DBMS_METADATA , 7 of 11

ADD_TRANSFORM Procedure

ADD_TRANSFORM specifies a transform that FETCH_xxx applies to the XML representation of the retrieved objects. It is possible to add more than one transform.

Syntax

FUNCTION add_transform
 (handle IN NUMBER,
  name IN VARCHAR2,
  encoding IN VARCHAR2 DEFAULT NULL)
  RETURN NUMBER;

Parameters

Table 28-10 ADD_TRANSFORM Parameters

Parameters	Description
handle	The handle returned from `OPEN.`
name	The name of the transform. If the name is `DDL`, creation DDL will be generated using XSL-T stylesheets stored within the Oracle dictionary. If the name contains a period (.), colon (:) or forward slash (/), it is interpreted as the URL of a user-supplied XSL-T stylesheet (see Oracle9i Application Developer's Guide - XML.
encoding	The name of NLS character set (see National Language Support Guide) in which the stylesheet pointed to by name is encoded. This is only valid if name is a URL. If left NULL and the URL is external to the database (e.g, /usr/williams/xsl/mystylesheet.xsl), UTF-8 encoding is assumed. If left NULL and the URL is internal to the database, that is, it begins with /oradb/ (see [XPATH-SUPP]), then the database character set is assumed to be the encoding.

Returns

An opaque handle to the transform. This handle is used as input to SET_TRANSFORM_PARAM. Note that this handle is different from the handle returned by OPEN; it refers to the transform, not the set of objects to be retrieved.

Exceptions

INVALID_ARGVAL. A NULL or invalid value was supplied for an input parameter. The error message text identifies the parameter.
INVALID_OPERATION. ADD_TRANSFORM was called after the first call to FETCH_xxx for the OPEN context. After the first call to FETCH_xxx is made, no further calls to ADD_TRANSFORM for the current OPEN context are permitted.

Usage Notes

With no transforms added, objects are returned by default as XML documents. You call ADD_TRANSFORM to specify an XSL-T stylesheet to transform the returned documents.

You can call ADD_TRANSFORM more than once to apply multiple transforms to the returned XML documents. FETCH_xxx will apply the transforms in the order in which they were specified, the output of the first transform being used as input to the second, and so on.

The encoding parameter must be specified if either of the following is true:

The XSL stylesheet pointed to by an external URL is encoded in a character set that is not a subset of UTF-8
The XSL stylesheet pointed to by a database-internal URL is encoded in a character set that is not a subset of the database character set.

An example of the latter might be if the database-internal URL pointed to an NCLOB or NVARCHAR column. Normally, this need not be specified, although explicitly setting it to US7ASCII (if applicable) results in slightly better XML parsing performance.

Note:

The output of the DDL transform is not an XML document. Therefore, no transform should be added after the DDL transform.