Skip Headers
Oracle Procedural Gateway® for APPC User's Guide
10g Release 2 (10.2) for UNIX

Part Number B16210-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

5 Implementing Commit-Confirm (SNA Only)

Commit-confirm allows the updating of local Oracle resources to occur in the same Oracle transaction as the updating of non-Oracle resources accessed through the Oracle Procedural Gateway for APPC.

Read this chapter to familiarize yourself with the elements and functions of commit-confirm.

This chapter includes the following sections:

5.1 Overview of Commit-Confirm

Important:

If you are planning to implement commit-confirm, then you should already have configured the components. Refer to Chapter 11, "Gateway Configuration Using SNA Communication Protocol" in the Oracle Procedural Gateway for APPC Installation and Configuration Guide for instructions on its configuration.

Commit-confirm is a special implementation of two-phase commit that allows a database or gateway that does not support full two-phase commit to participate in distributed update transactions with other databases or gateways that do support full two-phase commit. In this implementation, the commit-confirm site is always the first to be committed, after all other sites have been prepared.This allows all sites to be kept in sync, because if the commit-confirm site fails to commit successfully, all other sites can be rolled back.

Within an Oracle distributed transaction, all work associated with that transaction is assigned a common identifier, known as the Oracle Global Transaction ID. This identifier is guaranteed to be unique, so that it can be used to exclusively identify a particular distributed transaction. The key requirement for commit-confirm support is the ability for the commit-confirm site (in this case, the Oracle Procedural Gateway for APPC) to be able to log the Oracle Global Transaction ID as part of its unit of work, so that if a failure occurs, the gateway's recovery processing can determine the status of a particular Oracle Global Transaction ID by the presence or absence of a log entry for that transaction. A new Oracle Global Transaction ID is generated after every commit or rollback operation.

The Oracle Procedural Gateway for APPC implements commit-confirm using LU6.2 synclevel 1. This is similar to the implementation of single-site update, with the added advantage that resources on both the Oracle site and the OLTP being accessed by the gateway can be updated and kept in sync. The main difference is that the commit-confirm implementation requires some additional programming in the OLTP transaction to perform the transaction logging necessary for recovery support.

5.2 Supported OLTPs

Since commit-confirm uses LU6.2 synclevel 1, it can be supported by any OLTP that supports APPC, including CICS Transaction Server for z/OS and IMS/TM. The Oracle Procedural Gateway for APPC provides sample commit-confirm applications for both CICS Transaction Server for z/OS and IMS/TM.

With CICS Transaction Server for z/OS, the standard command-level EXEC CICS interface can be used for all APPC communications. In addition, the CPI-C interface can be used if it is preferred. A sample DB2 update transaction written in COBOL using the EXEC CICS interface is provided with the gateway. Any language supported by CICS Transaction Server for z/OS can be used for writing commit-confirm transactions.

With IMS/TM, the CPI-C interface must be used, making the IMS transaction an "explicit APPC transaction," as referred to in the IBM IMSCICS Transaction Server for z/OS manuals. This is necessary because it is the only way that the LU6.2 synclevel 1 control flows are accessible to the IMS transaction. When using "implied APPC" where "GU" from the IOPCB and "ISRT" to the IOPCB are used for receiving and sending data, there is no way for the IMS transaction to access the LU6.2 synclevel 1 control flow, making it impossible to use this method for commit-confirm. A sample DLI database update transaction written in COBOL using the CPI-C APPC interface is provided with the gateway. Any language supported by IMS and CPI-C can be used for writing commit-confirm transactions.

5.3 Components Required to Support Commit-Confirm

The following components are required to support commit-confirm:

5.4 Application Design Requirements

When designing commit-confirm applications for use with the Oracle Procedural Gateway for APPC, there are some requirements you must meet to provide the ability for the gateway to determine the state of a transaction in the event of a failure. If these requirements are not met, attempting to use an application with a commit-confirm gateway will produce unpredictable results.

The first thing that must be done by an OLTP transaction invoked by a commit-confirm gateway is to receive the Oracle Global Transaction ID from the gateway and log it into the OLTP commit-confirm transaction log database. This must be done before the normal data flow between the OLTP transaction and the Oracle application begins. The gateway always sends the Oracle Global Transaction ID as the very first data item.

If the OLTP transaction is a one-shot transaction, this is the only change needed. If the transaction is a persistent transaction that performs more than one unit of work (issues more than one commit or rollback), then a new Oracle Global Transaction ID must be received and logged after every commit or rollback.

The Oracle Global Transaction ID is sent by the gateway in a variable-length record with a maximum length of 202 bytes. The first 32 bytes contain a special binary string used to verify that the data came from the gateway and not from some other application. The next 1 byte is a reserved field. The Oracle Global Transaction ID is next, with a maximum length of 169 bytes. You must log the reserved field and the Oracle Global Transaction ID, as well as a date/time stamp and any other information you wish to log. Note that the Oracle Global Transaction ID must be the key field for the log database so that the forget/recovery transaction can use the Oracle Global Transaction ID to directly access a log entry.

Note:

If your OLTP is IMS/TM, you must add a PCB for the commit-confirm transaction log database to the PSB for each transaction that you will use with a commit-confirm gateway. This PCB must be the first PCB in the PSB.

5.5 Commit-Confirm Architecture

The architecture of the commit-confirm implementation in the Oracle Procedural Gateway for APPC consists of three main components:

This section describes the role each component plays in the operation of commit-confirm and how these components interact.

5.5.1 Components

The Oracle Integrating Server is the controlling component in the commit-confirm architecture. It tells the gateway server when to commit a transaction and when to rollback a transaction. It does the same with all other servers participating in a distributed transaction. When a failure has occurred, it is the integrating server which drives the recovery process in each participating server, including the gateway server.

The gateway server performs the task of converting instructions from the Oracle Integrating Server into LU6.2 operations and then logs the transaction into the Oracle logging server. The gateway server stores the log information in a table called PGA_CC_PENDING on the logging server. If a failure occurs during transaction processing, the gateway server determines which error should be returned to the integrating server.

The Oracle logging server is an Oracle server available to the gateway server for storing and accessing its commit-confirm log information. The logging server need not be the same Oracle server as the integrating server, but can be. Because the logging server is an integral component of gateway commit-confirm operations, the best place for it to reside is on the same system as the gateway server. This allows the communication between the gateway server and the logging server to use interprocess communications, providing a high-speed, low overhead, local connection between the components.

5.5.2 Interactions

There is a specific set of interactions that occur between the components. They are:

  • Oracle Integrating Server <--> Gateway Server

    The Oracle Integrating Server drives all actions by the gateway server. At the request of the Oracle application, the integrating server can instruct the gateway server to begin a new Oracle transaction, start a commit sequence, start a rollback sequence, or start a forget sequence. It can also call gateway remote procedural call (RPC) functions (PGAINIT, PGAXFER, PGATERM) on behalf of the Oracle application.

  • Gateway Server <--> Oracle Logging Server

    The gateway server calls the Oracle logging server to insert and delete rows from its PGA_CC_PENDING table. This is actually done by calling a PL/SQL stored procedure, PGA_CC_LOG, in the logging server to reduce the number of open cursors required by the gateway server for performing its logging. Only a single cursor is needed by the gateway server for logging.

5.6 Commit-Confirm Flow

The flow of control for a successful commit between an Oracle application and an OLTP transaction is described in the following section and illustrated in Figure 5-1, "Commit-Confirm Flow with Synclevel 1". The figure assumes that both Oracle and OLTP resources have been updated. The following steps in section 4 outline the commit-confirm logic flow.

5.6.1 Commit-Confirm Logic Flow, Step by Step

  1. The application issues a COMMIT to the Oracle Integrating Server.

  2. The Oracle Integrating Server sends PREPARE to each participant in the distributed transaction other than the gateway.

  3. Each participant prepares its database updates and responds PREPARE OK to the Oracle Integrating Server.

  4. The Oracle Integrating Server sends COMMIT to the gateway. The gateway receives the COMMIT from the Oracle Integrating Server and inserts a new pending transaction row into the PGA_CC_PENDING table.

  5. The gateway sends an APPC CONFIRM to the OLTP application. The OLTP application receives the CONFIRM request in the form of a status from the last APPC RECEIVE.

  6. The OLTP application issues a COMMIT using an appropriate OLTP function. The OLTP commits all database updates made by the application since the last COMMIT, including the commit-confirm transaction log update.

  7. Once the database updates have been committed, the OLTP returns control to the application with a return code indicating the status of the COMMIT.

  8. The OLTP application sends an APPC CONFIRMED to the gateway.

  9. The gateway receives the CONFIRMED and returns COMMIT OK to the Oracle Integrating Server.

  10. The Oracle Integrating Server sends COMMIT to each participant in the distributed transaction other than the gateway.

  11. Each participant commits its database updates and responds COMMIT OK to the Oracle Integrating Server.

  12. The Oracle Integrating Server sends a FORGET to the gateway.

  13. The gateway receives the FORGET and starts a new APPC conversation with the FORGET/RECOVERY transaction at the OLTP, sends it a FORGET request and an APPC CONFIRM. The FORGET/RECOVERY transaction receives the FORGET request and deletes the entry from the commit-confirm transaction log for the current Oracle transaction, and commits the delete.

  14. The FORGET/RECOVERY transaction sends an APPC CONFIRMED to the gateway to indicate that the FORGET was processed, and then terminates. The gateway receives the CONFIRMED and deletes the pending transaction row from the PGA_CC_PENDING table.

  15. The gateway returns FORGET OK to the Oracle Integrating Server.

  16. The Oracle Integrating Server returns control to the Oracle application.

Figure 5-1, "Commit-Confirm Flow with Synclevel 1" illustrates the Commit-Confirm logic flow described in the previous section.

Figure 5-1 Commit-Confirm Flow with Synclevel 1

Description of 5_1comm.gif follows
Description of the illustration 5_1comm.gif

5.6.2 Gateway Server Commit-Confirm Transaction Log

The commit-confirm transaction log consists of a single table, PGA_CC_PENDING. This table contains a row for each in-flight Oracle transaction that includes the commit-confirm gateway. The table is maintained by the gateway server and is similar in function to the Oracle server's DBA_2PC_PENDING table. Note that a row is not inserted into this table until a COMMIT is received by the gateway and the row is deleted when a FORGET is received by the gateway. There is no involvement by the gateway during the PREPARE phase.

The PGA_CC_PENDING table contains the following columns:

  • GLOBAL_TRAN_ID

    This is the Oracle Global Transaction ID for the transaction. It is identical to the corresponding column in the DBA_2PC_PENDING table.

  • SIDE_NAME

    This is the Side Information Profile name that was used by the gateway to allocate the APPC conversation with the target LU. It corresponds to the SIDENAME parameter passed to the PGAINIT gateway function.

  • LU_NAME

    This is the fully-qualified partner LU name of the target LU. This value is either the LU name from the Side Information Profile or the LUNAME parameter passed to the PGAINIT gateway function. This name fully identifies the OLTP system on which the transaction was executed.

  • MODE_NAME

    This is the Mode name that was used by the gateway to allocate the APPC conversation with the target LU. The value is either the Mode name from the Side Information Profile or the MODENAME parameter passed to the PGAINIT gateway function.

  • TP_NAME

    This is the transaction program name executed at the target LU. The value is either the TP name from the Side Information Profile or the TPNAME parameter passed to the PGAINIT gateway function. This name fully identifies the OLTP transaction program that was executed.