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
• Running OCI Applications
• Using the Object Type Translator and the INTYPE File Assistant

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.

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

   

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_HOME\OCI80\INCLUDE directory.

Additional Information:   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_HOME\BIN directory and are part of the Required Support Files.

To use the Oracle DLLs to make OCI calls, you must link your application with one of the OCI libraries:

• OCI.LIB
• OCIW32.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 your compiler.

   

OCI.LIB

Release 8.0.5 of the Oracle Call Interface for Windows NT, 95, or 98 includes a library called OCI.LIB. Oracle has removed any version number from the library name. Now, you do not have to relink your applications every time there is a new release of OCI.

OCIW32.LIB

OCIW32.LIB is included for backward compatibility with Oracle7. This library contains only the 7.x OCI functions.

This DLL dynamically loads the Oracle client DLL that is available on user systems. However, this DLL only contains the 7.x OCI calls. With Release 8 installed, OCIW32.DLL loads ORA805.DLL and passes the functions to the DLL described in the implementation below.

OCIW32.DLL attempts to translate the registry variable ORAOCI.

• If the variable exists, its value is expected to be the name of an Oracle client DLL: ORA805.DLL, ORA804.DLL, ORA803.DLL, ORA73.DLL, ORA72.DLL, ORANT71.DLL, or ORA70.DLL.
• If the variable does not exist, or if using its value to call LoadLibrary fails, then OCIW32.DLL continues to search through a predefined list of known Oracle client DLL names (most recent to least recent RSFs). If no Oracle client DLLs are found, an error is returned.

Note:   The registry variables ORAOCI and ORAOCI_DEBUG should be set in the HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID subkey, where ID indicates the home in which OCIW32.DLL is installed.

   

Next, OCIW32.DLL fills in a table of function pointers, one for each OCI call. Obsolete OCI functions are not immediately loaded since they are most likely not to be used (and may be omitted in future OCI releases). These are loaded on demand at runtime instead. No errors are returned when attempting to load function pointers.

When a user calls a function in OCIW32.DLL, the function in OCIW32.DLL checks to see if the corresponding function in the Oracle client DLL exists.

• If the function does exist, it is called by OCIW32.DLL.
• If the function does not exist, the error "ORA-1010: Invalid OCI Operation" is returned by OCIW32.DLL.

Note:   A debug mode is available. Set ORAOCI_DEBUG to any value, and a number of informational messages boxes are raised.

   

Loading of Client DLLs (when LoadLibrary() is used)

The following directories are searched in this order by LoadLibrary:

• directory from which the application is loaded
• current directory
• on Windows NT:
• the 32-bit Windows system directory (SYSTEM32). Use the GetWindowsDirectory function to obtain the path of this directory.
• the 16-bit Windows directory (SYSTEM). There is no Win32 function that obtains the path of this directory, but it is searched.
• on Windows 95 or Windows 98:
• the Windows directory. Use the GetWindowsDirectory function to obtain the path of this directory.

the directories that are listed in the PATH environment variable

Note:   If no Oracle client DLL can be loaded, the DllMain() function of OCIW32.DLL will return FALSE and the application will fail to load. If the operating system does not provide an adequate error message to detect this, set ORAOCI_DEBUG.

   

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.

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.

Note:   As on the Solaris platform, OTT on Windows NT can be invoked from the command line. See Oracle Call Interface Programmer's Guide for more information. Additionally, a configuration file may be named on the command line. For Windows NT, the configuration file is:  %ORACLE_HOME%\OTT80\OTTCFG.CFG.

   

To take advantage of objects, essentially, 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 (for example, CASE=LOWER) applies only to C identifiers that are not specifically listed, either through a TYPE or TRANSLATE statement in the INTYPE file. Therefore, it is important to provide the type name with the appropriate cases (TYPE Person, Type PeRsOn, and so on) 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 type(s) 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.

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.

   

---