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

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

Syntax

SQLRETURN SQLConnect (SQLHDBC         hdbc,
                      SQLCHAR         *szDSN,
                      SQLSMALLINT     cbDSN,
                      SQLCHAR         *szUID,
                      SQLSMALLINT     cbUID,
                      SQLCHAR         *szAuthStr,
                      SQLSMALLINT     cbAuthStr);

Function arguments

Table 1. SQLConnect 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 System 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 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_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLConnect SQLSTATEs
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. i5/OS does not support multiple simultaneous connections to the same data source in a single job.

When you are using DB2 for i CLI on a newer release, 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.