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.
SQLRETURN SQLConnect (
SQLHDBC ConnectionHandle, /* hdbc */
SQLCHAR *ServerName, /* szDSN */
SQLSMALLINT ServerNameLength, /* cbDSN */
SQLCHAR *UserName, /* szUID */
SQLSMALLINT UserNameLength, /* cbUID */
SQLCHAR *Authentication, /* szAuthStr */
SQLSMALLINT AuthenticationLength); /* cbAuthStr */
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. |
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.
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.
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(). |
/* connect to the database */
cliRC = SQLConnect(hdbc,
(SQLCHAR *)db1Alias,
SQL_NTS,
(SQLCHAR *)user,
SQL_NTS,
(SQLCHAR *)pswd,
SQL_NTS);