[Top] [Prev] [Next] [Bottom]

TPCONNECT(3CBL)

TPCONNECT(3CBL)

Name

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(), the service does not call TPRECV() to get the data sent by TPCONNECT.

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.
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 BEA TUXEDO system 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(), TPRECV(), TPSEND()

[Top] [Prev] [Next] [Bottom]