| Specification: | DB2 CLI 2.1 |
This function is needed if the application needs to deterministically switch to a particular connection before continuing execution. It should only be used when the application is mixing DB2 CLI function calls with embedded SQL function calls and multiple connections are involved.
Syntax
SQLRETURN SQLSetConnection (SQLHDBC ConnectionHandle); /* hdbc */
Function Arguments
Table 152. SQLSetConnection Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHDBC | ConnectionHandle | input | The connection handle associated with the connection the application wishes to switch to. |
Usage
In DB2 CLI version 1 it was possible to mix DB2 CLI calls with calls to routines containing embedded SQL as long as the connect request was issued via the DB2 CLI connect function. The embedded SQL routine would simply use the existing DB2 CLI connection.
Although this is still true, there is a potential complication: DB2 CLI allows multiple concurrent connections. This means that it is no longer clear which connection an embedded SQL routine would use upon being invoked. In practice, the embedded routine would use the connection associated with the most recent network activity. However, from the application's perspective, this is not always deterministic 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 CLI 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 CLI function applies.
For more information on using embedded SQL within DB2 CLI applications refer to Mixing Embedded SQL and DB2 CLI.
Return Codes
Diagnostics
Table 153. 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 was no specific SQLSTATE and for which no implementation defined SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
Restrictions
None.
(The complete sample dbmusemx.sqc is also available here .)
/* From the CLI sample dbmusemx.sqc */
/* ... */
sqlrc = SQLSetConnection( a_hdbc[0]);
MC_HANDLE_CHECK( SQL_HANDLE_DBC, a_hdbc[0], sqlrc,
&henv, a_hdbc, MAX_CONNECTIONS ) ;
References