2
Building OCI Applications

This chapter provides an overview of how to build Oracle database applications using OCI. Specific topics discussed are:

• Writing OCI Applications

• Compiling OCI Applications

• Linking OCI Applications

• XA Dynamic Registration

• The Oracle XA Library

• Using the Object Type Translator and the INTYPE File Assistant

  See Also: See the Oracle Call Interface Programmer's Guide for detailed information about writing OCI applications.

Writing OCI Applications

The general goal of an OCI application is to connect to an Oracle Server, engage in some sort of data exchange, and perform necessary data processing. While some flexibility exists in the order in which specific tasks can be performed, every OCI application needs to accomplish particular steps.

The basic programming structure used by the OCI is as follows:

1. Initialize the OCI programming environment and processes.

2. Allocate necessary handles, and establish a server connection and a user session.

3. Issue SQL statements to the server, and perform necessary application data processing.

4. Free statements and handles not to be reused or reexecute prepared statements again, or prepare a new statement.

5. Terminate user session and server connection.

   Note: The initialization of an OCI environment in Shared Data Mode that is discussed in the Oracle Call Interface Programmer's Guide is not supported on Windows in this release. It will be available in a future release.

Compiling OCI Applications

When you compile an OCI application, you must include the appropriate OCI header files. The header files are located in the \oracle_base\oracle_home\oci\include directory.

For example, if you are using Microsoft Visual C++ 6.0, you would need to put in the appropriate path in the Directories page of the Options dialog in the Tools menu. See Figure 2-1, "Directories Tab of the Options Dialog".

Figure 2-1 Directories Tab of the Options Dialog

Text description of the illustration msvcopts.gif

Linking OCI Applications

The OCI calls are implemented in dynamic link libraries (DLLs) that Oracle provides. The DLLs are located in the oracle_base\oracle_home\bin directory and are part of the Required Support Files (RSFs).

To use the Oracle DLLs to make OCI calls, you must link your application with oci.lib.

You do not have to indicate any special link options.

Note: Other libraries may be necessary, such as msvcrt.lib for Microsoft and bidsft.lib for Borland. These depend on the compiler.

oci.lib

oci.lib is a single, programmatic interface to Oracle. Oracle has removed any version number from the library name.

Client DLL Loading When Using LoadLibrary()

The following directories are searched in this order by LoadLibrary:

• Directory from which the application is loaded

• Current directory

• Windows NT:
  • 32-bit Windows system directory (system32). Use the GetWindowsDirectory function to obtain the path of this directory.

  • 16-bit Windows directory (system). There is no Win32 function that obtains the path of this directory, but it is searched.

• Windows 95 or Windows 98:
  • Windows directory. Use the GetWindowsDirectory function to obtain the path of this directory.

• Directories that are listed in the PATH environment variable

Running OCI Applications

To run an OCI application, ensure that the entire corresponding set of RSFs is installed on the machine that is running your OCI application.

The Oracle XA Library

The XA Application Program Interface (API) is typically used to enable an Oracle8 database to interact with a transaction processing (TP) monitor, such as:

• BEA Tuxedo

• IBM Transarc Encina

• IBM CICS

You can also use TP monitor statements in your client programs. The use of the XA API is supported from OCI.

The Oracle XA Library is automatically installed as part of Oracle8i Enterprise Edition. The following components are created in your Oracle home directory:

Component	Location
oraxa.lib	oracle_base\oracle_home\rdbms\xa
xa.h	oracle_base\oracle_home\rdbms\xa

Compiling and Linking an OCI Program with the Oracle XA Library

To compile and link an OCI program:

1. Compile program.c by using Microsoft Visual C++ or Borland C, making sure to include oracle_base\oracle_home\rdbms\xa in your path.

2. Link program.obj with the following libraries:

   Library	Located in...
   oraxa.lib	oracle_base\oracle_home\rdbms\xa
   oci.lib	oracle_base\oracle_home\oci\lib\msvc
   	or
   	oracle_base\oracle_home\oci\lib\borland

3. Run program.exe.

XA Dynamic Registration

The Oracle8i database supports the use of XA dynamic registration. XA dynamic registration improves the performance of applications interfacing with XA-compliant TP monitors. For TP Monitors to use XA dynamic registration with an Oracle database on Windows NT, you must add either an environmental variable or a registry variable to the Windows NT computer on which your TP monitor is running. See either of the following sections for instructions:

• Adding an Environmental Variable for the Current Session

• Adding a Registry Variable for All Sessions

Adding an Environmental Variable for the Current Session

Adding an environmental variable at the command prompt affects only the current MS-DOS session.

To add an environmental variable:

From the computer where your TP monitor is installed, enter the following at the MS-DOS command prompt:

C:\> set ORA_XA_REG_DLL = vendor.dll

where vendor.dll is the TP monitor DLL provided by your vendor.

Adding a Registry Variable for All Sessions

Adding a registry variable affects all sessions on your Windows NT computer. This is useful for computers where only one TP monitor is running.

To add a registry variable:

1. Go to the computer where your TP monitor is installed.

2. On Windows NT, enter the following at the MS-DOS command prompt:

   C:\> regedt32
   

   On Windows 95/98, enter:

   C:\> regedit
   
   

   The Registry Editor window appears.

3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE.

4. Choose the Add Value option in the Edit menu. The Add Value dialog box appears.

5. Enter ORA_XA_REG_DLL in the Value Name text box.

6. Select REG_EXPAND_SZ from the Data Type list box.

7. Click OK. The String Editor dialog box appears.

8. Type vendor.dll in the String field, where vendor.dll is the TP monitor DLL provided by your vendor.

9. Click OK. The Registry Editor adds the parameter.

10. Choose Exit from the Registry menu.

    The registry exits.

XA and TP Monitor Information

Refer to the following general information about XA and TP monitors:

• Distributed TP: The XA Specification published by X/Open (now part of OpenGroup). See the web site at:

  http://www.opengroup.org/publications/catalog/tp.htm

• Transaction Processing XPG4 X/Open CAE Specification XO/CAE/91/300 or C193 2/92

• X/Open Company, Ltd., 1010 El Camino Real, Suite 380, Menlo Park, CA 94025, U.S.A.

• Your specific TP monitor documentation

See Also: For more information about the Oracle XA Library and using XA dynamic registration, see Oracle8i Application Developer's Guide - Fundamentals.

Using the Object Type Translator and the INTYPE File Assistant

The Object Type Translator (OTT) is used to create C-struct representations of Abstract Data Types that have been created and stored in an Oracle8 database.

To take advantage of objects run OTT against the database, and a header file is generated that includes the C structs. For example, if a PERSON type has been created in the database, OTT can generate a C struct with elements corresponding to the attributes of PERSON. In addition, a null indicator struct is created that represents null information for an instance of the C struct.

The INTYPE file tells the OTT which object types should be translated. This file also controls the naming of the generated structs. The INTYPE File Assistant is a wizard that helps developers to create the INTYPE file.

Note that the CASE specification inside the INTYPE files, such as CASE=LOWER, applies only to C identifiers that are not specifically listed, either through a TYPE or TRANSLATE statement in the INTYPE file. It is important to provide the type name with the appropriate cases, such as TYPE Person and Type PeRsOn, in the INTYPE file.

The INTYPE File Assistant generates type names in the INTYPE file with the same case as in the database. By default, all of the types in the database are created in upper case.

In order to preserve the case, use double quotes when creating types in the database. For example:

CREATE TYPE "PeRsOn" AS OBJECT...

Object type dependencies are not checked by the Oracle INTYPE File Assistant. When adding an object type for inclusion in the INTYPE file, the INTYPE File Assistant does not add other object types with dependency relationships.

The INTYPE File Assistant requires explicit translations for object types or attributes whose names contain non-ASCII characters. These object types or attributes are indicated by the predefined tag Identifier in the fields where the translations would be entered. Users are required to override this tag with the C identifier translation for the corresponding object type or attribute. The INTYPE File Assistant does not create the INTYPE file until all required translations have been entered.

OTT on Windows NT can be invoked from the command line. Additionally, a configuration file may be named on the command line. For Windows NT, the configuration file is ottcfg.cfg, located in oracle_base\oracle_home\precomp\admin.

Additional Information: See the Oracle Call Interface Programmer's Guide for more information about OTT and INTYPE files. In addition, see the online help for OTT.