Section 3c - C Functions

ATMI C Function Reference

tpservice(3c)

Name

tpservice()—Template for service routines.

Synopsis

#include <atmi.h>                   /* C interface */  
void tpservice(TPSVCINFO *svcinfo)  /* C++ interface - must have
                                     * C linkage */  
extern "C" void tpservice(TPSVCINFO *svcinfo)

Description

tpservice() is the template for writing service routines. This template is used for services that receive requests via tpcall(), tpacall() or tpforward() 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, then the service routine may originate as many transactions as it wants using tpbegin(), tpcommit(), and tpabort(). 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[32];
char        *data;
long        len;  
long        flags;  
int         cd;  
long        appkey;  
CLIENTID     cltid;

name is populated with the service name that the requester used to invoke the service.

The setting of flags upon entrance to a service routine indicates attributes which the service routine may want to note. The following are the possible values for flags:

TPCONV

A connection request for a conversation has been accepted and the descriptor for the conversation is available in cd. If not set, then 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 will not be set if TPCONV is set.

TPSENDONLY

The service is invoked such that it can only 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 only send data. This flag is mutually exclusive with TPSENDONLY and may be set only when TPCONV is also set.

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 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 either tpreturn() or tpforward() when the service ends. If a different buffer is passed to those routines, then that buffer is freed by them. Note that the buffer pointed to by data will be overwritten by the next service request even if this buffer is not passed to tpreturn() or tpforward(). data may be NULL if no data accompanied the request. In this case, len will be 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.

appkey is set to the application key assigned to the requesting client by the application defined authentication service. This key value is passed along with any and all service requests made while within this invocation of the service routine. appkey will have a value of -1 for originating clients that do not pass through the application authentication service.

cltid is the unique client identifier for the originating client associated with this service request. The definition of this structure is made available to the application in atmi.h solely so that client identifiers may be passed between application servers if necessary. Therefore, the semantics of the fields defined below are not documented and applications should not manipulate the contents of CLIENTID structures. Doing so will invalidate the structures. The CLIENTID structure includes the following member:

long clientdata[4];

Note that for C++, the service function must have C linkage. This is done by declaring the function as `extern "C."'

Return Values

A service routine does not return any value to its caller, the communication manager dispatcher; thus, it is declared as a void. Service routines, however, are expected to terminate using either tpreturn() or tpforward(). A conversational service routine must use tpreturn(), and cannot use tpforward(). If a service routine returns without using either tpreturn() or tpforward() (that is, it uses the C language return statement or just simply "falls out of the function") or tpforward() is called from a conversational server, the server will print a warning message in a log file and return a service error to the originator or requester. All open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be marked stale. If the server was in transaction mode at the time of failure, the transaction is marked abort-only. Note also that if either tpreturn() or tpforward() are used outside of a service routine (for example, in clients, or in tpsvrinit() or tpsvrdone()), then these routines simply return 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().