ANSI C, C++

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

K&R C

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

The function tprecv() is used to receive data sent across an open connection from another program. This function's first argument, cd, specifies on which open connection to receive data. cd is a descriptor returned from either tpconnect() or the TPSVCINFO parameter to the service. The second argument, data, is the address of a pointer to a buffer previously allocated by tpalloc().

Upon successful return, and for several event types, *data points to the data received and *len contains the size of the buffer. Note that if *len is greater than the total size of the buffer before the call, then the buffer's new size is *len. If *len is 0, no data was received and neither *data nor the buffer it points to were modified. It is an error for data, *data or len to be NULL.

tprecv() can be issued only by the program that does not have control of the connection.

<<cd

Specify a descriptor.>>

<<data

Specify the address of the pointer to the buffer which will contain received data.>>

<<len

Specify the address of the area which will contain the length of received data.>>

<<flags

Indicates flags.>>

<<revent

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

The valid flags are as follows:

TPNOCHANGE

By default, if a buffer is received that differs in type from the buffer pointed to by *data, then *data's buffer type changes to the received buffer's type so long as the receiver recognizes the incoming buffer type. When this flag is set, the type of the buffer pointed to by *data is not allowed to change. That is, the type and sub-type of the received buffer must match the type and sub-type of the buffer pointed to by *data.

TPNOBLOCK

The function tprecv() does not wait for data to arrive. If data is already available to receive, tprecv() gets the data and returns. When this flag is not specified and data is not available to receive, the caller blocks until data arrives.

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

If an event exists for the descriptor, cd, and tprecv() encounters no errors, the event type is returned in revent. data can be received along with the TPEV_SVCSUCC, TPEV_SVCFAIL, and TPEV_SENDONLY events. Valid events for tprecv() 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 by means of 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). Because this is an immediate disconnection notification (that is, abortive rather than orderly), data in transit may be lost. If the two programs were participating in the same transaction, the transaction is marked rollback_only. The descriptor used for the connection is no longer valid.

TPEV_SENDONLY

The program at the other end of the connection has relinquished control of the connection. The recipient of this event is allowed to send data but cannot receive any data until it relinquishes control.

TPEV_SVCERR

Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued tpreturn(). tpreturn() encountered an error that precluded the service from returning successfully. For example, bad arguments may have been passed to tpreturn() or it may have been called while the service had open connections to other subordinates. Due to the nature of this event, any application-defined data or return code are not available. The connection has been terminated and cd is no longer a valid descriptor. If this event occurred as part of the recipient's transaction, the transaction is marked rollback-only.

TPEV_SVCFAIL

Received by the originator of a conversation, this event indicates that the subordinate service on the other end of the conversation has finished unsuccessfully as defined by the application (that is, it called tpreturn() with TPFAIL). If the subordinate service was in control of this connection when tpreturn() was called, it can pass a typed buffer back to the originator of the connection. As part of ending the service routine, the server has terminated the connection. Thus, cd is no longer a valid descriptor. If this event occurred as part of the recipient's transaction, the transaction is marked rollback-only.

TPEV_SVCSUCC

Received by the originator of a conversation, this event indicates that the subordinate service on the other end of the conversation has finished successfully as defined by the application (that is, it called tpreturn() with TPSUCCESS). As part of ending the service routine, the server has terminated the connection. Thus, cd is no longer a valid descriptor. If the recipient is in transaction mode, it can either commit (if it is also the initiator) or roll back the transaction causing the work done by the server (if also in transaction mode) to either commit or roll back.

Upon return from tprecv() 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 tprecv() returns -1 on error and sets tperrno to indicate the error condition. Also, if an event exists and no errors were encountered, tprecv() returns -1 and tperrno is set to TPEEVENT.

Errors

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

tpalloc(), tpconnect(), tpdiscon(), tpsend().

1. <<The TPSIGRSTRT flag is invalid. Regardless of this flag, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
2. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
3. <<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. >>
4. <<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.>>