Sending Synchronous Messages


	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 TPCALL(3cbl) call sends a request to a service subroutine and synchronously waits for a reply. Use the following signature to call the TPCALL routine.

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 ITPTYPE-REC.
   COPY TPTYPE.
01 IDATA-REC.
   COPY User Data.
01 OTPYTPE-REC.
   COPY TPTYPE.
01 ODATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPCALL" USING TPSVCDEF-REC 
              ITPTYPE-REC 
              IDATA-REC 
              OTPTYPE-REC
              ODATA-REC 
               TPSTATUS-REC.

For more information on the TPSVCDEF data structure, refer to Defining a Service. The IDATA-REC and ITPTYPE-REC structures define the request record. The ODATA-REC and OTPTYPE-REC structures define the reply record. The ITPTYPE-REC and OTPTYPE-REC data structures are similar to the TPTYPE-REC data structure, as defined in Defining a Service.

TPCALL waits for the expected reply.

Note: Calling the TPCALL routine is logically the same as calling the TPACALL routine, immediately followed by TPGETRPLY, as described in Sending Asynchronous Messages.

The request carries the priority set by the system for the specified service (SERVICE-NAME) unless a different priority has been explicitly set by a call to the TPSPRIO routine (described in Setting and Getting Message Priorities).

TPCALL returns an integer. On failure, the value of TP-STATUS is set to a value that reflects the type of error that occurred. For information on valid error codes, refer to TPCALL(3cbl) in the BEA Tuxedo COBOL Function Reference.

Note: Communication calls may fail for a variety of reasons, many of which can be corrected at the application level. Possible causes of failure include: application defined errors (TPESVCFAIL), errors in processing return arguments (TPESVCERR), typed record errors (TPEITYPE, TPEOTYPE), time-out errors (TPETIME), and protocol errors (TPEPROTO), among others. For a detailed discussion of errors, refer to Managing Errors. For a complete list of possible errors, refer to TPCALL(3cbl) in the BEA Tuxedo COBOL Function Reference.

The BEA Tuxedo system automatically adjusts a record used for receiving a message if the received message is too large for the allocated record. You should test for whether or not the reply records have been resized.

To access the new size of the record, use the address returned in *LEN IN OTPTYPE-REC. To determine whether a reply record has changed in size, compare the size of the reply record before the call to TPCALL with the value of LEN IN OTPTYPE-REC after its return. If LEN IN OTPTYPE-REC is larger than the original size, the record has grown. If not, the record size has not changed.

Example: Using the Same Record for Request and Reply Messages

The following example shows how the client program makes a synchronous call using the same record for both the request and reply messages. In this case, using the same record is appropriate because the AUDV-REC message record has been set up to accommodate both request and reply information. The following actions are taken in this code:

The service queries the B_ID field, but does not overwrite it.
The application initializes the BALANCE field to zero in preparation for the values to be returned by the service.

The SERVICE-NAME represents the service name requested. In this example, these variables represent account and teller, respectively.

Using the Same Record for Request and Reply Messages

WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
  01  TPTYPE-REC.
  COPY TPTYPE.
*
  01 TPSTATUS-REC.
  COPY TPSTATUS.
*
  01  TPSVCDEF-REC.
  COPY TPSVCDEF.
*****************************************************
* Log messages definitions
*****************************************************
  01  LOGMSG.
     05  FILLER           PIC X(6) VALUE  "FIG =>".
     05  LOGMSG-TEXT      PIC X(50).
  01  LOGMSG-LEN          PIC S9(9)  COMP-5.
*
  01  USER-DATA-REC       PIC X(75).
*****************************************************
* This VIEW record (audv) will be sent to the server
*****************************************************
  01 AUDV-REC.
  COPY AUDV.
*
******************************************************
  PROCEDURE DIVISION.
  START-FIG.
  MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
*****************************************************
*  Prepare the audv record
*****************************************************
  MOVE "BRANCH" TO B-ID IN AUDV-REC.
  MOVE 0 TO BALANCE IN AUDV-REC.
  MOVE LENGTH OF AUDV-REC TO LEN.
  MOVE "VIEW" TO REC-TYPE.
  MOVE "audv" TO SUB-TYPE.
  MOVE "SOMESERVICE" TO SERVICE-NAME.
  SET TPBLOCK TO TRUE.
  SET TPNOTRAN TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
  SET TPNOCHANGE TO TRUE.
  CALL "TPCALL" USING TPSVCDEF-REC
                TPTYPE-REC
                AUDV-REC
                TPTYPE-REC
                AUDV-REC
                TPSTATUS-REC.
  IF NOT TPOK
         MOVE "Service Failed" TO LOGMSG-TEXT
         PERFORM DO-USERLOG
         PERFORM EXIT-PROGRAM.
  DISPLAY BRANCH and BALANCE
  . . .

If the reply is larger than ODATA-REC, then ODATA-REC contains as much of the message as fits in the record. The remainder is discarded and TPCALL sets TP-STATUS IN TPSTATUS-REC to TPTRUNCATE.

Example: Sending a Synchronous Message with TPSIGRSTRT Set

The following example is based on the TRANSFER service, which is part of the XFER server process of bankapp. (bankapp is a sample application delivered with the BEA Tuxedo system.) The example is based on a service that assumes the role of a client when it calls the WITHDRAWAL and DEPOSIT services. The application sets the communication flag to TPSIGRSTRT in these service calls to give the transaction a better chance of committing. The TPSIGRSTRT flag specifies the action to take if there is a signal interrupt. For more information on communication flags, refer to TPCALL(3cbl) in the BEA Tuxedo COBOL Function Reference.

Sending a Synchronous Message with TPSIGRSTRT Set

   WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
   01 TPTYPE-REC.
   COPY TPTYPE.
*
   01 TPSTATUS-REC.
   COPY TPSTATUS.
 *
   01 TPSVCDEF-REC.
   COPY TPSVCDEF.
*****************************************************
* This VIEW record (audv) will be sent to the server
*****************************************************
   01 AUDV-REC.
   COPY AUDV.
*
******************************************************
   PROCEDURE DIVISION.
 START-FIG.
*****************************************************
* Prepare the audv record for withdrawal
*****************************************************
  . . .
  MOVE "WITHDRAWAL" TO SERVICE-NAME.
  SET TPSIGRSTRT TO TRUE.
  PERFORM DO-TPCALL.
  IF NOT TPOK
         MOVE "Cannot withdraw from debit account" TO LOGMSG-TEXT
         PERFORM DO-USERLOG
         PERFORM EXIT-PROGRAM.
  MOVE "DEPOSIT" TO SERVICE-NAME.
  SET TPSIGRSTRT TO TRUE.
  PERFORM DO-TPCALL.
  IF NOT TPOK
         MOVE "Cannot deposit into credit account" TO LOGMSG-TEXT
         PERFORM DO-USERLOG
         PERFORM EXIT-PROGRAM.
  . . .
*****************************************************
*  Perform a TPCALL
*****************************************************
 DO-TPCALL.
   MOVE LENGTH OF AUDV-REC TO LEN.
   MOVE "VIEW" TO REC-TYPE.
   MOVE "audv" TO SUB-TYPE.
   SET TPBLOCK TO TRUE.
   SET TPNOTRAN TO TRUE.
   SET TPNOTIME TO TRUE.
   SET TPNOCHANGE TO TRUE.
   CALL "TPCALL" USING TPSVCDEF-REC
                 TPTYPE-REC
                 AUDV-REC
                 TPTYPE-REC
                 AUDV-REC
                 TPSTATUS-REC.
   . . .

Example: Sending a Synchronous Message with TPNOTRAN Set

The following example illustrates a communication call that suppresses transaction mode. The call is made to a service that is not affiliated with a resource manager; it would be an error to allow the service to participate in the transaction. The application prints an accounts receivable report, ACCRV, generated from information obtained from a database named ACCOUNTS.

The service routine REPORT interprets the specified parameters and sends the byte stream for the completed report as a reply. The client uses TPCALL to send the byte stream to a service called PRINTER, which, in turn, sends the byte stream to a printer that is conveniently close to the client. The reply is printed. Finally, the PRINTER service notifies the client that the hard copy is ready to be picked up.

Note: The example Sending an Asynchronous Message with TPNOTRAN or TPNOREPLY shows a similar example using an asynchronous message call.

Sending a Synchronous Message with TPNOTRAN Set

    WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
    01  ITPTYPE-REC.
    COPY TPTYPE.
    01  OTPTYPE-REC.
    COPY TPTYPE.
*
    01 TPSTATUS-REC.
    COPY TPSTATUS.
*
    01  TPSVCDEF-REC.
    COPY TPSVCDEF.
*****************************************************
    01 REPORT-REQUEST         PIC X(100) VALUE SPACES.
    01 REPORT-OUTPUT          PIC X(50000) VALUE SPACES.
******************************************************
    PROCEDURE DIVISION.
  START-FIG.
    . . .
    join application
    start transaction
    . . .
********************************************************
* Send report request to REPORT service
* Receive results into REPORT-OUTPUT
********************************************************
    MOVE "REPORT=accrcv DBNAME=accounts" TO REPORT-REQUEST.
    MOVE "STRING" TO REC-TYPE IN ITYPE-REC.
    MOVE 29 TO LEN IN ITYPE-REC.
    MOVE "STRING" TO REC-TYPE IN OITYPE-REC.
    MOVE 50000 TO LEN IN OTYPE-REC.
    MOVE "REPORT" TO SERVICE-NAME.
    SET TPTRAN TO TRUE.
    SET TPBLOCK TO TRUE.
    SET TPNOTIME TO TRUE.
    SET TPSIGRSTRT TO TRUE.
    SET TPNOCHANGE TO TRUE.
    CALL "TPCALL" USING TPSVCDEF-REC
                  ITPTYPE-REC
                  REPORT-REQUEST
                  OTPTYPE-REC
                  REPORT-OUTPUT
                  TPSTATUS-REC.
    IF NOT TPOK
       error processing
    IF TPETRUNCATE
       The report was truncated
       error processing
********************************************************
* Send REPORT-OUTPUT to PRINTER service
********************************************************
    MOVE "PRINTER" TO SERVICE-NAME.
    SET TPNOTRAN TO TRUE.
    MOVE "STRING" TO REC-TYPE IN ITTYPE-REC.
    MOVE LEN IN OTYPE-REC TO LEN IN ITYPE-REC.
    CALL "TPCALL" USING TPSVCDEF-REC
                  ITPTYPE-REC
                  REPORT-OUTPUT
                  OTPTYPE-REC
                  REPORT-OUTPUT
                  TPSTATUS-REC.
    IF NOT TPOK
         error processing
    . . .
         terminate transaction
          leave application

Note: In the preceding example, the term error routine indicates that the following tasks are performed: an error message is printed, the transaction is aborted, the client leaves the application, and the program is exited.

This example also shows how the TPNOCHANGE communication setting is used to enforce strong record type checking by indicating that the reply message must be returned in the same type of record that was originally allocated. The strong type check flag, TPNOCHANGE, forces the reply to be returned in a record of type STRING.

A possible reason for this check is to guard against errors that may occur in the REPORT service subroutine, resulting in the use of a reply record of an incorrect type. Another reason is to prevent changes that are not made consistently across all areas of dependency. For example, another programmer may have changed the REPORT service to standardize all replies in another STRING format without modifying the client process to reflect the change.