User Interface

• the TDS administrator responsible for the generation step and for monitoring the TDS application,

• the GCOS 7 system administrator and the ORACLE database administrator who are responsible for data consistency,

• the TDS programmer who is responsible for programming transactions that are committed with XA.

7.3.1 TDS Generation and Application Monitoring

7.3.1.1 TDS Generation

TDS Section

The XA-RESYNC-DELAY clause specifies the time between two resynchronization attempts by an XA commitment unit:

[ XA-RESYNC-DELAY [IS] {dec4 | 300 } ]

Transaction Section

Include the following clause to allow the transaction to use XA services: XA SERVICE USED

ORACLE-DEF ... ORACLE-ENDDEF Block

Add two new parameters for XA transactions: XA-USER IS <name30>.

XA-PASSWORD IS <name20>.

These are the user name and password used at TDS restart for connection and to request all ORACLE databases to provide the list of CUs to be resynchronized. The default values are SYSTEM/MANAGER.

This user/password needs only to have select privilege on the V$XATRANS$ view on all databases accessed.

7.3.1.2 Application Monitoring

The master commands specific to XA are documented in the TDS Administrator's Guide.

7.3.2 Server Configuration

Make sure that the V$XATRANS$ view exists on all ORACLE7 databases. You can create the view by running the SQL script xaview_sql. Execute this SQL script under the ORACLE server user sys.

The select privilege on V$XATRANS$ must be given to all ORACLE7/TDS-XA users, including the XA user/password given in the TDS generation.

For more details, see the ORACLE RDBMS Administrator's Guide. ORACLE documentation is listed in the ORACLE7 Documentation Catalog.

7.3.3 TPR Programming

7.3.3.1 CONNECT Statement and ORACLE7/TDS Cache Manager

The ORACLE7/TDS Cache Manager is designed to multiplex the users of an ORACLE7 application on a small number of ORACLE processes. A "logical connection" is defined for each CONNECT statement with a given profile (user, password, (AT)DBn, host). This connection is mapped on a physical connection to the ORACLE process which was established at the time of the first CONNECT with the given profile. The physical connection is not stopped until TDS stops or until the ORACLE7 administrator requests that it be stopped through the ORACLE transaction. Each commitment unit is represented by a CACHE entry, and all connections within this CU are represented by CONNECTION entries chained on the CACHE entry.

The connection cache contains all physical connections that are active on all ORACLE databases being accessed by TDS as follows:

• The XA connections are represented by XA CONNECTION entries chained on an XA CACHE entry which in turn represents an XA commitment unit (the transaction has been declared XA in the STDS).

• Non-XA connections are represented by non-XA CACHE entries.

The algorithm defined to reuse entries supposes that a non-XA connection cannot be reused for an XA connection even of the connection profile is the same.

Therefore the CISIZE parameter representing the CACHE size must be considered as having one part for the XA entries and another part for the non-XA entries. The cache size has a great impact on performance, so bear this factor in mind when dimensioning the cache.

Use the XA and other parameters as follows:

• the CSIZE parameter is the total size of the context cache, XA and non-XA.

• CASTAT transaction statistics:

− number of non-XA busy entries, number of non-XA free entries

− number of XA busy entries, number of XA free entries

• JOR statistics:

− number of CTX entries used for non-XA,

− number of CTX entries used for XA,

The following processing is specific to XA mode:

• up to eight database identifiers can be controlled in the processing of a CU in a TDS-XA,

• connection errors are rejected with the SQL code ORAT-28.

To obtain the explicit XA error codes, it is necessary to set the ORACLE trace level to value 2 and to restart the TPR with trace print XA domain activated. Messages are written in the TDS debug file. See the appropriate TDS Programmer's Guide for full syntax of the TDS trace commands.

7.3.3.2 Using Precompilers with ORACLE XA

When used in an ORACLE XA application, cursors are valid only for the duration of the transaction. Therefore, you must open explicit cursors after the transaction begins and close them before the commit or rollback.

You must use the option release-cursor=yes when compiling your precompiler application.

7.3.3.3 SQL-Based Restrictions

The following restrictions apply due to SQL constraints:

• Rollbacks and Commits: Because the Transaction Manager is responsible for

coordinating and managing the progress of the transaction, the application must not contain any ORACLE server-specific statement that would independently roll back or commit a transaction:

− do not use EXEC SQL ROLLBACK WORK for precompiler applications. Either arrange for the transaction to be rolled back by the initiator or call INVCMIT,

− do not use the EXEC SQL COMMIT WORK statement in a precompiler application. Use DFCMIT instead to end a transaction.

• DDL Statements: Because a DDL statement such as CREATE TABLE implies

an implicit commit, the ORACLE XA application cannot execute any SQL DDL statements.

• Savepoint: Do not use savepoint. For example, do not use EXEC SQL

SAVEPOINT <savepointname>.

• Read Only Transactions: Do not use read only transactions. For example, do

not execute SQL statements such as SET TRANSACTION READ ONLY.

• EXECSQL: Do not use the EXEC SQL command to connect or disconnect.

That is, do not use EXEC SQL COMMIT WORK RELEASE or EXEC SQL ROLLBACK WORK RELEASE.

7.3.3.4 Checking the Synchronization State

You are strongly advised to start each XA TPR with a call to the "GET-

SYNCSTATE" procedure (COBOL) or the h_get_syncstate function (C language) to obtain the synchronization state of the committed data.

See the appropriate TDS Programmer's Guide for full details.

7.3.3.5 The H_XAEVT Special Transaction

To handle situations of data consistency, you are strongly advised to rewrite the H_XAEVT special transaction using the ORACLE7/TDS-XA procedure H_OR_XARMSOFCU.

See appendix H for an example of the H_XAEVT special transaction.

The H_OR_XARMSOFCU procedure is designed to return a list of all the RMs being accessed by a given CU, together with the state of this CU in relation to the RMs accessed.

The call to H_OR_XARMSOFCU must occur in the first TPR of the H_XAEVT transaction.

H_OR_XARMSOFCU (RMLIST_PTR, RMNB)

Parameters:

RMLIST_PTR is an input parameter that provides a pointer to an area that will be filled by ORACLE/TDS-XA with RMNB entries, one for each RM accessed during the currency of this CU. The area is allocated by the caller (a TPR in C or COBOL) and is sized for a maximum of eight entries of the following type:

XA_ENTRY

XA_GBLFORID PIC X(40) global transaction id XA_DBID PIC X(8) database identifier XA_RMIDENT PIC X(44) RM identifier XA_STATUS COMP-1 Status of last commit for

this RM

RMNB is an output parameter receiving the effective number of RMs accessed during the currency of the CU and corresponding to the number of entries in the array pointed by RMLIST_PTR.

The troubleshooting of distributed transaction problems is then handled as follows:

• when XA_STATUS is not done, XA_RMIDENT identifies the desynchronized RM,

• the database manager checks the RM and verifies the status of the transaction indicated by XA_GBLFORID in the DBA_2PC_PENDING table,

• he takes a heuristic decision or arranges for the communication link to be restored, then waits for completion of resynchronization.

For a full description of the H_XAEVT transaction, see the appropriate TDS Programmer's Guide.

7.4 HA And XCP2 Compatibility