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

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 read into, and, on input, LEN indicates the maximum number of bytes that should be moved into DATA-REC. Upon successful return from TPGETRPLY, 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 reply is larger than DATA-REC, DATA-REC contain only as many bytes as fit in the record. The remainder of the reply is discarded and TPGETRPLY sets TPTRUNCATE.

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

<<TPSVCDEF-REC

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

<<TPTYPE-REC

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

<<DATA-REC

Points to the data to be received.>>

<<TPSTATUS-REC

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

The valid settings of TPSVCDEF-REC are as follows:

TPGETANY

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

TPGETHANDLE

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

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 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 are 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

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

TPBLOCK

When TPBLOCK is specified and no reply 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 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.

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

Upon successful completion, TPGETRPLY sets TP-STATUS to TPOK. When TP-STATUS is set to either TPOK or TPESVCFAIL, 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, TPGETRPLY fails and sets TP-STATUS as indicated below. Note that if TPGETHANDLE is set, COMM-HANDLE is invalidated unless otherwise stated. If TPGETANY is set, COMM-HANDLE identifies the descriptor for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, COMM-HANDLE is set to 0, unless otherwise stated. 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).

TPEBADDESC

COMM-HANDLE contains an invalid communication handle.

TPEOTYPE

Either the type and sub-type of the reply 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 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, the transaction is marked rollback-only since the reply is discarded.

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 TPGETHANDLE was set, COMM-HANDLE remains valid unless the caller is in transaction mode. If a transaction timeout occurred, any attempts to send new requests or receive outstanding replies fail with TPETIME until the transaction has been rolled back.

TPESVCFAIL

The service routine sending the caller's reply called TPRETURN with TPFAIL. This is an application-level failure. The contents of the service's reply, if one was sent, are available in DATA-REC. If the reply was received on behalf of the caller's transaction, the transaction is marked rollback-only. Note that so long as the transaction has not timed out, further communication may be attempted before rolling back the transaction. Such attempts may be processed normally or may fail (producing an error return or event). Such attempts should be made with TPNOTRAN set if they are to have any lasting effect. Any work performed on behalf of the caller's transaction is rolled back upon transaction completion.

TPESVCERR

An error was encountered either in invoking a service routine or during its completion in TPRETURN (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, the transaction is marked rollback-only. Note that so long as the transaction has not timed out, further communication may be attempted before rolling back the transaction. Such attempts may be processed normally or may fail (producing an error return or event). Such attempts should be made with TPNOTRAN set if they are to have any lasting effect. Any work performed on behalf of the caller's transaction is rolled back upon transaction completion.

TPEBLOCK

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

TPEGOTSIG

A signal was received and TPNOSIGRSTRT was specified.

TPEPROTO

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

TPACALL, TPCANCEL, TPRETURN.

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, 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. <<If the function TPACALL passes a record of a type that cannot be used by the called service, it returns normally, but the function TPGETRPLY will encounter an error. If the function TPGETRPLY encounters a TPESYSTEM or TPESVCERR error, check the results of the function TPACALL as well.>>
5. <<If the SPP that was asked to offer its service abnormally terminates, the function could return with a TPETIME error before the time assigned to watch_time in the definition elapses. If watch_time is assigned 0 (infinitely wait for a response), the function could return with a TPEPROTO error.>>
6. <<If the service request is not validated when OpenTP1 security is in use, the function returns with a TPEPROTO error. To determine whether the error return was caused by an invalidated service request, refer to the detailed information in the UAP trace.>>
7. <<For OSI TP communication using the TP1/NET/OSI-TP-Extended, the length of the receive data must not exceed the value assigned to the length operand of the NET buffer group definition (nettbuf) contained in the NET/Library common definition.>>