OpenTP1 Version 7 Programming Reference C Language
tpcall - Send a service request and synchronously await its reply
Format
ANSI C, C++
#include <xatmi.h> int tpcall (char *svc, char *idata, long ilen, char **odata, long *olen, long flags) |
K&R C
#include <xatmi.h> int tpcall (svc, idata, ilen, odata, olen, flags) char *svc; char *idata; long ilen; char **odata; long *olen; long flags; |
Description
<<Arguments>>
<<svc
Specify the name of the service to be requested.>>
<<idata
Specify the pointer to the send buffer.>>
<<ilen
Specify the length of the send buffer.>>
<<odata
Specify the address of the pointer to the buffer which will contain reply data.>>
<<olen
Indicates the pointer to the long-type data giving the length of the reply buffer.>>
<<flags>>
The valid flags are as follows:
Return value
Upon successful return from tpcall() 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, tpcall() fails and sets tperrno to one of the values below. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.
Return value | Return value (numeric) | Explanation |
---|---|---|
TPEINVAL | 4 | Invalid arguments were given (for example, svc is NULL or the value of flags is invalid). |
TPENOENT | 6 | Cannot establish a connection because the service specified in svc does not exist. |
TPEITYPE | 17 | type and subtype for idata are not in a format that can be used for svc. |
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 *odata do not match type and subtype of the reply sent by the service. If this error occurs, neither *odata nor *olen is changed. If the service request was made as the caller's current transaction, the transaction is marked rollback_only since the reply is discarded. |
TPETRAN | 14 | TPNOTRAN was not set, even though transaction processing could not be performed for svc. |
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 *odata nor *olen is changed. 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 *odata. If the service request was made as the caller's current transaction, the transaction is marked rollback_only.
|
TPESVCERR | 10 | This 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 *odata, nor *olen are changed). If the reply processing for the service request was made as the caller's transaction, the transaction is marked the rollback_only status.
|
TPEBLOCK | 3 | When tpcall() for which TPNOBLOCK was specified was called, the blocking status existed. |
TPEGOTSIG | 15 | A signal was received, but TPSIGRSTRT was not set. |
TPEPROTO | 9 | tpcall() 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
tpalloc(), tpacall(), tpgetrply(), tpreturn().
<<Notes on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.