Developing and Installing Applications That Use the XA Libraries

Threads=true | false

Interfacing XA with Precompilers and OCIs

This section describes how to use the Oracle XA library with precompilers and Oracle Call Interface (OCI).

Using Precompilers with the Oracle XA Library

When used in an Oracle XA application, cursors are valid only for the duration of the transaction. Explicit cursors should be opened after the transaction begins, and closed before the commit or rollback.

There are two options to choose from when interfacing with precompilers:

The following examples use the precompiler Pro*C/C++.

Using Precompilers with the Default Database

To interface to a precompiler with the default database, make certain that the DB=db_name field, used in the open string, is not present. The absence of this field indicates the default connection, and only one default connection is allowed for each process.

The following is an example of an open string identifying a default Pro*C/C++ connection.

ORACLE_XA+SqlNet=host@MAIL+ACC=P/scott/tiger

+SesTM=10+LogDir=/usr/local/logs

Note that the DB=db_name is absent, indicating an empty database ID string.

The syntax of a SQL statement would be:

EXEC SQL UPDATE Emp_tab SET Sal = Sal*1.5;

16-16 Oracle Database Application Developer's Guide - Fundamentals

Developing and Installing Applications That Use the XA Libraries

Using Precompilers with a Named Database

To interface to a precompiler with a named database, include the DB=db_name field in the open string. Any database you refer to must reference the same db_name you specified in the corresponding open string.

An application may include the default database, as well as one or more named databases, as shown in the following examples.

For example, suppose you want to update an employee's salary in one database, his department number (DEPTNO) in another, and his manager in a third database. You would configure the following open strings in the transaction manager:

ORACLE_XA+DB=MANAGERS+SqlNet=hqfin@SID1+ACC=P/scott/tiger

+SesTM=10+LogDir=/usr/local/xalog

ORACLE_XA+DB=PAYROLL+SqlNet=SID2+ACC=P/scott/tiger

+SesTM=10+LogDir=/usr/local/xalog

ORACLE_XA+SqlNet=hqemp@SID3+ACC=P/scott/tiger

+SesTM=10+LogDir=/usr/local/xalog

Note that there is no DB=db_name field in the last open string.

In the application server program, you would enter declarations, such as:

EXEC SQL DECLARE PAYROLL DATABASE;

EXEC SQL DECLARE MANAGERS DATABASE;

Again, the default connection (corresponding to the third open string that does not contain the db_name field) needs no declaration.

When doing the update, you would enter statements similar to the following:

EXEC SQL AT PAYROLL UPDATE Emp_Tab SET Sal=4500 WHERE Empno=7788; EXEC SQL AT MANAGERS UPDATE Emp_Tab SET Mgr=7566 WHERE Empno=7788; EXEC SQL UPDATE Emp_Tab SET Deptno=30 WHERE Empno=7788;

There is no AT clause in the last statement because it is referring to the default database.

In Oracle Database precompilers release 1.5.3 or later, you can use a character host variable in the AT clause, as the following example shows:

EXEC SQL BEGIN DECLARE SECTION; DB_NAME1 CHARACTER(10); DB_NAME2 CHARACTER(10);

EXEC SQL END DECLARE SECTION;

...

SET DB_NAME1 = 'PAYROLL'

Using Oracle XA with Transaction Monitors 16-17

Developing and Installing Applications That Use the XA Libraries

SET DB_NAME2 = 'MANAGERS'

...

EXEC SQL AT :DB_NAME1 UPDATE...

EXEC SQL AT :DB_NAME2 UPDATE...

Caution: Do not use XA applications to create connections. Any work performed would be outside the global transaction and would have to be committed separately.

Using OCI with the Oracle XA Library

Oracle Call Interface applications that use the Oracle XA library should not call OCISessionBegin() (olon() or orlon() in Version 7) to log on to the resource manager. Rather, the logon should be done through the TPM. The applications can execute the function xaoSvcCtx() (sqlld2() in Version 7) to obtain the service context (lda in Version 7) structure they need to access the resource manager.

In applications that need to pass the environment handle to OCI functions, you can also call xaoEnv() to find that handle.

Because an application server can have multiple concurrent open Oracle Database resource managers, it should call the function xaoSvcCtx() with the correct arguments to obtain the correct service context.

Release 7.3

If DB=db_name is not present in the open string, then execute:

sqlld2(lda, NULL, 0);

This obtains the lda for this resource manager.

Alternatively, if DB=db_name is present in the open string, then execute:

sqlld2(lda, db_name, strlen(db_name));

This obtains the lda for this resource manager.

Release 8.0

If DB=db_name is not present in the open string, then execute:

xaoSvcCtx(NULL);

Alternatively, if DB=db_name is present in the open string, then execute:

16-18 Oracle Database Application Developer's Guide - Fundamentals