Working with Multiple XARs

Enterprise Server supports multiple XARs defined for a single enterprise server region. The following scenarios provide XAR configuration and application organization recommendations that yield the best results when using multiple XARs:

Scenario: Multiple XARs of different RM switch module types

For a single enterprise server region, you can define and use one XAR for each RM switch module type. A simple scenario such as this does not require any recompilation of source code, nor does it require special XAR configuration. Enterprise Server handles all CICS transactions, Web services, and batch jobs correctly.

Scenario: Multiple XARs of the same type

In this scenario, suppose your application requires three XARs, all of the same type, but only one XAR is required for CICS applications. The other two are used in batch jobs only.

Here, you define the XAR for the CICS application with no special configuration options, and the two XARs used for batch jobs by including BatchOnly=T in the xa_open string. See SQL xa_open string Configuration Options for more information.

Scenario: Multiple XARs of the same type

In this scenario, you have two XARs of the same type. Both are required for CICS or Web services applications, and each is used by a distinct SQL program module executed by the application.

Here you must take steps to ensure that every SQL statement uses the correct XAR when it executes under Enterprise Server.

1. Assign each XAR a unique XAR ID.
2. Compile each SQL program module separately, using the appropriate preprocessor, and including the XAID compiler directive option. For each program, set the XAID compiler directive option to the value of the appropriate, corresponding XAR ID.

Scenario: Multiple XARs executed from the same program module

In this scenario, you have an application that needs to access two distinct XARs of the same or differing types, but both from within the same source code module. In this case, you have two options:

Separate the source code

We highly recommend this option as it requires minimal source code changes:

1. Separate the source code module into distinct modules, one for each that requires a distinct XAR.
2. Compile each program module using the XAID compiler directive option set to the value of its corresponding XAR ID.

Modify the source code

DB2 applications

• Use EXEC SQL 'SET CONNECTION connection-name' statements in programs to explicitly specify the current connection, where connection-name matches the database alias used in the xa_open string.
• If you specify the XAID compiler directive option when compiling any other source code modules, to avoid confusion, we highly recommend that you set the XAID value to match both the connection-name and the RM ID specified in the XAR definition.
• If user impersonation is required, you must register the XAR statically.

SQL Server applications

• Use EXEC SQL 'SET CONNECTION connection-name' statements in programs to explicitly specify the current connection.
  • Where connection-name matches the CONNECTNAME parameter in the xa_open string. If CONNECTNAME is not present, connection-name must match the RM ID specified in the XAR definition.
  • If you specify the XAID compiler directive option when compiling any source code modules, to avoid confusion, we highly recommend that its value match both connection-name and the RM ID specified in the XAR definition.
• Use 'AT dbname' prefix clause in every applicable SQL statement to explicitly specify the connection used.
  • Where dbname matches the CONNECTNAME parameter in the xa_open string. If CONNECTNAME is not present, dbname must match the RM ID specified in the XAR definition.
  • If you specify the XAID compiler directive option when compiling any other source code modules, to avoid confusion, we highly recommend that its value match both dbname and the RM ID specified in the XAR definition.

Oracle applications

Use 'AT dbname' prefix clause in every applicable SQL statement to explicitly specify the connection used.

• Where dbname matches the DB parameter in the xa_open string. If the DB parameter is not present, dbname must match the RM ID specified in the XAR definition.
• If you specify the XAID compiler directive option when compiling any other source code modules, to avoid confusion, we highly recommend that its value match both dbname and the RM ID specified in the XAR definition.
• If user impersonation is required, you must register the XAR statically.

Generic one-phase commit for ODBC applications

• Use EXEC SQL 'SET CONNECTION connection-name' statements in programs to explicitly specify the current connection.
  • Where connection-name matches the RM ID specified in the XAR definition.
  • If you specify the XAID compiler directive option when compiling any other source code modules, to avoid confusion, we highly recommend that its value match both connection-name and the RM ID specified in the XAR definition.
• Use 'AT dbname' prefix clause in every applicable SQL statement to explicitly specify the connection used.
  • Where dbname matches RM ID specified in the XAR definition.
  • If you specify the XAID compiler directive option when compiling any other source code modules, to avoid confusion, we highly recommend that its value match both dbname and the RM ID specified in the XAR definition.