Starting the Transaction


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Programming BEA Tuxedo ATMI Applications Using COBOL \| Local Topics \| Previous Topic \| Next Topic \| Contents

To start a global transaction, use the TPBEGIN(3cbl) routine with the following signature:

*
  01 TPTRXDEF-REC.
     COPY TPTRXDEF.
*
  01 TPSTATUS-REC.
     COPY TPSTATUS.
*
   CALL "TPBEGIN" USING TPTRXDEF-REC TPSTATUS-REC.

The following table describes the TPTRXDEF-REC structure fields

TPTRXDEF Structure Field

Field

Description

T-OUT

Specifies the amount of time, in seconds, a transaction can execute before timing out. You can set this value to the maximum number of seconds allowed by the system, by specifying a value of 0. In other words, you can set timeout to the maximum value for an unsigned long as defined by the system.

The use of 0 or an unrealistically large value for the T-OUT parameter delays system detection and reporting of errors. The system uses the T-OUT parameter to ensure that responses to service requests are sent within a reasonable time, and to terminate transactions that encounter problems such as network failures before executing a commit.

For a transaction in which a person is waiting for a response, you should set this parameter to a small value: if possible, less than 30 seconds.

In a production system, you should set T-OUT to a value large enough to accommodate expected delays due to system load and database contention. A small multiple of the expected average response time is often an appropriate choice.

Note: The value assigned to the T-OUT parameter should be consistent with that of the SCANUNIT parameter set by the BEA Tuxedo application administrator in the configuration file. The SCANUNIT parameter specifies the frequency with which the system checks, or scans, for timed-out transactions and blocked calls in service requests. The value of this parameter represents the interval of time between these periodic scans, referred to as the scanning unit.

You should set the T-OUT parameter to a value that is greater than the scanning unit. If you set the T-OUT parameter to a value smaller than the scanning unit, there will be a discrepancy between the time at which a transaction times out and the time at which this timeout is discovered by the system. The default value for SCANUNIT is 10 seconds. You may need to discuss the setting of the T-OUT parameter with your application administrator to make sure the value you assign to the T-OUT parameter is compatible with the values assigned to your system parameters.

TRANID

Transaction identifier.

Field	Description
T-OUT	Specifies the amount of time, in seconds, a transaction can execute before timing out. You can set this value to the maximum number of seconds allowed by the system, by specifying a value of 0. In other words, you can set timeout to the maximum value for an unsigned long as defined by the system. The use of 0 or an unrealistically large value for the T-OUT parameter delays system detection and reporting of errors. The system uses the T-OUT parameter to ensure that responses to service requests are sent within a reasonable time, and to terminate transactions that encounter problems such as network failures before executing a commit. For a transaction in which a person is waiting for a response, you should set this parameter to a small value: if possible, less than 30 seconds. In a production system, you should set T-OUT to a value large enough to accommodate expected delays due to system load and database contention. A small multiple of the expected average response time is often an appropriate choice. Note: The value assigned to the T-OUT parameter should be consistent with that of the SCANUNIT parameter set by the BEA Tuxedo application administrator in the configuration file. The SCANUNIT parameter specifies the frequency with which the system checks, or scans, for timed-out transactions and blocked calls in service requests. The value of this parameter represents the interval of time between these periodic scans, referred to as the scanning unit. You should set the T-OUT parameter to a value that is greater than the scanning unit. If you set the T-OUT parameter to a value smaller than the scanning unit, there will be a discrepancy between the time at which a transaction times out and the time at which this timeout is discovered by the system. The default value for SCANUNIT is 10 seconds. You may need to discuss the setting of the T-OUT parameter with your application administrator to make sure the value you assign to the T-OUT parameter is compatible with the values assigned to your system parameters.
TRANID	Transaction identifier.

Any process may call TPBEGIN unless the process is already in transaction mode. If TPBEGIN is called in transaction mode, the call fails due to a protocol error and TP-STATUS is set to TPEPROTO. If the process is in transaction mode, the transaction is unaffected by the failure.

The following example provides a high-level view of how a global transaction is defined.

Delineating a Transaction

. . .
MOVE 0 TO T-OUT.
CALL "TPBEGIN" USING
TPTRXDEF-REC
TPSTATUS-REC.
IF  NOT TPOK
    error processing
. . .
    program statements
. . .
CALL "TPCOMMIT" USING
                TPTRXDEF-REC
                TPSTATUS-REC.
IF  NOT TPOK
    error processing

The following example shows how an outstanding reply can cause an error.

Error - Starting a Transaction with an Outstanding Reply

  . . .
  MOVE "BUY" TO SERVICE-NAME.
  SET TPBLOCK TO TRUE.
  SET TPNOTRAN TO TRUE.
  SET TPREPLY TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
  CALL "TPACALL" USING
                 TPSVCDEF-REC
                 TPTYPE-REC
                 BUY-REC
                 TPSTATUS-REC.
  IF  NOT TPOK
      error processing
  . . .
  MOVE 0 TO T-OUT.
  CALL "TPBEGIN" USING
                 TPTRXDEF-REC
                 TPSTATUS-REC.
  IF  NOT TPOK
      error processing
* ERROR TP-STATUS is set to TPEPROTO
  . . .
      program statements
  . . .
  SET TPBLOCK TO TRUE.
  SET TPNOTRAN TO TRUE.
  SET TPCHANGE TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
  SET TPGETANY TO TRUE.
  CALL "TPGETRPLY" USING
                   TPSVCDEF-REC
                   TPTYPE-REC
                   WK-AREA
                   TPSTATUS-REC.
  IF  NOT TPOK
      error processing

If a transaction times out, a call to TPCOMMIT causes the transaction to be aborted. As a result, TPCOMMIT fails and sets TP-STATUS to TPEABORT.

The following example shows how to test for a transaction timeout. Note that the value of T-OUT is set to 30 seconds.

Testing for Transaction Timeout

. . .
MOVE 30 TO T-OUT.
CALL "TPBEGIN" USING TPTRXDEF-REC TPSTATUS-REC.
IF  NOT TPOK
    MOVE "Failed to BEGIN a transaction" TO LOG-REC-TEXT.
    MOVE 29 to LOG-REC-LEN
    CALL "USERLOG" USING
                   LOG-REC-TEXT
                   LOG-REC-LEN
                   TPSTATUS-REC
    CALL "TPTERM" USING
                  TPSTATUS-REC
    PERFORM A-999-EXIT.
. . .
       communication CALL statements
. . .
IF  TPETIME
    CALL "TPABORT" USING
                   TPTRXDEF-REC
                   TPSTATUS-REC
IF  NOT TPOK
       error processing
ELSE
   CALL "TPCOMMIT" USING
                   TPTRXDEF-REC
                   TPSTATUS-REC
   IF  NOT TPOK
        error processing

Note: When a process is in transaction mode and makes a communication call with TPNOTRAN, it prohibits the called service from becoming a participant in the current transaction. Whether the service request succeeds or fails has no impact on the outcome of the transaction. The transaction can still timeout while waiting for a reply that is due from a service, whether it is part of the transaction or not. Refer to Managing Errors for more information on the effects of the TPNOTRAN flag.

The following example shows how to define a transaction.

Defining a Transaction

 DATA DIVISION.
 WORKING-STORAGE SECTION.
*
 01  TPTYPE-REC.
 COPY TPTYPE.
*
 01 TPSTATUS-REC.
 COPY TPSTATUS.
*
 01 TPINFDEF-REC.
 COPY TPINFDEF.
*
 01  TPSVCDEF-REC.
 COPY TPSVCDEF.
*
 01  TPTRXDEF-REC.
 COPY TPTRXDEF.
*
 01 LOG-REC              PIC X(30) VALUE " ".
 01 LOG-REC-LEN          PIC S9(9)  COMP-5.
*
 01 USR-DATA-REC         PIC X(16).
*
 01 AUDV-REC.
     05  AUDV-BRANCH-ID      PIC S9(9) COMP-5.
     05  AUDV-BALANCE        PIC S9(9) COMP-5.
     05  AUDV-ERRMSG         PIC X(60).
*
 PROCEDURE DIVISION.
*
 A-000.
  . . .
* Get Command Line Options  set Variables (Q-BRANCH)
  MOVE SPACES TO USRNAME.
  MOVE SPACES TO CLTNAME.
  MOVE SPACES TO PASSWD.
  MOVE SPACES TO GRPNAME.
  CALL "TPINITIALIZE" USING TPINFDEF-REC
                      USR-DATA-REC
                      TPSTATUS-REC.
  IF  NOT TPOK
      MOVE "Failed to join application" TO LOG-REC
      MOVE 26 TO LOG-REC-LEN
       CALL "USERLOG" USING LOG-REC
                      LOG-REC-LEN
                      TPSTATUS-REC
       PERFORM A-999-EXIT.
* Start global transaction
  MOVE 30 TO T-OUT.
  CALL "TPBEGIN" USING TPTRXDEF-REC TPSTATUS-REC.
  IF  NOT TPOK
      MOVE 29 to LOG-REC-LEN
      MOVE "Failed to begin a transaction" TO LOG-REC
      CALL "USERLOG" USING LOG-REC
                     LOG-REC-LEN
                     TPSTATUS-REC
      PERFORM DO-TPTERM.
* Set up record
  MOVE Q-BRANCH TO AUDV-BRANCH-ID.
  MOVE ZEROS TO AUDV-BALANCE.
  MOVE SPACES TO AUDV-ERRMSG.
* Set up TPCALL records
  MOVE "GETBALANCE" TO SERVICE-NAME.
  MOVE "VIEW" TO REC-TYPE.
  MOVE LENGTH OF AUDV-REC TO LEN.
  SET TPBLOCK TO TRUE.
  SET TPTRAN IN TPSVCDEF-REC TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
  SET TPCHANGE TO TRUE.
*
  CALL "TPCALL" USING TPSVCDEF-REC
                TPTYPE-REC
                AUDV-REC
                TPTYPE-REC
                AUDV-REC
                TPSTATUS-REC.
  IF  NOT TPOK
      MOVE 19 to LOG-REC-LEN
      MOVE "Service call failed" TO LOG-REC
      CALL "USERLOG" USING LOG-REC
                     LOG-REC-LEN
                     TPSTATUS-REC
      PERFORM DO-TPABORT
      PERFORM DO-TPTERM.
* Commit global transaction
  CALL "TPCOMMIT" USING TPTRXDEF-REC
                  TPSTATUS-REC
  IF  NOT TPOK
      MOVE 16 to LOG-REC-LEN
      MOVE "Failed to commit" TO LOG-REC
      CALL "USERLOG" USING LOG-REC
                LOG-REC-LEN
                TPSTATUS-REC
      PERFORM DO-TPTERM.
* Show results only when transaction has completed successfully
  DISPLAY "BRANCH=" Q-BRANCH.
  DISPLAY "BALANCE=" AUDV-BALANCE.
  PERFORM DO-TPTERM.
* Abort the transaction
 DO-TPABORT.
  CALL "TPABORT" USING TPTRXDEF-REC
                 TPSTATUS-REC
  IF  NOT TPOK
      MOVE 26 to LOG-REC-LEN
      MOVE "Failed to abort transaction" TO LOG-REC
      CALL "USERLOG" USING LOG-REC
                     LOG-REC-LEN
                     TPSTATUS-REC.
* Leave the application
 DO-TPTERM.
  CALL "TPTERM" USING TPSTATUS-REC.
  IF  NOT TPOK
      MOVE 27 to LOG-REC-LEN
      MOVE "Failed to leave application" TO LOG-REC
      CALL "USERLOG" USING LOG-REC
                     LOG-REC-LEN
                     TPSTATUS-REC.
                     EXIT PROGRAM.
*
 A-999-EXIT.
*
 EXIT PROGRAM.