PURPOSE

TPACALL - routine to send a message to a service asynchronously

SYNOPSIS

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

DESCRIPTION

TPACALL sends a request message to the 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). DATA-REC is a message to be sent and LEN IN TPTYPE-REC specifies the amount of data in DATA-REC that should be sent. Note that if DATA-REC is a record of a type that does not require a length to be specified, then LEN is ignored (and may be 0). If REC-TYPE IN TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and a request is sent with no data portion. If REC-TYPE is STRING and LEN is 0, then the request is sent with no data portion. The REC-TYPE and SUB-TYPE of DATA-REC must match one of the REC-TYPE and SUB-TYPEs recognized by SERVICE-NAME. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.

F: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 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 uses this setting 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. This setting is ignored if the caller is not in transaction mode. Either TPNOTRAN or TPTRAN must be set.

TPNOREPLY

Informs TPACALL that a reply is not expected. When TPNOREPLY is set, the routine returns [TPOK] on success and sets COMM-HANDLE IN TPSVCDEF-REC to 0, an invalid communications handle. When the caller is in transaction mode, this setting cannot be used when TPTRAN is also set. Either TPNOREPLY or TPREPLY must be set.

TPREPLY

Informs TPACALL that a reply is expected. When TPREPLY is set, the routine returns [TPOK] on success and sets COMM-HANDLE to a valid communications handle. When the caller is in transaction mode, this setting must be used when TPTRAN is also set. Either TPNOREPLY or TPREPLY 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). 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 call fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

RETURN VALUES

Upon successful completion, TPACALL sets TP-STATUS to [TPOK]. In addition, if TPREPLY was set in TPSVCDEF-REC, then TPCALL(3cbl) returns a valid communications handle in COMM-HANDLE that can be used to receive the reply of the request sent.

ERRORS

Under the following conditions, TPACALL 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).

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

[TPELIMIT]

The caller's request was not sent because the maximum number of outstanding asynchronous requests has been reached.

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

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO]

TPACALL 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

TPCANCEL(3cbl),
TPCALL(3cbl),
TPGETRPLY(3cbl),
TPSPRIO(3cbl),
TPGPRIO(3cbl),