The Easysoft ODBC-DB2 Driver is installed on the computer where your applications are running. ODBC applications access ODBC drivers through the ODBC Driver Manager and a data source. The data source tells the Driver Manager which ODBC driver to load, which DB2 server to connect to and how to connect to it. This chapter describes how to create data sources, use DSN-less connections and configure the Easysoft ODBC-DB2 Driver.
Before setting up a data source, you must have successfully installed the Easysoft ODBC-DB2 Driver.
For Easysoft ODBC-DB2 Driver installation instructions, see Installation.
This section describes how to configure the Easysoft ODBC-DB2 Driver to connect to a DB2 database by using a data source or a DSN-less connection string. The section assumes you are, or are able to consult with, a database administrator.
Refer to the section relevant to your platform to continue:
There are two ways to set up a data source to your DB2 data:
By default, the Easysoft ODBC-DB2 Driver installation creates a SYSTEM data source named [DB2_SAMPLE]. If you are using the unixODBC included in the Easysoft ODBC-DB2 Driver distribution, the SYSTEM odbc.ini file is in /etc.
If you built unixODBC yourself, or installed it from some other source, SYSTEM data sources are stored in the path specified with the configure option --sysconfdir=directory. If sysconfdir was not specified when unixODBC was configured and built, it defaults to /usr/local/etc.
If you accepted the default choices when installing the Easysoft ODBC-DB2 Driver, USER data sources must be created and edited in $HOME/.odbc.ini.
|
To display the directory where unixODBC stores SYSTEM and USER data sources, type odbcinst -j. By default, you must be logged in as root to edit a SYSTEM data source defined in /etc/odbc.ini. |
You can either edit the sample data source or create new data sources.
Each section of the odbc.ini file starts with a data source name in square brackets [ ] followed by a number of attribute=value pairs.
The Driver attribute identifies the ODBC driver in the odbcinst.ini file to use for a data source.
When the Easysoft ODBC-DB2 Driver is installed into unixODBC, it places an Easysoft ODBC-DB2 entry in odbcinst.ini. For Easysoft ODBC-DB2 Driver data sources therefore, you need to include a Driver = Easysoft ODBC-DB2 entry.
To configure a DB2 data source, in your odbc.ini file, you need to specify:
The Easysoft ODBC-DB2 Driver must be able to find the following shared objects, which are installed during the Easysoft ODBC-DB2 Driver installation:
By default, this is located in /usr/local/easysoft/unixODBC/lib.
By default, this is located in /usr/local/easysoft/lib.
By default, this is located in /usr/local/easysoft/lib.
You may need to set and export LD_LIBRARY_PATH, SHLIB_PATH or LIBPATH (depending on your operating system and run-time linker) to include the directories where libodbcinst.so, libeslicshr.so and libessupp.so are located.
|
The shared object file extension (.so) may vary depending on the operating system (.so, .a or .sl). |
The isql query tool lets you test your Easysoft ODBC-DB2 Driver data sources.
To test the Easysoft ODBC-DB2 Driver connection
1. Change directory into /usr/local/easysoft/unixODBC/bin.
2. Type ./isql.sh -v data_source, where data_source is the name of the target data source.
3. At the prompt, type an SQL query. For example:
Type help to return a list of tables:
To connect an ODBC application on a Windows machine to a DB2 database:
1. Open ODBC Data Source Administrator:
The ODBC Data Source Administrator dialog box is displayed:
2. Select the User DSN tab to set up a data source that only you can access.
Select the System DSN tab to create a data source which is available to anyone who logs on to this Windows machine.
3. Click Add... to add a new data source.
The Create New Data Source dialog box displays a list of drivers:
4. Select Easysoft ODBC-DB2 Driver and click Finish.
The Easysoft ODBC-DB2 Driver DSN Setup dialog box is displayed:
For details of the other attributes that can be set on this dialog box, see Attribute Fields.
This section lists the attributes which can be set for the Easysoft ODBC-DB2 Driver in a table showing:
Attributes which are text fields are displayed as value.
Attributes which are logical fields can contain either 0 (to set to off) or 1 (to set to on) and are displayed as "0|1".
If an attribute can contain one of several specific values then each possible entry is displayed and separated by a pipe symbol.
For example, in the statement:
the value entered may be "1", "2" or "3".
The name of the User or System data source to be created, as used by the application when calling the SQLConnect or SQLDriverConnect functions.
Descriptive text that may be retrieved by certain applications to describe the data source.
The database to to connect to. For example, to connect to the DB2 SAMPLE database set the Database attribute value to SAMPLE.
The operating system user name to use when connecting to DB2. You must specify a name of a user who has access to the machine on which DB2 is running.
To specify the user name in the connection string, use UID rather than User. For more information about specifying Easysoft ODBC-DB2 Driver attributes in the connection string, see DSN-less Connections.
The password for the user name.
To specify the password in the connection string, use PWD rather than Password.
The host name or IP address of the machine on which the DB2 instance is running.
If your DB2 database is available on more than one DB2 machine, you can define a primary server for the database and additional fallback database servers. By default, the Easysoft ODBC-DB2 Driver will try to connect to the first server that you specify. If that server is unavailable, the Easysoft ODBC-DB2 Driver will try to connect to the next server in the list and so on. Use the format:
Server = primaryserver[:port] [, fallbackserver[:port]...]
Server = db2hostA,db2hostB,db2hostC:50001
Connection attempts continue until either a connection is successfully made or all the servers in the list have been tried once.
Note that authentication details (as specified by User and Password) needs to be valid on each DB2 machine in the list.
On Unix, if you want to balance the load between database servers, configure the driver to randomly choose the database server it connects to. To do this, set the ClientLB attribute to 1.
The TCP port that the DB2 instance is listening on.
If you are connecting to a default instance that is listening on port 50000, the Port setting can be omitted.
Set IPv6 to 1 when connecting to a DB2 instance that is listening on an IPv6 address.
By default, IPv6 is OFF (set to 0), which means that the Easysoft ODBC-DB2 Driver assumes that the target DB2 instance is listening on an IPv4 address.
Whether the Easysoft ODBC-DB2 Driver requests an encrypted connection to DB2.
The encryption algorithm to use when encrypting the user name and password. When ON (set to 1), the Easysoft ODBC-DB2 Driver encrypts the user name and password by using an Advanced Encryption Standard (AES) encryption algorithm. Otherwise, the Easysoft ODBC-DB2 Driver encrypts the user name and password by using a Data Encryption Standard (DES) encryption algorithm.
By default, Use AES is OFF (set to 0).
The private key for use with the SSL session.
The file that contains the public key certificate of the CA that signed the DB2 certificate. The CA certificate file must be in base-64 PEM format.
If the CA certificate is not installed on your client machine, you need to export the certificate on the DB2 machine and install it on the client.
The cypher suite that the Easysoft ODBC-DB2 Driver will request during the SSL handshake with the DB2 machine.
A cypher suite is a set of authentication, encryption, and data integrity algorithms used to protect data exchanged between machines. During the SSL handshake part of the connection process, the SSL layer in the ODBC driver and the Schannel layer on the DB2 machine negotiate to decide which cipher suite they will use.
To see which cypher suite is being used for a particular connection, enable Easysoft ODBC-DB2 Driver logging.
Connect and then examine the driver log file. Look for a log file entry similar to:
SSL using cypher 'RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5'
This entry shows that the ODBC driver and the DB2 machine negotiated the following cryptographic protection for the connection:
(You can also display the cryptographic settings negotiated during the SSL handshake by enabling Schannel logging. Enable the "Log informational and success events" Schannel logging option to write this information to the Windows Event Viewer logs. For information about how to do this, see http://support.microsoft.com/kb/260729.)
Use the Cypher setting, if you want to request a different encryption or data integrity algorithm to the ones negotiated during the SSL handshake. For example:
If you specify a cypher suite that is not available on the server machine, the Easysoft ODBC-DB2 Driver returns the error "Required SSL (failed to receive packet)".
If you specify a cypher suite that the Easysoft ODBC-DB2 Driver does not recognise, the driver returns the error "SSL3_CLIENT_HELLO:no ciphers available".
Whether the Easysoft ODBC-DB2 Driver tries to validate the server certificate to verify the identity of the DB2 machine. Set Trust Cert to Yes if your DB2 machine is using a self-signed SSL certificate.
Whether the Easysoft ODBC-DB2 Driver tries to balance the load between the servers specified by the Server setting. The ClientLB setting only has an effect if you specify a primary server and additional fallback servers with Server.
When ClientLB is ON (set to 1), the Easysoft ODBC-DB2 Driver randomly selects a server to connect to. If the server is unavailable, the Easysoft ODBC-DB2 Driver then moves sequentially through the list of other servers.
When ClientLB OFF (set to 0, the default), the Easysoft ODBC-DB2 Driver tries to connect to the servers in the order that they are defined in. (Primary server first and then each additional fallback server.)
You specify a primary server (db2hostA) and two fallback servers (db2hostB and db2hostC):
Server = db2hostA,db2hostB,db2hostC:1583
When ClientLB is ON, the Easysoft ODBC-DB2 Driver will randomly choose a server to connect to. If, for example, the driver tries to connect to db2hostB first, it will then try to connect to db2hostC (if db2hostB is unavailable) and db2hostA (if sqlsrvhostC is unavailable).
When ClientLB is OFF, the Easysoft driver will try to connect to db2hostA and then db2hostB (if db2hostA is unavailable) and finally db2hostC (if db2hostB is unavailable).
The size of the receive buffer for the socket in bytes. Possible values for num are:
0, do not set the receive buffer size, use the system default value.
n, where n is a number greater than 0, set the receive buffer to the specified size by passing n to the setsockopt() function .
By default, the system default receive buffer size is used.
The precision to use when converting SQL_DOUBLE data in a result set to a string
If an application specifies a string as the target type for non-character data in a SQLBindCol or SQLGetData call, the Easysoft ODBC-DB2 Driver converts the data to the target type. Use the DPrec attribute to specify the precision to use when the driver does this conversion for SQL_DOUBLE data.
The precision to use when converting SQL_FLOAT data in a result set to a string
If your application specifies a string as the target type for non-character data in a SQLBindCol or SQLGetData call, the Easysoft ODBC-DB2 Driver converts the data to the target type. Use the FPrec attribute to specify the precision to use when the driver does this conversion for SQL_FLOAT data.
Use LimitVarchar to restrict the size returned by the Easysoft ODBC-DB2 Driver when describing VARCHAR data.
The locale on the Easysoft ODBC-DB2 Driver machine.
If you do not set the Locale attribute, the Easysoft ODBC-DB2 Driver will use the value set for the LC_CTYPE environment variable. If LC_CTYPE, is not set, the Easysoft ODBC-DB2 Driver will use the value set for the LANG environment variable. If neither LC_CTYPE nor LANG are set, the Easysoft ODBC-DB2 Driver will set the locale value to C.
When ON (set to 1), the Easysoft ODBC-DB2 Driver converts strings passed to Unicode ODBC calls (with suffix "W") to UTF-8. The Easysoft ODBC-DB2 Driver also converts metadata and result sets returned by Unicode ODBC calls to UTF-8.
By default, ConvWToUtf is OFF (set to 0).
Controls how single bytes in a string are converted to Unicode. When ON (set to 1), UTF-8 sequences are regarded as single Unicode values. Otherwise, UTF-8 sequences are regarded as individual 8-bit values.
For example, setting SbUTF8 controls whether a UTF-8 Euro symbol (0xE2 0x82 0xAC) converts to 0x20AC (single character) or 0x00E2, 0x0082, 0x00AC (three characters).
By default, SbUTF8 is OFF (set to 0).
The Easysoft ODBC-DB2 Driver uses libgssapi_krb5.so, the Kerberos GSS-API library, to request service tickets for accessing DB2 instances. If the Easysoft ODBC-DB2 Driver is unable to open this library, the connection will fail with the error:
Krb5: failed to open gss lib (libgssapi_krb5.so)
If the Kerberos GSS-API library is not called libgssapi_krb5.so in your GSS-API distribution, use the GSSLIB attribute in your data source to specify the alternative GSS-API library. For example:
GSSLIB = /opt/extension/lib/libgssapi.so
The Easysoft ODBC-DB2 Driver allows you to pass req_flags to the gss_init_sec_context() function, which is used to initiate a security context for the driver. The Key Distribution Center (KDC) uses this security context to verify the identity of the client. To pass req_flags to gss_init_sec_context(), use the GSSFLAG attribute:
where req_flags is a bitmask specifying the requested GSS services. To look up the available bitmask values, refer to the gssapi.h header file for the GSS-API distribution on the Easysoft ODBC-DB2 Driver machine. The driver default GSSFLAG value is 4, which sets the GSS_C_REPLAY_FLAG flag.
As an example, to request credential delegation, set the GSS_C_DELEG_FLAG flag by including this entry in your data source GSSFLAG = 1.
When ON (set to 1) the Easysoft ODBC-DB2 Driver does not send the database name (the DDM_RDBNAM parameter) in the DRDA authentication message. By default, SingleDB is OFF (set to 0).
In addition to using a data source, you can also connect to a database by using a DSN-less connection string of the form:
SQLDriverConnect(..."DRIVER={Easysoft ODBC-DB2};
Server=server;UID=user;PWD=password;
where server is the host name or IP address of the machine on which the DB2 instance is running, user and password are a valid operating system user name and password and database is the DB2 database you want to connect to. You need to use the Easysoft ODBC-DB2 DRIVER keyword to identify the Easysoft ODBC-DB2 Driver.
Other Easysoft ODBC-DB2 Driver attribute settings, as described in Setting Up Data Sources on Unix, can be added to the connection string using the same PARAMETER=value; format. For example, the following connection string connects to a DB2 instance that is listening on a non-standard port:
"DRIVER={Easysoft ODBC-DB2};Server=myhost;UID=myuser;PWD=mypassword;Database=SAMPLE;Port=50001"
© 1993 - 2024 Easysoft Limited. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other trademarks and registered trademarks appearing on easysoft.com are the property of their respective owners.
