EML consists of statements that you can use to manipulate the data of a business object. You use the READ ENTITIES statement to read data; for all other operations, you use the MODIFY ENTITIES statement with the corresponding addition UPDATE, CREATE, or DELETE.
You can only use the CREATE, UPDATE, and DELETE operations if the behavior definition of the business object contains the corresponding use create, use update, or use delete directive. Trying to use a prohibited operation causes a syntax error.
To read data from a business object, you use the READ ENTITIES statement. The statement has two important parameters: one internal table containing the keys of the data that you want to read and another containing the results of the query.
These internal tables have special data types called derived behavior definition types. The system creates them automatically when a developer creates a behavior definition and they contain some or all of the fields of the business object along with further fields that control how the system processes a particular request. You declare the internal tables using the new addition TYPE TABLE FOR <operation> in the DATA statement.
The type TABLE FOR READ IMPORT contains the key field or fields of the business object. The %control structure is a generated structure that indicates which fields of the business object are actually used in the current operation. In our example, the system fills the structure automatically and you do not have to worry about it.
The type TABLE FOR READ RESULT contains all of the fields of the business object. This table contains the result set after the read statement has been executed.
The read import table contains a column for each key field of the business object, in this case, agencyID. To read a particular agency, you add a row to the internal table containing its key. As well as the key field or fields, the table contains the columns %is_draft and %control. With %is_draft you can specify whether you want to read draft data or active data. The %control structure is used to specify which fields are to be read.
In our example, we only read active data and the %control structure is filled by the framework, based on the field list after addition FIELDS.
When you process a business object, using the READ ENTITIES OF or MODIFY ENTITIES OF statement, you must first specify the name of the behavior definition. This is followed by keyword ENTITY and the name of the entity with which you want to work. If the entity has a alias name, you should use it, here.
You cannot use the alias name after addition OF. This is because the technically speaking, you specify the name of the behavior definition at this point, not the name of the entity.
The READ ENTITIES statement reads business object data according to the keys that you pass in the WITH addition. It returns the result in the internal table in the RESULT addition. In the statement, you can also specify which fields of the business object you need. In this example, we have used the ALL FIELDS addition to return all of the fields. However, if you only require a subset of the fields, you can use the variant FIELDS ( field1 field2 … ) to restrict the amount of data that is read. Note that, unlike in a SELECT statement, the field list is not comma-separated.
The result table contains all of the fields of the business object, along with the control field %is_draft. If your READ ENTITIES statement contains the FIELDS ( f1 … fn ) variant, only the fields that you requested will be filled. If you use the ALL FIELDS variant, the system provides the values of all of the fields.
If you want to update data, you declare an internal table with TYPE TABLE FOR UPDATE. This contains all of the fields of the business object and also the %control structure. In our variant of the MODIFY ENTITIES statement, the system fills the %control structure automatically.
The MODIFY ENTITIES statement updates data in the RAP transactional buffer. In the UPDATE FIELDS addition, you specify which fields should be changed. In the WITH addition, you pass the internal table containing the data that you want to update.
When you use EML outside the business object, you must use the COMMIT ENTITIES statement to trigger the RAP save sequence and persist the data in the database.
Later in this course we will use EML inside the behavior implementation. Inside the behavior implementation it is neither necessary nor allowed to trigger the commit with COMMIT ENTITIES.