01 TPSVCDEF-REC. COPY TPSVCDEF. 01 TPTYPE-REC. COPY TPTYPE. 01 DATA-REC. COPY Data record definition. 01 TPSTATUS-REC. COPY TPSTATUS. CALL "TPRECV" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

TPRECV is used to receive data sent across an open connection from another program. COMM-HANDLE specifies on which open connection to receive data. COMM-HANDLE is a communication handle returned from either TPCONNECT or TPSVCSTART. DATA-REC specifies where the message is read into, and, on input, LEN indicates the maximum number of bytes that should be moved into DATA-REC.

Upon successful return, and for several event types, LEN contains the actual number of bytes moved into DATA-REC. REC-TYPE and SUB-TYPE contain the data's type and sub-type, respectively. If the message is larger than DATA-REC, DATA-REC contains only as many bytes as fit in the record. The remainder of the message is discarded and TPRECV sets TPTRUNCATE.

If LEN is 0 upon successful return, the message has no data portion and DATA-REC was not modified. It is an error for LEN to be 0 on input.

TPRECV can be issued only by the program that does not have control of the connection.

<<TPSVCDEF-REC

Specify a value indicating the TPRECV operation and a communication handle. The specifiable values and their meanings will be explained later.>>

<<TPTYPE-REC

Indicates the record type and subtype record name of the data to be received.>>

<<DATA-REC

Points to the record to be received.>>

<<TPSTATUS-REC

Will be assigned the return value indicating the result of TPRECV execution.>>

The valid settings of TPSVCDEF-REC are as follows:

TPNOCHANGE

When this setting is used, the type of DATA-REC is not allowed to change. That is, the type and sub-type of the message received must match REC-TYPE and SUB-TYPE, respectively. Either TPNOCHANGE or TPCHANGE must be set.

TPCHANGE

The type or subtype of the message received is allowed to differ from those specified in REC-TYPE and SUB-TYPE, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE or TPCHANGE must be set.

TPNOBLOCK

TPRECV does not wait for data to arrive. If data is already available to receive, TPRECV gets the data and returns. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and no data is available to receive, the caller blocks until data arrives. Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME

This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller receives blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.

TPSIGRSTRT

If a signal interrupts any underlying system calls, the interrupted system call is re-issued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, the interrupted system call is not restarted and the routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

If an event exists for COMM-HANDLE, and TPRECV encounters no errors, TPRECV returns setting TP-STATUS to TPEEVENT. The event type is returned in TP-EVENT. 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 via TPDISCON, or it issued TPRETURN, TXCOMMIT or TXROLLBACK 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). 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. COMM-HANDLE is no longer valid.

TPEV-SENDONLY

The program on 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 is not available. The connection has been terminated and COMM-HANDLE is no longer valid. 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 record back to the originator of the connection. As part of ending the service routine, the server has terminated the connection. Thus, COMM-HANDLE is no longer valid. 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, COMM-HANDLE is no longer valid. 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 successful completion, TPRECV sets TP-STATUS to TPOK. If an event exists and no errors were encountered, TPRECV sets TP-STATUS to TPEEVENT. When TP-STATUS is set to TPEEVENT and TP-EVENT is either TPEV-SVCSUCC or TPEV-SVCFAIL, APPL-RETURN-CODE contains an application-defined value that was sent as part of TPRETURN. If the size of the incoming message is larger than the size specified in LEN on input, TPTRUNCATE is set and only LEN bytes are moved into DATA-REC. The remaining bytes are discarded.

Errors

Under the following conditions, TPRECV fails and sets TP-STATUS to one of the values below. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.

TPEINVAL

Invalid arguments were given (for example, settings in TPSVCDEF-REC are invalid).

TPEBADDESC

COMM-HANDLE contains an invalid communication handle.

TPEOTYPE

Either the type and sub-type of the incoming message are not known to the caller, or TPNOCHANGE was set and REC-TYPE and SUB-TYPE do not match the type and sub-type of the incoming message. If the conversation is part of the caller's current transaction, the transaction is marked rollback-only since the incoming message is discarded. When this error occurs, any event for COMM-HANDLE is dropped and the conversation may now be in an indeterminate state. The caller should terminate the conversation.

TPETIME

A timeout occurred. If the caller is in transaction mode, a transaction timeout occurred and the transaction is marked rollback-only; otherwise, a blocking timeout occurred and both TPBLOCK and TPTIME were specified. In either case, neither DATA-REC nor TPTYPE-REC are changed. If a transaction timeout 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

An event occurred and its type is available in TP-EVENT.

TPEBLOCK

A blocking condition exists and TPNOBLOCK was specified.

TPEGOTSIG

A signal was received and TPNOSIGRSTRT was specified.

TPEPROTO

TPRECV was called in an improper context.

TPESYSTEM

A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPEOS

An operating system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPCONNECT, TPDISCON, TPSEND.

1. <<The value TPSIGRSTRT is invalid. Regardless of whether this value is set, 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, an error which raises need for 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. <<When OSI TP communication using the TP1/NET/OSI-TP-Extended is in progress, it cannot be used for conversational services. If an attempt is made to do so, the system operation is unpredictable.>>