Using C++ (OCCI) To Work With LOBs

Oracle C++ Call Interface (OCCI) is a C++ API for manipulating data in an Oracle database. OCCI is organized as an easy-to-use collection of C++ classes which enable a C++ program to connect to a database, execute SQL statements, insert/update values in database tables, retrieve results of a query, execute stored procedures in the database, and access metadata of database schema objects. OCCI also provides a seamless interface to manipulate objects of user-defined types as C++ class instances.

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 already written as "close to the machine" as possible. Since 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 machine.

• 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 need to write corresponding SQL statements. If you use the client side cache, the navigational interface performs better than the object interface.

• With respect to ODBC, the OCCI API is simpler to use. Since 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 Oracle C++ Call Interface (OCCI) to make changes to an entire internal LOB, or to pieces of the beginning, middle, or end of it, as follows:

• For reading from internal and external LOBs (BFILEs)

• For writing to internal LOBs

Distinct Classes for Each LOB Type

Unlike OCI which uses a common API for operations on BLOBs, CLOBs, and BFILEs, OCCI has distinct classes for each LOB types, as follows:

• OCCIClob Class to access and modify data stored in internal CLOBs and NCLOBs

• OCCIBlob Class to access and modify data stored in internal BLOBs

• OCCIBfile Class to access and read data stored in external LOBs (BFILEs)

OCCIClob Class

The OCCIClob driver implements a CLOB object using an SQL locator(CLOB). 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 (Character Large Object) value, for materializing a CLOB value on the client, and getting a substring. Methods in the interfaces ResultSet statement such as getClob() and setClob() allow you to access SQL CLOB values.

OCCIBlob Class

Methods in the OCCIResultSet and OCCIStatement interfaces, such as getBlob() and setBlob(), allow you to access SQL BLOB values. The OCCIBlob 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.

These methods are listed in the tables below.

See Also: Oracle C++ Interface Programmer's Guide for detailed documentation, including parameters, parameter types, return values, and example code. Oracle9i Globalization and National Language Support Guide for detailed information about implementing applications in different languages.

Offset and Amount Parameters: Fixed-Width Versus Varying-Width, Character or Byte With OCCI

Fixed Width Character Set Rules

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

• OCCIClob: offset and amount parameters are always in characters

• OCCIBlob: offset and amount parameters are always in bytes

• OCCIBfile: offset and amount parameters are always in bytes

Varying-Width Character Set Rules

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:
  • OCCIClob(): in characters

  • OCCIBlob(): in bytes

  • OCCIBfile(): in bytes

• Amount parameter: The amount parameter is always as follows:
  • OCCIClob: in characters, when referring to a server-side LOB

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

  • OCCIBfile: 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:
  • OCCIClob.length(): in characters

  • OCCIBlob.length(): in bytes

  • OCCIBfile.length(): in bytes

• OCCIClob.read() and OCCIBlob.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'.

• OCCIClob.write() and OCCIBlob.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.

OffSet and Amount Parameters for Other OCCI Operations

For all other OCCI LOB operations, irrespective of the client-side character set, the amount parameter is in characters for CLOBs and NCLOBs. These include the following:

• OCCIClob.copy()

• OCCIClob.erase()

• OCCIClob.trim()

• For LoadFromFile functionality, overloaded OCCICLob.copy()

All these operations refer to the amount of LOB data on the server.

See also: Oracle9i Globalization and National Language Support Guide

NCLOBs

• NCLOBs parameters are allowed in methods

• NCLOBs parameters are not allowed as attributes in object types

Loading from Files with OCCIClob.copy() and OCCIBlob.copy(): Specify the Amount Parameter to be Less than Length of BFILE

The LoadFromFile functionality in OCCI is provided though the OCCIClob.copy() and OCCIBlob.copy() methods. These take an OCCIBfile argument.

You cannot specify amounts larger than the length of the BFILE.

OCCIClob.read(), OCCIBlob.read(), and OCCIBfile.read(): Specify Amount Parameter to be 4 gigabytes - 1

When reading in OCCIClobs, OCCIBlobs, and OCCIBfiles, specify the amount = 4 gigabytes-1, and it will read to the end of the LOB.

Further Information About OCCI

See Also: Oracle C++ Interface Programmer's Guide http://www.oracle.com/products and select Application Server. Enter OCCI on the search line to bring up articles on OCCI. http://otn.oracle.com/Products/Programmer for OCCI features

OCCI Methods that Operate on BLOBs, BLOBs, NCLOBs, and BFILEs

OCCI methods that operate on BLOBs, CLOBs, NCLOBs, and BFILEs are as follows:

• To modify internal LOBs, see Table 3-16

• To read or examine LOB values, see Table 3-17

• For read only methods on external LOBs (BFILEs), see Table 3-18

• Other LOB OCCI methods are described in Table 3-19

• To open and close LOBs, see Table 3-20

OCCI Methods To Modify Internal LOB (BLOB, CLOB, and NCLOB) Values

Table 3-16 OCCI Clob and OCCIBlob Methods To Modify Internal LOB (BLOB, CLOB, and NCLOB) Values

Function/Procedure	Description
OCCIBlob.append()	Appends CLOB or BLOB value to another LOB.
OCCIBlob.copy()	Copies all or part of a CLOB or BLOB to another LOB.
OCCIBlob.copy()	Loads BFILE data into an internal LOB.
OCCIBlob.trim()	Truncates a CLOB or BLOB.
OCCIBlob.write()	Writes data from a buffer into a LOB, overwriting existing data.

OCCI Methods To Read or Examine Internal LOB and BFILE Values

Table 3-17 OCCI Blob/OCCIClob/OCCIBfile Methods To Read or Examine internal LOB and external LOB (BFILE) Values

Function/Procedure	Description
OCCIBlob.getChunkSize()	Gets the Chunk size used when reading and writing. This works on internal LOBs and does not apply to external LOBs (BFILEs).
OCCIBlob.length()	Returns the length of a LOB or a BFILE.
OCCIBlob.read()	Reads a specified portion of a non-null LOB or a BFILE into a buffer.

OCCI Read-Only Methods For BFILEs

Table 3-18  OCCI Read-Only Methods For BFILES

Function/Procedure	Description
OCCIBfile.close()	Closes an open BFILE.
OCCIBfile.fileExists()	Checks whether a BFILE exists.
OCCIBfile.getFileName()	Returns the name of a BFILE.
OCCIBfile.getDirAlias()	Gets the directory alias.
OCCIBfile.isOpen()	Checks whether a BFILE is open.
OCCIBfile.open()	Opens a BFILE.

Other OCCI LOB Methods

Table 3-19  Other OCCI LOB Methods

Methods	Description
OCCIClob/Blob/Bfile.=	Assigns one LOB locator to another. Use = or the copy constructor.
OCCIClob.getCharSetForm()	Returns the character set form of a LOB.
OCCIClob.getCharSetId()	Returns the character set ID of a LOB.
OCCIBfile.setName()	Sets the name of a BFILE.
OCCIClob/Blob/Bfile.IsEqual()	Checks whether two LOB refer to the same LOB.
OCCIClob/Blob/Bfile.isInitialized()	Checks whether a LOB is initialized.

OCCI Methods To Open and Close Internal and External LOBs

Table 3-20  OCCI Methods To Open and Close Internal and External LOBs

Function/Procedure	Description
OCCIClob/Blob/Bfile.Open()	Opens a LOB
OCCIClob/Blob/Bfile.IsOpen()	Sees if a LOB is open
OCCIClob/Blob/Bfile.Close()	Closes a LOB