SQLDriverConnect - Connect to a data source

SQLDriverConnect() is an alternative to SQLConnect(). Both functions establish a connection to the target database, but SQLDriverConnect() uses a connection string to determine the data source name, user ID, and password. The functions are the same; both are supported for compatibility purposes.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLDriverConnectW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 CLI.

Syntax

SQLRETURN   SQLDriverConnect (SQLHDBC           ConnectionHandle,
                              SQLPOINTER        WindowHandle,
                              SQLCHAR           *InConnectionString,
                              SQLSMALLINT       StringLength1,
                              SQLCHAR           *OutConnectionString,
                              SQLSMALLINT       BufferLength,
                              SQLSMALLINT       *StringLength2Ptr,
                              SQLSMALLINT       DriverCompletion);

Function arguments

Table 1. SQLDriverConnect arguments
Data type	Argument	Use	Description
SQLHDBC	ConnectionHandle	Input	Connection handle.
SQLPOINTER	WindowHandle	Input	For DB2 for Linux, UNIX, and Windows, this is the parent handle. On i5/OS, it is ignored.
SQLCHAR *	InConnectionString	Input	A full, partial, or empty (null pointer) connection string.
SQLSMALLINT	StringLength1	Input	Length of InConnectionString.
SQLCHAR *	OutConnectionString	Output	Pointer to buffer for the completed connection string. If the connection is established successfully, this buffer contains the completed connection string.
SQLSMALLINT	BufferLength	Input	Maximum size of the buffer pointed to by OutConnectionString.
SQLSMALLINT *	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.
SQLSMALLINT	DriverCompletion	Input	This indicates when DB2 for i CLI should prompt the user for more information. Possible values: SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED SQL_DRIVER_NOPROMPT

Usage

The connection string is used to pass one or more values that are needed to complete a connection. The contents of the connection string and the value of DriverCompletion determine how the connection should be established.


   .-;------------------------------------------.   
   V                                            |   
>>---| Connection string syntax |--=--attribute-+--------------><

Connection string syntax

|--+-DSN---------------------+----------------------------------|
   +-UID---------------------+   
   +-PWD---------------------+   
   '-DB2 CLI-defined-keyword-'

Each of the previous keywords has an attribute that is equal to:

DSN: Data source name. The name or alias-name of the database. The data source name is required if DriverCompletion is equal to SQL_DRIVER_NOPROMPT.
UID: Authorization-name (user identifier).
PWD: The password that corresponds to the authorization name. If there is no password for the user ID, empty is specified (PWD=;).

The System i® platform currently has no DB2 for i CLI-defined keywords.

Input user ID and password strings passed in argument InConnectionString are treated as case sensitive.

The value of DriverCompletion is verified to be valid, but all result in the same behavior. A connection is attempted with the information that is contained in the connection string. If there is not enough information, SQL_ERROR is returned.

As soon as 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.

Non-server mode connections to the *LOCAL relational database do not lead to validation of the connecting userid and password. The *CURUSR value will be used for the connection processing.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR

Error conditions

All of the diagnostics that are generated by SQLConnect() can be returned here as well. The following table shows the additional diagnostics that can be returned.

Table 2. SQLDriverConnect SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated	The buffer szConnstrOut is 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	Connection string attribute that is not valid	A keyword or attribute value that is not valid is specified in the input connection string, but the connection to the data source is successful anyway because one of the following situations occurs: The unrecognized keyword is ignored. The attribute value that is not valid is ignored, the default value is used instead. (Function returns SQL_SUCCESS_WITH_INFO)
HY009	Argument value that is not valid	The argument InConnectionString, OutConnectionString, or StringLength2PTR is a null pointer. The argument DriverCompletion is not equal to 1.
HY090	String or buffer length that is not valid	The value specified for StringLength1 is less than 0, but not equal to SQL_NTS. The value specified for BufferLength is less than 0.
HY110	Driver completion that is not valid	The value specified for the argument DriverCompletion is not equal to one of the valid values.

Restrictions

None.

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

/* From CLI sample drivrcon.c */
/* ... */
/********************************************************************
**   drv_connect - Prompt for connect options and connect              **
********************************************************************/
 
int
drv_connect(SQLHENV henv,
            SQLHDBC * hdbc,
            SQLCHAR con_type)
{
    SQLRETURN       rc;
    SQLCHAR         server[SQL_MAX_DSN_LENGTH + 1];
    SQLCHAR         uid[MAX_UID_LENGTH + 1];
    SQLCHAR         pwd[MAX_PWD_LENGTH + 1];
    SQLCHAR         con_str[255];
    SQLCHAR         buffer[255];
    SQLSMALLINT     outlen;
 
    printf("Enter Server Name:\n");
    gets((char *) server);
    printf("Enter User Name:\n");
    gets((char *) uid);
    printf("Enter Password Name:\n");
    gets((char *) pwd);
 
    /* Allocate a connection handle */
    SQLAllocHandle( SQL_HANDLE_DBC,
                         henv,
                         hdbc
                       );
    CHECK_HANDLE( SQL_HANDLE_DBC, *hdbc, rc);
 
    sprintf((char *)con_str, "DSN=%s;UID=%s;PWD=%s;",
            server, uid, pwd);
 
    rc = SQLDriverConnect(*hdbc,
            (SQLPOINTER) NULL,
            con_str,
            SQL_NTS,
            buffer, 255, &outlen,
            SQL_DRIVER_NOPROMPT);
    if (rc != SQL_SUCCESS) {
        printf("Error while connecting to database, RC= %ld\n", rc);
        CHECK_HANDLE( SQL_NULL_HENV, *hdbc, rc);
        return (SQL_ERROR);
    } else {
        printf("Successful Connect\n");
        return (SQL_SUCCESS);
    }
}

References

SQLConnect - Connect to a data source