OpenTP1 Version 7 Programming Reference C Language

[Contents][Index][Back][Next]

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

The function tpcall() sends a request and synchronously awaits its reply. A call to this function is the same as calling tpacall() immediately followed by tpgetrply(). The function tpcall() sends a request to the service named by svc. The data portion of a request is pointed to by idata, a buffer previously allocated by tpalloc(). The argument ilen specifies how much of idata to send. Note that if idata points to a buffer of a type that does not require a length to be specified, ilen is ignored (and may be 0). If data points to a buffer that does require a length, len must not be zero. Also, idata may be NULL in which case ilen is ignored. The type and sub-type of idata must match one of the types and sub-types recognized by svc.

odata is the address of a pointer to the buffer where a reply is read into, and the length of that reply is returned in *olen. *odata must point to a buffer originally allocated by tpalloc(). If the same buffer is to be used for both sending and receiving, odata should be set to the address of idata. To determine whether a reply buffer changed in size, compare its (total) size before tpcall() was issued with *olen. If *olen is larger, then the buffer has grown; otherwise, the buffer has not changed size. Also, if idata and *odata were equal when tpcall() was invoked, and *odata is changed, idata no longer points to a valid address. Note that *odata may change for reasons other than the buffer's size increased. If *olen is 0 upon return, then the reply has no data portion and neither *odata nor the buffer it points to were modified. It is an error for *odata or olen to be NULL.

<<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:

TPNOTRAN
If the caller is in transaction mode and this flag is set, when svc is invoked, it is not performed on behalf of the caller's transaction. If svc does not support transactions, this flag must be set when the caller is in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.

TPNOCHANGE
By default, if a buffer is received that differs in type from the buffer pointed to by *odata, *odata'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 *odata 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 *odata.

TPNOBLOCK
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Note that this flag applies only to the send portion of tpcall(); the function may block waiting for the reply. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME
This flag signifies that the caller is willing to block indefinitely 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.

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.

Note
So long as the transaction has not timed out, further communication may be performed up until before rollback. In this case, any work performed as the caller's transaction is rolled back upon transaction completion. Be sure to set TPNOTRAN for communication with continuous processing enabled. Depending on the transaction function, some processing is performed to rollback the caller's transaction.
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.

Note
So long as the transaction has not timed out, further communication may be attempted before rolling back the transaction. Such attempts may be processed normally or may fail (producing an error return or event). Be sure to set TPNOTRAN for communication with continuous processing enabled. Depending on the transaction function, some processing is performed to rollback the caller's transaction.
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>>

  1. <<The TPNOBLOCK flag is invalid under the relevant version of the OpenTP1. Therefore, the error code TPEBLOCK will not be returned to tperrno. The OpenTP1 is designed so that if communication is impossible because of blocking, TPESYSTEM is returned as when communication is impossible because of network failure.>>
  2. <<Under the relevant version of the OpenTP1, the TPNOTIME flag is valid only when a reply is received. It is invalid when blocking occurs at the time of request sending.>>
  3. <<The TPSIGRSTRT flag is invalid. Regardless of this flag, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
  4. <<Under the relevant version of the OpenTP1, TPEITYPE will not return. If data of a type unavailable with svc is passed, TPESYSTEM will return. If the calling program is in transaction mode, the rollback_only state comes into effect.>>
  5. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
  6. <<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.>>
  7. <<If an SPP to which the service request is addressed terminates abnormally, the function may return with a TPETIME error before the time specified for watch_time in the definition has elapsed. If 0 (wait until response reception) is specified for watch_time, the function may return with a TPEPROTO error.>>
  8. <<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.>>
  9. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, a line failure forces control to return, and outputs TPESVCERR.>>
  10. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, transmission data must not exceed the length specified in the length operand of the NET buffer group definition nettbuf (NET/Library common definition).>>
  11. <<During OSI TP communication, the following conditions cause a TPESVCERR error when an attempt is made to issue the function tpcall() or tpgetrply(); during TCP/IP communication, they cause a TPENOENT or TPESYSTEM error when the same attempt is made:
    • The specified service does not exist at the request destination.
    • The typed buffer is not recognized by the server.
    • Service activation encounters an error.>>
  12. <<If the number of system associations is insufficient during OSI TP communication, the function outputs a log message and returns with TPESYSTEM.>>
  13. <<While OSI TP communication is in use, blocking time-out occurs even if TPNOTIME is specified. While TCP/IP communication is in use, blocking time-out occurs during non-transaction periods.>>
  14. <<For OSI TP communication, the value assigned to the user service definition message_store_buflen must be equal to or greater than the size specified by nettbuf -g. For TCP/IP communication, the same rules as for the function dc_rpc_call() apply.>>
  15. <<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.>>
  16. <<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.>>
  17. <<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.>>