Oracle Call Interface Getting Started
Release 8.1.6 for Windows

Part Number A73022-01





Go to previous page Go to next page

Building OCI Applications

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

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.


    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 msvcopts.gif follows

Text description of the illustration msvcopts.gif

See Also:

See your compiler's documentation for specific information about compiling your application and special compiler options. 

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.


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


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:

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:

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 





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... 









  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 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.


  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

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:


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. 

Go to previous page Go to next page
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.