tpgetrply(3c)-routine for getting a reply from a previous request
#include <atmi.h>
int tpgetrply(int *cd, char **data, long *len, long flags)
tpgetrply(3c) 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(3c) 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 data. FML and FML32 buffers often assume a minimum size of 4096 bytes; if the reply is larger than 4096, 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 send. 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(3c) 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
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
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
TPSIGRSTRT
Except as noted below, *cd is no longer valid after its reply is received.
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.
Under the following conditions, tpgetrply(3c) 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. If a call fails with a particular tperrno value, a subsequent call to tperrordetail(3c) with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the tperrordetail(3c) reference page for more information.
TPEINVAL]
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]
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]
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]
tpreturn 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]
tpreturn or tpforward (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 is non-zero, TPESVCERR is returned when a service timeout occurs.
TPEBLOCK]
TPNOBLOCK was specified. *cd remains valid.
TPGOTSIG]
TPSIGRSTRT was not specified.
TPEPROTO]
tpgetrply was called in an improper context.
TPESYSTEM]
TPEOS]
TPEOS may possibly be returned.
tpacall(3c), tpalloc(3c), tpcancel(3c), tperrordetail(3c), tprealloc(3c), tpreturn(3c), tpstrerrordetail(3c), tptypes(3c)