OpenTP1 Version 7 Programming Reference C Language
tpreturn - Return from a service routine
Format
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; |
Description
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:
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:
<<Arguments>>
<<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).>>
Return value
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().
See also
tpalloc(), tpcall(), tpconnect(), tpdiscon(), tpgetrply(), tprecv(), tpsend(), tpservice().
<<Notes on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.