Oracle Call Interface Getting Started for Windows Platforms

Library

Product

Contents

Index

Introducing Oracle Call Interface

Oracle Call Interface (OCI) Overview
What Is Included?
Oracle Directory Structure
Sample OCI Programs

Oracle Call Interface (OCI) Overview

The Oracle Call Interface (OCI) is an application programming interface (API) for accessing an Oracle database from a C program.

You make calls directly to the OCI functions from within your C program to direct the execution of your SQL statements.

OCI requires more programming than Pro*C and should be used to develop applications which require greater control over processing SQL statements.

You can build OCI applications using techniques detailed in this book. You do not need to precompile the source code, because OCI applications contain no EXEC SQL statements.

What Is Included?

The Oracle Call Interface for Windows platforms package includes:

Oracle Call Interface

Required Support Files (RSF)

Oracle Installer

sample programs for demonstrating how to build applications using Oracle Call Interface

libraries for linking OCI programs

new client DLL (OCIW32.DLL and OCIW16.DLL)

OCIW32.DLL

OCIW32.DLL is included with OCI Release 7.3 for Windows NT/95. It contains only the OCI layer. This new DLL dynamically loads any Oracle client DLL available on user systems. The impact of this is that users do not generally need be concerned with which Oracle client DLLs are available on their systems.

However, functionality available to users is limited to the DLLs they have loaded. If a function is not available in the loaded client DLL, an error is returned when that function is called.

Note If OCI 7.3-specific functions are used to develop applications, and those applications are then deployed onto 7.2 systems, the 7.3-specific functions will not be available, and an error (ORA-1010'Invalid OCI Operation') will be returned.

Implementation

OCIW32.DLL attempts to translate the variable ORAOCI. If the variable exists, it's value is expected to be the name of an Oracle client DLL. If the variable does not exist, or if using it's 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.

Next, OCIW32 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 instead loaded on demand at runtime. No errors are returned when attempting to load function pointers.

When a user calls a function, check to see if a pointer exists, and call the function if it does. If it does not, return an error (ORA-1010'Invalid OCI Operation')

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

Loading of Windows NT/95 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

Windows NT:

the 32-bit Windows system directory (SYSTEM32). Use the GetWindowsDirectory function to get the path of this directory.

the 16-bit Windows directory (SYSTEM). There is not a Win32 function that obtains the path of this directory, but it is searched.

Windows 95--the Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

the Windows directory. Use the GetWindowsDirectory function to get 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 LibMain() 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.

OCIW16.DLL

OCIW16.DLL is included with OCI Release 7.3 for Windows. It contains only the OCI layer. This new DLL dynamically loads any Oracle client DLL available on user systems. This feature means that users need not generally be concerned with which Oracle client DLLs are available on their systems.

However, functionality available to users is limited to the DLLs they have loaded. If a function is not available in the loaded client DLL, an error is returned when that function is called.

Implementation

OCIW16.DLL attempts to translate the variable ORAOCI. If the variable exists, it's value is expected to be the name of an Oracle client DLL. If the variable does not exist, or if using it's 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.

Next, OCIW16.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 instead loaded on demand at runtime. No errors are returned when attempting to load function pointers.

When a user calls a function, check to see if a pointer exists, and call the function if it does. If it does not, return an error (ORA-1010'Invalid OCI Operation')

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

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

The following directories are searched in this order by LoadLibrary:

current directory

Windows directory (directory containing WIN.COM). This path is retrieved by the GetWindowsDirectory function.

Windows system directory (directory containing system files such as GDI.EXE). This path is retrieved by the GetSystemDirectory function.

directory containing the executable file for the current task. This path is retrieved by the GetmoduleFileName function.

directories listed in the PATH environment variable

list of directories mapped in a network

Note If no Oracle client DLL can be loaded, the LibMain() of OCIW16.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.

Translating Variables

Variables should be set in:

the Registry: HKEY_LOCAL_MACHINE/SOFTWARE/ORACLE (for Windows NT/95)

the [ORACLE] section of WIN.INI or ORACLE.INI (for Windows 3.1)

Linking

No special link options are required. Link your application with OCIW32.LIB (or OCIW16.LIB) instead of

ORA7NT.LIB, ORA71.LIB, or ORA72.LIB (for Windows NT/95)

ORA7WIN.LIB, ORA71WIN.LIB, or ORA72WIN.LIB (for Windows 3.1)

Oracle Directory Structure

When you install Oracle Call Interface for Windows NT/95, an Oracle home directory is created on the hard drive of your computer. Your Oracle home directory, as described below, contains the following subdirectories and files.

Directory	Contents
\ORANT, \ORAWIN95, or \ORAWIN	Oracle Home directory
\BIN	executable programs and batch files for the Oracle database tools and the dynamic link libraries (DLLs) used by the SQL*Net driver and other applications
\DBS	some common SQL scripts and message files
\ORAINST	Oracle Installer files

Depending on the supported products you choose to install, Oracle Installer also creates the appropriate product subdirectory.

For example, if you install Oracle Call Interface for Windows NT/95 Release 7.3:

\OCI73

contains Oracle Call Interface for Windows Platforms subdirectories under \ORANT, \ORAWIN95, or \ORAWIN

OCI Subdirectories

The OCI73 subdirectory contains the following subdirectories and includes the OCI files listed below.

Directory	Contents
\INCLUDE	header files, such as OCIDFN.H and OCIAPR.H
\LIB	Oracle libraries that link into Windows NT/95 programs
\SAMPLE	C sample program directories. This subdirectory contains separate subdirectories for Microsoft and Borland samples.

Sample OCI Programs

The OCI installation procedure copies a set of sample programs and their corresponding project files into the \SAMPLE subdirectory (see table below). Oracle recommends that you build and run these sample programs to verify that OCI has been successfully installed and to familiarize yourself with the steps involved in developing OCI applications. After you have finished using these sample programs, you can delete them if you choose. For details, see "Project Files" in Chapter 3.

OCI sample programs are built by opening the .MAK file provided with each sample program in Microsoft Visual C++ and doing a project build.

*Sample Program Groups*	Contents
OCI (WINDOWS)	OCI C sample programs for Windows NT
OCI C (GENERAL)	OCI C sample programs (QuickWin)
OCI C (NONBLOCKING)	OCI C sample nonblocking programs

OCI non-blocking functionality is supported against Oracle7 Release 7.2 or later databases, and requires that you use SQL*Net Release 2.2 or later on both the client and server if you are running against a remote database.

Prev Next

Library

Product

Contents

Index