6.3.1 Sending an Asynchronous Request
The
tpacall(3c) function sends a request to a service and immediately returns. Use the following signature to call the tpacall() function:
int
tpacall(char *svc, char *data, long len, long flags)Table 6‑2 describes the arguments to the tpacall() function.
Table 6-2 tpacall( ) Function Arguments
| Argument | Description |
|---|---|
svc
|
Pointer to the name of the service offered by your application. |
data
|
Pointer that contains the address of the data portion of the request. The pointer must reference a typed buffer that was allocated by a prior call to tpalloc(). Note that the type (and optionally the subtype) of idata must match the type (and optionally the subtype) expected by the service routine. If the types do not match, the system sets tperrno to TPEITYPE and the function call fails. If the request requires no data , set data to the NULL pointer. This setting means that the parameter can be ignored. If no data is being sent with the request, you do not need to allocate a buffer for data .
|
len
|
Length of the request data in the buffer referenced by data . If the buffer is a self-defining type, that is, an STRING buffer, you can set this argument to zero, indicating that the argument should be ignored.
|
flags
|
Flag options. You can list a group of flags by using the logical OR operator. If you set this value to zero, the communication is conducted in the default manner. For a list of valid flags and defaults, refer to tpacall(3c) in the Oracle Tuxedo ATMI C Function Reference.
|
The tpacall() function sends a request message to the service named in the svc parameter and immediately returns from the call. Upon successful completion of the call, the tpacall() function returns an integer that serves as a descriptor used to access the correct reply for the relevant request. While tpacall() is in transaction mode (as described in Writing Global Transactions) there may not be any outstanding replies when the transaction commits; that is, within a given transaction, for each request for which a reply is expected, a corresponding reply must eventually be received.
If the value TPNOREPLY is assigned to the flags parameter, the parameter signals to tpacall() that a reply is not expected. When this flag is set, on success tpacall() returns a value of 0 as the reply descriptor. If subsequently passed to the tpgetrply() function, this value becomes invalid. Guidelines for using this flag value correctly when a process is in transaction mode are discussed in Writing Global Transactions.
On error, tpacall() returns -1 and sets tperrno(5) to a value that reflects the nature of the error. tpacall() returns many of the same error codes as tpcall(). The differences between the error codes for these functions are based on the fact that one call is synchronous and the other, asynchronous. These errors are discussed at length in Managing Errors.