ABAP Keyword Documentation → ABAP - Reference → Data Interfaces and Communication Interfaces → ABAP and XML

CALL TRANSFORMATION

Other versions: 7.31 | 7.40 | 7.54

Syntax


CALL TRANSFORMATION {trans|(name)} 
   
                [PARAMETERS {p1 = e1 p2 = e2 ...}|(ptab)] 

              
     [transformation_options] 

                    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)}

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. 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)

The name of the transformation can be specified either directly as trans or dynamically as the content of a parenthesized character-like data object name. When specified dynamically, the name must be in uppercase letters. The specified transformation must exist as an XSLT program or as a Simple Transformation in the Repository. You can use transformation_options to specify transformation options.

Addition 1a

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

Effect

Specifying the source

Transformation of an XML document

When XML sxml is specified, the XML document in sxml is transformed. sxml can exist in the following forms:

as a data object with the type string and xstring or as a standard table with a flat or character-like or byte-like row type,
as an interface reference variable with the type IF_IXML_ISTREAM that points to an iXML input stream (for XSLT only),
as an interface reference variable with the type IF_IXML_NODE that points to an iXML node set (for XSLT only),
as a reference variable of the type IF_SXML_READER or CL_SXML_READER that points to an XML reader(instance of CL_SXML_READER).

Notes

The interfaces IF_IXML_ISTREAM and IF_IXML_NODE are components of the packages "Stream" and "DOM" in the iXML Library delivered by SAP.
For compatibility reasons, sxml 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.

Transformation of ABAP data

Use bn1 = e1 ... or (stab) to specify the ABAP data e1 e2 ... that you want to transform.

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 you want 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, you can pass the data objects 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 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 avoided by using transformation options.

The case of the names in the XML document depend 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 generates an internal writer object, which can be addressed using the interface IF_SXML_WRITER. The object is accessed using attributes of the ST statement tt:call-method.

Addition 1b

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

Effect

Specifying the target

Transformation to an XML document

When XML rxml is specified, a transformation to an XML document takes place and this document is passed to rxml. rxml can exist in the following forms:

as a data object with the type string and xstring or as a standard table with a flat character-like or byte-like row type,
as an interface reference variable with the type IF_IXML_OSTREAM that points to an iXML output stream (for XSLT only),
as an interface reference variable with the type IF_IXML_DOCUMENT that points to an iXML document (for XSLT only),
as a reference variable with the type IF_SXML_WRITER or CL_SXML_WRITER that points to an XML writer (istance of CL_SXML_WRITER).

Notes

The interfaces IF_IXML_ISTREAM and IF_IXML_NODE are components of the packages "Stream" and "DOM" in the iXML Library delivered by SAP.
If the data type xstring is used for rxml, the result is saved in the character representation UTF-8. This is of benefit if you want to save the resulting XML document to a file.
For compatibility reasons, rxml 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.

Transformation to ABAP data

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

An XSLT program deserializes the result of the XSL transformation into ABAP data objects, if the result represents 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, and use f1 f2 ... to specify ABAP data objects (appropriate to the data type) into which you want them to be deserialized.
When a Simple Transformation is called, the transformation has write access to the ABAP data using the names bn1 bn2 ....

Instead of using a static parameter list, you can pass the data objects 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.

Deserializations convert the elementary XML 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 avoided by using transformation options.

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.

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 generates an internal reader object, which can be addressed using the interface IF_SXML_READER. The object is accessed using attributes of the ST statement tt:call-method.

Addition 2

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

Effect

You can use this addition 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, you can specify the parameters 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

You must define the specified parameters 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, you must specify appropriate elementary ABAP parameters 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 you to represent byte strings 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. You can use the val attributes to define replacement values.

Examples

Exceptions

Catchable 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