ANSI C, C++

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

K&R C

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

The function tpacall() sends a request message to the service named by svc. If data is non-NULL, it must point to a buffer previously allocated by tpalloc() and len should specify the amount of data in the buffer that should be sent. Note that if data points to a buffer of a type that does not require a length to be specified, len is ignored (and may be 0). If data is NULL, len is ignored and a request is sent with no data portion. The type and sub-type of data must match one of the types and sub-types recognized by svc. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.

<<svc

Specify the name of the service to be requested.>>

<<data

Specify the pointer to the send data storage area.>>

<<len

Specify the length of the send data. >>

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

TPNOREPLY

This setting informs tpacall() that a reply is not expected. When TPNOREPLY is set, the function returns 0 on success, where 0 is an invalid descriptor. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). 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 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.

Upon successful completion, tpacall() returns a descriptor that can be used to receive the reply of the request sent. Otherwise it returns -1 and sets tperrno to indicate the error condition.

Errors

Under the following conditions, tpacall() fails and sets tperrno to one of the values below. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.

tpalloc(), tpcall(), tpcancel(), tpgetrply().

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. <<The TPNOTIME flag is invalid under the relevant version of the OpenTP1.>>
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, the function tpacall() normally returns, but TPESYSTEM will return when the function tpgetrply() is called. Therefore, the error condition is identified. 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. <<Under the relevant version of the OpenTP1, TPELIMIT will not return.>>
8. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, send data must not exceed the length specified in the length operand of the NET buffer group definition nettbuf (NET/Library common definition).>>
9. <<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.>>
10. <<If the number of system associations is insufficient during OSI TP communication, the function outputs a log message and returns with TPESYSTEM.>>
11. <<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.>>
12. <<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.>>
13. <<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.>>