Introduction to OCCI

20/02/2011

UNIX and Oracle Akhil Agarwal akhil.ag@tcs.com

INTRODUCTION TO OCCI

Contents
1. Introduction to OCCI .......................................................................................... 3 2. Benefits of OCCI .................................................................................................. 3 3. Processing of SQL Statements........................................................................... 3 4. Building an OCCI Application ............................................................................ 4 5. OCCI Compiling an OCCI Application ............................................................. 4 6. OCCI Environment Class..................................................................................... 4 7. OCCI Initialize Environment Example.......................................................... 5 8. OCCI Connection Class ....................................................................................... 5 9. OCCI Create Connection Example................................................................ 5 10. OCCI Executing SQL/PLSQL........................................................................... 6 11. OCCI Executing SQL Usage ......................................................................... 6 12. OCCI Executing SQL Examples ................................................................... 6 Simple DML Insert ........................................................................................................................... 6 DML Insert with bind...................................................................................................................... 6 Executing Select queries and fetching results ..................................................................... 7 13. OCCI Control classes ...................................................................................... 8 14. OCCI DML on multiple rows using Iterations............................................... 8 DML(INSERT/UPDATE/DELETE) of multiple rows in single roundtrip.......................... 8 15. OCCI Error Handling ...................................................................................... 9 Example - Handling Oracle and C++ STL errors separately............................................. 9 16. References......................................................................................................... 9

INTRODUCTION TO OCCI

1. Introduction to OCCI
OCCI stands for Oracle C++ Call Interface. OCCI is an API that provides C++ applications access and retrieve data from an Oracle database. OCCI enables C++ programmers to utilize the full range of Oracle database operations, including SQL statement processing and object manipulation. Introduced in 9i, growing customer base

2. Benefits of OCCI
Easy to learn and use. Based on Standard C++ and object oriented design. Continuing enhancements by Oracle to add more features.

3. Processing of SQL Statements

One of the main tasks of an OCCI application is to process SQL statements. Oracle recognizes several types of SQL statements: Data definition language (DDL) statements Control statements Data manipulation language (DML) statements Queries

INTRODUCTION TO OCCI

4. Building an OCCI Application

5. OCCI Compiling an OCCI Application

CC I<OCCI include DIR> -L<OCCI lib DIR> -locci -lclntsh lnnz10 test.cpp

6. OCCI Environment Class

An OCCI application is initialized by creating an Environment class instance. The Environment is the base for creating connections for further database access The Environment class provides an OCCI environment to manage memory and other resources for OCCI objects. To create an Environment call createEnvironment static method. To terminate an Environment call terminateEnvironment static method.

INTRODUCTION TO OCCI

7. OCCI Initialize Environment Example

//include 1 header file for all OCCI classes/interfaces #include <occi.h>

//create Environment Environment *env = Environment::createEnvironment(); //use the Environment instance to create connections, //database access

//terminate Environment by calling static method //Environment::terminateEnvironment Environment::terminateEnvironment(env);

8. OCCI Connection Class

A user connection with a specific database is represented by a Connection class instance Use the Connection object to access data, execute SQL commands To create a connection call Environment::createConnection. - Connection *Environment::createConnection( const string &userName, const string &password, const string &connectString); //db name/TNS alias

To end connection call Environment::terminateConnection. - Environment::terminateEnvironment(Connection *conn);

9. OCCI Create Connection Example

//First need Environment Environment *env = Environment::createEnvironment(); Connection *conn=env->createConnection(scott,tiger,); ..//database access use the Connection object .. .. //logoff and terminate connection env->terminateConnection(conn);

INTRODUCTION TO OCCI

10. OCCI Executing SQL/PLSQL

Execute DDL/DML statements, SELECT queries, PL/SQL blocks and retrieve results Statement class for preparing & executing SQL/PLSQL statements, getting PL/SQL OUT results ResultSet class for fetching SELECT query results Uniform interface for binding and getting values of all data types - setXXX methods of Statement - getXXX methods of Statement & ResultSet Data type conversions automatically handled by OCCI

11. OCCI Executing SQL Usage

Create a Statement object with Connection::createStatement() Specify SQL command(DDL/DML/query) as argument to :Statement * Connection::createStatement(string &sql); Statement::setSQL(string &sql); Statement::execute(string &sql); - can be used for any SQL, returns status Statement::executeUpdate(string &sql); - returns Insert/Update/Delete count Statement::executeQuery(string &sql); - returns ResultSet Use setXXX methods of Statement to pass input bind values Execute the SQL statement using one of the execute methods of Statement For SELECT queries, fetch the results using ResultSet class object

12. OCCI Executing SQL Examples

Simple DML Insert //createStatement() on Connection class gives a Statement //instance Statement *stmt = conn->createStatement( insert into Dept(Deptno,Dname, Loc) values (1, ACCOUNTS, ZONE1 ); //executeUpdate for all INSERT/UPDATE/DELETE stmt->executeUpdate(); conn->terminateStatement(stmt);

DML Insert with bind Statement *stmt = conn->createStatement( insert into Emp(EmpNo,Ename) values(:1, :2) );

INTRODUCTION TO OCCI

//1 and 2 are bind placeholders int empno = 2; string empname = JOHN W; //first parameter is bind position, second is value stmt->setInt(1, empno); stmt->setString(2, empname); stmt->executeUpdate(); conn->terminateStatement(stmt);

Executing Select queries and fetching results Statement *stmt = conn->createStatement( select Empno, Ename, Sal from Emp where Hiredate >= :1);

//automatically converted to Date stmt->setString(1, 01-JAN-1987);

//executeQuery returns a ResultSet ResultSet *rs = stmt->executeQuery();

//ResultSet::next fetches rows and returns FALSE //when no more rows while (rs->next() == true) { //get values using the getXXX methods of ResultSet empno = rs->getInt(1); empname = rs->getString(2); empsalary = rs->getFloat(3); } stmt->closeResultSet(rs);//to free resources

INTRODUCTION TO OCCI

13. OCCI Control classes

Environment

Create

Connection

Create

Statement

Execute

ResultSet

14. OCCI DML on multiple rows using Iterations

DML(INSERT/UPDATE/DELETE) of multiple rows in single roundtrip Statement *stmt = conn->createStatement(insert into emp (empno, ename) values (:1, :2)); //specify max iterations stmt->setMaxIterations(10);//number of rows //specify maximum data size for types like string stmt->setMaxParamSize(2, 100); //set values and add iterations stmt->setInt(1, 1001); stmt->setString(2, JOHN);

INTRODUCTION TO OCCI

stmt->addIteration(); stmt->setInt(1, 1002); stmt->setString(2, JOE); stmt->addIteration(); //repeat iterations,do not call addIteration after last set stmt->executeUpdate();//will insert 10 rows in single trip

15. OCCI Error Handling

OCCI uses C++ exception mechanism to return all errors(in Oracle client/server or C++ STL) Applications should have a try-catch block to handle exceptions The exception object thrown is of SQLException class if error is in Oracle SQLException is derived from standard C++ exception class getErrorCode and getMessage methods of SQLException return Oracle error information

Example - Handling Oracle and C++ STL errors separately try { ResultSet *rs = stmt->executeQuery(); while (rs->next()) . } catch (SQLException &oraex) //Oracle/OCCI errors { int errno = oraex->getErrorCode();//returns the ORA number string errmsg = oraex->getMessage(); //more application error handling } catch (exception &ex) //any other C++/STL error { cout << Error << ex.what() << endl; }

16. References
Oracle C++ Call Interface Programmers Guide