DB2 10.5 for Linux, UNIX, and Windows

SQLDriverConnect function (CLI) - Connect to a data source

Establishes a connection to a target database. The SQLDriverConnect() function supports connection strings and the ability to prompt the user for connection information.

Specification:

CLI 2.1
ODBC 1.0

The SQLDriverConnect() function is an alternative to the SQLConnect() function. You can use the SQLDriverConnect() function when the data source requires more than the three parameters that are supported by the SQLConnect() function (data source name, user ID, and password) or when you require the CLI driver to prompt the user for required connection information.

A complete connection string is returned in plain text only after a connection is successful. You can code your application to store the returned connection string for subsequent connection requests.

Syntax

SQLRETURN  SQLDriverConnect (
        SQLHDBC       ConnectionHandle,               /* hdbc */
        SQLHWND       WindowHandle,                   /* hwnd */
        SQLCHAR       *InConnectionString,            /* szConnStrIn */
        SQLSMALLINT   InConnectionStringLength,       /* cbConnStrIn */
        SQLCHAR       *OutConnectionString,           /* szConnStrOut */
        SQLSMALLINT   OutConnectionStringCapacity,    /* cbConnStrOutMax */
        SQLSMALLINT   *OutConnectionStringLengthPtr,  /* pcbConnStrOut */
        SQLUSMALLINT  DriverCompletion);              /* fDriverCompletion */

Function arguments

Table 1. SQLDriverConnect function arguments
Data type	Argument	Use	Description
SQLHDBC	ConnectionHandle	Input	Connection handle.
SQLHWND	WindowHandle	Input	Window handle. The WindowHandle argument value is the parent Windows operating system handle. The window handle is supported only on Windows operating systems. If a NULL value is passed, no user prompt is presented.
SQLCHAR *	InConnectionString	Input	Connection string. See the usage section for details.
SQLSMALLINT	InConnectionStringLength	Input	Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) that are needed to store the connection string that is specified for the InConnectionString argument.
SQLSMALLINT *	OutConnectionString	Output	Pointer to a buffer for the completed connection string for a successful connection or the NULL value. For this buffer, applications must allocate at least the number of bytes that you specify for the predefined maximum length (SQL_MAX_OPTION_STRING_LENGTH).
SQLSMALLINT	OutConnectionString Capacity	Input	Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) that are needed to store the connection string that is returned through the buffer that is specified for the OutConnectionString argument.
SQLSMALLINT *	OutConnectionString LengthPtr	Output	Pointer to the number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, that is available to return in the buffer that is specified by the OutConnectionString argument. If the returned length value in the *OutConnectionStringLengthPtr argument is greater than or equal to the OutConnectionStringCapacity argument value, the completed connection string in the buffer that is specified by the OutConnectionString argument is truncated to OutConnectionStringCapacity - 1 SQLCHAR or SQLWCHAR elements.
SQLUSMALLINT	DriverCompletion	Input	Indicator of when the CLI driver prompts the user for more information. Possible values are as follows: SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED SQL_DRIVER_NOPROMPT SQL_DRIVER_PROMPT

Usage

Unicode equivalent: You can also use this function with the Unicode character set. The corresponding Unicode function is SQLDriverConnectW().

InConnectionString argument

The InConnectionString argument consists of a valid connection string. A connection string has the following syntax:


>>-"--+---------------------------------+--+-DSN--=--dsn_name--;----------------------+-->
      '-DRIVER--=--{--driver_name--}--;-'  '-DATABASE--=--+-database_name--------+--;-'   
                                                          '-database:server:port-'        

>--+-------------------------------------------------------------------------+-->
   '-UID--=--user_id--;--PWD--=--password--;--+----------------------------+-'   
                                              '-NEWPWD--=--new_password--;-'     

   .-;---------------------------------.         
   V                                   |         
>----CLI_keyword--=--CLI_keyword_value-+--;--"-----------------><

DRIVER=driver_name: Name of the database driver. You can obtain the name of the database driver with the SQLDrivers() function.
DSN=dsn_name: The name of the data source that you are connecting to. The DSN keyword value is required for a connection unless the DriverCompletion argument is equal to SQL_DRIVER_NOPROMPT or the DATABASE keyword value is specified.
DATABASE=database_name: The database identifier. The database name can consist of just the database name or can consist of the database name, server name, and port number. If you do not provide a server name and port number, the default values are used. The default server name is LOCALHOST and the default port number is 50000. The DATABASE keyword value is required for a connection unless the DriverCompletion argument is equal to SQL_DRIVER_NOPROMPT or the DSN keyword value is specified.
UID: A user ID that is specified for the connection authentication request.
PWD: The password that corresponds to the specified user ID.
NEWPWD: A new password that is used as part of a change password request. You can specify a new password in the connection string, or specify NEWPWD=; in the connection string for a new password prompt if you do not set the DriverCompletion argument to SQL_DRIVER_NOPROMPT.
CLI_keyword: A CLI configuration keyword that is used to configure the behavior of the CLI driver. If any CLI keywords are specified more than once in the connection string, the first occurrence of the keyword is used.

For connection string keywords (other than the PWD and NEWPWD keywords) and their values, avoid the use of the following characters:

Opening bracket ([)
Closing bracket (])
Opening brace ({)
Closing brace (})
Comma (,)
Semicolon (;)
Question mark (?)
Asterisk (*)
Equal sign (=)
Exclamation mark (!)
At sign (@)
Backslash (\)

The CLI driver supports special characters for the PWD and NEWPWD keywords, with limitations. See the "Password rules for drivers and CLPPlus" topic in the related reference for details.

OutConnectionString argument

The OutConnectionString argument can be a pointer to a buffer or the NULL value. If a pointer to a buffer is specified, the buffer is populated with the connection string upon a successful connection. Applications that require multiple connections to the same database for the same user ID can store this output connection string. The returned connection string can then be used as the input connection string value on future calls to the SQLDriverConnect() function. The NULL value causes the pointer that is specified for the OutConnectionString LengthPtr argument to return the number of characters in the connection string upon successful connection.

If any keywords exist in the CLI initialization file, the keywords and their values are used to augment the information that is passed to the CLI driver in the connection string. If the information in the CLI initialization file contradicts information in the connection string, the values in the connection string take precedence.

DriverCompletion argument

The following values of the DriverCompletion argument determine whether the CLI driver prompts the user for more information:

SQL_DRIVER_COMPLETE: A dialog is initiated only if there is insufficient information in the connection string. The information from the connection string is used as initial values and is supplemented by data that is entered when the user is prompted.
SQL_DRIVER_COMPLETE_REQUIRED: A dialog is initiated only if there is insufficient information in the connection string. The information from the connection string is used as initial values. 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 in the connection string. If there is not enough information, the SQL_ERROR message is returned.
SQL_DRIVER_PROMPT: A dialog is always initiated. The information from the connection string and the CLI initialization file is used as initial values.

After a connection is established, the complete connection string is returned. Applications that require multiple connections to the same database with the same user ID can store this output connection string. This string can then be used as the input connection string value on future SQLDriverConnect() calls.

Return codes

SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO

Diagnostics

The following table contains the diagnostic messages that the SQLDriverConnect() function can return:

Table 2. The SQLSTATES values that can be returned by the SQLDriverConnect function
SQLSTATE	Description	Explanation
01004	Data truncated.	The buffer szConnstrOut was not large enough to hold the entire connection string. The *OutConnectionStringLengthPtr argument contains the actual length of the connection string that is available for return. The 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 because one of the following events occurred: The unrecognized keyword was ignored. The invalid attribute value was ignored, and the default value was used instead. The function returns SQL_SUCCESS_WITH_INFO.
HY000	General error. Dialog failed	The information that was specified in the connection string was insufficient for making a connection request, but the dialog was prohibited by setting fCompletion to SQL_DRIVER_NOPROMPT. The attempt to start the dialog failed.
HY090	Invalid string or buffer length.	The value specified for the InConnectionStringLength argument was less than 0 but not equal to SQL_NTS. The value specified for OutConnectionStringCapacity was less than 0.
HY110	Invalid driver completion.	The value specified for the fCompletion argument was not equal to one of the valid values.

Example

The following code example demonstrates the use of the SQLDriverConnect() function:

    rc = SQLDriverConnect(hdbc,
                          (SQLHWND)sqlHWND,
                          InConnectionString,
                          InConnectionStringLength,
                          OutConnectionString,
                          OutConnectionStringCapacity,
                          StrLength2,
                          DriveCompletion);