Section 3c - C Functions

ATMI C Function Reference

tpconnect(3c)

Name

tpconnect()—Routine for establishing a conversational service connection.

Synopsis

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

Description

tpconnect() allows a program to set up a half-duplex connection to a conversational service, svc. 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 listening program. If the caller chooses to pass data, then 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, (for example, an FML fielded buffer), then len is ignored (and may be 0). Also, data can be NULL in which case len is ignored (no application data is passed to the conversational service). The type and subtype of data must match one of the types and subtypes recognized by svc. data and len are passed to the conversational service via the TPSVCINFO structure with which the service is invoked; the service does not have to call tprecv() to get the data.

The following is a list of valid flags:

TPNOTRAN

If the caller is in transaction mode and this flag is set, then when svc is invoked, it is not performed on behalf of the caller's transaction. Note that svc may still be invoked in transaction mode but it will not be the same transaction: a svc may have as a configuration attribute that it is automatically invoked 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 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). Note that this flag applies only to the send portion of tpconnect(); the function may block waiting for an acknowledgement from the server. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a blocking timeout or transaction timeout occurs.

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts will still affect the program.

TPSIGRSTRT

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

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpconnect().

Return Values

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

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

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPEINVAL]

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 flags are otherwise invalid).

[TPEITYPE]

The type and subtype of data is not one of the allowed types and subtypes that svc accepts.

[TPELIMIT]

The caller's request was not sent because the maximum number of outstanding connections has been reached.

[TPENOENT]

Cannot initiate a connection to svc because it does not exist or is not a conversational service.

[TPEOS]

An operating system error has occurred.

[TPEPROTO]

tpconnect() was called improperly.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPETIME]

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 cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)

If a transaction timeout has occurred, then, with one exception, any attempts to start new conversations, 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.

[TPETRAN]

svc belongs to a program that does not support transactions and TPNOTRAN was not set.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.