SQLConnect function (CLI) - Connect to a data source
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.
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
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.
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
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);