1 package dbms_rowid is
2 ------------
3 -- OVERVIEW
4 --
5 -- This package provides procedures to create ROWIDs and to interpret
6 -- their contents
7
8 -- SECURITY
9 --
10 -- The execution privilege is granted to PUBLIC. Procedures in this
11 -- package run under the caller security.
12
13
14 ----------------------------
15
16 ----------------------------
17
18 -- ROWID TYPES:
19 --
20 -- RESTRICTED - Restricted ROWID
21 --
22 -- EXTENDED - Extended ROWID
23 --
24 rowid_type_restricted constant integer := 0;
25 rowid_type_extended constant integer := 1;
26
27 -- ROWID VERIFICATION RESULTS:
28 --
29 -- VALID - Valid ROWID
30 --
31 -- INVALID - Invalid ROWID
32 --
33 rowid_is_valid constant integer := 0;
34 rowid_is_invalid constant integer := 1;
35
36 -- OBJECT TYPES:
37 --
38 -- UNDEFINED - Object Number not defined (for restricted ROWIDs)
39 --
40 rowid_object_undefined constant integer := 0;
41
42 -- ROWID CONVERSION TYPES:
43 --
44 -- INTERNAL - convert to/from column of ROWID type
45 --
46 -- EXTERNAL - convert to/from string format
47 --
48 rowid_convert_internal constant integer := 0;
49 rowid_convert_external constant integer := 1;
50
51 -- EXCEPTIONS:
52 --
53 -- ROWID_INVALID - invalid rowid format
54 --
55 -- ROWID_BAD_BLOCK - block is beyond end of file
56 --
57 ROWID_INVALID exception;
58 pragma exception_init(ROWID_INVALID, -1410);
59 ROWID_BAD_BLOCK exception;
60 pragma exception_init(ROWID_BAD_BLOCK, -28516);
61
62 -- PROCEDURES AND FUNCTIONS:
63 --
64
65 --
66 -- ROWID_CREATE constructs a ROWID from its constituents:
67 --
68 -- rowid_type - type (restricted/extended)
69 -- object_number - data object number (rowid_object_undefined for restricted)
70 -- relative_fno - relative file number
71 -- block_number - block number in this file
72 -- file_number - file number in this block
73 --
74 function rowid_create(rowid_type IN number,
75 object_number IN number,
76 relative_fno IN number,
77 block_number IN number,
78 row_number IN number)
79 return rowid;
80 pragma RESTRICT_REFERENCES(rowid_create,WNDS,RNDS,WNPS,RNPS);
81
82 --
83 -- ROWID_INFO breaks ROWID into its components and returns them:
84 --
85 -- rowid_in - ROWID to be interpreted
86 -- rowid_type - type (restricted/extended)
87 -- object_number - data object number (rowid_object_undefined for restricted)
88 -- relative_fno - relative file number
89 -- block_number - block number in this file
90 -- file_number - file number in this block
91 -- ts_type_in - type of tablespace which this row belongs to
92 -- 'BIGFILE' indicates Bigfile Tablespace
93 -- 'SMALLFILE' indicates Smallfile (traditional pre-10i) TS.
94 -- NOTE: These two are the only allowed values for this param
95 --
96 procedure rowid_info( rowid_in IN rowid,
97 rowid_type OUT number,
98 object_number OUT number,
99 relative_fno OUT number,
100 block_number OUT number,
101 row_number OUT number,
102 ts_type_in IN varchar2 default 'SMALLFILE');
103 pragma RESTRICT_REFERENCES(rowid_info,WNDS,RNDS,WNPS,RNPS);
104
105 --
106 -- ROWID_TYPE returns the type of a ROWID (restricted/extended_nopart,..)
107 --
108 -- row_id - ROWID to be interpreted
109 --
110 function rowid_type(row_id IN rowid)
111 return number;
112 pragma RESTRICT_REFERENCES(rowid_type,WNDS,RNDS,WNPS,RNPS);
113
114 --
115 -- ROWID_OBJECT extracts the data object number from a ROWID.
116 -- ROWID_OBJECT_UNDEFINED is returned for restricted rowids.
117 --
118 -- row_id - ROWID to be interpreted
119 --
120 function rowid_object(row_id IN rowid)
121 return number;
122 pragma RESTRICT_REFERENCES(rowid_object,WNDS,RNDS,WNPS,RNPS);
123
124 --
125 -- ROWID_RELATIVE_FNO extracts the relative file number from a ROWID.
126 --
127 -- row_id - ROWID to be interpreted
128 -- ts_type_in - type of tablespace which this row belongs to
129 --
130 function rowid_relative_fno(row_id IN rowid,
131 ts_type_in IN varchar2 default 'SMALLFILE')
132 return number;
133 pragma RESTRICT_REFERENCES(rowid_relative_fno,WNDS,RNDS,WNPS,RNPS);
134
135 --
136 -- ROWID_BLOCK_NUMBER extracts the block number from a ROWID.
137 --
138 -- row_id - ROWID to be interpreted
139 -- ts_type_in - type of tablespace which this row belongs to
140 --
141 --
142 function rowid_block_number(row_id IN rowid,
143 ts_type_in IN varchar2 default 'SMALLFILE')
144 return number;
145 pragma RESTRICT_REFERENCES(rowid_block_number,WNDS,RNDS,WNPS,RNPS);
146
147 --
148 -- ROWID_ROW_NUMBER extracts the row number from a ROWID.
149 --
150 -- row_id - ROWID to be interpreted
151 --
152 function rowid_row_number(row_id IN rowid)
153 return number;
154 pragma RESTRICT_REFERENCES(rowid_row_number,WNDS,RNDS,WNPS,RNPS);
155
156 --
157 -- ROWID_TO_ABSOLUTE_FNO extracts the relative file number from a ROWID,
158 -- which addresses a row in a given table
159 --
160 -- row_id - ROWID to be interpreted
161 --
162 -- schema_name - name of the schema which contains the table
163 --
164 -- object_name - table name
165 --
166 function rowid_to_absolute_fno(row_id IN rowid,
167 schema_name IN varchar2,
168 object_name IN varchar2)
169 return number;
170 pragma RESTRICT_REFERENCES(rowid_to_absolute_fno,WNDS,WNPS,RNPS);
171
172 --
173 -- ROWID_TO_EXTENDED translates the restricted ROWID which addresses
174 -- a row in a given table to the extended format. Later, it may be removed
175 -- from this package into a different place
176 --
177 -- old_rowid - ROWID to be converted
178 --
179 -- schema_name - name of the schema which contains the table (OPTIONAL)
180 --
181 -- object_name - table name (OPTIONAL)
182 --
183 -- conversion_type - rowid_convert_internal/external_convert_external
184 -- (whether old_rowid was stored in a column of ROWID
185 -- type, or the character string)
186 --
187 function rowid_to_extended(old_rowid IN rowid,
188 schema_name IN varchar2,
189 object_name IN varchar2,
190 conversion_type IN integer)
191 return rowid;
192 pragma RESTRICT_REFERENCES(rowid_to_extended,WNDS,WNPS,RNPS);
193
194 --
195 -- ROWID_TO_RESTRICTED translates the extnded ROWID into a restricted format
196 --
197 -- old_rowid - ROWID to be converted
198 --
199 -- conversion_type - internal/external (IN)
200 --
201 -- conversion_type - rowid_convert_internal/external_convert_external
202 -- (whether returned rowid will be stored in a column of
203 -- ROWID type, or the character string)
204 --
205 function rowid_to_restricted(old_rowid IN rowid,
206 conversion_type IN integer)
207 return rowid;
208 pragma RESTRICT_REFERENCES(rowid_to_restricted,WNDS,RNDS,WNPS,RNPS);
209
210 --
211 -- ROWID_VERIFY verifies the ROWID. It returns rowid_valid or rowid_invalid
212 -- value depending on whether a given ROWID is valid or not.
213 --
214 -- rowid_in - ROWID to be verified
215 --
216 -- schema_name - name of the schema which contains the table
217 --
218 -- object_name - table name
219 --
220 -- conversion_type - rowid_convert_internal/external_convert_external
221 -- (whether old_rowid was stored in a column of ROWID
222 -- type, or the character string)
223 --
224 function rowid_verify(rowid_in IN rowid,
225 schema_name IN varchar2,
226 object_name IN varchar2,
227 conversion_type IN integer)
228 return number;
229 pragma RESTRICT_REFERENCES(rowid_verify,WNDS,WNPS,RNPS);
230
231 end;