Oracle Built−in Packages- P88 ppt

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 [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 426 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. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 427 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. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 428 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. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 429 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. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 430