Release 9.0.1.0.1 for UNIX
Part Number A90397-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Procedural Gateway for APPC User's Guide Release 9.0.1.0.1 for UNIX Part Number A90397-01 |
|
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. This chapter assumes that you are familiar with the basic concepts of two-phase commit as discussed in Oracle 9i Server Concepts. This chapter includes the following sections:
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.
Since commit-confirm uses LU6.2 synclevel 1, it can be supported by any OLTP that supports APPC, including CICS/ESA and IMS/TM. The Oracle Procedural Gateway for APPC provides sample commit-confirm applications for both CICS/ESA and IMS/TM.
With CICS/ESA, 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 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 IMS/ESA 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.
The following components are required to support commit-confirm:
The gateway server supports commit-confirm when PGA_CAPABILITY=COMMIT_CONFIRM is specified in the gateway initialization file. When the gateway server is running with commit-confirm enabled, it will connect to a local Oracle integrating server where it maintains a commit-confirm transaction log, similar to the Oracle two-phase commit log stored in the DBA_2PC_PENDING table. The gateway's transaction log is stored in the PGA_CC_PENDING table. A row is stored in this table for each in-flight transaction and remains there until the transaction has completed. The life span of rows in PGA_CC_PENDING is normally quite short, lasting only from the time the commit is received by the gateway until the time the integrating server completes all commit processing and tells the gateway to forget the transaction.
The commit-confirm gateway SID should be reserved for use only to invoke update transactions that implement commit-confirm. There is some extra overhead involved in the setup for logging when PGA_CAPABILITY is set to COMMIT_CONFIRM. Read-only transactions should be invoked through a separate gateway SID with PGA_CAPABILITY set to READ_ONLY so that they will not incur the extra overhead.
An Oracle server must be available for use by the gateway server for storing the PGA_CC_PENDING table. For maximum performance and reliability, Oracle Corporation recommends that this Oracle server reside on the same machine as the gateway server.
A commit-confirm transaction log database must be defined to the OLTP system being accessed. This database must be recoverable and must be accessible by the OLTP as part of the same unit of work as the OLTP application's databases, so that updates to the transaction log database will be kept in sync with updates to the application's databases in a single unit of work.
The commit-confirm transaction log database need contain only the Oracle Global Transaction ID and a date/time stamp. The Oracle Global Transaction ID is 169 bytes long and must be the key field. The date/time stamp is used for purging old entries that can be left in the log after certain failure scenarios.
For simplicity, all commit-confirm applications under a particular OLTP should share the same commit-confirm transaction log.
Code must be added to each OLTP transaction invoked by a commit-confirm gateway to perform the transaction logging required by the gateway's commit-confirm implementation. This code must receive the Oracle Global Transaction ID from the gateway and write that information into the OLTP commit-confirm transaction log database. For maximum flexibility and ease of use, this code can be written as a subroutine callable from any commit-confirm transaction on your OLTP system.
This code must be executed at the beginning of each commit-confirm transaction prior to the first APPC receive and then immediately after each COMMIT or ROLLBACK in the transaction. This ensures that the logging is done at the beginning of each unit of work.
A separate APPC transaction must be created on the OLTP system that can be started by the gateway to forget a transaction once it has been successfully committed and to query a transaction's state during recovery processing. This transaction deletes the entry for a particular Oracle Global Transaction ID from the OLTP commit-confirm transaction log database during forget processing and queries the entry for a particular Oracle Global Transaction ID from the OLTP commit-confirm transaction log database during recovery processing.
The steps for configuring commit-confirm include:
All of these steps must be performed before attempting to use any applications that use commit-confirm.
The Oracle integrating server where the gateway server will store its transaction log information should ideally be on the same machine where the gateway runs. The configuration of the server consists of creating the gateway DBA user, creating the commit-confirm log tables and creating the PL/SQL stored procedure used by the gateway server for logging transactions.
The pgaccau.sql script from the $ORACLE_HOME/pg4appc/admin directory creates the gateway DBA user IF. The default user ID is PGADBA with the initial password set to PGADBA. If you want to change the user ID or initial password, you must modify the script.
The gateway initialization parameters are discussed in Appendix A, "Gateway Initialization Parameters," of the Oracle Procedural Gateway for APPC Installation and Configuration Guide for your platform. The parameters necessary for commit-confirm support in the gateway are:
These parameters should be added to your initsid.ora file, where sid is the gateway SID for your commit-confirm gateway.
PGA_CAPABILITY must be set to COMMIT_CONFIRM to enable commit-confirm.
PGA_LOG_DB specifies a Oracle Net service name that is used by the gateway server to connect to the Oracle integrating server where the PGA_CC_PENDING table and the PGA_CC_LOG PL/SQL procedure are stored. The service name must be defined in a tnsnames.ora file that is accessible to the gateway server. The gateway server accesses the tnsnames.ora file through the TNS_ADMIN environment variable setting. TNS_ADMIN must specify the full path name of the directory in which the tnsnames.ora file is stored.
PGA_LOG_USER specifies the Oracle user ID that will be used by the gateway when connecting to the Oracle integrating server identified by the PGA_LOG_DB parameter. This user ID is the PGADBA user ID created by the pgaccau.sql script. The user ID specified must be the same user ID under which the pgaccpnd.sql and pgacclog.sql scripts were run.
PGA_LOG_PASS specifies the Oracle password that is used by the gateway when connecting to the Oracle integrating server identified by the PGA_LOG_DB parameter. This is the password for the Oracle user ID specified by PGA_LOG_USER.
PGA_RECOVERY_USER specifies the user ID that is used by the gateway when allocating an LU6.2 conversation with the transaction specified by the PGA_RECOVERY_TPNAME parameter. This parameter is necessary only if the PGA_SECURITY_TYPE parameter has been set to "PROGRAM".
PGA_RECOVERY_PASS specifies the password that is used by the gateway when allocating an LU6.2 conversation with the transaction specified by the PGA_RECOVERY_TPNAME parameter. This parameter is necessary only if the PGA_SECURITY_TYPE parameter has been set to "PROGRAM".
PGA_RECOVERY_TPNAME specifies the TP name of the transaction installed in the OLTP for performing operations against the commit-confirm transaction log database on the OLTP side. The default value is RECO, which is the name used by the installation procedure for the sample transaction shipped with the gateway. Note that when the OLTP is CICS/ESA, the TP name is limited to four characters, and when the OLTP is IMS/TM, the TP name is limited to eight characters. Other OLTPs may have other limits on the length of the TP name.
Configuration of the OLTP includes the following:
Detailed instructions for configuring CICS/ESA and IMS/TM are provided in the $ORACLE_HOME/pg4appc/demo/CICS/README.doc and $ORACLE_HOME/pg4appc/demo/IMS/README.doc files, respectively.
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.
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.
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 machine 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.
There is a specific set of interactions that occur between the components. They are:
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.
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.
The flow of control for a successful commit between an Oracle application and an OLTP transaction is shown in Figure 5-1, "Commit-Confirm Flow with Synclevel 1". This figure assumes that both Oracle and OLTP resources have been updated. The steps below outline the commit-confirm logic flow.
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:
This is the Oracle Global Transaction ID for the transaction. It is identical to the corresponding column in the DBA_2PC_PENDING table.
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.
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.
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.
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.
Samples are provided with the gateway for CICS/ESA and IMS/TM for implementing commit-confirm support. They are in the following directories, respectively: $ORACLE_HOME/pg4appc/demo/CICS and $ORACLE_HOME/pg4appc/demo/IMS. A README.doc file in each directory provides detailed information about installing and using the samples. JCL files for compiling and linking the sample programs are provided as well. The samples included with the gateway assist you with the following:
For CICS/ESA, the subroutine provided is called using the EXEC CICS LINK interface. For IMS/TM, the subroutine provided is called using the standard CALL statement or its equivalent in your application's programming language. Both of these subroutines are written in 370 assembler to eliminate any inter-language interface complexities and compiler dependencies.
DB2C, is provided in the pgadb2c.cob file. This is a COBOL example that updates the DB2 sample EMP table. For IMS/TM, a sample DLI update transaction, PGAIMSU, is provided in the pgaimsu.cob file. This is a COBOL example that updates the DLI sample PARTS database.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|