| Oracle® C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10778-01 |
|
|
View PDF |
| Oracle® C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10778-01 |
|
|
View PDF |
This chapter provides an overview of Oracle C++ Call Interface (OCCI) and introduces terminology used in discussing OCCI. You are provided with the background information needed to develop C++ applications that run in an Oracle environment.
This chapter contains these topics:
Oracle C++ Call Interface (OCCI) is an Application Programming Interface (API) that provides C++ applications access to data in an Oracle database. OCCI enables C++ programmers to utilize the full range of Oracle database operations, including SQL statement processing and object manipulation.
OCCI provides for:
High performance applications through the efficient use of system memory and network connectivity
Scalable applications that can service an increasing number of users and requests
Comprehensive support for application development by using Oracle database objects, including client-side access to Oracle database objects
Simplified user authentication and password management
n-tiered authentication
Consistent interfaces for dynamic connection management and transaction management in two-tier client/server environments or multitiered environments
Encapsulated and opaque interfaces
OCCI provides a library of standard database access and retrieval functions in the form of a dynamic runtime library (OCCI classes) that can be linked in a C++ application at runtime. This eliminates the need to embed SQL or PL/SQL within third-generation language (3GL) programs.
OCCI provides these significant advantages over other methods of accessing an Oracle database:
Leverages C++ and the Object Oriented Programming paradigm
Is easy to use
Is easy to learn for those familiar with JDBC
Has a navigational interface to manipulate database objects of user-defined types as C++ class instances
As Figure 1-1 shows, you compile and link an OCCI program in the same way that you compile and link a nondatabase application.
Oracle supports most popular third-party compilers. The details of linking an OCCI program vary from system to system. On some platforms, it may be necessary to include other libraries, in addition to the OCCI library, to properly link your OCCI programs.
OCCI provides the following functionality:
APIs to design a scalable, multithreaded applications 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
Advanced Queuing for message management
XA compliance for distributed transaction support
Statement caching of SQL and PL/SQL queries
Connection pooling for managing multiple connections
Globalization and Unicode support to customize applications for international and regional language requirement
Oracle C++ Call Interface (OCCI) enables you to develop scalable, multithreaded applications on multitiered architectures that combine nonprocedural data access power of structured query language (SQL) with the procedural capabilities of C++.
In a nonprocedural 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 nonprocedural nature of SQL makes it an easy language to learn and 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 nonprocedural and procedural language elements in an OCCI program provides easy access to an Oracle database in a structured programming environment.
OCCI supports all SQL data definition, data manipulation, query, and transaction control facilities that are available through an Oracle database server. For example, an OCCI program can run a query against an Oracle database. The queries can require the program to supply data to the database by using input (bind) variables, as follows:
SELECT name FROM employees WHERE empno = :empnumber
In this SQL statement, empnumber is a placeholder for a value that will be supplied by the application.
In an OCCI 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. OCCI also provides facilities for accessing and manipulating objects in an Oracle database server.
The Instant Client feature makes it extremely easy and fast to deploy OCCI based customer application by eliminating the need for ORACLE_HOME. The storage space requirements are an additional benefit; Instant Client shared libraries occupy about one-fourth of the disk space required for a full client installation.
Installation involves copying only four files.
Storage space requirement for the client is minimal
No loss of functionality or performance exists for deployed applications
Simplified packaging with ISV applicaitons
The OCCI Instant Client capability simplifies OCCI installation. Even though OCCI is independent of ORACLE_HOME setting in the Instant Client mode, applications that rely on ORACLE_HOME settings can continue operation by setting it to the appropriate value. The activation of the Instant Client mode is only dependent on the ability to load the Instant Client data shared library. In particular, this feature allows interoperability with Oracle applications that use ORACLE_HOME for their data, but use a newer release of OCCI. Other components such as shared libraries for network protocols, or security options, must be installed separately.
OCCI requires only four shared libraries (or dynamic link libraries, as they are called on some operating systems) to be loaded by the dynamic loader of the operating system:
OCI Shared Library (libociei.so on Solaris and oraociei10.dll on Windows); correct installation of this file determines if you are operating in Instant Client mode
Client Code Library (libclnstsh.so.10.1 on Solaris and oci.dll on Windows)
Security Library (libnnz10.so on Solaris and orannzsbb10.dll on Windows)
OCCI Library (libocci.so.10.1 on Solaris and oraocci10.dll on Windows)
If you performed a complete client installation by choosing the Admin option,
On Solaris, the libociei.so library can be copied from the $ORACLE_HOME/instantclient directory. All the other Solaris libraries can be copied from the $ORACLE_HOME/lib directory in a full Oracle installation.
On Windows, the oraociei10.dll library can be copied from the ORACLE_HOME\instantclient directory. All other Windows libraries can be copied from the ORACLE_HOME\bin directory.
If you did not install the database, you can retrieve these libraries by choosing the Instant Client option from the Oracle Universal Installer.
The Instant Client libraries are also available on the Oracle Technology Network (OTN) website at http://otn.oracle.com/tech/oci/occi/index.html.
If these four libraries are accessible through the directory on the OS Library Path variable (LD_LIBRARY_PATH on Solaris and PATH on Windows), then OCCI operates in the Instant Client mode. In this mode, there is no dependency on ORACLE_HOME and none of the other code and data files provided in ORACLE_HOME are needed by OCCI (except for the tnsnames.ora file as described later).
|
Note:
|
The Instant Client feature is designed for running production applications. For development, a full installation is necessary to access OCCI header files, Makefiles, demonstration programs, and so on. In general, all OCCI functionality is available to an application being run in the Instant Client mode, except for server-side external procedures.
Because Instant Client is a deployment feature, one of its design objectives is to reducing the number and size of necessary files. Therefore, Instant Client deployment does not include all files for patching shared libraries. You should use the OPATCH utility on an ORACLE_HOME based full client to patch the Instant Client shared libraries.
After successfully patching Instant Client shared libraries, we recommend that you generate the patch inventory information in ORACLE_HOME:
opatch lsinventory > opatchinv.out
This opatchinv.out file contains the record of all patches made, and should be copied to the deployment directory, together with the patched Instant Client libraries.
This feature is not available on Windows platforms.
The Instant Client Data Shared Library, libociei.so, can be regenerated in an Administrator Install of ORACLE_HOME. Executing the following two lines will create a new libociei.so file based on current file in ORACLE_HOME and place it in the ORACLE_HOME/instantclient directory:
cd $ORACLE_HOME/rdbms/lib make -f ins_rdbms.mk ilibociei
All Oracle net naming methods that do not require use of ORACLE_HOME or TNS_ADMIN (to locate configuration files such as tnsnames.ora or sqlnet.ora) work in the Instant Client mode. In particular, the connect string in the OCIServerAttach() call can be specified in the following formats:
A SQL Connect URL string of the form:
//host:[port][/service name]
such as:
//myserver111:5521/bjava21
As an Oracle Net keyword-value pair. For example:
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myserver111) (PORT=5521)) (CONNECT_DATA=(SERVICE_NAME=bjava21)))
Naming methods that require TNS_ADMIN to locate configuration files continue to work if the TNS_ADMIN environment variable is set.
If the TNS_ADMIN environment variable is not set, and TNSNAMES entries such as inst1 are used, then the ORACLE_HOME variable must be set and the configuration files are expected to be in the $ORACLE_HOME/network.101/admin directory.
The ORACLE_HOME variable in this case is only used for locating Oracle Net configuration files, and no other component of OCCI Client Code Library uses the value of ORACLE_HOME.
The bequeath adapter or the empty connect strings are not supported. However, an alternate way to use the empty connect string is to set the TWO_TASK environment variable on Solaris, or the LOCAL variable on Windows, to either a tnsnames.ora entry or an Oracle Net keyword-value pair. If TWO_TASK or LOCAL is set to a tnsnames.ora entry, then the tnsnames.ora file must be able to be loaded by TNS_ADMIN or ORACLE_HOME setting.
The ORACLE_HOME environment variable no longer determines the location of Globalization Support, CORE, and error message files. An OCCI-only application should not require ORACLE_HOME to be set. However, if it is set, it does not have an impact on OCCI's operation. OCCI will always obtain its data from the Data Shared Library. If the Data Shared Library is not available, only then is ORACLE_HOME used and a full client installation is assumed. When set, ORACLE_HOME should be a valid operating system path name that identifies a directory.
If Dynamic User callback libraries are to be loaded, then as this guide specifies, the callback package has to reside in ORACLE_HOME/lib on Solaris or ORACLE_HOME\bin on Windows. Therefore, ORACLE_HOME should be set in this case.
Environment variables ORA_NLS33, ORA_NLS32, and ORA_NLS are ignored in the Instant Client mode.
In the Instant Client mode, if the ORA_TZFILE variable is not set, then the smaller, default, timezone.dat file from the Data Shared Library is used. If the larger timezlrg.dat file is to be used from the Data Shared Library, then set the ORA_TZFILE environment variable to the name of the file without any absolute or relative path names. That is, on Solaris:
setenv ORA_TZFILE timezlrg.dat
On Windows:
set ORA_TZFILE timezlrg.dat
If OCCI is not operating in the Instant Client mode because the Data Shared Library is not available, the ORA_TZFILE variable, if set, names a complete path name.
If TNSNAMES entries are used, then TNS_ADMIN directory must contain the TNSNAMES configuration files. If TNS_ADMIN is not set, the ORACLE_HOME/network.101/admin directory must contain Oracle Net Services configuration files.
One of the main tasks of an OCCI 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 OCCI application. Oracle recognizes several types of SQL statements:
Data definition language (DDL) statements
Control statements
Transaction control statements
Connection control statements
System control statements
Data manipulation language (DML) statements
Queries
DDL statements manage schema objects in the database. These 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, as in the following series of statements which create 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
OCCI applications treat transaction control, connection control, and system control statements like DML statements.
DML statements can change data in database tables. For example, DML statements are used to perform the following actions:
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 by using input (bind) variables. Consider the following statement:
INSERT INTO dept_tab VALUES(:1,:2,:3)
Either this statement can be executed several times with different bind values, or an array insert can be performed to insert several rows in one round-trip to the server.
DML statements also enable you to work with objects in the Oracle database, 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 are statements that retrieve data from tables in 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 can require the program to supply data to the database server by using input (bind) variables, as in the following example:
SELECT name FROM employees WHERE empno = :empnumber
In this SQL statement, empnumber is a placeholder for a value that will be supplied by the application.
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 the following constructs:
One or more SQL statements
Variable declarations
Assignment statements
Procedural control statements (IF ... THEN ... ELSE statements and loops)
Exception handling
In addition to calling PL/SQL stored procedures from an OCCI program, you can use PL/SQL blocks in your OCCI program to perform the following tasks:
Call other PL/SQL 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
A PL/SQL procedure or function can also return an output variable. This is called an out bind variable. For example:
BEGIN GET_EMPLOYEE_NAME(:1, :2); END;
Here, the first parameter is an input variable that provides the ID number of an employee. The second parameter, or the out bind variable, contains the return value of employee name.
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.
SELECT ename, sal, comm INTO :emp_name, :salary, :commission FROM emp WHERE ename = :emp_number;
Note that the placeholders in this statement are not PL/SQL variables. They represent input and output parameters passed to and from the database server when the statement is processed. These placeholders need to be specified in your program.
This guide uses special terms to refer to the different parts of a SQL statement. Consider the following example of a SQL statement:
SELECT customer, address FROM customers WHERE bus_type = 'SOFTWARE' AND sales_volume = :sales;
This example contains these 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 (bind) variable in the WHERE clause: :sales
When you develop your OCCI application, you call routines that specify to the database server the value of, or reference to, input and output variables in your program. In this guide, specifying the placeholder variable for data is called a bind operation. For input variables, this is called an in bind operation. For output variables, this is called an out bind operation.
OCCI 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 type might have attributes, such as 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. By 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, or programmatic functions that represent the behavior of that object type.
OCCI provides a comprehensive API for programmers seeking to use the Oracle database server's object capabilities. These features can be divided into several major categories:
Client-side object cache
Runtime environment for objects
Associative and navigational interfaces to access and manipulate objects
Metadata class to describe object type metadata
Object Type Translator (OTT) utility, which maps internal Oracle schema information to client-side language bind variables
|
See Also:
|
The object cache is a client-side memory buffer that provides lookup and memory management support for objects. It stores and tracks objects which have been fetched by an OCCI application from the server to the client side. The client-side object cache is created when the OCCI environment is initialized in object mode. Multiple applications running against the same server will each have their own object cache. The client-side object cache tracks the objects that are currently in memory, maintains references to objects, manages automatic object swapping and tracks the meta-attributes or type information about objects. The client-side object cache provides the following benefits:
Improved application performance by reducing the number of client/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
Automatic garbage collection when cache thresholds are exceeded
OCCI provides a runtime environment for objects that offers a set of methods for managing how Oracle objects are used on the client side. These methods provide the necessary functionality for performing these tasks:
Connecting to an Oracle database server in order to access its object functionality
Allocating the client-side object cache and tuning its parameters
Retrieving error and warning messages
Controlling transactions that access objects in the database
Associatively accessing objects through SQL
Describing a PL/SQL procedure or function whose parameters or result are of Oracle object type system types
Applications that use OCCI can access objects in the database through several types of interfaces:
SQL SELECT, INSERT, and UPDATE statements
C++ pointers and references to access objects in the client-side object cache by traversing the corresponding references
OCCI provides a set of methods to support object manipulation by 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. OCCI provides methods to access objects by using SQL statements for:
Binding object type instances and references as input and output variables of SQL statements and PL/SQL stored procedures
Executing SQL statements that contain object type instances and references
Fetching object type instances and references
Retrieving column values from a result set as objects
Describing a select-list item of an Oracle object type
OCCI provides a seamless interface for navigating objects, enabling you to manipulate database objects in the same way that you would operate on transient C++ objects. You can dereference the overloaded arrow (->) operator on an object reference to transparently materialize the object from the database into the application space.
Each Oracle datatype is represented in OCCI by a C++ class. The class exposes the behavior and characteristics of the datatype by overloaded operators and methods. For example, the Oracle datatype NUMBER is represented by the Number class.
OCCI provides a metadata class that enables you to retrieve metadata describing database objects, including object types.
The Object Type Translator (OTT) utility translates schema information about Oracle object types into client-side language bindings. That is, OTT translates object type information into declarations of host language variables, such as structures and classes. OTT takes an intype file which contains information about Oracle database schema objects as input. OTT 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. OTT has many benefits, including:
Improving application developer productivity OTT eliminates the need for application developers to write by hand the host language variables that correspond to schema objects.
Maintaining SQL as the data definition language of choice By providing the ability to automatically map Oracle database schema objects that are created by using SQL to host language variables, OTT facilitates the use of SQL as the data definition language of choice. This in turn allows Oracle to support a consistent, enterprise-wide model of the user's data.
Facilitating schema evolution of object types OTT provides the ability to regenerate included header 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.
In summary, OCCI supports object handling in an Oracle database by:
Execution of SQL statements that manipulate object data and schema information
Passing object references and instances as input variables in SQL statements
Declaring object references and instances as variables to receive the output of SQL statements
Fetching object references and instances from a database
Describing properties of SQL statements that return object instances and references
Describing PL/SQL procedures or functions with object parameters or results
Extending commit and rollback calls to synchronize object and relational functionality
Advanced queuing of objects
|
 Copyright © 1999, 2003 Oracle Corporation All Rights Reserved. |
|