PURPOSE
TPCONNECT - establish a conversational connection
SYNOPSIS
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCONNECT" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
DESCRIPTION
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 sub-types recognized by SERVICE-NAME.
Because the conversational service receives DATA-REC
and LEN upon successful return from TPSVCSTART(3cbl),
the service does not call TPRECV(3cbl) to get the data sent by TPCONNECT.
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 in transaction
mode. Either TPNOTRAN or TPTRAN
must be set.
- TPSENDONLY
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.
- TPRECVONLY
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.
- TPNOBLOCK
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.
- 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 will still affect the
program. 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 call is re-issued. Either TPNOSIGRSTRT
or TPSIGRSTRT must be set.
- TPNOSIGRSTRT
When TPNOSIGRSTRT is specified and a signal is
received, the call fails and TP-STATUS is set
to TPGOTSIG. Either TPNOSIGRSTRT or
TPSIGRSTRT must be set.
RETURN VALUES
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.
ERRORS
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):
- [TPEINVAL]
- Invalid arguments were given (for example, settings in TPSVCDEF-REC
are invalid).
-
- [TPENOENT]
Can not initiate a connection to SERVICE-NAME
because it does not exist or is not 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 connection was not sent because the maximum number of
outstanding connections has been reached.
- [TPETRAN]
SERVICE-NAME belongs to a program that does
not support transactions and TPNOTRAN was not
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 or receive messages on any
connections or to start a new connection 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 TPSIGRSTRT was not
specified.
- [TPEPROTO]
TPCONNECT 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
TPDISCON(3cbl),
TPRECV(3cbl),
TPSEND(3cbl)