PURPOSE

TPSEND - routine to send a message in a conversational connection

SYNOPSIS

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPSEND" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

DESCRIPTION

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(3cbl) or TPSVCSTART(3cbl).

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).

F:Following is a list of valid settings in TPSVCDEF-REC.

TPRECVONLY

This setting signifies that, after the caller's data is sent, the caller gives up control of the connection (that is, the caller can not issue any more 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 can not issue more any TPRECV(3cbl) calls). Either TPRECVONLY or TPSENDONLY must be set.

TPSENDONLY

This setting signifies that the caller wants to remain in control of the connection. Either TPRECVONLY or TPSENDONLY must be set.

TPNOBLOCK

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.

TPBLOCK

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.

TPNOTIME

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.

TPTIME

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.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted call is re-issued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

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 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.

TPEV-DISCONIMM

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(3cbl), or the originator of the connection issued TPRETURN(3cbl) 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).

TPEV-SVCFAIL

Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN(3cbl) without having control of the conversation. In addition. TPRETURN(3cbl) was issued with TPFAIL set and no data record (that is, the REC-TYPE passed to TPRETURN(3cbl) was set to SPACES)

TPEV-SVCERR

Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN(3cbl) without having control of the conversation. In addition, TPRETURN(3cbl) was issued in a manner different from that described for TPEV-SVCFAIL below.

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.

RETURN VALUES

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.

ERRORS

Under the following conditions, TPSEND fails and sets TP-STATUS to (unless otherwise noted, failure does not affect caller's transaction, if one exits):

[TPEINVAL]

Invalid arguments were given.

[TPEBADDESC]

COMM-HANDLE contains an invalid communications handle.

[TPETIME]

A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. In either case, neither DATA-REC nor TPTYPE-REC are changed. If a transaction timeout occurred, then any attempts to send or receive messages on any connections or to start a new connection will fail with [TPETIME] until the transaction has been aborted.

[TPEEVENT]

An event occurred and its type is available in TPEVENT. DATA-REC is not sent when this error occurs.

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

TPSEND was called in an improper context (for example, the connection was established such that the calling program can only receive data).

[TPESYSTEM]

A System/T error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

SEE ALSO

TPCONNECT(3cbl),
TPDISCON(3cbl),
TPRECV(3cbl)