[Chapter 8] Managing Large Objects Chapter 8 8. Managing Large Objects Contents:Getting Started with DBMS_LOBLOB ConceptsDBMS_LOB InterfaceOracle8 and PL/SQL8 support the storage and manipulation of large objects (a.k.a. LOBs). A LOB, which can be a column in a table or an attribute of an object type, may store up to four gigabytes of data, such as character text, graphic images, video, or "raw" data. The DBMS_LOB package (new to Oracle8) provides a set of procedures and functions to access and manipulate LOBs from within PL/SQL programs. You can also manipulate LOBs from within SQL; refer to the Oracle documentation for these SQL-specific aspects of LOB management.8.1 Getting Started with DBMS_LOBThe DBMS_LOB package is created when the Oracle8 database is installed. The dbmslob.sql script (found in the built-in packages source directory, as described in Chapter 1, Introduction) contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_LOB for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package.8.1.1 DBMS_LOB ProgramsTable 8.1 summarizes the programs available in DBMS_LOB.Table 8.1: DBMS_LOB Programs NameDescriptionUse in SQLAPPENDAppends the contents of a source internal LOB to a destination internal LOBNoCOMPARECompares two LOBs of the same type; parts of LOBs can also be comparedYes COPYCopies all or part of the contents of a source internal LOB to a destination internal LOBNoERASEErases all or part of an internal LOBNoFILECLOSECloses an open BFILENoFILECLOSEALLCloses all open BFILEsNoFILEEXISTSChecks if a given file exists YesFILEGETNAMEReturns directory alias and filename of given file locatorNoFILEOPENOpens a BFILE for read-only accessNoFILEISOPENDetermines if a BFILE was opened with the given file locatorYesGETLENGTHReturns the length of the input LOB; length is in bytes for BFILEs and BLOBs; length is in characters for CLOBs and NCLOBsYesINSTRReturns matching offset location in the input LOB of the Nth occurrence of a given patternYesLOADFROMFILELoads all or part of external LOB to internal LOBNoREADProvides piece-wise read access to a LOBNoSUBSTRProvides piece-wise read access to a LOBYesTRIMTrims the contents of an internal LOB to the length specified by the newlenparameterNoWRITEWrites a given number of bytes or characters to an internal LOB at a specified offsetNoTable Table 8.2 shows which LOB types you can manipulate with the individual DBMS_LOB programs. For an explanation of these LOB types, see the section Section 8.2, "LOB Concepts"" later in this chapter.Table 8.2: DBMS_LOB Programs Can Manipulate These LOB TypesProgramBFILEBLOBCLOBNCLOBAPPEND XXXCOMPAREXXXXCOPY XXXERASE XXXFILECLOSEX   FILECLOSEALLX   FILEEXISTSX   FILEGETNAMEX   FILEISOPENX   FILEOPENX   GETLENGTHXXXXINSTRXXXXLOADFROMFILEXXXXREADXXXXSUBSTRXXXXTRIM XXXWRITE XXX8.1.2 DBMS_LOB ExceptionsTable Table 8.3 summarizes the exceptions declared by DBMS_LOB.Table 8.3: DBMS_LOB Exceptions ExceptionSQLCODECauseINVALID_ARGVAL-21560DBMS_LOB expects a valid argument to be passed, but the argument was NULL or invalid.Example: FILEOPEN is passed an invalid open mode. Example: a positional or size argument is outside of the range 1 through (4 gigabytes-1).ACCESS_ERROR-22925An attempt to read or write beyond maximum LOB size has occurred.NOEXIST_DIRECTORY-22285The directory specified does not exist in the data dictionary.NOPRIV_DIRECTORY-22286The user does not have the required privileges on either the specified directory object or the specified file.INVALID_DIRECTORY-22287The directory specified is not valid or has been modified by the database administrator since the last access.OPERATION_FAILED-22288An operation attempted on a file failed.UNOPENED_FILE-22289An operation was performed on a file that was not open.OPEN_TOOMANY-22290The maximum number of open files has been reached. This maximum is set via the SESSION_MAX_OPEN_FILES database initialization parameter. The maximum applies to many kinds of files, not only BFILES; for example, it applies to files opened using the UTL_FILE package.8.1.3 DBMS_LOB Nonprogram ElementsTable Table 8.4 summarizes the constants declared by the DBMS_LOB package.Table 8.4: DBMS_LOB ConstantsElement NameTypeValueFILE_READONLYCONSTANT BINARY_INTEGERZero. Mode used to open files.LOBMAXSIZECONSTANT INTEGER4,294,967,295 (4 gigabytes-1). Positional and size arguments cannot exceed this value.8.1.4 About the ExamplesThis chapter contains many examples of DBMS_LOB usage. For my examples, I use tables called my_book_files and my_book_text, which contain (or point to) large volumes of text for a book. The structures of these tables follow:/* Filename on companion disk: lobtabs.sql */* CREATE TABLE my_book_files ( file_descr VARCHAR2(100), book_file BFILE); CREATE TABLE my_book_text ( chapter_descr VARCHAR2(100), chapter_text CLOB);Often, I'll query one of the fields from the table for a given chapter (chapter_desc) value. To avoid repetition of code, here are the implementations of functions that will be used throughout the examples:/* Filename on companion disk: lobfuncs.sql */* CREATE OR REPLACE FUNCTION book_file (chapter_in IN VARCHAR2) RETURN BFILE IS CURSOR book_cur IS SELECT book_file FROM my_book_files WHERE file_descr = chapter_in; book_rec book_cur%ROWTYPE; BEGIN OPEN book_cur; FETCH book_cur INTO book_rec; CLOSE book_cur; RETURN book_rec.book_file; END; / CREATE OR REPLACE FUNCTION book_text (chapter_in IN VARCHAR2) RETURN CLOB IS CURSOR book_cur IS SELECT chapter_text FROM my_book_text WHERE chapter_descr = chapter_in; book_rec book_cur%ROWTYPE; BEGIN OPEN book_cur; FETCH book_cur INTO book_rec; CLOSE book_cur; RETURN book_rec.chapter_text; END; / CREATE OR REPLACE FUNCTION book_text_forupdate (chapter_in IN VARCHAR2) RETURN CLOB IS CURSOR book_cur IS SELECT chapter_text FROM my_book_text WHERE chapter_descr = chapter_in FOR UPDATE; book_rec book_cur%ROWTYPE; BEGIN OPEN book_cur; FETCH book_cur INTO book_rec; CLOSE book_cur; RETURN book_rec.chapter_text; END; /In several of the examples, I'll compare before and after "images" of LOB content using the following statements (stored in the compare_text.sql file): SELECT chapter_descr, chapter_text FROM my_book_text WHERE chapter_descr = '&1' ROLLBACK; EXEC DBMS_OUTPUT.PUT_LINE ('Rollback completed'); SELECT chapter_descr, chapter_text FROM my_book_text WHERE chapter_descr = '&1' END; /NOTE: It's a good practice to include exception handlers in any program working with LOBs to trap and deal with LOB-related errors. Not all of the programs and anonymous blocks shown in this chapter include exception handlers, but that is done only to reduce overall code volume.7.3 DBMS_APPLICATION_INFO Examples 8.2 LOB Concepts Copyright (c) 2000 O'Reilly & Associates. All rights reserved.