Call Level Interface Guide and Reference

SQLDriverConnect - (Expanded) Connect to a Data Source

Purpose

Specification: DB2 CLI 2.1 ODBC 1.0

SQLDriverConnect() is an alternative to SQLConnect(). Both functions establish a connection to the target database, but SQLDriverConnect() supports additional connection parameters and the ability to prompt the user for connection information.

Use SQLDriverConnect() when the data source requires parameters other than the 3 input arguments supported by SQLConnect() (data source name, user ID and password), or when you want to use DB2 CLI's graphical user interface to prompt the user for mandatory connection information.

Once a connection is established, the completed connection string is returned. Applications can store this string for future connection requests.

Syntax

Generic

SQLRETURN   SQLDriverConnect (
                SQLHDBC           ConnectionHandle,  /* hdbc */
                SQLHWND           WindowHandle,      /* hwnd */
                SQLCHAR      *FAR InConnectionString, /* szConnStrIn */
                SQLSMALLINT       StringLength1,     /* cbConnStrIn */
                SQLCHAR      *FAR OutConnectionString,/* szConnStrOut */
                SQLSMALLINT       BufferLength,      /* cbConnStrOutMax */
                SQLSMALLINT  *FAR StringLength2Ptr,   /* pcbConnStrOut */
                SQLUSMALLINT      DriverCompletion); /* fDriverCompletion */

Function Arguments

Table 52. SQLDriverConnect Arguments

Data Type Argument Use Description
SQLHDBC ConnectionHandle input Connection handle
SQLHWND hwindow input Window handle (platform dependent): on Windows, this is the parent Windows handle. On OS/2, this is the parent PM window handle. On AIX, this is the parent MOTIF Widget window handle.
If a NULL is passed, then no dialog will be presented.
SQLCHAR * InConnectionString input A full, partial or empty (null pointer) connection string (see syntax and description below).
SQLSMALLINT StringLength1 input Length of InConnectionString.
SQLCHAR * OutConnectionString output Pointer to buffer for the completed connection string.
If the connection was established successfully, this buffer will contain the completed connection string. Applications should allocate at least SQL_MAX_OPTION_STRING_LENGTH bytes for this buffer.
SQLSMALLINT BufferLength input Maximum size of the buffer pointed to by OutConnectionString.

SQLCHAR * StringLength2Ptr output Pointer to the number of bytes available to return in the OutConnectionString buffer.
If the value of StringLength2Ptr is greater than or equal to BufferLength, the completed connection string in OutConnectionString is truncated to BufferLength - 1 bytes.
SQLUSMALLINT DriverCompletion input Indicates when DB2 CLI should prompt the user for more information.
Possible values:

SQL_DRIVER_PROMPT
SQL_DRIVER_COMPLETE
SQL_DRIVER_COMPLETE_REQUIRED
SQL_DRIVER_NOPROMPT

Data Type	Argument	Use	Description
SQLHDBC	`ConnectionHandle`	input	Connection handle
SQLHWND	`hwindow`	input	Window handle (platform dependent): on Windows, this is the parent Windows handle. On OS/2, this is the parent PM window handle. On AIX, this is the parent MOTIF Widget window handle. If a NULL is passed, then no dialog will be presented.
SQLCHAR *	`InConnectionString`	input	A full, partial or empty (null pointer) connection string (see syntax and description below).
SQLSMALLINT	`StringLength1`	input	Length of `InConnectionString`.
SQLCHAR *	`OutConnectionString`	output	Pointer to buffer for the completed connection string. If the connection was established successfully, this buffer will contain the completed connection string. Applications should allocate at least SQL_MAX_OPTION_STRING_LENGTH bytes for this buffer.
SQLSMALLINT	`BufferLength`	input	Maximum size of the buffer pointed to by `OutConnectionString`.
SQLCHAR *	`StringLength2Ptr`	output	Pointer to the number of bytes available to return in the `OutConnectionString` buffer. If the value of `StringLength2Ptr` is greater than or equal to `BufferLength`, the completed connection string in `OutConnectionString` is truncated to `BufferLength` - 1 bytes.
SQLUSMALLINT	`DriverCompletion`	input	Indicates when DB2 CLI should prompt the user for more information. Possible values: SQL_DRIVER_PROMPT SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED SQL_DRIVER_NOPROMPT

Usage

The connection string is used to pass one or more values needed to complete a connection. The contents of the connection string and the value of DriverCompletion will determine if DB2 CLI needs to establish a dialog with the user.

   .-;----------------------------------------------.
   V                                                |
>>-----+-DSN---------------------+--=--attribute----+----------><
       +-UID---------------------+
       +-PWD---------------------+
       +-NEWPWD------------------+
       '-DB2 CLI-defined-keyword-'

Each keyword above has an attribute that is equal to the following:

DSN: Data source name. The name or alias-name of the database. Required if DriverCompletion is equal to SQL_DRIVER_NOPROMPT.
UID: Authorization-name (user identifier).
PWD: The password corresponding to the authorization name. If there is no password for the user ID, an empty value is specified (PWD=;).
NEWPWD: New password used as part of a change password request. The application can either specify the new string to use, for example, NEWPWD=anewpass; or specify NEWPWD=; and rely on a dialog box generated by the DB2 CLI driver to prompt for the new password (set the DriverCompletion argument to anything other than SQL_DRIVER_NOPROMPT).

The list of DB2 CLI defined keywords and their associated attribute values are discussed in Configuration Keywords. Any one of the keywords in that section can be specified on the connection string. If any keywords are repeated in the connection string, the value associated with the first occurrence of the keyword is used.

If any keywords exists in the CLI initialization file, the keywords and their respective values are used to augment the information passed to DB2 CLI in the connection string. If the information in the CLI initialization file contradicts information in the connection string, the values in connection string take precedence.

If the end user Cancels a dialog box presented, SQL_NO_DATA_FOUND is returned.

The following values of DriverCompletion determines when a dialog will be opened:

SQL_DRIVER_PROMPT:: A dialog is always initiated. The information from the connection string and the CLI initialization file are used as initial values, to be supplemented by data input via the dialog box.
SQL_DRIVER_COMPLETE:: A dialog is only initiated if there is insufficient information in the connection string. The information from the connection string is used as initial values, to be supplemented by data entered via the dialog box.
SQL_DRIVER_COMPLETE_REQUIRED:: A dialog is only initiated if there is insufficient information in the connection string. The information from the connection string is used as initial values. Only mandatory information is requested. The user is prompted for required information only.
SQL_DRIVER_NOPROMPT:: The user is not prompted for any information. A connection is attempted with the information contained in the connection string. If there is not enough information, SQL_ERROR is returned.

Once a connection is established, the complete connection string is returned. Applications that need to set up multiple connections to the same database for a given user ID should store this output connection string. This string can then be used as the input connection string value on future SQLDriverConnect() calls.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR

Diagnostics

All of the diagnostics generated by SQLConnect - Connect to a Data Source can be returned here as well. The following table shows the additional diagnostics that can be returned.

Table 53. SQLDriverConnect SQLSTATEs

SQLSTATE Description Explanation
01004 Data truncated. The buffer szConnstrOut was not large enough to hold the entire connection string. The argument StringLength2Ptr contains the actual length of the connection string available for return. (Function returns SQL_SUCCESS_WITH_INFO)
01S00 Invalid connection string attribute. An invalid keyword or attribute value was specified in the input connection string, but the connection to the data source was successful anyway because one of the following occurred:

The unrecognized keyword was ignored.
The invalid attribute value was ignored, the default value was used instead.

(Function returns SQL_SUCCESS_WITH_INFO)
HY000 General error.
Dialog Failed
The information specified in the connection string was insufficient for making a connect request, but the dialog was prohibited by setting fCompletion to SQL_DRIVER_NOPROMPT.
The attempt to display the dialog failed.
HY090 Invalid string or buffer length. The value specified for StringLength1 was less than 0, but not equal to SQL_NTS.
The value specified for BufferLength was less than 0.
HY110 Invalid driver completion. The value specified for the argument fCompletion was not equal to one of the valid values.

SQLSTATE	Description	Explanation
01004	Data truncated.	The buffer `szConnstrOut` was not large enough to hold the entire connection string. The argument `StringLength2Ptr` contains the actual length of the connection string available for return. (Function returns SQL_SUCCESS_WITH_INFO)
01S00	Invalid connection string attribute.	An invalid keyword or attribute value was specified in the input connection string, but the connection to the data source was successful anyway because one of the following occurred: The unrecognized keyword was ignored. The invalid attribute value was ignored, the default value was used instead. (Function returns SQL_SUCCESS_WITH_INFO)
HY000	General error. Dialog Failed	The information specified in the connection string was insufficient for making a connect request, but the dialog was prohibited by setting `fCompletion` to SQL_DRIVER_NOPROMPT. The attempt to display the dialog failed.
HY090	Invalid string or buffer length.	The value specified for `StringLength1` was less than 0, but not equal to SQL_NTS. The value specified for `BufferLength` was less than 0.
HY110	Invalid driver completion.	The value specified for the argument `fCompletion` was not equal to one of the valid values.

Restrictions

None.

Example

(The complete sample dbconn.c is also available here .)

 
/* From the CLI sample DBCONN.C */
/* ... */
 
    sqlrc = SQLDriverConnect(hdbc,
                             (SQLHWND) NULL,
                             connStr,
                             SQL_NTS,
                             NULL, 0, NULL,
                             SQL_DRIVER_NOPROMPT);

References

[ Top of Page | Previous Page | Next Page ]