ATMI COBOL Function Reference
TPCONNECT()
- establish a conversational connection
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPCONNECT" USINGTPSVCDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPCONNECT()
allows a program to set up a half-duplex connection to a conversational service, SERVICE-NAME
in TPSVCDEF-REC
. The name must be one of the conversational service names posted by a conversational server.
As part of setting up a connection, the caller can pass application-defined data to the receiving service routine. If the caller chooses to pass data, then DATA-REC
contains the data and LEN
in TPTYPE-REC
specifies how much of the record to send. 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 (no application data is passed to the conversational service). REC-TYPE
and SUB-TYPE
in TPTYPE-REC
must match one of the types and subtypes recognized by SERVICE-NAME
.
Because the conversational service receives DATA-REC
and LEN
upon successful return from TPSVCSTART()
, the service does not call TPRECV()
to get the data sent by TPCONNECT()
.
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 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.
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.
The caller wants the connection to be set up initially such that it can only send data and the called service can only receive data (that is, the caller initially has control of the connection). Either TPSENDONLY
or TPRECVONLY
must be specified.
The caller wants the connection to be set up initially such that it can only receive data and the called service can only send data (that is, the service being called initially has control of the connection). Either TPSENDONLY
or TPRECVONLY
must be specified.
The connection is not established and the data is not sent if a blocking condition exists (for example, the data buffers through which the message is sent are full). 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 will still affect the program. 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, the interrupted call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
Upon successful completion, TPCONNECT()
sets TP-STATUS
to [TPOK
] and returns a communications handle in COMM-HANDLE
in TPSVCDEF-REC
that is used to refer to the connection in subsequent calls.
Under the following conditions, TPCONNECT()
fails and sets TP-STATUS
to (unless otherwise noted, failure does not affect the caller's transaction, if one exists).
Can not initiate a connection to SERVICE-NAME
because it does not exist or is not a conversational service.
The pair REC-TYPE
and SUB-TYPE
is not one of the allowed types and subtypes that SERVICE-NAME
accepts.
This error code indicates that either a timeout has occurred or TPCONNECT()
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.)
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
.