BEGIN INSERT INTO my_book_text (chapter_descr, chapter_text) VALUES ( 'Table of Contents', EMPTY_CLOB() ) RETURNING chapter_text INTO chapter_loc; chapter_length := DBMS_LOB.GETLENGTH( chapter_loc ); DBMS_OUTPUT.PUT_LINE ('Length of Table of Contents: ' || chapter_length); EXCEPTION WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE( 'OTHERS Exception ' || sqlerrm); END; / This is the output of the script: Length of Table of Contents: 0 Note that EMPTY_CLOB can be used to populate both CLOB and NCLOB columns. EMPTY_BLOB and EMPTY_CLOB can be called with or without empty parentheses. NOTE: Do not populate BLOB, CLOB, or NCLOB columns with NULL values. Instead, use the EMPTY_BLOB or EMPTY_CLOB functions, which will populate the columns with a valid LOB locator and set the associated data to NULL. 8.1 Getting Started with DBMS_LOB 8.3 DBMS_LOB Interface Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 8.2.3 Internal LOB Considerations 401 Chapter 8 Managing Large Objects 8.3 DBMS_LOB Interface This section describes the programs available through the DBMS_LOB packages in several categories. 8.3.1 Working with BFILEs The following sections describe the programs in the DBMS_LOB package that perform operations on BFILE objects. 8.3.1.1 The DBMS_LOB.FILEEXISTS function The FILEEXISTS function indicates whether the given BFILE locator points to a file that exists in the operating system. Here's the specification for this program: FUNCTION DBMS_LOB.FILEEXISTS ( file_loc IN BFILE ) RETURN INTEGER; The file_loc parameter is the name of the file locator. The function returns one of the following values: Value Description 0 The specified file does not exist 1 The specified file exists 8.3.1.1.1 Exceptions One of the following exceptions may be raised if the file_loc parameter contains an improper value (e.g., NULL): DBMS_LOB.NOEXIST_DIRECTORY DBMS_LOB.NOPRIV_DIRECTORY DBMS_LOB.INVALID_DIRECTORY 8.3.1.1.2 Restrictions The FILEEXISTS function asserts a purity level with the RESTRICT_REFERENCES pragma. PRAGMA RESTRICT_REFERENCES (fileexists, WNDS, RNDS, WNPS, RNPS); 8.3.1.1.3 Examples This block uses the FILEEXISTS function to see if chapter01.txt exists in the BOOK_TEXT directory: DECLARE book_file_loc BFILE := NULL; book_file_exists BOOLEAN := FALSE; BEGIN 402 book_file_loc := BFILENAME( 'BOOK_TEXT', 'chapter01.txt' ); book_file_exists := DBMS_LOB.FILEEXISTS( book_file_loc ) = 1; IF book_file_exists THEN DBMS_OUTPUT.PUT_LINE ('chapter01.txt exists in BOOK_TEXT directory'); ELSE DBMS_OUTPUT.PUT_LINE ('chapter01.txt does not exist in BOOK_TEXT directory'); END IF; END; / This is the output of the script: chapter01.txt exists in BOOK_TEXT directory The following example selects the file locator for chapter01.txt from the my_book_files table and checks to see if the file exists: INSERT INTO my_book_files ( file_descr, book_file ) VALUES ('Chapter 1', BFILENAME('BOOK_TEXT', 'chapter01.txt') ); DECLARE book_file_loc BFILE := NULL; book_file_exists BOOLEAN := FALSE; BEGIN book_file_loc := book_file ('Chapter 1'); IF book_file_loc IS NOT NULL THEN book_file_exists := DBMS_LOB.FILEEXISTS( book_file_loc ) = 1; END IF; IF book_file_exists THEN DBMS_OUTPUT.PUT_LINE('Chapter 1 exists'); ELSE DBMS_OUTPUT.PUT_LINE('Chapter 1 does not exist'); END IF; END; / This is the output of the script: Chapter 1 exists FILEEXISTS raises a VALUE_ERROR exception when passed a NULL file locator, so you should always include conditional logic and an exception section. The next example raises the NOEXIST_DIRECTORY exception. This can occur if the directory alias does not exist, or if the user has not been granted READ privilege on the directory. DECLARE book_file_loc BFILE := NULL; book_file_exists BOOLEAN := FALSE; BEGIN book_file_loc := BFILENAME( 'NON_EXISTENT_DIRECTORY', 'chapter01.txt' ); book_file_exists := DBMS_LOB.FILEEXISTS( book_file_loc ) = 1; IF book_file_exists THEN DBMS_OUTPUT.PUT_LINE('chapter01.txt exists'); ELSE DBMS_OUTPUT.PUT_LINE('chapter01.txt does not exist'); END IF; [Appendix A] What's on the Companion Disk? 403 END; / Running this script results in this unhandled exception: ORA−22285: non−existent directory or file for FILEEXISTS operation If the directory exists and READ privileges have been granted to the user, but the specified file does not exist, FILEEXISTS returns zero. DECLARE book_file_loc BFILE := NULL; BEGIN book_file_loc := BFILENAME( 'BOOK_TEXT', 'non_existent_file.txt'); IF DBMS_LOB.FILEEXISTS( book_file_loc ) = 0 THEN DBMS_OUTPUT.PUT_LINE('non_existent_file.txt does not exist'); END IF; END; / This script produces the following: non_existent_file.txt does not exist FILEEXISTS can be called from SQL, for example: SELECT DBMS_LOB.FILEEXISTS ( BFILENAME ('BOOK_TEXT','chapter01.txt') ) fileexists FROM DUAL; FILEEXISTS −−−−−−−−−−−−−−−− 1 Calls to FILEEXISTS should trap and handle the NOEXIST_DIRECTORY exception (directory alias does not exist) and the VALUE_ERROR exception (input file locator is NULL). 8.3.1.2 The DBMS_LOB.FILEGETNAME procedure Given a file locator, the FILEGETNAME procedure determines its associated directory alias and filename. The specification for this program follows: PROCEDURE DBMS_LOB.FILEGETNAME ( file_loc IN BFILE, dir_alias OUT VARCHAR2, filename OUT VARCHAR2 ); Parameters are summarized in the following table. Parameter Description file_loc File locator dir_alias Directory alias for the file locator filename File name for the file locator [Appendix A] What's on the Companion Disk? 8.3.1 Working with BFILEs 404 8.3.1.2.1 Exceptions The following VALUE_ERROR exception is raised if the file_loc parameter contains an improper value (e.g., NULL): INVALID_ARGVAL 8.3.1.2.2 Examples The following example uses FILEGETNAME to get the directory alias and filename for the "Chapter 1" row in the my_book_files table: INSERT INTO my_book_files (file_descr, book_file) VALUES ( 'Chapter 1', BFILENAME('BOOK_TEXT', 'chapter01.txt') ); DECLARE book_file_exists BOOLEAN := FALSE; book_file_loc BFILE := NULL; book_file_dir VARCHAR2(30) := NULL; book_file_name VARCHAR2(2000) := NULL; BEGIN book_file_loc := book_file ('Chapter 1'); IF book_file_loc IS NOT NULL THEN book_file_exists := DBMS_LOB.FILEEXISTS( book_file_loc ) = 1; END IF; IF book_file_exists THEN DBMS_LOB.FILEGETNAME (book_file_loc, book_file_dir, book_file_name); DBMS_OUTPUT.PUT_LINE ('File name is: ' || book_file_name); DBMS_OUTPUT.PUT_LINE ('File is in Oracle directory: ' || book_file_dir); ELSE DBMS_OUTPUT.PUT_LINE('Chapter 1 does not exist'); END IF; EXCEPTION WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE('OTHERS Exception ' || sqlerrm ); END; / This is the output of the script: File name is: chapter01.txt File is in Oracle directory: BOOK_TEXT FILEGETNAME raises a VALUE_ERROR exception when passed a NULL file locator, so be sure to check the value of the file locator and/or include an exception handler. Note that FILEGETNAME does not actually confirm that the physical file and directory alias exist. This can be done via FILEEXISTS. 8.3.1.3 The DBMS_LOB.FILEOPEN procedure Given a file locator, the FILEOPEN procedure opens the BFILE for read−only access. Here's the header for this program: PROCEDURE DBMS_LOB.FILEOPEN ( file_loc IN OUT BFILE, open_mode IN BINARY_INTEGER := FILE_READONLY ) [Appendix A] What's on the Companion Disk? 8.3.1 Working with BFILEs 405 . DBMS_OUTPUT.PUT_LINE ('File name is: ' || book_file_name); DBMS_OUTPUT.PUT_LINE ('File is in Oracle directory: ' || book_file_dir); ELSE DBMS_OUTPUT.PUT_LINE('Chapter 1 does not. ' || sqlerrm ); END; / This is the output of the script: File name is: chapter01.txt File is in Oracle directory: BOOK_TEXT FILEGETNAME raises a VALUE_ERROR exception when passed a NULL file locator,