PURPOSE
tpgetrply - routine for getting a reply from a
previous request
SYNOPSIS
#include <atmi.h>
int tpgetrply(int *cd, char **data, long *len, long flags)
DESCRIPTION
tpgetrply() returns a reply from a previously sent request.
This function's first argument, cd, points to a call
descriptor returned by tpacall(3c).
By default, the function waits until the reply matching *cd
arrives or a timeout occurs.
data must be the address of a pointer to a buffer
previously allocated by tpalloc(3c)
and len should point to a long that tpgetrply() sets to
the amount of data successfully received. Upon successful return,
*data points to a buffer containing the reply and *len
contains the size of the buffer. FML and FML32
buffers often assume a minimum size of 4096 bytes; if the reply
is larger than 4096 bytes, the size of the buffer is increased to
a size large enough to accommodate the data being returned.
Buffers on the sending side that may be only partially filled
(for example, FML or STRING buffers) will have only the amount
that is used sent. The system may then enlarge the received data
size by some arbitrary amount. This means that the receiver may
receive a buffer that is smaller than what was originally
allocated by the sender, yet larger than the data that was sent.
The receive buffer may grow, or it may shrink, and its address
almost invariably changes, as the system swaps buffers around
internally. To determine whether (and how much) a reply buffer
changed in size, compare its total size before tpgetrply
was issued with *len. See intro(3) for more information about buffer
management.
If *len is 0, then the reply has no data portion and
neither *data nor the buffer it points to were modified.
It is an error for *data or len to be NULL.
Following is a list of valid flags.
- TPGETANY
- This flag signifies that tpgetrply() should ignore the
descriptor pointed to by cd, return any reply
available and set cd to point to the call
descriptor for the reply returned. If no replies exist,
tpgetrply() by default will wait for one to arrive.
- TPNOCHANGE
- By default, if a buffer is received that differs in type
from the buffer pointed to by *data, then *data's
buffer type changes to the received buffer's type so long
as the receiver recognizes the incoming buffer type. When
this flag is set, the type of the buffer pointed to by *data
is not allowed to change. That is, the type and sub-type
of the received buffer must match the type and sub-type
of the buffer pointed to by *data.
- TPNOBLOCK
- tpgetrply() does not wait for the reply to arrive. If the
reply is available, then tpgetrply() gets the reply and
returns. When this flag is not specified and a reply is
not available, the caller blocks until the reply arrives
or a timeout occurs (either transaction or blocking
timeout).
- TPNOTIME
- This flag signifies that the caller is willing to block
indefinitely for its reply and wants to be immune to
blocking timeouts. Transaction timeouts may still occur.
- TPSIGRSTRT
- If a signal interrupts any underlying system calls, then
the interrupted system call is re-issued.
Except as noted below, *cd is no longer valid after its
reply is received.
RETURN VALUES
Upon successful return from tpgetrply() or upon return where tperrno
is set to TPESVCFAIL, tpurcode contains an
application defined value that was sent as part of tpreturn().
tpgetrply() returns -1 on error and sets tperrno to
indicate the error condition.
ERRORS
Under the following conditions, tpgetrply() fails and sets tperrno
as indicated below. Note that if TPGETANY is not set,
then *cd is invalidated unless otherwise stated. If TPGETANY
is set, then cd points to the descriptor for the reply on
which the failure occurred; if an error occurred before a reply
could be retrieved, then cd points to 0. Also, the failure
does not affect the caller's transaction, if one exists, unless
otherwise stated.
- [TPEINVAL]
- Invalid arguments were given (for example, cd, data,
*data or len is NULL or flags are
invalid). If cd is non-NULL, then it is still
valid after this error and the reply remains outstanding.
- [TPEOTYPE]
- Either the type and sub-type of the reply are not known
to the caller; or, TPNOCHANGE was set in flags
and the type and sub-type of *data do not match
the type and sub-type of the reply sent by the service.
Regardless, neither *data, its contents nor *len
are changed. If the reply was to be received on behalf of
the caller's current transaction, then the transaction is
marked abort-only since the reply is discarded.
- [TPEBADDESC]
- cd points to an invalid descriptor.
- [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
were specified. In either case, neither *data, its
contents nor *len are changed. *cd remains
valid unless the caller is in transaction mode (and TPGETANY
was not set). 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(3c) with TPNOTRAN,
TPNOBLOCK and TPNOREPLY set).
- [TPESVCFAIL]
- The service routine sending the caller's reply called tpreturn(3c) with
TPFAIL. This is an application-level failure.
The contents of the service's reply, if one was sent, is
available in the buffer pointed to by *data. If
the service request was made on behalf of the caller's
transaction, then the transaction is marked abort-only.
Note that so long as the transaction has not timed out,
further communication may be performed before completely
aborting the transaction and that any work performed on
behalf of the caller's transaction will be aborted upon
transaction completion (that is, for subsequent
communication to have any lasting effect, it should be
done with TPNOTRAN set).
- [TPESVCERR]
- A service routine encountered an error either in tpreturn(3c) or tpforward(3c) (for
example, bad arguments were passed). No reply data is
returned when this error occurs (that is, neither *data,
its contents nor *len are changed). If the service
request was made on behalf of the caller's transaction,
then the transaction is marked abort-only. Note that so
long as the transaction has not timed out, further
communication may be performed before completely aborting
the transaction and that any work performed on behalf of
the caller's transaction will be aborted upon transaction
completion (that is, for subsequent communication to have
any lasting effect, it should be done with TPNOTRAN
set). If either SVCTIMEOUT in the ubbconfig
file or TA_SVCTIMEOUT in the TM_MIB
are non-zero, TPESVCERR is returned when a
service timeout occurs. In this case, tperrordetail(3)
will return TPED_SVCTIMEOUT.
- [TPEBLOCK]
- A blocking condition exists and TPNOBLOCK was
specified. *cd remains valid.
- [TPGOTSIG]
- A signal was received and TPSIGRSTRT was not
specified.
- [TPEPROTO]
- tpgetrply() 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 possibly be returned.
SEE ALSO
tpacall(3c),
tpalloc(3c),
tpcancel(3c),
tprealloc(3c),
tpreturn(3c),
tperrordetail(3c),
tpstrerrordetail(3c),
tptypes(3c)