PURPOSE

tpsend - routine for sending a message in a conversational connection

SYNOPSIS

#include <atmi.h>
int tpsend(int cd, char *data, long len, long flags, long *revent)

DESCRIPTION

tpsend() is used to send data across an open connection to another program. The caller must have control of the connection. tpsend()'s first argument, cd, specifies the open connection over which data is sent. cd is a descriptor returned from either tpconnect(3c) or the TPSVCINFO parameter passed to a conversational service.

The second argument, data, must point to a buffer previously allocated by tpalloc(3c). len specifies how much of the buffer to send. Note that if data points to a buffer of a type that does not require a length to be specified (for example, an FML fielded buffer), then len is ignored (and may be 0). Also, data can be NULL in which case len is ignored (no application data is sent - this might be done, for instance, to grant control of the connection without transmitting any data). The type and sub-type of data must match one of the types and sub-types recognized by the other end of the connection.

Following is a list of valid flags.

TPRECVONLY

This flag 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(3c) calls).

TPNOBLOCK

The data and any events are not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued.

If an event exists for the descriptor, cd, then tpsend() will fail without sending the caller's data. The event type is returned in revent. 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(3c), or it has issued tpreturn(3c), tpcommit(3c), or tpabort(3c) 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).

TPEV_SVCERR

Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued tpreturn(3c) without having control of the conversation. In addition, tpreturn(3c) has been issued in a manner different from that described for TPEV_SVCFAIL below.

This event can be caused by an ACL permissions violation; that is, the originator does not have permission to connect to the receiving process. This event is not returned at the time the tpconnect is issued, but is returned with the first tpsend (following a tpconnect with flag TPSENDONLY) or tprecv (following a tpconnect with flag TPRECVONLY). A system event and a userlog message are also generated.

TPEV_SVCFAIL

Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued tpreturn(3c) without having control of the conversation. In addition, tpreturn(3c) has been issued with rval set to TPFAIL or TPEXIT and data set to NULL.

Because each of these events indicates an immediate disconnection notification (that is, abortive rather than orderly), data in transit may be lost. The descriptor 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.

If the value of either SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in the TM_MIB is non-zero, TPESVCERR is returned when a service timeout occurs. In this case, tperrordetail(3) will return TPED_SVCTIMEOUT.

RETURN VALUES

Upon return from tpsend() where revent is set to either TPEV_SVCSUCC or TPEV_SVCFAIL, the global variable pointed at by tpurcode contains an application-defined value that was sent as part of tpreturn(). The function tpsend() returns -1 on error and sets tperrno to indicate the error condition. Also, if an event exists and no errors were encountered, tpsend() returns -1 and tperrno is set to [TPEEVENT].

ERRORS

Under the following conditions, tpsend(3c) fails and sets tperrno to:

[TPEINVAL]

Invalid arguments were given (for example, data does not point to a buffer allocated by tpalloc(3c) or flags are invalid).

[TPEBADDESC]

cd is invalid.

[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 was specified. In either case, no changes are made to *data, its contents, or *len. 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. data is not sent when this error occurs. The event type is returned in revent.

[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 occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

SEE ALSO

tpalloc(3c),
tpconnect(3c),
tpdiscon(3c),
tprecv(3c),
tpservice(3c)