DOCUMENTATION NOTES FOR

IBM INFORMIX ODBC Driver Programmer's Manual

Date: 06/2003

Version: 3.82


Table of Contents

I. Overview
II. Changes to the Manual
III.Corrections to the Manual


I. Overview

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


II. Additions to the Manual

Greater Than 2k LVARCHAR Implementation

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.

Using Visual Basic Client-side Cursors

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."

Pluggable Authentication Module (PAM)

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.


III. Corrections to the Manual

Connection String Attributes

On page 2-26 of the manual, the connection string attributes listed in the table are incorrectly implied to be specific to DSN-less connections. You can use any of these attribute names in a connection string with the DSN or DRIVER keywords.

Fetch Buffer Size

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.



© Copyright International Business Machines Corporation 2003. All rights reserved.
US Government User Restricted Rights—Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.