Oracle Built−in Packages- P90 pdf

9.1.1.3 DBMS_ROWID nonprogram elements Table 9.3 lists the named constants defined by the DBMS_ROWID package for use with its programs. Table 9.3: DBMS_ROWID Constants Name/Type Description ROWID_TYPE_RESTRICTED A ROWID type: integer constant assigned the value of 0. ROWID_TYPE_EXTENDED A ROWID type: integer constant assigned the value of 1. ROWID_IS_VALID A ROWID verification result: integer constant assigned the value of 0. ROWID_IS_INVALID A ROWID verification result: integer constant assigned the value of 1. ROWID_OBJECT_UNDEFINED An object type indicating that the object number is not defined (for restricted ROWIDs): integer constant assigned the value of 0. ROWID_CONVERT_INTERNAL A ROWID conversion type: integer constant assigned the value of 0. ROWID_CONVERT_EXTERNAL A ROWID conversion type: integer constant assigned the value of 1. 9.1.2 ROWID Concepts This section offers a quick overview of the Oracle ROWID. You can get much more extensive information on ROWIDs from the Oracle documentation. In the Oracle RDBMS, ROWID is a pseudocolumn that is a part of every table you create. The ROWID is an internally generated and maintained binary value that identifies a row of data in your table. It is called a pseudocolumn because a SQL statement includes it in places where you would normally use a column. However, it is not a column that you create for the table. Instead, the RDBMS generates the ROWID for each row as it is inserted into the database. The information in the ROWID provides the exact physical location of the row in the database. You cannot change the value of a ROWID. You can use the ROWID datatype to store ROWIDs from the database in your PL/SQL program. You can SELECT or FETCH the ROWID for a row into a ROWID variable. To manipulate ROWIDs in Oracle8, you will want to use the DBMS_ROWID package described in this chapter. In Oracle7, you will use the ROWIDTOCHAR function to convert the ROWID to a fixed−length string and then perform operations against that string. In Oracle7, the format of the fixed−length ROWID is, BBBBBBB.RRRR.FFFFF where components of this format have the following meanings: BBBBBBB The block in the database file. RRRR The row in the block (where the first row is zero, not one). FFFFF The database file. All these numbers are hexadecimal; the database file is a number that you would then use to look up the actual name of the database file through the data dictionary. [Appendix A] What's on the Companion Disk? 9.1.1 Getting Started with DBMS_ROWID 436 In Oracle8, ROWIDs have been "extended" to support partitioned tables and indexes. The new, extended ROWIDs include a data object number, identifying the database segment. Any schema object found in the same segment, such as a cluster of tables, will have the same object number. In Oracle8, then, a ROWID contains the following information: • The data object number • The data file (where the first file is 1) • The data block within the data file • The row in the data block (where the first row is 0) Usually (and always in Oracle7), a ROWID will uniquely identify a row of data. Within Oracle8, however, rows in different tables stored in the same cluster can have the same ROWID value. 9.1.3 The DBMS_ROWID Interface The following sections describe the procedures and functions available through DBMS_ROWID. 9.1.3.1 The DBMS_ROWID.ROWID_BLOCK_NUMBER function The ROWID_BLOCK_NUMBER function returns the block number of a ROWID. Its header is, FUNCTION DBMS_ROWID.ROWID_BLOCK_NUMBER (row_id IN ROWID) RETURN NUMBER; where the ROWID parameter is the ROWID from which the value is extracted. 9.1.3.1.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_BLOCK_NUMBER: PRAGMA RESTRICT_REFERENCES (ROWID_BLOCK_NUMBER, WNDS, RNDS, WNPS, RNPS); 9.1.3.2 The DBMS_ROWID.CREATE_ROWID function The CREATE_ROWID function creates and returns 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. Here is its header: FUNCTION DBMS_ROWID.ROWID_CREATE (rowid_type IN NUMBER ,object_number IN NUMBER ,relative_fno IN NUMBER ,block_number IN NUMBER ,row_number IN NUMBER) RETURN ROWID; Parameters are summarized in the following table. Parameter Description [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 437 rowid_type The type of ROWID to be created. Specify either of the named constants ROWID_TYPE_RESTRICTED or ROWID_TYPE_EXTENDED. object_number The data object number for the ROWID. For a restricted ROWID (Oracle7), use the ROWID_OBJECT_UNDEFINED constant. relative_fno The relative file number for the ROWID. block_number The block number for the ROWID. row_number The row number for the ROWID. 9.1.3.2.1 Restrictions The DBMS_ROWID package supplies the following pragma for CREATE_ROWID: PRAGMA RESTRICT_REFERENCES (CREATE_ROWID, WNDS, RNDS, WNPS, RNPS); 9.1.3.2.2 Example Here is an example of a call to the ROWID_CREATE procedure: my_rowid ROWID; BEGIN my_rowid := DBMS_ROWID.ROWID_CREATE (DBMS_ROWID.ROWID_TYPE_EXTENDED, 100, 15, 103, 345); END; / 9.1.3.3 The DBMS_ROWID.ROWID_INFO procedure The ROWID_INFO procedure parses out and returns the individual components of the specified ROWID. Here is its header: PROCEDURE DBMS_ROWID.ROWID_INFO (rowid_in IN ROWID ,rowid_type OUT NUMBER ,object_number OUT NUMBER ,relative_fno OUT NUMBER ,block_number OUT NUMBER ,row_number OUT NUMBER); Parameters are summarized in the following table. Parameter Description rowid_in The ROWID value to be parsed into components. rowid_type The type of ROWID. The value returned will be either of the named constants ROWID_TYPE_RESTRICTED or ROWID_TYPE_EXTENDED. object_number The data object number for the ROWID. For a restricted ROWID (Oracle7), the ROWID_OBJECT_UNDEFINED constant is returned. relative_fno The relative file number for the ROWID. block_number The block number for the ROWID in the file. row_number The row number for the ROWID. [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 438 9.1.3.3.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_INFO: PRAGMA RESTRICT_REFERENCES (ROWID_INFO, WNDS, RNDS, WNPS, RNPS); 9.1.3.4 The DBMS_ROWID.ROWID_OBJECT function The ROWID_OBJECT function returns the object number of a ROWID. The ROWID_OBJECT_UNDEFINED constant is returned for restricted ROWIDs. Its header is, FUNCTION DBMS_ROWID.ROWID_OBJECT (row_id IN ROWID) RETURN NUMBER; where the row_id parameter is the ROWID from which the value is extracted. 9.1.3.4.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_OBJECT: PRAGMA RESTRICT_REFERENCES (ROWID_OBJECT, WNDS, RNDS, WNPS, RNPS); 9.1.3.4.2 Example You will want to obtain a ROWID's object number only if the ROWID type is extended. You would write code like this to perform that check: IF DBMS_ROWID.ROWID_TYPE (v_rowid) = DBMS_ROWID.ROWID_TYPE_EXTENDED THEN v_objnum := DBMS_ROWID.ROWID_OBJECT (v_rowid); END IF; 9.1.3.5 The DBMS_ROWID.ROWID_RELATIVE_FNO function The ROWID_RELATIVE_FNO function returns the relative file number of a ROWID. Its header is, FUNCTION DBMS_ROWID.ROWID_RELATIVE_FNO (row_id IN ROWID) RETURN NUMBER; where the row_id parameter is the ROWID from which the value is extracted. 9.1.3.5.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_RELATIVE_FNO: PRAGMA RESTRICT_REFERENCES (ROWID_RELATIVE_FNO, WNDS, RNDS, WNPS, RNPS); 9.1.3.6 The DBMS_ROWID.ROWID_ROW_NUMBER function The ROWID_ROW_NUMBER function returns the row number of a ROWID. Its header is, FUNCTION DBMS_ROWID.ROWID_ROW_NUMBER (row_id IN ROWID) RETURN NUMBER; where the row_id parameter is the ROWID from which the value is extracted. [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 439 9.1.3.6.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_ROW_NUMBER: PRAGMA RESTRICT_REFERENCES (ROWID_ROW_NUMBER, WNDS, RNDS, WNPS, RNPS); 9.1.3.7 The DBMS_ROWID.ROWID_TO_ABSOLUTE_FNO function The ROWID_TO_ABSOLUTE_FNO function returns the absolute file number of a ROWID. Here is its header: FUNCTION DBMS_ROWID.ROWID_TO_ABSOLUTE_FNO (row_id IN ROWID ,schema_name IN VARCHAR2 ,object_name IN VARCHAR2) RETURN NUMBER; Parameters are summarized in the following table. Parameter Description row_id The ROWID from which the value is extracted. schema_name The name of the schema contains the table. object_name The table name. 9.1.3.7.1 Restrictions The DBMS_ROWID package supplies the following pragma for ROWID_RELATIVE_FNO: PRAGMA RESTRICT_REFERENCES (ROWID_RELATIVE_FNO, WNDS, WNPS, RNPS); 9.1.3.8 The DBMS_ROWID.ROWID_TO_EXTENDED function The ROWID_TO_EXTENDED function converts a restricted ROWID, addressing a specific row in a table, to an extended ROWID. Here is its header: FUNCTION DBMS_ROWID.ROWID_TO_EXTENDED (old_rowid IN ROWID ,schema_name IN VARCHAR2 ,object_name IN VARCHAR2 ,conversion_type IN INTEGER) RETURN ROWID; Parameters are summarized in the following table. Parameter Description old_rowid The ROWID to be converted. schema_name The name of the schema that contains the table. object_name The table name. conversion_type The type of conversion. Pass either the ROWID_CONVERT_INTERNAL constant (if old_ROWID was stored in a column of type ROWID) or ROWID_CONVERT_EXTERNAL (if old_ROWID was stored as a character string). [Appendix A] What's on the Companion Disk? 9.1.3 The DBMS_ROWID Interface 440 . Concepts This section offers a quick overview of the Oracle ROWID. You can get much more extensive information on ROWIDs from the Oracle documentation. In the Oracle RDBMS, ROWID is a pseudocolumn that. for a row into a ROWID variable. To manipulate ROWIDs in Oracle8 , you will want to use the DBMS_ROWID package described in this chapter. In Oracle7 , you will use the ROWIDTOCHAR function to convert. the data block (where the first row is 0) Usually (and always in Oracle7 ), a ROWID will uniquely identify a row of data. Within Oracle8 , however, rows in different tables stored in the same cluster