Oracle Built−in Packages- P83 pptx

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

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.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

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?

/

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

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?