DBA Data[Home] [Help]

PACKAGE: SYS.AD_DBMS_METADATA

Source


1 PACKAGE ad_dbms_metadata AS
2 /* $Header: adgrants.sql 120.26.12010000.2 2009/01/12 06:39:09 diverma ship $ */
3 ---------------------------
4 -- PROCEDURES AND FUNCTIONS
5 --
6 -- OPEN: Specifies the type of object whose metadata is to be retrieved.
7 -- PARAMETERS:
8 --      object_type     - Identifies the type of objects to be retrieved; i.e.,
9 --              TABLE, INDEX, etc. This determines which view is selected.
10 --      version         - The version of the objects' metadata to be fetched.
11 --              To be used in downgrade scenarios: Objects in the DB that are
12 --              incompatible with an older specified version are not returned.
13 --              Values can be 'COMPATIBLE' (default), 'LATEST' or a specific
14 --              version number.
15 --      model           - The view of the metadata, such as Oracle proprietary,
16 --              ANSI99, etc.  Currently only 'ORACLE' is supported.
17 --      network_link    - The name of a database link to the database
18 --              whose data is to be retrieved.  If NULL (default), metadata
19 --              is retrieved from the database on which the caller is running.
20 --
21 -- RETURNS:
22 --      A handle to be used in subsequent calls to SET_FILTER, SET_COUNT,
23 --      ADD_TRANSFORM, GET_QUERY, SET_PARSE_ITEM, FETCH_xxx and CLOSE.
24 -- EXCEPTIONS:
25 --      INVALID_ARGVAL  - a NULL or invalid value was supplied for an input
26 --              parameter.
27 
28   FUNCTION open (
29                 object_type     IN  VARCHAR2,
30                 version         IN  VARCHAR2 DEFAULT 'COMPATIBLE',
31                 model           IN  VARCHAR2 DEFAULT 'ORACLE')
32         RETURN NUMBER;
33 
34 -- SET_FILTER: Specifies restrictions on the objects whose metadata
35 --      is to be retrieved.
36 --      This function is overloaded: the filter value can be a varchar2,
37 --      number or boolean.
38 -- PARAMETERS:
39 --      handle          - Context handle from previous OPEN call.
40 --      name            - Name of the filter.
41 --      value           - Value of the filter.
42 --      object_type_path- Path name of object types to which
43 --                        the filter applies.
44 
45   PROCEDURE set_filter (
46                 handle                  IN  NUMBER,
47                 name                    IN  VARCHAR2,
48                 value                   IN  VARCHAR2);
49 
50   PROCEDURE set_filter (
51                 handle                  IN  NUMBER,
52                 name                    IN  VARCHAR2,
53                 value                   IN  BOOLEAN DEFAULT TRUE);
54 
55 
56 
57 -- SET_COUNT: Specifies the number of objects to be returned in a single
58 --      FETCH_xxx call.
59 -- PARAMETERS:
60 --      handle          - Context handle from previous OPEN call.
61 --      value           - Number of objects to retrieve.
62 
63   PROCEDURE set_count (
64                 handle                  IN  NUMBER,
65                 value                   IN  NUMBER);
66 
67 
68 -- GET_QUERY:   Return the text of the query (or queries) that will be
69 --              used by FETCH_xxx.  This function is provided to aid
70 --              in debugging.
71 -- PARAMETERS:  handle  - Context handle from previous OPEN call.
72 -- RETURNS:     Text of the query.
73 
74   FUNCTION get_query (
75                 handle          IN  NUMBER)
76         RETURN VARCHAR2;
77 
78 
79 -- SET_PARSE_ITEM: Enables output parsing and specifies an object attribute
80 --      to be parsed and returned
81 -- PARAMETERS:
82 --      handle  - Context handle from previous OPEN call.
83 --      name    - Attribute name.
84 --      object_type- Object type to which the transform applies.
85 
86   PROCEDURE set_parse_item (
87                 handle          IN  NUMBER,
88                 name            IN  VARCHAR2);
89 
90 -- ADD_TRANSFORM : Specify a transform to be applied to the XML representation
91 --              of objects processed by FETCH_xxx, CONVERT or PUT.
92 -- PARAMETERS:  handle  - Context handle from previous OPEN or OPENW call.
93 --              name    - The name of the transform: Can be 'DDL' to generate
94 --                        creation DDL or a URI pointing to a stylesheet,
95 --                        either external or internal to the DB (the latter
96 --                        being an Xpath spec. starting with '/oradb').
97 --              encoding- If name is a URI, this specifies the encoding of the
98 --                        target stylesheet. If left NULL, then if uri starts
99 --                        with  '/oradb', then the database char. set is used;
100 --                        otherwise, 'UTF-8'. Use 'US-ASCII' for better perf.
101 --                        if you can. May be any valid NLS char. set name.
102 --                        Ignored if name is an internal transform name (like
103 --                        DDL), not a URI.
104 --              object_type- Object type to which the transform applies.
105 --
106 -- NOTE: If name is an intra-DB uri (ie, /oradb) that points to an NCLOB
107 --       column or a CLOB with an encoding different from the database charset,
108 --       you must explicitly specify the encoding.
109 -- RETURNS:     An opaque handle to the transform to be used in subsequent
110 --              calls to SET_TRANSFORM_PARAM.
111 
112   FUNCTION add_transform (
113                 handle          IN NUMBER,
114                 name            IN VARCHAR2,
115                 encoding        IN VARCHAR2 DEFAULT NULL)
116         RETURN NUMBER;
117 
118 
119 -- SET_TRANSFORM_PARAM: Specifies a value for a parameter to the XSL-T
120 --      stylesheet identified by handle.
121 --      This procedure is overloaded: the parameter value can be a varchar2,
122 --      a number or a boolean.
123 -- PARAMETERS:
124 --      transform_handle - Handle from previous ADD_TRANSFORM call.
125 --      name             - Name of the parameter.
126 --      value            - Value for the parameter.
127 --      object_type      - Object type to which the transform param applies.
128 
129   PROCEDURE set_transform_param (
130                 transform_handle        IN  NUMBER,
131                 name                    IN  VARCHAR2,
132                 value                   IN  VARCHAR2);
133 
134 
135   PROCEDURE set_transform_param (
136                 transform_handle        IN  NUMBER,
137                 name                    IN  VARCHAR2,
138                 value                   IN  BOOLEAN DEFAULT TRUE);
139 
140 -- SET_REMAP_PARAM: Specifies a value for a parameter to the XSL-T
141 --      stylesheet identified by handle.
142 -- PARAMETERS:
143 --      transform_handle - Handle from previous ADD_TRANSFORM call.
144 --      name             - Name of the parameter.
145 --      old_value        - Old value for the remapping
146 --      new_value        - New value for the remapping
147 --      object_type      - Object type to which the transform param applies.
148 
149   PROCEDURE set_remap_param (
150                 transform_handle        IN  NUMBER,
151                 name                    IN  VARCHAR2,
152                 old_value               IN  VARCHAR2,
153                 new_value               IN  VARCHAR2);
154 
155 -- FETCH_XML:   Return metadata for objects as XML documents. This version
156 --              can return multiple objects per call (when the SET_COUNT
157 --              'value' parameter > 1).
158 -- PARAMETERS:  handle  - Context handle from previous OPEN call.
159 -- RETURNS:     XML metadata for the objects as an XMLType, or NULL if all
160 --              objects have been fetched.
161 -- EXCEPTIONS:  Throws an exception if DDL transform has been added
162 
163   FUNCTION fetch_xml (handle    IN NUMBER)
164         RETURN sys.XMLType;
165 
166 
167 -- FETCH_DDL:   Return metadata as DDL.
168 --              More than one DDL statement may be returned.
169 -- RETURNS:     Metadata for the objects as one or more DDL statements
170 -- PARAMETERS:  handle  - Context handle from previous OPEN call.
171 
172   FUNCTION fetch_ddl (
173                 handle  IN NUMBER)
174         RETURN sys.ku$_ddls;
175 
176 
177 -- FETCH_CLOB:  Return metadata for object (transformed or not) as a CLOB.
178 -- PARAMETERS:  handle  - Context handle from previous OPEN call.
179 --              cache_lob - TRUE = read LOB into buffer cache
180 --              lob_duration - either DBMS_LOB.SESSION (default)
181 --                or DBMS_LOB.CALL, the duration for the termporary lob
182 -- RETURNS:     XML metadata for the objects as a CLOB, or NULL if all
183 --              objects have been fetched.
184 
185   FUNCTION fetch_clob (handle       IN NUMBER)
186         RETURN CLOB;
187 
188 
189 -- PROCEDURE FETCH_CLOB: Same as above but with IN/OUT NOCOPY CLOB. CLOB
190 --              must be pre-created prior to call.
191 
192   PROCEDURE fetch_clob (
193                 handle  IN NUMBER,
194                 xmldoc  IN OUT NOCOPY CLOB);
195 
196 
197   PROCEDURE CLOSE (handle IN NUMBER);
198 
199 
200 -- GET_XML:     Return the metadata for a single object as XML.
201 --      This interface is meant for casual browsing (e.g., from SQLPlus)
202 --      vs. the programmatic OPEN / FETCH / CLOSE interfaces above.
203 -- PARAMETERS:
204 --      object_type     - The type of object to be retrieved.
205 --      name            - Name of the object.
206 --      schema          - Schema containing the object.  Defaults to
207 --                        the caller's schema.
208 --      version         - The version of the objects' metadata.
209 --      model           - The object model for the metadata.
210 --      transform       - XSL-T transform to be applied.
211 -- RETURNS:     Metadata for the object as an NCLOB.
212 
213   FUNCTION get_xml (
214                 object_type     IN  VARCHAR2,
215                 name            IN  VARCHAR2,
216                 schema          IN  VARCHAR2 DEFAULT NULL,
217                 version         IN  VARCHAR2 DEFAULT 'COMPATIBLE',
218                 model           IN  VARCHAR2 DEFAULT 'ORACLE',
219                 transform       IN  VARCHAR2 DEFAULT NULL)
220         RETURN CLOB;
221 
222 
223 -- GET_DDL:     Return the metadata for a single object as DDL.
224 --      This interface is meant for casual browsing (e.g., from SQLPlus)
225 --      vs. the programmatic OPEN / FETCH / CLOSE interfaces above.
226 -- PARAMETERS:
227 --      object_type     - The type of object to be retrieved.
228 --      name            - Name of the object.
229 --      schema          - Schema containing the object.  Defaults to
230 --                        the caller's schema.
231 --      version         - The version of the objects' metadata.
232 --      model           - The object model for the metadata.
233 --      transform       - XSL-T transform to be applied.
234 -- RETURNS:     Metadata for the object transformed to DDL as a CLOB.
235 
236   FUNCTION get_ddl (
237                 object_type     IN  VARCHAR2,
238                 name            IN  VARCHAR2,
239                 schema          IN  VARCHAR2 DEFAULT NULL,
240                 version         IN  VARCHAR2 DEFAULT 'COMPATIBLE',
241                 model           IN  VARCHAR2 DEFAULT 'ORACLE',
242                 transform       IN  VARCHAR2 DEFAULT 'DDL')
243         RETURN CLOB;
244 
245 -- GET_DEPENDENT_XML:   Return the metadata for objects dependent on a
246 --      base object as XML.
247 --      This interface is meant for casual browsing (e.g., from SQLPlus)
248 --      vs. the programmatic OPEN / FETCH / CLOSE interfaces above.
249 -- PARAMETERS:
250 --      object_type     - The type of object to be retrieved.
251 --      base_object_name- Name of the base object.
252 --      base_object_schema- Schema containing the base object.  Defaults to
253 --                        the caller's schema.
254 --      version         - The version of the objects' metadata.
255 --      model           - The object model for the metadata.
256 --      transform       - XSL-T transform to be applied.
257 --      object_count    - maximum number of objects to return
258 -- RETURNS:     Metadata for the object as a CLOB.
259 
260   FUNCTION get_dependent_xml (
261                 object_type             IN  VARCHAR2,
262                 base_object_name        IN  VARCHAR2,
263                 base_object_schema      IN  VARCHAR2 DEFAULT NULL,
264                 version                 IN  VARCHAR2 DEFAULT 'COMPATIBLE',
265                 model                   IN  VARCHAR2 DEFAULT 'ORACLE',
266                 transform               IN  VARCHAR2 DEFAULT NULL,
267                 object_count            IN  NUMBER   DEFAULT 10000)
268         RETURN CLOB;
269 
270 -- GET_DEPENDENT_DDL:   Return the metadata for objects dependent on a
271 --      base object as DDL.
272 --      vs. the programmatic OPEN / FETCH / CLOSE interfaces above.
273 -- PARAMETERS:
274 --      object_type     - The type of object to be retrieved.
275 --      base_object_name- Name of the base object.
276 --      base_object_schema- Schema containing the base object.  Defaults to
277 --                        the caller's schema.
278 --      version         - The version of the objects' metadata.
279 --      model           - The object model for the metadata.
280 --      transform       - XSL-T transform to be applied.
281 --      object_count    - maximum number of objects to return
282 -- RETURNS:     Metadata for the object as a CLOB.
283 
284   FUNCTION get_dependent_ddl (
285                 object_type             IN  VARCHAR2,
286                 base_object_name        IN  VARCHAR2,
287                 base_object_schema      IN  VARCHAR2 DEFAULT NULL,
288                 version                 IN  VARCHAR2 DEFAULT 'COMPATIBLE',
289                  model                   IN  VARCHAR2 DEFAULT 'ORACLE',
290                 transform               IN  VARCHAR2 DEFAULT 'DDL',
291                 object_count            IN  NUMBER   DEFAULT 10000)
292         RETURN CLOB;
293 
294 
295 END AD_DBMS_METADATA;