ANSI C, C++

#include <xatmi.h>
int tpgetrply (int *cd, char **data, long *len, long
               flags)

K&R C

#include <xatmi.h>
int tpgetrply (cd, data, len, flags)
int      *cd;
char     **data;
long     *len;
long     flags;

The function tpgetrply() returns a reply from a previously-sent service request. This function's first argument, cd, points to a call descriptor returned by tpacall(). 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() and len should point to a long that tpgetrply() sets to the amount of data successfully received. tpgetrply() ensures that the request fits into the specified buffer by growing the buffer if necessary. Upon successful return, *data points to a buffer containing the reply and *len contains the size of the data. Note that *data may have changed upon return for reasons other than an increase in the size of the buffer. If *len is greater than the total size of the buffer before the call, the buffer's new size is *len. If *len is 0, then the reply dequeued 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.

<<cd

Specify a descriptor.>>

<<data

Specify the address of the pointer to the buffer which will contain received data.>>

<<len

Specify the address of the area which will contain the length of received data.>>

<<flags>>

The valid flags are as follows:

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, by default tpgetrply() waits 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, 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, the interrupted system call is reissued.

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, the tpurcode global contains an application-defined value that was sent as part of tpreturn(). Otherwise, it returns -1 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, *cd is invalidated unless otherwise stated. If TPGETANY is set, cd points to the descriptor for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, cd points to 0. Also, the failure does not affect the caller's transaction, if one exists, unless otherwise stated.

tpacall(), tpalloc(), tpreturn().

1. <<The TPSIGRSTRT flag is invalid. Regardless of this flag, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
2. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
3. <<Under the relevant version of the OpenTP1, data which requires rollback causes the return of TPESYSTEM unless otherwise specified by the X/Open. However, the rollback_only state may not come into effect even when TPESYSTEM returns.>>
4. <<If the function tpacall() passes data of a type that cannot be used by the called service, it returns normally, but the function tpgetrply() will encounter an error. If the function tpgetrply() encounters a TPESYSTEM error, check the results of the function tpacall() as well.>>
5. <<If an SPP to which a service was requested terminates abnormally, the function might return with a TPETIME error before the time specified in the watch_time operand in the definition has elapsed. If 0 (wait until a response is received) is specified in the watch_time operand, the function might return with a TPEPROTO error.>>
6. <<The function returns with a TPEPROTO error if the OpenTP1 security facility is used but the service request is not authenticated. Whether the cause of the error return is because the service request is not authenticated can be checked with the UAP trace detail error code.>>
7. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, receive data must not exceed the length specified in the length operand of the NET buffer group definition nettbuf (NET/Library common definition).>>
8. <<Suppose that inter-TP1 OSI TP communication is in use. When a service with N specified for the atomic_update clause is called as a transaction, TPESVCERR is returned to the service requester.>>
9. <<Suppose that a service called via TCP/IP communication calls a service via OSI TP communication and that the service function ends without receiving a response. The UAP which called the service via TCP/IP communication receives a normal response message. The functions tpcall() and tpgetrply() return normally.>>
10. <<The behavior caused by XATMI errors encountered during OSI TP communication may be different from the behavior caused by errors encountered conventional TCP/IP communication.>>