Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPRECV(3cbl)

Name

TPRECV() - receive a message in a conversational connection

Synopsis

01 TPSVCDEF-REC.
 COPY TPSVCDEF. 
 
01 TPTYPE-REC.
 COPY TPTYPE. 
 
01 DATA-REC.
 COPY User data. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS. 
 
CALL "TPRECV" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Description

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 communications 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 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 subtype, respectively. If the message is larger than DATA-REC, then DATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and TPRECV() sets TPTRUNCATE.

If LEN is 0 upon successful return, then the reply 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.

The following is a list of valid settings in TPSVCDEF-REC.

TPNOCHANGE

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

TPCHANGE

The type and/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 wait for data to arrive. If data is already available to receive, then 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 will still affect the program. Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller will receive 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 the underlying receive system call, then the call is reissued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

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

If an event exists for the communications handle, COMM-HANDLE, then TPRECV() will return setting TP-STATUS to TPEEVENT(). The event type is returned in TPEVENT(). 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 issued an immediate disconnect on the connection via TPDISCON(), or an error occurred when the originator issued TPRETURN() or TPCOMMIT() 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, then the transaction is marked abort-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 errors that precluded the service from returning successfully. For example, bad arguments may have been passed to TPRETURN() or TPRETURN() 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 torn down and COMM-HANDLE is no longer valid. If this event occurred as part of the recipient's transaction, then the transaction is marked as abort-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() or TPEXIT()). If the subordinate service was in control of this connection when TPRETURN() was called, then it can pass an application-defined return value and a record back to the originator of the connection. As part of ending the service routine, the server has torn down the connection. Thus, COMM-HANDLE is no longer valid. If this event occurred as part of the recipient's transaction, then the transaction is marked abort-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 torn down the connection. Thus, COMM-HANDLE is no longer valid. If the recipient is in transaction mode, then it can either commit (if it is also the initiator) or abort the transaction causing the work done by the server (if also in transaction mode) to either commit or abort.

Return Values

Upon successful completion, TPRECV() sets TP-STATUS to [TPOK]. When TP-STATUS is set to [TPEEVENT] and TPEVENT() 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 was larger then the size specified in LEN on input, TPTRUNCATE() is set and only LEN amount of data was moved to DATA-REC, the remaining data is discarded.

Errors

Under the following conditions, TPRECV() fails and sets TP-STATUS to (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.

[TPEOTYPE]

Either the type of subtype 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 subtype of the incoming message. If the conversation is part of the caller's transaction, then the transaction is marked abort-only since the incoming message is discarded.

[TPEBADDESC]

COMM-HANDLE contains an invalid communications handle.

[TPETIME]

This error code indicates that either a timeout has occurred or TPRECV() 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 can occur only if both TPBLOCK and TPTIME are specified.) In either case, no changes are made to DATAREC.

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

[TPEEVENT]

An event occurred and its type is available in TPEVENT().

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

TPRECV() was called in an improper context (for example, the connection was established such that the calling program can only send data).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Usage

A server can pass an application-defined return value and typed record when calling TPRETURN(). The return value is available in APPL-RETURN-CODE and the record is available in DATA-REC.