Oracle Built−in Packages- P89 potx

Suddenly a scream rang out. An EXCEPTION had not been handled. 8.3.3.5 The DBMS_LOB.WRITE procedure The WRITE procedure writes a given number of bytes (BLOB) or characters (CLOB, NCLOB) to an internal LOB, beginning at a specified offset. The contents of the write operation are taken from the buffer. WRITE replaces (overlays) any data that exists in the LOB at the offset. The headers for this program, for each corresponding LOB type, are the following: PROCEDURE DBMS_LOB.WRITE (lob_loc IN OUT BLOB, amount IN BINARY_INTEGER, offset IN INTEGER, buffer IN RAW); PROCEDURE DBMS_LOB.WRITE (lob_loc IN OUT CLOB CHARACTER SET ANY_CS, amount IN BINARY_INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET); The overloaded specification allows WRITE to be used with BLOBs, CLOBs, and NCLOBs. The term ANY_CS in the specification allows either CLOB or NCLOB locators as input. WRITE cannot be used with BFILEs, because access to BFILEs is read−only. Parameters are summarized in the following table. Parameter Description lob_loc A locator for the target LOB amount Number of bytes (BLOB) or characters (CLOB, NCLOB) to be written offset The location of the byte (BLOB) or character (CLOB, NCLOB) in the LOB at which the write begins buffer Buffer holding the contents of the write operation 8.3.3.5.1 Exceptions The WRITE procedure may raise any of the following exceptions: VALUE_ERROR lob_loc, amount, or offset is NULL or invalid. INVALID_ARGVAL One of the following conditions exists: • amount < 1 or amount > 32767 • offset < 1 or offset > LOBMAXSIZE 8.3.3.5.2 Example In the following example, we write the string "The End" to the end of the "Chapter 2" chapter_textcolumn in the my_book_text table. We display the new text, roll back the changes, and display the original text. Internal LOBs can participate in database transactions. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 431 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_text_loc CLOB; v_offset INTEGER; v_buffer VARCHAR2(100); BEGIN v_text_loc := book_text_forupdate ('Chapter 1'); v_offset := DBMS_LOB.GETLENGTH (v_text_loc) + 3; v_buffer := 'The End.'; DBMS_LOB.WRITE (v_text_loc, 8, v_offset, v_buffer); 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 brightly the following morning. All traces of the storm had disappeared. The End. Rollback complete. CHAPTER_DESCR CHAPTER_TEXT −−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Chapter 2 The sun shone brightly the following morning. All traces of the storm had disappeared. 8.2 LOB Concepts 9. Datatype Packages Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 432 Chapter 9 433 9. Datatype Packages Contents: DBMS_ROWID: Working with the ROWID Pseudo−Column (Oracle8 only) UTL_RAW: Manipulating Raw Data This chapter introduces you to several packages that let you work effectively with particular types of Oracle data: DBMS_ROWID New in Oracle8, allows you to work with the two different ROWID formats: extended (new to Oracle8) and restricted (traditional Oracle7 ROWIDs). UTL_RAW Offers a set of functions allowing you to perform concatenation, substring, bit−wise logical analysis, byte translation, and length operations on RAW data. UTL_REF New in Oracle8 Release 8.1; provides a PL/SQL interface to select and modify objects (instances of an object type) in an object table without having to specify or know about the underlying database table. 9.1 DBMS_ROWID: Working with the ROWID Pseudo−Column (Oracle8 only) The DBMS_ROWID package lets you work with ROWIDs from within PL/SQL programs and SQL statements. You can use the programs in this package to both create and manipulate ROWIDs. You can determine the data block number, the object number, and other components of the ROWID without having to write code to translate the base−64 character external ROWID. NOTE: With Oracle8, there are two types of ROWIDs: extended and restricted. Restricted ROWIDs are the ROWIDs available with Oracle Version 7 and earlier. Extended ROWIDs are used only in Oracle8. 9.1.1 Getting Started with DBMS_ROWID The DBMS_ROWID package is created when the Oracle8 database is installed. The dbmsutil.sql script (found in the built−in packages source code directory, as described in Chapter 1, Introduction), contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_ROWID for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. All of the programs in DBMS_ROWID run as invoker, meaning that the privileges of the programs are taken from the session running the DBMS_ROWID programs and not from the owner of that package. 9.1.1.1 DBMS_ROWID programs Table 9.1 lists the programs defined for the DBMS_ROWID package. For a dicussion of some of the concepts underlying these program operations, see the next section, "Section 9.1.2, "ROWID Concepts"." 9. Datatype Packages 434 Table 9.1: DBMS_ROWID Programs Name Description Use in SQL ROWID_BLOCK_NUMBER Returns the database block number of the ROWID. Yes ROWID_CREATE Creates a ROWID (either restricted or extended as you request) based on the individual ROWID component values you specify. Use this function for test purposes only. Yes ROWID_INFO Returns information about the specified ROWID. This procedure essentially "parses" the ROWID. Yes ROWID_OBJECT Returns the data object number for an extended ROWID. Returns 0 if the specified ROWID is restricted. Yes ROWID_RELATIVE_FNO Returns the relative file number (relative to the tablespace) of the ROWID. Yes ROWID_ROW_NUMBER Returns the row number of the ROWID. Yes ROWID_TO_ABSOLUTE_FNO Returns the absolute file number (for a row in a given schema and table) from the ROWID. Yes ROWID_TO_EXTENDED Converts a restricted ROWID to an extended ROWID. Yes ROWID_TO_RESTRICTED Converts an extended ROWID to a restricted ROWID. Yes ROWID_TYPE Returns 0 if the ROWID is restricted, 1 if the ROWID is extended. Yes ROWID_VERIFY Returns 0 if the restricted ROWID provided can be converted to an extended format, and 1 otherwise. Yes 9.1.1.2 DBMS_ROWID exceptions Table 9.2 lists the named exceptions defined in the DBMS_ROWID package; they are associated with the error number listed beside the name. Table 9.2: DBMS_ROWID Exceptions Name Number Description ROWID_INVALID −1410 The value entered is larger than the maximum width defined for the column. ROWID_BAD_BLOCK −28516 The block number specified in the ROWID is invalid. [Appendix A] What's on the Companion Disk? 9.1.1 Getting Started with DBMS_ROWID 435 . Pseudo−Column (Oracle8 only) UTL_RAW: Manipulating Raw Data This chapter introduces you to several packages that let you work effectively with particular types of Oracle data: DBMS_ROWID New in Oracle8 ,. ROWID. NOTE: With Oracle8 , there are two types of ROWIDs: extended and restricted. Restricted ROWIDs are the ROWIDs available with Oracle Version 7 and earlier. Extended ROWIDs are used only in Oracle8 . 9.1.1. Oracle8 , allows you to work with the two different ROWID formats: extended (new to Oracle8 ) and restricted (traditional Oracle7 ROWIDs). UTL_RAW Offers a set of functions allowing you to perform concatenation,