D
COBOL APIs to Applications

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

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

• The ACXAINIT 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 Event Function

• The Ping Function

• The Get Error Function

  See Also: "Sending Inbound Interactions Using an IMS/TM Transaction" for details of how to use a CICS transaction that calls the APIs instead of using the APIs

Connection APIs

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

• The Connect Function

• The Disconnect 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

ACXACNCT using ServersUrls Username Password Workspace AdapterName Persistent IdleTimeout ConnectMode DefinitionFileName KeyName KeyValue ConnectHandle

Table D-1  ACXACNCT 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 To supply the adapter schema as a parameter for the ACXACNCT call, build an ESDS VSAM file, which holds the adapter definition. Insert the schema into this VSAM file You can insert the schema into the VSAM file by creating a table with one column with a datatype of char X and use an INSERT INTO SQL statement to enter the data
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

ACXADSCO using ConnectHandle

Table D-2  ACXADSCO Parameters

Parameter	Usage	Description
ConnectHandle	Input	A pointer to the connection

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

ACXASCMT using ConnectHandle AutoCommit

Table D-3  ACXASCMT 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

ACXACMIT using ConnectHandle Xid

Table D-4  ACXACMIT 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

ACXARBCK using ConnectHandle Xid

Table D-5  ACXARBCK 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

ACXAEXEC using ConnectHandle InterationName BufferIn BufferOut BufferOutLen

Table D-6  ACXAEXEC 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 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

ACXAGTEV using ConnectHandle EventName Wait Keep BufferOut BufferOutLen

Table D-7  ACXAGTEV 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

ACXAPING using ConnectHandle OutputStruct

Table D-8  ACXAPING 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

ACXAGTER using ConnectHandle Error Status

Table D-9  ACXAGTER 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