PURPOSE

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(3cbl) or TPSVCSTART(3cbl). 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 sub-type, 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.

F: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 sub-type of the message received must match REC-TYPE and SUB-TYPE, respectively. Either TPNOCHANGE or TPCHANGE must be set.
TPCHANGE: The type and/or sub-type 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 re-issued. 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(3cbl), or an error occurred when the originator issued TPRETURN(3cbl) or TPCOMMIT(3cbl) 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 can not 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(3cbl). TPRETURN(3cbl) encountered an errors that precluded the service from returning successfully. For example, bad arguments may have been passed to TPRETURN(3cbl) or TPRETURN(3cbl) 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(3cbl) with TPFAIL or TPEXIT). If the subordinate service was in control of this connection when TPRETURN(3cbl) 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(3cbl) 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(3cbl). 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 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 transaction, then the transaction is marked abort-only since the incoming message is discarded.
[TPEBADDESC]: COMM-HANDLE contains an invalid communications handle.
[TPETIME]: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. In either case, DATA-REC was not changed. If a transaction timeout occurred, then any attempts to send or receive messages on any connections or to start a new connection will fail with TPETIME until the transaction has been aborted.
[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 System/T error has occurred. The exact nature of the error is written to a log file.
[TPEOS]: An operating system error has occurred.

USAGE