OpenTP1 Version 7 Programming Reference C Language

[Contents][Index][Back][Next]

tpconnect - Establish a conversational service connection

Format

ANSI C, C++

#include <xatmi.h>
int tpconnect (char *svc, char *data, long len,
               long flags)

K&R C

#include <xatmi.h>
int tpconnect (svc, data, len, flags)
char      *svc;
char      *data;
long      len;
long      flags;

Description

The function tpconnect() allows a program to set up a half-duplex connection to a conversational service, svc.

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 must point to a buffer previously allocated by tpalloc(). len specifies how much of the buffer to send. Note that if data points to a buffer of a type that does not require a length to be specified, len is ignored (and may be 0). If data points to a buffer that does require a length, len must not be zero. Also, data can be NULL in which case len is ignored (no application data is passed to the conversational service). The type and sub-type of data must match one of the types and sub-types recognized by svc. Because the conversational service receives data and len via the TPSVCINFO structure upon invocation, the service does not call tprecv() to get the data sent by tpconnect().

<<Arguments>>

<<svc

Specify the name of the service to be requested.>>

<<data

Specify the pointer to the send data storage area.>>

<<len

Specify the length of the send data.>>

<<flags>>

The valid flags are as follows:

TPNOTRAN
If the caller is in transaction mode and this flag is set, when svc is invoked, it is not performed on behalf of the caller's transaction. If svc does not support transactions, this flag must be set when the caller is in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.

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). When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

TPSIGRSTRT
If a signal interrupts any underlying system calls, the interrupted system call is reissued.

Return value

Upon successful completion, tpconnect() returns a descriptor that is used to refer to the connection in subsequent calls. Otherwise it returns -1 and sets tperrno to indicate the error condition.

Errors

Under the following conditions, tpconnect() fails and sets tperrno to one of the values below. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.

Return value Return value (numeric) Explanation
TPEINVAL 4 Invalid arguments were given (for example, svc is NULL, data is non-NULL and does not point to a buffer allocated by tpalloc(), TPSENDONLY or TPRECVONLY was not specified in flags, or the value of flags is invalid).
TPENOENT 6 Cannot establish a connection because the service specified in svc does not exist.
TPEITYPE 17 The type and subtype for data are not in a format that can be used for svc.
TPELIMIT 5 The caller's request was not sent because the maximum number of outstanding connections has been reached.
TPETRAN 14 TPNOTRAN was not set, even though transaction processing could not be performed for svc.
TPETIME 13 A timeout occurred. If the caller is in transaction mode, a transaction time-out occurred and the transaction is marked rollback_only; otherwise, a blocking time-out occurred and neither TPNOBLOCK nor TPNOTIME were specified. If a transaction time-out 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 3 When tpconnect() for which TPNOBLOCK was specified was called, the blocking status existed.
TPEGOTSIG 15 A signal was received, but TPSIGRSTRT was not set.
TPEPROTO 9 tpconnect() was called in an improper context.
TPESYSTEM 12 A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner.
TPEOS 7 An operating system error has occurred. The exact nature of the error is determined in a product-specific manner.

See also

tpalloc(), tpdiscon(), tprecv(), tpsend(), tpservice().

<<Notes on use with OpenTP1>>

  1. <<The TPNOBLOCK flag is invalid under the relevant version of the OpenTP1. Therefore, the error code TPEBLOCK will not be returned to tperrno. 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 TPNOTIME flag is invalid under the relevant version of the OpenTP1.>>
  3. <<The TPSIGRSTRT flag is invalid. Regardless of this flag, 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 data of a type unavailable with svc is passed, TPESYSTEM 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, data which requires 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. <<The function returns with a TPEPROTO error if the OpenTP1 security facility is used but the service request is not authenticated. Whether the cause of the error return is because the service request is not authenticated can be checked with the UAP trace detail error code.>>
  8. <<For OSI TP communication using TP1/NET/OSI-TP-Extended, conversational service communication cannot be held. If this is done, the system operation is undefined.>>
  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.>>