5
Oracle Application Server Integration Adapter for Tuxedo Features and Restrictions

After the Oracle Application Server Integration Adapter for Tuxedo is installed and the modeling described in Chapter 3, "Modeling Interactions for Oracle Application Server Integration Adapter for Tuxedo" and Chapter 4, "Using Interactions in a Business Process" completed, you can use the Oracle Application Server Integration Adapter for Tuxedo to invoke interactions that access programs under Tuxedo.

This chapter contains the following sections:

• Tuxedo Message Buffer Support

• Sending Inbound Interactions Using a Tuxedo Service

• High Availability with Oracle Connect

• Known Restrictions

Tuxedo Message Buffer Support

Oracle Connect for Tuxedo provides support for all standard types of Tuxedo's message buffers as Input/Output:

STRING - A null terminated character array

CARRAY - An array of un-interpreted arbitrary binary data.

XML - An XML formatted data

VIEW - A "C" structure layout.

VIEW32 - A "C" structure layout where 32-bit FML identifiers are used.

FML - A special Tuxedo system type that provides transparent data portability.

FML32 - An FML type where 32-bit FML identifiers are used.

Note: Synonyms such as X_C_TYPE, X_OCTET are also recognized.

Unstructured message buffers are wrapped within a record as follows:

• A message buffer of type STRING is wrapped within a record containing a single field of type string.

• A message buffer of type CARRAY is wrapped within a record containing a single field of type binary with a fixed size.

• A message buffer of type XML is wrapped within a record containing a single field of type xml.

Sending Inbound Interactions Using a Tuxedo Service

The Oracle Application Server Integration Adapter for Tuxedo includes a set of APIs that enable sending a native event as an inbound interaction from a C program.

To use the APIs, you must include the following in the C program:

• The gap.h header file - This header file includes all the API declarations

• The GAP_LOAD function - This function loads the API functions. The function does not have any parameters

This appendix describes the APIs and functions:

• Connection APIs

• Transaction APIs

• The Execute Function

• The Get Adapter Schema Function

• The Get Event Function

• The Ping Function

• The Get Error Function

Connection APIs

The following functions handle the connection and connection context for an inbound interaction:

• The Connect Function

• The Disconnect Function

• The Reauthenticate Function

• The Clean Connection Function

There are two kinds of connections:

Transient Connection - Transient connections are created for use within a single inbound interaction. A transient connection is disconnected when an inbound interaction ends, or when the connection context changes (that is, with the connect, setConnection or disconnect functions).

Persistent Connection - Persistent connections can persist across multiple inbound interactions or connection context changes. Persistent connections are disconnected upon an explicit disconnect function or when a connection idle timeout expires.

The Connect Function

The Connect function establishes a new connection context. All the interactions defined take place within a connection context.

Upon a successful connect, a connection context is established and an implicit setConnection is performed with the newly created connection ID. A failed connect function leaves the inbound interaction with no connection context (that is, if a connection context was established prior to invoking the connect function, that connection context will no longer be in effect).

The function returns an integer of 1 (TRUE) or 0 (FALSE), to determine the success of the function.

Syntax

ACXAPI_CONNECT(char * ServersUrls, char* Username, char* Password, char* Workspace, char* AdapterName, int Persistent, long IdleTimeout, ACXAPI_CONNECT_MODE ConnectMode, char* DefinitionFileName, char* KeyName, char* KeyValue, void **ConnectHandle)

Table 5-1  ACXAPI_CONNECT Parameters

Parameter	Usage	Description
ServersUrls	Input	The address of the server being connected to in the format: server_name:port. Or: TCP/IP_address:port. A series of servers, separated by commas, can be specified. The connection is made to the first server, in the list, that is up
Username	Input	The username required by the adapter
Password	Input	The user password required by the adapter
Workspace	Input	Optional. The name of the workspace where the adapter associated to the connection runs. The default workspace is Navigator
AdapterName	Input	The name of the adapter to connect to
Persistent	Input	Persistent connection indication. If true, a persistent connection is created. Otherwise a transient connection is created. The default is false.
IdleTimeout	Input	A per-connection client idle timeout setting (in seconds). If the client does not use the connection for the specified amount of time, the connection is disconnected by the server and its associated resources released. This setting is limited by the server side maximum idle connection timeout setting
ConnectMode	Input	The mode of the connection: 0 - Immediate connection 1 - Deferred connection - the connection is made when the execute function is performed
DefinitionFileName	Input	The name and path of the local definition used for the adapter. If omitted, the API queries the underlying adapter for the metadata This parameter should be specified, when the adapter is remote
KeyName	Input	The name of the encryption key
KeyValue	Input	The value associated with the encryption key
ConnectHandle	Output	A pointer to the connection. A pointer is always returned when the connection fails. This enables calling the getError function to determine what caused the error The Disconnect function must always be called to clear the connection handle

The Disconnect Function

The Disconnect function destroys the current connection context. All the resources associated with the current connection (persistent or transient) are released.

Syntax

ACXAPI_DISCONNECT(void* ConnectHandle)

Table 5-2  ACXAPI_DISCONNECT Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection

The Reauthenticate Function

The Reauthenticate function establishes a new client identity for the active connection. Adapters are not required to support reauthentication.

An adapter that does not support reauthentication is required to produce an exception if required to reauthenticate with an identity different from the current one. Failure of reauthentication prevents further activity on the connection (other than retrying authentication). Once the reauthentication succeeds, the connection's client is authorized based upon the authenticated identity established.

The function returns an integer of 1 (TRUE) or 0 (FALSE), to determine the success of the function.

Syntax

ACXAPI_REAUTHENTICATE(void* ConnectHandle, char* Username, char* Password)

Table 5-3  ACXAPI_REAUTHENTICATE Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection.
Username	Input	The username of the new client using the connection
Password	Input	The user password of the new client using the connection

The Clean Connection Function

The Clean Connection function indicates that the client is working with connection pooling and that the connection is being 'soft-closed'. That is, the connection is being placed in a connections pool. The connection is still valid but various resources on it are freed (for example, objects related to local interactions).

The function returns an integer of 1 (TRUE) or 0 (FALSE), to determine the success of the function.

Syntax

ACXAPI_CLEAN_CONNECTION(void* ConnectHandle, int forgetAuthentification)

Table 5-4  ACXAPI_CLEAN_CONNECTION Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection.
forgetAuthentification	Input	Indicates the adapter should forget the authentication information. This behavior is reflected in the adapter metadata

Transaction APIs

Transaction APIs are used in the following scenarios:

Non-transacted operation - The adapter works in auto-commit mode. Work is committed immediately and automatically upon execution. This operation mode is the default operation mode when no transaction APIs are used, or when the setAutoCommit function sets auto-commit to true.

Local transaction operation - When auto-commit is set to false, the first interaction starts a transaction that lasts until an explicit commit (using the transactionCommit function) or an explicit rollback (using the transactionRollback function) occurs. All interactions performed in between are part of that transaction.

Note: 'local' is used here to indicate the scope of the transaction, rather than its location: the local transaction may be running on a remote machine.

The following functions handle transaction operations:

• The Set Autocommit Function

• The Transaction Commit Function

• The Transaction Rollback Function

The Set Autocommit Function

The Set Autocommit function sets the auto-commit mode of the connection.

Syntax

ACXAPI_SET_AUTO_COMMIT(void* ConnectHandle, int AutoCommit)

Table 5-5  ACXAPI_SET_AUTO_COMMIT Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection.
AutoCommit	Input	New auto-commit mode of the connection. If set to true, each interaction immediately commits once executed. The auto-commit mode must be turned off if multiple interactions need to be grouped into a single transaction and committed or rolled back as a unit When auto-commit is reset and no global transaction is in progress, any interaction starts a local transaction. The client is required to use transactionCommit or transactionRollback at the appropriate time to commit or rollback the transaction The auto-commit mode is true by default and is reset if a distributed (global) transaction is started

The Transaction Commit Function

The Transaction Commit function commits the work done under the global or local transaction.

Syntax

ACXAPI_TRANSACTION_COMMIT(void* ConnectHandle, ACX_XID Xid)

Table 5-6  ACXAPI_TRANSACTION_COMMIT Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection.
Xid	Input	For internal use only. Supply an empty value

The Transaction Rollback Function

The Transaction Rollback function rolls back the work done under the (global) transaction.

Syntax

ACXAPI_TRANSACTION_ROLLBACK(void* ConnectHandle, ACX_XID Xid)

Table 5-7  ACXAPI_TRANSACTION_ROLLBACK Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
Xid	Input	For internal use only. Supply an empty value

The Execute Function

The Execute function executes a given interaction against the application. The function supplies the input record that is required by the application.

Syntax

ACXAPI_EXECUTE(void* ConnectHandle, char* InterationName, void* BufferIn, void* BufferOut, long BufferOutLen)

Table 5-8  ACXAPI_EXECUTE Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
InteractionName	Input	Name of interaction to execute
BufferIn	Input	A pointer to the input record
BufferOut	Output	For internal use only. Supply an empty value
BufferOutLen	Output	For internal use only. Supply an empty value

The Get Adapter Schema Function

The Get Adapter Schema function returns the schema of Oracle Connect for Tuxedo's backend adapter.

Syntax

ACXAPI_GET_ADAPTER_SCHEMA(void* ConnectHandle, void** *Definition)

Table 5-9  ACXAPI_GET_ADAPTER_SCHEMA Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
Definition	Output	The listing of the adapter definition

The Get Event Function

The Get Event function determines the event to wait for and how long to wait. When an event is received, the function returns the results of performing the event.

Syntax

ACXAPI_GET_EVENT(void* ConnectHandle, char* EventName, long Wait, int Keep, void* BufferOut, long BufferOutLen)

Table 5-10  ACXAPI_GET_EVENT Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
EventName	Input	Name of event to wait for
Wait	Input	Length of time to wait to receive the event, in seconds
Keep	Input	Whether the event should be stored in the repository or deleted once finished. The default is false (to delete the event)
BufferOut	Output	A pointer to the output record
BufferOutLen	Output	The length of the output record

The Ping Function

The Ping function returns, in a pingResponse response, information about an active adapter.

Syntax

ACXAPI_PING(void* ConnectHandle, void** OutputStruct)

Table 5-11  ACXAPI_PING Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
OutputStruct	Output	The return information describing the structure of the adapter

The Get Error Function

The Get Error function returns error information.

Syntax

ACXAPI_GET_ERROR(void* ConnectHandle, char* *Error, long *Status)

Table 5-12  ACXAPI_GET_ERROR Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection
Error	Output	The error message returned by the function
Status	Output	The status of the returned error

High Availability with Oracle Connect

You can configure a pool of server processes so that a server process is always available for a client request.

See Also: "Configuring the Daemon for High Availability" for details about high availability

Known Restrictions

If you encounter incompatibility problems, please contact Oracle Support Services. The following section describes the known restrictions and includes suggestions for dealing with them when possible:

• Data Handling

• Datatype Handling

• User-Defined Datatypes

  Note: If you have any questions or concerns about the restrictions, contact Oracle Support Services.

Data Handling

Oracle Connect for Tuxedo handles Tuxedo's data at a record level only. Individual fields cannot be addressed independently.

Datatype Handling

Specifying a value greater than 1 in the COUNT field of Tuxedo's field definition within a VIEW file, translates to array='xx' attribute

Specifying a value in the SIZE field of Tuxedo's field definition within a VIEW file, translates to size='yy' attribute

Specifying C in the FLAG field of Tuxedo's field definition within a VIEW file, imposes generation of an extra leading COUNTER field to hold the actual count value.

Specifying L in the FLAG field of Tuxedo's field definition within a VIEW file, imposes generation of an extra leading LENGTH field to hold the actual length value.

Note: The L flag is applicable for STRING and CARRAY datatypes only. In the case where a COUNT value greater than 1 is specified for the field, the extra leading LENGTH field is generated as an ARRAY. The array entries should hold the actual length values of the corresponding field array entries.

Specifying a value in the NULL field of Tuxedo's field definition within a VIEW file is not reflected in Oracle Connect for Tuxedo's backend adapter record.

Tuxedo's restrictions with regard to VIEW fields are preserved.

The following is an example of a VIEW definition:

VIEW emp
#TYPE     CNAME            FBNAME          COUNT   FLAG  SIZE   NULL
long      lSalary          SALARY            1      -      -     0
short     nDeptnum         DEPTNUM           1      -      -     0
short     nEmpnum          EMPLOYEE_NUMBER   1      -      -     0
short     nJobcode         JOBCODE           1      -      -     0
string    szMessageText    MESSAGE_TEXT      1      -     80     ""
string    szFirstName      FIRST_NAME        1      -     16     ""
string    szLastName       LAST_NAME         1      -     21     ""
END

The following is an example of a field table that defines the FML field IDs:

*base 100
# name           number   type    flags comments
MESSAGE_TEXT           1  string   -     -
#
DEPTNUM              100  short    -     -
EMPLOYEE_NUMBER      101  short    -     -
JOBCODE              102  short    -     -
FIRST_NAME           103  string   -     -
LAST_NAME            104  string   -     -
SALARY               105  long     -     -

User-Defined Datatypes

Oracle Connect for Tuxedo does not handle user-defined datatypes.