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.
Syntax
SQLRETURN SQLDriverConnect (SQLHDBC ConnectionHandle,
SQLPOINTER WindowHandle,
SQLCHAR *InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR *OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT *StringLength2Ptr,
SQLSMALLINT DriverCompletion);
Function 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 Db2 for i, 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:
|
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.
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 IBM® 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.
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 DriverCompletion 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,
(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);
}
}