ATMI C Function Reference
tpacall()
—Routine for sending a service request.
#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags)
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 tpspri()
. If data
is non-NULL, it must point to a buffer previously allocated by tpalloc()
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 subtype of data
must match one of the types and subtypes recognized by svc
. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.
The following is a list of valid flags
:
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.
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.
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).
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
In a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpacall()
.
Upon successful completion, tpacall()
returns a descriptor that can be used to receive the reply of the request sent.
Upon failure, tpacall()
returns a value of -1 and sets tperrno
to indicate the error condition.
Upon failure, tpacall()
sets tperrno
to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
Invalid arguments were given (for example, svc
is NULL, data
does not point to space allocated with tpalloc()
, or flags
are invalid).
The caller's request was not sent because the maximum number of outstanding asynchronous requests has been reached.
This error code indicates that either a timeout has occurred or tpacall()
has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK
and/or TPNOTIME
is specified.)
If a transaction timeout has 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).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
tpalloc(3c)
, tpcall(3c)
, tpcancel(3c)
, tpgetrply(3c)
, tpgprio(3c)
, tpsprio(3c)