8.6 OCCI API for LOBs

OCCI provides a seamless interface to manipulate objects of user-defined types as C++ class instances.

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

See Also:

Syntax information on these classes and details on OCCI in general is available in theOracle C++ Call Interface Programmer's Guide.

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.

See also:

Oracle Database Globalization Support Guide

Table 8-8 OCCI Methods for LOBs

Category	Function/Procedure	Description
Sanity Checking	Clob/Blob.isInitialized	Checks whether a LOB locator is initialized.
Open/Close	Clob/Blob.Open()	Open a LOB
	Clob/Blob.isOpen()	Check if a LOB is open
	Clob/Blob.Close()	Close the LOB
Read Operations	Blob/Clob.length()	Get the length of the LOB
	Blob/Clob.getChunkSize()	Get the optimum read or write size
	Blob/Clob.read()	Read data from the LOB starting at the specified offset
	Clob.getCharSetId()	Return the character set ID of a LOB
	Clob.getCharSetForm()	Return the character set form of a LOB.
Modify Operations	Blob/Clob.write()	Write data to the LOB at a specified offset
	Blob/Clob.trim()	Trim the LOB value to the specified shorter length
Operations involving multiple locators	Clob/Blob.operator == and !=	Checks whether two LOB locators refer to the same LOB.
	Blob/Clob.append()	Append a LOB value to another LOB
	Blob/Clob.copy()	Copy all or part of a LOB to another LOB, or load from a BFILE into a LOB
	Clob/Blob.operator =	Assign one LOB to another
Operations specific to securefiles	Blob/Clob.getOptions()	Returns options (deduplication, compression, encryption) for SecureFiles.
	Blob/Clob.setOptions()	Sets LOB features (deduplication and compression) for SecureFiles
	Blob/Clob.getContentType()	Gets the content string for a SecureFiles
	Blob/Clob.setContentType()	Sets a content string in a SecureFiles