Functions for establishing a distributed unit-of-work connection

You establish distributed unit of work connections when you call SQLSetEnvAttr() or SQLSetConnectAttr() with SQL_ATTR_CONNECTTYPE set to SQL_COORDINATED_TRANS.

You cannot specify MULTICONTEXT=1 in the initialization file if you want to use coordinated distributed transactions. Users of your application can specify CONNECTTYPE=2 in the Db2 ODBC initialization file or in the SQLDriverConnect() connection string to enable coordinated transactions.

You cannot mix concurrent connections with coordinated connections in your application. The connection type that you specify for the first connection determines the connection type of all subsequent connections. SQLSetEnvAttr() and SQLSetConnectAttr() return an error if your application attempts to change the connection type while any connection is active. After you establish a connection type, it persists until you free all connection handles and change the value of the CONNECTTYPE keyword or the SQL_ATTR_CONNECTTYPE attribute.

The following example shows an example of an application that sets SQL_ATTR_CONNECTTYPE to SQL_COORDINATED_TRANS and performs a coordinated transaction on two data sources within the distributed environment.
Figure 1. An application that connects to two data sources for a coordinated transaction
/* ... */
#define MAX_CONNECTIONS   2
int
DBconnect(SQLHENV henv,
          SQLHDBC * hdbc,
          char    * server);
int
main()
{
    SQLHENV         henv;
    SQLHDBC         hdbc[MAX_CONNECTIONS];
    SQLRETURN       rc;
    char *          svr[MAX_CONNECTIONS] =
                    {
                      "KARACHI"   ,
                      "DAMASCUS"
                    }
    /* Allocate an environment handle   */
    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    /* Before allocating any connection handles, set Environment wide
       Connect Attributes  */
    /* Set to CONNECT(type 2)*/
    rc = SQLSetEnvAttr(henv, SQL_CONNECTTYPE,
                       (SQLPOINTER) SQL_COORDINATED_TRANS, 0);
/* ... */
    /* Connect to first data source */
    /* Allocate a connection handle     */
    if (SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc[0]) != SQL_SUCCESS) {
        printf(">---ERROR while allocating a connection handle-----\n");
        return (SQL_ERROR);
    }
    /* Connect to first data source (Type-II) */
    DBconnect (henv,
               &hdbc[0],
               svr[0]);
    /* Allocate a second connection handle     */
    if (SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc[1]) != SQL_SUCCESS) {
        printf(">---ERROR while allocating a connection handle-----\n");
        return (SQL_ERROR);
    }
    /* Connect to second data source (Type-II) */
    DBconnect (henv,
               &hdbc[1],
               svr[1]);
    /*********   Start processing step  *************************/
    /* Allocate statement handle, execute statement, and so on  */
    /* Note that both connections participate in the disposition*/
    /* of the transaction. Note that a NULL connection handle   */
    /* is passed as all work is committed on all connections.   */
    /*********   End processing step  ***************************/
    (void)SQLEndTran(SQL_HANDLE_HENV, henv, SQL_COMMIT);
    /* Disconnect, free handles and exit */
}
/********************************************************************
**   Server is passed as a parameter. Note that USERID and PASSWORD**
**   are always NULL.                                              **
********************************************************************/
int
DBconnect(SQLHENV henv,
          SQLHDBC * hdbc,
          char    * server)
{
    SQLRETURN       rc;
    SQLCHAR         buffer[255];
    SQLSMALLINT     outlen;
    /* Allocate a connection handle     */    
    SQLAllocHandle(SQL_HANDLE_DBC, henv, hdbc);
    rc = SQLConnect(*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
    if (rc != SQL_SUCCESS) {
        printf(">--- Error while connecting to database: 
        return (SQL_ERROR);
    } else {
        printf(">Connected to 
        return (SQL_SUCCESS);
    }
}
/* ... */