Oracle7 Server Distributed Systems Volume I: Distributed Data

Interfacing to Precompilers and OCIs

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

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. Also, you must use the release_cursor=yes option when compiling your precompiler application.

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

using precompilers with the default database

using precompilers with a named database

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 as defined by sqllib, and only one default connection is allowed per 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+GPwD=P/mailgrp
	+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 SET SAL = sal*1.5;

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, her department number (DEPTNO) in another, and her 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
	+GPwd+P/pay+SesTM=10+LogDir=/usr/local/xalog

ORACLE_XA+DB=PAYROLL+SqlNet=SID2+ACC=P/scott/tiger
	+GPwd=P/mgr+SesTM=10+LogDir=/usr/local/xalog

ORACLE_XA+SqlNet=hqemp@SID3+ACC=P/scott/tiger+GPwd=P/mgr
	+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 SET SAL=4500 WHERE EMPNO=7788;

EXEC SQL AT MANAGERS UPDATE EMP SET MGR=7566 WHERE EMPNO=7788;

EXEC SQL UPDATE EMP 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 precompilers version 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'

SET DB_NAME2 = 'MANAGERS'

EXEC SQL AT :DB_NAME1 UPDATE...

EXEC SQL AT :DB_NAME2 UPDATE...

Additional Information: For more information on concurrent logons, see the Programmer's Guide to the Oracle Precompilers.

Note: Applications using XA should not create Oracle Server database connections of their own. Any work performed by them would be outside the global transaction, and may confuse the connection information used by the Oracle XA library.

Using OCI with the Oracle XA Library

OCI applications that use the Oracle XA library should not call olon() or orlon() to log on to the resource manager. Rather, the logon should be done through the TPM. The applications can execute the function sqlld2() to obtain the lda structure they need to access the resource manager.

Because an application server can have multiple concurrent open Oracle Server resource managers, it should call the function sqlld2() with the correct arguments to obtain the correct lda structure.

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

sqlld2(lda, NULL, 0);

to obtain 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));

to obtain the lda for this resource manager.

Additional Information: For more information about using the sqlld2() function, see the Programmer's Guide to the Oracle Call Interface.