Date: 06/2003
Version: 3.82
This document describes feature and performance topics not covered in the current release of the IBM Informix ODBC Driver Programmer's Manual.
Additionally, you may want to look at some of the documentation notes for manuals that are distributed with your Informix database server. These notes include information about the following products and features that might affect your client application:
To see these documentation notes, look in one of the following database server directories. If you need information about these directories, contact your DBA.
Platform | Directory for Documentation Notes |
---|---|
UNIX | $INFORMIXDIR/release/en_us/0333 |
Windows | %INFORMIXDIR%\release\en_us\04e4 |
IBM Informix Dynamic Server, Version 9.40 server has extended the implementation of the LVARCHAR data type. The maximum size of LVARCHAR is 32K. You can specify the length in a subscript while creating LVARCHAR columns.
When connecting to IDS 9.40 servers using the ODBC 3.82 driver, the SQLDescribeCol, SQLColAttributes & SQLDescribeParam APIs report the length mentioned during creation of the LVARCHAR column. If no length was mentioned during creation, length defaults to 2048 bytes.
While using Visual Basic clientside cursors to perform rowset update related operations using CHAR or LVARCHAR columns with lengths >= 16385, the IBM Informix ODBC Driver may return an error.
Visual Basic sends the SQL datatype to SQLBindParameter as SQL_LONGVARCHAR instead of SQL_VARCHAR when the length is >= 16385. IBM Informix ODBC driver maps SQL_LONGVARCHAR to TEXT data type. Thererfore, applications might see the error: "[Informix][Informix ODBC Driver]No cast from text to lvarchar" or "[Informix][Informix ODBC Driver]Illegal attempt to use Text/Byte host variable."
IBM Informix Dynamic Server, Version 9.4 supports PAM authentication. PAM allows client/server connections to use enhanced authentication mechanisms provided by some operating systems. To use PAM authentication, the application must register a callback function with the driver.
SQLSetConnectAttr()
Use the SQLSetConnectAttr() function to specify the callback function used by the server. SQLSetConnectAttr() is also used to specify what parameters are used by the callback function. Parameter attributes are passed back to the callback function exactly as they are specified to the driver.
The following attributes are IBM Informix-specific extensions to the ODBC standard:
Parameter | Type | Description |
SQL_INFX_ATTR_PAM_FUNCTION | void * | A pointer to the call back function. It's prototype is:
void (* pamCallback) (int msgStyle, void *responseBuf, int responseBufLen, int *responsePtrLen, void *challengeBuf, int challengeBufLen, int *challengePtrLen) |
SQL_INFX_ATTR_PAM_RESPONSE_BUF | void * | A generic pointer to a buffer containing the response to an authentication challenge |
SQL_INFX_ATTR_PAM_RESPONSE_LEN | int | The length of the response buffer in bytes |
SQL_INFX_ATTR_PAM_RESPONSE_LEN_PTR | int * | The address which stores the number of bytes in the response |
SQL_INFX_ATTR_PAM_CHALLENGE_BUF | void * | A generic pointer to a buffer containing the authentication challenge. The driver stores any challenge received from the server into this buffer. If the buffer is not large enought to contain the challenge, the challenge is truncated. The callback function can detect this by comparing the buffer length with the number of bytes in the challenge. It is up to the application developer to detect this situation and handle it correctly. |
SQL_INFX_ATTR_PAM_CHALLENGE_BUF_LEN | int | The length of the challenge buffer in bytes |
SQL_INFX_ATTR_PAM_CHALLENGE_LEN_PTR | int * | The address which stores the number of bytes in the challenge |
The challenge and response buffer pointers can be null. If the PAM server requires the information that would be stored in these buffers, a connection failure results due to a PAM authentication failure. The challenge length information will be returned whether the connection is successful or not. If the message type does not require a response, the response buffer may be null (default) or it may contain an empty string.
The attributes above can be set at any time and in any order. However, they will only be valid for connections established with subsequent calls to one of the driver's connect functions.
Connection Pooling
An application programmer must be aware of the effects of connection pooling when using PAM. In ODBC, the driver manager controls connection pooling. The driver does not control when its connections are placed in the pool or when a connection is pulled from the pool. If the application connects and disconnects without the user's knowledge, the performance benefits of connection pooling will be maintained and the user will not receive any unexpected PAM challenges. If the application does make the user aware they are reestablishing a connection, there will still be no PAM challenge because the connection between the driver manager and the server was never closed. For more information on connection pooling refer to the Microsoft Data Access SDK documentation.
Connect Functions
Any ODBC function which establishes a connection, SQLConnect(), SQLDriverConnect(), or SQLBrowseConnect(), can be used with PAM. Consider the following when using these functions:
SQLDriverConnect()
The DriverCompletion parameter to the SQLDriverConnect() function can take the following values
If an authentication challenge is expected, it is recommended that you use SQL_DRIVER_NOPROMPT. Using other values may result in the user being presented with multiple requests for authentication information.
SQLBrowseConnect()
SQLBrowseConnect() is designed to be used iteratively where the driver provides guidance to the application on how to complete the connection string and the application prompts the user for the required values. This can create situations where the user is presented with multiple prompts between connection string completion and PAM authentication.
Additionally, it is typical for the driver to present a choice of databases to the application as part of the connection string completion process. However, the driver is not able to query the server for a list of databases until after the user is authenticated. Depending on application logic, whether or not it provides a database name in the original connection string, and whether or not a challenge is going to be received from the PAM server, it may not be possible to use SQLBrowseConnect() when the server is PAM enabled.
Using 3rd Party Applications or Intermediate Code
When using PAM, it is the responsibility of the application to handle any challenges that originate from the PAM server. To do this, the application programmer must be able to register a callback function with the driver. Since there are no attributes defined in the ODBC standard that are used to accomplish this, the attributes used are IBM Informix extensions.
Many applications are written using Microsoft's ADO layer to abstract the ODBC calls from the developer. Most Visual Basic applications are written using ADO objects. These applications and 3rd party applications in general will not be aware of the IBM Informix extensions and will not be able to handle a PAM challenge.
The ODBC Data Source Administrator on Windows also falls under the class of 3rd party applications. Not all features will be available when configuring a data source. For example, the "Apply and Test Connection" button and the "Use Server Database Locale" toggle will not work if a challenge is received because those features require the ability to connect to the server.
On page 2-10, the the default for the fetchbuffer_size keyword is incorrect. It should be 32767 instead of 4096.
On page 2-19, the Fetch Buffer Size listed is incorrect. It should be 32767 instead of 4096.