Purpose
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
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLCHAR * | InConnectionString | Input | A full, partial, or empty (null pointer) connection string. |
| SQLCHAR * | OutConnectionString | Output | Pointer to buffer for the completed connection
string. If the connection is established successfully, this buffer contains the completed connection string. |
| SQLHDBC | ConnectionHandle | Input | Connection handle. |
| SQLHWND | hwindow | Input | For DB2 Universal Database™ for Linux®, UNIX®, and Windows®, this is the parent handle. On i5/OS™, it is ignored. |
| 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 | Indicates when DB2® UDB CLI should prompt the user for more
information. Possible values:
|
| SQLSMALLINT | BufferLength | Input | Maximum size of the buffer pointed to by OutConnectionString. |
| SQLSMALLINT | StringLength1 | Input | Length of InConnectionString. |
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-'
- 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=;).
iSeries™ 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.
| 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:
(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
/* 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);
}
}