Oracle 11g Release 2 11.2 Database Software Developer's Guide

Opening a BFILE with FILEOPEN on page 21-12

Yes

Yes

Using ISOPEN on page 21-13

Yes

Determining Whether a BFILE Is Open with FILEISOPEN on page 21-14

Yes

Yes

Reading a Portion of BFILE Data Using

Yes

SUBSTR on page 21-17

Yes

Comparing All or Parts of Two BFILES on page 21-17

Yes

Checking If a Pattern Exists in a BFILE

Using INSTR on page 21-18

Yes

Getting the Length of a BFILE page 21-19

Yes

COBOL Pro*C/C++ COM

Yes Yes Yes

Yes

JDBC

Yes

21-2

Oracle Database SecureFiles and Large Objects Developer's Guide

Directory Objects

Table 21–1 (Cont.) Environments Supported for BFILE APIs

Operation PL/SQL OCI

Assigning a BFILE Locator on page 21-20

Getting Directory Object Name and

File Name of a BFILE on page 21-21

Updating a BFILE by Initializing a

BFILE Locator on page 21-21

"Loading a LOB with BFILE Data" on page 21-10).

Yes

COBOL Pro*C/C++ COM

Yes Yes Yes

Yes

Accessing BFILEs

To access BFILEs use one of the following interfaces:

■

OCI (Oracle Call Interface)

PL/SQL (DBMS_LOB package)

Precompilers, such as Pro*C/C++ and Pro*COBOL

Oracle Objects for OLE (OO4O)

Java (JDBC)

Directory Objects

The DIRECTORY object facilitates administering access and usage of BFILE data types.

A DIRECTORY object specifies a logical alias name for a physical directory on the database server file system under which the file to be accessed is located. You can access a file in the server file system only if granted the required access privilege on

DIRECTORY

object. You can also use Enterprise Manager Web console to manage

DIRECTORY

objects.

Initializing a BFILE Locator

The DIRECTORY object also provides the flexibility to manage the locations of the files, instead of forcing you to hard-code the absolute path names of physical files in your applications. A directory object name is used in conjunction with the BFILENAME function, in SQL and PL/SQL, or the OCILobFileSetName() in OCI, for initializing a BFILE locator.

LOB APIs for BFILE Operations

21-3

Yes

JDBC

Yes

Directory Objects

Note:

The database does not verify that the directory and path name you specify actually exist. You should take care to specify a valid directory in your operating system. If your operating system uses case-sensitive path names, then be sure you specify the directory in the correct format. There is no requirement to specify a terminating slash (for example, /tmp/ is not necessary, simply use /tmp).

Directory specifications cannot contain ".." anywhere in the path (for example, /abc/def/hij..).

How to Associate Operating System Files with a BFILE

To associate an operating system file to a BFILE, first create a DIRECTORY object which is an alias for the full path name to the operating system file.

To associate existing operating system files with relevant database records of a particular table use Oracle SQL DML (Data Manipulation Language). For example:

■

Use INSERT to initialize a BFILE column to point to an existing file in the server file system.

Use UPDATE to change the reference target of the BFILE.

■

Initialize a BFILE to NULL and then update it later to refer to an operating system file using the BFILENAME function.

OCI users can also use OCILobFileSetName() to initialize a BFILE locator variable that is then used in the VALUES clause of an INSERT statement.

Directory Example

The following statements associate the files Image1.gif and image2.gif with records having key_value of 21 and 22 respectively. 'IMG' is a DIRECTORY object that represents the physical directory under which Image1.gif and image2.gif are stored.

You may be required to set up data structures similar to the following for certain examples to work:

CREATE TABLE Lob_table (

Key_value NUMBER NOT NULL,

F_lob BFILE)

INSERT INTO Lob_table VALUES

(21, BFILENAME('IMG', 'Image1.gif'));

INSERT INTO Lob_table VALUES

(22, BFILENAME('IMG', 'image2.gif'));

The following UPDATE statement changes the target file to image3.gif for the row with key_value of 22.

UPDATE Lob_table SET f_lob = BFILENAME('IMG', 'image3.gif')

WHERE Key_value = 22;

21-4

Oracle Database SecureFiles and Large Objects Developer's Guide

Characteristics of the BFILE Data Type

Note:

The database does not expand environment variables specified in the DIRECTORY object or file name of a BFILE locator. For example, specifying:

BFILENAME('WORK_DIR', '$MY_FILE') where MY_FILE, an environment variable defined in the operating system, is not valid.

BFILENAME and Initialization

BFILENAME

is a built-in function that you use to initialize a BFILE column to point to an external file.

Once physical files are associated with records using SQL DML, subsequent read operations on the BFILE can be performed using PL/SQL DBMS_LOB package and

OCI. However, these files are read-only when accessed through BFILEs, and so they cannot be updated or deleted through BFILEs.

As a consequence of the reference-based semantics for BFILEs, it is possible to have multiple BFILE columns in the same record or different records referring to the same file. For example, the following UPDATE statements set the BFILE column of the row with key_value = 21 in lob_table to point to the same file as the row with key_value

= 22.

UPDATE lob_table

SET f_lob = (SELECT f_lob FROM lob_table WHERE key_value = 22)

WHERE key_value = 21;

Think of BFILENAME in terms of initialization — it can initialize the value for the following:

■

BFILE

column

BFILE

(automatic) variable declared inside a PL/SQL module

Characteristics of the BFILE Data Type

Using the BFILE data type has the following advantages:

■

If your need for a particular BFILE is temporary and limited within the module on which you are working, then you can use the BFILE related APIs on the variable without ever having to associate this with a column in the database.

Because you are not forced to create a BFILE column in a server side table, initialize this column value, and then retrieve this column value using a SELECT, you save a round-trip to the server.

For more information, refer to the example given for DBMS_LOB.LOADFROMFILE (see

The OCI counterpart for BFILENAME is OCILobFileSetName(), which can be used in a similar fashion.

DIRECTORY Name Specification

You must have CREATE ANY DIRECTORY system privilege to create directories. Path names cannot contain two dots (".."). The naming convention for DIRECTORY objects is the same as that for tables and indexes. That is, normal identifiers are interpreted in

LOB APIs for BFILE Operations

21-5

BFILE Security uppercase, but delimited identifiers are interpreted as is. For example, the following statement:

CREATE OR REPLACE DIRECTORY scott_dir AS '/usr/home/scott'; creates or redefines a DIRECTORY object whose name is 'SCOTT_DIR' (in uppercase).

But if a delimited identifier is used for the DIRECTORY name, as shown in the following statement

CREATE DIRECTORY "Mary_Dir" AS '/usr/home/mary'; then the directory object name is 'Mary_Dir'. Use 'SCOTT_DIR' and 'Mary_Dir' when calling BFILENAME. For example:

BFILENAME('SCOTT_DIR', 'afile')

BFILENAME('Mary_Dir', 'afile')

On Windows Platforms

On Windows platforms the directory names are case-insensitive. Therefore the following two statements refer to the same directory:

CREATE DIRECTORY "big_cap_dir" AS "g:\data\source";

CREATE DIRECTORY "small_cap_dir" AS "G:\DATA\SOURCE";

BFILE Security

This section introduces the BFILE security model and associated SQL statements. The main SQL statements associated with BFILE security are:

■

SQL DDL: CREATE and REPLACE or ALTER a DIRECTORY object

SQL DML: GRANT and REVOKE the READ system and object privileges on

DIRECTORY

objects

Ownership and Privileges

The DIRECTORY object is a system owned object. For more information on system owned objects, see Oracle Database SQL Language Reference. Oracle Database supports two new system privileges, which are granted only to DBA:

■

CREATE

ANY DIRECTORY — for creating or altering the DIRECTORY object creation

DROP

ANY DIRECTORY — for deleting the DIRECTORY object

Read Permission on a DIRECTORY Object

READ

permission on the DIRECTORY object enables you to read files located under that directory. The creator of the DIRECTORY object automatically earns the READ privilege.

If you have been granted the READ permission with GRANT option, then you may in turn grant this privilege to other users/roles and add them to your privilege domains.

Note:

The READ permission is defined only on the DIRECTORY object, not on individual files. Hence there is no way to assign different privileges to files in the same directory.

21-6

Oracle Database SecureFiles and Large Objects Developer's Guide

BFILE Security

The physical directory that it represents may or may not have the corresponding operating system privileges (read in this case) for the Oracle Server process.

It is the responsibility of the DBA to ensure the following:

■

That the physical directory exists

■

Read permission for the Oracle Server process is enabled on the file, the directory, and the path leading to it

The directory remains available, and read permission remains enabled, for the entire duration of file access by database users

The privilege just implies that as far as the Oracle Server is concerned, you may read from files in the directory. These privileges are checked and enforced by the PL/SQL

DBMS_LOB

package and OCI APIs at the time of the actual file operations.

Caution:

Because CREATE ANY DIRECTORY and DROP ANY

privileges potentially expose the server file system to all database users, the DBA should be prudent in granting these privileges to normal database users to prevent security breach.

SQL DDL for BFILE Security

Refer to the Oracle Database SQL Language Reference for information about the following

SQL DDL statements that create, replace, and drop DIRECTORY objects:

■

CREATE

DIRECTORY

DROP

DIRECTORY

SQL DML for BFILE Security

Refer to the Oracle Database SQL Language Reference for information about the following

SQL DML statements that provide security for BFILEs:

■

GRANT

(system privilege)

GRANT

(object privilege)

REVOKE

(system privilege)

REVOKE

(object privilege)

AUDIT

(new statements)

AUDIT

(schema objects)

Catalog Views on Directories

Catalog views are provided for DIRECTORY objects to enable users to view object names and corresponding paths and privileges. Supported views are:

■

ALL_DIRECTORIES

(OWNER, DIRECTORY_NAME, DIRECTORY_PATH)

This view describes all directories accessible to the user.

DBA_DIRECTORIES

(OWNER, DIRECTORY_NAME, DIRECTORY_PATH)

This view describes all directories specified for the entire database.

LOB APIs for BFILE Operations

21-7

BFILE Security

Guidelines for DIRECTORY Usage

The main goal of the DIRECTORY feature is to enable a simple, flexible, non-intrusive, yet secure mechanism for the DBA to manage access to large files in the server file system. But to realize this goal, it is very important that the DBA follow these guidelines when using DIRECTORY objects:

■

Do not map a DIRECTORY object to a data file directory. A DIRECTORY object should not be mapped to physical directories that contain Oracle data files, control files, log files, and other system files. Tampering with these files (accidental or otherwise) could corrupt the database or the server operating system.

Only the DBA should have system privileges. The system privileges such as

CREATE

ANY DIRECTORY (granted to the DBA initially) should be used carefully and not granted to other users indiscriminately. In most cases, only the database administrator should have these privileges.

Use caution when granting the DIRECTORY privilege. Privileges on DIRECTORY objects should be granted to different users carefully. The same holds for the use of the WITH GRANT OPTION clause when granting privileges to users.

Do not drop or replace DIRECTORY objects when database is in operation.

DIRECTORY

objects should not be arbitrarily dropped or replaced when the database is in operation. If this were to happen, then operations from all sessions on all files associated with this DIRECTORY object fail. Further, if a DROP or REPLACE command is executed before these files could be successfully closed, then the references to these files are lost in the programs, and system resources associated with these files are not be released until the session(s) is shut down.

■

The only recourse left to PL/SQL users, for example, is to either run a program block that calls DBMS_LOB.FILECLOSEALL and restart their file operations, or exit their sessions altogether. Hence, it is imperative that you use these commands with prudence, and preferably during maintenance downtimes.

Use caution when revoking a user's privilege on DIRECTORY objects. Revoking a user's privilege on a DIRECTORY object using the REVOKE statement causes all subsequent operations on dependent files from the user's session to fail. Either you must re-acquire the privileges to close the file, or run a FILECLOSEALL in the session and restart the file operations.

In general, using DIRECTORY objects for managing file access is an extension of system administration work at the operating system level. With some planning, files can be logically organized into suitable directories that have READ privileges for the Oracle process.

DIRECTORY

objects can be created with READ privileges that map to these physical directories, and specific database users granted access to these directories.

BFILEs in Shared Server (Multithreaded Server) Mode

The database does not support session migration for BFILE data types in shared server (multithreaded server) mode. This implies that operations on open BFILE instances can persist beyond the end of a call to a shared server.

In shared server sessions, BFILE operations are bound to one shared server, they cannot migrate from one server to another.

21-8

Oracle Database SecureFiles and Large Objects Developer's Guide

BFILE Security

External LOB (BFILE) Locators

For BFILEs, the value is stored in a server-side operating system file; in other words, external to the database. The BFILE locator that refers to that file is stored in the row.

When Two Rows in a BFILE Table Refer to the Same File

If a BFILE locator variable that is used in a DBMS_LOB.FILEOPEN (for example L1) is assigned to another locator variable, (for example L2), then both L1 and L2 point to the same file. This means that two rows in a table with a BFILE column can refer to the same file or to two distinct files — a fact that the canny developer might turn to advantage, but which could well be a pitfall for the unwary.

BFILE Locator Variable

A BFILE

locator variable operates like any other automatic variable. With respect to file operations, it operates like a file descriptor available as part of the standard input/output library of most conventional programming languages. This implies that once you define and initialize a BFILE locator, and open the file pointed to by this locator, all subsequent operations until the closure of this file must be done from within the same program block using this locator or local copies of this locator.

■

Guidelines for BFILEs

Note the following guidelines when working with BFILEs:

Open and close a file from the same program block at same nesting level. The

BFILE

locator variable can be used, just as any scalar, as a parameter to other procedures, member methods, or external function callouts. However, it is recommended that you open and close a file from the same program block at the same nesting level.

Set the BFILE value before flushing the object to the database. If an object contains a BFILE, then you must set the BFILE value before flushing the object to the database, thereby inserting a new row. In other words, you must call

OCILobFileSetName()

after OCIObjectNew() and before

OCIObjectFlush()

Indicate the DIRECTORY object name and file name before inserting or updating of a BFILE. It is an error to insert or update a BFILE without indicating a

DIRECTORY

object name and file name.

This rule also applies to users using an OCI bind variable for a BFILE in an insert or update statement. The OCI bind variable must be initialized with a DIRECTORY object name and file name before issuing the insert or update statement.

Initialize BFILE Before insert or update

Note:

OCISetAttr()

does not allow the user to set a BFILE locator to NULL.

■

Before using SQL to insert or update a row with a BFILE, you must initialize the

BFILE

to one of the following:

■

NULL

(not possible if using an OCI bind variable)

A DIRECTORY object name and file name

A path name cannot contain two dots ("..") anywhere in its specification. A file name cannot start with two dots.

LOB APIs for BFILE Operations

21-9

Loading a LOB with BFILE Data

This section describes how to load a LOB with data from a BFILE.

Note:

The LOADBLOBFROMFILE and LOADCLOBFROMFILE procedures implement the functionality of this procedure and provide improved features for loading binary data and character data. The improved procedures are available in the PL/SQL environment only.

When possible, using one of the improved procedures is

"Loading a CLOB or NCLOB with Data from a BFILE" on page 22-9 for more information.

Character Set Conversion

In using OCI, or any of the programmatic environments that access OCI functionality, character set conversions are implicitly performed when translating from one character set to another.

BFILE to CLOB or NCLOB: Converting From Binary Data to a Character Set

When you use the DBMS_LOB.LOADFROMFILE procedure to populate a CLOB or

NCLOB

, you are populating the LOB with binary data from the BFILE. No implicit

translation is performed from binary data to a character set. For this reason, you should

use the LOADCLOBFROMFILE procedure when loading text (see Loading a CLOB or

NCLOB with Data from a BFILE on page 22-9).

Amount Parameter

Note the following with respect to the amount parameter:

■

DBMS_LOB.LOADFROMFILE

If you want to load the entire BFILE, then pass the constant

DBMS_LOB.LOBMAXSIZE

. If you pass any other value, then it must be less than or equal to the size of the BFILE.

■

OCILobLoadFromFile()

21-10

Oracle Database SecureFiles and Large Objects Developer's Guide

Opening a BFILE with OPEN

■

If you want to load the entire BFILE, then you can pass the constant UB4MAXVAL.

If you pass any other value, then it must be less than or equal to the size of the

BFILE

OCILobLoadFromFile2()

If you want to load the entire BFILE, then you can pass the constant UB8MAXVAL.

If you pass any other value, then it must be less than or equal to the size of the

BFILE

Opening a BFILE with OPEN

This section describes how to open a BFILE using the OPEN function.

Note:

You can also open a BFILE using the FILEOPEN function; however, using the OPEN function is recommended for new

development. Using the FILEOPEN function is described in Opening a

BFILE with FILEOPEN on page 21-12.

Opening a BFILE with FILEOPEN

This section describes how to open a BFILE using the FILEOPEN function.

Note:

The FILEOPEN function is not recommended for new application development. The OPEN function is recommended for new development. See

"Opening a BFILE with OPEN" on page 21-11

Determining Whether a BFILE Is Open Using ISOPEN

This section describes how to determine whether a BFILE is open using ISOPEN.

Note:

This function (ISOPEN) is recommended for new application development. The older FILEISOPEN function, described in

"Determining Whether a BFILE Is Open with FILEISOPEN" on page 21-14, is not recommended for new development.

Determining Whether a BFILE Is Open with FILEISOPEN

This section describes how to determine whether a BFILE is OPEN using the

FILEISOPEN function.

Note:

The FILEISOPEN function is not recommended for new application development. The ISOPEN function is recommended for

new development. See Determining Whether a BFILE Is Open Using

ISOPEN on page 21-13

Displaying BFILE Data

This section describes how to display BFILE data.

Reading Data from a BFILE

This section describes how to read data from a BFILE.

Streaming Read in OCI

The most efficient way to read large amounts of BFILE data is by OCILobRead2() with the streaming mechanism enabled, and using polling or callback. To do so, specify the starting point of the read using the offset parameter as follows: ub8 char_amt = 0; ub8 byte_amt = 0; ub4 offset = 1000;

OCILobRead2(svchp, errhp, locp, &byte_amt, &char_amt, offset, bufp, bufl,

OCI_ONE_PIECE, 0, 0, 0, 0);

When using polling mode, be sure to look at the value of the byte_amt parameter after each OCILobRead2() call to see how many bytes were read into the buffer, because the buffer may not be entirely full.

When using callbacks, the lenp parameter, which is input to the callback, indicates how many bytes are filled in the buffer. Be sure to check the lenp parameter during your callback processing because the entire buffer may not be filled with data (see the

Oracle Call Interface Programmer's Guide.)

Amount Parameter

■

When calling DBMS_LOB.READ, the amount parameter can be larger than the size of the data; however, the amount parameter should be less than or equal to the size of the buffer. In PL/SQL, the buffer size is limited to 32K.

■

When calling OCILobRead2(), you can pass a value of 0 (zero) for the byte_amt parameter to read to the end of the BFILE.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB) (Oracle Database PL/SQL Packages and Types Reference):

"DBMS_LOB" — READ

C (OCI) (Oracle Call Interface Programmer's Guide): Chapter 7, "LOB and File

Operations" for usage notes. Chapter 16, section "LOB Functions" —

OCILobRead2()

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

LOB READ.

C/C++ (Pro*C/C++) (Pro*C/C++ Programmer's Guide): "Large Objects (LOBs)",

"LOB Statements", "Embedded SQL Statements and Directives" — LOB READ

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC) (Oracle Database JDBC Developer's Guide and Reference): Chapter 7,

"Working With LOBs and BFILEs" — Working with BFILEs.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB): fread.sql

OCI: fread.c

COM (OO4O): fread.bas

Java (JDBC): fread.java

21-16

Oracle Database SecureFiles and Large Objects Developer's Guide

Comparing All or Parts of Two BFILES

Reading a Portion of BFILE Data Using SUBSTR

This section describes how to read portion of BFILE data using SUBSTR.

Comparing All or Parts of Two BFILES

This section describes how to compare all or parts of two BFILEs.

Checking If a Pattern Exists in a BFILE Using INSTR

This section describes how to determine whether a pattern exists in a BFILE using

INSTR

Determining Whether a BFILE Exists

This procedure determines whether a BFILE locator points to a valid BFILE instance.

Getting the Length of a BFILE

This section describes how to get the length of a BFILE.

Assigning a BFILE Locator

This section describes how to assign one BFILE locator to another.

Getting Directory Object Name and File Name of a BFILE

This section describes how to get the DIRECTORY object name and file name of a

BFILE

Updating a BFILE by Initializing a BFILE Locator

This section describes how to update a BFILE by initializing a BFILE locator.

Closing a BFILE with FILECLOSE

This section describes how to close a BFILE with FILECLOSE.

Note:

This function (FILECLOSE) is not recommended for new development. For new development, use the CLOSE function instead.

See

"Closing a BFILE with CLOSE" on page 21-23 for more

information.

Closing a BFILE with CLOSE

This section describes how to close a BFILE with the CLOSE function.

Note:

This function (CLOSE) is recommended for new application development. The older FILECLOSE function, is not recommended for new development.

Closing All Open BFILEs with FILECLOSEALL

This section describes how to close all open BFILEs.

You are responsible for closing any BFILE instances before your program terminates.

For example, you must close any open BFILE instance before the termination of a

PL/SQL block or OCI program.

You must close open BFILE instances even in cases where an exception or unexpected termination of your application occurs. In these cases, if a BFILE instance is not closed, then it is still considered open by the database. Ensure that your exception handling strategy does not allow BFILE instances to remain open in these situations.

Inserting a Row Containing a BFILE

This section describes how to insert a row containing a BFILE by initializing a BFILE locator.

Using LOB APIs

This chapter describes APIs that perform operations on BLOB, CLOB, and NCLOB data types. The operations given in this chapter can be used with either persistent or temporary LOB instances. Note that operations in this chapter do not apply to BFILEs.

APIs covered in this chapter are listed in

Table 22–1

Supported Environments

Table 22–1, " Environments Supported for LOB APIs" indicates which programmatic

environments are supported for the APIs discussed in this chapter. The first column describes the operation that the API performs. The remaining columns indicate with

"Yes" or "No" whether the API is supported in PL/SQL, OCI, OCCI, COBOL,

Pro*C/C++, COM, and JDBC.

Table 22–1 Environments Supported for LOB APIs

Operation

Determining Character Set Form on page 22-5

Determining Character Set ID on page 22-5

Determining Chunk Size, See: Writing

Data to a LOB on page 22-27

PL/SQL OCI

Yes Yes

Yes

OCCI COBOL Pro*C/C++ COM

No Yes Yes Yes

Yes

JDBC

Yes

22-2

Oracle Database SecureFiles and Large Objects Developer's Guide

Supported Environments

Table 22–1 (Cont.) Environments Supported for LOB APIs

Operation

Converting a BLOB to a CLOB on page 22-40

Yes

Converting a CLOB to a BLOB on page 22-40

PL/SQL OCI

Yes

Copying a LOB Locator on page 22-24

Yes

Disabling LOB Buffering on page 22-38 No

Yes

Enabling LOB Buffering on page 22-36

Yes

Equality: Checking If One LOB Locator

Is Equal to Another on page 22-25

Flushing the Buffer on page 22-37

Yes

Determining Whether LOB Locator Is

Initialized on page 22-25

Length: Determining the Length of a

LOB on page 22-22

Yes

Loading a LOB with Data from a BFILE on page 22-6

Yes

Loading a BLOB with Data from a

BFILE on page 22-7

Yes

Loading a CLOB or NCLOB with Data from a BFILE on page 22-9

LOB Array Read on page 22-14

LOB Array Write on page 22-29

Opening Persistent LOBs with the

OPEN and CLOSE Interfaces on page 12-9

Yes

Open:

Determining Whether a LOB is

Open on page 22-10

Patterns: Checking for Patterns in a

LOB Using INSTR on page 22-22

Reading a Portion of a LOB (SUBSTR) on page 22-20

Storage Limit, Determining: Maximum

Yes

Storage Limit for Terabyte-Size LOBs on page 12-22

Yes

OCCI

Yes

COBOL Pro*C/C++

Yes

COM

Yes

JDBC

Yes

Using LOB APIs

22-3

Appending One LOB to Another

Table 22–1 (Cont.) Environments Supported for LOB APIs

Operation

WriteNoAppend, see Appending to a

LOB on page 22-26.

more details on the state of the locator after an update, refer to "Example of Updating

PL/SQL OCI

Yes

Yes Yes

OCCI COBOL Pro*C/C++ COM

Yes

Yes Yes Yes Yes

JDBC

Yes

Appending One LOB to Another

This operation appends one LOB instance to another.

Preconditions

Before you can append one LOB to another, the following conditions must be met:

■

Two LOB instances must exist.

Both instances must be of the same type, for example both BLOB or both CLOB types.

You can pass any combination of persistent or temporary LOB instances to this operation.

Usage Notes

Persistent LOBs:

You must lock the row you are selecting the LOB from prior to updating a LOB value if you are using the PL/SQL DBMS_LOB Package or OCI.

While the SQL INSERT and UPDATE statements implicitly lock the row, locking the row can be done explicitly using the SQL SELECT FOR UPDATE statement in SQL and

PL/SQL programs, or by using an OCI pin or lock function in OCI programs. For

LOBs Through Updated Locators" on page 12-12.

Syntax

See the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — APPEND

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobAppend()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

LOB APPEND.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide for information on embedded

SQL statements and directives — LOB APPEND

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference for information on creating and populating LOB columns in Java.

22-4

Oracle Database SecureFiles and Large Objects Developer's Guide

Determining Character Set ID

Examples

To run the following examples, you must create two LOB instances and pass them when you call the given append operation. Creating a LOB instance is described in

Chapter 19, "Operations Specific to Persistent and Temporary LOBs" .

Examples for this use case are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lappend.sql

■

OCI: lappend.c

COM (OO4O): lappend.bas

Java (JDBC): lappend.java

Determining Character Set Form

This section describes how to get the character set form of a LOB instance.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): There is no applicable syntax reference for this operation.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobCharSetForm()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL): There is no applicable syntax reference for this operation

C/C++ (Pro*C/C++): There is no applicable syntax reference for this operation.

COM (OO4O): There is no applicable syntax reference for this operation.

Java (JDBC): There is no applicable syntax reference for this operation.

Example

The example demonstrates how to determine the character set form of the foreign language text (ad_fltextn).

This functionality is currently available only in OCI:

■

OCI: lgetchfm.c

Determining Character Set ID

This section describes how to determine the character set ID.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): There is no applicable syntax reference for this operation.

C (OCI): Oracle Call Interface Programmer's Guide "Relational Functions" — LOB

Functions, OCILobCharSetId()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL): There is no applicable syntax reference for this operation.

Using LOB APIs

22-5

Loading a LOB with Data from a BFILE

■

C/C++ (Pro*C/C++): There is no applicable syntax reference for this operation

COM (OO4O): There is no applicable syntax reference for this operation.

Java (JDBC): There is no applicable syntax reference for this operation.

Example

This functionality is currently available only in OCI:

■

OCI: lgetchar.c

Loading a LOB with Data from a BFILE

This operation loads a LOB with data from a BFILE. This procedure can be used to load data into any persistent or temporary LOB instance of any LOB data type.

Use LOADCLOBFROMFILE When Loading Character Data

When you use the DBMS_LOB.LOADFROMFILE procedure to load a CLOB or NCLOB instance, you are loading the LOB with binary data from the BFILE and no implicit character set conversion is performed. For this reason, using the

DBMS_LOB.LOADCLOBFROMFILE

procedure is recommended when loading character data, see

Loading a CLOB or NCLOB with Data from a BFILE on page 22-9 for more

information.

Specifying Amount of BFILE Data to Load

The value you pass for the amount parameter to functions listed in

Table 22–2

must be one of the following:

■

An amount less than or equal to the actual size (in bytes) of the BFILE you are loading.

22-6

Oracle Database SecureFiles and Large Objects Developer's Guide

Loading a BLOB with Data from a BFILE

■

The maximum allowable LOB size (in bytes). Passing this value, loads the entire

BFILE

. You can use this technique to load the entire BFILE without determining the size of the BFILE before loading. To get the maximum allowable LOB size, use

the technique described in Table 22–2

Table 22–2 Maximum LOB Size for Load from File Operations

Environment Function

To pass maximum LOB size, get value of:

DBMS_LOB

OCI

DBMS_LOB.LOADBLOBFROMFILE

DBMS_LOB.LOADCLOBFROMFILE

DBMS_LOB.LOBMAXSIZE

UB8MAXVAL

OCI

OCILobLoadFromFile2()

(For LOBs of any size.)

OCILobLoadFromFile()

(For LOBs less than 4 gigabytes in size.)

UB4MAXVAL

Syntax

See the following syntax references for details on using this operation in each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — LOADFROMFILE.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobLoadFromFile().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB LOAD

, LOB OPEN, LOB CLOSE.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB LOAD

COM (OO4O) Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lloaddat.sql

OCI: lloaddat.c

COM (OO4O): lloaddat.bas

Java (JDBC): lloaddat.java

Loading a BLOB with Data from a BFILE

This procedure loads a BLOB with data from a BFILE. This procedure can be used to load data into any persistent or temporary BLOB instance.

Using LOB APIs

22-7

Loading a BLOB with Data from a BFILE

New Offsets Returned

Using DBMS_LOB.LOADBLOBFROMFILE to load binary data into a BLOB achieves the same result as using DBMS_LOB.LOADFROMFILE, but also returns the new offsets of

BLOB.

Specifying Amount of BFILE Data to Load

The value you pass for the amount parameter to the DBMS_LOB.LOADBLOBFROMFILE function must be one of the following:

■

An amount less than or equal to the actual size (in bytes) of the BFILE you are loading.

The maximum allowable LOB size: DBMS_LOB.LOBMAXSIZE. Passing this value causes the function to load the entire BFILE. This is a useful technique for loading the entire BFILE without introspecting the size of the BFILE.

Specifying Amount of BFILE Data to Load

The value you pass for the amount parameter to the DBMS_LOB.LOADCLOBFROMFILE function must be one of the following:

■

An amount less than or equal to the actual size (in characters) of the BFILE data you are loading.

The maximum allowable LOB size: DBMS_LOB.LOBMAXSIZE

Passing this value causes the function to load the entire BFILE. This is a useful technique for loading the entire BFILE without introspecting the size of the

BFILE

Syntax

See Oracle Database PL/SQL Packages and Types Reference, "DBMS_LOB" —

LOADCLOBFROMFILE

procedure for syntax details on this procedure.

Examples

The following examples illustrate different techniques for using this API:

■

"PL/SQL: Loading Character Data from a BFILE into a LOB"

"PL/SQL: Loading Segments of Character Data into Different LOBs"

Using LOB APIs

22-9

Determining Whether a LOB is Open

PL/SQL: Loading Character Data from a BFILE into a LOB

The following example illustrates:

■

How to use default csid (0).

How to load the entire file without calling getlength for the BFILE.

■

How to find out the actual amount loaded using return offsets.

This example assumes that ad_source is a BFILE in UTF8 character set format and the database character set is UTF8. The online file is lldclobf.sql.

PL/SQL: Loading Segments of Character Data into Different LOBs

The following example illustrates:

■

How to get the character set ID from the character set name using the

NLS_CHARSET_ID

function.

How to load a stream of data from a single BFILE into different LOBs using the returned offset value and the language context lang_ctx.

How to read a warning message.

This example assumes that ad_file_ext_01 is a BFILE in JA16TSTSET format and the database national character set is AL16UTF16. The online file is lldclobs.sql.

Determining Whether a LOB is Open

This operation determines whether a LOB is open.

Preconditions

The LOB instance must exist before executing this procedure.

Usage Notes

When a LOB is open, it must be closed at some point later in the session.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — OPEN, ISOPEN.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobIsOpen()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

LOB DESCRIBE.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB DESCRIBE ... ISOPEN ...

COM (OO4O): There is no applicable syntax reference for this use case.

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

22-10

Oracle Database SecureFiles and Large Objects Developer's Guide

Displaying LOB Data

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lisopen.sql

OCI: lisopen.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): No example is provided with this release.

Java (JDBC): lisopen.java

Java (JDBC): Checking If a LOB Is Open

Here is how to check a BLOB or a CLOB.

Checking If a CLOB Is Open

To see if a CLOB is open, your JDBC application can use the isOpen method defined in oracle.sql.CLOB

. The return Boolean value indicates whether the CLOB has been previously opened or not. The isOpen method is defined as follows:

/**

* Check whether the CLOB is opened.

* @return true if the LOB is opened.

*/ public boolean isOpen () throws SQLException

The usage example is:

CLOB clob = ...

// See if the CLOB is opened

boolean isOpen = clob.isOpen ();

...

Checking If a BLOB Is Open

To see if a BLOB is open, your JDBC application can use the isOpen method defined in oracle.sql.BLOB

. The return Boolean value indicates whether the BLOB has been previously opened or not. The isOpen method is defined as follows:

/**

* Check whether the BLOB is opened.

* @return true if the LOB is opened.

public boolean isOpen () throws SQLException

The usage example is:

BLOB blob = ...

// See if the BLOB is opened boolean isOpen = blob.isOpen ();

...

Displaying LOB Data

This section describes APIs that allow you to read LOB data. You can use this operation to read LOB data into a buffer. This is useful if your application requires displaying large amounts of LOB data or streaming data operations.

Using LOB APIs

22-11

Displaying LOB Data

Usage Notes

Note the following when using these APIs.

Streaming Mechanism

The most efficient way to read large amounts of LOB data is to use OCILobRead2() with the streaming mechanism enabled.

Amount Parameter

The value you pass for the amount parameter is restricted for the APIs described in

Table 22–3 .

Table 22–3 Maximum LOB Size for Amount Parameter

Environment Function

Value of amount parameter is limited to:

DBMS_LOB

OCI

DBMS_LOB.READ

The size of the buffer, 32Kbytes.

UB4MAXVAL OCILobRead()

(For LOBs less than 4 gigabytes in size.) Specifying this amount reads the entire file.

OCI

OCILobRead2()

(For LOBs of any size.)

UB8MAXVAL

Specifying this amount reads the entire file.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — OPEN, READ, CLOSE.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —,

OCILobOpen(), OCILobRead2(), OCILobClose().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB READ.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB READ

COM (OO4O) (Oracle Objects for OLE (OO4O) Oracle Objects for OLE Developer's

Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): ldisplay.sql

OCI: ldisplay.c

C++ (OCCI): No example is provided in this release.

COM (OO4O): ldisplay.bas

22-12

Oracle Database SecureFiles and Large Objects Developer's Guide

Reading Data from a LOB

■

Java (JDBC): ldisplay.java

Reading Data from a LOB

This section describes how to read data from LOBs using OCILobRead2().

Usage Notes

Note the following when using this operation.

Streaming Read in OCI

The most efficient way to read large amounts of LOB data is to use OCILobRead2() with the streaming mechanism enabled using polling or callback. To do so, specify the starting point of the read using the offset parameter as follows: ub8 char_amt = 0; ub8 byte_amt = 0; ub4 offset = 1000;

OCILobRead2(svchp, errhp, locp, &byte_amt, &char_amt, offset, bufp, bufl,

OCI_ONE_PIECE, 0, 0, 0, 0);

When using polling mode, be sure to look at the value of the byte_amt parameter after each OCILobRead2() call to see how many bytes were read into the buffer because the buffer may not be entirely full.

Oracle Call Interface Programmer's Guide.)

Chunk Size

A chunk is one or more Oracle blocks. You can specify the chunk size for the BasicFiles

The API you are using has a function that returns the amount of space used in the LOB chunk to store the LOB value. In PL/SQL use DBMS_LOB.GETCHUNKSIZE. In OCI, use

OCILobGetChunkSize()

. For

SecureFiles s, CHUNK is an advisory size and is provided for backward compatibility purposes.

To improve performance, you may run write requests using a multiple of the value returned by one of these functions. The reason for this is that you are using the same unit that the Oracle database uses when reading data from disk. If it is appropriate for your application, then you should batch reads until you have enough for an entire chunk instead of issuing several LOB read calls that operate on the same LOB chunk.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — OPEN, GETCHUNKSIZE, READ, CLOSE.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobOpen()

, OCILobRead2(), OCILobClose().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

Using LOB APIs

22-13

LOB Array Read

■

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB READ

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB READ

COM (OO4O) Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lread.sql

OCI: lread.c

COM (OO4O): lread.bas

Java (JDBC): lread.java

LOB Array Read

This section describes how to read LOB data for multiple locators in one round trip, using OCILobArrayRead().

Usage Notes

This function improves performance in reading LOBs in the size range less than about

512 Kilobytes. For an OCI application example, assume that the program has a prepared SQL statement such as:

SELECT lob1 FROM lob_table for UPDATE; where lob1 is the LOB column and lob_array is an array of define variables corresponding to a LOB column:

OCILobLocator * lob_array[10];

...

for (i=0; i<10, i++) /* initialize array of locators */

lob_array[i] = OCIDescriptorAlloc(..., OCI_DTYPE_LOB, ...);

...

OCIDefineByPos(..., 1, (dvoid *) lob_array, ... SQLT_CLOB, ...);

/* Execute the statement with iters = 10 to do an array fetch of 10 locators. */

OCIStmtExecute ( <service context>, <statement handle>, <error handle>,

10, /* iters */

0, /* row offset */

NULL, /* snapshot IN */

NULL, /* snapshot out */

OCI_DEFAULT /* mode */);

...

ub4 array_iter = 10;

char *bufp[10];

oraub8 bufl[10];

oraub8 char_amtp[10];

22-14

Oracle Database SecureFiles and Large Objects Developer's Guide

oraub8 offset[10];

for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

offset[i] = 1;

char_amtp[i] = 1000; /* Single byte fixed width char set. */

}

/* Read the 1st 1000 characters for all 10 locators in one

* round trip. Note that offset and amount need not be

* same for all the locators. */

OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_ONE_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);/* character set form */

...

for (i=0; i<10; i++)

{

/* Fill bufp[i] buffers with data to be written */

strncpy (bufp[i], "Test Data------", 15);

bufl[i] = 1000;

offset[i] = 50;

char_amtp[i] = 15; /* Single byte fixed width char set. */

}

/* Write the 15 characters from offset 50 to all 10

* locators in one round trip. Note that offset and

* amount need not be same for all the locators. */

OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_ONE_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);/* character set form */

...

LOB Array Read

Using LOB APIs

22-15

LOB Array Read

Streaming Support

LOB array APIs can be used to read/write LOB data in multiple pieces. This can be done by using polling method or a callback function.

Here data is read/written in multiple pieces sequentially for the array of locators. For polling, the API would return to the application after reading/writing each piece with the array_iter parameter (OUT) indicating the index of the locator for which data is read/written. With a callback, the function is called after reading/writing each piece with array_iter as IN parameter.

Note that:

■

It is possible to read/write data for a few of the locators in one piece and read/write data for other locators in multiple pieces. Data is read/written in one piece for locators which have sufficient buffer lengths to accommodate the whole data to be read/written.

Your application can use different amount value and buffer lengths for each locator.

Your application can pass zero as the amount value for one or more locators indicating pure streaming for those locators. In the case of reading, LOB data is read to the end for those locators. For writing, data is written until

OCI_LAST_PIECE

is specified for those locators.

LOB Array Read in Polling Mode

The following example reads 10Kbytes of data for each of 10 locators with 1Kbyte buffer size. Each locator needs 10 pieces to read the complete data.

OCILobArrayRead()

must be called 100 (10*10) times to fetch all the data.

First we call OCILobArrayRead() with OCI_FIRST_PIECE as piece parameter.

This call returns the first 1K piece for the first locator.

Next OCILobArrayRead() is called in a loop until the application finishes reading all the pieces for the locators and returns OCI_SUCCESS. In this example it loops 99 times returning the pieces for the locators sequentially.

/* Fetch the locators */

...

/* array_iter parameter indicates the number of locators in the array read.

* It is an IN parameter for the 1st call in polling and is ignored as IN

* parameter for subsequent calls. As OUT parameter it indicates the locator

* index for which the piece is read.

ub4 array_iter = 10;

char *bufp[10];

oraub8 bufl[10];

oraub8 char_amtp[10];

oraub8 offset[10];

sword st;

for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

}

22-16

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Array Read

st = OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT); /* character set form */

/* First piece for the first locator is read here.

* bufp[0] => Buffer pointer into which data is read.

* char_amtp[0 ] => Number of characters read in current buffer

While ( st == OCI_NEED_DATA)

{

st = OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_NEXT_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

/* array_iter returns the index of the current array element for which

* data is read. for example, aray_iter = 1 implies first locator,

* array_iter = 2 implies second locator and so on.

* lob_array[ array_iter - 1]=> Lob locator for which data is read.

* bufp[array_iter - 1] => Buffer pointer into which data is read.

* char_amtp[array_iter - 1] => Number of characters read in current buffer

...

/* Consume the data here */

...

}

LOB Array Read with Callback

The following example reads 10Kbytes of data for each of 10 locators with 1Kbyte buffer size. Each locator needs 10 pieces to read all the data. The callback function is called 100 (10*10) times to return the pieces sequentially.

/* Fetch the locators */

...

ub4 array_iter = 10;

char *bufp[10];

oraub8 bufl[10];

Using LOB APIs

22-17

LOB Array Read

oraub8 char_amtp[10];

oraub8 offset[10];

sword st;

for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

}

st = OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

ctx, /* callback context */

cbk_read_lob, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

...

/* Callback function for LOB array read. */ sb4 cbk_read_lob(dvoid *ctxp, ub4 array_iter, CONST dvoid *bufxp, oraub8 len,

ub1 piece, dvoid **changed_bufpp, oraub8 *changed_lenp)

{

static ub4 piece_count = 0;

piece_count++;

switch (piece)

{

case OCI_LAST_PIECE:

/*--- buffer processing code goes here ---*/

(void) printf("callback read the %d th piece(last piece) for %dth locator \n\n",

piece_count, array_iter );

piece_count = 0;

break;

case OCI_FIRST_PIECE:

/*--- buffer processing code goes here ---*/

(void) printf("callback read the 1st piece for %dth locator\n",

array_iter);

/* --Optional code to set changed_bufpp and changed_lenp if the buffer needs

to be changed dynamically --*/

break;

case OCI_NEXT_PIECE:

/*--- buffer processing code goes here ---*/

(void) printf("callback read the %d th piece for %dth locator\n",

piece_count, array_iter);

/* --Optional code to set changed_bufpp and changed_lenp if the buffer

must be changed dynamically --*/

break;

default:

(void) printf("callback read error: unkown piece = %d.\n", piece);

return OCI_ERROR;

}

return OCI_CONTINUE;

}

22-18

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Array Read

...

Polling LOB Array Read

The next example is polling LOB data in OCILobArrayRead() with variable amtp, bufl

, and offset.

/* Fetch the locators */

...

ub4 array_iter = 10;

char *bufp[10];

oraub8 bufl[10];

oraub8 char_amtp[10];

oraub8 offset[10];

sword st;

for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

}

/* For 3rd locator read data in 500 bytes piece from offset 101. Amount

* is 2000, that is, total number of pieces is 2000/500 = 4.

offset[2] = 101; bufl[2] = 500; char_amtp[2] = 2000;

/* For 6th locator read data in 100 bytes piece from offset 51. Amount

* is 0 indicating pure polling, that is, data is read till the end of

* the LOB is reached.

offset[5] = 51; bufl[5] = 100; char_amtp[5] = 0;

/* For 8th locator read 100 bytes of data in one piece. Note amount

* is less than buffer length indicating single piece read.

offset[7] = 61; bufl[7] = 200; char_amtp[7] = 100;

st = OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT); /* character set form */

/* First piece for the first locator is read here.

* bufp[0] => Buffer pointer into which data is read.

* char_amtp[0 ] => Number of characters read in current buffer

Using LOB APIs

22-19

Reading a Portion of a LOB (SUBSTR)

while ( st == OCI_NEED_DATA)

{

st = OCILobArrayRead(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of read buffers */

bufl, /* array of buffer lengths */

OCI_NEXT_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

/* array_iter returns the index of the current array element for which

* data is read. for example, aray_iter = 1 implies first locator,

* array_iter = 2 implies second locator and so on.

* lob_array[ array_iter - 1]=> Lob locator for which data is read.

* bufp[array_iter - 1] => Buffer pointer into which data is read.

* char_amtp[array_iter - 1]=>Number of characters read in current buffer

...

/* Consume the data here */

...

}

Syntax

Use the following syntax references for the OCI programmatic environment:

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobArrayRead()

Example

An example is provided in the following programmatic environment:

OCI: lreadarr.c

Reading a Portion of a LOB (SUBSTR)

This section describes how to read a portion of a LOB using SUBSTR.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — SUBSTR, OPEN, CLOSE

C (OCI): There is no applicable syntax reference for this use case.

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

ALLOCATE, LOB OPEN, LOB READ, LOB CLOSE

22-20

Oracle Database SecureFiles and Large Objects Developer's Guide

Comparing All or Part of Two LOBs

■

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB READ. See PL/SQL DBMS_LOB.SUBSTR.

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lsubstr.sql

OCI: No example is provided with this release.

C++ (OCCI): No example is provided with this release.

COM (OO4O): lsubstr.bas

Java (JDBC): lsubstr.java

Comparing All or Part of Two LOBs

This section describes how to compare all or part of two LOBs.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — COMPARE.

C (OCI): There is no applicable syntax reference for this use case.

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide or information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

EXECUTE. Also reference PL/SQL DBMS_LOB.COMPARE.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — EXECUTE. Also reference PL/SQL

DBMS_LOB.COMPARE

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lcompare.sql

C (OCI): No example is provided with this release.

C++ (OCCI): No example is provided with this release.

COM (OO4O): lcompare.bas

Java (JDBC): lcompare.java

Using LOB APIs

22-21

Patterns: Checking for Patterns in a LOB Using INSTR

This section describes how to see if a pattern exists in a LOB using INSTR.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — INSTR.

C (OCI): There is no applicable syntax reference for this use case.

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

EXECUTE. Also reference PL/SQL DBMS_LOB.INSTR.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — EXECUTE. Also reference PL/SQL

DBMS_LOB.INSTR

COM (OO4O): There is no applicable syntax reference for this use case.

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): linstr.sql

C (OCI): No example is provided with this release.

C++ (OCCI): No example is provided with this release.

COM (OO4O): No example is provided with this release.

Java (JDBC): linstr.java

Length: Determining the Length of a LOB

This section describes how to determine the length of a LOB.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — GETLENGTH

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobGetLength2()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

LOB DESCRIBE.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB DESCRIBE ... GET LENGTH...

COM (OO4O): Oracle Objects for OLE Developer's Guide

22-22

Oracle Database SecureFiles and Large Objects Developer's Guide

Copying All or Part of One LOB to Another LOB

■

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package) llength.sql

OCI: llength.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): llength.bas

Java (JDBC): llength.java

Copying All or Part of One LOB to Another LOB

This section describes how to copy all or part of a LOB to another LOB. These APIs copy an amount of data you specify from a source LOB to a destination LOB.

Usage Notes

Note the following issues when using this API.

Specifying Amount of Data to Copy

The value you pass for the amount parameter to the DBMS_LOB.COPY function must be one of the following:

■

An amount less than or equal to the actual size of the data you are loading.

The maximum allowable LOB size: DBMS_LOB.LOBMAXSIZE.Passing this value causes the function to read the entire LOB. This is a useful technique for reading the entire LOB without introspecting the size of the LOB.

Note that for character data, the amount is specified in characters, while for binary data, the amount is specified in bytes.

Locking the Row Prior to Updating

If you plan to update a LOB value, then you must lock the row containing the LOB prior to updating. While the SQL INSERT and UPDATE statements implicitly lock the row, locking is done explicitly by means of a SQL SELECT FOR UPDATE statement in

SQL and PL/SQL programs, or by using an OCI pin or lock function in OCI programs.

For more details on the state of the locator after an update, refer to "Example of

Updating LOBs Through Updated Locators" on page 12-12.

Syntax

See the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — COPY

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobCopy2

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

Using LOB APIs

22-23

Copying a LOB Locator

■

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

LOB COPY

. Also reference PL/SQL DBMS_LOB.COPY.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide for information on embedded

SQL statements and directives — LOB COPY

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lcopy.sql

OCI: lcopy.c

COM (OO4O): lcopy.bas

Java (JDBC): lcopy.java

Copying a LOB Locator

This section describes how to copy a LOB locator. Note that different locators may point to the same or different data, or to current or outdated data.

Note:

To assign one LOB to another using PL/SQL, use the :=

operator. This is discussed in more detail in "Read-Consistent

Locators" on page 12-10.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Refer to "Read-Consistent Locators" on page 12-10

for information on assigning one lob locator to another.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobAssign()

, OCILobIsEqual().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB Statements, and embedded SQL and precompiler directives —

ALLOCATE, LOB ASSIGN.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — SELECT, LOB ASSIGN

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lcopyloc.sql

OCI: lcopyloc.c

22-24

Oracle Database SecureFiles and Large Objects Developer's Guide

Determining Whether LOB Locator Is Initialized

■

C++ (OCCI): No example is provided with this release.

COM (OO4O): lcopyloc.bas

Java (JDBC): lcopyloc.java

Equality: Checking If One LOB Locator Is Equal to Another

This section describes how to determine whether one LOB locator is equal to another.

If two locators are equal, then this means that they refer to the same version of the

LOB data.

Determining Whether LOB Locator Is Initialized

This section describes how to determine whether a LOB locator is initialized.

Appending to a LOB

This section describes how to write-append the contents of a buffer to a LOB.

Writing Singly or Piecewise

The writeappend operation writes a buffer to the end of a LOB.

For OCI, the buffer can be written to the LOB in a single piece with this call; alternatively, it can be rendered piecewise using callbacks or a standard polling method.

Writing Piecewise: When to Use Callbacks or Polling

If the value of the piece parameter is OCI_FIRST_PIECE, then data must be provided through callbacks or polling.

■

If a callback function is defined in the cbfp parameter, then this callback function is called to get the next piece after a piece is written to the pipe. Each piece is written from bufp.

If no callback function is defined, then OCILobWriteAppend2() returns the

OCI_NEED_DATA

error code. The application must call OCILobWriteAppend2() again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations. A piece value of OCI_LAST_PIECE terminates the piecewise write.

22-26

Oracle Database SecureFiles and Large Objects Developer's Guide

Writing Data to a LOB

Locking the Row Prior to Updating

Prior to updating a LOB value using the PL/SQL

DBMS_LOB

package or the OCI, you must lock the row containing the LOB. While the

SQL INSERT and UPDATE statements implicitly lock the row, locking is done explicitly by means of an SQL SELECT FOR UPDATE statement in SQL and PL/SQL programs, or by using an OCI pin or lock function in OCI programs.

For more details on the state of the locator after an update, refer to "Example of

Updating LOBs Through Updated Locators" on page 12-12.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — WRITEAPPEND

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobWriteAppend2()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB WRITE APPEND

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB WRITE APPEND

COM (OO4O): No syntax reference is provided with this release.

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lwriteap.sql

OCI: lwriteap.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): No example is provided with this release.

Java (JDBC): lwriteap.java

Writing Data to a LOB

This section describes how to write the contents of a buffer to a LOB.

Stream Write

The most efficient way to write large amounts of LOB data is to use OCILobWrite2() with the streaming mechanism enabled, and using polling or a callback. If you know

Using LOB APIs

22-27

Writing Data to a LOB how much data is written to the LOB, then specify that amount when calling

OCILobWrite2()

. This ensures that LOB data on the disk is contiguous. Apart from being spatially efficient, the contiguous structure of the LOB data makes reads and writes in subsequent operations faster.

Chunk Size

OCILobGetChunkSize()

Use a Multiple of the Returned Value to Improve Write Performance

To improve performance, run write requests using a multiple of the value returned by one of these functions. The reason for this is that the LOB chunk is versioned for every write

operation. If all writes are done on a chunk basis, then no extra or excess versioning is incurred or duplicated. If it is appropriate for your application, then you should batch writes until you have enough for an entire chunk instead of issuing several LOB write calls that operate on the same LOB chunk.

Locking the Row Prior to Updating

Prior to updating a LOB value using the PL/SQL DBMS_LOB Package or OCI, you must lock the row containing the LOB. While the SQL INSERT and UPDATE statements implicitly lock the row, locking is done explicitly by means of a SQL SELECT FOR

UPDATE

statement in SQL and PL/SQL programs, or by using an OCI pin or lock function in OCI programs.

For more details on the state of the locator after an update, refer to "Example of

Updating LOBs Through Updated Locators" on page 12-12.

Using DBMS_LOB.WRITE to Write Data to a BLOB

When you are passing a hexadecimal string to DBMS_LOB.WRITE() to write data to a

BLOB, use the following guidelines:

■

The amount parameter should be <= the buffer length parameter

The length of the buffer should be ((amount*2) - 1). This guideline exists because the two characters of the string are seen as one hexadecimal character (and an implicit hexadecimal-to-raw conversion takes place), that is, every two bytes of the string are converted to one raw byte.

The following example is correct: declare

blob_loc BLOB;

rawbuf RAW(10);

an_offset INTEGER := 1;

an_amount BINARY_INTEGER := 10;

BEGIN

select blob_col into blob_loc from a_table where id = 1;

rawbuf := '1234567890123456789';

dbms_lob.write(blob_loc, an_amount, an_offset, rawbuf);

commit;

22-28

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Array Write

END;

Replacing the value for an_amount in the previous example with the following values, yields error message, ora_21560:

an_amount BINARY_INTEGER := 11; or

an_amount BINARY_INTEGER := 19;

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — WRITE

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobWrite2().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB WRITE

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB WRITE

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lwrite.sql

OCI: lwrite.c

COM (OO4O): lwrite.bas

Java (JDBC): lwrite.java

LOB Array Write

This section describes how to write LOB data for multiple locators in one round trip, using OCILobArrayWrite().

Usage Notes

LOB Array Write in Polling Mode

The following example writes 10Kbytes of data for each of 10 locators with a 1K buffer size. OCILobArrayWrite() has to be called 100 (10 times 10) times to write all the data. The function is used in a similar manner to OCILobWrite2().

/* Fetch the locators */

Using LOB APIs

22-29

LOB Array Write

...

/* array_iter parameter indicates the number of locators in the array read.

* It is an IN parameter for the 1st call in polling and is ignored as IN

* parameter for subsequent calls. As an OUT parameter it indicates the locator

* index for which the piece is written.

*/ ub4 array_iter = 10; char *bufp[10]; oraub8 bufl[10]; oraub8 char_amtp[10]; oraub8 offset[10]; sword st; int i, j; for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

/* Fill bufp here. */

...

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

} for (i = 1; i <= 10; i++)

{

/* Fill up bufp[i-1] here. The first piece for ith locator would be written from

bufp[i-1] */

...

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT); /* character set form */

for ( j = 2; j < 10; j++)

{

/* Fill up bufp[i-1] here. The jth piece for ith locator would be written from

bufp[i-1] */

...

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_NEXT_PIECE, /* piece information */

NULL, /* callback context */

22-30

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Array Write

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

/* array_iter returns the index of the current array element for which

* data is being written. for example, aray_iter = 1 implies first locator,

* array_iter = 2 implies second locator and so on. Here i = array_iter.

* lob_array[ array_iter - 1] => Lob locator for which data is written.

* bufp[array_iter - 1] => Buffer pointer from which data is written.

* char_amtp[ array_iter - 1] => Number of characters written in

* the piece just written

}

/* Fill up bufp[i-1] here. The last piece for ith locator would be written from

bufp[i -1] */

...

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_LAST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

}

...

LOB Array Write with Callback

The following example writes 10Kbytes of data for each of 10 locators with a 1K buffer size. A total of 100 pieces must be written (10 pieces for each locator). The first piece is provided by the OCILobArrayWrite() call. The callback function is called 99 times to get the data for subsequent pieces to be written.

/* Fetch the locators */

...

ub4 array_iter = 10;

char *bufp[10];

oraub8 bufl[10];

oraub8 char_amtp[10];

oraub8 offset[10];

sword st;

for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

bufl[i] = 1000;

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

}

st = OCILobArrayWrite(<service context>, <error handle>,

Using LOB APIs

22-31

LOB Array Write

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

ctx, /* callback context */

cbk_write_lob /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

...

/* Callback function for LOB array write. */ sb4 cbk_write_lob(dvoid *ctxp, ub4 array_iter, dvoid *bufxp, oraub8 *lenp,

ub1 *piecep, ub1 *changed_bufpp, oraub8 *changed_lenp)

{

static ub4 piece_count = 0;

piece_count++;

printf (" %dth piece written for %dth locator \n\n", piece_count, array_iter);

/*-- code to fill bufxp with data goes here. *lenp should reflect the size and

* should be less than or equal to MAXBUFLEN -- */

/* --Optional code to set changed_bufpp and changed_lenp if the buffer must

* be changed dynamically --*/

if (this is the last data buffer for current locator)

*piecep = OCI_LAST_PIECE;

else if (this is the first data buffer for the next locator)

*piecep = OCI_FIRST_PIECE;

piece_count = 0;

else

*piecep = OCI_NEXT_PIECE;

return OCI_CONTINUE;

}

...

Polling LOB Data in Array Write

The next example is polling LOB data in OCILobArrayWrite() with variable amtp, bufl

, and offset.

/* Fetch the locators */

...

ub4 array_iter = 10; char *bufp[10]; oraub8 bufl[10]; oraub8 char_amtp[10]; oraub8 offset[10]; sword st; int i, j; int piece_count; for (i=0; i<10; i++)

{

bufp[i] = (char *)malloc(1000);

22-32

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Array Write

bufl[i] = 1000;

/* Fill bufp here. */

...

offset[i] = 1;

char_amtp[i] = 10000; /* Single byte fixed width char set. */

}

/* For 3rd locator write data in 500 bytes piece from offset 101. Amount

* is 2000, that is, total number of pieces is 2000/500 = 4.

offset[2] = 101; bufl[2] = 500; char_amtp[2] = 2000;

/* For 6th locator write data in 100 bytes piece from offset 51. Amount

* is 0 indicating pure polling, that is, data is written

* till OCI_LAST_PIECE

offset[5] = 51; bufl[5] = 100; char_amtp[5] = 0;

/* For 8th locator write 100 bytes of data in one piece. Note amount

* is less than buffer length indicating single piece write.

offset[7] = 61; bufl[7] = 200; char_amtp[7] = 100; for (i = 1; i <= 10; i++)

{

/* Fill up bufp[i-1] here. The first piece for ith locator would be written from

bufp[i-1] */

...

/* Calculate number of pieces that must be written */

piece_count = char_amtp[i-1]/bufl[i-1];

/* Single piece case */

if (char_amtp[i-1] <= bufl[i-1])

piece_count = 1;

/* Zero amount indicates pure polling. So we can write as many

* pieces as needed. Let us write 50 pieces.

if (char_amtp[i-1] == 0)

piece_count = 50;

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_FIRST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT); /* character set form */

for ( j = 2; j < piece_count; j++)

{

/* Fill up bufp[i-1] here. The jth piece for ith locator would be written

* from bufp[i-1] */

...

Using LOB APIs

22-33

LOB Array Write

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_NEXT_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

/* array_iter returns the index of the current array element for which

* data is being written. for example, aray_iter = 1 implies first locator,

* array_iter = 2 implies second locator and so on. Here i = array_iter.

* lob_array[ array_iter - 1] => Lob locator for which data is written.

* bufp[array_iter - 1] => Buffer pointer from which data is written.

* char_amtp[ array_iter - 1] => Number of characters written in

* the piece just written

}

/* Fill up bufp[i-1] here. The last piece for ith locator would be written from

* bufp[i -1] */

...

/* If piece_count is 1 it is a single piece write. */ if (piece_count[i] != 1)

st = OCILobArrayWrite(<service context>, <error handle>,

&array_iter, /* array size */

lob_array, /* array of locators */

NULL, /* array of byte amounts */

char_amtp, /* array of char amounts */

offset, /* array of offsets */

(void **)bufp, /* array of write buffers */

bufl, /* array of buffer lengths */

OCI_LAST_PIECE, /* piece information */

NULL, /* callback context */

NULL, /* callback function */

0, /* character set ID - default */

SQLCS_IMPLICIT);

}

...

Syntax

Use the following syntax references for the OCI programmatic environment:

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobArrayWrite()

Example

An example is provided in the following programmatic environment:

OCI: lwritearr.c

22-34

Oracle Database SecureFiles and Large Objects Developer's Guide

Erasing Part of a LOB

Trimming LOB Data

This section describes how to trim a LOB to the size you specify.

Locking the Row Prior to Updating

Prior to updating a LOB value using the PL/SQL DBMS_LOB Package, or OCI, you must lock the row containing the LOB. While the SQL INSERT and UPDATE statements implicitly lock the row, locking is done explicitly by means of:

■

A SELECT FOR UPDATE statement in SQL and PL/SQL programs.

An OCI pin or lock function in OCI programs.

For more details on the state of the locator after an update, refer to "Example of

Updating LOBs Through Updated Locators" on page 12-12.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — TRIM

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobTrim2().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB TRIM

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL and Precompiler Directives" — LOB TRIM

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference Chapter 7,

"Working With LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): ltrim.sql

OCI: ltrim.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): ltrim.bas

Java (JDBC): ltrim.java

Erasing Part of a LOB

This section describes how to erase part of a LOB.

Using LOB APIs

22-35

Enabling LOB Buffering

Locking the Row Prior to Updating

Prior to updating a LOB value using the PL/SQL DBMS_LOB Package or OCI, you must lock the row containing the LOB. While INSERT and UPDATE statements implicitly lock the row, locking is done explicitly by means of a SELECT FOR UPDATE statement in SQL and PL/SQL programs, or by using the OCI pin or lock function in

OCI programs.

For more details on the state of the locator after an update, refer to

"Example of

Updating LOBs Through Updated Locators" on page 12-12.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): Oracle Database PL/SQL Packages and Types

Reference "DBMS_LOB" — ERASE

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCILobErase2()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB ERASE

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL and Precompiler Directives" — LOB ERASE

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): Oracle Database JDBC Developer's Guide and Reference, "Working With

LOBs" — Creating and Populating a BLOB or CLOB Column.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): lerase.sql

OCI: lerase.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): lerase.bas

Java (JDBC): lerase.java

Enabling LOB Buffering

This section describes how to enable LOB buffering.

Note:

■

You must flush the buffer in order to make your modifications persistent.

Do not enable buffering for the stream read and write involved in checkin and checkout.

For more information, refer to "LOB Buffering Subsystem" on page 12-1.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL: This API is not available in any supplied PL/SQL packages.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCIEnableLobBuffering()

, OCIDisableLobBuffering(),

OCIFlushBuffer()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB ENABLE BUFFERING.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL and Precompiler Directives" — LOB ENABLE BUFFERING

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): There is no applicable syntax reference for this use case.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL: No example is provided.

C (OCI): No example is provided with this release. Using this API is similar to that

described in the example, "Disabling LOB Buffering" on page 22-38.

C++ (OCCI): No example is provided with this release.

COM (OO4O): lenbuf.bas

Java (JDBC): No example provided.

Flushing the Buffer

This section describes how to flush the LOB buffer.

Notes:

■

You must flush the buffer in order to make your modifications persistent.

Do not enable buffering for the stream read and write involved in checkin and checkout.

For more information, refer to "LOB Buffering Subsystem" on page 12-1.

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): There is no applicable syntax reference for this use case.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCIEnableLobBuffering(), OCIDisableLobBuffering(), OCIFlushBuffer().

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB FLUSH BUFFER.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB FLUSH BUFFER.

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): There is no applicable syntax reference for this use case.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): No example is provided with this release.

C (OCI): No example is provided with this release. Using this API is similar to that

described in the example, "Disabling LOB Buffering" on page 22-38.

C++ (OCCI): No example is provided with this release.

COM (OO4O): No example is provided with this release.

Java (JDBC): No example is provided with this release.

Disabling LOB Buffering

This section describes how to disable LOB buffering.

Note:

■

You must flush the buffer in order to make your modifications persistent.

Do not enable buffering for the stream read and write involved in checkin and checkout.

For more information, refer to "LOB Buffering Subsystem" on page 12-1

Syntax

Use the following syntax references for each programmatic environment:

■

PL/SQL (DBMS_LOB Package): There is no applicable syntax reference for this use case.

C (OCI): Oracle Call Interface Programmer's Guide "LOB Functions" —

OCIEnableLobBuffering()

, OCIDisableLobBuffering(),

OCIFlushBuffer()

C++ (OCCI): Oracle C++ Call Interface Programmer's Guide

COBOL (Pro*COBOL) Pro*COBOL Programmer's Guide for information on LOBs, usage notes on LOB statements, and embedded SQL and precompiler directives —

LOB DISABLE BUFFER.

C/C++ (Pro*C/C++): Pro*C/C++ Programmer's Guide Appendix F, "Embedded SQL

Statements and Directives" — LOB DISABLE BUFFER

COM (OO4O): Oracle Objects for OLE Developer's Guide

Java (JDBC): There is no applicable syntax reference for this use case.

Examples

Examples are provided in the following programmatic environments:

■

PL/SQL (DBMS_LOB Package): No example is provided with this release.

OCI: ldisbuf.c

C++ (OCCI): No example is provided with this release.

COM (OO4O): ldisbuf.bas

Java (JDBC): No example is provided with this release.

Determining Whether a LOB instance Is Temporary

This section describes how to determine whether a LOB instance is temporary.

Java (JDBC): Determining Whether a BLOB Is Temporary

To see if a BLOB is temporary, the JDBC application can either use the isTemporary instance method to determine whether the current BLOB object is temporary, or pass the BLOB object to the static isTemporary method to determine whether the specified

BLOB

object is temporary. These two methods are defined inlistempb.java.

This JDBC API replaces previous work-arounds that use

DBMS_LOB.isTemporary().

To determine whether a CLOB is temporary, the JDBC application can either use the isTemporary

instance method to determine whether the current CLOB object is temporary, or pass the CLOB object to the static isTemporary method. These two methods are defined in listempc.java.

Converting a BLOB to a CLOB

You can convert a BLOB instance to a CLOB using the PL/SQL procedure

DBMS_LOB.CONVERTTOCLOB

. This technique is convenient if you have character data stored in binary format that you want to store in a CLOB. You specify the character set of the binary data when calling this procedure. See Oracle Database PL/SQL Packages

and Types Reference for details on syntax and usage of this procedure.

Converting a CLOB to a BLOB

You can convert a CLOB instance to a BLOB instance using the PL/SQL procedure

DBMS_LOB.CONVERTTOBLOB

. This technique is a convenient way to convert character data to binary data using LOB APIs. See Oracle Database PL/SQL Packages and Types

Reference for details on syntax and usage of this procedure.

22-40

Oracle Database SecureFiles and Large Objects Developer's Guide

Ensuring Read Consistency

This script can be used to ensure that hot backups can be taken of tables that have

NOLOGGING

or FILESYSTEM_LIKE_LOGGING LOBs and have a known recovery point with no read inconsistencies:

ALTER DATABASE FORCE LOGGING;

SELECT CHECKPOINT_CHANGE# FROM V$DATABASE; --Start SCN

SCN (System Change Number) is a stamp that defines a version of the database at the time that a transaction is committed.

Perform the backup.

Run the next script:

ALTER SYSTEM CHECKPOINT GLOBAL;

SELECT CHECKPOINT_CHANGE# FROM V$DATABASE; --End SCN

ALTER DATABASE NO FORCE LOGGING;

Back up the archive logs generated by the database. At the minimum, archive logs between start SCN and end SCN (including both SCN points) must be backed up.

To restore to a point with no read inconsistency, restore to end SCN as your incomplete recovery point. If recovery is done to an SCN after end SCN, there can be read inconsistency in the NOLOGGING LOBs.

For SecureFiless, if a read inconsistency is found during media recovery, the database treats the inconsistent blocks as holes and fills BLOBs with 0's and CLOBs with fill characters.

Using LOB APIs

22-41

Ensuring Read Consistency

22-42

Oracle Database SecureFiles and Large Objects Developer's Guide

LOB Demonstration Files

This appendix describes files distributed with the database that demonstrate how

LOBs are used in supported programmatic environments. This appendix contains these topics:

■

PL/SQL LOB Demonstration Files

OCI LOB Demonstration Files

■

COM OO4O LOB Demonstration Files

Java LOB Demonstration Files

PL/SQL LOB Demonstration Files

The following table lists PL/SQL demonstration files. These files are installed in

$ORACLE_HOME/rdbms/demo/lobs/plsql/

. A driver program, lobdemo.sql, that calls these files is found in the same directory.

Table A–1 PL/SQL Demonstration Examples

File Name

fclose_c.sql

fclose_f.sql

fclosea.sql

fcompare.sql

fcopyloc.sql

fdisplay.sql

fexists.sql

ffilopen.sql

Description

Closing a BFILE with CLOSE

Closing a BFILE with FILECLOSE

Closing all open BFILEs

Comparing all or parts of two BFILEs

Copying a LOB locator for a BFILE

Displaying BFILE data

Checking if a BFILE exists

Opening a BFILE with FILEOPEN ffisopen.sql

Checking if the BFILE is OPEN with

FILEISOPEN fgetdir.sql

Getting the directory object name and filename of a BFILE

Usage Information

Comparing All or Parts of Two BFILES on page 21-17

Assigning a BFILE Locator on page 21-20

Opening a BFILE with FILEOPEN on page 21-12

Determining Whether a BFILE Is Open with FILEISOPEN on page 21-14

Getting Directory Object Name and File

Name of a BFILE on page 21-21

LOB Demonstration Files

A-1

PL/SQL LOB Demonstration Files

Table A–1 (Cont.) PL/SQL Demonstration Examples

File Name Description Usage Information

finsert.sql

fisopen.sql

flength.sql

Inserting row containing a BFILE by initializing a BFILE locator

Checking if the BFILE is open with ISOPEN

Getting the length of a BFILE

Using ISOPEN on page 21-13

Getting the Length of a BFILE on page 21-19

floadlob.sql

fopen.sql

Loading a LOB with BFILE data

Opening a BFILE with OPEN fpattern.sql

Checking if a pattern exists in a BFILE using fread.sql

lcopy.sql

instr

Reading data from a BFILE freadprt.sql

fupdate.sql

Reading portion of a BFILE data using substr

Reading a Portion of BFILE Data Using

SUBSTR on page 21-17

Updating a BFILE by initializing a BFILE locator

Updating a BFILE by Initializing a

BFILE Locator on page 21-21

lappend.sql

Appending one LOB to another lcompare.sql

Comparing all or part of LOB

Copying all or part of a LOB to another LOB

Checking If a Pattern Exists in a BFILE

Using INSTR on page 21-18

lcopyloc.sql

ldisplay.sql

lerase.sql

linsert.sql

linstr.sql

lisopen.sql

listemp.sql

Copying a LOB locator

Displaying LOB data

Erasing part of a LOB

Inserting a row by initializing LOB locator bind variable

Seeing if pattern exists in LOB (instr)

Seeing if LOB is open

Seeing if LOB is temporary

Inserting a Row by Initializing a LOB

Locator Bind Variable on page 15-6

Patterns: Checking for Patterns in a LOB

Using INSTR on page 22-22

Determining Whether a LOB is Open on page 22-10

Loading a BLOB with Data from a

lldblobf.sql

Using DBMS_LOB.LOADBLOBFROMFILE to load a BLOB with data from a BFILE lldclobf.sql

Using DBMS_LOB.LOADCLOBFROMFILE to load a CLOB or NCLOB with data from a BFILE lldclobs.sql

Using DBMS_LOB.LOADCLOBFROMFILE to load segments of a stream of data from a BFILE into different CLOBs llength.sql

Getting the length of a LOB

BFILE on page 22-7

Loading a CLOB or NCLOB with Data from a BFILE on page 22-9

Length: Determining the Length of a

LOB on page 22-22

A-2

Oracle Database SecureFiles and Large Objects Developer's Guide

OCI LOB Demonstration Files

Table A–1 (Cont.) PL/SQL Demonstration Examples

File Name Description

lloaddat.sql

Loading a LOB with BFILE data lobuse.sql

lread.sql

lsubstr.sql

Examples of LOB API usage.

Reading data from LOB

Reading portion of LOB (substr) ltrim.sql

Trimming LOB data lwrite.sql

Writing data to a LOB lwriteap.sql

Writing to the end of LOB (write append)

Usage Information

Loading a LOB with Data from a BFILE on page 22-6

Creating Persistent and Temporary

LOBs in PL/SQL on page 19-3

Reading a Portion of a LOB (SUBSTR) on page 22-20

Appending to a LOB on page 22-26

OCI LOB Demonstration Files

The following table lists OCI demonstration files. These files are installed in

$ORACLE_HOME/rdbms/demo/lobs/oci/

. A driver program, lobdemo.c, that calls these files is found in the same directory, as is the header file lobdemo.h.

Table A–2 OCI Demonstration Examples

File Name

fclose_c.c

fclose_f.c

fclosea.c

fcopyloc.c

fdisplay.c

fexists.c

ffilopen.c

ffisopen.c

fgetdir.c

finsert.c

fisopen.c

flength.c

floadlob.c

fopen.c

Description

Closing a BFILE with CLOSE

Closing a BFILE with FILECLOSE

Closing all open BFILEs

Copying a LOB locator for a BFILE

Displaying BFILE data

Checking if a BFILE exists

Opening a BFILE with FILEOPEN

Checking if the BFILE is OPEN with

FILEISOPEN

Getting the directory object name and filename of a BFILE

Inserting row containing a BFILE by initializing a BFILE locator

Checking if the BFILE is open with

ISOPEN

Getting the length of a BFILE

Loading a LOB with BFILE data

Opening a BFILE with OPEN

Usage Information

Assigning a BFILE Locator on page 21-20

Opening a BFILE with FILEOPEN on page 21-12

Determining Whether a BFILE Is Open with FILEISOPEN on page 21-14

Getting Directory Object Name and File

Name of a BFILE on page 21-21

Using ISOPEN on page 21-13

Getting the Length of a BFILE on page 21-19

LOB Demonstration Files

A-3

COM OO4O LOB Demonstration Files

Table A–2 (Cont.) OCI Demonstration Examples

File Name

fread.c

fupdate.c

lappend.c

lcopy.c

lcopyloc.c

ldisbuf.c

ldisplay.c

lequal.c

lerase.c

lgetchar.c

lgetchfm.c

linit.c

linsert.c

lisopen.c

listemp.c

llength.c

lloaddat.c

lread.c

lreadarr.c

ltrim.c

lwrite.c

lwritearr.c

lwriteap.c

Description

Reading data from a BFILE

Updating a BFILE by initializing a

BFILE locator

Appending one LOB to another

Copying all or part of a LOB to another LOB

Copying a LOB locator

Usage Information

Updating a BFILE by Initializing a BFILE

Locator on page 21-21

Disabling LOB Buffering on page 22-38

Disabling LOB buffering (persistent

LOBs)

Displaying LOB data

Seeing if one LOB locator is equal to another

Erasing part of a LOB

Getting character set id

Getting character set form of the foreign language ad text, ad_fltextn

Seeing if a LOB locator is initialized

Equality: Checking If One LOB Locator Is

Equal to Another on page 22-25

Determining Character Set ID on page 22-5

Determining Character Set Form on page 22-5

Inserting a row by initializing LOB locator bind variable

Seeing if LOB is open

Seeing if LOB is temporary

Getting the length of a LOB

Loading a LOB with BFILE data

Reading data from LOB

Reading data from an array of LOB locators

Trimming LOB data

Writing data to a LOB

Writing data into an array of LOB locators

Writing to the end of LOB (write append)

Determining Whether LOB Locator Is

Initialized on page 22-25

Inserting a Row by Initializing a LOB

Locator Bind Variable on page 15-6

Determining Whether a LOB is Open on page 22-10

Length: Determining the Length of a LOB on page 22-22

Loading a LOB with Data from a BFILE on page 22-6

LOB Array Read on page 22-14

Trimming LOB Data

LOB Array Write

on page 22-35

Appending to a LOB on page 22-26

on page 22-29

COM OO4O LOB Demonstration Files

The following table lists COM OO4O demonstration files. These files are installed in

$ORACLE_HOME/rdbms/demo/lobs/vb/

A-4

Oracle Database SecureFiles and Large Objects Developer's Guide

COM OO4O LOB Demonstration Files

Table A–3 COM OO4O Demonstration Examples

File Name

fclose_c.bas

fclosea.bas

fcompare.bas

fdisplay.bas

fexists.bas

fgetdir.bas

finsert.bas

fisopen.bas

flength.bas

floadlob.bas

fopen.bas

fread.bas

freadprt.bas

fupdate.bas

lappend.bas

lcompare.bas

lcopy.bas

lcopyloc.bas

ldisbuf.bas

ldisplay.bas

lenbuf.bas

lerase.bas

linsert.bas

llength.bas

Description Usage Information

Closing a BFILE with CLOSE

Displaying BFILE data

Checking if a BFILE exists

Closing all open BFILEs

Comparing All or Parts of Two BFILES on page 21-17

Comparing all or parts of two BFILEs

Getting Directory Object Name and

Getting the directory object name and filename of a BFILE

File Name of a BFILE on page 21-21

Inserting row containing a BFILE by initializing a BFILE locator

Checking if the BFILE is open with

ISOPEN

Getting the length of a BFILE

Loading a LOB with BFILE data

Opening a BFILE with OPEN

Getting the Length of a BFILE page 21-19

Using ISOPEN

on page 21-13

Reading data from a BFILE

Reading a Portion of BFILE Data Using

Reading portion of a BFILE data using substr

SUBSTR on page 21-17

Updating a BFILE by initializing a

BFILE

locator

Appending one LOB to another

Comparing all or part of LOB

Copying all or part of a LOB to another LOB

Copying a LOB locator

Updating a BFILE by Initializing a

BFILE Locator

Appending One LOB to Another page 22-4

on page 21-21

Disabling LOB Buffering on page 22-38

Disabling LOB buffering (persistent

LOBs)

Displaying LOB data

Enabling LOB buffering

Erasing part of a LOB

Inserting a row by initializing LOB locator bind variable

Getting the length of a LOB

Enabling LOB Buffering on page 22-36

Inserting a Row by Initializing a LOB

Locator Bind Variable on page 15-6

Length: Determining the Length of a

LOB on page 22-22

LOB Demonstration Files

A-5

Java LOB Demonstration Files

Table A–3 (Cont.) COM OO4O Demonstration Examples

File Name

lloaddat.bas

Description

Loading a LOB with BFILE data lread.bas

lsubstr.bas

ltrim.bas

lwrite.bas

Reading data from LOB

Reading portion of LOB (substr)

Trimming LOB data

Writing data to a LOB

Usage Information

Loading a LOB with Data from a

BFILE on page 22-6

Reading a Portion of a LOB (SUBSTR) on page 22-20

Java LOB Demonstration Files

The following table lists Java demonstration files. These files are installed in

$ORACLE_HOME/rdbms/demo/lobs/java/

Table A–4 Java Demonstration Examples

File Name

Readme.txt

LobDemoConnectionFactory.java

fclose_c.java

fclose_f.java

fclosea.java

fcompare.java

fexists.java

ffilopen.java

ffisopen.java

fgetdir.java

finsert.java

fisopen.java

Description

Usage Information

See the Chapter "Getting Started" in the "Oracle

Database JDBC Developer's Guide and

Reference" for information on setting up your system to be able to compile and run JDBC programs with the Oracle Driver

As written LobDemoConnectionFactory uses the JDBC OCI driver with a local connection.

You should edit the URL "jdbc:oracle:oci8:@" to match your setup. Again see the "Getting

Started" section in the JDBC manual.

Closing a BFILE with

FILECLOSE

Closing All Open BFILEs with FILECLOSEALL on page 21-24

Closing all open BFILEs

Comparing all or parts of two BFILEs

Checking if a BFILE exists

Opening a BFILE with

FILEOPEN

Comparing All or Parts of Two BFILES page 21-17

Determining Whether a BFILE Exists page 21-19

Opening a BFILE with FILEOPEN

on page 21-12

Checking if the BFILE is

OPEN with

FILEISOPEN

Determining Whether a BFILE Is Open with

FILEISOPEN on page 21-14

Getting the directory object name and filename of a BFILE

Getting Directory Object Name and File Name of a BFILE on page 21-21

Inserting row containing a BFILE by initializing a

BFILE

locator

Determining Whether a BFILE Is Open Using

Checking if the BFILE is open with ISOPEN

ISOPEN on page 21-13

A-6

Oracle Database SecureFiles and Large Objects Developer's Guide

Java LOB Demonstration Files

Table A–4 (Cont.) Java Demonstration Examples

File Name

flength.java

Description

Getting the length of a

BFILE fopen.java

fpattern.java

fread.java

fupdate.java

lappend.java

lcompare.java

lcopy.java

lerase.java

linsert.java

linstr.java

lisopen.java

listempb.java

listempc.java

llength.java

lloaddat.java

lread.java

lsubstr.java

ltrim.java

lwrite.java

lwriteap.java

Usage Information

Getting the Length of a BFILE on page 21-19

Opening a BFILE with

OPEN

Checking if a pattern exists in a BFILE using instr

Reading data from a

BFILE

Opening a BFILE with OPEN

Checking If a Pattern Exists in a BFILE Using

INSTR on page 21-18

Reading Data from a BFILE

on page 21-11

on page 21-15

Updating a BFILE by initializing a BFILE locator

Updating a BFILE by Initializing a BFILE

Locator on page 21-21

Appending one LOB to another

Comparing all or part of

LOB

Inserting a Row by Initializing a LOB Locator

Copying all or part of a

LOB to another LOB

Erasing part of a LOB

Inserting a row by initializing LOB locator bind variable

Bind Variable on page 15-6

Seeing if pattern exists in

LOB (instr)

Patterns: Checking for Patterns in a LOB Using

INSTR on page 22-22

Seeing if LOB is open

Copying All or Part of One LOB to Another LOB on page 22-23

Determining Whether a LOB is Open on page 22-10

Seeing if LOB is temporary

Getting the length of a

LOB

Length: Determining the Length of a LOB on page 22-22

Loading a LOB with

BFILE data

Loading a LOB with Data from a BFILE page 22-6

Reading data from LOB

Reading a Portion of a LOB (SUBSTR) page 22-20

Reading portion of LOB

(substr)

Trimming LOB data

Writing data to a LOB

Writing to the end of

LOB (write append)