|
|
|
|
|
|
Sending Asynchronous Messages
This section explains how to:
The type of asynchronous processing discussed in this section is sometimes referred to as fan-out parallelism because it allows a client's requests to be distributed (or "fanned out") simultaneously to several services for processing.
The other type of asynchronous processing supported by the BEA Tuxedo system is pipeline parallelism in which the TPFORWAR routine is used to pass (or forward) a process from one service to another. For a description of the TPFORWAR routine, refer to Writing Servers.
Sending an Asynchronous Request
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.
For more information on the TPSVCDEF and TPTYPE-REC data structures, refer to Defining a Service.
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) 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.
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.
The following example shows how TPACALL uses the TPNOTRAN and TPNOREPLY settings. This code is similar to the code in Example: Sending a Synchronous Message with TPNOTRAN Set. In this case, however, a reply is not expected from the PRINTER service. By setting both TPNOTRAN and TPNOREPLY, the client is indicating that no reply is expected and the PRINTER service will not participate in the current transaction. This situation is discussed more fully in Managing Errors.
Sending an Asynchronous Message with TPNOTRAN or TPNOREPLY
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
Getting an Asynchronous Reply
A reply to a service call can be received asynchronously by calling the TPGETRPLY(3cbl) routine. The TPGETRPLY routine dequeues a reply to a request previously sent by TPACALL.
Use the following signature to call the TPGETRPLY routine.
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.
For more information on the TPSVCDEF and TPTYPE-REC data structures, refer to Defining a Service.
By default, the function waits for the arrival of the reply that corresponds to the value referenced by the communication handle. During this waiting interval, a blocking time-out may occur. A time-out occurs when TPGETRPLY fails and TP-STATUS is set to TPETIME (unless TPNOTIME is set).
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|