ATMI C Function Reference
tpsend()
—Routine for sending a message in a conversational connection.
#include <atmi.h>
int tpsend(intcd
, char *
data
, long
len
, long
flags
, long *
revent
)
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()
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 (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 subtype of data
must match one of the types and subtypes recognized by the other end of the connection.
The following is a list of valid flags
:
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()
calls).
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).
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
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:
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 it issued tpreturn()
, tpcommit()
or tpabort()
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).
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()
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 log message are also generated.
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 a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpsend()
.
Upon return from tpsend()
where revent
is set to either TPEV_SVCSUCC
or TPEV_SVCFAIL
, the tpurcode()
global 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]
.
Upon failure, tpsend()
sets tperrno
to one of the following values:
Invalid arguments were given (for example, data
does not point to a buffer allocated by tpalloc()
or flags
are invalid).
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 cannot occur if TPNOBLOCK
and/or TPNOTIME
is 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
.
tpsend()
was called in an improper context (for example, the connection was established such that the calling program can only receive data).
tpalloc(3c)
, tpconnect(3c)
, tpdiscon(3c)
, tprecv(3c)
, tpservice(3c)