SQLDriverConnect - (Expanded) Connect to a data source

SQLDriverConnect - (Expanded) 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.

Syntax
SQLRETURN   SQLDriverConnect (SQLHDBC           ConnectionHandle,
                              SQLHWND           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.
SQLHWND hwindow 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 UDB 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 UDB 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 UDB CLI-defined keywords.
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.

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 fCompletion is not equal to one of the valid values.

Restrictions

None.

Example

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,
            (SQLHWND) 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

Parent topic:
DB2 UDB CLI functions

Data type	Argument	Use	Description
SQLHDBC	ConnectionHandle	Input	Connection handle.
SQLHWND	hwindow	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 UDB CLI should prompt the user for more information. Possible values: SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED SQL_DRIVER_NOPROMPT

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 fCompletion is not equal to one of the valid values.