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.
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,
CLOB
s and NCLOB
s:
- 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,
CLOB
s and NCLOB
s:
- 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 CLOB
s and NCLOB
s. 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.
NCLOBs
NCLOBs
parameters are allowed in methods
NCLOB
s 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
OCCI Methods that Operate on BLOBs, BLOBs, NCLOBs, and BFILEs
OCCI methods that operate on BLOBs, CLOBs, NCLOBs, and BFILEs are as follows:
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
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
OCCI Read-Only Methods For BFILEs
Table 3-18 OCCI Read-Only Methods For BFILES
Other OCCI LOB Methods
Table 3-19 Other OCCI LOB Methods
OCCI Methods To Open and Close Internal and External LOBs
Table 3-20 OCCI Methods To Open and Close Internal and External LOBs