01 TPSVCDEF-REC. COPY TPSVCDEF. 01 TPTYPE-REC. COPY TPTYPE. 01 DATA-REC. COPY Data record definition. 01 TPSTATUS-REC. COPY TPSTATUS. CALL "TPCONNECT" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

TPCONNECT allows a program to set up a half-duplex connection to a conversational service, SERVICE-NAME.

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, DATA-REC contains the data and LEN 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, LEN is ignored (and may be 0). If DATA-REC is a record of a type that does require a length, LEN must not be zero. If REC-TYPE does not have a subtype, SUB-TYPE is ignored (and may be SPACES). If REC-TYPE is SPACES, DATA-REC and LEN are ignored (no application data is passed to the conversational service). REC-TYPE and SUB-TYPE 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.

<<TPSVCDEF-REC

Specify a value indicating the TPCONNECT operation. The value specified here determines the return value. The specifiable values and their meanings will be explained later.>>

<<TPTYPE-REC

Indicates the data type and subtype record name of the send data.>>

<<DATA-REC

Points to the send data.>>

<<TPSTATUS-REC

Will be assigned the return value indicating the result of TPCONNECT execution.>>

The valid settings of TPSVCDEF-REC are as follows:

TPNOTRAN

If the caller is in transaction mode and this setting is used, when SERVICE-NAME is invoked, it is not performed on behalf of the caller's transaction. If SERVICE-NAME does not support transactions, 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, 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 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 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 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 receives 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, the interrupted system call is re-issued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, the interrupted system call is not restarted and the routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

Upon successful completion, TPCONNECT sets TP-STATUS to TPOK and returns a valid communication handle in COMM-HANDLE that is used to refer to the connection in subsequent calls.

Errors

Under the following conditions, TPCONNECT fails and sets TP-STATUS to one of the values below. 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

Cannot initiate a connection to SERVICE-NAME because it does not exist.

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 established because the maximum number of outstanding connections has been reached.

TPETRAN

SERVICE-NAME does not support transactions and TPTRAN was set.

TPETIME

A timeout occurred. If the caller is in transaction mode, a transaction timeout occurred and the transaction is marked rollback-only; otherwise, a blocking timeout occurred and both TPBLOCK and TPTIME were specified. If a transaction timeout occurred, any attempts to send or receive messages on any connections or to start a new connection fail with TPETIME until the transaction has been rolled back.

TPEBLOCK

A blocking condition exists and TPNOBLOCK was specified.

TPEGOTSIG

A signal was received and TPNOSIGRSTRT was specified.

TPEPROTO

TPCONNECT was called in an improper context.

TPESYSTEM

A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPEOS

An operating system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPDISCON, TPRECV, TPSEND, TPSVCSTART.

1. <<The value TPNOBLOCK is invalid under the relevant version of the OpenTP1. Therefore, the error code TPEBLOCK will not be returned to TP-STATUS. The OpenTP1 is designed so that if communication is impossible because of blocking, TPESYSTEM is returned as when communication is impossible because of network failure.>>
2. <<The value TPNOTIME is invalid under the relevant version of the OpenTP1.>>
3. <<The value TPSIGRSTRT is invalid. Regardless of whether this value is set, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
4. <<Under the relevant version of the OpenTP1, TPEITYPE will not return. If a record of a type unavailable with SERVICE-NAME is passed, TPESYSTEM or TPESVCERR will return. If the calling program is in transaction mode, the rollback_only state comes into effect.>>
5. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
6. <<Under the relevant version of the OpenTP1, an error which raises need for rollback causes the return of TPESYSTEM unless otherwise specified by the X/Open. However, the rollback_only state may not come into effect even when TPESYSTEM returns.>>
7. <<If the function returns with a TPEPROTO error. To determine whether the error return was caused by an invalidated service request, refer to the detailed information in the UAP trace.>>
8. <<When OSI TP communication using the TP1/NET/OSI-TP-Extended is in progress, it cannot be used for conversational services. If an attempt is made to do so, the system operation is unpredictable.>>
9. <<If the server AP is in shutdown status, the system operates as follows depending on whether the request destination SPP that is shutdown is on a local node or on a remote node:
   

   When the request destination SPP on a local node is shutdown:

   tpconnect() returns -1 and sets the value TPEPROTO in tperrno.

   When the request destination SPP on a remote node is shutdown:

   In the transaction mode, the server AP terminates abnormally due to transaction time-out.

   In the non-transaction mode, tpconnect() returns -1 and sets the value TPETIME in tperrno.>>