ABAP RAP

Entity Manipulation Language (EML)

EML

EML (Entity Manipulation Language) is comparable to SQL's DML. The ABAP extension EML is used in RAP objects to implement actions, and it is also used to manipulate RAP objects from external code.

EML works with the transactional buffer of Business Objects (BOs) and provides a compact, declarative way to read and modify instances.

EML statements

Common EML statements you'll encounter:

  • READ
  • MODIFY
  • GET PERMISSIONS
  • SET LOCKS
  • COMMIT ENTITIES
  • ROLLBACK ENTITIES

Data types

RAP BOs generate many data types used by EML. They are built from the fields of CDS views and include generated %-prefixed fields and %-structures (e.g. %KEY, %PID, %TKY).

Return parameters

EML operations use structured return parameters to report results back to the caller:

  • FAILED — keys of instances that could not be processed successfully
  • MAPPED — returned by MODIFY ENTITY to provide key mapping (useful for numbering)
  • REPORTED — messages (errors, warnings, info)

SET LOCKS

Acquire locks for one or more BO instances. If the objects are already locked the details are returned in the FAILED and REPORTED parameters.

Syntax

SET LOCKS ENTITY <BO-Type>
		FROM <KeyTable>
	 [FAILED <Failed-Table>]
	 [REPORTED <Reported-Table>].

COMMIT ENTITIES

This statement is normally invoked implicitly when Behaviors are processed. It is used explicitly only outside that context. COMMIT ENTITIES starts the RAP save sequence.

Syntax

COMMIT ENTITIES [IN SIMULATION MODE].
COMMIT ENTITIES [IN SIMULATION MODE] RESPONSE OF bdef1 response_param
																		[RESPONSE OF bdef2 response_param]
																		[...].

COMMIT ENTITIES — Simulation Mode

Simulation Mode does not write data to the database but it executes the following lifecycle methods:

  • FINALIZE
  • CHECK_BEFORE_SAVE
  • CLEANUP_FINALIZE

Methods that are not executed in simulation mode include:

  • ADJUST_NUMBERS
  • SAVE
  • CLEANUP

Use Simulation Mode when you want to verify whether a save would fail; read the RESPONSE to determine the outcome.

ROLLBACK ENTITIES

Rollback changes from the transactional buffer to the last persisted state.

	* Reset transactional buffer
	ROLLBACK ENTITIES.

READ ENTITY — like SELECT SINGLE in ABAP

You can read instances from the transactional buffer using READ ENTITY.

Example in EML

		READ ENTITY zi_users
			ALL FIELDS
			WITH VALUE #( ( userid = 'JBRANDEIS' ) )
			RESULT DATA(lt_result).

Equivalent in ABAP SQL

		SELECT SINGLE FROM zi_users
			*
		WHERE userid = 'JBRANDEIS'
		INTO TABLE @DATA(lt_result).

Result type

	lt_result TYPE TABLE FOR READ RESULT zi_users.

Key component groups

In generated structures you will frequently see %-prefixed groups:

%KEY

Contains all key elements.

%PKY

  • All elements of %KEY.
  • Optionally includes %PID (Preliminary ID) — present for new instances and when using late numbering.

%TKY

  • All elements of %PKY.
  • Optionally includes %IS_DRAFT when draft mode is used.

Overview

MODIFY ENTITY / MODIFY ENTITIES

Use MODIFY ENTITY to create, update or delete BO instances. You can also trigger actions on BO instances with MODIFY.

All MODIFY calls are bulk operations — you can process many instances in a single call. MODIFY ENTITIES can create instances for multiple different BO entity types at once.

You must supply the list of fields that are affected in each call.

MODIFY ENTITY <BO-Entity>
	CREATE  FIELDS ( ... )

EML Example: create a task

	METHOD if_oo_adt_classrun~main.
		MODIFY ENTITY zi_jb5_tasks
				CREATE  FIELDS ( taskkey assignee author summary description status )
					WITH  VALUE #( ( taskkey = 'DMO-03'
															 %key-taskkey = 'DMO-03'
															 assignee     = sy-uname
															 author       = sy-uname
															 summary      = 'Create a new Task from ABAP'
															 description  = |Create a new Task using the \n MODIFY ENTITY statement. \n test!|
															 status       = 'NEW' ) )
														 REPORTED DATA(create_rep)
														 FAILED DATA(create_fail).
                             
		LOOP AT create_rep-zi_jb5_tasks INTO DATA(ls_create_rep).
			out->write( ls_create_rep-%msg->if_message~get_text( ) ).
		ENDLOOP.

		COMMIT ENTITIES RESPONSE OF zi_jb5_tasks REPORTED DATA(lt_reported)
																						 FAILED   DATA(lt_failed).
                                             
		LOOP AT lt_reported-zi_jb5_tasks INTO DATA(ls_data).
			out->write( ls_data-%msg->if_message~get_text( ) ).
		ENDLOOP.
	ENDMETHOD.