SQLSetConnection() - Set connection handle

SQLSetConnection() is needed if the application needs to deterministically switch to a particular connection before continuing execution. Use this function only when your application mixes Db2 ODBC function calls with embedded SQL function calls and makes multiple database connections.

ODBC specifications for SQLSetConnection()

Table 1. SQLSetConnection() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
No No No

Syntax

SQLRETURN  SQLSetConnection  (SQLHDBC           hdbc);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLSetConnection() arguments
Data type Argument Use Description
SQLHDBC hdbc input The connection handle associated with the connection to which the application wants to switch.

Usage

ODBC allows multiple concurrent connections. It is not clear which connection an embedded SQL routine uses when invoked. In practice, the embedded routine uses the connection associated with the most recent network activity. However, from the application's perspective, this is not always easy to determine and it is difficult to keep track of this information. SQLSetConnection() is used to allow the application to explicitly specify which connection is active. The application can then call the embedded SQL routine.

SQLSetConnection() is not needed at all if the application makes purely Db2 ODBC calls. This is because each statement handle is implicitly associated with a connection handle and there is never any confusion as to which connection a particular Db2 ODBC function applies.

Important: To mix Db2 ODBC with embedded SQL, you must not enable Db2 ODBC support for multiple contexts. The initialization file for mixed applications must specify MULTICONTEXT=0 or exclude MULTICONTEXT keyword.

Return codes

After you call SQLSetConnection(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLSetConnection() SQLSTATEs
SQLSTATE Description Explanation
08003 Connection is closed. The connection handle provided is not currently associated with an open connection to a database server.
HY000 General error. An error occurred for which there is no specific SQLSTATE and for which the implementation does not define an SQLSTATE. SQLGetDiagRec() returns an error message in the argument szErrorMsg that describes the error and its cause.

Example

The topic Using arrays to pass parameter values contains an example that demonstrates how to invoke SQLSetConnection().