OpenTP1 Version 7 Programming Reference C Language
tpservice - Template for service routines
Format
ANSI C, C++
#include <xatmi.h> void tpservice (TPSVCINFO *svcinfo) |
K&R C
#include <xatmi.h> void tpservice (svcinfo) TPSVCINFO *svcinfo; |
Description
The function tpservice() is the template for writing service routines. This template is used for services that receive requests via tpcall() or tpacall() routines as well as by services that communicate via tpconnect(), tpsend() and tprecv() routines.
Service routines processing requests made via either tpcall() or tpacall() receive, at most, one incoming message (in the data element of svcinfo) and send, at most, one reply (upon exiting the service routine with tpreturn()).
Conversational services, on the other hand, are invoked by connection requests with, at most, one incoming message along with a means of referring to the open connection. When a conversational service routine is invoked, either the connecting program or the conversational service may send and receive data as defined by the application. The connection is half-duplex in nature meaning that one side controls the conversation (that is, it sends data) until it explicitly gives up control to the other side of the connection.
Concerning transactions, service routines can participate in, at most, one transaction if invoked in transaction mode. As far as the service routine writer is concerned, the transaction ends upon returning from the service routine. If the service routine is not invoked in transaction mode, the service routine may originate as many transactions as it wants using tx_begin(), tx_commit() and tx_rollback(). Note that tpreturn() is not used to complete a transaction. Thus, it is an error to call tpreturn() with an outstanding transaction that originated within the service routine.
<<Argument>>
Service routines are invoked with one argument: svcinfo, a pointer to a service information structure. This structure includes the following members:
char name[XATMI_SERVICE_NAME_LENGTH]; char *data; long len; long flags; int cd; |
The element name is populated with the service name that the requester used to invoke the service.
The setting of flags upon entry to a service routine indicates attributes that the service routine may want to note. The possible values for flags are as follows:
The element data points to the data portion of a request message and len is the length of the data. The buffer pointed to by data was allocated by tpalloc() in the communication resource manager. This buffer may be grown by the user with tprealloc(); however, it cannot be freed by the user. It is recommended that this buffer be the one passed to tpreturn() when the service ends. If a different buffer is passed to those routines, that buffer is freed by them. Note that the buffer pointed to by data is overwritten by the next service request even if this buffer is not passed to tpreturn(). The element data may be NULL if no data accompanied the request. In this case, len is 0.
When TPCONV is set in flags, cd is the connection descriptor that can be used with tpsend() and tprecv() to communicate with the program that initiated the conversation.
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), then 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(), tpgetrply(), tprecv(), tpreturn(), tpsend().
<<Notes on using the function in OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.