OpenTP1 Version 7 Programming Reference C Language
tpsend - Send a message in a conversational connection
Format
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; |
Description
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.
<<Arguments>>
<<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:
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:
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.
Return value
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:
Return value | Return value (numeric) | Explanation |
---|---|---|
TPEINVAL | 4 | Invalid arguments were given (for example, data is not a pointer to a buffer allocated for tpalloc() or the value of flags is invalid). |
TPEBADDESC | 2 | The argument cd points to an invalid descriptor. |
TPETIME | 13 | A timeout occurred. If the caller is in transaction mode, a transaction time-out occurred and the transaction is marked rollback_only; otherwise, a blocking time-out occurred and neither TPNOBLOCK nor TPNOTIME were specified. In either case, *data and its contents are not changed. If a transaction time-out occurred, any attempts to send or receive messages on any connections or to start a new connection fail with TPETIME until the transaction has been rolled back. |
TPEEVENT | 22 | An event occurred. data is not sent when this error occurs. The event type is returned in revent. |
TPEBLOCK | 3 | When tpsend() for which TPNOBLOCK was specified was called, the blocking status existed. |
TPEGOTSIG | 15 | A signal was received, but TPSIGRSTRT was not set. |
TPEPROTO | 9 | tpsend() was called in an improper context. |
TPESYSTEM | 12 | A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner. |
TPEOS | 7 | An operating system error has occurred. The exact nature of the error is determined in a product-specific manner. |
See also
tpalloc(), tpconnect(), tpdiscon(), tprecv(), tpreturn().
<<Notes on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.