ANSI C, C++

#include <xatmi.h>
void tpreturn (int rval, long rcode, char *data,
               long len, long flags)

K&R C

#include <xatmi.h>
void tpreturn (rval, rcode, data, len, flags)
int       rval;
long      rcode;
char      *data;
long      len;
long      flags;

The function tpreturn() indicates that a service routine has completed. tpreturn() acts like a return statement in the C-language (that is, when tpreturn() is called, the service routine returns to the communication resource manager). It is recommended that tpreturn() be called from within the service routine dispatched by the communication resource manager to ensure correct return of control to the communication resource manager.

The function tpreturn() is used to send a service's reply message. If the program 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 buffer.

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 tx_commit() or tx_rollback() is called by the originator of the transaction.

The function 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 is 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 descriptors for those replies become invalid.

The function 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 rval set to TPFAIL and data is NULL, then 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 descriptor data (and any event) should be sent. For this reason, a descriptor is not passed to tpreturn().

The argument rval 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, or if any work done within the service caused its transaction to be marked rollback-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 rollback-only while in the service routine for any reason, rval 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 fails 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 rval does not contain one of these two values, TPFAIL is assumed.

An application-defined return code, rcode, may be sent to the program receiving the service reply. This code is sent regardless of the setting of rval 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). In addition, for conversational services, this code can be sent only if the service routine has control of the connection when it issues tpreturn(). The value of rcode is available to the receiver in the variable tpurcode.

data points to the data portion of a reply to be sent. If data is non-NULL, it must point to a buffer previously obtained by a call to tpalloc(). If this is the same buffer passed to the service routine upon its invocation, its disposition is up to the communication resource manager; the service routine writer does not have to worry about whether it is freed or not. In fact, any attempt by the user to free this buffer fails. However, if the buffer passed to tpreturn() is not the same one with which the service is invoked, tpreturn() frees that buffer. len specifies the amount of the data buffer to be sent. If data points to a buffer that does not require a length to be specified, then len is ignored (and may be 0). If data points to a buffer that does require a length, len must not be zero.

If data is NULL, len is 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() frees data as necessary and returns sending no reply.

Currently, flags are reserved for future use and must be set to 0.

If the service is conversational, there are two cases where the caller's return code and the data portion are 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 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 is transmitted; however, if the originator receives the TPEV_SVCFAIL event, the return code is available in the originator's tpurcode variable.

<<rval

Specify either TPSUCCESS or TPFAIL.>>

<<rcode

Specify a return code defined in the application.>>

<<data

Specify the pointer to the buffer containing the reply data to be sent.>>

<<len

Specify the length of the buffer for data which will come.>>

<<flags

Set 0 (reserved for the future).>>

A service routine does not return any value to its caller, the communication resource manager dispatcher; thus, it is declared as a void. Service routines, however, are expected to terminate using tpreturn(). If a service routine returns without using tpreturn() (that is, it uses the C-language return statement or falls out of the function), 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 (for example, 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 function's caller. Such errors cause tperrno 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().

tpalloc(), tpcall(), tpconnect(), tpdiscon(), tpgetrply(), tprecv(), tpsend(), tpservice().

1. <<Under the relevant version of the OpenTP1, the function tpreturn() will not terminate the service function. After calling the function tpreturn(), use return() to terminate the service function. If some processing is performed after the function tpreturn() is called, subsequent operation is unpredictable.>>
2. <<The behavior caused by XATMI errors encountered during OSI TP communication may be different from the behavior caused by errors encountered conventional TCP/IP communication.>>