Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Data Interfaces and Communication Interfaces →  ABAP and XML →  Transformations for XML →  CALL TRANSFORMATION 

CALL TRANSFORMATION - OPTIONS

Quick Reference

Other versions: 7.31 | 7.40 | 7.54

Syntax


... OPTIONS [clear              = val] 

            [data_refs          = val] 

            [initial_components = val] 

            [technical_types    = val] 

            [value_handling     = val] 

            [exceptions         = val] 

            [xml_header         = val] ...

Extras

1. ... clear
2. ... data_refs

3. ... initial_components

4. ... technical_types

5. ... value_handling

6. ... exceptions
7. ... xml_header

Effect

The addition OPTIONS enables predefined transformation options to be specified, to which specific values can be assigned to control transformations. The values must be defined as data objects val of type c or string. Each transformation option may only be specified once. Multiple values separated by blanks can be specified for a transformation option in val. If an invalid value is specified for a transformation option, an exception of class CX_SY_TRANS_OPTION_ERROR is raised. This exception can be handled.


Note

The transformations apply to XML and also to JSON (where applicable).

Addition 1

...clear

Effect

The transformation option clear specifies how the ABAP target fields are initialized when deserializing XML or JSON to ABAP.

Possible Values Meaning
all All target fields specified after RESULT are initialized before calling the transformation. This is the recommended setting.
supplied In ST, the target fields which have a root node assigned to them in the ST program are initializedbefore calling the transformation. In XSLT, target fields for which there is a root node in the XML data are initialized before importing the nodes. Other target fields keep their value.
none Default, the target fields specified after RESULT are not initialized, except for internal tables


Note

Using the default setting (none) can become a critical issue when nonexistent or empty elements are deserialized in data objects. In the case of nonexistent elements, all data objects preserve their original values. In the case of empty elements, structures preserve their values. In cases like this, it is advisable to use clear with the value "all".

Addition 2

... data_refs

Effect

The transformation option data_refs specifies the output of data references if the transformation is from ABAP to XML or JSON.

Possible Values Meaning
no Default in ST, no data references are produced.
heap Default in XSLT and only allowed there, data referenced usingheap references is produced as subelements of theasXML elements <asx:heap> or the asJSON object %heap. Data objects referenced usingstack references are not serialized.
heap-or-error Only possible in XSLT. Like heap, but the exception CX_REFERENCE_NOT_SERIALIZABLE is raised if the data to be serialized containsstack references.
heap-or-create Only possible in XSLT. Like heap, but data objects referenced usingstack references are handled like data objects referenced usingheap references.
embedded Only possible in XSLT. Referenced data objects are produced together with the reference. It is not possible to deserialize XML data created in this way, since the identity of the objects is lost when serialized.


Note

The exception CX_REFERENCE_NOT_SERIALIZABLE cannot be caught directly. It can only be caught using CX_XSLT_SERIALIZATION_ERROR.

Executable Example

For information about the differences between serializing to heap and embedded elements, see Serializations to Heap or Embedded.

Addition 3

... initial_components

Effect

The transformation option initial_components specifies the output of initial structure components when transforming from ABAP to XML or JSON.

Possible Values Meaning
include Initial components of structures are output.
suppress_boxed Default, does not produce initial boxed components of structures; produces initial components of all other structures.
suppress Initial components of structures are not output.


Notes

  • The suppression of initial components in serializations reduces the data volume. However, this option should be used with caution and only there is complete control over deserializations. If the option clear is not used with the value "all" in serializations, any suppressed components in ABAP data objects are ignored and the target fields preserve their values. Deserialization in external systems can cause problems if a suppressed component is expected.
  • The suppression of initial components also affects structure components that are typed with the domains for XML schema data types. For example, a component typed with the domain XSDBOOLEAN is not displayed if it has the value abap_false. This can also cause unwanted results.

Addition 4

... technical_types

Effect

The transformation option technical_types specifies the behavior if no type description can be serialized when serializing data references to asXML or asJSON. This is the case when the technical type attributes of the dynamic type of the data reference variable are known, but the type does not have a name (or it only has a technical name).

Possible Values Meaning
error Default in XSLT and only allowed there. The serialization of a data reference variable with a dynamic type without a name raises the exception CX_REFERENCE_NOT_SERIALIZABLE.
ignore Only possible in XSLT. A data reference variable with a dynamic type without a name is ignored in serializations.


Notes

  • Exception CX_REFERENCE_NOT_SERIALIZABLE cannot be caught directly. It can only be caught using CX_XSLT_SERIALIZATION_ERROR.
  • Data types without names are bound data types or data types constructed using RTTS.

Addition 5

... value_handling

Effect

The transformation option value_handling specifies the tolerance of conversions when mapping elementary ABAP types.

Possible Values Meaning
default Default, in serializations, if there is an invalid value in a field of type n,the exception CX_SY_CONVERSION_NO_NUMBER is raised. When deserializing, the exception CX_SY_CONVERSION_DATA_LOSSis raised if target fields of the types c, n,or x are too short or the exception CX_SY_CONVERSION_LOST_DECIMALS is raised if target fields of the type p have too few decimal places.
move Only possible in serializations. Invalid values in a field of type n are copied to XML or JSON without being changed.
accept_data_loss Only possible in deserializations. If target fields of types c, n, or x are too short, surplus data for cand x is cut off on the right and surplus data for n is cut off on the left.
accept_decimals_loss Only possible in deserializations. If target fields of the type p have too few decimal places, they are rounded up to the available decimal places.
reject_illegal_characters Only possible in deserializations. If a value to be deserialized contains characters that are notvalid for the encoding of the XML data or JSON data or for the current code page of AS ABAP, an exceptionof the type CX_SY_CONVERSION_CODEPAGE is raised. If the XML or JSON data is passed as an iXML input stream, the setting of the iXML parser overrides the encoding of the XML or JSON data.


Notes

  • The exceptions mentioned cannot be handled directly by CALL TRANSFORMATION and are packed into CX_TRANSFORMATION_ERROR or its subclasses.
  • If a value is specified that is not supported in the specified direction however, the exception CX_SY_TRANS_OPTION_ERROR is raised (can be handled directly).


Example

If value_handling = 'reject_illegal_characters' is specified, for example, an exception is raised if, in the XML header of XML data in the Latin-1 character set, encoding="utf-8" is specified and the XML data contains characters other than those of the 7-bit ASCII character set.

Addition 6

... exceptions

Effect

The transformation option exceptions specifies the behavior of exceptions packed in CX_TRANSFORMATION_ERROR or its subclasses.

Possible Values Meaning
resumable Only in deserializations with ST. Exceptions of the class CX_ST_DESERIALIZATION_ERROR are raised asresumable exceptionsof the class. If they are handled using CATCHBEFORE UNWIND, the target field where the exception was raised is given its type-dependentinitial value and the attribute RESULT_REF_FOR_RESUME of the exception object contains a data referenceto this target field. The canceled transformation can be resumed using RESUME.

If the transformation option exceptions = 'resumable' is specified, an exception of the class CX_ST_DESERIALIZATION_ERROR, that wraps an original exception behaves as if it were raised as a resumable exception.


Notes

  • When the resumable exception is handled, the target field can also be given a different value using the attribute RESULT_REF_FOR_RESUME before processing is resumed using RESUME.
  • If an exception of the class CX_ST_DESERIALIZATION_ERROR is raised by an exception that is itself raised in an ABAP method called during the transformation, the transformation option exceptions = 'resumable' alone is not enough to resume at the place where the exception was raised. For this to happen, the exception must be declared using RAISING RESUMABLE and raised using RAISE RESUMABLE EXCEPTION.


Example

Raises an exception (resumable) in the deserialization of a character to a numeric target field and the character does not represent a number. The attribute RESULT_REF_FOR_RESUME points to the target field field1, itself assigned a negative value to demonstrate that the deserialization did not work. The deserialization is then resumed using RESUME and field2 is given the value 2 from the XML file.

CALL TRANSFORMATION demo_two_values 
  SOURCE field1 = 'x' 
         field2 = '2' 
  RESULT XML DATA(xml). 

cl_demo_output=>write_xml( xml ). 

DATA: field1 TYPE i, 
      field2 TYPE i. 
TRY. 
    CALL TRANSFORMATION demo_two_values 
      SOURCE XML xml 
      RESULT field1 = field1 
             field2 = field2 
      OPTIONS exceptions = 'resumable'. 
  CATCH BEFORE UNWIND cx_st_deserialization_error INTO DATA(exc). 
    ASSIGN exc->result_ref_for_resume->* TO FIELD-SYMBOL(<fs>). 
    <fs>  = -1. 
    RESUME. 
ENDTRY. 

cl_demo_output=>write( |{ field1 }, { field2 }| ). 

cl_demo_output=>display( ).

Addition 7

... xml_header

Effect

The transformation option xml_header specifies the output of the XML header when transforming to XML and writing to a data object of type c, string, or to an internal table.

Possible Values Meaning
no No XML header is produced.
without_encoding An XML header is produced without encoding specified.
full Default, an XML header is produced and encoding is specified.

Exceptions

Handleable Exceptions

CX_SY_TRANS_OPTION_ERROR

  • Cause: Invalid transformation option or invalid value.