ATMI COBOL Function Reference
TPSEND()
- routine to send 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 "TPSEND" USINGTPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPSEND()
is used to send data across an open connection to another program. The caller must have control of the connection. COMM-HANDLE
specifies the open connection to send data over. COMM-HANDLE
is a communications handle returned from either TPCONNECT()
or TPSVCSTART()
.
DATA-REC
contains the data to be sent and LEN
specifies how much of the data to send. 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
is SPACES
, DATA-REC
and LEN
are ignored and a message is sent with no data (this might be done, for instance, to grant control of the connection without transmitting any data).
The following is a list of valid settings in TPSVCDEF-REC
.
This setting signifies that, after the caller's data is sent, the caller gives up control of the connection (that is, the caller cannot issue anymore TPSEND()
calls). When the receiver on the other end of the connection receives the data sent by TPSEND()
, it will also receive an event (TPEV-SENDONLY
) indicating that it has control of the connection (and cannot issue anymore TPRECV()
calls). Either TPRECVONLY
or TPSENDONLY
must be set.
This setting signifies that the caller wants to remain in control of the connection. Either TPRECVONLY
or TPSENDONLY
must be set.
The data and any events are not sent if a blocking condition exists (for example, the data buffers through which the message is sent 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 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 any underlying system calls, then the interrupted call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
If an event exists for COMM-HANDLE
, then TPSEND()
will return without sending the caller's data. The event type is returned in TPEVENT()
. Valid events for TPSEND()
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 the originator of the connection issued TPRETURN()
with open subordinate connections. 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).
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN()
without having control of the conversation. In addition. TPRETURN()
was issued with TPFAIL()
set and no data record (that is, the REC-TYPE
passed to TPRETURN()
was set to SPACES
).
Because each of these events indicates an immediate disconnection notification (that is, abortive rather than orderly), data in transit may be lost. The communications handle used for the connection is no longer valid. If the two programs were participating in the same transaction, then the transaction has been marked abort-only.
Upon successful completion, TPSEND()
sets TP-STATUS
to [TPOK
]. If an event exists and no errors were encountered, TPSEND()
sets TP-STATUS
to [TPEEVENT
]. When TP-STATUS
is set to [TPEEVENT
] and TP-EVENT
is either TPEV-SVCSUCC
or TPEV-SVCFAIL
, APPL-RETURN-CODE
contains an application-defined value that was sent as part of TPRETURN()
.
Under the following conditions, TPSEND()
fails and sets TP-STATUS
to (unless otherwise noted, failure does not affect caller's transaction, if one exits):
This error code indicates that either a timeout has occurred or TPSEND()
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 transactional 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
.
An event occurred and its type is available in TPEVENT()
. DATA-REC
is not sent when this error occurs.
TPSEND()
was called in an improper context (for example, the connection was established such that the calling program can only receive data).