9.1.3.8.1 Restrictions Note the following restrictions on calling ROWID_TO_EXTENDED: • The ROWID_TO_EXTENDED function returns a ROWID in the extended character format. If you provide a NULL ROWID, the function will return NULL. If a zero−valued ROWID is supplied (00000000.0000.0000), a zero−valued restricted ROWID is returned. • The DBMS_ROWID package supplies the following pragma for ROWID_TO_EXTENDED: PRAGMA RESTRICT_REFERENCES (ROWID_TO_EXTENDED, WNDS, WNPS, RNPS); • If the schema and object names are provided as IN parameters, this function first verifies that you have SELECT privilege on the table named. It then converts the restricted ROWID provided to an extended ROWID, using the data object number of the specified table. Even if ROWID_TO_EXTENDED returns a value, however, that does not guarantee that the converted ROWID actually references a valid row in the table, either at the time that the function is called, or when the extended ROWID is actually used. It is only performing a conversion. • If the schema and object name are not provided (i.e., are passed as NULL), then this function attempts to fetch the page specified by the restricted ROWID provided. It treats the file number stored in this ROWID as the absolute file number. This may cause problems if the file has been dropped, and its number has been reused prior to the data migration. If the fetched page belongs to a valid table, the data object number of this table is used in converting to an extended ROWID value. This approach is very inefficient. Oracle recommends doing this only as a last resort, when the target table is not known. Note that the user must still be aware of the correct table name when using the converted ROWID. • If an extended ROWID value is supplied, that ROWID's data object is verified against the data object number calculated from the table name argument. If the two numbers do not match, DBMS_ROWID raises the INVALID_ROWID exception. If there is a match, then the input ROWID is returned. 9.1.3.8.2 Example Suppose that I have a table in my APP schema called ROWID_conversion. This table contains two columns: ROWID_value and table_name. The ROWID_value column contains the restricted−format ROWIDs for rows in the table specifed by the table_name column. I can then convert all of my restricted ROWID values to extended ones with the following UPDATE statement: UPDATE app.rowid_conversion SET rowid_value = DBMS_ROWID.ROWID_TO_EXTENDED (rowid_value, 'APP', table_name, DBMS_ROWID.ROWID_CONVERT_INTERNAL);. [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 441 9.1.3.9 The DBMS_ROWID.ROWID_TO_RESTRICTED function The ROWID_TO_RESTRICTED function converts an extended ROWID to a restricted ROWID. Here is its header: FUNCTION DBMS_ROWID.ROWID_TO_RESTRICTED (old_rowid IN ROWID ,conversion_type IN INTEGER) RETURN ROWID; Parameters are summarized in the following table. Parameter Description old_rowid The ROWID to be converted. conversion_type The format of the returned ROWID. Pass either the ROWID_CONVERT_INTERNAL constant (if the returned ROWID is to be stored in a column of type ROWID) or the ROWID_CONVERT_EXTERNAL constant (if the returned ROWID is to be stored as a character string). 9.1.3.9.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_TO_RESTRICTED: PRAGMA RESTRICT_REFERENCES (ROWID_TO_RESTRICTED, WNDS, RNDS, WNPS, RNPS); 9.1.3.10 The DBMS_ROWID.ROWID_TYPE function The ROWID_TYPE function returns the type of a ROWID via one of the following package constants: ROWID_TYPE_RESTRICTED or ROWID_TYPE_EXTENDED. Its header is, FUNCTION DBMS_ROWID.ROWID_TYPE (row_id IN ROWID) RETURN NUMBER; where the row_id parameter is the ROWID from which the value is extracted. 9.1.3.10.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_TYPE: PRAGMA RESTRICT_REFERENCES (ROWID_TYPE, WNDS, RNDS, WNPS, RNPS); 9.1.3.10.2 Example In the following query, I determine the ROWID types in the emp table: SELECT DISTINCT (DBMS_ROWID.ROWID_TYPE(ROWID)) FROM emp; This returns the value of 1, that is: DBMS_ROWID.ROWID_TYPE_EXTENDED. The emp table was created under Oracle8 and therefore uses the Oracle8 type of ROWID. 9.1.3.11 The DBMS_ROWID.ROWID_VERIFY function The ROWID_VERIFY function verifies a ROWID. It returns either the ROWID_VALID or ROWID_INVALID constants. Here is its header: [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 442 FUNCTION DBMS_ROWID.ROWID_VERIFY (rowid_in IN ROWID ,schema_name IN VARCHAR2 ,object_name IN VARCHAR2 ,conversion_type IN INTEGER) RETURN NUMBER; Parameters are summarized in the following table. Parameter Description rowid_in The ROWID to be verified. schema_name The name of the schema containing the table. object_name The name of the table. conversion_type The type of conversion to be used for the verification. You should pass either the ROWID_CONVERT_INTERNAL constant (if ROWID_in is stored in a column of type ROWID) or the ROWID_CONVERT_EXTERNAL constant (if ROWID_in is stored as a character string). 9.1.3.11.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_VERIFY: PRAGMA RESTRICT_REFERENCES (ROWID_VERIFY, WNDS, WNPS, RNPS); 9.1.3.11.2 Example Interestingly, you can call this numeric function as a kind of Boolean function within SQL. Suppose that I want to find all the invalid ROWIDs prior to converting them from restricted to extended. I could write the following query (using the same tables used in the example for the ROWID_TO_EXTENDED function): SELECT ROWID, rowid_value FROM app.rowid_conversion WHERE DBMS_ROWID.ROWID_VERIFY (rowid_value, NULL, NULL, 0) = 1; 8.3 DBMS_LOB Interface 9.2 UTL_RAW: Manipulating Raw Data Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 443 Chapter 9 Datatype Packages 9.2 UTL_RAW: Manipulating Raw Data The UTL_RAW package contains a set of programs that allow you to manipulate raw data. This package was originally written as a component of the Oracle Server's advanced replication option, and it supported procedural replication of data across different NLS (National Language Support) language databases. By converting data to RAW, the remote procedure calls would not perform NLS conversion, thus preserving the nature of some special data. The functions included in this package actually go beyond this original functionality and provide a toolkit for the manipulation of raw data that is not otherwise available in the Oracle Server product. These functions perform a number of special operations: conversion and coercion, slicing and dicing of raw data, and bit−fiddling, all described in the next section. Other than replication support, there are a number of advantages Oracle can offer in storing raw data in the database, such as tighter integration with the rest of the application, transaction−level consistency, concurrency, and recoverability. One of the difficulties in the use of raw data in an Oracle database has been in the poor support for manipulation of this data. The UTL_RAW package provides this support. 9.2.1 Getting Started with UTL_RAW The UTL_RAW package is created when the Oracle database is installed. The utlraw.sql script (found in the built−in packages source code directory, as described in Chapter 1) contains the source code for this package's specification and body. This script is called by catrep.sql, which is run when the advanced replication option of the Oracle database is installed. If this package is not already installed, check to see if these files are in your admin subdirectory. If so, you can connect as SYS and install this package by running the two scripts in the following order: SQL> @utlraw.sql SQL> @prvtrawb.plb 9.2.1.1 UTL_RAW programs Table 9.4 lists the programs provided by the UTL_RAW package. For a discussion of some of the concepts underlying the operations performed by these programs, see the next section, "Section 9.2.2, "Raw Data Manipulation Concepts"." Table 9.4: UTL_RAW Programs Name Description Use In SQL BIT_AND Performs bitwise logical AND of the values in raw r1 with raw r2 and returns the ANDed result raw. Yes BIT_COMPLEMENT Performs bitwise logical "complement" of the values in raw r and returns the "complemented" Yes 444 result raw. BIT_OR Performs bitwise logical OR of the values in raw r1 with raw r2 and returns the ORed result raw. Yes BIT_XOR Performs bitwise logical "exclusive or" (XOR) of the values in raw r1 with raw r2 and returns the XORed result raw. Yes CAST_TO_RAW Converts a VARCHAR2 string represented using N data bytes into a raw with N data bytes. Yes CAST_TO_VARCHAR2 Converts a raw represented using N data bytes into a VARCHAR2 string with N data bytes. Yes COMPARE Compares raw r1 against raw r2. Returns 0 if r1 and r2 are identical; otherwise, returns the position of the first byte from r1 that does not match r2. Yes CONCAT Concatenates a set of up to 12 raws into a single raw. Yes CONVERT Converts a raw from one character set to another character set. Yes COPIES Returns N copies of the original raw concatenated together. Yes LENGTH Returns the length in bytes of a raw. Yes OVERLAY Overlays the specified portion of a raw with a different raw value. Yes REVERSE Reverses the byte sequence in the raw from end to end. Yes SUBSTR Returns the specified sub−portion of a raw. Yes TRANSLATE Translates original bytes in the raw with the specified replacement set. Yes TRANSLITERATE Translates original bytes in the raw with the specified replacement set following rules, which result in the transliterated raw always being the same length as the original raw. Yes XRANGE Returns a raw containing all valid 1−byte encodings in succession beginning with the value start_byte and ending with the value end_byte. Yes UTL_RAW does not declare any exceptions or nonprogram elements. [Appendix A] What's on the Companion Disk? 445 . value of 1, that is: DBMS_ROWID.ROWID_TYPE_EXTENDED. The emp table was created under Oracle8 and therefore uses the Oracle8 type of ROWID. 9.1.3.11 The DBMS_ROWID.ROWID_VERIFY function The ROWID_VERIFY. Getting Started with UTL_RAW The UTL_RAW package is created when the Oracle database is installed. The utlraw.sql script (found in the built−in packages source code directory, as described in Chapter. that allow you to manipulate raw data. This package was originally written as a component of the Oracle Server's advanced replication option, and it supported procedural replication of data