PURPOSE

TPGETRPLY - get reply from asynchronous message

SYNOPSIS

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

DESCRIPTION

TPGETRPLY returns a reply from a previously sent request. TPGETRPLY either returns a reply for a particular request, or it returns any reply that is available. Both options are described below.

DATA-REC specifies where the reply is to be read into and, on input, LEN in TPTYPE-REC indicates the maximum number of bytes that should be moved into DATA-REC. Also, REC-TYPE in TPTYPE-REC must be specified. Upon successful return from TPGETRPLY, LEN contains the actual number of bytes moved into DATA-REC. REC-TYPE and SUB-TYPE, both in TPTYPE-REC, contain the data's type and sub-type, respectively. If the reply 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 TPGETRPLY sets TPTRUNCATE.

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

F:Following is a list of valid settings in TPSVCDEF-REC.

TPGETANY

This setting signifies that TPGETRPLY should ignore the communications handle indicated by COMM-HANDLE in TPSVCDEF-REC, return any reply available, and set COMM-HANDLE to the communications handle for the reply returned. If no replies exist, TPGETRPLY can wait for one to arrive. Either TPGETANY or TPGETHANDLE must be set.

TPGETHANDLE

This setting signifies that TPGETRPLY should use the communications handle identified by COMM-HANDLE and return a reply available for that COMM-HANDLE. If no replies exist, TPGETRPLY can wait for one to arrive. Either TPGETANY or TPGETHANDLE must be set.

TPNOCHANGE

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

TPCHANGE

The type and/or subtype of the reply record differs from REC-TYPE and SUB-TYPE, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE or TPCHANGE must be set.

TPNOBLOCK

TPGETRPLY does not wait for the reply to arrive. If the reply is available, then TPGETRPLY gets the reply and returns. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and no data is available , the caller blocks until the reply arrives or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME

This setting signifies that the caller is willing to block indefinitely for its reply 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 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 any underlying system calls, then the interrupted system 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.

Except as noted below, COMM-HANDLE is no longer valid after its reply is received.

RETURN VALUES

Upon successful completion, TPGETRPLY sets TP-STATUS to [TPOK]. When TP-STATUS is set to TPOK or TPESVCFAIL, APPL-RETURN-CODE in TPSTATUS-REC contains an application-defined value that was sent as part of TPRETURN. If the size of the incoming message was larger than 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, TPGETRPLY fails and sets TP-STATUS as indicated below. Note that if TPGETHANDLE is set, then COMM-HANDLE is invalidated unless otherwise stated. If TPGETANY is set, then COMM-HANDLE identifies the communications handle for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, then COMM-HANDLE is 0. Also, the failure does not affect the caller's transaction, if one exists, unless otherwise stated.

[TPEINVAL]

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

[TPEOTYPE]

Either the type and sub-type of the reply are not known to the caller; or, TPNOCHANGE was set and the REC-TYPE and SUB-TYPE do not match the type and sub-type of the reply sent by the service. Neither DATA-REC nor TPTYPE-REC are changed. If the reply was to be received on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply 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 both TPBLOCK and TPTIME were specified. In either case, neither DATA-REC nor TPTYPE-REC are changed. If TPGETHANDLE was set, COMM-HANDLE remains valid unless the caller is in transaction mode. If a transaction timeout occurred, then any attempts to send new requests or receive outstanding replies will fail with [TPETIME] until the transaction has been aborted.

[TPESVCFAIL]

The service routine sending the caller's reply called TPRETURN(3cbl) with TPFAIL. This is an application-level failure. The contents of the service's reply, if one was sent, is available in DATA-REC. APPL-RETURN-CODE contains an application-defined value that was sent as part of TPRETURN. If the reply was received on behalf of the caller's transaction, then the transaction is marked abort-only. Note that so long as the transaction has not timed out, further communication may be performed before aborting the transaction; any work performed on behalf of the caller's transaction will be aborted upon transaction completion (that is, for subsequent communication to have any lasting effect, it should be done with TPNOTRAN set).

[TPESVCERR]

An error was encountered by a service routine during its completion in TPRETURN(3cbl) or TPFORWAR(3cbl) (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither DATA-REC nor TPTYPE-REC are changed). If the reply was received on behalf of the caller's transaction, then the transaction is marked abort-only. Note that so long as the transaction has not timed out, further communication may be performed before aborting the transaction and that any work performed on behalf of the caller's transaction will be aborted upon transaction completion (that is, for subsequent communication to have any lasting effect, it should be done with TPNOTRAN set).

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified. COMM-HANDLE remains valid.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

TPGETRPLY was called in an improper context.

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

SEE ALSO

TPACALL(3cbl),
TPCANCEL(3cbl),
tperrordetail(3c),
tpstrerrordetail(3c),
TPRETURN(3cbl)