Oracle C++ Call Interface (OCCI) is a C++ API for manipulating data in an Oracle database. OCCI is organized as an easy-to-use set of C++ classes that enable a C++ program to connect to a database, run SQL statements, insert/update values in database tables, retrieve results of a query, run stored procedures in the database, and access metadata of database schema objects.

Oracle C++ Call Interface (OCCI) is designed so that you can use OCI and OCCI together to build applications.

The OCCI API provides the following advantages over JDBC and ODBC:

• OCCI encompasses more Oracle functionality than JDBC. OCCI provides all the functionality of OCI that JDBC does not provide.

• OCCI provides compiled performance. With compiled programs, the source code is written as close to the computer as possible. Because JDBC is an interpreted API, it cannot provide the performance of a compiled API. With an interpreted program, performance degrades as each line of code must be interpreted individually into code that is close to the computer.

• OCCI provides memory management with smart pointers. You do not have to be concerned about managing memory for OCCI objects. This results in robust higher performance application code.

• Navigational access of OCCI enables you to intuitively access objects and call methods. Changes to objects persist without writing corresponding SQL statements. If you use the client side cache, then the navigational interface performs better than the object interface.

• With respect to ODBC, the OCCI API is simpler to use. Because ODBC is built on the C language, OCCI has all the advantages C++ provides over C. Moreover, ODBC has a reputation as being difficult to learn. The OCCI, by contrast, is designed for ease of use.

You can use OCCI to perform random and piecewise operations on LOBs, which means that you specify the offset or amount of the operation to read or write a part of the LOB value.

OCCI provides these classes that allow you to use different types of LOB instances as objects in your C++ application:

• Clob class to access and modify data stored in persistent CLOBs and NCLOBs

• Blob class to access and modify data stored in persistent BLOBs

Clob Class

The Clob driver implements a CLOB object using an SQL LOB locator. This means that a CLOB object contains a logical pointer to the SQL CLOB data rather than the data itself.

The CLOB interface provides methods for getting the length of an SQL CLOB value, for materializing a CLOB value on the client, and getting a substring. Methods in the ResultSet and Statement interfaces such as getClob() and setClob() allow you to access SQL CLOB values.

Blob Class

Methods in the ResultSet and Statement interfaces, such as getBlob() and setBlob(), allow you to access SQL BLOB values. The Blob interface provides methods for getting the length of a SQL BLOB value, for materializing a BLOB value on the client, and for extracting a part of the BLOB.

Fixed-Width Character Set Rules

In OCCI, for fixed-width client-side character sets, these rules apply:

• Clob: offset and amount parameters are always in characters

• Blob: offset and amount parameters are always in bytes

The following rules apply only to varying-width client-side character sets:

• Offset parameter: Regardless of whether the client-side character set is varying-width, the offset parameter is always as follows:

  • Clob(): in characters

  • Blob(): in bytes

• Amount parameter: The amount parameter is always as indicated:

  • Clob: in characters, when referring to a server-side LOB

  • Blob: in bytes, when referring to a client-side buffer

• length(): Regardless of whether the client-side character set is varying-width, the output length is as follows:

  • Clob.length(): in characters

  • Blob.length(): in bytes

• Clob.read() and Blob.read(): With client-side character set of varying-width, CLOBs and NCLOBs:

  • Input amount is in characters. Input amount refers to the number of characters to read from the server-side CLOB or NCLOB.

  • Output amount is in bytes. Output amount indicates how many bytes were read into the OCCI buffer parameter, buffer.

• Clob.write() and Blob.write(): With client-side character set of varying-width, CLOBs and NCLOBs:

  • Input amount is in bytes. Input amount refers to the number of bytes of data in the OCCI input buffer, buffer.

  • Output amount is in characters. Output amount refers to the number of characters written into the server-side CLOB or NCLOB.

• Amount Parameter for Other OCCI Operations: For the OCCI LOB operations Clob.copy(), Clob.erase(), Clob.trim() irrespective of the client-side character set, the amount parameter is in characters for CLOBs and NCLOBs. All these operations refer to the amount of LOB data on the server.