Db2 ODBC support of multiple contexts

A context is the Db2 ODBC equivalent of a Db2 thread. Contexts are the structures that describe the logical connections that an application makes to data sources and the internal Db2 ODBC connection information that allows applications to direct operations to a data source.

You establish a context when you allocate a connection handle when multiple contexts are enabled. Db2 ODBC always creates a context for the first connection handle that you create on a Language Environment® thread. If you do not enable Db2 ODBC support for multiple contexts, only these SQLAllocHandle() calls establish a context. If you enable support for multiple contexts, Db2 ODBC establishes a separate context (and Db2 thread) each time that you issue SQLAllocHandle() to allocate a connection handle.

To enable or explicitly disable Db2 ODBC support for multiple contexts, use the MULTICONTEXT keyword in the Db2 ODBC initialization file.

Before you enable multiple contexts, each Language Environment thread that you create can use only a single context. With only one context for each Language Environment thread, your application runs with only simulated support for the ODBC connection model. Multiple contexts are disabled by default. To explicitly disable multiple contexts, specify MULTICONTEXT=0 in the initialization file.

When you specify MULTICONTEXT=1 in the initialization file, a distinct context is established for each connection handle, which you establish with SQLAllocHandle(). With a context for each connection, Db2 ODBC is consistent with, and provides full support for, the ODBC connection model.

To use multiple contexts, you must specify MVSATTACHTYPE=RRSAF in the initialization file.

Specifying MULTICONTEXT=1 implies CONNECTTYPE=1. Implicitly concurrent connection types are consistent with the ODBC connection model. SQLEndTran() handles all connections independently for both commit and rollback.

In a multiple-context environment, you establish contexts with SQLAllocHandle() and delete contexts with SQLFreeHandle() (with the HandleType argument on both functions set to SQL_HANDLE_DBC). All SQLConnect() and SQLDisconnect() operations that use the same connection handle belong to the same context. Although you can make only one active connection to a data source within a single context, you can call SQLDisconnect() and then call SQLConnect() to change the target data source. When you change data sources in a multiple-context environment, this change is also subject to the rules of CONNECTTYPE=1.

Start of changeWhen you specify MULTICONTEXT=1, Db2 ODBC automatically uses the internal RRSAF control functions to create and manage contexts for the application. However, Db2 ODBC does not perform context management for the application if any of the following conditions are true:
  • Your Db2 ODBC application creates a Db2 thread before it invokes Db2 ODBC. This condition always applies for any stored procedure that uses Db2 ODBC.
  • Your Db2 ODBC application creates and switches to an RRS private context before it invokes Db2 ODBC. For example, an application that explicitly uses z/OS® Unauthorized Context Services and that issues ctxswch() to switch to a private context prior to invoking Db2 ODBC cannot take advantage of MULTICONTEXT=1.
  • Your Db2 ODBC application starts a unit of recovery with any RRS resource manager before it invokes Db2 ODBC.
  • You specify MVSATTACHTYPE=CAF in the initialization file.
End of change

To determine if MULTICONTEXT=1 is active for the Db2 ODBC application, call SQLGetInfo() with the InfoType argument set to SQL_MULTIPLE_ACTIVE_TXN.

The following table shows the connection characteristics that different combinations of MULTICONTEXT and CONNECTTYPE produce.

Table 1. Connection characteristics
Setting: MULTICONTEXT Setting: CONNECTTYPE Result: Language Environment threads can have more than one ODBC connection with an outstanding unit of work Result: Language Environment threads can commit or roll back an ODBC connection independently Result: Number of Db2 threads that Db2 ODBC creates on behalf of application
0 2 Y N 1 per Language Environment thread
0 1 N Y 1 per Language Environment thread
11 1 or 22 Y Y 1 per ODBC connection handle
Note:
  1. MULTICONTEXT=1 requires MVSATTACHTYPE=RRSAF
  2. MULTICONTEXT=1 implies CONNECTTYPE=1 characteristics. If you specify MULTICONTEXT=1 and CONNECTTYPE=2 in the initialization file, Db2 ODBC ignores CONNECTTYPE=2. When you specify MULTICONTEXT=1, any attempt to set CONNECTTYPE=2 with SQLSetEnvAttr(), SQLSetConnectAttr(), or SQLDriverConnect() is rejected with SQLSTATE 01S02.
    • All connections in a Db2 ODBC application have the same CONNECTTYPE and MULTICONTEXT characteristics. The connection type of an application (which is specified with the CONNECTTYPE keyword) is established at the first SQLConnect() call. Multiple-context support (which is specified with the MULTICONTEXT keyword) is established when you allocate an environment handle.
    • For CONNECTTYPE=1 or MULTICONTEXT=1, the AUTOCOMMIT default value is ON. For CONNECTTYPE=2 or MULTICONTEXT=0, the AUTOCOMMIT default value is OFF.