Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPRETURN(3cbl)

Name

TPRETURN() - returns from a BEA Tuxedo ATMI 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 ATMI 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 ATMI 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 ATMI 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.

TPSUCCESS

The service has terminated successfully. If data is present, then it will be sent (barring any failures processing the return). If the caller is in transaction mode, then TPRETURN() places the caller's portion of the transaction in a state such that it can be committed when the transaction ultimately commits. Note that a call to TPRETURN() does not necessarily finalize an entire transaction. Also, even though the caller indicates success, if there are any outstanding replies or open connections, if any work done within the service caused its transaction to be marked abort-only, then a failed message is sent (that is, the recipient of the reply receives a TPESVCERR() indication or a TPEV-SVCERR event). Note that if a transaction becomes abort-only while in the service routine for any reason, then TP-RETURN-VAL should be set to TPFAIL(). If TPSUCCESS() is specified for a conversational service, a TPEV-SVCSUCC event is generated.

TPFAIL

The service has terminated unsuccessfully from an application standpoint. An error will be reported to the program receiving the reply. That is, the call to get the reply will fail and the recipient receives a [TPSVCERR] indication or a TPEV-SVCERR event. If the caller is in transaction mode, then TPRETURN() marks the transaction as abort-only (note that the transaction may already be marked abort-only). Barring any failures in processing the return, the caller's data is sent, if present. One reason for not sending the caller's data is when a transaction timeout has occurred. In this case, the program waiting for the reply will receive an error of [TPETIME].

TPEXIT

This value is the same as TPFAIL(), with respect to completing the service, but the server will exit after the transaction is marked as abort-only and the reply is sent back to the requester. If the server is restartable, then the server will automatically be restarted.

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 subtype 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:

If the connection has been terminated when the call is made (that is, the caller has received TPEV-DISCONIMM on the connection), then this call simply ends the service routine and rolls back the current transaction, if one exists. In this case, the caller's data record cannot be transmitted.
If the caller does not have control of the connection, either TPEV-SVCERR or TPEV-SVCFAIL is sent to the originator of the connection as described above. Regardless of which event the originator receives, no data record is transmitted. If the originator receives the TPEV_SVCFAIL event, however, the return code is available in the originator's APPL-RETURN-CODE in TPSTATUS-REC.

Return Values

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().