SQLConnect

Purpose

SQLConnect() establishes a connection to the target database. The application must supply a target SQL database, and optionally 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

Table 1. SQLConnect arguments
Data type	Argument	Use	Description
SQLCHAR *	szAuthStr	Input	Authentication string (password).
SQLCHAR *	szDSN	Input	Data source: name or alias name of the database.
SQLCHAR *	szUID	Input	Authorization name (user identifier).
SQLHDBC	hdbc	Input	Connection handle.
SQLSMALLINT	cbAuthStr	Input	Length of contents of szAuthStr argument.
SQLSMALLINT	cbDSN	Input	Length of contents of szDSN argument.
SQLSMALLINT	cbUID	Input	Length of contents of szUID 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.

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^® eServer platform, you can use the Work with Relational Database Directory Entries (WRKRDBDIRE) command to determine which data sources have been defined already, and to optionally define additional data sources.

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^® UDB 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 server system:

   DLTSQLPKG SQLPKG(QGPL/QSQCLI*)

The next SQLConnect() creates a new SQL package.

Example

Refer to the example in SQLAllocEnv().

SQLConnect - Connect to a data source