ANSI C, C++

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

K&R C

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

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

The second argument, data, must point to a buffer previously allocated by tpalloc(). 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, len is ignored (and may be 0). If data points to a buffer that does require a length, len must not be zero. 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.

<<cd

Specify a descriptor.>>

<<data

Specify the pointer to the buffer containing the data to be sent.>>

<<len

Specify the length of the buffer.>>

<<flags

Indicates flags.>>

<<revent

Indicates the pointer to the long-type data about the event.>>

The valid flags are as follows:

TPRECVONLY

This flag signifies that, after the caller's data is sent, the caller gives up control of the connection (that is, the caller cannot issue any more tpsend() calls). When the receiver at the other end of the connection receives the data sent by tpsend(), it also receives an event (TPEV_SENDONLY) indicating that it has control of the connection (and cannot issue more any tprecv() 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, the interrupted system call is reissued.

If an event exists for the descriptor, cd, tpsend() fails 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 either issued an immediate disconnect on the connection via tpdiscon(), or it issued tpreturn(), tx_commit() or tx_rollback() with the connection still open. This event is also returned to the originator or subordinate when a connection is broken due to a communication 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() without having control of the conversation. In addition, tpreturn() was issued in a manner different from that described for TPEV_SVCFAIL below.

TPEV_SVCFAIL

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 the TPFAIL and no data (that is, rval was set to TPFAIL and data was 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, the transaction has been marked rollback-only.

The function tpsend() returns -1 on error and sets tperrno to indicate the error condition. Upon return from tpsend() where revent is set to TPEV_SVCFAIL, the tpurcode global contains an application-defined value that was set as part of tpreturn().

Errors

Under the following conditions, tpsend() fails and sets tperrno to one of the following values:

tpalloc(), tpconnect(), tpdiscon(), tprecv(), tpreturn().

1. <<The TPNOBLOCK flag is invalid under the relevant version of the OpenTP1. Therefore, the error code TPEBLOCK will not be returned to tperrno. The OpenTP1 is designed so that if communication is impossible because of blocking, TPESYSTEM is returned as when communication is impossible because of network failure.>>
2. <<The TPNOTIME flag is invalid under the relevant version of the OpenTP1.>>
3. <<The TPSIGRSTRT flag is invalid. Regardless of this flag, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
4. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
5. <<Under the relevant version of the OpenTP1, data which requires rollback causes the return of TPESYSTEM unless otherwise specified by the X/Open. However, the rollback_only state may not come into effect even when TPESYSTEM returns.>>
6. <<Under the OpenTP1, even if the mate of conversation has called the function tpdiscon() or tpreturn(), the function tpsend() cannot generate an event provided that the process which calls the function tpsend() has not received an event.>>
7. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, conversational service communication cannot be held. If this is done, the system operation is undefined.>>