Terminating a Service Routine


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using COBOL

The TPRETURN(3cbl), TPCANCEL(3cbl), and TPFORWAR(3cbl) routines specify that a service routine has completed with one of the following actions:

TPRETURN sends a reply to the calling client.
TPCANCEL cancels the current request.
TPFORWAR forwards a request to another service for further processing.

Sending Replies

The TPRETURN(3cbl) and TPFORWAR(3cbl) calls are COBOL copy files that contain EXIT statements to mark the end of a service routine and send a message to the requester or forward the request to another service, respectively. Use the following signature to call the TPRETURN routine.

 01 TPSVCRET-REC.
    COPY TPSVCRET.
 01 TPTYPE-REC.
    COPY TPTYPE.
 01 DATA-REC.
    COPY User Data.
 01 TPSTATUS-REC.
    COPY TPSTATUS.
 COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
               TPTYPE-REC BY TPTYPE-REC
               DATA-REC BY DATA-REC
                TPSTATUS-REC BY TPSTATUS-REC.

Note: You must use COPY here instead of CALL to ensure that the EXIT statement is called properly, and the COBOL service routine returns control to the BEA Tuxedo system.

The following listing provides the TPSVCRET-REC record signature.

 05 TPRETURN-VAL    PIC S9(9) COMP-5.
   88 TPSUCCESS     VALUE 0.
   88 TPFAIL        VALUE 1.
   88 TPFAIL        VALUE 2.
 05 APPL-CODE      PIC S9(9) COMP-5.

The following table describes the members of a TPSVCRET-REC data structure.

TPSVCRET-REC Data Structure Members

Member
Description

TP-RETURN-VAL

Indicates whether or not the service has completed successfully on an application-level. The value is an integer that is represented by a symbolic name. Valid settings include:

TPSUCCESS - The calling routine succeeded. The routine stores the reply message in the caller's record. If there is a reply message, it is in the caller's record.
TPFAIL (default) - The service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply. In this case, the client's TPCALL or TPGETRPLY routine call fails and the system sets the TP-STATUS variable to TPESVCFAIL to indicate an application-defined failure. If a reply message was expected, it is available in the caller's record.
TPEXIT - The service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply, and exits.

For a description of the effect that the value of this argument has on global transactions, refer to Writing Global Transactions.

APPLC-CODE

Returns an application-defined return code to the caller. The client can access the value returned in APPLC-CODE by querying APPL-RETURN-CODE IN TPSTATUS-REC. The routine returns this code regardless of success or failure.

Member	Description
TP-RETURN-VAL	Indicates whether or not the service has completed successfully on an application-level. The value is an integer that is represented by a symbolic name. Valid settings include: TPSUCCESS - The calling routine succeeded. The routine stores the reply message in the caller's record. If there is a reply message, it is in the caller's record. TPFAIL (default) - The service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply. In this case, the client's TPCALL or TPGETRPLY routine call fails and the system sets the TP-STATUS variable to TPESVCFAIL to indicate an application-defined failure. If a reply message was expected, it is available in the caller's record. TPEXIT - The service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply, and exits. For a description of the effect that the value of this argument has on global transactions, refer to Writing Global Transactions.
APPLC-CODE	Returns an application-defined return code to the caller. The client can access the value returned in APPLC-CODE by querying APPL-RETURN-CODE IN TPSTATUS-REC. The routine returns this code regardless of success or failure.

Refer to Defining a Service for a description of the TPTYPE-REC record.

The primary function of a service routine is to process a request and return a reply to a client process. It is not necessary, however, for a single service to do all the work required to perform the requested function. A service can act as a requester and pass a request call to another service the same way a client issues the original request: through calls to TPCALL or TPACALL.

Note: The TPCALL and TPACALL routines are described in detail in Writing Request/Response Clients and Servers.

When TPRETURN is called, control always returns to the controlling program. If a service has sent requests with asynchronous replies, it must receive all expected replies or invalidate them with TPCANCEL before returning control to the controlling program. Otherwise, the outstanding replies are automatically dropped when they are received by the BEA Tuxedo system controlling program, and an error is returned to the caller.

If the client invokes the service with TPCALL, after a successful call to TPRETURN, the reply message is available in the O-DATA-REC record. If TPACALL is used to send the request, and TPRETURN returns successfully, the reply message is available in the DATA-REC record of TPGETRPLY.

If a reply is expected and TPRETURN encounters errors while processing its arguments, it sends a failed message to the calling process. The caller detects the error by checking the value placed in TP-STATUS. In the case of failed messages, the system sets the TP-STATUS to TPESVCERR. This situation takes precedence over the value of APPL-RETURN-CODE IN TPSTATUS-REC. If this type of error occurs, no reply data is returned, and both the contents and length of the caller's output record remain unchanged.

If TPRETURN returns a message in a record of an unknown type or a record that is not allowed by the caller (that is, if the call is made with TPNOCHANGE), the system returns TPEOTYPE in TP-STATUS. In this case, application success or failure cannot be determined, and the contents and length of the output record remain unchanged.

The value returned in APPL-RETURN-CODE IN TPSTATUS-REC is not relevant if the TPRETURN routine is invoked and a time-out occurs for the call waiting for the reply. This situation takes precedence over all others in determining the value that is returned in TP-STATUS. In this case, TP-STATUS is set to TPETIME and the reply data is not sent, leaving the contents and length of the caller's reply record unchanged. There are two types of time-outs in the BEA Tuxedo system: blocking and transaction time-outs (discussed in Writing Global Transactions).

The example code in this section shows the TRANSFER service that is part of the XFER server. Basically, the TRANSFER service makes synchronous calls to the WITHDRAWAL and DEPOSIT services. It allocates a separate record for the reply message since it must use the request record for the calls to both the WITHDRAWAL and the DEPOSIT services. If the call to WITHDRAWAL fails, the service writes the message cannot withdraw on the status line of the form and sets TP-RETURN-VAL IN TPSVCRET-REC of the TPRETURN routine to TPFAIL. If the call succeeds, the debit balance is retrieved from the reply record.

Note: In the following example, the application moves the identifier for the "destination account" (which is retrieved from the cr_id variable) to the zeroth occurrence of the ACCOUNT_ID field in the transf fielded record. This move is necessary because this occurrence of the field in an FML record is used for data-dependent routing. Refer to Setting Up a BEA Tuxedo Application for more information.

A similar scenario is followed for the call to DEPOSIT. On success, the service sets the TP-RETURN-VAL IN TPSVCRET-REC to TPSUCCESS, returning the pertinent account information to the status line.

TPRETURN Routine

IDENTIFICATION DIVISION.
PROGRAM-ID. TRANSFER.
AUTHOR. TUXEDO DEVELOPMENT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. USL-486.
OBJECT-COMPUTER. USL-486.
*
INPUT-OUTPUT SECTION.
. . .
******************************************************
* Tuxedo definitions
******************************************************
01 TPSVCRET-REC.
COPY TPSVCRET.
*
01 TPTYPE-REC.
COPY TPTYPE.
*
01 TPSTATUS-REC.
COPY TPSTATUS.
*
01 TPSVCDEF-REC.
COPY TPSVCDEF.
******************************************************
* User defined data records
******************************************************
01 TRANS-REC.
COPY TRANS-AMOUNT.
*
LINKAGE SECTION.
*
PROCEDURE DIVISION.
*
START-TRANSFER.
******************************************************
* Get the data that was sent by the client
******************************************************
MOVE LENGTH OF TRANS-REC TO LEN.
CALL "TPSVCSTART" USING TPSVCDEF-REC
TPTYPE-REC
TRANS-REC
TPSTATUS-REC.
IF NOT TPOK
MOVE "Transaction Encountered An Error" TO STATUS-LINE
SET TPFAIL TO TRUE.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY TRANS-REC
TPSTATUS-REC BY TPSTATUS-REC.
ELSE
. . . Check other parameters
******************************************************
* must have a valid debit and credit account number
******************************************************
CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-DEBIT-ACCOUNT IN TRANS-REC.

IF TRANS-DEBIT-ACCOUNT is not valid
MOVE "Invalid Debit Account Number"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.

CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-CREDIT-ACCOUNT IN TRANS-REC.

IF TRANS-CREDIT-ACCOUNT is not valid
MOVE "Invalid Credit Account Number"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Check amount to transfer
******************************************************
IF TRANS-AMOUNT IN TRANS-REC < 0
MOVE "Invalid Transfer Amount Requested"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Make Withdrawal using another service
******************************************************
MOVE "WITHDRAWAL" TO SERVICE-NAME.
. . . set other TPCALL parameters
CALL "TPCALL" USING . . .
IF NOT TPOK
MOVE "Cannot withdraw from debit account"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Make Deposit using another service
******************************************************
MOVE "DEPOSIT" TO SERVICE-NAME.
. . . set other TPCALL parameters
CALL "TPCALL" USING . . .
IF NOT TPOK
MOVE "Cannot Deposit into credit account"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN R

Invalidating Descriptors

If a service calling TPGETRPLY (described in detail in Writing Request/Response Clients and Servers) fails with TPETIME and decides to cancel the request, it can invalidate the descriptor with a call to TPCANCEL(3cbl). If a reply subsequently arrives, it is silently discarded.

TPCANCEL cannot be used for transaction replies (that is, for replies to requests made without the TPNOTRAN flag set). Within a transaction, TPABORT(3cbl) does the same job of invalidating the transaction call descriptor.

The following example shows how to invalidate a reply after timing out.

Invalidating a Reply After Timing Out

. . .  Set up parameters to TPACALL
SET TPNOTRAN TO TRUE.
CALL "TPACALL" USING TPSVCDEF-REC
                   TPTYPE-REC
                   DEBIT-REC
                   TPSTATUS-REC.
IF  NOT TPOK
       error processing
. . .
CALL "TPGETRPLY" USING TPSVCDEF-REC
                   TPTYPE-REC
                   DEBIT-REC
                   TPSTATUS-REC.
IF  NOT TPOK
       error processing
IF TPETIME
        CALL "TPCANCEL" TPSVCDEF-REC
                   TPSTATUS-REC.
    . . .
    SET TPSUCCESS TO TRUE.
    COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
                   TPTYPE-REC BY TPTYPE-REC
                   DATA-REC BY DEBIT-REC
                   TPSTATUS-REC BY TPSTATUS-REC.

Forwarding Requests

The TPFORWAR(3cbl) routine allows a service to forward a request to another service for further processing.

Use the following signature to call the TPFORWAR routine.

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
COPY TPFORWAR REPLACING TPSVCDEF-REC BY TPSVCDEF-REC
              TPTYPE-REC BY TPTYPE-REC
              DATA-REC BY DATA-REC
              TPSTATUS-REC BY TPSTATUS-REC.

For descriptions of the TPSVCDEF-REC and TPTYPE-REC records, refer to Defining a Service.

The functionality of TPFORWAR differs from a service call: a service that forwards a request does not expect a reply. The responsibility for providing the reply is passed to the service to which the request has been forwarded. The latter service sends the reply to the process that originated the request. It becomes the responsibility of the last server in the forward chain to send the reply to the originating client by invoking TPRETURN.

The following figure shows one possible sequence of events when a request is forwarded from one service to another. Here a client initiates a request using the TPCALL routine and the last service in the chain (SVC_C) provides a reply using the TPRETURN routine.

Forwarding a Request

Service routines can forward requests at specified priorities in the same manner that client processes send requests, by using the TPSPRIO routine.

When a process calls TPFORWAR, the system-supplied the controlling program regains control, and the server process is free to do more work.

Note: If a server process is acting as a client and a reply is expected, the server is not allowed to request services from itself. If the only available instance of the desired service is offered by the server process making the request, the call fails, indicating that a recursive call cannot be made. However, if a service routine sends a request (to itself) with the TPNOREPLY communication flag set, or if it forwards the request, the call does not fail because the service is not waiting for itself.

Calling TPFORWAR can be used to indicate success up to that point in processing the request. If no application errors have been detected, you can invoke TPFORWAR, otherwise, you can call TPRETURN with TP-RETURN-VAL IN TPSVCRET-REC set to TPFAIL.

The following example illustrates how the service sends its data record to the DEPOSIT service by calling TPFORWAR. If the new account is added successfully, the branch record is updated to reflect the new account, and the data record is forwarded to the DEPOSIT service. On failure, TPRETURN is called with TP-RETURN-VAL IN TPSVCRET-REC set to TPFAIL and the failure is reported on the status line of the form.

How to Use TPFORWAR

    . . .
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE LENGTH OF TRANS-REC TO LEN.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      TRANS-REC
                      TPSTATUS-REC.
    IF NOT TPOK
             MOVE "Transaction Encountered An Error" TO STATUS-LINE
             SET TPFAIL TO TRUE.
             COPY TPRETURN REPLACING
                      DATA-REC BY TRANS-REC.
    ELSE
             . . . Check other parameters
******************************************************
* Insert new account record
******************************************************
    CALL "ADD-NEW-ACCOUNT-FUNCTION" USING TRANS-ACCOUNT IN TRANS-REC.
    IF Adding New Account Failed
             MOVE "Account not added" TO STATUS-LINE IN TRANS-REC
             SET TPFAIL TO TRUE
             COPY TPRETURN REPLACING
                       DATA-REC BY TRANS-REC.
******************************************************
* Forward record to the DEPOSIT service to add initial
* balance into account
******************************************************
    MOVE "DEPOSIT" TO SERVICE-NAME.
    . . . set other TPFORWAR parameters
    COPY TPFORWAR REPLACING
                       DATA-REC BY TRANS-REC.