F
Oracle8 OCI New Features

This chapter provides a detailed overview of the new features of the Oracle8 OCI. This information supplements that which is contained in Chapter 1, "Introduction and New Features". This chapter includes the following sections:

• Introduction
• Oracle8 OCI Enhancements
• Benefits of the OCI's New Features

Introduction

The Oracle Call Interface (OCI) is an application programming interface (API) that allows an application developer to use a third-generation language's native procedures or function calls to access the Oracle database server and control all phases of SQL statement execution. The OCI provides a library of standard database access and retrieval functions in the form of a dynamic runtime library, OCILIB, that can be linked in by the application. This eliminates the need to embed SQL or PL/SQL within 3GL programs. The OCI supports the datatypes, calling conventions, syntax and semantics of a number of third-generation languages including C, C++, COBOL and FORTRAN. Oracle is also planning to provide support for Java.

The Oracle Call Interface offers programmers the following key benefits:

• It provides the greatest degree of control over program execution.
• It allows them to use familiar 3GL programming techniques and application development tools such as browsers and debuggers.
• It supports dynamic SQL (method 4).
• It is available on the broadest range of platforms of all the Oracle Programmatic Interfaces.

Oracle8 OCI Enhancements

The Oracle8 OCI has many new features that can be broadly categorized in two 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 Oracle8 objects
• OCI support for Oracle Advanced Queueing

Encapsulated/Opaque Interfaces

All the data structures that are used by Oracle8 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 OCILIB 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 Oracle8 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 Oracle8 OCI provides application developers simplified user authentication and password management in two ways: (i) it provides the ability for a single OCI application to authenticate and maintain multiple users, and (ii) 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 Oracle8 OCI supports two types of login sessions:

• It provides a simplified login function for sessions where a single user connects to the database using a login name and password.
• It supports a setup in which a single OCI application authenticates and maintains multiple sessions by separating the login session (the session created when a user logs into an Oracle database) from the user sessions (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. Oracle8 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 Oracle8 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
• Implicit prefetching of SELECT statement result sets to eliminate the describe round trip
• Elimination of open and close cursor round trips
• Improved support for multi-threaded environments

Consistent Interface for Transaction Management

The Oracle8 OCI supports several improvements to provide a single unified interface for transaction management in a variety of configurations. Some of the major improvements are:

• 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 dblink connections and eliminating the need for separate sessions to be created for each branch of a global transaction
• Allowing clients to authenticate different users and allow transactions to be started on their behalf

Oracle8 OCI Object Support

The Oracle8 OCI provides the most comprehensive application programming interface for programmers seeking to use the Oracle8 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 Oracle8 types
• Object Type Translator utility, which maps internal Oracle8 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 Oracle8 OCI can access objects in the Oracle8 server through two types of interfaces - (i) Using SQL SELECT, INSERT, and UPDATE statements and (ii) Using a C-style "pointer chasing" scheme to access objects in the client-side cache by traversing the corresponding smart pointers or REFs

• The Oracle8 OCI provides a set of functions with extensions to support object manipulation using SQL SELECT, INSERT, and UPDATE statements.
• To access Oracle8 objects these SQL statements use a consistent set of steps as if they were accessing relational tables.
• The Oracle8 OCI provides the following four sets of functions required to access objects using SQL statements:
  • Binding/defining object type instances and references as input/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 Oracle8 object type
• The Oracle8 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 Oracle8 OCI provides a runtime environment for objects that offers a set of functions for managing how Oracle8 objects are used on the client-side. These functions provide the necessary functionality for:

• Connecting to an Oracle8 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 Oracle8 OCI provides two sets of functions to work with Oracle8 objects:

• Type Mapping functions allow applications to map attributes of an Oracle8 schema which are represented in the server as internal Oracle8 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 Oracle8 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 Oracle8 object types into client-side language bindings. That is, the Oracle8 OTT translates type information into declarations of host language variables (structures and classes). The OTT takes an "intype" file which contains metadata information about Oracle8 schema objects (an Oracle8 data dictionary) and generates an "outtype" file and the necessary header/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 Oracle8 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 Oracle8 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 Oracle8 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 Oracle8, 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 Oracle8's Advanced Queueing feature. Oracle AQ (Oracle Advanced Queueing) 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 Queueing" on page 7-40.

Benefits of the OCI's New Features

The enhancements to the new OCI provide several benefits:

• Comprehensive support for Oracle8 objects
• Improved application performance
• Greater scalability; Enhanced application extensibility
• Simplified migration of existing applications.

Each of these benefits is described below.

Comprehensive Support for Oracle8 Objects

As has been described above, the OCI provides the most comprehensive support for Oracle8 objects of all the programmatic interfaces and provides the most highly tunable interface to access, modify and manipulate Oracle8 object types on the client side. Further, the many tools and features of the OCI significantly enhance developer productivity when creating applications that use Oracle8 objects.

Improved Application Performance

The Oracle8 OCI facilitates improved application performance by reducing the number of client-to-server round trips in three ways.

• Since Oracle8 OCI does not fundamentally work around the concept of cursors, no calls are required to open and close cursors.
• The describe round trip is eliminated due to Oracle8 OCI's ability to implicitly prefetch SELECT statement result sets.
• Oracle8 OCI also reduces the number of client-server round trips when working with Oracle8 objects - (i) The Oracle8 OCI's use of a client-side cache allows applications to update multiple objects from the client to/from the server in a single round trip using a flush or refresh operation; (ii) Oracle8 OCI's complex object retrieval mechanism provides a transparent but configurable approach to prefetching connected objects from the server in a single round trip.

Greater Scalability

Applications written to use Oracle8 OCI will have greater scalability due to the Oracle8 OCI's reduced use of server side memory, its ability to pool concurrent transactions, and its improved support for multi-threaded environments.

• Oracle8 OCI's use of handles enables it to carry out more client-side processing and as a result reduce significantly the amount of state information that needs to be retained on the server. As a result, server side memory usage is significantly reduced and applications, therefore, scale better.
• The Oracle8 OCI allows multiple concurrent transactions to be a pooled on a single connection to the server. This substantially reduces the number of connections required between the client and the server. As a result, three tier architectures that use Oracle8 OCI scale well.

Simplified Migration of Existing Applications

The OCI has been significantly improved with many features, and applications written to work with Oracle7 OCI have a very smooth migration path to Oracle8 OCI due to the interoperability of the Oracle7 OCI (version7 client) with Oracle8 (server) and Oracle8 OCI (version 8 client) with Oracle7 (server). Specifically:

• Applications that use Oracle7 OCI work unchanged against the Oracle8 server (all release 7.3 OCI function calls work against the Oracle8 server).
• Applications that use Oracle8 OCI work against an Oracle7 server provided they do not use any of the object capabilities of the OCI or the server.
• Oracle7 OCI and Oracle8 OCI 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 Oracle7 OCI 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 Oracle8 server.
• Upgrade to Oracle8 OCI client but do not modify application: Customers who choose to upgrade from a Oracle7 OCI client to Oracle8 OCI client need only relink the new version of OCILIB and need NOT recompile their application. Relinked Oracle7 OCI applications work unchanged against an Oracle8 server.
• Upgrade to Oracle8 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 calls, relink them with the new OCILIB and run them against an Oracle8 server.

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

Enhanced Application Extensibility

All the data structures that are used by Oracle8 OCI are encapsulated in the form of opaque interfaces that are called handles. This encapsulation of the OCI's interfaces allows changes to be made to the underlying data structures without affecting applications. For example, some of the services that are currently provided by the database and externalized through the OCI's APIs could in the future be provided by an application server. By using the OCI's opaque handles applications will not need to change significantly if accessing these services from the application server - this facilitates application extensibility.

---