Oracle Built−in Packages- P86 pdf

This is the output of the script:file_loc_1 equals file_loc_2 This example compares two diagrams from the my_book_diagrams table: DECLARE CURSOR diagram_cur num IN INTEGER IS SELECT d

NULL Either amount, offset_1oroffset_2,is less than 1, or amount, offset_1, or offset_2is greater

thanLOBMAXSIZE

8.3.2.1.1 Exceptions

The COMPARE function may raise the following exceptions:

NOEXIST_DIRECTORY

For BFILEs

UNOPENED_FILE

For BFILEs Files must be open before comparison

NOPRIV_DIRECTORY

For BFILEs

INVALID_DIRECTORY

For BFILEs

INVALID_OPERATION

For BFILEs

8.3.2.1.2 Restrictions

The program asserts a purity level with the RESTRICT_REFERENCES pragma

PRAGMA RESTRICT_REFERENCES (compare, WNDS, RNDS, WNPS, RNPS);

8.3.2.1.3 Examples

The following example compares two BFILE locators that are pointing to the same file Note that for BFILEs

we must provide a number of bytes (in the amount parameter) to compare, which is determined via the

GETLENGTH function Note also that for BFILES we must first open the files

DECLARE

v_file_loc_1 BFILE;

v_file_1_length INTEGER;

v_file_loc_2 BFILE;

BEGIN

v_file_loc_1 := BFILENAME ('IMAGES', 'ourlogo.bmp');

v_file_loc_2 := BFILENAME ('IMAGES', 'ourlogo.bmp');

DBMS_LOB.FILEOPEN(v_file_loc_1);

DBMS_LOB.FILEOPEN(v_file_loc_2);

v_file_1_length := DBMS_LOB.GETLENGTH( v_file_loc_1);

IF DBMS_LOB.COMPARE

( v_file_loc_1, v_file_loc_2, v_file_1_length) = 0

THEN

DBMS_OUTPUT.PUT_LINE('file_loc_1 equals file_loc_2');

ELSE

DBMS_OUTPUT.PUT_LINE('file_loc_1 is not equal to file_loc_2');

END IF;

DBMS_LOB.FILECLOSEALL;

END;

/

This is the output of the script:

file_loc_1 equals file_loc_2

This example compares two diagrams from the my_book_diagrams table:

DECLARE

CURSOR diagram_cur (num IN INTEGER)

IS

SELECT diagram

FROM my_book_diagrams

WHERE chapter_descr = 'Chapter 1'

AND diagram_no = num;

v_diagram_1_loc BLOB;

v_diagram_2_loc BLOB;

BEGIN

OPEN diagram_cur (1);

FETCH diagram_cur INTO v_diagram_1_loc;

CLOSE diagram_cur;

OPEN diagram_cur (2);

FETCH diagram_cur INTO v_diagram_1_loc;

CLOSE diagram_cur;

IF DBMS_LOB.COMPARE (v_diagram_1_loc, v_diagram_2_loc) = 0

THEN

DBMS_OUTPUT.PUT_LINE ('diagrams are equal');

ELSE

DBMS_OUTPUT.PUT_LINE ('diagrams are different');

END IF;

END;

/

This is the output of the script:

diagrams are different

8.3.2.2 The DBMS_LOB.GETLENGTH function

The GETLENGTH function returns the length of the input LOB The length is in bytes for BFILEs and BLOBs, and in characters for CLOBs and NCLOBs The headers for this program, for each corresponding LOB type, are the following:

FUNCTION DBMS_LOB.GETLENGTH (lob_loc IN BLOB) RETURN INTEGER;

FUNCTION DBMS_LOB.GETLENGTH (lob_loc IN CLOB CHARACTER SET ANY_CS)

RETURN INTEGER;

FUNCTION DBMS_LOB.GETLENGTH (lob_loc IN BFILE) RETURN INTEGER;

The lob_loc parameter is the locator of the LOB whose length is to be determined

The overloaded specification allows GETLENGTH to be used with all types of LOBs The clause ANY_CS

in the specification allows either CLOB or NCLOB locators as input

The function returns the length (in bytes or characters) of the input LOB, or it returns NULL if the input LOB

is NULL or invalid

8.3.2.2.1 Restrictions

The program asserts a purity level with the RESTRICT_REFERENCES pragma

PRAGMA RESTRICT_REFERENCES (getlength, WNDS, RNDS, WNPS, RNPS);

8.3.2.2.2 Examples

The following example gets the size in bytes of the file ch01_01.bmp in the IMAGES directory:

DECLARE

v_file_loc BFILE;

v_diagram_size INTEGER;

BEGIN

v_file_loc := BFILENAME('IMAGES','ch01_01.bmp');

v_diagram_size := DBMS_LOB.GETLENGTH(v_file_loc);

DBMS_OUTPUT.PUT_LINE('Diagram size: ' || v_diagram_size);

END;

/

This is the output of the script:

Diagram size: 481078

This example gets the size in characters of "Chapter 1" from the my_book_text table:

DECLARE

v_text_loc CLOB;

BEGIN

v_text_loc := book_text ('Chapter 1');

DBMS_OUTPUT.PUT_LINE

('Length of Chapter 1: ' || DBMS_LOB.GETLENGTH(v_text_loc));

END;

/

This is the output of the script:

Length of Chapter 1: 100

8.3.2.3 The DBMS_LOB.READ procedure

The READ procedure provides piece−wise read access to a LOB A specified number of bytes (BFILE,

BLOB) or characters (CLOB, NCLOB) is read into the buffer, starting from a specified location The number

of bytes or characters actually read by the operation is returned The headers for this program, corresponding

to each type, are the following:

PROCEDURE DBMS_LOB.READ

(lob_loc IN BLOB | BFILE,

amount IN OUT BINARY_INTEGER,

offset IN INTEGER,

buffer OUT RAW);

PROCEDURE DBMS_LOB.READ

(lob_loc IN CLOB CHARACTER SET ANY_CS,

amount IN OUT BINARY_INTEGER,

offset IN INTEGER,

buffer OUT VARCHAR2 CHARACTER SET lob_loc%CHARSET);

The overloaded specification allows READ to be used with all types of LOBs The term ANY_CS in the

specification allows either CLOB or NCLOB locators as input.

The READ procedure and the DBMS_LOB.SUBSTR function provide similar functionality READ is a procedure, while SUBSTR is a function However, READ will raise NO_DATA_FOUND and

INVALID_ARGVAL exceptions, while SUBSTR will ignore these exceptions and return NULL when they occur DBMS_LOB.SUBSTR can also be called from within a SQL statement, but READ cannot be, since it

is a procedure

Parameters are summarized in the following table

Parameter Description

lob_loc A locator for the LOB to be read

amount Number of bytes (BFILE, BLOB) or characters (CLOB, NCLOB) to read; the number of bytes or

characters actually read by the operation is returned in amount

offset Location of the byte (BFILE, BLOB) or character (CLOB, NCLOB) in the LOB at which the

read begins

buffer Buffer where the results of the read operation are placed

8.3.2.3.1 Exceptions

The READ procedure may raise any of the following exceptions:

VALUE_ERROR

lob_loc, amount, or offset is NULL

INVALID_ARGVAL

One of the following conditions exists:

•

amount< 1 or amount> 32767

•

offset< 1 or offset> LOBMAXSIZE

•

size of amount> size of buffer

NO_DATA_FOUND

The end of the LOB is reached

UNOPENED_FILE

For BFILEs, files must be open before the read

NOEXIST_DIRECTORY

For BFILEs

NOPRIV_DIRECTORY

For BFILEs

INVALID_DIRECTORY

For BFILEs

INVALID_OPERATION

For BFILEs.

8.3.2.3.2 Examples

The following example reads the first 60 characters of the CLOB chapter_text column of the

my_book_texttable using the "Chapter 1" row:

DECLARE

v_text_loc CLOB;

v_text_amt BINARY_INTEGER := 60;

v_text_buffer VARCHAR2(60);

BEGIN

v_text_loc := book_text ('Chapter 1');

DBMS_LOB.READ (v_text_loc, v_text_amt, 1, v_text_buffer);

DBMS_OUTPUT.PUT_LINE('Chapter 1: ' || v_text_buffer);

END;

/

This is the output of the script:

Chapter 1: It was a dark and stormy night Suddenly a scream rang out.

The next example reads sixty characters at a time from the CLOB chapter_text column of the my_book_text table using the "Chapter 1" row Note that the loop continues until READ raises the NO_DATA_FOUND exception

DECLARE

v_text_loc CLOB;

v_text_amt BINARY_INTEGER := 60;

v_text_pos INTEGER := 1;

v_text_buffer VARCHAR2(60);

BEGIN

v_text_loc := book_text ('Chapter 1');

LOOP

DBMS_LOB.READ

(v_text_loc, v_text_amt, v_text_pos, v_text_buffer);

/* process the text and prepare to read again */

DBMS_OUTPUT.PUT_LINE('Chapter 1: ' || v_text_buffer);

v_text_pos := v_text_pos + v_text_amt;

END LOOP;

EXCEPTION

WHEN NO_DATA_FOUND

THEN

DBMS_OUTPUT.PUT_LINE('End of Chapter Reached.');

END;

/

This script produces the following:

Chapter 1: It was a dark and stormy night Suddenly a scream rang out.

Chapter 1: An EXCEPTION had not been handled.

End of Chapter Reached.

Note that the maximum size of a VARCHAR2 or RAW variable is 32767 bytes This is the size limit of the buffer to be used with READ

8.3.2.4 The DBMS_LOB.SUBSTR function

The SUBSTR function provides piece−wise access to a LOB The specified number of bytes (BFILE, BLOB)

or characters (CLOB, NCLOB) is returned, starting from the specified location The headers for this program, corresponding to each LOB type, are the following: