EML

All examples in these docs work without EML. But on a recent ABAP release, you can also use this feature in abap2UI5 apps.

EML

The Entity Manipulation Language simplifies work with RAP business objects by giving a consistent way to read, create, update, and delete entities.

Read

Use READ ENTITIES to fetch sales orders and show them in a UI5 table:

CLASS zcl_sample_eml_read DEFINITION PUBLIC.

  PUBLIC SECTION.
    INTERFACES z2ui5_if_app.
    DATA mt_salesorder TYPE TABLE FOR READ RESULT i_salesordertp\salesorder.

  PROTECTED SECTION.
  PRIVATE SECTION.
ENDCLASS.

CLASS zcl_sample_eml_read IMPLEMENTATION.
  METHOD z2ui5_if_app~main.

    IF client->check_on_navigated( ).

      READ ENTITIES OF I_SalesOrderTP
        ENTITY SalesOrder
        ALL FIELDS WITH
        VALUE #( ( SalesOrder = `0000000001` ) )
        RESULT mt_salesorder.

      DATA(view) = z2ui5_cl_ui5_view_builder=>factory(
          )->ele( n = `View` ns = `mvc`
              )->a( n = `xmlns`     v = `sap.m`
              )->a( n = `xmlns:mvc` v = `sap.ui.core.mvc`

              )->ele( `Page`
                  )->ele( `Table`
                      )->a( n = `items` v = client->_bind( mt_salesorder )

                      )->ele( `columns`
                          )->ele( `Column`
                              )->tag( `Text`
                                  )->a( n = `text` v = `SalesOrder`
                          )->end(
                          )->ele( `Column`
                              )->tag( `Text`
                                  )->a( n = `text` v = `SalesOrderType`
                          )->end(
                          )->ele( `Column`
                              )->tag( `Text`
                                  )->a( n = `text` v = `SalesOrganization`
                          )->end(

                      )->end(

                      )->ele( `items`
                          )->ele( `ColumnListItem`
                              )->ele( `cells`
                                  )->tag( `Text`
                                      )->a( n = `text` v = `{SALESORDER}`
                                  )->tag( `Text`
                                      )->a( n = `text` v = `{SALESORDERTYPE}`
                                  )->tag( `Text`
                                      )->a( n = `text` v = `{SALESORGANIZATION}` ).

      client->view_display( view->stringify( ) ).

    ENDIF.

  ENDMETHOD.
ENDCLASS.

Modify

The example below creates a sales order with MODIFY inside an abap2UI5 app:

  METHOD z2ui5_if_app~main.

    MODIFY ENTITIES OF i_salesordertp
           ENTITY salesorder
           CREATE
           FIELDS ( salesordertype
                    salesorganization
                    distributionchannel
                    organizationdivision
                    soldtoparty )
           WITH VALUE #( ( %cid  = `0001`
                           %data = VALUE #(
                SalesOrderType       = `TA`
                SalesOrganization    = `1010`
                DistributionChannel  = `10`
                OrganizationDivision = `00`
                SoldToParty          = `0033500056` ) ) )
           MAPPED   DATA(ls_mapped)
           FAILED   DATA(ls_failed)
           REPORTED DATA(ls_reported_modify).

    COMMIT ENTITIES BEGIN
           RESPONSE OF i_salesordertp
           FAILED   DATA(ls_save_failed)
           REPORTED DATA(ls_save_reported).
    COMMIT ENTITIES END.

ENDMETHOD.

Key Points:

• EML calls in abap2UI5 apps run outside the RAP framework, so explicit transaction commits (COMMIT ENTITIES) are needed.
• Restrictions inside the RAP framework, like disallowing direct calls to posting function modules or explicit commits, don't apply to abap2UI5 EML operations. You get more flexibility when handling commits and other actions.

Failure Handling

EML statements (MODIFY ENTITIES, READ ENTITIES, COMMIT ENTITIES) report problems through the FAILED and REPORTED structures rather than by raising exceptions. They can also raise classic ABAP exceptions for infrastructure-level failures.

What to handle:

• Business / validation failures — inspect FAILED (which entities failed) and REPORTED (the messages explaining why) after each EML call. These are not exceptions; an unchecked FAILED will look like success in your code while the data was never written.
• Transactional behavior — EML modifications stay in the transactional buffer until COMMIT ENTITIES. If you skip the commit, nothing is persisted. If COMMIT ENTITIES itself reports failures, you must decide whether to retry, roll back, or surface the error to the user.
• Infrastructure exceptions — wrap EML calls in TRY … CATCH for the cases that do raise:
  • cx_root / cx_dynamic_check — catch-all safety net.
  • cx_abap_invalid_value, cx_sy_conversion_no_number — data conversion problems before the EML statement runs.
  • cx_abap_behv and its subclasses — RAP behavior framework errors (e.g. unknown action, locking issues).
  • cx_abap_lock_failure — when COMMIT ENTITIES cannot acquire locks.

A typical defensive pattern — the REPORTED structure goes to the user as it is, and the commit is skipped when anything failed:

TRY.
    MODIFY ENTITIES OF z_i_invoice
      ENTITY invoice
      UPDATE FIELDS ( amount ) WITH VALUE #( ( %tky = ls_key amount = lv_amount ) )
      FAILED   DATA(failed)
      REPORTED DATA(reported).

    IF failed IS NOT INITIAL.
      " the messages explaining why, shown as one box typed by the most severe
      client->message_box_display( reported ).
      ROLLBACK ENTITIES.
      RETURN.
    ENDIF.

    COMMIT ENTITIES RESPONSE OF z_i_invoice
      FAILED   DATA(commit_failed)
      REPORTED DATA(commit_reported).

    IF commit_failed IS NOT INITIAL.
      client->message_box_display( commit_reported ).
      RETURN.
    ENDIF.

  CATCH cx_root INTO DATA(lx).
    client->message_box_display( lx ).
ENDTRY.

message_box_display( ) takes the RAP response structure as it is: it recognizes the %msg references in every entity's REPORTED table, reads their texts and shows one box typed by the most severe message, error before warning. A REPORTED without a single message shows nothing, so check FAILED rather than REPORTED to decide. An exception object works the same way — the box reads the text out of it. For what happens to an exception you do not catch, see Exception.

Working Samples

Complete apps from the sample catalog that use what this page describes. Each is a single class in abap2UI5/samples unless its row names another of the three sample repositories — pull that repository with abapGit and start the class with ?app_start=<class>.

Sample	Class
Read a Travel — reads one instance by its key - a missing key comes back in FAILED, not as an exception	Z2UI5_CL_SMPS_APP_001 · samples-stack, branch 03-rap
Create a Travel — MODIFY ... CREATE, key from MAPPED	Z2UI5_CL_SMPS_APP_002 · samples-stack, branch 03-rap
Update a Travel — changes single fields of one instance - UPDATE FIELDS names what may be touched	Z2UI5_CL_SMPS_APP_003 · samples-stack, branch 03-rap
Delete a Travel — deletes one instance - MODIFY ... DELETE FROM	Z2UI5_CL_SMPS_APP_004 · samples-stack, branch 03-rap
Manage Travels, the Complete App — 01-04 plus EXECUTE and COMMIT ENTITIES RESPONSE OF	Z2UI5_CL_SMPS_APP_005 · samples-stack, branch 03-rap