ABAP: Executing the Transformation

Use

During this step, your program performs a loop over all source data, calls the Service Mapping Tool (SMT) for one source line, receives a target line as a result, and adds this target line to the target container.

Prerequisites

The SMT has completed the Prefetch mode (either by calling the method PREFETCH_END or by creating an SMT object without Prefetch).

Procedure

Your program performs a loop over all source data, and calls the method EXECUTE of the SMT object.

TRY.
      LOOP AT lt_source INTO l_source.
       CLEAR l_target.
        l_engine->execute( EXPORTING i_source = l_source
            i_overwrite_check = abap_true
          CHANGING  ch_target = l_target ).
        APPEND l_target to lt_target.
      ENDLOOP.
    CATCH cx_smt_customizing_error cx_smt_transformation_error INTO l_error.
      " ...
  ENDTRY.

Table 1: Parameters for Method EXECUTE
Parameter	Meaning
I_SOURCE	Source data line
I_PREDECESSOR1-4	Optional source data lines, which are hierarchical predecessors of the source data line. If, for example, the source is a document item, the first predecessor is the document header.
I_ADD1-20	Optional import parameters for additional data lines, that are not part of the source data hierarchy. You can use them, for example, to transfer customizing data.
I_DO_NOT_SET_CHANGE_FIELD	Indicator: If you set the value abap_true, no fields of the change structure are set.
I_OVERWRITE_CHECK	Indicator: If you set the value abap_true, the SMT announces a runtime error when a transformation overwrites an already filled target field.
I_NO_DATA_LOSS_CHECK	Indicator: If you set the value abap_true, the SMT does not check whether a loss of data will occur during an assignment.
I_LOCATION_TEXT	Optional text displayed when an error occurs. You can use this text to locate the source of the error.
CH_CHANGE	Optional change parameter for the change structure. Its structure must consist of fields that have the same description as the target data structure. The structure must have the type Character length 1. The SMT assigns the value abap_true to all fields in this structure, in which data transfers to target fields took place. The SMT fills only the key fields of the change structure with the same values as the target.
CH_TARGET	Change parameter that transfers the target data line to the SMT. Is filled by the SMT.

If a customizing error occurs, this method triggers the exception CX_SMT_CUSTOMIZING_ERROR. This happens, for example, if your program transfers data of a different type than specified in Customizing. The system issues type CX_SMT_TRANSFORMATION_ERROR exceptions for transformation errors.

Transformation Calls and Extended XML Handling

Without extended XML handling, the system calls all transformations and conditions specified in Customizing for this mapping and this mapping step. This is not the case, if the extended XML handling is activated. Suppose that the SMT is used for implementing changed inbound services. In this case, an XML document that is sent to the system contains only sections for changed data.

The service infrastructure converts this XML document into a highly complex structure, that contains all fields of the business object. Unsent data indicates initial values in the corresponding structure fields. For this reason, transformation calls for these fields would trigger errors. In addition, the program must prevent that X values are set in the change structure for unsent data.

For this reason, the logic of the call for transformation and condition methods is designed as follows, if extended XML handling is active:

If no obligatory import parameters of the method were sent, the system does not call a condition or transformation method.
If no import parameters (obligatory or optional) of the method were sent, the system does not call a condition or transformation method.
If some, but not all, obligatory import parameters were sent, the system displays an error.
If a method contains optional import parameters only, the system calls it up, if at least one of these parameters was sent.
If a method is not called, the system does not fill any fields of the change structure.

Note

Note that optional parameters have no influence on whether or not the system calls a method. Methods that contain optional parameters only are an exception to this. Whether you declare the parameters of a transformation or condition method as optional or obligatory, has a decisive influence on mapping behavior. Suppose that you create a transformation method with two import parameters. If you declare both as obligatory, only XML documents that contain no or both import parameters do not trigger mapping errors. If you ignore the cardinality of these XML fields, the mapping may trigger errors for correct XML documents.

Transformations of currency amounts are a good example for the importance of this declaration. If you declare the parameter of the currency amount as optional, and if the currency code – but no amount – is sent, the system calls the transformation method. As a consequence, the amount field of the business object is initialized, if the change function of the business object is called.

In this case, an exception should be displayed, as currency conversions always require an amount and a currency code. For this reason, both import parameters must be obligatory, and all XML documents, that contain one of the parameters only, must lead to a mapping.

The behavior of simple field mappings is less complicated: In extended XML handling, no mapping field is executed, if the field was not sent. As a consequence, no change indicator is set. Condition methods for field mappings are treated as described above.

Field checks ignore extended XML handling. For this reason, you should specify field checks for non-initial values or checks via check methods only for fields that are always sent.

Note

Method with m > 0 obligatory and n optional parameters:

0 obligatory parameters sent and any number of optional parameters => Method is not called
1 < Obligatory parameters sent < m and any number of optional parameters => Error is triggered
All m obligatory parameters sent and any number of optional parameters => Method is called

Method with n only > 0 assigned optional parameters:

0 optional parameters were sent => Method is not called
1< Sent optional parameters => Method is called
None of the optional parameters is assigned, or all specified optional parameters are assigned to fixed values => Method is always called (as nothing is sent from external).

Method has no inbound parameters: It is always called.

Note

If a condition method is not called due to extended XML handling, the associated transformation is also not called.