1
Introduction, New Features, and Upgrading

This chapter introduces you to the Oracle Call Interface (OCI). It provides background information that you need to develop applications using the OCI. This chapter also introduces special terms that are used in discussing the OCI and describes the changes in the new OCI release. The following topics are covered:

• Overview of OCI

• New Features

• Compatibility, Upgrading, and Migration

Overview of OCI

The Oracle Call Interface (OCI) is an application programming interface (API) that allows you to create applications that use the native procedures or function calls of a third-generation language to access an Oracle database server and control all phases of SQL statement execution. OCI supports the datatypes, calling conventions, syntax, and semantics of a number of third-generation languages including C, C++, COBOL and FORTRAN.

OCI provides:

• improved performance and scalability through the efficient use of system memory and network connectivity

• consistent interfaces for dynamic session and transaction management in a two-tier client-server or multi-tier environment

• N-tiered authentication

• comprehensive support for application development using Oracle objects

• access to external databases

• applications that can service an increasing number of users and requests without additional hardware investments

OCI allows you to manipulate data and schemas in an Oracle database using a host programming language, such as C. It provides a library of standard database access and retrieval functions in the form of a dynamic runtime library (OCI library) that can be linked in an application at runtime. This eliminates the need to embed SQL or PL/SQL within 3GL programs.

OCI has many new features that can be categorized into several primary areas:

• encapsulated/opaque interfaces

• simplified user authentication and password management

• extensions to improve application performance and scalability

• consistent interface for transaction management

• OCI extensions to support client side access to Oracle objects

Advantages of OCI

OCI provides significant advantages over other methods of accessing an Oracle database:

• more fine-grained control over all aspects of the application design

• high degree of control over program execution

• use of familiar 3GL programming techniques and application development tools such as browsers and debuggers

• supports of dynamic SQL (method 4)

• availability on the broadest range of platforms of all the Oracle Programmatic Interfaces

• dynamic bind and define using callbacks

• describe functionality to expose layers of server metadata

• asynchronous event notification for registered client applications

• enhanced array data manipulation language (DML) capability for array INSERTs, UPDATEs, and DELETEs

• ability to associate a commit request with an execute to reduce roundtrips

• optimization for queries using transparent prefetch buffers to reduce roundtrips

• thread safety so you do not have to user mutual exclusive locks (mutex) on OCI handles

Building an OCI Application

As Figure 1-1 shows, you compile and link an OCI program in the same way that you compile and link a non-database application. There is no need for a separate preprocessing or precompilation step.

Figure 1-1 The OCI Development Process

Oracle Corporation supports most popular third-party compilers. The details of linking an OCI program vary from system to system. On some platforms, it may be necessary to include other libraries, in addition to the OCI library, to properly link your OCI programs. See your Oracle system-specific documentation and the installation guide for more information about compiling and linking an OCI application for your specific platform.

Parts of the OCI

The OCI encompasses four main sets of functionality:

• APIs to design a scalable, multi-threaded application that can support large numbers of users securely

• SQL access functions, for managing database access, processing SQL statements, and manipulating objects retrieved from an Oracle database server

• datatype mapping and manipulation functions, for manipulating data attributes of Oracle types

• data loading functions, for loading data directly into the database without using SQL statements

• external procedure functions, for writing C callbacks from PL/SQL

Procedural and Non-Procedural Elements

The Oracle Call Interface (OCI) allows you to develop scalable, multi-threaded applications on multi-tiered architecture that combine the non-procedural data access power of Structured Query Language (SQL) with the procedural capabilities of most programming languages, such as C and C++.

• In a non-procedural language program, the set of data to be operated on is specified, but what operations will be performed, or how the operations are to be carried out is not specified. The non-procedural nature of SQL makes it an easy language to learn and to use to perform database transactions. It is also the standard language used to access and manipulate data in modern relational and object-relational database systems.

• In a procedural language program, the execution of most statements depends on previous or subsequent statements and on control structures, such as loops or conditional branches, which are not available in SQL. The procedural nature of these languages makes them more complex than SQL, but it also makes them very flexible and powerful.

The combination of both non-procedural and procedural language elements in an OCI program provides easy access to an Oracle database in a structured programming environment.

The OCI supports all SQL data definition, data manipulation, query, and transaction control facilities that are available through an Oracle database server. For example, an OCI program can run a query against an Oracle database. The queries can require the program to supply data to the database using input (bind) variables, as follows:

SELECT name FROM employees WHERE empno = :empnumber

In the above SQL statement, :empnumber is a placeholder for a value that will be supplied by the application.

You can also take advantage of PL/SQL, Oracle's procedural extension to SQL. The applications you develop can be more powerful and flexible than applications written in SQL alone. The OCI also provides facilities for accessing and manipulating objects in an Oracle database server.

Object Support

With release 8i, the Oracle server has facilities for working with object types and objects. An object type is a user-defined data structure representing an abstraction of a real-world entity. For example, the database might contain a definition of a person object. That object might have attributes--first_name, last_name, and age--which represent a person's identifying characteristics.

The object type definition serves as the basis for creating objects, which represent instances of the object type. Using the object type as a structural definition, a person object could be created with the attributes 'John', 'Bonivento', and '30'. Object types may also contain methods--programmatic functions that represent the behavior of that object type.

See Also: For a more detailed explanation of object types and objects, see Oracle8i Concepts, and Oracle8i Application Developer's Guide - Fundamentals.

The Oracle OCI includes functions that extend the capabilities of the OCI to handle objects in an Oracle database server. Specifically, the following capabilities have been added to the OCI:

• support for execution of SQL statements that manipulate object data and schema information

• support for passing object references and instances as input variables in SQL statements.

• support for declaring object references and instances as variables to receive the output of SQL statements

• support for fetching object references and instances from a database

• support for describing the properties of SQL statements that return object instances and references

• support for describing PL/SQL procedures or functions with object parameters or results

• commit and rollback calls have been extended to synchronize object and relational functionality

Additional OCI calls are provided to support manipulation of objects after they have been accessed by way of SQL statements. For a more detailed description of enhancements and new features, refer to "New Features".

SQL Statements

One of the main tasks of an OCI application is to process SQL statements. Different types of SQL statements require different processing steps in your program. It is important to take this into account when coding your OCI application. Oracle recognizes several types of SQL statements:

• Data Definition Language

• Control Statements
  • Transaction Control

  • Session Control

  • System Control

• Data Manipulation Language (DML)

• Queries

  Note: Queries are often classified as DML statements, but OCI applications process queries differently, so they are considered separately here.

• PL/SQL

• Embedded SQL

Data Definition Language

Data Definition Language (DDL) statements manage schema objects in the database. DDL statements create new tables, drop old tables, and establish other schema objects. They also control access to schema objects.

The following is an example of creating and specifying access to a table:

CREATE TABLE employees
    (name               VARCHAR2(20),
          ssn                  VARCHAR2(12),
          empno              NUMBER(6),
          mgr                  NUMBER(6),
          salary            NUMBER(6))

GRANT UPDATE, INSERT, DELETE ON employees TO donna
REVOKE UPDATE ON employees FROM jamie

DDL statements also allow you to work with objects in the Oracle database server, as in the following series of statements which creates an object table:

CREATE TYPE person_t AS OBJECT (
        name                VARCHAR2(30),
        ssn                  VARCHAR2(12),
        address          VARCHAR2(50))

CREATE TABLE person_tab OF person_t

Control Statements

OCI applications treat transaction control, session control, and system control statements like DML statements. See the Oracle8i SQL Reference for information about these types of statements.

Data Manipulation Language

Data manipulation language (DML) statements can change data in the database tables. For example, DML statements are used to

• INSERT new rows into a table

• UPDATE column values in existing rows

• DELETE rows from a table

• LOCK a table in the database

• EXPLAIN the execution plan for a SQL statement

DML statements can require an application to supply data to the database using input (bind) variables. See the section "Binding" for more information about input bind variables.

DML statements also allow you to work with objects in the Oracle database server, as in the following example, which inserts an instance of type person_t into the object table person_tab:

INSERT INTO person_tab
        VALUES (person_t('Steve May','123-45-6789','146 Winfield Street'))

Queries

Queries are statements that retrieve data from a database. A query can return zero, one, or many rows of data. All queries begin with the SQL keyword SELECT, as in the following example:

SELECT dname FROM dept
        WHERE deptno = 42

Queries access data in tables, and they are often classified with DML statements. However, OCI applications process queries differently, so they are considered separately in this guide.

Queries can require the program to supply data to the database using input (bind) variables, as in the following example:

SELECT name 
FROM employees
WHERE empno = :empnumber

In the above SQL statement, :empnumber is a placeholder for a value that will be supplied by the application.

When processing a query, an OCI application also needs to define output variables to receive the returned results. In the above statement, you would need to define an output variable to receive any name values returned from the query.

See Also: See the section "Binding" for more information about input bind variables. See the section "Defining" for information about defining output variables.

See Chapter 4, "SQL Statement Processing", for detailed information about how SQL statements are processed in an OCI program.

PL/SQL

PL/SQL is Oracle's procedural extension to the SQL language. PL/SQL processes tasks that are more complicated than simple queries and SQL data manipulation language statements. PL/SQL allows a number of constructs to be grouped into a single block and executed as a unit. Among these are:

• one or more SQL statements

• variable declarations

• assignment statements

• procedural control statements (IF...THEN...ELSE statements and loops)

• exception handling

You can use PL/SQL blocks in your OCI program to

• call Oracle stored procedures and stored functions

• combine procedural control statements with several SQL statements, to be executed as a single unit

• access special PL/SQL features such as records, tables, cursor FOR loops, and exception handling

• use cursor variables

• access and manipulate objects in an Oracle database server

The following PL/SQL example issues a SQL statement to retrieve values from a table of employees, given a particular employee number. This example also demonstrates the use of placeholders in PL/SQL statements.

BEGIN
        SELECT ename, sal, comm INTO :emp_name, :salary, :commission
        FROM emp
        WHERE ename = :emp_number;
END;

Note that the placeholders in this statement are not PL/SQL variables. They represent input values passed to Oracle when the statement is processed. These placeholders need to be bound to C language variables in your program.

See Also: See the PL/SQL User's Guide and Reference for information about coding PL/SQL blocks.

See the section "Binding Placeholders in PL/SQL" for information about working with placeholders in PL/SQL.

Embedded SQL

The OCI processes SQL statements as text strings, which an application passes to Oracle on execution. The Oracle precompilers (Pro*C/C++, Pro*COBOL, Pro*FORTRAN) allow programmers to embed SQL statements directly into their application code. A separate precompilation step is then necessary to generate an executable application.

It is possible to mix OCI calls and embedded SQL in a precompiler program. Refer to the Pro*C/C++ Precompiler Programmer's Guide for more information.

Special OCI/SQL Terms

This guide uses special terms to refer to the different parts of a SQL statement. For example, a SQL statement such as

SELECT customer, address
FROM customers
WHERE bus_type = 'SOFTWARE'
AND sales_volume = :sales

contains the following parts:

• a SQL command -- SELECT

• two select-list items -- customer and address

• a table name in the FROM clause -- customers

• two column names in the WHERE clause -- bus_type and sales_volume

• a literal input value in the WHERE clause -- 'SOFTWARE'

• a placeholder for an input variable in the WHERE clause -- :sales

When you develop your OCI application, you call routines that specify to the Oracle database server the address (location) of input and output variables in your program. In this guide, specifying the address of a placeholder variable for data input is called a bind operation. Specifying the address of a variable to receive select-list items is called a define operation.

For PL/SQL, both input and output specifications are called bind operations. These terms and operations are described in Chapter 4, "SQL Statement Processing".

New Features

This release of OCI provides the following new features and performance advantages:

• Ability to create new object with non-NULL attribute values

• Support for universal ROWIDs

• Support for fixed-width Unicode

• OCIThread package for thread manipulation

• Ability to register user-created callback functions

• Enhanced application failover processing ability

• Support for publish/subscribe notification

• No-wait locking option for objects

• Ability to detect object changes when flushing

• Support for temporary LOBs

• Enhancements to LOB support

• Enhanced array DML statement execution allowing all errors to be returned in a batch

• Enhanced DML...RETURNING support

• Ability to create objects based on object views or user-created object IDs

• Support for non-blocking mode

• Additional functional and performance enhancements

• Publish-subscribe functionality for client notification of events

• Direct path loading calls that provide access to the direct block formatter of the Oracle server

• Reduced memory usage at runtime

• Increased runtime performance with code reduction

• Increased query performance with streamlined and more efficient fetch protocol

Each of these features is discussed in greater detail in later chapters of this guide. See the section "Compatibility, Upgrading, and Migration" for information about new calls that supersede existing routines. See chapters 15, 16, 17, and 18 in Part 3 for listings of OCI calls. Note that new calls, such as "Advanced Queuing and Publish-Subscribe Functions" and "Direct Path Loading Functions", have been added and various existing calls have updated.

Encapsulated Interfaces

All the data structures that are used by OCI are encapsulated in the form of opaque interfaces that are called handles. A handle is an opaque pointer to a storage area allocated by the OCI library that stores context information, connection information, error information, or bind information about a SQL or PL/SQL statement. A client allocates a certain type of handle, populates one or more of those handles through well-defined interfaces, and sends requests to the server using those handles. In turn, applications can access the specific information contained in the handle by using accessor functions. The OCI library manages a hierarchy of handles. Encapsulating the OCI interfaces using these handles has several benefits to the application developer including:

• Reduction in the amount of server side state information that needs to be retained thereby reducing server side memory usage

• Improved application developer productivity by eliminating the need for global variables, making error reporting easier and providing consistency in the way OCI variables are accessed and used

• Further, the encapsulation of OCI structures in the form of handles makes them opaque to the application developer allowing changes to be made to the underlying structure without affecting applications

Simplified User Authentication and Password Management

The Oracle OCI provides application developers simplified user authentication and password management in several ways:

• Allows a single OCI application to authenticate and maintain multiple users.

• Allows the application to update a user's password which is particularly helpful if an expired password message is returned by an authentication attempt.

The Oracle OCI supports two types of login sessions:

• a simplified login function for sessions where a single user connects to the database using a login name and password.

• a setup in which a single OCI application authenticates and maintains multiple sessions by separating the login session, which is the session created when a user logs into an Oracle database, from the user sessions, which are all other sessions created by a user. This is an important difference from Oracle 7.3, in which sessions could be created implicitly by starting new transactions once the user has logged in to the database, a process called session cloning. These user sessions in Oracle 7.3 inherited the privileges and security context from the login session. Oracle OCI requires a client to provide all the necessary authentication information for each user session. This allows an OCI application to support multiple users.

Extensions to Improve Application Performance and Scalability

The Oracle OCI has several enhancements to improve application performance and scalability. Application performance has been improved by reducing the number of client to server round trips required and scalability improvements have been facilitated by reducing the amount of state information that needs to be retained on the server side. Some of these features include:

• Increased client-side processing, and reduced server-side requirements on queries

• Implicit prefetching of SELECT statement result sets to eliminate the describe round trip, reduce roundtrips, and reduce memory usage

• Elimination of open and close cursor round trips

• Improved support for multi-threaded environments

• Piggy-backed calls

• Session multiplexing over connections

• Consistent support for a variety of configurations including standard 2-tier client-server configurations, server-to-server transaction coordination, and 3-tier TP-monitor configurations

• Consistent support for local and global transactions including support for the XA interface's TM_JOIN operation

• Improved scalability by providing the ability to concentrate connections, processes, and sessions across users on connections and eliminating the need for separate sessions to be created for each branch of a global transaction

• Allowing applications to authenticate multiple users and allow transactions to be started on their behalf

Oracle OCI Object Support

The Oracle OCI provides the most comprehensive application programming interface for programmers seeking to use the Oracle server's object capabilities. These features can be divided into five major categories:

• Client-side Object Cache

• Runtime environment for objects

• Associative and navigational interfaces to access and manipulate objects

• Type management functions to access information about object types in an Oracle database

• Type mapping and manipulation functions for manipulating data attributes of Oracle types

• Object Type Translator utility, which maps internal Oracle schema information to client-side language bind variables

Client-side Object Cache

The object cache is a client-side memory buffer that provides lookup and memory management support for objects. It stores and tracks objects instances which have been fetched by an OCI application from the server to the client side. The object cache is created when the OCI environment is initialized. Multiple applications running against the same server will each have their own object cache. The cache tracks the objects which are currently in memory, maintains references to objects, manages automatic object swapping and tracks the meta-attributes or type information about objects. The cache provides the following OCI applications:

• Improved application performance by reducing the number of client-to-server round trips required to fetch and operate on objects

• Enhanced scalability by supporting object swapping from the client-side cache

• Improved concurrency by supporting object-level locking

Associative and Navigational Interfaces

Applications using the Oracle OCI can access objects in the Oracle server through several types of interfaces:

• Using SQL SELECT, INSERT, and UPDATE statements

• Using a C-style pointer chasing scheme to access objects in the client-side cache by traversing the corresponding smart pointers or REFs

The Oracle OCI provides a set of functions with extensions to support object manipulation using SQL SELECT, INSERT, and UPDATE statements. To access Oracle objects these SQL statements use a consistent set of steps as if they were accessing relational tables. The Oracle OCI provides the following sets of functions required to access objects using SQL statements for:

• Binding and defining object type instances and references as input and output variables of SQL statements

• Executing SQL statements that contain object type instances and references

• Fetching object type instances and references

• Describing a select-list item of an Oracle object type

The Oracle OCI also provides a set of functions using a C-style pointer chasing scheme to access objects once they have been fetched into the client-side cache by traversing the corresponding smart pointers or REFs. This navigational interface provides functions for:

• Instantiating a copy of a referenceable persistent object, that is, of a persistent object with object ID in the client-side cache by pinning its smart pointer or REF.

• Traversing a sequence of objects that are connected to each other by traversing the REFs that point from one to the other.

• Dynamically getting and setting values of an object's attributes.

Runtime Environment for Objects

The Oracle OCI provides a runtime environment for objects that offers a set of functions for managing how Oracle objects are used on the client-side. These functions provide the necessary functionality for:

• Connecting to an Oracle server in order to access its object functionality including initializing a session, logging on to a database server, and registering a connection.

• Setting up the client-side object cache and tuning its parameters.

• Getting errors and warning messages.

• Controlling transactions that access objects in the server.

• Associatively accessing objects through SQL.

• Describing a PL/SQL procedure or function whose parameters or result are of Oracle type system types.

Type Management, Mapping and Manipulation Functions

The Oracle OCI provides two sets of functions to work with Oracle objects:

• Type Mapping functions allow applications to map attributes of an Oracle schema which are represented in the server as internal Oracle datatypes such as Oracle's number, date and string types to their corresponding host language types such as integer, months and days.

• Type Manipulation functions allow host language applications to manipulate individual attributes of an Oracle schema such as setting/getting their values and flushing their values to the server.

Additionally, the OCIDescribeAny() function can provide information about objects stored in the database.

Object Type Translator

The Object Type Translator (OTT) utility translates schema information about Oracle object types into client-side language bindings. That is, the Oracle OTT translates type information into declarations of host language variables, such as structures and classes. The OTT takes an intype file which contains metadata information about Oracle schema objects (an Oracle data dictionary) and generates an outtype file and the necessary header and implementation files that must be included in a C application that runs against the object schema. Both OCI applications and Pro*C precompiler applications may include code generated by the OTT. The OTT has many benefits including:

• Improves application developer productivity: OTT eliminates the need for application developers to write by hand the host language variables that correspond to schema objects.

• Maintains SQL as the data-definition language of choice: By providing the ability to automatically map Oracle schema objects that are created using SQL to host language variables automatically, OTT facilitates using SQL as the data-definition language of choice. This in turn allows Oracle to support a consistent model of the user's data, enterprise-wide.

• Facilitates schema evolution of object types: OTT provides the ability to regenerate #include files when the schema is changed allowing Oracle applications to support schema evolution.

OTT is typically invoked from the command line by specifying the intype file, the outtype file and the specific database connection. With Oracle, OTT can only generate C structs which can either be used with OCI programs or with the Pro*C precompiler programs.

OCI Support for Oracle Advanced Queueing

The OCI provides an interface to Oracle's Advanced Queueing (AQ) feature. Oracle AQ provides message queuing as an integrated part of the Oracle server. Oracle AQ provides this functionality by integrating the queuing system with the database, thereby creating a message-enabled database. By providing an integrated solution Oracle AQ frees application developers to devote their efforts to their specific business logic rather than having to construct a messaging infrastructure.

For more information about the OCI advanced queueing features, refer to "OCI and Advanced Queuing".

Simplified Migration of Existing Applications

The OCI has been significantly improved with many features. Applications written to work with Oracle OCI release 7 have a smooth migration path to Oracle OCI release 8i due to the interoperability of Oracle OCI release 7 client with Oracle8i and Oracle OCI release 8i client with Oracle7 database server. Specifically:

• Applications that use Oracle OCI release 7.3 work unchanged against Oracle8i.

• Applications that use Oracle OCI release 8i work against an Oracle7 server provided they do not use any of the new capabilities of the OCI or the server.

• Oracle OCI release 7 and Oracle OCI release 8i calls can be mixed in the same application and in the same transaction provided they are not mixed within the statement.

As a result, customers migrating an existing Oracle OCI release 7 application have the following three alternatives:

• Retain Oracle7 OCI client: Customers can retain their Oracle7 OCI applications without making any modifications - they will continue to work against an Oracle8i server.

• Upgrade to Oracle8i OCI client but do not modify application: Customers who choose to upgrade from a Oracle7 OCI client to Oracle8i OCI client need only relink the new version of OCI library and need NOT recompile their application. Relinked Oracle7 OCI applications work unchanged against an Oracle8i server.

• Upgrade to Oracle8i OCI client and modify application: To avail themselves of the performance and scalability benefits provided by the new OCI, however, customers will need to modify their existing applications to use the new OCI programming paradigm, relink them with the new OCI library and run them against an Oracle8i server.

Further, if application developers need to use any of the object capabilities of the Oracle8i server, they will need to upgrade their client to use Oracle8i OCI.

Compatibility, Upgrading, and Migration

The OCI release 8i provides support for applications written with either the 7.x OCI and the 8.x OCI. This section discusses changes in the OCI library routines, issues concerning compatibility between different versions of the OCI and server, as well as issues involved in migrating an application from the release 7.x OCI to the 8.x OCI.

Note: For the most recently updated information about compatibility, upgrading, and migration, refer to the Oracle8i Migration manual.

Obsolescent OCI Routines

Release 8.0 of the Oracle Call Interface introduced an entirely new set of functions which were not available in release 7.3. Release 8i adds more new functions. The earlier 7.x calls are still available, but Oracle strongly recommends that existing applications use the new calls to improve performance and provide increased functionality.

Table 1-1, "Obsolescent OCI Routines" lists the 7.x OCI calls with their release 8i equivalents. For more information about the Oracle OCI calls, see the function descriptions in Part III of this guide. For more information about the 7.x calls, see the Programmer's Guide to the Oracle Call Interface, Release 7.3. These 7.x calls are obsoleted, meaning that OCI has replaced them with newer calls. While the obsoleted calls are supported at this time, they may not be supported in all future versions of the OCI.

Note: In many cases the new OCI routines do not map directly onto the 7.x routines, so it may not be possible to simply replace one function call and parameter list with another. Additional program logic may be required before or after the new call is made. See the remaining chapters of this guide for more information.

Table 1-1 Obsolescent OCI Routines

7.x OCI Routine	Equivalent or Similar 8.x Oracle OCI Routine
obindps(), obndra(), obndrn(), obndrv()	OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)
obreak()	OCIBreak()
ocan()	none
oclose()	Note: cursors are not used in Release 8i
ocof(), ocon()	OCIStmtExecute() with OCI_COMMIT_ON_SUCCESS mode
ocom()	OCITransCommit()
odefin(), odefinps()	OCIDefineByPos() (Note: additional define calls may be necessary for some data types)
odescr()	Note: schema objects are described with OCIDescribeAny(). A describe, as used in release 7.x, will most often be done by calling OCIAttrGet() on the statement handle after SQL statement execution.
odessp()	OCIDescribeAny()
oerhms()	OCIErrorGet()
oexec(), oexn()	OCIStmtExecute()
oexfet()	OCIStmtExecute(), OCIStmtFetch() (Note: result set rows can be implicitly prefetched)
ofen(), ofetch()	OCIStmtFetch()
oflng()	none
ogetpi()	OCIStmtGetPieceInfo()
olog()	OCILogon()
ologof()	OCILogoff()
onbclr(), onbset(), onbtst()	Note: non-blocking mode can be set or checked by calling OCIAttrSet() or OCIAttrGet() on the server context handle or service context handle
oopen()	Note: cursors are not used in Release 8i
oopt()	none
oparse()	OCIStmtPrepare(); however, it is all local
opinit()	OCIInitialize()
orol()	OCITransRollback()
osetpi()	OCIStmtSetPieceInfo()
sqlld2()	SQLSvcCtxGet or SQLEnvGet
sqllda()	SQLSvcCtxGet or SQLEnvGet
odsc()	Note: see odescr() above
oermsg()	OCIErrorGet()
olon()	OCILogon()
orlon()	OCILogon()
oname()	Note: see odescr() above
osql3()	Note: see oparse() above

See Also: For information about the additional functionality provided by new functions not listed here, see the remaining chapters of this guide.

OCI Routines Not Supported

Some OCI routines that were available in previous versions of the OCI are not supported in Oracle8i. They are listed in Table 1-2, "OCI Routines Not Supported"

Table 1-2 OCI Routines Not Supported

OCI Routine	Equivalent or Similar 8.x Oracle OCI Routine
obind()	OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)
obindn()	OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)
odfinn()	OCIDefineByPos() (Note: additional define calls may be necessary for some data types)
odsrbn()	Note: see odescr() in Table 1-1
ologon()	OCILogon()
osql()	Note: see oparse() Table 1-1

:

Compatibility

This section addresses compatibility between different versions of the OCI and Oracle server.

7.x Applications

Existing 7.x applications with no new release 8.x OCI calls have two choices:

• do not relink the application

• relink with the new 8.x OCI library

In either case, the application will work against both Oracle7 and Oracle8i. The application will not be able to use the object features of Oracle8i, and will not get any of the performance or scalability benefits provided by the Oracle OCI release 8i.

Oracle8 Applications

New applications written completely in the Oracle OCI will work seamlessly against both Oracle7 and Oracle8i with the following exceptions:

• Against Oracle7 servers, none of Oracle's object features are supported, and the following datatypes are not supported:
  • SQLT_NTY - named data type

  • SQLT_REF - reference to named data type in host language representation.

  • SQLT_CLOB - a character LOB data type.

  • SQLT_BLOB - a binary LOB data type.

  • SQLT_NCLOB - a national character set LOB data type.

  • SQLT_NCHAR - fixed or varying national character set datatype.

  • SQLT_BFILE - a binary FILE LOB data type.

  • SQLT_RSET - result set data type.

• Against Oracle7 Servers, the following calls or features are not supported, or are supported with restrictions:

  Table 1-3 Oracle OCI Release 8i Restrictions When Running Against Oracle7 Servers

  Function	Restrictions
  OCIBindObject()	not supported
  OCIPasswordChange()	not supported
  OCIDefineObject()	not supported
  OCIDescribeAny()	only supports description of select lists or stored procedures
  OCIErrorGet()	only a subset of Oracle error codes can be returned
  OCIStmtFetch()	prefetching options not supported
  OCILob*() calls	LOB/FILE calls are not supported
  OCIAttrSet()	setting NCHAR attributes not supported
  OCIAttrGet()	getting NCHAR attributes not supported

Upgrading

Programmers who wish to incorporate new release 8i functionality into existing OCI applications have two options:

• Completely rewrite the application to use only new OCI calls (recommended)

• Incorporate new Oracle OCI release 8i calls into the application, while still using 7.x calls for some operations.

This manual should provide the information necessary to rewrite an existing application to use only new OCI calls.

Adding 8i Oracle OCI Calls to 7.x Applications

The following guidelines apply to programmers who want to incorporate new Oracle datatypes and features by using new OCI calls, while keeping 7.x calls for some operations:

• Change the existing logon to use OCILogon instead of olog() (or other logon call). The service context handle can be used with new OCI calls or can be converted into a Lda_Def to be used with 7.x OCI calls.

  Note: See the description of OCIServerAttach() and the description of OCISessionBegin() for information about the logon calls necessary for applications which are maintaining multiple sessions.

• After the server context handle has been initialized, it can be used with Oracle OCI release 8i calls.

• To use Oracle7 OCI calls, convert the server context handle to an Lda_Def using OCISvcCtxToLda(), and pass the resulting Lda_Def to the 7.x calls.

  Note: If there are multiple service contexts which share the same server handle, only one can be in Oracle7 mode at any time.

• To begin using 8i Oracle OCI calls again, the application must convert the Lda_Def back to a server context handle using OCILdaToSvcCtx().

• The application may toggle between the Lda_Def and server context as often as necessary in the application.

This approach allows an application to use a single connection, but two different APIs, to accomplish different tasks.

You can mix and match OCI 7.x and OCI 8i calls within a transaction, but not within a statement. This allows you to execute one SQL or PL/SQL statement with OCI 7.x calls and the next SQL or PL/SQL statement within that transaction with Oracle8i OCI calls.

Warning: You can not open a cursor, and parse with OCI 7.x calls and then execute the statement with OCI 8i calls.

Application Linking Issues

This section discusses issues related to application linking, including the use of non-deferred linking and single-task linking with various OCI versions.

Non-deferred linking

Application developers are cautioned that Oracle plans to desupport non-deferred mode linking beginning with a future release of Oracle. It will continue to be supported with all the releases of Oracle8i. Recognizing these plans, application developers should no longer use non-deferred mode linking in developing new applications. Version 7.3 of the OCI supports two linking modes:

• Non-deferred linking: The Oracle OCI version 6 (client) only supported non-deferred linking which meant that for each SQL statement, a parse, a bind and a define call were each executed separately with individual round trips between the client and the server. This significantly increased network traffic between the client and the server and reduced both the performance and scalability of OCI applications.

• Deferred linking: Unlike the Oracle OCI version 6, the Oracle7 OCI supports both non-deferred linking and deferred linking. Deferred mode linking essentially defers the bind and define steps until the statement executes - that is it automatically bundles and defers the bind and define calls to execution time. Further, when the application is linked with deferred mode and a special parsing call is used (the OPARSE call with the DEFFLG set to a non-zero value), even the parse call can be deferred to execution time. Note that deferred mode linking does not depend on the specific OCI calls that the application uses, only on the link option that is selected.

Deferred mode linking therefore significantly reduces the number of round trips between the client and the server and as a result improves the performance and scalability of OCI applications. The default behavior of Oracle7 OCI connected to the Oracle7 server is deferred mode linking. However, Oracle7 OCI also supports non-deferred linking by setting specific link time options.

All the Oracle7 OCI calls are supported with Oracle8i OCI. This means that they will work with a Oracle8i OCI client by relinking the release 8i OCI libraries.The default mode with these calls continues to be deferred mode linking; however, non-deferred mode linking is supported for these calls through all releases of Oracle8i by setting link time options. However, Oracle8i-specific calls use a different paradigm and as a result non-deferred mode linking is not necessary.

The various combinations of client-side libraries and server with which non-deferred linking is currently supported are summarized in the following table:

Table 1-4 Supported Linking Modes for Various Client and Server Versions

Client	Oracle 6.x OCI	Oracle 7.x OCI	Oracle 8.x OCI (7.x calls)	Oracle 8.x OCI (8.x calls)	Oracle 9.x OCI
Server
Oracle9	Not supported	Default: deferred Non-deferred supported	Default: deferred Non-deferred supported	Not supported	Not supported
Oracle8	Not supported	Default: deferred Non-deferred supported	Default: deferred Non-deferred supported	Not supported	Not supported
Oracle7	Non-deferred mode only	Default: deferred Non-deferred supported	Default: deferred Non-deferred supported	Not supported	Not supported
Oracle6	Non-deferred mode only	Default: deferred Non-deferred supported	Not supported	Not supported	Not supported

Oracle will continue to support deferred-mode linking with all the releases of Oracle8i. This has varying implications depending on the version of the OCI library that is used.

Applications using Oracle OCI Version 6 libraries

Because the Oracle OCI 6.x library is not supported against Oracle8i, applications using the Oracle OCI 6.x library cannot be run against Oracle8i.

Applications using Oracle7 OCI libraries

Applications using Oracle7 OCI libraries can run in two configurations against an Oracle8i database:

• They can be run with Oracle 7.x OCI libraries against an Oracle8i database in non-deferred mode provided link time options are set appropriately.

• They can also be relinked with the Oracle 8i OCI libraries and run in non-deferred mode provided link time options are set appropriately. Oracle will support the first configuration through all the releases of Oracle8i. However, the second configuration will not be supported in release 9 of Oracle. Therefore, applications that require non-deferred linking will not be able to upgrade to Oracle 9.x client-side libraries.

Applications using Oracle OCI release 8i libraries

Applications using Oracle release 8i OCI calls, such as those used to access Oracle's object types, do not need to use non-deferred mode linking since the Oracle OCI release 8i uses a different paradigm. Applications using only Oracle7 OCI calls will be able to use non-deferred mode linking but only through release 8.1

Single-task linking

Single-task linking is a feature used by a limited number of Oracle's customers, primarily on the OpenVMS platform. Some Oracle platforms support single-task linking, others no longer support it. Application developers are cautioned that Oracle will desupport single task on ALL platforms beginning with the first server release after Oracle8i. Oracle will continue to support single-task linking for all Oracle 8.x releases on those platforms that do support it today. Application developers are referred to the product-line specific documentation to determine whether or not their platform supports single-task linking today.

With single-task linking, Oracle supports two configurations to link Oracle products and user-written applications against the Oracle database:

• Single-task linking: In this case, applications are directly linked against the Oracle shareable image making single-task connection to Oracle.

• Two-task linking: In this case, applications linked in a standalone configuration can only connect to Oracle using Net8's two task drivers such as Net8 DECnet or Net8 VMS Mailbox on the OpenVMS platform. This is the typical configuration used in the large majority of client-server applications. With two task linking applications and tools connect with the Oracle7 database through a programmatic interface that creates a shadow process for each user connection. This shadow process runs a copy of the Oracle shareable image on behalf of the user process using Net8 protocols to communicate between the user and shadow processes. Therefore, with this interface, user routines that invoke the Oracle7 Server functions run as one process or task, and the Oracle7 routines that execute these functions run as the second task.

Oracle will continue to support single-task linking with all the releases of the Oracle server (all 8.* releases) but will desupport it beginning with the first release after Oracle8i. Application developers who would like to use single-task linking to run their applications will not be able to do so against the first server release after Oracle8i.

---