NAME

UnixODBC::DriverConf - Properties for UnixODBC drivers.

SYNOPSIS

    use UnixODBC qw(:all);
    use UnixODBC::DriverConf qw(:all);


    # Object-oriented Interface

    my $self = new UnixODBC::DriverConf;

    $self -> ConstructProperties ($driver);

    # Methods for accessing properties
    $self -> Values;
    $self -> Help;
    $self -> PromptType;
    $self -> PromptData;

    # Configuration Modes
    $self -> SQLSetConfigMode ($mode);
    $mode = $self -> SQLGetConfigMode ();

    my @drivers = $self -> SQLGetInstalledDrivers ();
    my @drivers = $self -> SQLGetAvailableDrivers ();

    $r = $self -> SQLValidDSN ($dsn);

    $confpath = $self -> odbcinst_system_file_path ();

    $s = $self -> GetProfileString ($section, $keyword, $filename);
    $self -> WriteProfileString ($section, $newprofilestring, $filename);

    @dsn = $self -> GetDSN ($name, $filename);
    $self -> WriteDSN (\@template, $filename);
    

    # Procedural Interface

    my @drivers = SQLGetInstalledDrivers ();
    # Synonym for SQLGetInstalledDrivers ();
    my @drivers = SQLGetAvailableDrivers ();

    $r = SQLValidDSN ($dsn);

    $confpath = odbcinst_system_file_path ();
    @dsn = GetDSN ($name, $filename);
    WriteDSN (\@template, $filename);

DESCRIPTION

UnixODBC::DriverConf extracts and accesses properties of driver-specific libraries, and provides procedural interfaces for libodbcinst's configuration functions.

UnixODBC Configuration

Each ODBC-accessible DBMS has an ODBC driver defined for it. The file odbcinst.ini contains site-specific values for each property. Properties and their values depend on the DBMS server's Application Programming Interface.

Each ODBC accessible database must have a Data Source Name defined for it. DSNs are contained in the file, odbc.ini. Each DSN specifies driver and configuration libraries, a database name, and the host name. Additional values depend on the properties defined by the driver library.

The function, odbcinst_system_file_path (), returns the directory of odbcinst.ini and odbc.ini.

ConstructProperties () retrieves driver properties. The methods, Values (), Help (), PromptType (), and PromptData (), return the each property's value, documentation string, prompt type, and prompt data.

This program lists the properties of a PostgreSQL driver and their values.

  use UnixODBC qw(:all);
  use UnixODBC::DriverConf qw(:all);

  my $self = new UnixODBC::DriverConf;
  $self -> ConstructProperties ('PostgreSQL 7.x');

  foreach (keys %{$self -> Values}) { print "$_ = ". 
                 $self -> Values -> {$_} . "\n"; }

This is the program's output.

   Description = PostgreSQL 7.x
   TraceFile = 
   Password = 
   Protocol = 6.4
   Name = 
   Servername = localhost
   Driver = PostgreSQL 7.x
   Trace = No
   ShowOidColumn = No
   ShowSystemTables = No
   Database = 
   Port = 5432
   FakeOidIndex = No
   Username = 
   RowVersioning = No
   ReadOnly = No
   ConnSettings = 

DSN and driver section headings in odbc.ini and odbcinst.ini are delimited by brackets. An example odbcinst.ini section for a MySQL-MyODBC Driver is given below.

  [MySQL 3.23.49]
  Description   = MySQL-MyODBC Sample - Edit for your system.
  Driver        = /usr/local/lib/libmyodbc3-3.51.02.so
  Setup         = /usr/local/lib/libodbcmyS.so.1.0.0
  FileUsage     = 1
  CPTimeout     = 
  CPReuse       = 

A DSN named definition that uses the driver is shown here.

  [Contacts]
  Description   = Names and Addresses Sample - Edit for your system.
  Driver        = MySQL 3.23.49
  Server        = localhost
  Port          = 3396
  Socket        = /tmp/mysql.sock
  Database      = Contacts

An odbc.ini entry for a DSN that defines values the PostgreSQL driver library properties is shown here.

  [Postgresql]
  Description           = Sample DSN - Edit for your system.
  Driver                = PostgreSQL 7.x
  Trace                 = No
  TraceFile             = 
  Database              = gutenberg
  Servername            = localhost
  Username              = postgres
  Password              = postgres
  Port                  = 5432
  Protocol              = 6.4
  ReadOnly              = No
  RowVersioning         = No
  ShowSystemTables      = No
  ShowOidColumn         = No
  FakeOidIndex          = No
  ConnSettings          = 
  Server                = localhost

FUNCTIONS

ConstructProperties (driver)

Retrieve the driver properties. This method is not automatically called by new ().

  $self -> ConstructProperties ($driver);

GetDSN (dsn, filename)

Returns a list of the template of dsn from filename.

    my @dsn = $self -> GetDSN ('mydsn', '/usr/local/etc/odbc.ini');

GetProfileString (section, keyword, conffile)

Return a profile string.

  $s = $self -> GetProfileString ($driver, $keyword, $conffile);

Help ()

Return a hash of properties' documentation strings, if any.

    %docs = $self -> Help;

new ()

UnixODBC::DriverConf constructor.

  my $self = new UnixODBC::DriverConf;

PromptData ()

Return default values for each property, if any. Each value is separated by a newline ("\n");

  # Default values for "Protocol" property.
  my %promptdefaults = $self -> PromptData;
  foreach (split "\n", $prompromptdefaults{Protocol}) { print "$_\n"; }

PromptType ()

Return type of each prompt. The type can be

  $ODBCINST_PROMPTTYPE_LABEL 
  $ODBCINST_PROMPTTYPE_TEXTEDIT
  $ODBCINST_PROMPTTYPE_LISTBOX 
  $ODBCINST_PROMPTTYPE_COMBOBOX
  $ODBCINST_PROMPTTYPE_FILENAME 
  $ODBCINST_PROMPTTYPE_HIDDEN

  $self -> PromptType;

SQLGetAvailableDrivers ()

A synonym for "SQLGetInstalledDrivers ()".

SQLGetConfigMode ()

  Return the libodbcinst configuration mode.  Mode may be one of:

  $ODBC_BOTH_DSN
  $ODBC_USER_DSN
  $ODBC_SYSTEM_DSN

  $mode = $self -> SQLGetConfigMode; 

SQLGetInstalledDrivers ()

Returns a list of installed drivers.

  # List the installed ODBC drivers
  my @drivers = SQLGetInstalledDrivers ();
  foreach (@drivers) {print "$_\n";}

SQLSetConfigMode (mode)

Set the UnixODBC configuration mode. The parameter may be one of:

  $ODBC_BOTH_DSN
  $ODBC_USER_DSN
  $ODBC_SYSTEM_DSN

SQLValidDSN (dsnname)

Returns true if dsnname has a length > 0 and does not contain the following characters: '[', ']', '{', '}', '(', ')', ',', ';', '?', '*', '=', '!', '@', or '\'. Returns false otherwise.

odbcinst_system_file_path ();

Return the directory name of the unixODBC configuration files.

WriteProfileString (section, newprofilestring, conffile)

Write a profile string to conffile.

  $self -> WriteProfileString ($section, $newprofilestring, $conffile);

Values ()

Return a hash of values for each property.

  %values = $self -> Values;

WriteDSN (templateref, filename)

Writes the template array reference templateref to filename.

  my $template = ['[MyDSN]', 
                  'prop1 = val1',
                  'prop2 = val2',
                  'prop3 = val3'];

  $self -> WriteDSN ($template, '/usr/local/etc/odbc.ini');

EXPORTS

See @EXPORT_OK in UnixODBC::DriverConf.pm.

VERSION

Version 0.02

COPYRIGHT

Copyright © 2004-2005, 2008 Robert Kiesling, rkies@cpan.org.

Licensed under the same terms as Perl. Refer to the file, "Artistic," for details.

SEE ALSO

UnixODBC(3)

cpanm UnixODBC

perl -MCPAN -e shell
install UnixODBC