External contexts

Typically, the DB2® ODBC driver manages contexts in an ODBC application. With external contexts, you can write applications that manage contexts outside of DB2 ODBC. You use external contexts in combination with Language Environment® threads in the same way you use multiple contexts in combination with Language Environment threads.

When you combine external contexts with Language Environment threads, you must manage both the external contexts and the Language Environment threads within your application.

To write an application that uses external contexts, specify the following values in the initialization file:
  • MULTICONTEXT=0
  • MVSATTACHTYPE=RRSAF
Call the following APIs in your application to manage contexts using Resource Recovery Services (RRS) instead of the DB2 ODBC driver:
  • CRGGRM() to register your application as a resource manager
  • CRGSEIF() to set exit routines for your application
  • CTXBEGC() to create a private external context
  • CTXSWCH() to switch between contexts
  • CTXENDC() to end a private external context

When an application attempts to establish multiple active connections to the same data source from a single context, the ODBC driver rejects the connection request.

You cannot define different connection types for each external context. The following specifications set the connection type of all connections for every external context that your DB2 ODBC application creates:
  • The CONNECTTYPE keyword in the initialization file
  • The SQL_ATTR_CONNECTTYPE attribute in the functions SQLSetEnvAttr() and SQLSetConnectAttr()

DB2 ODBC does not support external contexts in applications that run as a stored procedure.

The following example shows an application that manages contexts outside of ODBC. This application uses RRS APIs to register as a context manager, set exit routines, create an external context, and switch between contexts.
Figure 1. An application that manages external contexts
/* Register as an unauthorized resource manager  */ 
CRGGRM();
/* Set exit information                          */   
CRGSEIF();                                            
/* Get an environment handle (henv)              */   
SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
 /* Get a connection handle, hdbc1, and connect to 
   STLEC1 under the native context.              */   
SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
SQLConnect( hdbc1, "STLEC1", ... );                   
/* Execute SQL under the native context at STLEC1*/
SQLAllocHandle(SQL_HANDLE_STMT, ...);
SQLExecDirect ...
       .
     .
/* Create a private context                      */  
CTXBEGC( ctxtoken1 );
/* Switch to private                             */
CTXSWCH( ctxtoken1 );
An application that manages external contexts
/* Get a connection handle, hdbc2, and connect 
   to STLEC1 under the private context.         */ 
SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc2);
SQLConnect( hdbc2, "STLEC1", ... );                  
/* Execute SQL under the private context at
   STLEC1                                         */  
SQLAllocHandle(SQL_HANDLE_STMT, ...);
SQLExecDirect ...
     .
     .                                                 
/* Commit changes on hdbc2                       */
SQLEndTran(SQL_HANDLE_DBC,  hdbc2, SQL_COMMIT);
/* Switch back to native                         */ 
CTXSWCH( 0 );                                         
/* Execute some more SQL under the native context 
    at STLEC1                                      */ 
SQLAllocHandle(SQL_HANDLE_STMT, ...);
SQLExecDirect ...
    .
    .                                                 
/* Rollback changes on hdbc1                     */
SQLEndTran(SQL_HANDLE_DBC, hdbc1, SQL_ROLLBACK);