SQLSetConnection function (CLI) - Set connection handle

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 CLI function calls with embedded SQL function calls and where multiple connections are used.

Specification:

  • CLI 2.1

Syntax

SQLRETURN   SQLSetConnection (SQLHDBC          ConnectionHandle); /* hdbc */

Function arguments

Table 1. SQLSetConnection arguments
Data type Argument Use Description
SQLHDBC ConnectionHandle input The connection handle associated with the connection that the application wishes to switch to.

Usage

In CLI version 1 it was possible to mix CLI calls with calls to routines containing embedded SQL as long as the connect request was issued via the CLI connect function. The embedded SQL routine would simply use the existing CLI connection.

Although this is still true, there is a potential complication: 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 if the application makes use of CLI exclusively. Under those conditions, each statement handle is implicitly associated with a connection handle and there is never any confusion as to which connection a particular CLI function applies.

Return codes

  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. 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-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec() in the argument MessageText describes the error and its cause.

Restrictions

None.

Example

  /* perform statements on the first connection */
  cliRC = SQLSetConnection(hdbc1);

  /* ... */

  /* perform statements on the second connection */
  cliRC = SQLSetConnection(hdbc2);