ATMI COBOL Function Reference
TPCALL()
- routine to send a message to a service synchronously
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01ITPTYPE-REC
.
COPY TPTYPE.
01IDATA-REC
.
COPY User data.
01OTPTYPE-REC
.
COPY TPTYPE.
01ODATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPCALL" USINGTPSVCDEF-REC
ITPTYPE-REC
IDATA-REC
OTPTYPE-REC
ODATA-REC
TPSTATUS-REC
.
TPCALL()
sends a request and synchronously awaits its reply. A call to this routine is the same as calling TPACALL()
immediately followed by TPGETRPLY()
. 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()
. 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-TYPE
s and SUB-TYPE
s 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 subtype 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.
The following is a list of valid settings in TPSVCDEF-REC
.
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.
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.
When this setting is used, the type of ODATA-REC
is not allowed to change. That is, the type and subtype 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.
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.
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.
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.
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.
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.
If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
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()
.
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 ODATA-REC
, the remaining data is discarded.
Under the following conditions, TPCALL()
fails and sets TP-STATUS
to (unless otherwise noted, failure does not affect the caller's transaction, if one exists):
Invalid arguments were given (for example, SERVICE-NAME
is SPACES
or settings in TPSVCDEF-REC
are invalid).
Cannot send to SERVICE-NAME
because it does not exist or is not a request/response service (that is, it is a conversational service).
The pair REC-TYPE
and SUB-TYPE
is not one of the allowed types and subtypes that SERVICE-NAME
accepts.
Either the type and subtype 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 subtype of the reply sent by the service. Neither ODATA-REC
nor LEN
in OTPTYPE-REC
are 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.
This error code indicates that either a timeout has occurred or TPCALL()
has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout can occur only if both TPBLOCK
and TPTIME
are specified.) In either case, no changes are made to ODATA-REC
or OTPTYPE-REC
.
If a transaction timeout has 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. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, TPACALL()
with TPNOTRAN
, TPNOBLOCK
, and TPNOREPLY
set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
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, 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 regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to TPACALL()
with TPNOREPLY
, TPNOTRAN
, and TPNOBLOCK
set.
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 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 regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to TPACALL()
with TPNOREPLY
, TPNOTRAN
, and TPNOBLOCK
set.
TPACALL(3cbl)
, TPFORWAR(3cbl)
, TPGPRIO(3cbl)
, TPRETURN(3cbl)
, TPSPRIO(3cbl)