2
Building OCI Applications

This chapter provides an overview of how to build Oracle database applications using OCI.

This chapter contains these topics:

• Writing OCI Applications
  
  
• Compiling OCI Applications
  
  
• Linking OCI Applications
  
  
• The Oracle XA Library
  
  
• Using the Object Type Translator and the INTYPE File Assistant

  See Also: 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 must 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.

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 can either dynamically load the DLL and function entry points, or you can link your application with the import library oci.lib. Oracle Corporation only provides the oci.lib import library for use with the Microsoft Compiler. Other compilers, though likely compatible with the Oracle DLLs, are not tested and supported by Oracle for use with OCI.

When using oci.lib with the Microsoft Compiler, you do not have to indicate any special link options.

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 or Windows 2000:
  
  
  • 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 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 Required Support Files (RSFs) is installed on the computer that is running your OCI application.

The Oracle XA Library

The XA Application Program Interface (API) is typically used to enable an Oracle9i 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 Oracle9i Enterprise Edition. The following components are created in your Oracle home directory:

Table 2-1 Oracle XA Library Components

Component	Location
oraxa9.lib	ORACLE_BASE\ORACLE_HOME\rdbms\xa
xa.h	ORACLE_BASE\ORACLE_HOME\rdbms\demo

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++, making sure to include ORACLE_BASE\ORACLE_HOME\rdbms\xa in your path.
   
   
2. Link program.obj with the following libraries:
   
   
   

   Library	Located in...
   oraxa9.lib	ORACLE_BASE\ORACLE_HOME\rdbms\xa
   oci.lib	ORACLE_BASE\ORACLE_HOME\oci\lib\msvc

3. Run program.exe.

Using XA Dynamic Registration

The Oracle9i 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 session.

To add an environmental variable:

From the computer where your TP monitor is installed, enter the following at the 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 or Windows 2000, enter the following at the command prompt:
   
   

   C:\> regedt32
   
   

   On Windows 98, enter:

   C:\> regedit
   
   

   The Registry Editor window appears.

3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID.

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. Choose 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. Choose 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 (C193) published by the Open Group. The Open Group., 1010 El Camino Real, Suite 380, Menlo Park, CA 94025, U.S.A.
  
  
• See the Web site at:

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

• Your specific TP monitor documentation

Oracle C++ Call Interface Methods Specific to Windows NT

The global methods for getting collections of Refs or setting collections of Refs from classes Statement and ResultSet have changed for Windows NT as follows:

• Use getVectorOfRefs in place of getVector on Windows NT
  
  
• Use setVectorOfRefs in place of setVector on Windows NT

The method names have been changed but the number of parameters and the types of the parameters remain the same as the original getVector and setVector methods for Refs on these classes.

• Applications on Windows NT platforms should be calling these new methods only for retrieving and inserting collections of Refs.
  
  
• Applications not running on Windows NT platforms have a choice of calling the currently existing getVector and setVector methods. However, Oracle Corporation recommends the use of the new methods for any vector operations with Refs.

ResultSet Class: Fetching collection of Refs

void getVectorOfRefs(ResultSet  *rs, unsigned int index, 
 OCCI_STD_NAMESPACE::vector<Ref<T> > &vect);

This method fetches a column value specified by the column index that is a collection of Refs from a result set.

The parameters are:

• rs - ResultSet object
  
  
• index - the column index of a column which is a collection of Refs
  
  
• vect - the vector into which the Refs are fetched

Statement Class: Fetching collection of Refs

void getVectorOfRefs(Statement *stmt, unsigned int index, 
 OCCI_STD_NAMESPACE::vector<Ref<T> > &vect);

This method fetches a column value specified by the column index that is a collection of Refs from a statement. This is used in case of OUT binds and data manipulation language (DML) returning clauses. The parameters are:

• stmt - statement object
  
  
• index - the column index of a column that is a collection of Refs
  
  
• vect - the vector into which the Refs are fetched

Statement Class: Inserting a collection of Refs

template  <class T>
void setVectorOfRefs(Statement *stmt, unsigned int paramIndex,
  const OCCI_STD_NAMESPACE::vector<Ref<T> > &vect, 
  const OCCI_STD_NAMESPACE::string &sqltype);

This method inserts a collection of Refs into a column specified by the index. The parameters are:

• stmt - statement object
  
  
• paramIndex - the column index of a column that is a collection of Refs
  
  
• vect - the vector of Refs that are inserted into the column
  
  
• sqltype - the type name of the collection that was created in the database

The global methods for the fetching or inserting of collections of objects have been changed for Windows NT. The interface remains the same with respect to the method names and the number of parameters and the datatypes, but differs in the template parameter definition for Windows NT. Specifically, the template parameter for the template methods of getVector and setVector of objects (object pointers) on Windows NT have a T instead of a T * as shown in the following APIs.

Note that the usage of the methods does not differ across the platforms (users need not modify the call to these methods at all). On Windows NT, the template arguments passed as object pointers in the method call are specialized for the parameter T instead of T * on other platforms.

class ResultSet: fetching a collection of objects

#ifdef WIN32COMMON
   template <class T>
   void getVector( ResultSet *rs, unsigned int index, 
     OCCI_STD_NAMESPACE::vector< T > &vect) ;
#else
  template <class T>
    void getVector( ResultSet *rs, unsigned int index,
      OCCI_STD_NAMESPACE::vector< T* > &vect) ;
#endif

This method fetches a collection of objects from a ResultSet for the column specified by the index.

The parameters are:

• rs - resultSet object
  
  
• index - column index
  
  
• vect - the vector into which the objects should be fetched

class Statement: fetching a collection of objects

#ifdef WIN32COMMON
   template <class T>
   void getVector( Statement *stmt, unsigned int index,  
     OCCI_STD_NAMESPACE::vector< T > &vect) ;
  #else
   template <class T>
   void getVector( Statement *stmt, unsigned int index,
     OCCI_STD_NAMESPACE::vector< T* > &vect) ;
  #endif

This method fetches a collection of objects from a statement for the column specified by the index. This method is used in case of OUT binds and DML returning clauses. The parameters are:

• stmt - statement object
  
  
• index - column index
  
  
• vect - the vector into which the objects should be fetched

class Statement: inserting a vector of objects

#ifdef WIN32COMMON
  template <class T>
  void setVector( Statement *stmt, unsigned int paramIndex, 
    const OCCI_STD_NAMESPACE::vector< T > &vect, 
    const  OCCI_STD_NAMESPACE::string &sqltype) ;
#else
  template <class T>
  void setVector( Statement *stmt, unsigned int paramIndex,
    const OCCI_STD_NAMESPACE::vector<T* > &vect, 
    const OCCI_STD_NAMESPACE::string &sqltype) ;
#endif

This method inserts a collection of objects into a statement for the column specified by the index. The parameters are:

• stmt - statement object
  
  
• paramIndex - column index
  
  
• vect - the vector into which the objects should be fetched
  
  
• sqltype - the type name of the collection that was created in the database

  See Also: Oracle9i Application Developer's Guide - Fundamentals for more information about the Oracle XA Library and using XA dynamic registration

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

The Intype File Assistant (IFA) is deprecated in this release and it will no longer be supported in future versions.