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
Programming Oracle Tuxedo ATMI Applications Using C. 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.
TPCALL waits for the expected reply.
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
Oracle Tuxedo ATMI COBOL Function Reference.
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.
3.
|
The SERVICE-NAME represents the service name requested. In this example, these variables represent account and teller, respectively.
|
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.
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 Oracle 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
Oracle Tuxedo ATMI COBOL Function Reference.
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.
. . .
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.
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.
The TPACALL(3cbl) routine sends a request to a service and immediately returns. Use the following signature to call the
TPACALL routine:
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01
TPTYPE-REC.
COPY TPTYPE.
01
DATA-REC.
COPY User Data.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPACALL" USING
TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
The TPACALL routine sends a request message to the service named in the
SERVICE-NAME and immediately returns from the call. Upon successful completion of the call, the
TPACALL routine returns an integer that serves as a communication handle used to access the correct reply for the relevant request. While
TPACALL is in transaction mode (as described in
“Writing Global Transactions” in
Programming Oracle Tuxedo ATMI Applications Using C) there may not be any outstanding replies when the transaction commits; that is, within a given transaction, for each request for which a reply is expected, a corresponding reply must eventually be received.
If the value TPNOREPLY is set, the parameter signals to
TPACALL that a reply is not expected. When set, on success
TPACALL returns a value of
0 as the reply descriptor. If subsequently passed to the
TPGETRPLY routine, this value becomes invalid, this value becomes invalid. Guidelines for using this setting correctly when a process is in transaction mode are discussed in
“Writing Global Transactions” in
Programming Oracle Tuxedo ATMI Applications Using C.
On error, TPACALL sets
TP-STATUS to a value that reflects the nature of the error.
TPACALL returns many of the same error codes as
TPCALL. The differences between the error codes for these functions are based on the fact that one call is synchronous and the other, asynchronous. These errors are discussed at length in
“Managing Errors” in
Programming Oracle Tuxedo ATMI Applications Using C.
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 ITPTYPE-REC.
MOVE 29 TO LEN IN ITPTYPE-REC.
MOVE "STRING" TO REC-TYPE IN OITYPE-REC.
MOVE 50000 TO LEN IN OTPTYPE-REC.
MOVE "REPORT" TO SERVICE-NAME.
SET TPTRAN TO TRUE.
SET TPBLOCK TO TRUE.
SET TPNOTIME TO TRUE.
SET TPSIGRSTRT TO TRUE.
SET TPREPLY 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.
SET TPNOREPLY TO TRUE.
MOVE "STRING" TO REC-TYPE IN ITPTYPE-REC.
MOVE LEN IN OTPTYPE-REC TO LEN IN ITPTYPE-REC.
CALL "TPACALL" USING TPSVCDEF-REC
ITPTYPE-REC
REPORT-OUTPUT
TPSTATUS-REC.
IF NOT TPOK
error processing
. . .
commit transaction
leave application
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01
TPTYPE-REC.
COPY TPTYPE.
01
DATA-REC.
COPY User Data.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGETRPLY" USING
TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
The TPSPRIO(3cbl) routine enables you to set the priority of a message request.
The TPSPRIO routine affects the priority level of only one request: the next request to be sent by
TPCALL or
TPACALL, or to be forwarded by a service subroutine.
01 TPPRIDEF-REC.
COPY TPPRIDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSPRIO" USING
TPPRIDEF-REC TPSTATUS-REC.
05 PRIORITY PIC S9(9) COMP-5.
05
PRIO-FLAG PIC S9(9) COMP-5.
88 TPABSOLUTE VALUE 0.
88 TPRELATIVE VALUE 1.
Table 6‑1 describes the arguments to the
TPSPRIO routine.
|
|
|
Integer indicating a new priority value. The effect of this argument is controlled by PRIO-FLAG. If PRIO-FLAG is set to 0, PRIORITY specifies a relative value and the sign accompanying the value indicates whether the current priority is incremented or decremented. Otherwise, the value specified indicates an absolute value and PRIORITY must be set to a value between 0 and 100. If you do not specify a value within this range, the system sets the value to 50.
|
|
Indicates whether the value of PRIORITY is treated as a relative value (0, the default) or an absolute value ( TPABSOLUTE).
|
The following sample code is an excerpt from the TRANSFER service. In this example, the
TRANSFER service acts as a client by sending a synchronous request, via
TPCALL, to the
WITHDRAWAL service.
TRANSFER also invokes
TPSPRIO to increase the priority of its request message to
WITHDRAWAL, and to prevent the request from being queued for the
WITHDRAWAL service (and later the
DEPOSIT service) after waiting on the
TRANSFER queue.
WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
01 TPTYPE-REC.
COPY TPTYPE.
*
01 TPSTATUS-REC.
COPY TPSTATUS.
*
01 TPSVCDEF-REC.
COPY TPSVCDEF.
*
01 TPPRIDEF-REC.
COPY TPPRIDEF.
*****************************************************
01 DATA-REC PIC X(100) VALUE SPACES.
******************************************************
PROCEDURE DIVISION.
START-FIG.
. . .
join application
. . .
MOVE 30 TO PRIORITY.
SET TPRELATIVE TO TRUE.
CALL "TPSPRIO" USING TPPRIDEF-REC TPSTATUS-REC
IF NOT TPOK
error processing
MOVE "CARRAY" TO REC-TYPE.
MOVE 100 TO LEN.
MOVE "WITHDRAWAL" TO SERVICE-NAME.
SET TPTRAN TO TRUE .
SET TPBLOCK TO TRUE .
SET TPNOTIME TO TRUE .
SET TPSIGRSTRT TO TRUE .
SET TPREPLY TO TRUE .
CALL "TPACALL" USING TPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
. . .
leave application
The TPGPRIO(3cbl) routine enables you to get the priority of a message request.
01 TPPRIDEF-REC.
COPY TPPRIDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGPRIO" USING
TPPRIDEF-REC TPSTATUS-REC.
A requester can call the TPGPRIO routine after invoking the
TPCALL or
TPACALL routine to retrieve the priority of the request message. If a requester calls the function but no request is sent, the routine fails, setting
TP-STATUS to
TPENOENT. Upon success,
TPGPRIO sets
TP-STATUS to
TPOK and returns an integer value in the range of 1 to 100 (where the highest priority value is 100).
If a priority has not been explicitly set using the TPSPRIO routine, the system sets the message priority to that of the service routine that handles the request. Within an application, the priority of the request-handling service is assigned a default value of 50 unless a system administrator overrides this value.
WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
01 TPTYPE-REC-1.
COPY TPTYPE.
01 TPTYPE-REC-2.
COPY TPTYPE.
*
01 TPSTATUS-REC.
COPY TPSTATUS.
*
01 TPSVCDEF-REC-1.
COPY TPSVCDEF.
01 TPSVCDEF-REC-2.
COPY TPSVCDEF.
*
01 TPPRIDEF-REC-1.
COPY TPPRIDEF.
01 TPPRIDEF-REC-2.
COPY TPPRIDEF.
*****************************************************
01 DATA-REC-1 PIC X(100) VALUE SPACES.
01 DATA-REC-2 PIC X(100) VALUE SPACES.
******************************************************
PROCEDURE DIVISION.
START-FIG.
. . .
join application
populate DATA-REC1 and DATA-REC2 with send request
. . .
MOVE "CARRAY" TO REC-TYPE IN TYPE-REC-1.
MOVE 100 TO LEN IN TYPE-REC-1.
MOVE "SERVICE1" TO SERVICE-NAME IN TPSVCDEV-REC-1.
SET TPTRAN TO TRUE IN TPSVCDEV-REC-1.
SET TPBLOCK TO TRUE IN TPSVCDEV-REC-1.
SET TPNOTIME TO TRUE IN TPSVCDEV-REC-1.
SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-1.
SET TPREPLY TO TRUE IN TPSVCDEV-REC-1.
CALL "TPACALL" USING TPSVCDEF-REC-1
TPTYPE-REC-1
DATA-REC-1
TPSTATUS-REC.
IF NOT TPOK
error processing
CALL "TPGPRIO" USING TPPRIDEF-REC-1 TPSTATUS-REC
IF NOT TPOK
error processing
MOVE "CARRAY" TO REC-TYPE IN TYPE-REC-2.
MOVE 100 TO LEN IN TYPE-REC-2.
MOVE "SERVICE2" TO SERVICE-NAME IN TPSVCDEV-REC-2.
SET TPTRAN TO TRUE IN TPSVCDEV-REC-2.
SET TPBLOCK TO TRUE IN TPSVCDEV-REC-2.
SET TPNOTIME TO TRUE IN TPSVCDEV-REC-2.
SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-2.
SET TPREPLY TO TRUE IN TPSVCDEV-REC-2.
CALL "TPACALL" USING TPSVCDEF-REC-2
TPTYPE-REC-2
DATA-REC-2
TPSTATUS-REC.
IF NOT TPOK
error processing
CALL "TPGPRIO" USING TPPRIDEF-REC-2 TPSTATUS-REC
IF NOT TPOK
error processing
IF PRIORITY IN TPSVCDEF-REC-1 >= PRIORITY IN TPSVCDEF-REC-2
PERFORM DO-GETREPLY1
PERFORM DO-GETREPLY2
ELSE
PERFORM DO-GETREPLY2
PERFORM DO-GETREPLY1
END-IF.
. . .
leave application
DO-GETRPLY1.
SET TPGETHANDLE TO TRUE IN TPSVCDEV-REC-1.
SET TPCHANGE TO TRUE IN TPSVCDEV-REC-1.
SET TPBLOCK TO TRUE IN TPSVCDEV-REC-1.
SET TPNOTIME TO TRUE IN TPSVCDEV-REC-1.
SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-1.
CALL "TPGETRPLY" USING TPSVCDEF-REC-1
TPTYPE-REC-1
DATA-REC-1
TPSTATUS-REC.
IF NOT TPOK
error processing
DO-GETRPLY2
SET TPGETHANDLE TO TRUE IN TPSVCDEV-REC-2.
SET TPCHANGE TO TRUE IN TPSVCDEV-REC-2.
SET TPBLOCK TO TRUE IN TPSVCDEV-REC-2.
SET TPNOTIME TO TRUE IN TPSVCDEV-REC-2.
SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-2.
CALL "TPGETRPLY" USING TPSVCDEF-REC-2
TPTYPE-REC-2
DATA-REC-2
TPSTATUS-REC.
IF NOT TPOK
error processing