PURPOSE

TPCALL - routine to send a message to a service synchronously

SYNOPSIS

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 ITPTYPE-REC.
   COPY TPTYPE.
01 IDATA-REC.
   COPY User data.
01 OTPTYPE-REC.
   COPY TPTYPE.
01 ODATA-REC.
   COPY User data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPCALL" USING TPSVCDEF-REC ITPTYPE-REC IDATA-REC
  OTPTYPE-REC ODATA-REC TPSTATUS-REC.

DESCRIPTION

TPCALL sends a request and synchronously awaits its reply. A call to this routine is the same as calling TPACALL(3cbl) immediately followed by TPGETRPLY(3cbl). TPCALL sends a request to the request/response service named by SERVICE-NAME in TPSVCDEF-REC. The request is sent out at the priority defined for SERVICE-NAME unless overridden by a previous call to TPSPRIO(3cbl). The data portion of a request is specified by IDATA-REC and LEN in ITPTYPE-REC specifies how much of IDATA-REC to send. Note that if IDATA-REC is a record of a type that does not require a length to be specified, then LEN in ITPTYPE-REC is ignored (and may be 0). If REC-TYPE in ITPTYPE-REC is SPACES, IDATA-REC and LEN in ITPTYPE-REC are ignored and a request is sent with no data portion. If REC-TYPE in ITPTYPE-REC is STRING and LEN in ITPTYPE-REC is 0, then the request is sent with no data portion. The REC-TYPE in ITPTYPE-REC and SUB-TYPE in ITPTYPE-REC must match one of the REC-TYPEs and SUB-TYPEs recognized by SERVICE-NAME.

ODATA-REC specifies where a reply is read into, and, on input LEN in OTPTYPE-REC indicates the maximum number of bytes that should be moved into ODATA-REC. If the same record is to be used for both sending and receiving, ODATA-REC should be REDEFINED to IDATA-REC. Upon successful return from TPCALL, LEN in OTPTYPE-REC contains the actual number of bytes moved into ODATA-REC. REC-TYPE and SUB-TYPE in OTPTYPE-REC contain the replies type and sub-type respectively. If the reply is larger than ODATA-REC, then ODATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and TPCALL sets TPTRUNCATE.

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

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

TPNOTRAN

If the caller is in transaction mode and this setting is used , then when SERVICE-NAME is invoked, it is not performed on behalf of the caller's transaction. If the SERVICE-NAME belongs to a server that does not support transactions then this setting must be used when the caller is in transaction mode. A caller in transaction mode that sets this to true is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller's transaction is not affected. Either TPNOTRAN or TPTRAN must be set.

TPTRAN

If the caller is in transaction mode and this setting is used, then when SERVICE-NAME is invoked, it is performed on behalf of the caller's transaction. The setting is ignored if the caller is not in transaction mode. Either TPNOTRAN or TPTRAN must be set.

TPNOCHANGE

When this setting is used, the type of ODATA-REC is not allowed to change. That is, the type and sub-type of the replied record must match REC-TYPE in OTPTYPE-REC and SUB-TYPE in OTPTYPE-REC, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE or TPCHANGE must be set.

TPCHANGE

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

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Note that this setting applies only to the send portion of TPCALL: the routine may block waiting for the reply. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides 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 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 routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

RETURN VALUES

Upon successful completion, TPCALL 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(3cbl).

If the size of the incoming message is larger then the size specified in LEN on input, TPTRUNCATE is set and only LEN amount of data was moved to ODATA-REC, the remaining data is discarded.

ERRORS

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

[TPEINVAL]

Invalid arguments were given (for example, SERVICE-NAME is SPACES or settings in TPSVCDEF-REC are invalid).

[TPENOENT]

Can not send to SERVICE-NAME because it does not exist or is not a request/response service (that is, it is a conversational service).

[TPEITYPE]

The pair REC-TYPE and SUB-TYPE is not one of the allowed types and sub-types that SERVICE-NAME accepts.

[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 in ODATA-REC do not match the type and sub-type of the reply sent by the service. Neither ODATA-REC nor LEN in OTPTYPE-REC is changed. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.

[TPETRAN]

SERVICE-NAME belongs to a server that does not support transactions and TPTRAN was set.

[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 ODATA-REC nor OTPTYPE-REC are changed. If a transaction timeout 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.

[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 ODATA-REC. If the service request was made on behalf of the caller's current 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).

[TPESVCERR]

An error was encountered either in invoking a service routine or during its completion in TPRETURN(3cbl) (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither ODATA-REC nor OTPTYPE-REC are changed). If the service request was made on behalf of the caller's transaction (that is, TPNOTRAN was not set), 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 was found on the send portion of TPCALL and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

TPCALL 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),
TPFORWARD(3cbl),
TPGPRIO(3cbl),
tperrordetail(3c),
tpstrerrordetail(3c),
TPSPRIO(3cbl),
TPRETURN(3cbl),