|
|
TPRETURN(3cbl)
Name
TPRETURN() - returns from a BEA Tuxedo system service routine
Synopsis
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 T
PSTATUS-REC BY TPSTATUS-REC.
Description
TPRETURN() indicates that a service routine has completed. Since TPRETURN() contains an EXIT PROGRAM statement, it should be called from within the same routine that was invoked to ensure correct return of control to the BEA Tuxedo system dispatcher (that is, TPRETURN() should not be invoked in a sub-program of the service routine since control would not return to the BEA Tuxedo system dispatcher).
TPRETURN() is used to send a service's reply message. If the service receiving the reply is waiting in either TPCALL(), TPGETRPLY(), or TPRECV(), then after a successful call to TPRETURN(), the reply is available in the receiver's record.
For conversational services, TPRETURN() also tears down the connection. That is the service routine cannot call TPDISCON() directly. To ensure correct results, the program that connected to the conversation service should not call TPDISCON(); rather, it should wait for notification that the conversational service has completed (that is, it should wait for one of the events, like TPEV-SVCSUCC or TPEV-SVCFAIL. sent by TPRETURN()).
If a service routine was in transaction mode, TPRETURN() places the service's portion of the transaction in a state from which it may be either committed or aborted when the transaction is completed. A service may be invoked multiple times as part of the same transaction so it is not necessarily fully committed nor aborted until either TPCOMMIT() or TPABORT() is called by the originator of the transaction.
TPRETURN() should be called after receiving all replies expected from request/response service requests initiated by the service routine. Otherwise, depending on the nature of the service, either a [TPESVCERR] status or a TPEV-SVCERR event will be returned to the program that initiated communications with the service routine. Any outstanding replies which are not received will automatically be dropped by the BEA Tuxedo system dispatcher upon receipt. In addition, the communications handle for those replies become invalid.
TPRETURN() should also be called after closing all connections initiated by the service. Otherwise, depending on the nature of the service, either a [TPESVCERR] status or a TPEV-SVCERR event will be returned to the program that initiated communications with the service routine. Also, an immediate disconnect event (that is, TPEV-DISCONIMM) is sent over all open connections to subordinates.
Concerning control of a connection, if the service routine does not have control over the connection with which it was invoked when it issued TPRETURN(), then two outcomes are possible. First, if the service routine calls TPRETURN() with TP-RETURN-VAL IN TPSVCRET-REC set to TPFAIL() and REC-TYPE IN TPTYPE-REC set to SPACES (that is, no data is sent), then a TPEV-SVCFAIL event is sent to the originator of this conversation. Second, if any other invocation of TPRETURN() is used, a TPEV-SVCERR event is sent to the originator.
Since a conversational service has only one open connection which it did not initiate, the server knows over which communications handle the data (and any event) should be sent. For this reason, a communication handle is not passed to TPRETURN().
The following is a description of the TPRETURN() arguments. TP-RETURN-VAL can be set to one of the following.
If TP-RETURN-VAL is not set to one of these three values, then it defaults to TPFAIL().
An application defined return code, APPL-CODE in TPSVCRET-REC, may be sent to the program receiving the service reply. This code is sent regardless of the setting of TP-RETURN-VAL as long as a reply can be successfully sent (that is, as long as the receiving call returns success or [TPESVCFAIL], or receives one of the events TPEV-SVCSUCC or TPEV-SVCFAIL). The value of APPL-CODE is available in the receiver in the variable, APPL-RETURN-CODE in TPSTATUS-REC.
DATA-REC is a record to be sent and LEN specifies the amount of DATA-REC that should be sent. Note that if DATA-REC is a record of type and sub-type that does not require a length to be specified, then LEN is ignored (and may be 0). If REC-TYPE is SPACES, DATA-REC and LEN are ignored. In this case, if a reply is expected by the program that invokes the service, then a reply is sent with no data portion. If no reply is expected, then TPRETURN() ignores any data passed to it and returns sending no reply. If REC-TYPE is STRING and LEN is 0, then the request is sent with no data portion.
If the service is conversational, there are several cases in which the application return code and the data portion are not transmitted:
Because TPRETURN() contains an EXIT PROGRAM statement, no value is returned to the caller, nor does control return to the service routine. If a service routine returns without using TPRETURN() (that is, it uses an EXIT PROGRAM statement directly or just simply "falls out of the service routine"), the server will return a service error to the service requester. In addition, all open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be dropped. If the server was in transaction mode at the time of failure, the transaction is marked abort-only. Note also that if TPRETURN() is used outside of a service routine (that is, by routines that are not services), then it returns having no effect.
Errors
Errors encountered either in handling arguments or in processing cause TP-STATUS to be set to [TPESVCERR] for a program receiving the service's outcome via either TPCALL() or TPGETRPLY(), and cause the event, TPEV-SVCERR, to be sent over the conversation to a program using TPSEND() or TPRECV().
See Also
TPCALL(3cbl), TPCONNECT(3cbl), TPFORWAR(3cbl)
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|