2
Working with LOBs

This chapter describes the usage and semantics of LOBs that you need to be familiar with to use LOBs in your application. Various techniques for working with LOBs are covered.

Most of the discussions in this chapter regarding persistent LOBs assume that you are dealing with LOBs in tables that already exist. The task of creating tables with LOB columns is typically performed by your database administrator. See Chapter 4, "LOBs in Tables" of this guide for details on creating tables with LOB columns.

This chapter includes the following sections:

• LOB Column States
• Locking a Row Containing a LOB
• Opening and Closing LOBs
• LOB Locator and LOB Value
• LOB Locators and BFILE Locators
• Accessing LOBs
• LOB Restrictions

LOB Column States

The techniques you use when accessing a cell in a LOB column differ depending on the state of the given cell. A cell in a LOB Column can be in one of the following states:

• NULL

  The table cell is created, but the cell holds no locator or value.

• Empty

  A LOB instance with a locator exists in the cell, but it has no value. The length of the LOB is zero.

• Populated

  A LOB instance with a locator and a value exists in the cell.

Locking a Row Containing a LOB

You can lock a row containing a LOB to prevent other database users from writing to the LOB during a transaction. To lock a row containing a LOB, specify the FOR UPDATE clause when you select the row. While the row is locked, other users cannot lock or update a the LOB, until you end your transaction.

Opening and Closing LOBs

The LOB APIs include operations that enable you to explicitly open and close a LOB instance. You can open and close a persistent LOB instance of any type: BLOB, CLOB, NCLOB, or BFILE. You open a LOB to achieve one or both of the following results:

• Open the LOB in read only mode.

  This ensures that the LOB (both the LOB locator and LOB value) cannot be changed in your session until you explicitly close the LOB. For example, you can open the LOB to ensure that the LOB is not changed by some other part of your program while you are using the LOB in a critical operation. After you perform the operation, you can then close the LOB.

• Open the LOB in read write mode--persistent BLOB, CLOB, or NCLOB instances only.

  Opening a LOB in read write mode defers any index maintenance on the LOB column until you close the LOB. Opening a LOB in read write mode is only useful if there is an extensible index on the LOB column and you do not want the database to perform index maintenance every time you write to the LOB. This technique can increase the performance of your application if you are doing several write operations on the LOB while it is open.

If you open a LOB, then you must close the LOB at some point later in your session. This is the only requirement for an open LOB. While a LOB instance is open, you can perform as many operations as you want on the LOB--provided the operations are allowed in the given mode.

LOB Locator and LOB Value

There are two techniques that you can use to access and modify LOB values:

• Using the Data Interface for LOBs
• Using the LOB Locator to Access and Modify LOB Values

Using the Data Interface for LOBs

You can perform bind and define operations on CLOB and BLOB columns in C applications using the data interface for LOBs in OCI. Doing so, enables you to insert or select out data in a LOB column without using a LOB locator as follows:

• Using a bind variable associated with a LOB column to insert character data into a CLOB, or RAW data into a BLOB.
• Using a define operation to define an output buffer in your application that will hold character data selected from a CLOB, or RAW data selected from a BLOB.

  See Also: Chapter 13, "Data Interface for Persistent LOBs" for more information on implicit assignment of LOBs to other datatypes.

Using the LOB Locator to Access and Modify LOB Values

The value of a LOB instance stored in the database can be accessed through a LOB locator, a reference to the location of the LOB value. Database tables store only locators in CLOB, BLOB, NCLOB and BFILE columns. Note the following with respect to LOB locators and values:

• To access or manipulate a LOB value, you pass the LOB locator to the various LOB APIs.
• A LOB locator can be assigned to any LOB instance of the same type.
• The characteristics of a LOB as being temporary or persistent have nothing to do with the locator. The characteristics of temporary or persistent apply only to the LOB instance.

LOB Locators and BFILE Locators

There are some differences between the semantics of locators for LOB types BLOB, CLOB, and NCLOB; and the semantics of locators for the BFILE type that you need to be aware of:

• For LOB types BLOB, CLOB, and NCLOB, the LOB column stores a locator to the LOB value. Each LOB instance has its own distinct LOB locator and also a distinct copy of the LOB value.
• For initialized BFILE columns, the row stores a locator to the external operating system file that holds the value of the BFILE. Each BFILE instance in a given row has its own distinct locator; however, two different rows can contain a BFILE locator that points to the same operating system file.

Regardless of where the value of a LOB is stored, a locator is stored in the table row of any initialized LOB column. Note that when the term locator is used without an identifying prefix term, it refers to both LOB locators and BFILE locators. Also, when your select a LOB from a table, the LOB returned is always a temporary LOB. For more information on working with locators for temporary LOBs, see "LOBs Returned from SQL Functions".

Initializing a LOB Column to Contain a Locator

Any LOB instance that is NULL does not have a locator. Before you can pass a LOB instance to any LOB API routine, the instance must contain a locator. For example, you can select a NULL LOB from a row, but you cannot pass the instance to the PL/SQL DBMS_LOB.READ procedure. The following sub-sections describe how to initialize a persistent LOB column and how to initialize a BFILE column.

Initializing a Persistent LOB Column

Before you can start writing data to a persistent LOB using the supported programmatic environment interfaces (PL/SQL, OCI, OCCI, Pro*C/C++, Pro*COBOL, Visual Basic, Java, or OLEDB), the LOB column/attribute must be made non-null, that is, it must contain a locator.

You can accomplish this by initializing the persistent LOB to empty in an INSERT/UPDATE statement using the functions EMPTY_BLOB for BLOBs or EMPTY_CLOB for CLOBs and NCLOBs.

Running the EMPTY_BLOB() or EMPTY_CLOB() function in and of itself does not raise an exception. However, using a LOB locator that was set to empty to access or manipulate the LOB value in any PL/SQL DBMS_LOB or OCI routine will raise an exception.

Valid places where empty LOB locators may be used include the VALUES clause of an INSERT statement and the SET clause of an UPDATE statement.

The following INSERT statement:

Similarly, the LOB attributes for the ad_header column in print_media can be initialized to NULL or set to empty as shown in the following.

INSERT INTO print_media (product_id, ad_id, ad_header) 
    VALUES (101, 1, adheader_typ('AD FOR ORACLE', sysdate, 
    'Have Grid', EMPTY_BLOB()));

BFILEs

Before you can access BFILE values using LOB APIs, the BFILE column or attribute must be made non-null. You can initialize the BFILE column to point to an external operating system file by using the BFILENAME() function.

Accessing LOBs

You can access a LOB instance using the following techniques:

• Accessing a LOB Using SQL
• Accessing a LOB Using the Data Interface
• Accessing a LOB Using the Locator Interface

Accessing a LOB Using SQL

Support for columns that use LOB datatypes is built into many SQL functions. This support enables you to use SQL semantics to access LOB columns in SQL. In most cases, you can use the same SQL semantics on a LOB column that you would use on a VARCHAR2 column.

Accessing a LOB Using the Data Interface

You can select a LOB directly into CHAR or RAW buffers using the LONG-to-LOB API in OCI and PL/SQL. In the following PL/SQL example, AD_FINALTEXT is selected into a VARCHAR buffer final_ad.

DECLARE
    final_ad VARCHAR(32767);
BEGIN
    SELECT AD_FINALTEXT INTO final_ad FROM print_media
        WHERE PRODUCT_ID= 2056 and AD_ID= 12001 ; 
    DBMS_OUTPUT.PUT_LINE(final_ad);
    /* more calls to read final_ad */
END;

Accessing a LOB Using the Locator Interface

You can access and manipulate a LOB instance by passing the LOB locator to the LOB APIs supplied with the database. An extensive set of LOB APIs is provided with each supported programmatic environment. In OCI, a LOB locator is mapped to a locator pointer which is used to access the LOB value.

LOB Restrictions

This section provides details on LOB restrictions.

Restrictions on LOB Columns

LOB columns are subject to the following restrictions:

• You cannot specify a LOB as a primary key column.
• Distributed LOBs are not supported. Therefore, you cannot use a remote locator in SELECT or WHERE clauses of queries or in functions of the DBMS_LOB package.

  The following syntax is not supported for LOBs:

  SELECT lobcol FROM table1@remote_site;
  INSERT INTO lobtable SELECT type1.lobattr FROM 
      table1@remote_site;
  SELECT DBMS_LOB.getlength(lobcol) FROM table1@remote_site;
  
  

  However, you can use a remote locator in others parts of queries that reference LOBs. The following syntax is supported on remote LOB columns:

  CREATE TABLE t AS SELECT * FROM table1@remote_site;
  INSERT INTO t SELECT * FROM table1@remote_site;
  UPDATE t SET lobcol = (SELECT lobcol FROM table1@remote_site);
  INSERT INTO table1@remote_site select * from local_table;
  UPDATE table1@remote_siteset lobcol = (SELECT lobcol FROM local_table);
  DELETE FROM table1@remote_site <WHERE clause involving non_lob_columns>
  
  
  

  This is the only supported syntax involving LOBs in remote tables. No other usage is supported.

  In statements structured like the first three of the preceding examples, only standalone LOB columns are allowed in the select list.

  SQL functions and DBMS_LOB APIs are not supported for use with remote LOB columns. For example, the following statement is supported:

  CREATE TABLE AS SELECT clob_col FROM tab@dbs2; 
  
  

  However, the following statement is not supported:

  CREATE TABLE AS SELECT dbms_lob.substr(clob_col) from tab@dbs2; 
  
  

• Clusters cannot contain LOBs, either as key or nonkey columns.
• The following data structures are supported only as temporary instances. You cannot store these instances in database tables:
  • Varray of any LOB type
  • Varray of any type containing a LOB type, such as an ADT with a LOB attribute.
• You cannot specify LOB columns in the ORDER BY clause of a query, or in the GROUP BY clause of a query or in an aggregate function.
• You cannot specify a LOB column in a SELECT... DISTINCT or SELECT... UNIQUE statement or in a join. However, you can specify a LOB attribute of an object type column in a SELECT... DISTINCT statement or in a query that uses the UNION or MINUS set operator if the column's object type has a MAP or ORDER function defined on it.
• You cannot specify LOB columns in ANALYZE... COMPUTE or ANALYZE... ESTIMATE statements.
• The first (INITIAL) extent of a LOB segment must contain at least three database blocks.
• When creating an UPDATE DML trigger, you cannot specify a LOB column in the UPDATE OF clause.
• You cannot specify a LOB column as part of an index key. However, you can specify a LOB column in the function of a function-based index or in the indextype specification of a domain index. In addition, Oracle Text lets you define an index on a CLOB column.
• In an INSERT or UPDATE operation, you can bind data of any size to a LOB column, but you cannot bind data to a LOB attribute of an object type. In an INSERT... AS SELECT operation, you can bind up to 4000 bytes of data to LOB columns.
• If a table has both LONG and LOB columns, you cannot bind more than 4000 bytes of data to both the LONG and LOB columns in the same SQL statement. However, you can bind more than 4000 bytes of data to either the LONG or the LOB column.

  Note: For a table on which you have defined a DML trigger, if you use OCI functions or DBMS_LOB routines to change the value of a LOB column or the LOB attribute of an object type column, the database does not fire the DML trigger.

Restrictions for LOB Operations

Other general LOB restrictions include the following:

• In SQL loader, A field read from a LOBFILE cannot be used as an argument to a clause. See "Database Utilities for Loading Data into LOBs" for more information.
• Session migration is not supported for BFILEs in shared server (multithreaded server) mode. This implies that operations on open BFILEs can persist beyond the end of a call to a shared server. In shared server sessions, BFILE operations will be bound to one shared server, they cannot migrate from one server to another.