ATMI COBOL Function Reference
TPRECV()
- receive a message in a conversational connection
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPRECV" USINGTPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPRECV()
is used to receive data sent across an open connection from another program. COMM-HANDLE
, specifies on which open connection to receive data. COMM-HANDLE
is a communications handle returned from either TPCONNECT()
or TPSVCSTART()
. DATA-REC
specifies where the message is read into, and, on input, LEN
indicates the maximum number of bytes that should be moved into DATA-REC
.
Upon successful and for several event types, LEN
contains the actual number of bytes moved into DATA-REC
. REC-TYPE
and SUB-TYPE
contain the data's type and subtype, respectively. If the message 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 TPRECV()
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.
TPRECV()
can be issued only by the program that does not have control of the connection.
The following is a list of valid settings in TPSVCDEF-REC
.
When this setting is used, the type of DATA-REC
is not allowed to change. That is, the type and subtype of the message received must match REC-TYPE
and SUB-TYPE
, respectively. Either TPNOCHANGE
or TPCHANGE
must be set.
The type and/or subtype of the message received is allowed to differ from those specified in REC-TYPE
and SUB-TYPE
, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE
or TPCHANGE
must be set.
TPRECV()
does wait for data to arrive. If data is already available to receive, then TPRECV()
gets the data and returns. Either TPNOBLOCK
or TPBLOCK
must be set.
When TPBLOCK
is specified and no data is available to receive, the caller blocks until data arrives. 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 will still affect the program. 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 the underlying receive system call, then the call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
If a signal interrupts any underlying system calls, then the interrupted system call is not restarted and the call fails. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
If an event exists for the communications handle, COMM-HANDLE
, then TPRECV()
will return setting TP-STATUS
to TPEEVENT()
. The event type is returned in TPEVENT()
. Data can be received along with the TPEV-SVCSUCC
, TPEV-SVCFAIL
, and TPEV-SENDONLY
events. Valid events for TPRECV()
are as follows.
Received by the subordinate of a conversation, this event indicates that the originator of the conversation has issued an immediate disconnect on the connection via TPDISCON()
, or an error occurred when the originator issued TPRETURN()
or TPCOMMIT()
with the connection still open. This event is also returned to the originator or subordinate when a connection is broken due to a communications error (for example, a server, machine, or network failure). Because this is an immediate disconnection notification (that is, abortive rather than orderly), data in transit may be lost. If the two programs were participating in the same transaction, then the transaction is marked abort-only. COMM-HANDLE
is no longer valid.
The program on the other end of the connection has relinquished control of the connection. The recipient of this event is allowed to send data but cannot receive any data until it relinquishes control.
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN()
. TPRETURN()
encountered an errors that precluded the service from returning successfully. For example, bad arguments may have been passed to TPRETURN()
or TPRETURN()
may have been called while the service had open connections to other subordinates. Due to the nature of this event, any application-defined data or return code are not available. The connection has been torn down and COMM-HANDLE
is no longer valid. If this event occurred as part of the recipient's transaction, then the transaction is marked as abort-only.
Received by the originator of a conversation, this event indicates that the subordinate service on the other end of the conversation has finished unsuccessfully as defined by the application (that is, it called TPRETURN()
with TPFAIL()
or TPEXIT()
). If the subordinate service was in control of this connection when TPRETURN()
was called, then it can pass an application-defined return value and a record back to the originator of the connection. As part of ending the service routine, the server has torn down the connection. Thus, COMM-HANDLE
is no longer valid. If this event occurred as part of the recipient's transaction, then the transaction is marked abort-only.
Received by the originator of a conversation, this event indicates that the subordinate service on the other end of the conversation has finished successfully as defined by the application (that is, it called TPRETURN()
with TPSUCCESS()
). As part of ending the service routine, the server has torn down the connection. Thus, COMM-HANDLE
is no longer valid. If the recipient is in transaction mode, then it can either commit (if it is also the initiator) or abort the transaction causing the work done by the server (if also in transaction mode) to either commit or abort.
Upon successful completion, TPRECV()
sets TP-STATUS
to [TPOK
]. When TP-STATUS
is set to [TPEEVENT
] and TPEVENT()
is either TPEV-SVCSUCC
or TPEV-SVCFAIL
, APPL-RETURN-CODE
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, TPRECV()
fails and sets TP-STATUS
to (unless otherwise noted, failure does not affect the caller's transaction, if one exists):
Either the type of subtype of the incoming message are not known to the caller, or TPNOCHANGE
was set and REC-TYPE
and SUB-TYPE
do not match the type and subtype of the incoming message. If the conversation is part of the caller's transaction, then the transaction is marked abort-only since the incoming message is discarded.
This error code indicates that either a timeout has occurred or TPRECV()
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 DATAREC
.
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 an ATMI call 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
.
TPRECV()
was called in an improper context (for example, the connection was established such that the calling program can only send data).
A server can pass an application-defined return value and typed record when calling TPRETURN()
. The return value is available in APPL-RETURN-CODE
and the record is available in DATA-REC
.