Oracle Built−in Packages- P88 ppt

The headers for this program, corresponding to each LOB type, are the following: PROCEDURE DBMS_LOB.COPY dest_lob IN OUT BLOB, src_lob IN BLOB, amount IN INTEGER, dest_offset IN INTE

SET LONG 200

COL chapter_descr FOR A15

COL chapter_text FOR A40 WORD_WRAPPED

@compare_text ('Chapter 1');

This is the output of the script:

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night

Suddenly a scream rang out An

EXCEPTION had not been handled The sun

shone brightly the following morning

All traces of the storm had disappeared

Rollback complete

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night

Suddenly a scream rang out An

EXCEPTION had not been handled

8.3.3.2 The DBMS_LOB.COPY procedure

The COPY procedure copies all or part of the contents of a source internal LOB to a destination internal LOB.

An offset location in each LOB can be specified The headers for this program, corresponding to each LOB type, are the following:

PROCEDURE DBMS_LOB.COPY

(dest_lob IN OUT BLOB,

src_lob IN BLOB,

amount IN INTEGER,

dest_offset IN INTEGER := 1,

src_offset IN INTEGER := 1);

PROCEDURE DBMS_LOB.COPY

(dest_lob IN OUT CLOB CHARACTER SET ANY_CS,

src_lob IN CLOB CHARACTER SET dest_lob%CHARSET,

amount IN INTEGER,

dest_offset IN INTEGER := 1,

src_offset IN INTEGER := 1);

The overloaded specification allows COPY to be used with BLOBs, CLOBs, and NCLOBs The term

ANY_CS in the specification allows either CLOB or NCLOB locators as input COPY cannot be used with BFILEs, because access to BFILEs is read−only.

Parameters are summarized in the following table.

Parameter Description

dest_lob Locator for the destination LOB

src_lob Locator for the source LOB

amount Number of bytes (BLOB) or characters (CLOB, NCLOB) to copy

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

copy operation begins; the default value is 1

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

copy operation begins; the default value is 1

8.3.3.2.1 Exceptions

The COPY procedure may raise one of the following exceptions:

VALUE_ERROR

One or both LOBs are NULL or invalid.

INVALID_ARGVAL

One of the following conditions exists:

•

src_offset < 1 or src_offset > LOBMAXSIZE

•

dest_offset <1 or dest_offset > LOBMAXSIZE

•

amount < 1 or amount > LOBMAXSIZE

ORA−22920

dest_lob is not locked for update.

8.3.3.2.2 Example

In the following example, the text "Suddenly a scream rang out " is copied from the "Chapter 1" row of the my_book_text table to the "Chapter 2" row Note that the COPY operation replaces (i.e., does not append) existing text We display the copied text, roll back the changes, and display the original text Internal LOBs

can participate in database transactions.

SET LONG 200

COL chapter_descr FOR A15

COL chapter_text FOR A40 WORD_WRAPPED

SELECT chapter_descr, chapter_text

FROM my_book_text;

DECLARE

v_text_loc CLOB;

v_text_buffer VARCHAR2(60);

v_text_pattern VARCHAR2(60) := 'dark';

BEGIN

v_dest_loc := book_text_forupdate ('Chapter 2');

v_src_loc := book_text ('Chapter 1');

DBMS_LOB.COPY(v_dest_loc, v_src_loc, 63, 47 ,34);

END;

/

@compare_text ('Chapter 2');

This is the output of the script:

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night

Suddenly a scream rang out An

EXCEPTION had not been handled

Chapter 2 The sun shone brightly the following

morning All traces of the storm had

disappeared

PL/SQL procedure successfully completed.

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 2 The sun shone brightly the following

morning Suddenly a scream rang out An

EXCEPTION had not been handled

Rollback complete

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 2 The sun shone brightly the following

morning All traces of the storm had

disappeared

8.3.3.3 The DBMS_LOB.ERASE procedure

The ERASE procedure removes all or part of the contents of an internal LOB An offset location in the LOB can be specified In the middle of a LOB, spaces are written for CLOBs and NCLOBs, and zero−byte filler is written for BLOBs.

PROCEDURE DBMS_LOB.ERASE

(lob_loc IN OUT BLOB | CLOB CHARACTER SET ANY_CS,

amount IN OUT INTEGER,

offset IN INTEGER := 1);

The overloaded specification allows ERASE to be used with BLOBs, CLOBs, and NCLOBs The term

ANY_CS in the specification allows either CLOB or NCLOB locators as input ERASE cannot be used with BFILEs because access to BFILEs is read−only.

Parameters are summarized in the following table.

Parameter Description

lob_loc Locator for the LOB to be erased

amount Number of bytes (BLOB) or characters (CLOB, NCLOB) to erase

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

operation begins; the default value is 1

8.3.3.3.1 Exceptions

The ERASE procedure may raise any of the following exceptions:

VALUE_ERROR

lob_loc or amount is NULL or invalid.

INVALID_ARGVAL

One of the following conditions exists:

•

amount < 1 or amount > LOBMAXSIZE

•

offset < 1 or offset > LOBMAXSIZE

ORA−22920

dest_lob is not locked for update.

8.3.3.3.2 Example

In the following example, we erase the string "brightly" from the "Chapter 2" chapter_textcolumn in the my_book_text table Note that the string is replaced with spaces We display the erased text, roll back the

changes, and display the original text Internal LOBs can participate in database transactions.

SET LONG 200

COL chapter_descr FOR A15

COL chapter_text FOR A40 WORD_WRAPPED

SELECT chapter_descr, chapter_text

FROM my_book_text

WHERE chapter_descr = 'Chapter 2';

DECLARE

v_dest_loc CLOB;

v_erase_amt INTEGER;

BEGIN

v_dest_loc := book_text_forupdate ('Chapter 2');

v_erase_amt := 9;

DBMS_LOB.ERASE(v_dest_loc, v_erase_amt, 15);

END;

/

@compare_text ('Chapter 2');

This is the output of the script:

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 2 The sun shone brightly the following

morning All traces of the storm had

disappeared

PL/SQL procedure successfully completed

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 2 The sun shone the following

morning All traces of the storm had

disappeared

Rollback complete

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 2 The sun shone brightly the following

morning All traces of the storm had

disappeared

8.3.3.4 The DBMS_LOB.TRIM procedure

The TRIM procedure trims the contents of an internal LOB to a specified length The headers for this

program, corresponding to each LOB type, are the following:

PROCEDURE DBMS_LOB.TRIM

(lob_loc IN OUT BLOB|CLOB CHARACTER SET ANY_CS,

newlen IN INTEGER);

The overloaded specification allows TRIM to be used with BLOBs, CLOBs, and NCLOBs The term

ANY_CS in the specification allows either CLOB or NCLOB locators as input TRIM cannot be used with BFILEs because access to BFILEs is read−only.

The parameters for this program are summarized in the following table.

Parameter Description

lob_loc Locator for the LOB to be erased

newlen Number of bytes (BLOB) or characters (CLOB, NCLOB) to remain in the LOB

8.3.3.4.1 Exceptions

The TRIM procedure may raise any of the following exceptions:

VALUE_ERROR

lob_loc or newlen is NULL or invalid.

INVALID_ARGVAL

newlen < 0 or newlen > LOBMAXSIZE.

ORA−22920

dest_lob is not locked for update.

8.3.3.4.2 Example

In the following example, we trim the "Chapter 1" chapter_textcolumn in the my_book_text table to 31 characters We display the trimmed text, roll back the changes, and display the original text Internal LOBs

can participate in database transactions.

SET LONG 200

COL chapter_descr FOR A15

COL chapter_text FOR A40 WORD_WRAPPED

SELECT chapter_descr, chapter_text

FROM my_book_text

WHERE chapter_descr = 'Chapter 1';

DECLARE

v_text_loc CLOB;

BEGIN

v_text_loc := book_text ('Chapter 1');

DBMS_LOB.TRIM (v_text_loc, 31);

END;

/

@compare_text ('Chapter 1');

This is the output of the script:

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night

Suddenly a scream rang out An

EXCEPTION had not been handled

PL/SQL procedure successfully completed

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night

Rollback complete

CHAPTER_DESCR CHAPTER_TEXT

−−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−

Chapter 1 It was a dark and stormy night