`SQLDriverConnect()` - Use a connection string to connect to a data source

SQLDriverConnect() is an alternative to SQLConnect(). Both functions establish a connection to the target database, but SQLDriverConnect() supports additional connection parameters.

ODBC specifications for `SQLDriverConnect()`

Table 1. `SQLDriverConnect()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
1.0	No	No

Syntax

SQLRETURN SQLDriverConnect   (SQLHDBC           hdbc,
                              SQLHWND           hwnd,
                              SQLCHAR      FAR  *szConnStrIn,
                              SQLSMALLINT       cbConnStrIn,
                              SQLCHAR      FAR  *szConnStrOut,
                              SQLSMALLINT       cbConnStrOutMax,
                              SQLSMALLINT  FAR  *pcbConnStrOut,
                              SQLUSMALLINT      fDriverCompletion);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLDriverConnect()` arguments
Data type	Argument	Use	Description
SQLHDBC	hdbc	input	Specifies the connection handle to use for the connection.
SQLHWND	hwindow	input	Always specify the value NULL. This argument is not used.
SQLCHAR *	szConnStrIn	input	A complete, partial, or empty (null pointer) connection string. See Usage for a description and the syntax of this string.
SQLSMALLINT	cbConnStrIn	input	Specifies the length, in bytes, of the connection string to which the szConnStrIn argument points.
SQLCHAR *	szConnStrOut	output	Points to a buffer where the complete connection string is returned. If the connection is established successfully, this buffer contains the completed connection string. Applications should allocate at least SQL_MAX_OPTION_STRING_LENGTH bytes for this buffer.
SQLSMALLINT	cbConnStrOutMax	input	Specifies the maximum size, in bytes, of the buffer to which the szConnStrOut argument points.
SQLSMALLINT*	pcbConnStrOut	output	Points to a buffer that contains the total number of available bytes for the complete connection string. If the value of pcbConnStrOut is greater than or equal to cbConnStrOutMax, the completed connection string in szConnStrOut is truncated to cbConnStrOutMax - 1 bytes.
SQLUSMALLINT	fDriverCompletion	input	Indicates when Db2 ODBC should prompt the user for more information. IBM® specific: Db2 for z/OS® supports only the value of SQL_DRIVER_NOPROMPT for this argument. The following values are not supported: SQL_DRIVER_PROMPT SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED

Usage

Use SQLDriverConnect() when you want to specify any or all keyword values that are defined in the Db2 ODBC initialization file when you connect to a data source.

When a connection is established, the complete connection string is returned. Applications can store this string for future connection requests, which allows you to override any or all keyword values in the Db2 ODBC initialization file.

Use the connection string to pass one or more values that are needed to complete a connection. You must write the connection string to which the szConnStrln argument points with the following syntax:

Connection string syntax

The connection string contains the following keywords:

DSN: Data source name. The name or alias name of the database.
IBM specific: This is a required value because Db2 for z/OS supports only SQL_DRIVER_NOPROMPT for the fDriverCompletion argument.
UID: Authorization name (user identifier). This value is validated and authenticated.
IBM specific: Db2 for z/OS supports only SQL_DRIVER_NOPROMPT for the fDriverCompletion argument. If you do not specify a value for UID, Db2 uses the primary authorization ID of your application and the PWD keyword is ignored if it is specified.
PWD: The password corresponding to the authorization name. If the user ID has no password, pass an empty string (PWD=;). This value is validated and authenticated.
IBM specific: Db2 for z/OS supports only SQL_DRIVER_NOPROMPT for the fDriverCompletion argument. The value you specify for PWD is ignored if you do not specify UID in the connection string.

Any one of the initialization keywords can be specified on the connection string. If any keywords are repeated in the connection string, the value that is associated with the first occurrence of the keyword is used.

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

The application receives an error on any value of fDriverCompletion as follows:

SQL_DRIVER_PROMPT:: Db2 ODBC returns SQL_ERROR.
SQL_DRIVER_COMPLETE:: Db2 ODBC returns SQL_ERROR.
SQL_DRIVER_COMPLETE_REQUIRED:: Db2 ODBC returns SQL_ERROR.
SQL_DRIVER_NOPROMPT:: The user is not prompted for any information. A connection is attempted with the information that the connection string contains. If this information is inadequate to make a connection, SQL_ERROR is returned.

When a connection is established, the complete connection string is returned.

Return codes

After you call SQLDriverConnect(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR

Diagnostics

This function generates similar diagnostics as the function SQLConnect(). The following table shows the additional SQLSTATEs that SQLDriverConnect() returns.

Table 3. `SQLDriverConnect()` SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated.	The buffer that theszConnstrOut argument specifies is not large enough to hold the complete connection string. The pcbConnStrOut argument contains the actual length, in bytes, of the connection string that is available for return. (`SQLDriverConnect()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
01S00	Invalid connection string attribute.	An invalid keyword or attribute value is specified in the input connection string, but the connection to the data source is successful because one of the following events occur: The unrecognized keyword is ignored. The invalid attribute value is ignored and the default value is used instead. (`SQLDriverConnect()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
01S02	Option value changed.	SQL_CONNECTTYPE changes to SQL_CONCURRENT_TRANS while MULTICONTEXT=1 is in use.
HY090	Invalid string or buffer length.	This SQLSTATE is returned for one or more of the following reasons: The specified value for the cbConnStrIn argument is less than 0 and not equal to SQL_NTS. The specified value for the cbConnStrOutMax argument is less than 0.
HY110	Invalid driver completion.	The specified value for the fDriverCompletion argument is not equal to a valid value.

Restrictions

Db2 ODBC does not support the hwindow argument. Window handles do not apply in the z/OS environment.

Db2 ODBC does not support the following ODBC-defined values for the fDriverCompletion argument:

SQL_DRIVER_PROMPT
SQL_DRIVER_COMPLETE
SQL_DRIVER_COMPLETE_REQUIRED

Example

The following example shows an application that uses SQLDriverConnect()instead of SQLConnect() to pass keyword values to the connection.

Figure 1. An application that passes keyword values as it connects

 /******************************************************************/
 /*  Issue SQLDriverConnect to pass a string of initialization     */
 /*  parameters to compliment the connection to the data source.   */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "sqlcli1.h"
  /******************************************************************/
  /* SQLDriverConnect -----------                                   */
  /******************************************************************/
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   char            *ConnStrIn =
                   "dsn=STLEC1;connecttype=2;bitdata=2;optimizefornrows=30";
   char            ConnStrOut [200];
   SQLSMALLINT     cbConnStrOut;
   int             i;
   char            *token;
   (void) printf ("**** Entering CLIP10.\n\n");

  /*****************************************************************/
  /* CONNECT to DB2                                                */
  /*****************************************************************/
   rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if( rc != SQL_SUCCESS )
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle( SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
     goto dberror;
  /*****************************************************************/
  /* Invoke SQLDriverConnect -----------                           */
  /*****************************************************************/
   RETCODE = SQLDriverConnect (hDbc                 ,
                               NULL                 ,
                               (SQLCHAR *)ConnStrIn ,
                               strlen(ConnStrIn)    ,
                               (SQLCHAR *)ConnStrOut,                              
                               sizeof(ConnStrOut)   ,
                               &cbConnStrOut        ,
                               SQL_DRIVER_NOPROMPT);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
   {
     (void) printf ("**** Driver Connect Failed. rc = 
     goto dberror;
   }
  /*****************************************************************/
  /* Enumerate keywords and values returned from SQLDriverConnect  */
  /*****************************************************************/
   (void) printf ("**** ConnStrOut = %s.\n", ConnStrOut);
   for (i = 1, token = strtok (ConnStrOut, ";");
        (token != NULL);
        token = strtok (NULL, ";"), i++)
     (void) printf ("**** Keyword # 
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle (SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
/*****************************************************************/
  /* Disconnect from data sources in connection table              */
  /*****************************************************************/
   SQLFreeHandle(SQL_HANDLE_ENV, hEnv);     /* Free  environment handle  */
   goto exit;
   dberror:
   RETCODE=12;
   exit:
   (void) printf ("**** Exiting  CLIP10.\n\n");
   return(RETCODE);
}

SQLDriverConnect() - Use a connection string to connect to a data source

ODBC specifications for SQLDriverConnect()