Oracle Built−in Packages- P89 potx

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 headers f

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?

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.

Copyright (c) 2000 O'Reilly & Associates All rights reserved.

[Appendix A] What's on the Companion Disk?

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

Table 9.1: DBMS_ROWID Programs

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

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

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

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?