CALL TRANSFORMATION

Syntax

CALL TRANSFORMATION {trans|(name)}
                    [PARAMETERS {p1 = e1 p2 = e2 ...}|(ptab)]
                    [OBJECTS    {o1 = e1 o2 = e2 ...}|(otab)]
                    [OPTIONS    a1 = e1 a2 = e2 ...]
                    SOURCE {XML sxml}
                         | {{bn1 = e1 bn2 = e2 ...}|(stab)}
                    RESULT {XML rxml}
                         | {{bn1 = f1 bn2 = f2 ...}|(rtab)}.

Extras:

1a. ... SOURCE {XML sxml}|{{bn1 = e1 bn2 = e2 ...}|(stab)}

1b. ... RESULT {XML rxml}|{{bn1 = f1 bn2 = f2 ...}|(rtab)}

2a. ... PARAMETERS {{p1 = e1 p2 = e2 ...}|(ptab)}

2b. ... OBJECTS {{o1 = e1 o2 = e2 ...}|(otab)}

3. ... OPTIONS a1 = e1 a2 = e2 ...

Effect

This statement calls the specified XSL transformation (XSLT) or a simple transformation (ST, as of release 6.40). The source of the transformation is specified after SOURCE and the result is stored as specified after RESULT. Use PARAMETERS and OBJECTS to pass parameters to the transformation. Possible transformation types are:

from XML to XML (only for XSLT),
from XML to ABAP (for XSLT and simple transformations),
from ABAP to XML (for XSLT and simple transformations),
from ABAP to ABAP (only for XSLT),

where the last two types are available only as of release 6.20.

The name of the transformation can be specified either directly as trans or as content of a character-type data object name in braces. The specified transformation must exist as a XSLT program or as a simple transformation in the Repository.

Addition 1a

... SOURCE {XML sxml}|{{bn1 = e1 bn2 = e2 ...}|(stab)}

Effect

Source Specification

Transformation of an XML Document

When you specify XML sxml, the XML document contained in xsml is transformed, where sxml can have one of the following forms:

Data object of type string and xstring or as a standard table with flat character-type row type,
Interface reference variable of type IF_IXML_ISTREAM, which points to an iXML input stream (only for XSLT),
Interface reference variable of type IF_IXML_NODE, which points to an iXML nodeset (only for XSLT),
Class reference variable of type CL_FX_READER, which points to an XML reader (only for ST).

Note

The interfaces IF_IXML_ISTREAM and IF_IXML_NODE are components of the "Stream" and "DOM" packages of the iXML Library delivered by SAP.

Transformation of ABAP Data

Use bn1 = e1 ... or (stab) to specify the ABAP data e1 e2 ... to be transformed.

When calling an XSLT program, the ABAP data are serialized into the canonical XML representation, which is then used as source of the XSL transformation. Use bn1 bn2 ... to specify the names of the XML elements meant to represent the ABAP data objects in the canonical XML presentation.
When calling a simple transformation, in the transformation the names bn1 bn2 ... are used to read the ABAP data.

Instead of using a static parameter list, you can also pass the data objects dynamically as value pairs in the columns of an internal table stab, which has the type ABAP_TRANS_SRCBIND_TAB from the ABAP type group.

The following data objects cannot be serialized and trigger a treatable exception:

Data objects of type n, whose current content does not exclusively consist of numbers.
Data objects of type p, whose current content does not represent a valid packed number.
Data objects of type d and t, whose current content contains leading or trailing blanks and, at the same time, uses the separators ("-" or ":") according to ISO-8601 for the presentation.
Data reference variables pointing to data objects, whose data type has only a technical name.

Data reference variables pointing to data objects that were not created with CREATE DATA are treated as initial reference variables during the serialization.

Addition 1b

... RESULT {XML rxml}|{{bn1 = f1 bn2 = f2 ...}|(rtab)}

Effect

Target Specification

Transformation into an XML Document

When you specify XML rxml, transformation into an

XML is executed; the document is then placed into rxml, where rxml can be one of the following:

a data object of type string and xstring or a standard table with a flat, character-type rpw type.
an interface reference variable of type IF_IXML_OSTREAM, which points to an iXML output stream (only for XSLT).
an interface reference variable of type IF_IXML_DOCUMENT, which points to an iXML document (only for XSLT),
a class reference variable of type CL_FX_WRITER, which points to an XML writer (only for ST).

Notes

The interfaces IF_IXML_OSTREAM and IF_IXML_DOCUMENT are components of the "Stream" and "DOM" packages of the iXML Library delivered by SAP.

If you use the data type xstring for rxml, then the result is stored in the UTF-8 character representation. This is helpful, if the resulting XML-document is to be stored in a file.

Transformation into ABAP Data

Use bn1 = f1 ... or (rtab) to specify the ABAP target fields f1 f2 ... , into which you want the XML data to be transformed.

When calling an XSLT program, the result of the XSL transformation into ABAP data objects is deserialized, if it is a canonical XML representation. Use bn1 bn2 ... to specify the names of the XML elements that represent the ABAP data objects in the canonical XML representation, while you use f1 f2 ... to specify the ABAP data objects of the appropriate data type, into which you want to deserialize them.
When calling a simple transformation, in the transformation, the names bn1 bn2 ... are used for write access to the ABAP data.

Instead of using a static parameter list, the data objects can also be passed dynamically as value pairs in the columns of the internal table rtab, which has the type ABAP_TRANS_RESBIND_TAB of the ABAP type group.

An XML element must be convertable into the respective ABAP data objects, where instead of the usual conversion rules the following restrictions apply:

Deserialization into too short data objects of data types c or n must never lead to loss of data, except when for data type c only leading and trailing blanks are concerned and for data type n only leading blanks.
Data must never be lost due to the deserialization into a data object of data type p with too few decimal places.
Data must never be lost due to the deserialization into a too short data object of data type c.
Structures cannot be converted into elementary data objects.

If an XML element cannot be converted into the ABAP data object, a treatable exception is triggered.

When deserializing into a reference variable, this must be the same as or more general than the dynamic type of the object stored in the XML document. The allocated ABAP objects or instances of a class are created during the deserialization.

Addition 2a

... PARAMETERS {{p1 = e1 p2 = e2 ...}|(ptab)}

Effect

Use this addition to attach ABAP data objects e1 e2 ... to the parameters p1 p2 ... of an XSL transformation or a simple transformation In Release 6.10, the data objects e1 e2 ... must be character-type, as of release 6.20 all elementary data objects and object references are allowed.

Instead of using a static parameter list, you can also specify the parameters dynamically as value pairs in the columns of the internal

table ptab, which has one of the following types from the ABAP type group: ,,ABAP_TRANS_PARMBIND_TAB for specifying strings ,,ABAP_TRANS_OBJBIND_TAB for specifying object references (only for SXLT), ,,ABAP_TRANS_PARM_OBJ_BIND_TAB for specifying data references (only for SXLT).

Passing Parameters to XSL Transformations

The specified parameters must be defined in the XSL transformation as input parameters:

<xsl:param name="..." type="..." />

For the attribute name, enter the parameter name in uppercase. For the optional attribute type, specify one of the type indicators string, number, boolean, nodeset, xstring or object(...), where you must enter the name of a global ABAP class in the brackets after object.

If no type is specified in the XSL transformation, the data types of elementary parameters are mapped to XSL types according to the table below:

ABAP Data Type/>	XSL Parameter Type
c, d, n, string	string
i, s, b, f, p	number
x, xstring	string, where the content is presented to the base of 64.

If in the XSL transformation the XSL types of the above table are specified explicitly, you must enter the matching elementary ABAP parameters, which can be converted into the XSL type:

The XSLtype boolean expects ABAP parameters of the type c with the length 1. A space is interpreted as "false" and a different character is interpreted as "true".
The XSLtype xstring expects ABAP parameters of the type x or xstring and the display of the content is hexadecimal.
The XSL types nodeset and object expect an object reference variable pointing to a class instance. The type nodeset expects appropriate object properties.

If a parameter does not match the XSL type, an untreatable exception is triggered. If a parameter defined in the XSL transformation is not passed, it is set to the default value in the transformation. A specified parameter that is not defined in the XSL transformation is ignored.

Note

The XSL types string, number, boolean, and nodeset are XSL standard types, whereas xstring and object are special SAP extensions. The type xstring allows a hexadecimal display of byte chains instead of the presentation to the base of 64. The type object enables you to call ABAP methods from the XSLT program.

Passing Parameters to ST Programs

In an ST program, the parameters must be defined outside of a template as parameters of the main template as follows:

<tt:parameter name="..." [kind="..."]
[[s-val="..."][d-val="..."]]|[val="..."] />

When calling an ST program, apart from input parameters, also output parameters and input/output parameters are supported. The kind of the parameter is defined with kind in the ST program, where you can specify "in", "out" and "inout", which is the default. With the val attributes, replacement values can be defined.

Addition 2b

... OBJECTS {{o1 = e1 o2 = e2 ... }|(otab)}

Effect

You can use this addition to pass object references e1 e2 ... as external objects o1 o2 ... to an XSL transformation where you can call their methods.

Instead of using a static parameter list, you can also pass the objects dynamically as value pairs in the columns of the internal table otab which has the type ABAP_TRANS_OBJMBIND_TAB from the type group.

Note

As of release 6.20, the addition OBJECTS is obsolete and external objects are treated as parameters. Therefore, object references should be passed with the addition PARAMETERS.

Addition 3

... OPTIONS a1 = e1 a2 = e2 ...

Effect

You can use this addition to specify the values e1, e2 ... for addtional control options a1, a2 ... of the transformation. The values e1, e2 ... must be of the type c or string.

For a1, a2 ..., you can specify the following values:

XML_HEADER to control the output of the XML headers in case of a transformation to XML and the storage in a data object of the type c, string or in an internal table.

Possible values	Meaning
no	No output of an XML header
without_encoding	Output of an XML header without specification of encodings
full	Default setting, output of an XML header with specification of encodings

DATA_REFS to control the output of data references in case of a transformation from ABAP to XML.

Possible values	Meaning
no	Default for ST, no output of data references
heap	Default for XSLT and only possible there, output of referenced data as subelements of the asXML elements <asx:heap>.
embedded	Output of referenced data with the reference

INITIAL_COMPONENTS to control the output of initial structure components in case of a transformation from ABAP to XML.

Possible values	Meaning
include	Default setting, output of initial components of structures
suppress	No output of initial components of structures

Example

See Example of an XSL Transformation. and example for a Simple Transformation

Exceptions

Catchable Exceptions

CX_XSLT_ABAP_CALL_ERROR

Cause: Error when calling an ABAP method from XSLT
Runtime error XSLT_METH_ERROR

CX_XSLT_DESERIALIZATION_ERROR

Cause: Error during deserialization
Runtime Error: XML_NOT_SUPPORTED

CX_XSLT_FORMAT_ERROR

Cause: Document is not in asXML format
Runtime error: XML_FORMAT_ERROR

CX_SY_XSLT_RUNTIME_ERROR

Cause: Error in the XSLT processor
Runtime Error: UNCAUGHT_EXCEPTION

CX_XSLT_SERIALIZATION_ERROR

Cause: Error during deserialization
Runtime Error: XML_NOT_SUPPORTED

CX_ST_ERROR and subclasses

Cause:Error during a Simple Transformation

Note

The mutual superclass of all exception classes for CALL TRANSFORMATION is CX_TRANSFORMATION_ERROR.