PURPOSE

tpacall - routine for sending a service request

SYNOPSIS

#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags)

DESCRIPTION

tpacall() sends a request message to the service named by svc. The request is sent out at the priority defined for svc unless overridden by a previous call to tpsprio(3c). If data is non-NULL, it must point to a buffer previously allocated by tpalloc(3c) and len should specify the amount of data in the buffer that should be sent. Note that if data points to a buffer of a type that does not require a length to be specified, (for example, an FML fielded buffer), then len is ignored (and may be 0). If data is NULL, len is ignored and a request is sent with no data portion. The type and sub-type of data must match one of the types and sub-types recognized by svc. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.

Following is a list of valid flags.

TPNOTRAN

If the caller is in transaction mode and this flag is set, then when svc is invoked, it is not performed on behalf of the caller's transaction. If svc belongs to a server that does not support transactions, then this flag must be set when the caller is in transaction mode. Note that svc may still be invoked in transaction mode but it will not be the same transaction: a svc may have as a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.

TPNOREPLY

Informs tpacall() that a reply is not expected. When TPNOREPLY is set, the function returns 0 on success, where 0 is an invalid descriptor. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. However, if the caller is in transaction mode, this flag has no effect; it is subject to the transaction time-out limit. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued.

RETURN VALUES

Upon successful completion, tpacall() returns a descriptor that can be used to receive the reply of the request sent. Otherwise it returns a value of -1 and sets tperrno to indicate the error condition.

ERRORS

Under the following conditions, tpacall() fails and sets tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)

[TPEINVAL]

Invalid arguments were given (for example, svc is NULL, data does not point to space allocated with tpalloc(3c), or flags are invalid).

[TPENOENT]

Cannot send to svc because it does not exist or is a conversational service or the name begins with "..".

[TPEITYPE]

The type and sub-type of data is not one of the allowed types and sub-types that svc accepts.

[TPELIMIT]

The caller's request was not sent because the maximum number of outstanding asynchronous requests has been reached.

[TPETRAN]

svc belongs to a server that does not support transactions and TPNOTRAN was not set.

[TPETIME]

A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tpacall() was called in an improper context.

[TPESYSTEM]

A System/T error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpacall returned successfully.

SEE ALSO

tpalloc(3c),
tpcall(3c),
tpcancel(3c),
tpgetrply(3c),
tpgprio(3c),
tpsprio(3c)