SQLConnect function (CLI) - Connect to a data source

Establishes a connection or a trusted connection to the target database.

Purpose

Specification: CLI 1.1 ODBC 1.0 ISO CLI

A target database name must be provided when you call the SQLConnect() function. You must also specify a user ID and associated password for database authentication when you are establishing a non-trusted connection to a database.

A connection must be established before you allocate a statement handle with the SQLAllocHandle() function.

Unicode Equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLConnectW(). Refer to Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLConnect       (
               SQLHDBC           ConnectionHandle,       /* hdbc */
               SQLCHAR           *ServerName,             /* szDSN */
               SQLSMALLINT       ServerNameLength,       /* cbDSN */
               SQLCHAR           *UserName,               /* szUID */
               SQLSMALLINT       UserNameLength,         /* cbUID */
               SQLCHAR           *Authentication,         /* szAuthStr */
               SQLSMALLINT       AuthenticationLength);  /* cbAuthStr */

Function arguments

Table 1. 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 ServerNameLength input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the ServerName argument.
SQLCHAR * UserName input Authorization-name (user identifier)
SQLSMALLINT UserNameLength input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the UserName argument.
SQLCHAR * Authentication input Authentication-string (password)
SQLSMALLINT AuthenticationLength input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the Authentication argument.

Usage

The target database name is also known as a data source name, or a database-alias. Applications can obtain a list of databases available for a connection by calling the SQLDataSources() function.

The input length arguments to theSQLConnect() function (ServerNameLength, UserNameLength, AuthenticationLength) can be set to the actual length of their associated data in elements (SQLCHAR or SQLWCHAR), not including any null-terminating character. You can indicate that the associated data is null-terminated by setting the length argument to SQL_NTS.

The ServerName and UserName argument values must not contain any space characters.

The CLI driver supports special characters for the password with limitations.

Stored procedures that use the CLI driver can make a SQLConnect() function call with null arguments to allocate statement handles (the ServerName, UserName, and Authentication argument pointers are all set to NULL and their respective length arguments all set to 0 or SQL_NTS):
cliRC = SQLConnect(hdbc, NULL, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
In CLI applications, including stored procedures that use the CLI driver, you cannot allocate statement handles without the connection handle. By calling a SQLConnect() function with null arguments, you are implicitly creating a connection handle.

The SQLConnect() function call with null arguments still require a call to the SQLAllocHandle() function be made first. However, the SQLEndTran() function does not require a prior call to the SQLDisconnect() function.

To create a trusted connection, specify the SQL_ATTR_USE_TRUSTED_CONTEXT connection attribute before you call the SQLConnect() function. A message is returned if the database server does not accept the connection as the trusted connection.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLConnect SQLSTATEs
SQLSTATE Description Explanation
01679 Unable to establish a trusted connection. CLI requested a trusted connection but the trust attributes of the connection do not match any trusted context object on the database server. The connection is allowed but it is a regular connection, not a trusted connection.
08001 Unable to connect to data source. 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.
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. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY013 Unexpected memory handling error. Db2 CLI was unable to access memory required to support execution or completion of the function.
HY090 Invalid string or buffer length. The value specified for argument ServerNameLength was less than 0, but not equal to SQL_NTS and the argument ServerName was not a null pointer.

The value specified for argument UserNameLength was less than 0, but not equal to SQL_NTS and the argument UserName was not a null pointer.

The value specified for argument AuthenticationLength was less than 0, but not equal to SQL_NTS and the argument Authentication was not a null pointer.
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. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for SQLSetStmtAttr().
Note: This SQLSTATE applies only to .Net applications.

Restrictions

  • The implicit connection (or default database) option to IBM® database is not supported.
  • A connection must be established before any SQL statement can be issued.
  • You cannot specify a user ID and password arguments (authentication parameters) in the SQLConnect() function when the certificate authentication is specified. The certification authentication is specified when the Authentication keyword in the db2cli.ini configuration file or the IBM data server driver configuration file is set to CERTIFICATE.

Example

  /* connect to the database */
  cliRC = SQLConnect(hdbc,
                     (SQLCHAR *)db1Alias,
                     SQL_NTS,
                     (SQLCHAR *)user,
                     SQL_NTS,
                     (SQLCHAR *)pswd,
                     SQL_NTS);