PURPOSE

TPRETURN - return from a System/T 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
TPSTATUS-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 System/T dispatcher (that is, TPRETURN should not be invoked in a sub-program of the service routine since control would not return to the System/T dispatcher).

TPRETURN is used to send a service's reply message. If the service receiving the reply is waiting in either TPCALL(3cbl), TPGETRPLY(3cbl), or TPRECV(3cbl), 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(3cbl) directly. To ensure correct results, the program that connected to the conversation service should not call TPDISCON(3cbl); rather, it should wait for notification that the conversational service has completed (i.e., 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 where 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(3cbl) or TPABORT(3cbl) 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 System/T 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 (i.e., 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 TPRETURN's 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 (i.e., 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 that 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 (i.e., 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 where the application return code and the data portion are not transmitted:

--
if the connection has been terminated when the call is made (i.e., 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; however, if the originator receives the TPEV_SVCFAIL event, the return code is available in the originator's APPL-RETURN-CODE in TPSTATUS-REC.

RETURN VALUES

Since 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 (i.e., 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 (i.e., by routines that are not services), then it returns having no effect.

ERRORS

Errors encountered either in handling arguments or in processing cannot be indicated to the routine's caller. Such errors cause TP-STATUS to be set to [TPESVCERR] for a program receiving the service's outcome via either TPCALL(3cbl) or TPGETRPLY(3cbl), and cause the event TPEV-SVCERR to be sent over the conversation to a program using TPSEND(3cbl) or TPRECV(3cbl).

tperrordetail(3c) and tpstrerrordetail(3c) can be used to get additional information about an error produced by the last TUXEDO routine called in the current thread. If an error occurred, tperrordetail returns a numeric value that can be used as an argument to tpstrerrordetail to retrieve the text of the error detail.

PURPOSE

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO