ATMI COBOL Function Reference
TPACALL()
- routine to send a message to a service asynchronously
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPACALL" USINGTPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPACALL()
sends a request message to the service named by SERVICE-NAME IN
TPSVCDEF-REC
. The request is sent out at the priority defined for SERVICE-NAME
unless overridden by a previous call to TPSPRIO()
. DATA-REC
is a message to be sent and LEN IN
TPTYPE-REC
specifies the amount of data in DATA-REC
that should be sent. Note that if DATA-REC
is a record of a type that does not require a length to be specified, then LEN
is ignored (and may be 0
). If REC-TYPE IN
TPTYPE-REC
is SPACES
, DATA-REC
and LEN
are ignored and a request is sent with no data portion. If REC-TYPE
is STRING
and LEN
is 0
, then the request is sent with no data portion. The REC-TYPE
and SUB-TYPE
of DATA-REC
must match one of the REC-TYPE
and SUB-TYPE
s recognized by SERVICE-NAME
. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.
The following is a list of valid settings in TPSVCDEF-REC
.
If the caller is in transaction mode and this setting is used, then when SERVICE-NAME
is invoked, it is not performed on behalf of the caller's transaction. If SERVICE-NAME
belongs to a server that does not support transactions, then this setting must be used when the caller is in transaction mode. A caller in transaction mode that uses this setting is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller's transaction is not affected. Either TPNOTRAN
or TPTRAN
must be set.
If the caller is in transaction mode and this setting is used, then when SERVICE-NAME
is invoked, it is performed on behalf of the caller's transaction. This setting is ignored if the caller is not in transaction mode. Either TPNOTRAN
or TPTRAN
must be set.
Informs TPACALL()
that a reply is not expected. When TPNOREPLY
is set, the routine returns [TPOK
] on success and sets COMM-HANDLE IN
TPSVCDEF-REC
to 0
, an invalid communications handle. When the caller is in transaction mode, this setting cannot be used when TPTRAN
is also set. Either TPNOREPLY
or TPREPLY
must be set.
Informs TPACALL()
that a reply is expected. When TPREPLY
is set, the routine returns [TPOK
] on success and sets COMM-HANDLE
to a valid communications handle. When the caller is in transaction mode, this setting must be used when TPTRAN
is also set. Either TPNOREPLY
or TPREPLY
must be set.
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Either TPNOBLOCK
or TPBLOCK
must be set.
When TPBLOCK
is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK
or TPBLOCK
must be set.
This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME
or TPTIME
must be set.
This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME
or TPTIME
must be set.
If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
Upon successful completion, TPACALL()
sets TP-STATUS
to [TPOK
]. In addition, if TPREPLY
was set in TPSVCDEF-REC
, then TPCALL()
returns a valid communications handle in COMM-HANDLE
that can be used to receive the reply of the request sent.
Under the following conditions, TPACALL()
fails and sets TP-STATUS
to (unless otherwise noted, failure does not affect the caller's transaction, if one exists):
Cannot send to SERVICE-NAME
because it does not exist or is not a request/response service (that is, it is a conversational service).
The pair REC-TYPE
and SUB-TYPE
is not one of the allowed types and subtypes that SERVICE-NAME
accepts.
The caller's request was not sent because the maximum number of outstanding asynchronous requests has been reached.
This error code indicates that either a timeout has occurred or TPACALL()
has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout can occur only if both TPBLOCK
and TPTIME
are specified.)
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME
until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, TPACALL()
with TPNOTRAN
, TPNOBLOCK
, and TPNOREPLY
set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
TPCALL(3cbl)
, TPCANCEL(3cbl)
, TPGETRPLY(3cbl)
, TPGPRIO(3cbl)
, TPSPRIO(3cbl)