Call Level Interface Guide and Reference

SQLConnect - Connect to a Data Source

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

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.

A connection handle must be allocated using SQLAllocHandle() before calling this function.

This function must be called before allocating a statement handle using SQLAllocHandle().

Syntax

SQLRETURN   SQLConnect       (
                SQLHDBC           ConnectionHandle,  /* hdbc */
                SQLCHAR      *FAR ServerName,        /* szDSN */
                SQLSMALLINT       NameLength1,       /* cbDSN */
                SQLCHAR      *FAR UserName,          /* szUID */
                SQLSMALLINT       NameLength2,       /* cbUID */
                SQLCHAR      *FAR Authentication,    /* szAuthStr */
                SQLSMALLINT       NameLength3);      /* cbAuthStr */

Function Arguments

Table 40. SQLConnect Arguments

Data Type Argument Use Description
SQLHDBC ConnectionHandle input Connection handle
SQLCHAR * ServerName input Data Source: The name or alias-name of the database.
SQLSMALLINT NameLength1 input length of contents of ServerName argument
SQLCHAR * UserName input Authorization-name (user identifier)
SQLSMALLINT NameLength2 input Length of contents of UserName argument
SQLCHAR * Authentication input Authentication-string (password)
SQLSMALLINT NameLength3 input Length of contents of Authentication argument

Data Type	Argument	Use	Description
SQLHDBC	`ConnectionHandle`	input	Connection handle
SQLCHAR *	`ServerName`	input	Data Source: The name or alias-name of the database.
SQLSMALLINT	`NameLength1`	input	length of contents of `ServerName` argument
SQLCHAR *	`UserName`	input	Authorization-name (user identifier)
SQLSMALLINT	`NameLength2`	input	Length of contents of `UserName` argument
SQLCHAR *	`Authentication`	input	Authentication-string (password)
SQLSMALLINT	`NameLength3`	input	Length of contents of `Authentication` argument

Usage

The target database (also known as data source) for IBM RDBMSs is the database-alias. The application can obtain a list of databases available to connect to by calling SQLDataSources().

Before SQLDataSources() can return this information, the database(s) must be cataloged. Under Windows, using the ODBC Driver Manager, the user must catalog the database twice:

Once to the IBM RDBMS
Once to ODBC.

This can be accomplished in one step with the DB2 Client Setup included with the DB2 Client Application Enabler products. Although the methods of cataloging are different between ODBC Driver Manager and for IBM RDBMSs, the DB2 CLI applications are shielded from this. (One of the strengths of Call Level Interface is that the application does not have to know about the target database until SQLConnect() is invoked at runtime.) The mapping of the data source name to an actual DBMS is outside the scope and responsibility of the CLI application.

When using DB2 CLI in environments without an ODBC Driver Manager, the IBM RDBMSs need to be cataloged only once. For more information on cataloging, refer to Chapter 4, Configuring CLI/ODBC and Running Sample Applications.

The input length arguments to SQLConnect() (NameLength1, NameLength2, NameLength3) can be set to the actual length of their associated data (not including any null-terminating character) or to SQL_NTS to indicate that the associated data is null-terminated.

The ServerName and UserName argument values must not contain any blanks.

Use the more extensible SQLDriverConnect() function to connect when the applications needs to:

Request the user to specify more than just the data source name, user ID, and password arguments on connect,
Display a graphical dialog box to prompt for connect information

Various connection characteristics (options) may be specified by the end user in the section of the db2cli.ini (and odbc.ini) initialization file associated with the ServerName data source argument or set by the application using SQLSetConnectAttr(). The extended connect function, SQLDriverConnect(), can also be called with additional connect options.

Stored procedures written using DB2 CLI must make a null SQLConnect() call. A null SQLConnect() is where the ServerName, UserName, and Authentication argument pointers are all set to NULL and their respective length arguments all set to 0. A null SQLConnect() still requires SQLAllocEnv() and SQLAllocConnect() be called first, but does not require that SQLTransact() be called before SQLDisconnect(). For more information, refer to Stored Procedure Example.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 41. SQLConnect SQLSTATEs

SQLSTATE Description Explanation
08001 Unable to connect to data source. DB2 CLI was unable to establish a connection with the data source (server).
The connection request was rejected because an existing connection established via embedded SQL already exists.
08002 Connection in use. The specified ConnectionHandle has already been used to establish a connection with a data source and the connection is still open.
08004 The application server rejected establishment of the connection. The data source (server) rejected the establishment of the connection.
The number of connections specified by the MAXCONN keyword has been reached.
28000 Invalid authorization specification. The value specified for the argument UserName or the value specified for the argument Authentication violated restrictions defined by the data source.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY090 Invalid string or buffer length. The value specified for argument NameLength1 was less than 0, but not equal to SQL_NTS and the argument ServerName was not a null pointer.
The value specified for argument NameLength2 was less than 0, but not equal to SQL_NTS and the argument UserName was not a null pointer.
The value specified for argument NameLength3 was less than 0, but not equal to SQL_NTS and the argument Authentication was not a null pointer.
HY013 Unexpected memory handling error. DB2 CLI was unable to access memory required to support execution or completion of the function.
HY501 Invalid data source name. An invalid data source name was specified in argument ServerName.
HYT00 Timeout expired. The timeout period expired before the data source returned the result set. Timeouts are only supported on non-multitasking systems such as Windows 3.1 and Macintosh System 7. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for SQLSetConnectAttr().

SQLSTATE	Description	Explanation
08001	Unable to connect to data source.	DB2 CLI was unable to establish a connection with the data source (server). The connection request was rejected because an existing connection established via embedded SQL already exists.
08002	Connection in use.	The specified `ConnectionHandle` has already been used to establish a connection with a data source and the connection is still open.
08004	The application server rejected establishment of the connection.	The data source (server) rejected the establishment of the connection. The number of connections specified by the MAXCONN keyword has been reached.
28000	Invalid authorization specification.	The value specified for the argument `UserName` or the value specified for the argument `Authentication` violated restrictions defined by the data source.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for argument `NameLength1` was less than 0, but not equal to SQL_NTS and the argument `ServerName` was not a null pointer. The value specified for argument `NameLength2` was less than 0, but not equal to SQL_NTS and the argument `UserName` was not a null pointer. The value specified for argument `NameLength3` was less than 0, but not equal to SQL_NTS and the argument `Authentication` was not a null pointer.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.
HY501	Invalid data source name.	An invalid data source name was specified in argument `ServerName`.
HYT00	Timeout expired.	The timeout period expired before the data source returned the result set. Timeouts are only supported on non-multitasking systems such as Windows 3.1 and Macintosh System 7. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for `SQLSetConnectAttr()`.

Restrictions

The implicit connection (or default database) option for IBM RDBMSs is not supported. SQLConnect() must be called before any SQL statements can be executed.

CLI Sample utilcli.c

(The complete sample utilcli.c is also available here .)

 
/* From the CLI sample utilcli.c */
/* ... */
 
    /* connect to the database */
    printf( "\nConnecting to %s ...\n", dbAlias ) ;    
    sqlrc = SQLConnect( *pHdbc,
                     (SQLCHAR *)dbAlias,   SQL_NTS,
                     (SQLCHAR *)user, SQL_NTS,
                     (SQLCHAR *)pswd, SQL_NTS
                   ) ;
    HANDLE_CHECK( SQL_HANDLE_DBC, *pHdbc, sqlrc, pHenv, pHdbc ) ;     
    printf( "Connected to %s.\n", dbAlias ) ;
 
    return( 0 ) ;
}

References

[ Top of Page | Previous Page | Next Page ]