ATMI COBOL Function Reference
TPGETRPLY()
- get reply from asynchronous message
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPGETRPLY" USINGTPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPGETRPLY()
returns a reply from a previously sent request. TPGETRPLY()
either returns a reply for a particular request, or it returns any reply that is available. Both options are described below.
DATA-REC
specifies where the reply is to be read into and, on input, LEN
in TPTYPE-REC
indicates the maximum number of bytes that should be moved into DATA-REC
. Also, REC-TYPE
in TPTYPE-REC
must be specified. Upon successful return from TPGETRPLY()
, LEN
contains the actual number of bytes moved into DATA-REC
, REC-TYPE
and SUB-TYPE
, both in TPTYPE-REC
, contain the data's type and subtype, respectively. If the reply is larger than DATA-REC
, then DATA-REC
will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and TPGETRPLY()
sets TPTRUNCATE()
.
If LEN
is 0
upon successful return, then the reply has no data portion and DATA-REC
was not modified. It is an error for LEN
to be 0
on input.
The following is a list of valid settings in TPSVCDEF-REC
.
This setting signifies that TPGETRPLY()
should ignore the communications handle indicated by COMM-HANDLE
in TPSVCDEF-REC
, return any reply available and set COMM-HANDLE
to the communications handle for the reply returned. If no replies exist, TPGETRPLY()
can wait for one to arrive. Either TPGETANY
or TPGETHANDLE
must be set.
This setting signifies that TPGETRPLY()
should use the communications handle identified by COMM-HANDLE
and return a reply available for that COMM-HANDLE
. If no replies exist, TPGETRPLY()
can wait for one to arrive. Either TPGETANY
or TPGETHANDLE
must be set.
When this value is set, the type of DATA-REC
is not allowed to change. That is, the type and subtype of the reply record must match REC-TYPE
and SUB-TYPE
, respectively. Either TPNOCHANGE
or TPCHANGE
must be set.
The type and/or subtype of the reply record differs from REC-TYPE
and SUB-TYPE
, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE
or TPCHANGE
must be set.
TPGETRPLY()
does not wait for the reply to arrive. If the reply is available, then TPGETRPLY()
gets the reply and returns. Either TPNOBLOCK
or TPBLOCK
must be set.
When TPBLOCK
is specified and no data is available, the caller blocks until the reply arrives 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 for its reply 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.
Except as noted below, COMM-HANDLE
is no longer valid after its reply is received.
Upon successful completion, TPGETRPLY()
sets TP-STATUS
to [TPOK
]. When TP-STATUS
is set to TPOK()
or TPESVCFAIL()
, APPL-RETURN-CODE
in TPSTATUS-REC
contains an application-defined value that was sent as part of TPRETURN()
. If the size of the incoming message was larger then the size specified in LEN
on input, TPTRUNCATE()
is set and only LEN
amount of data was moved to DATA-REC
, the remaining data is discarded.
Under the following conditions, TPGETRPLY()
fails and sets TP-STATUS
as indicated below. Note that if TPGETHANDLE
is set, then COMM-HANDLE
is invalidated unless otherwise stated. If TPGETANY
is set, then COMM-HANDLE
identifies the communications handle for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, then COMM-HANDLE
is 0
. Also, the failure does not affect the caller's transaction, if one exists, unless otherwise stated.
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE
was set and the REC-TYPE
and SUB-TYPE
do not match the type and subtype of the reply sent by the service. Neither DATA-REC
nor TPTYPE-REC
are changed. If the reply was to be received on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.
This error code indicates that either a timeout has occurred or TPGETRPLY()
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.) In either case, no changes are made to DATA-REC
or TPTYPE-REC
. If TPGETHANDLE
was set, COMM-HANDLE
remains valid unless the caller is in transaction mode.
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
.
The service routine sending the caller's reply called TPRETURN()
with TPFAIL()
. This is an application-level failure. The contents of the service's reply, if one was sent, is available in DATA-REC
. APPL-RETURN-CODE
contains an application-defined value that was sent as part of TPRETURN()
. If the reply was received on behalf of the caller's transaction, then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to TPACALL()
with TPNOREPLY
, TPNOTRAN
, and TPNOBLOCK
set.
An error was encountered by a service routine during its completion in TPRETURN()
or TPFORWAR()
(for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither DATA-REC
nor TPTYPE-REC
are changed). If the reply was received on behalf of the caller's transaction, then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to TPACALL()
with TPNOREPLY
, TPNOTRAN
, and TPNOBLOCK
set.