TPRETURN - Return from a service routine

TPRETURN indicates that a service routine has completed. TPRETURN is a file containing the last sequence of COBOL code to be executed in the service. It contains references to three data record names: TPSVCRET-REC, TPTYPE-REC and DATA-REC that may be substituted by the record names effectively used in the service routine. Since TPRETURN contains an EXIT PROGRAM statement, it should be issued in the same routine that was invoked by the communication resource manager so that control can be returned to the communication resource manager (that is, TPRETURN should not be invoked in a sub-program of the service routine since control would not return to the communication resource manager).

TPRETURN is used to send a service's reply message. If the program receiving the reply is waiting in TPCALL, TPGETRPLY or TPRECV, after a successful call to TPRETURN, the reply is available in the receiver's record.

For conversational services, TPRETURN also terminates the connection. That is, the service routine cannot call TPDISCON directly. To ensure correct results, the program that connected to the conversational 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 the 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 rolled back 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 rolled back until either TXCOMMIT or TXROLLBACK is called by the originator of the transaction.

TPRETURN should be called after receiving all replies expected from service requests initiated by the service routine. Otherwise, depending on the nature of the service, either a TPESVCERR error or a TPEV-SVCERR event are returned to the program that initiated communication with the service routine. Any outstanding replies that are not received are automatically dropped by the communication resource manager. In addition, the communication handles for those replies become invalid.

TPRETURN should be called after closing all connections initiated by the service. Otherwise, depending on the nature of the service, either a TPESVCERR or a TPEV-SVCERR event is returned to the program that initiated communication with the service routine. Also, an immediate disconnect event (that is, TPEV-DISCONIMM) is sent over all open connections to subordinates.

Concerning control of the connection, if the service routine does not have control over the connection with which it was invoked when it issues TPRETURN, two outcomes are possible. Firstly, 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), a TPEV-SVCFAIL event is sent to the originator of this conversation. Secondly, 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 that it did not initiate, the communication resource manager knows over which communication handle data (and any event) should be sent. For this reason, a communication handle is not passed to TPRETURN.

<<TPSVCRET-REC

Specify TP-RETURN-VAL and APPL-CODE.>>

<<TPTYPE-REC

Indicates the record type and subtype record name of the send data.>>

<<DATA-REC

Points to the send data.>>

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, it is sent (barring any failures processing the return). If the caller is in transaction mode, 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 to subordinates, or if any work done within the service caused its transaction to be marked rollback-only, 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 rollback-only while in the service routine for any reason, 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 is reported to the program receiving the reply. That is, the call to get the reply has failed and the recipient receives a TPSVCFAIL indication or a TPEV-SVCFAIL event. If the caller is in transaction mode, TPRETURN marks the transaction as rollback-only (note that the transaction may already be marked rollback-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 receives an error of TPETIME.

If TP-RETURN-VAL does not contain one of these two values, TPFAIL is assumed.

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 to the receiver in APPL-RETURN-CODE in TPSTATUS-REC.

DATA-REC is the record to be sent and LEN (in TPTYPE-REC) specifies the amount of data in DATA-REC that should be sent. Note that if DATA-REC is a record of a type that does not require a length to be specified, LEN is ignored (and may be 0). If DATA-REC is a record of a type that does require a length, LEN must not be zero. If REC-TYPE does not specify subtype, SUB-TYPE is ignored (and may be SPACES). If REC-TYPE is SPACES, DATA-REC and LEN are ignored. In this case, if a reply is expected by the program that invoked the service, a reply is sent with no data portion. If no reply is expected, TPRETURN ignores any data passed to it and returns sending no reply.

If the service is conversational, there are two cases where the data record is not transmitted:

If the connection has already been terminated when the call is made (that is, the caller has received TPEV-DISCONIMM on the connection), 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-SVCFAIL or TPEV-SVCERR 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.

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 (that is, it uses an EXIT PROGRAM statement directly or falls out of the service routine), the server returns a service error to the service requester. In addition, all open connections to subordinates are disconnected immediately, and any outstanding asynchronous replies are dropped. If the server was in transaction mode at the time of failure, the transaction is marked rollback-only. Note also that if TPRETURN is used outside a service routine (that is, by routines that are not services), it returns having no effect.

Errors

Since TPRETURN ends the service routine, any 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 or TPGETRPLY, and cause the event, TPEV-SVCERR, to be sent over the conversation to a program using TPSEND or TPRECV.