![]() |
![]() |
|
|
Sending Synchronous Messages
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 ATMI 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), timeout 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 ATMI 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:
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 ATMI 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 ATMI 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.
![]() |
![]() |
![]() |
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|