ANSI C, C++

#include <xatmi.h>
void tpservice (TPSVCINFO *svcinfo)

K&R C

#include <xatmi.h>
void tpservice (svcinfo)
TPSVCINFO    *svcinfo;

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.

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:

TPCONV

A connection request for a conversation has been accepted and the descriptor for the conversation is available in cd. If not set, this is a request/response service and cd is not valid.

TPTRAN

The service routine is in transaction mode.

TPNOREPLY

The caller is not expecting a reply. This option is not set if TPCONV is set.

TPSENDONLY

The service is invoked such that it can send data across the connection and the program on the other end of the connection can only receive data. This flag is mutually exclusive with TPRECVONLY and may be set only when TPCONV is also set.

TPRECVONLY

The service is invoked such that it can only receive data from the connection and the program on the other end of the connection can send data. This flag is mutually exclusive with TPSENDONLY and may be set only when TPCONV is also set.

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.

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().

tpalloc(), tpcall(), tpconnect(), tpgetrply(), tprecv(), tpreturn(), tpsend().

1. <<For an OpenTP1 UAP (service function), always write return immediately after tpreturn(). This is because OpenTP1 execution processes are restricted. After calling tpreturn(), immediately execute return. No processing must be performed between tpreturn() and return. Updating resources between a call to tpreturn() and execution of return within transaction processing includes the updating in the transaction.>>
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.>>