SAP NetWeaver AS ABAP Release 750, ©Copyright 2016 SAP AG. All rights reserved.
ABAP - Keyword Documentation →
ABAP - Reference →
Data Interfaces and Communication Interfaces →
ABAP and XML →
Transformations for XML →
CALL TRANSFORMATION
Quick Reference
Syntax
CALL TRANSFORMATION ID
| trans|(name)
[PARAMETERS {p1 = e1 p2 = e2 ...}|(ptab)]
[transformation_options]
SOURCE {XML src_xml}
| {{bn1 = e1 bn2 = e2 ...}|(stab)}
RESULT {XML rslt_xml}
| { {bn1 = f1 bn2 = f2 ...}|(rtab) }.
Alternatives:
1. ... ID ...
2. ... trans|(name) ...
Additions
1a. ... SOURCE {XML src_xml}|{{bn1 = e1 bn2 = e2 ...}|(stab)}
1b. ... RESULT {XML rslt_xml}|{{bn1 = f1 bn2 = f2 ...}|(rtab)}
2. ... PARAMETERS {{p1 = e1 p2 = e2 ...}|(ptab)}
Effect
This statement calls the specified XSL transformation (XSLT) or a
simple transformation
(ST). The source of the transformation is specified behind SOURCE and the
result is stored behind RESULT. PARAMETERS can
be used to pass parameters to the transformation.
transformation_options can be used to specify transformation options. The possible transformation types are:
-
from XML to XML (for XSLT only)
-
from XML to ABAP (for XSLT and simple transformations only)
-
from ABAP to XML (for XSLT and simple transformations only)
-
from ABAP to ABAP (for XSLT only)
JSON-XML, which maps
JSON data to XML, can be used to execute all categories of transformations for JSON that are also possible for XML. More information is available in
Transformations for JSON.
Notes
-
The characters <, >, &,
", and ', which have a separate meaning
in XML syntax, are handled automatically for XML data. When XML data is written, the required XML notation
<, >, &,
", or ' is created in
values of elements or attributes. When XML data is read, the XML notation is transformed to the appropriate
characters. It is not usually necessary to apply the escape character function
escape or a similar method to character-like XML results of the statement
CALL TRANSFORMATION and would actually produce incorrect results. An exception to this rule is creating HTML data with XSLT in cases where it contains JavaScript parts.
-
When JSON data is written, syntax characters in character-like
values are prefixed automatically with the escape character \. Conversely, the escape character is removed from character-like values when JSON data is read.
-
When a transformation is performed, methods from the class libraries for XML are used internally.
- In the case of XSLT, a DOM is always needed as a source. This DOM is constructed and processed using the
iXML Library. In the case of the
identity transformation ID, the
iXML Library is used only if appropriate objects are specified as source or target.
-
The library used also determines the character set that is supported. The iXML Library supports
UCS-2; the sXML Library supports UTF.
Example
The transaction STDEMO demonstrates various transformations from ABAP data to
XML and JSON.
Alternative 1
... ID ...
Effect
Specifies the identity transformation
ID directly. This transformation exists as an XSL transformation in the repository, but is executed
by the runtime environment in an optimized ID engine, depending on the transformation source or target. For more information, see:
Example
Example of an identity transformation
Alternative 2
... trans|(name) ...
Effect
Specifies any transformation. The transformation addition can be specified either statically or dynamically:
-
If static, the transformation is specified directly as trans.
-
If dynamic, the transformation is specified as the uppercase content of a parenthesized character-like data object name.
The specified transformation must exist as an XSLT program or as a
simple transformation in the
repository. If a dynamically specified transformation is not found, an exception of the class CX_INVALID_TRANSFORMATION is raised.
Example
Example of a simple transformation
Addition 1a
... SOURCE {XML src_xml}|{{bn1 = e1 bn2 = e2 ... }|(stab)}
Effect
Specifying the source.
Transformation of XML data
When XML src_xml is specified, the
XML data in src_xml is transformed. src_xml can exist in the following forms:
-
As a data object with the type string or as a
standard table with a
flat character-like row type, which can contain the following data:
- Character-like XML data in XML 1.0 format.
- Character-like JSON data. When any transformation trans|(name) is used, the JSON data is converted to the associated
JSON XML format and passed to this transformation. The predefined
identity transformation ID handles the JSON data directly.
-
As a data object with the type xstring or as a
standard table with a
flat byte-like row type, which can contain the following data:
- Byte-like representation of the characters in XML data in XML 1.0 format, in accordance with a code page such as UTF-8.
- Byte-like representation of the characters in
JSON data, in accordance with a code page such as UTF-8. When any transformation trans|(name) is used, the JSON data is converted to the associated
JSON XML format and passed to this transformation. The predefined
identity transformation ID handles the JSON data directly.
-
As an interface reference variable for objects in iXML Library (XSLT only):
- Interface reference variable with the type IF_IXML_ISTREAM, pointing to an input stream that reads XML data.
- Interface reference variable with the type IF_IXML_NODE, pointing to a node or a full XML document in DOM representation.
-
As a reference variable with the type IF_SXML_READER or CL_SXML_READER for
XML readers in
sXML Library. The transformation moves the reader by
one node and processes the entire matching subtree. If the transformation is successful, the reader is located at the end of the processed data. Any valid reader can be specified:
- XML readers for XML data in XML 1.0 format.
- XOP readers for XML data in XOP format.
- JSON readers for JSON data. When any transformation trans|(name) is used, the JSON reader returns the JSON data in
JSON-XML format. When a predefined
identity transformation
ID is used, the JSON data are handled directly.
Notes
-
The interface IF_SXML_READER and the class CL_SXML_READER are part of the API of
sXML Library, whose objects can be accessed using CALL TRANSFORMATION.
-
XML data in XOP format can only
be transformed using an XOP reader from sXML Library. All other formats can be also specified in appropriate strings or internal tables.
-
The interfaces IF_IXML_ISTREAM and IF_IXML_NODE are part of the API of the
iXML Library, whose objects can be accessed using CALL TRANSFORMATION.
-
For compatibility reasons, src_xml can also be a class reference variable of the type CL_FX_READER. However, the class CL_FX_READER is triggered by CL_SXML_READER.
-
When specifying XML data in strings or internal tables, it is best to use byte strings or byte-like row types and a representation in the UTF-8 code page.
-
The methods CONVERT_FROM and CONVERT_TO from the class CL_ABAP_CODEPAGE
can be used to transform character-like XML data or JSON data to a byte-like representation in accordance with a code page (and back).
Transformation of ABAP data
bn1 = e1 ... or (stab) is used to specify the ABAP data e1 e2 ... that is to be transformed.
-
When the identity transformation ID is called, the ABAP data are either serialized in the
canonical XML format
asXML or in the
canonical JSON format asJSON, depending on the target.
-
When an XSLT program is called, the ABAP data is serialized to the
canonical XML representation, which is then used
as the source of the XSL transformation. Use bn1 bn2 ... to specify the names of the XML elements that are to represent the ABAP data objects in the canonical XML representation.
-
When a simple transformation is called, the transformation has read-only access to the ABAP data using the names bn1 bn2 ....
Instead of using a static parameter list, the data objects can be passed dynamically as value pairs in the columns of an internal table stab that has the type ABAP_TRANS_SRCBIND_TAB from the
type group ABAP.
Serializations convert the elementary components of the ABAP data objects to
asXML or
asJSON, in accordance with the
mappings for predefined ABAP types or for
further XML schema data types. This can raise the exceptions described there, some of which can be bypassed by using
transformation options.
The case of the names in the XML or JSON data depends on how they are specified in the ABAP runtime environment. If specified statically
(b1, b2, ...), uppercase is used; if specified dynamically in stab, the case used there is used.
Note
When a simple transformation is called, the serialization always creates an internal
XML writer object, which can be addressed using the interface IF_SXML_WRITER from
sXML Library. The object is accessed using attributes
of the ST statement tt:call-method.
Example
For an overview of all possible XML sources, see XML Sources of Transformations.
Example
For a deserialization of ABAP data from an XML reader from sXML Library, see sXML Library, Transformation from XML Reader.
Addition 1b
... RESULT {XML rslt_xml}|{{bn1 = f1 bn2 = f2 ...}|(rtab)}
Effect
Specifying the target.
Transformation to XML data
When XML rslt_xml is specified, a transformation to
XML data takes place and this data is passed to rslt_xml. rslt_xml can exist in the following forms:
-
As a variable with the type string or as a standard table with a flat character-like
row type. The XML data returned by the transformation is stored in XML 1.0 format as a character string in the string or in the table. Here, a byte order mark (BOM) is used as a prefix.
-
As a variable with the type xstring or as a standard table with a flat byte-like
row type. The XML data returned by the transformation is saved in XML 1.0 format and as a byte string
in the string or table. The byte string represents the characters of the XML data in accordance with the code page UTF-8. A byte order mark (BOM) is not used as a prefix.
-
As an inline declaration DATA(var), where a variable with the type xstring is created.
-
As an interface reference variable for objects in iXML Library (XSLT only):
- Interface reference variable with the type IF_IXML_OSTREAM, pointing to an output stream that writes XML data.
- Interface reference variable with the type IF_IXML_DOCUMENT that points to an
XML document in DOM representation.
-
As a reference variable with the type IF_SXML_WRITER or CL_SXML_WRITER for
XML writers in
sXML Library. The result of the transformation is added to the current element of the writer as a subtree. Any valid writer can be specified:
- XML writers for XML data in XML 1.0 format.
- XOP writers for XML data in XOP format.
Notes
-
The interface IF_SXML_WRITER and the class CL_SXML_WRITER are part of the API of
sXML Library, whose objects can be accessed using CALL TRANSFORMATION.
-
Transformations to formats other than XML 1.0 are only possible with the appropriate writers in sXML Library.
-
The interfaces IF_IXML_OSTREAM and IF_IXML_DOCUMENT are part of the API of the
iXML Library, whose objects can be accessed using CALL TRANSFORMATION.
-
For compatibility reasons, rslt_xml can also be a class reference variable of the type CL_FX_WRITER. However, the class CL_FX_WRITER is replaced by CL_SXML_WRITER.
-
When XML data is saved in strings or internal tables, it is best to use byte strings or byte-like row types and the UTF-8 code page for the representation.
-
XML data that is written to Unicode
systems as character-like data cannot be processed as character-like data in a non-Unicode system, due to the byte order mark (BOM) that is predefined by the XML standard.
-
The methods CONVERT_FROM and CONVERT_TO from the class CL_ABAP_CODEPAGE
can be used to transform character-like XML data or JSON data to a byte-like representation in accordance with a code page (and back).
Security Note
If the output method "html" of an XSL transformation is used to create
HTML data that contains JavaScript parts, the syntax characters <,
>, &, ", and ' in the JavaScript parts are not transformed to their
XML notation. To prevent cross site scripting (XSS) in
HTML data that contains dynamic JavaScript parts, appropriate measures must be taken. These measures are best applied in the XSL transformation that creates the data.
Transformation to ABAP data
Use bn1 = f1 ... or (rtab) to specify the ABAP target fields f1 f2 ... into which the XML data is to be transformed.
-
When the identity transformation ID is called, the source must either be a
canonical XML display format or a
canonical JSON display format for ABAP data. The canonical
display format is deserialized in the ABAP data objects. Use bn1 bn2 ...
to specify the names of the XML elements that represent the ABAP data objects in the canonical XML representation,
and use f1 f2 ... to specify ABAP data objects (appropriate to the data type) into which they are to be deserialized.
-
When an XSLT program is called, the result must represent the XSL transformation into a
canonical XML display format, which is deserialized into the ABAP data objects (like with the identity transformation).
-
When a simple transformation is called, the transformation performs writes on the ABAP data using the names bn1 bn2 ....
Instead of using a static parameter list, the data objects can be passed dynamically as value pairs to the columns of the internal table rtab that has the type ABAP_TRANS_RESBIND_TAB from the
type group ABAP.
Deserialization converts the elementary XML or JSON values to elementary ABAP data types in accordance with the
mappings for predefined ABAP types or for
further XML schema data types. This can raise the exceptions described there, some of which can be bypassed by using
transformation options.
The case used in the XML or JSON data must match exactly the case specified in the ABAP runtime environment. If specified statically
(b1, b2, ...), uppercase is used; if specified dynamically in rtab, the case used there is used.
When deserializing from a canonical display format, if no corresponding asXML element or asJON object
component exists for an ABAP object, the data object retains its previous value. If an empty XML element
or an empty JSON array is assigned to an elementary or tabular ABAP data object, the ABAP data object
is set to its type-friendly initial value. If an empty XML element or empty JSON object is assigned
to a structure, this has the same effect as non-existent elements on the structure components. The structure
components retain their previous values. The transformation option
clear with the value "all" can be used to initialize all data objects that have nonexistent or empty elements assigned to them.
In the case of the deserialization of internal tables with non-unique table keys, the order of the duplicate rows in relation to these keys is not retained.
Note
When a simple transformation is called, the deserialization always creates an internal
XML reader object, which can be addressed using the interface IF_SXML_READER from
sXML Library. The object is accessed using attributes
of the ST statement tt:call-method.
Example
For an overview of all possible XML targets, see XML Targets of Transformations.
Example
More information about the transformation of XML data to DOM representation in iXML Library is available in iXML Library, DOM Representation.
Example
For a transformation of ABAP data to an XML writer from sXML Library, see sXML Library, Transformation to XML Writer.
Example
More information about how to deserialize missing or empty asXML elements or asJSON object components is available in:
Example
For information about transforming syntax characters in XML targets is available in Transformation of Syntax Characters.
Addition 2
... PARAMETERS {{p1 = e1 p2 = e2 ...}|(ptab)}
Effect
This addition can be used to bind ABAP data objects e1 e2 ... to the parameters p1 p2 ... of an
XSL transformation or a
simple transformation. All elementary data objects and object references are permitted.
Instead of using a static parameter list, the parameters can be specified dynamically as value pairs in the columns of the internal table ptab that has one of the following types from the
type group ABAP:
-
ABAP_TRANS_PARMBIND_TAB for specifying strings,
-
ABAP_TRANS_OBJBIND_TAB for specifying object references (for XSLT only),
-
ABAP_TRANS_PARM_OBJ_BIND_TAB for specifying data references (for XSLT only).
Passing Parameters to XSL Transformations
The specified parameters must be defined in an XSL transformation as input parameters, as follows:
<xsl:param name="..." sap:type="..." />
Specify the parameter name for the attribute name in uppercase letters. Before
a binding can take place, the case used in the XML document must match exactly the case specified in the ABAP runtime environment. If specified statically
(b1, b2, ...), uppercase is used; if specified dynamically in rtab, the case used there is used.
For the optional attribute type, one of the type names string,
number, boolean, nodeset,
xstring, or object(...) can be defined, with a
global ABAP class specified in parentheses behind object. The namespace before
type must be defined as xmlns:sap="http://www.sap.com/sapxsl", with the prefix sap proposed as a convention.
If no type is specified in the transformation, the data types of elementary parameters are mapped to XSL types in accordance with the following table.
ABAP Data Type |
XSL Parameter Type |
c, d, n, string |
string |
i (b, s), f, p |
number |
x, xstring |
string, where the content is represented in Base 64. |
If the XSL types shown in the table above are specified explicitly in the XSL transformation, appropriate elementary ABAP parameters must be specified that can be converted to the XSL type:
-
The XSL type boolean expects ABAP parameters of the type c with the length one. A blank is interpreted as "false" and any other character as "true".
-
The XSL type xstring expects ABAP parameters of the type x or xstring and the content is represented as hexadecimal.
-
The XSL types nodeset and object expect an object
reference variable that points to an instance of a class. The type nodeset expects appropriate object properties.
If a parameter does not match the XSL type, a non-handleable exception is raised. If a parameter defined
in the XSL transformation is not passed, it is set to a default value in the transformation. A specified parameter that is not defined in the XSL transformation is ignored.
Notes
-
The XSL types string, number, boolean,
and nodeset are standard XSL types. xstring and
object represent special SAP enhancements. The type xstring
enables byte strings to be represented in hexadecimal instead of base 64. The type object enables ABAP methods to be called from the XSLT program.
-
The special addition OBJECTS
can be used to pass object references, but this addition is replaced by PARAMETERS.
Passing Parameters to ST Programs
In an ST program, the parameters must be defined as follows as parameters of the main template outside a template:
<tt:parameter name="..." [kind="..."]
[[s-val="..."][d-val="..."]]|[val="..."] />
When an ST program is called, output parameters and input/output parameters are supported as well as
input parameters. The type of the parameter is defined using kind in the
ST program, where "in", "out", and "inout"
can be specified. "inout" is the default. The val attributes can be used to define replacement values.
Exceptions
Handleable Exceptions
CX_TRANSFORMATION_ERROR
-
Cause: Common superclass of all exception classes for CALL
TRANSFORMATION. The direct subclasses are CX_ST_ERROR for simple
transformations and CX_XSLT_EXCEPTION for XSL transformations. When the
statement CALL TRANSFORMATION is executed, only exceptions of the class CX_TRANSFORMATION_ERROR
and almost all of its subclasses, plus exceptions of the class CX_SY_NO_HANDLER can be handled. When a transformation is executed, further exceptions can be raised, such as exceptions that occur when
mapping ABAP data types to asXML. These exceptions
cannot be handled directly, but they are also caught when the exception CX_TRANSFORMATION_ERROR (or
its subclasses) are handled. The attribute PREVIOUS of the corresponding exception object then contains a reference to the original exception.
Subclasses of CX_ST_ERROR
CX_ST_CALL_ERROR
-
Cause: Error when calling the transformation
CX_ST_CALL_METHOD_ERROR
-
Cause: Exception in an ABAP method called from the transformation
CX_ST_CONDITION
-
Cause: Error in a transformation condition
CX_ST_CONSTRAINT_ERROR
-
Cause: Data object to be serialized or deserialized is too long.
CX_ST_DESERIALIZATION_ERROR
-
Cause: Error in the deserialization
CX_ST_FORMAT_ERROR
-
Cause: Format error in a node
CX_ST_INVALID_XML
-
Cause: A serialization would produce invalid XML.
CX_ST_MATCH
-
Cause: Deserialization match failed
CX_ST_REF_ACCESS
-
Cause: Error in data node access
CX_ST_RUNTIME_ERROR
-
Cause: Error in execution of the transformation
CX_ST_SERIALIZATION_ERROR
-
Cause: Error in the serialization
CX_ST_VALIDATION_ERROR
-
Cause: Failed validation with the attribute xsd-type
for the ST statements tt:value,
tt:write,
or tt:read. This exception cannot be caught directly.
Subclasses of CX_XSLT_EXCEPTION
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 in the deserialization
Runtime Error: XML_NOT_SUPPORTED
CX_XSLT_FORMAT_ERROR
-
Cause: Document is not in asXML format
Runtime error: XML_FORMAT_ERROR
CX_XSLT_RUNTIME_ERROR
-
Cause: Error in the XSLT processor
Runtime Error: UNCAUGHT_EXCEPTION
CX_XSLT_SERIALIZATION_ERROR
-
Cause: Error in the serialization
Runtime Error: XML_NOT_SUPPORTED
Continue
CALL TRANSFORMATION - transformation_options
CALL TRANSFORMATION - Examples