SQLConnect - Connect to a data source
SQLConnect()
establishes
a connection to the target database. The application can optionally
supply a target SQL database, an authorization name, and an authentication
string.
SQLAllocConnect()
must be
called before calling this function.
This function must be called
before calling SQLAllocStmt()
.
Syntax
SQLRETURN SQLConnect (SQLHDBC hdbc,
SQLCHAR *szDSN,
SQLSMALLINT cbDSN,
SQLCHAR *szUID,
SQLSMALLINT cbUID,
SQLCHAR *szAuthStr,
SQLSMALLINT cbAuthStr);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHDBC | hdbc | Input | Connection handle. |
SQLCHAR * | szDSN | Input | Data source: name or alias name of the database. |
SQLSMALLINT | cbDSN | Input | Length of contents of szDSN argument. |
SQLCHAR * | szUID | Input | Authorization name (user identifier). |
SQLSMALLINT | cbUID | Input | Length of contents of szUID argument. |
SQLCHAR * | szAuthStr | Input | Authentication string (password). |
SQLSMALLINT | cbAuthStr | Input | Length of contents of szAuthStr argument. |
Usage
You can define various connection
characteristics (options) in the application using SQLSetConnectOption()
.
The input length arguments to SQLConnect()
(cbDSN, cbUID, cbAuthStr)
can be set to the actual length of their associated data - this does
not include any null-terminating character - or to SQL_NTS to indicate
that the associated data is null-terminated.
Leading and trailing blanks in the szDSN and szUID argument values are stripped before processing unless they are enclosed in quotation marks.
Input arguments szUID and szAuthStr are treated as case sensitive.
When running in server mode, both szUID and szAuthStr must be passed in order for the connection to run on behalf of a user ID other than the current user. If either parameter is NULL or both are NULL, the connection is started using the user ID that is in effect for the current job running the CLI program.
The data source must already be defined on the system for the connect function to work. On the IBM® i platform, you can use the Work with Relational Database Directory Entries (WRKRDBDIRE) command to determine which data sources have been defined, and to optionally define additional data sources.
If the application does not supply a target database (szDSN), the CLI uses the local database as the default.
Non-server mode connections to the *LOCAL relational database must specify for the connecting szUID either NULL or the current user. In this case, the password is not validated. When a non-server mode connection is used, the application should not obtain the connecting szUID as input from the user, since SQLConnect will not validate the password associated with the connection.
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
Diagnostics
SQLSTATE | Description | Explanation |
---|---|---|
08001 | Unable to connect to data source | The driver is unable to establish a connection with the data source (server). |
08002 | Connection in use | The specified hdbc has been used to establish a connection with a data source and the connection is still open. |
08004 | Data source rejected establishment of connection | The data source (server) rejected the establishment of the connection. |
28000 | Authorization specification that is not valid | The value specified for the argument szUID or the value specified for the argument szAuthStr violated restrictions defined by the data source. |
58004 | System error | Unrecoverable system error. |
HY001 | Memory allocation failure | The driver is unable to allocate memory required to support the processing or completion of the function. |
HY009 | Argument value that is not valid | The value specified for argument cbDSN is
less than 0, but not equal to SQL_NTS and the argument szDSN is
not a null pointer. The value specified for argument cbUID is less than 0, but not equal to SQL_NTS and the argument szUID is not a null pointer. The value specified for argument cbAuthStr is less than 0, but not equal to SQL_NTS and the argument szAuthStr is not a null pointer. A nonmatching double quotation mark (") is found in either the szDSN, szUID, or szAuthStr argument. |
HY013 * | Memory management problem | The driver is unable to access memory required to support the processing or completion of the function. |
HY501 * | Data source name that is not valid | A data source name that is not valid is specified in argument szDSN. |
Restrictions
The implicit connection (or
default database) option for IBM DBMSs
is not supported. SQLConnect()
must be called before
any SQL statements can be processed. Db2 for
i does not support multiple
simultaneous connections to the same data source in a single job.
SQLConnect()
can
encounter an SQL0144 message. This indicates that the data source
(the server) has obsolete SQL packages that must be deleted. To delete
these packages, run the following command on the data
source: DLTSQLPKG SQLPKG(QGPL/QSQCLI*)
The next SQLConnect()
creates a new
SQL package.Example
Refer to the example in SQLAllocEnv - Allocate environment handle.