1 PACKAGE utl_xml AUTHID DEFINER AS
2
3 -- Opaque handles
4 SUBTYPE xmlCtx IS PLS_INTEGER; -- Handle to a parser: It's really just
5 -- a monotonically increasing ub4 per
6 -- session.
7
8 ----------------------------------------
9 -- CONSTANTS
10 ----------------------------------------
11 --
12 -- These are parse flags corresponding to their counterparts in lpx.h
13 VALIDATE CONSTANT BINARY_INTEGER := 1;
14 DISCARD_WHITESPACE CONSTANT BINARY_INTEGER := 2;
15 DTD_ONLY CONSTANT BINARY_INTEGER := 4;
16 STOP_ON_WARNING CONSTANT BINARY_INTEGER := 8;
17
18 ----------------------------------------
19 -- PUBLIC INTERFACE
20 ----------------------------------------
21
22 -- XSLLOADFROMFILE: Load an XSL stylesheet from a BFILE into a CLOB
23 -- PARAMS:
24 -- destLob - LOB locator of target for the load
25 -- srcFile - BFILE locator of the source for the load
26 -- amount - number of bytes to load from the BFILE
27
28 PROCEDURE xslLoadFromFile(destLob IN CLOB,
29 srcFile IN BFILE,
30 amount IN BINARY_INTEGER
31 );
32
33 -- GETFDO: Return the format descriptor object for objects on this platform.
34 -- PARAMS: None.
35 -- Returns: Returns the RAW(100) FDO.
36
37 FUNCTION getFdo RETURN RAW;
38
39 -- GETNEXTTYPEID: Given the current value of next_typeid for a type hierarchy
40 -- and another typeid, see if next_typeid needs to be incremented,
41 -- and, if so, what its new value should be.
42 -- PARAMS:
43 -- next_typeid - current next_typeid value
44 -- typeid - another typeid
45 -- new_next_typeid - the new next_typeid value
46 -- or NULL if no increment needed.
47
48 PROCEDURE getNextTypeid (next_typeid IN RAW,
49 typeid IN RAW,
50 new_next_typeid OUT RAW);
51
52 -- GETHASHCODE: Upgrade from 817 corrupts the hashcode in type$,
53 -- so we have to get it by calling kotgHashCode.
54 -- PARAMS:
55 -- schema - type schema
56 -- typename - type name
57 -- flag - 1 = only return V1 hashcode
58 -- 0 = return the hashcode whatever version it is
59 -- hashcode - returned hashcode
60
61 PROCEDURE getHashCode (schema IN VARCHAR2,
62 typename IN VARCHAR2,
63 flag IN BINARY_INTEGER,
64 hashcode OUT RAW);
65
66 -- TYPEHASHCODEEQ: Does the hashcode match the hc for the type?
67 -- The type hashcode versions changed between 10.2 and 11g
68 -- so a simple compare doesn't work. This is a wrapper around
69 -- kottyphcequ.
70 -- PARAMS:
71 -- schema - type schema
72 -- typename - type name
73 -- hashcode - hashcode to check
74 -- RETURNS: TRUE if a match
75
76 FUNCTION typeHashCodeEq (schema IN VARCHAR2,
77 typename IN VARCHAR2,
78 hashcode IN RAW)
79 RETURN BOOLEAN;
80
81 -- HASTSTZ: Does the type have a TSTZ element or attribute?
82 -- PARAMS:
83 -- schema - type schema
84 -- typename - type name
85 -- RETURNS: TRUE if it does
86
87 FUNCTION HasTstz (schema IN VARCHAR2,
88 typename IN VARCHAR2)
89 RETURN BOOLEAN;
90
91 -- LONG2CLOB: Fetch a LONG as a CLOB
92 -- PARAMS:
93 -- tab - table name
94 -- col - column name
95 -- row_id - rowid value
96 -- lobloc - a LOB locator to receive the long value
97 -- NOTE: tab and col must belong to a short list of valid values;
98 -- see prvtcxml.sql
99
100
101 PROCEDURE long2clob (
102 tab IN VARCHAR2,
103 col IN VARCHAR2,
104 row_id IN ROWID,
105 lobloc IN OUT NOCOPY CLOB
106 );
107
108 -- PARSEEXPR: Parse an expression (boolean or arithmetic)
109 -- and return in a CLOB as XML
110 -- PARAMS:
111 -- schema - schema
112 -- tab - table name
113 -- sqltext - the text of the expression
114 -- arith - non-0 = sqltext is an arithmetic expression
115 -- lobloc - a LOB locator to receive the parsed value
116
117 PROCEDURE parseExpr (schema IN VARCHAR2,
118 tab IN VARCHAR2,
119 sqltext IN CLOB,
120 arith IN BINARY_INTEGER,
121 lobloc IN OUT NOCOPY CLOB
122 );
123
124 -- PARSEQUERY: Parse a SQL query and return in a CLOB as XML
125 -- PARAMS:
126 -- user - user
127 -- sqltext - the text of the query
128 -- lobloc - a LOB locator to receive the parsed value
129
130 PROCEDURE parseQuery (user IN VARCHAR2,
131 sqltext IN CLOB,
132 lobloc IN OUT NOCOPY CLOB
133 );
134
135 -- XMLSETMEMDEBUG: Set kux's Lpx memory tracing
136 PROCEDURE xmlSetMemDebug (value IN BOOLEAN);
137
138
139 -- XMLDUMPCTXS: Dump info on the active XML contexts to the trace file.
140 PROCEDURE xmlDumpCtxs;
141
142
143 -- XMLINIT: Initializes a DOM XML Parser.
144 -- PARAMS: None.
145 -- RETURNS: An opaque handle to this parser.
146 -- NOTE: Encoding (a param. in the C LpxInitialize) is specified in XMLPARSE
147 -- on a per-document basis. The implementation registers a private error
148 -- hdlr. and UGA memory alloc. routines for session duration scope.
149 -- This routine must be called before any others in this package.
150
151 FUNCTION xmlInit RETURN xmlCtx;
152
153 -- XMLSETPARSEFLAGS: Sets parsing options for this parser.
154 -- NOTE: These are sticky across parses using the same parser.
155 -- PARAMS:
156 -- ctx - Parser context to which the flag should apply.
157 -- flag - a valid parsing option:
158 -- VALIDATE: Perform XML validation as per XML 1.0 spec.
159 -- DEFAULT: NO
160 -- DISCARD_WHITESPACE: Remove all whitespace between elements
161 -- DEFAULT: NO
162 -- DTD_ONLY: Parse just the DTD
163 -- DEFAULT: NO
164 -- STOP_ON_WARNING: Return to caller on warnings rather than just
165 -- throw the error to stdout and continuing.
166 -- DEFAULT: NO
167 -- value - TRUE or FALSE to enable or disable the flag.
168
169 PROCEDURE xmlSetParseFlag( ctx IN xmlctx,
170 flag IN BINARY_INTEGER,
171 value IN BOOLEAN
172 );
173
174 -- XMLPARSE: Parses target of a URI (file or DB column) into a DOM format.
175 -- PARAMS:
176 -- ctx - Parser's context. Resulting DOM tree is opaque within ctx.
177 -- uri - URI of target. Can point to a file or be an Xpath to say,
178 -- a CLOB col. holding a stylesheet. The latter might look
179 -- like:
180 -- '/oradb/SCOTT/XSLTABLE/ROW[XSLTAG=''my_stylesheet''/xslCLOB/text()'
181 -- Former would be a regular dir. path like:
182 -- '/usr/disk1/scott/my_stylesheet.xsl'
183 -- encoding - Doc's encoding. If left NULL, then if uri starts with
184 -- '/oradb/', then the database charset is used; otherwise,
185 -- 'UTF-8'. Use 'US-ASCII' for better perf. if you can.
186 -- NOTE: If the uri is an intra-DB uri (ie, /oradb) that points to an NCLOB
187 -- column or a CLOB with an encoding different from the database charset,
188 -- you must explicitly specify the encoding.
189
190 PROCEDURE xmlParse (ctx IN xmlCtx,
191 uri IN VARCHAR2,
192 encoding IN VARCHAR2 DEFAULT NULL
193 );
194
195 -- XMLPARSE: Parses the CLOB source doc into a DOM format.
196 -- PARAMS:
197 -- ctx - Parser's context. Resulting DOM tree is opaque within ctx.
198 -- srcDoc - XML document to parse.
199 -- NOTE: The document's char set encoding is implicit within the lob's locator.
200
201 PROCEDURE xmlParse (ctx IN xmlCtx,
202 srcDoc IN CLOB
203 );
204
205 -- XSLTRANSFORM: Transforms srcdoc into resdoc using the XSL stylesheet
206 -- associated with xslCtx.
207 -- PARAMS:
208 -- srcDoc - The source XML document as a CLOB
209 -- xslCtx - The XSL stylesheet document parser's context
210 -- resDoc - The transformed output.
211
212 -- NOTE: There are several transformation variants accepting / returning either
213 -- a CLOB or a parser context. These are useful when chaining together
214 -- multiple transforms to avoid the cost of converting to/from
215 -- a CLOB on the intermediate steps.
216
217 PROCEDURE xslTransform (srcDoc IN CLOB,
218 xslCtx IN xmlCtx,
219 resDoc IN OUT NOCOPY CLOB
220 );
221
222 -- This one takes a CLOB and returns the xmlCtx of the result... to be used as
223 -- the first stage of chained transforms. It must have a different name because
224 -- its signature differs from the previous only in return type.
225 -- NOTE: It is the responsibility of the caller to clean up the returned parser.
226
227 FUNCTION xslTransformCtoX (srcDoc IN CLOB,
228 xslCtx IN xmlCtx
229 ) RETURN xmlCtx;
230
231 -- Perform a transformation on a pre-parsed xmlCtx returning another xmlCtx
232 -- Used as the middle stage for 3 or more chained transforms.
233 -- NOTE: It is the responsibility of the caller to clean up the returned parser.
234
235 FUNCTION xslTransformXtoX(srcCtx IN xmlCtx,
236 xslCtx IN xmlCtx
237 ) RETURN xmlCtx;
238
239 -- Perform an XSL transformation on a pre-parsed xmlctx returning a CLOB. To be
240 -- used as the final stage in chained transforms or where the caller wants to
241 -- parse source documents separately.
242
243 PROCEDURE xslTransformXtoC (srcCtx IN xmlctx,
244 xslCtx IN xmlCtx,
245 resDoc IN OUT NOCOPY CLOB
246 );
247
248 -- XSLSETPARAM: set a parameter value for a stylesheet.
249 -- PARAMS:
250 -- xslCtx - Parser context for the XSL stylesheet (already parsed)
251 -- paramName - The parameter whose value we're setting
252 -- paramVal - The parameter's value
253 -- NOTE: These settings are 'sticky' and remain in effect until xslResetParams
254 -- is called.
255
256 PROCEDURE xslSetParam (xslCtx IN xmlCtx,
257 paramName IN VARCHAR2,
258 paramVal IN VARCHAR2
259 );
260
261 -- XSLRESETPARAMS: Resets all parameters to their default values for the given
262 -- XSL parser ctx.
263 -- PARAMS:
264 -- ctx - Parser's context.
265
266 PROCEDURE xslResetParams (xslCtx IN xmlCtx);
267
268 -- XMLCLEAN: Cleans up memory from last doc. assoc. with this parser.
269 -- PARAMS:
270 -- ctx - Parser's context.
271
272 PROCEDURE xmlClean (ctx IN xmlCtx);
273
274 -- isnameomf: Test the file name to see if it is an OMF name.
275 -- PARAMS:
276
277 PROCEDURE isnameomf(fname IN varchar2,
278 isomf OUT binary_integer);
279
280 --
281 -- compare - compare ddl of 2 input objects and return a diff document
282 -- Params:
283 -- ctx xml context
284 -- doc1 sxml doc1
285 -- doc2 sxml doc2
286 -- difDoc resultant diff document
287 -- flags (IN) input flags for XmlDiff (currently not used)
288 -- (OUT) kuxDifOb return flags (e.g., no difference found)
289
290 PROCEDURE compare
291 (
292 ctx IN xmlCtx,
293 doc1 IN CLOB,
294 doc2 IN CLOB,
295 difDoc IN CLOB,
296 flags IN OUT BINARY_INTEGER
297 );
298
299 -- windows32: Determine if running on 32 bit Windows NT system.
300 -- Params:
301 -- flag (OUT) if value 1, then 32 bit Windows NT system
302 -- otherwise 0.
303
304 PROCEDURE windows32(flag OUT binary_integer);
305
306 -- ----------------------------------------------------------------------------
307 -- STYLESHEET CACHE (ssc) INTERFACES
308 -- ----------------------------------------------------------------------------
309 -- SSCSETDEBUG: Set stylesheet cache's debug level to match prvtmeti.sql.
310 PROCEDURE sscSetDebug (value IN BOOLEAN);
311
312
313 -- SSCGETCTX: Get xml context identifier for the specified stylesheet
314 -- PARAMS:
315 -- ss_index - Identifier of stylesheet
316 --
317 FUNCTION sscGetCtx (ss_index IN BINARY_INTEGER
318 ) RETURN xmlctx;
319
320
321 -- SSCFIND: Find stylesheet by index or name or allocate it
322 -- PARAMS:
323 -- ss_index - Identifier of stylesheet
324 -- ss_name - Name of stylesheet
325 --
326 FUNCTION sscFind (ss_index IN BINARY_INTEGER,
327 ss_name IN VARCHAR2
328 ) RETURN BINARY_INTEGER;
329
330
331 -- SSCMINIMIZECACHE: Minimize stylesheet cache LRU size (set to 1).
332 PROCEDURE sscMinimizeCache;
333
334
335 -- SSCPARSE: Sets the top-level style sheet for the upcoming transform
336 -- and also establishes the base URI for any included or imported
337 -- stylesheets. In other words, the href in <xsl:import/include>
338 -- statements may be relative to the path established in this call.
339 -- This routine also parses the top-level stylesheet, so XMLPARSE should
340 -- not be called separately.
341 -- NOTE: *Must* be called prior to any of the transform routines.
342 -- PARAMS:
343 -- ss_index - Stylesheet identifier.
344 -- uri - XPath spec. to the stylesheet. May be a dir. path or
345 -- intra-DB spec; eg, /oradb/SYS/METAXSL$/ROW[...]/STYLESHEET
346 -- encoding - Doc's encoding. If left NULL, then if uri starts with
347 -- '/oradb/', then the database charset is used; otherwise,
348 -- 'UTF-8'. Use 'US-ASCII' for better perf. if you can.
349 -- NOTE: If the uri is an intra-DB uri (ie, /oradb) that points to an NCLOB
350 -- column or a CLOB with an encoding different from the database charset,
351 -- you must explicitly specify the encoding.
352
353 PROCEDURE sscParse (ss_index IN BINARY_INTEGER,
354 uri IN VARCHAR2,
355 encoding IN VARCHAR2 DEFAULT NULL
356 );
357
358
359 -- SSCPURGE: Purge stylesheet cache.
360 PROCEDURE sscPurge;
361
362 -- GETDDLSRCFROMXML: Bypass XSL processing for retrieval of pl/sql source from source$
363 -- Generating DDL for very large pkgs via XSL can be very expensive. This routine
364 -- forms the heart of an alternate fast method of retrieving the source of an
365 -- object via C string manipulations rather than XSL transformations.
366 -- PARAMS:
367 -- src - The CLOB containing the object's XML representation
368 -- dst - The CLOB to receive the DDL src
369 PROCEDURE getDDLSrcFromXML (src IN CLOB,
370 dst IN OUT NOCOPY CLOB
371 );
372 END utl_xml;