What does it do? The addition OPTIONS enables predefined transformation options to be specified, to which specific values can be assigned to control transformations. The values must be specified in 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, a catchable exception of class CX_SY_TRANS_OPTION_ERROR is raised.
Latest notes: The transformations apply to XML and to JSON, if applicable. NON_V5_HINTS ABAP_HINT_END
ABAP Addition
What does it do? The transformation option clear controls how the ABAP target fields are initialized when deserializing from XML or JSON to ABAP. Possible ValuesMeaning allAll target fields specified after RESULT are initialized before calling the transformation. This is the recommended setting. suppliedIn ST, the target fields which have a root node assigned to them in the ST program are initialized before calling the transformation. In XSLT, target fields for which a root node exists in the XML data are initialized before importing the nodes. Other target fields keep their value. noneDefault, the target fields specified after RESULT are not initialized, except for internal tables
Latest notes: Using the default setting (none) can become critical when nonexistent or empty elements are deserialized to data objects. In the case of nonexistent elements, all data objects keep their original values. In the case of empty elements, structures keep their values. In cases like this, it is advisable to use clear with the value all. NON_V5_HINTS ABAP_HINT_END
ABAP Addition
What does it do? The transformation option data_refs specifies the output of data references if the transformation is from ABAP to XML or JSON. Possible ValuesMeaning noDefault in ST; no data references are produced. heapDefault in XSLT and only possible there; data referenced using heap references is output as subelements of the asXML elements asx:heap or the asJSON object %heap. Data objects referenced using stack references are not serialized. heap-or-errorOnly possible in XSLT. Like heap, but the exception CX_REFERENCE_NOT_SERIALIZABLE is raised if the data to be serialized contains stack references . heap-or-createOnly possible in XSLT. Like heap, but data objects referenced using stack references are handled like data objects referenced using heap references. embeddedOnly possible in XSLT. Referenced data objects are output 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.
Latest notes: The exception CX_REFERENCE_NOT_SERIALIZABLE cannot be caught by specifying it directly. It can only be caught by specifying CX_XSLT_SERIALIZATION_ERROR. NON_V5_HINTS ABAP_HINT_END
ABAP_EXAMPLE_ABEXA For information about the differences between serializing to heap and embedded elements, see Serializations to Heap or Embedded. ABAP_EXAMPLE_END
ABAP Addition
What does it do? The transformation option initial_components controls the output of initial structure components when transforming from ABAP to XML or JSON. Possible ValuesMeaning includeInitial components of structures are output. suppress_boxedDefault; does not output initial boxed components of structures; initial components of all other structures are output. suppressInitial components of structures are not output.
Latest notes:
The suppression of initial components in serializations reduces the data volume. However, this option should be used with caution and only if 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 keep 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 created as output if it has the value abap_false. This can also cause unwanted results. NON_V5_HINTS ABAP_HINT_END
ABAP Addition
What does it do? The transformation option technical_types controls 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 properties 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 ValuesMeaning error Default in XSLT and only possible there. The serialization of a data reference variable with a dynamic type without a name raises the exception CX_REFERENCE_NOT_SERIALIZABLE. ignoreOnly possible in XSLT. A data reference variable with a dynamic type without a name is ignored in serializations.
Latest notes:
The exception CX_REFERENCE_NOT_SERIALIZABLE cannot be caught by specifying it directly. It can only be caught by specifying CX_XSLT_SERIALIZATION_ERROR.
Data types without names are bound data types or data types constructed using RTTS. NON_V5_HINTS ABAP_HINT_END
ABAP Addition
What does it do? The transformation option value_handling controls the tolerance of conversions when mapping elementary ABAP types. Possible ValuesMeaning defaultDefault setting; in serializations, an invalid value in a field of type n raises the exception CX_SY_CONVERSION_NO_NUMBER. When deserializing, the exception CX_SY_CONVERSION_DATA_LOSS is 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. moveOnly possible in serializations. Invalid values in a field of type n are copied to XML or JSON without being changed. accept_data_lossOnly possible in deserializations. If target fields of types c, n, or x are too short, surplus data for c and x is cut off on the right and surplus data for n is cut off on the left. accept_decimals_lossOnly 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_charactersOnly possible in deserializations. If a value to be deserialized contains characters that do not match the encoding of the XML data or JSON data, nor the current code page of AS ABAP, an exception of the type CX_SY_CONVERSION_CODEPAGE is raised. BEGIN_SECTION VERSION 5 OUT 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. END_SECTION VERSION 5 OUT
Latest notes:
The exceptions mentioned cannot be caught by specifying them directly by CALL TRANSFORMATION but are packed into CX_TRANSFORMATION_ERROR or its subclasses.
If a value is specified that is not supported in the specified direction however, the directly catchable exception CX_SY_TRANS_OPTION_ERROR is raised. NON_V5_HINTS ABAP_HINT_END
ABAP_EXAMPLE_VX5 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. ABAP_EXAMPLE_END
ABAP Addition
What does it do? The transformation option exceptions controls the behavior of exceptions packed in CX_TRANSFORMATION_ERROR or its subclasses. Possible ValuesMeaning resumableOnly in deserializations with ST. Exceptions of the class CX_ST_DESERIALIZATION_ERROR are raised as resumable exceptions of the class. If they are handled using CATCH BEFORE UNWIND, the target field for which the exception was raised is given its type-dependent initial value and the attribute RESULT_REF_FOR_RESUME of the exception object contains a data reference to this target field. The terminated 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.
Latest 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 sufficient to resume at the position where the exception was raised. To do this, the exception must be declared using RAISING RESUMABLE and raised using RAISE RESUMABLE EXCEPTION . NON_V5_HINTS ABAP_HINT_END BEGIN_SECTION SAP_INTERNAL_HINT As a downward compatible bugfix, using OPTIONS exceptions makes also some runtime errors CONVT_NO_NUMBER and CONVT_OVERFLOW catchable, that in some rare cases have not been wrapped in CX_ST_DESERIALIZATION_ERROR. END_SECTION SAP_INTERNAL_HINT
ABAP_EXAMPLE_VX5 Resumable raising of an exception in the deserialization of a character that does not represent a number to a numeric target field. The attribute RESULT_REF_FOR_RESUME points to the target field field1, to which a negative value is assigned 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. ABEXA 00085 ABAP_EXAMPLE_END
ABAP Addition
What does it do? The transformation option xml_header controls 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 ValuesMeaning noNo XML header is output. without_encodingAn XML header is output without specifying the encoding. fullDefault; an XML header is output and encoding is specified.
