OpenTP1 Version 7 Programming Reference C Language
tpgetrply - Get a reply from a previous service request
Format
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; |
Description
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.
<<Arguments>>
<<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:
Except as noted below, *cd is no longer valid after its reply is received.
Return value
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.
Return value | Return value (numeric) | Explanation |
---|---|---|
TPEINVAL | 4 | Invalid arguments were given (for example, cd, data, *data or len is NULL or the value of flags is invalid). If cd is non-NULL, it is still valid after this error and the reply remains unresolved. |
TPEBADDESC | 2 | The argument cd points to an invalid descriptor. |
TPEOTYPE | 18 | Either type and subtype of the reply are not known to the caller, or TPNOCHANGE was set in flags, but the buffer type and subtype specified for *data do not match type and subtype of the reply sent by the service. If this error occurs, neither *data nor *len is changed. If the reply was to be received as the caller's current transaction, the transaction is marked rollback_only since the reply is discarded. |
TPETIME | 13 | A timeout occurred. If the caller is in transaction mode, a transaction time-out occurred and the transaction is marked rollback_only; otherwise, a blocking time-out occurred and neither TPNOBLOCK nor TPNOTIME were specified. In either case, neither *data nor *len is changed (unless the caller is in transaction mode). The argument *cd remains valid (and TPGETANY was not set). If a transaction time-out occurred, any attempts to send new requests or receive outstanding replies fail with TPETIME until the transaction has been rolled back. |
TPESVCFAIL | 11 | The service function sending the caller's reply called tpreturn() with TPFAIL. This is an application-level failure. The contents of the reply sent by the service are available in the buffer pointed to by *data. If the service request was made as the caller's current transaction, the transaction is marked rollback_only.
|
TPESVCERR | 10 | An error was encountered either in invoking a service function or during its completion in tpreturn() (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither *data, nor *len is changed). If the reply was received as the caller's transaction, the transaction is marked rollback_only.
|
TPEBLOCK | 3 | When TPNOBLOCK was specified, the blocking status existed. The argument *cd remains valid. |
TPEGOTSIG | 15 | A signal was received, but TPSIGRSTRT was not set. |
TPEPROTO | 9 | tpgetrply() was called in an improper context. |
TPESYSTEM | 12 | A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner. |
TPEOS | 7 | An operating system error has occurred. The exact nature of the error is determined in a product-specific manner. |
See also
tpacall(), tpalloc(), tpreturn().
<<Notes on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.