+> If you choose to modify recently read lines in a work area, for example, within a loop (`LOOP AT INTO dobj`), you +might modify the line and then modify the internal table based on this line using a `MODIFY` statement. + +[`MODIFY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_itab.htm) +statements offer multiple options for changing the content of single and multiple table lines by specifying the table key or a table index +without reading lines into a target area first. + +``` abap +"Addition FROM ...; specified key values determine the line to be modified + +"line: existing line including key values + +MODIFY TABLE it FROM line. + +"line constructed inline + +MODIFY TABLE it FROM VALUE #( a = 1 b = 2 ... ). + +"Respecting only specified fields with the addition TRANSPORTING +"In case of sorted/hashed tables, key values cannot be specified. + +MODIFY TABLE it FROM line TRANSPORTING b c. + +"Modification via index +"Note that it is only MODIFY, not MODIFY TABLE. +"Example: It modifies the line with number 1 in the primary table index. + +MODIFY it FROM line INDEX 1. + +"Without the addition TRANSPORTING, the entire line is changed. +"Example: It modifies specific values. + +MODIFY it FROM line INDEX 1 TRANSPORTING b c. + +"USING KEY addition +"If the addition is not specified, the primary table key is used; +"otherwise, it is the explicitly specified table key that is used. +"Example: It is the same as MODIFY it FROM line INDEX 1. + +MODIFY it FROM line USING KEY primary_key INDEX 1. + +"The statement below uses a secondary key and an index specification +"for the secondary table index. Only specific fields are modified. + +MODIFY it FROM line USING KEY sec_key INDEX 1 TRANSPORTING c d. + +"Modifying multiple lines in internal tables +"All lines matching the logical expression in the WHERE clause are modified +"as specified in line. +"The additions TRANSPORTING and WHERE are both mandatory; USING KEY is optional. + +MODIFY it FROM line TRANSPORTING b c WHERE a < 5. +``` +> **💡 Note**
+> The system field `sy-subrc` is set to `0` if at least one line was changed. It is set to `4` if no lines were changed. + + + +### Deleting Internal Table Content + +Using [`DELETE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdelete_itab.htm) statements, you can delete single and multiple lines in internal tables. +``` abap +"Deleting via index +"Example: The first line in the table is deleted. + +DELETE it INDEX 1. + +"If USING KEY is not used, INDEX can only be used with index tables. +"If doing so, it determines the line from the primary table index. +"If a secondary key is specified, the secondary table index is respected +"Example: same as above + +DELETE it INDEX 1 USING KEY primary_key. + +"Deleting an index range; FROM or TO alone can also be specified + +DELETE it FROM 2 TO 5. + +"Deleting via keys +"The line must have a compatible type to the tables line type and +"include key values. The first found line with the corresponding keys +"is deleted. +"If the key is empty, no line is deleted. + +DELETE TABLE it FROM line. + +"Instead of specifying the keys using a data object ("line" above), +"the keys can be specified separately. All key values must be specified. +"Example: Respects keys from primary table index. + +DELETE TABLE it WITH TABLE KEY a = 1. + +"You can also specify secondary keys. +"Example: Same as above + +DELETE TABLE it WITH TABLE KEY primary_key COMPONENTS a = 1. + +DELETE TABLE it_sec WITH TABLE KEY sec_key COMPONENTS ... + +"Deleting multiple lines based on a WHERE condition +"Specifying the additions USING KEY, FROM, TO is also possible. + +DELETE it WHERE a < 6. +``` + +`DELETE ADJACENT DUPLICATES` statements allow you to delete all neighboring lines except for the first line that have the same content +in specific components. Usually, a suitable sorting before carrying out these statements is required. +``` abap +"Implicitly uses the primary table key + +DELETE ADJACENT DUPLICATES FROM it. + +"Deletion respecting the values of the entire line + +DELETE ADJACENT DUPLICATES FROM it COMPARING ALL FIELDS. + +"Only lines are delete with matching content in specific fields + +DELETE ADJACENT DUPLICATES FROM it COMPARING a c. + +"Deletion respecting a specified table key + +"Same as first example above +DELETE ADJACENT DUPLICATES FROM it USING KEY primary_key. + +DELETE ADJACENT DUPLICATES FROM it USING KEY sec_key. +``` + +> **💡 Note**
+> The system field `sy-subrc` is set to `0` if at least one line was deleted. It is set to `4` if no lines were deleted. + +Using +[`CLEAR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclear.htm) +and +[`FREE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapfree_dataobject.htm) +statements, you can delete the complete table content. + +The difference between the two is the handling the initially requested +memory space for the table. When clearing a table using `CLEAR`, +the content is removed but the initially requested memory space remains +allocated. If the table is later filled again, the memory space is still +available, which is beneficial in terms of performance in contrast to +clearing an internal table using `FREE`. Such a statement also +clears the table content but, additionally, it releases the memory +space. + +``` abap +CLEAR it. + +"Additionally, it releases memory space. +FREE it. +``` + + +## More Information +Topic [Internal +Tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenitab.htm) in the ABAP Keyword Documentation. + +## Executable Example +[zcl_demo_abap_internal_tables](./src/zcl_demo_abap_internal_tables.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/02_Structures.md b/02_Structures.md new file mode 100644 index 0000000..70247dc --- /dev/null +++ b/02_Structures.md @@ -0,0 +1,669 @@ + +# Working with Structures + +- [Working with Structures](#working-with-structures) + - [Structures ...](#structures-) + - [Creating Structures and Structured Types](#creating-structures-and-structured-types) + - [Variants of Structures](#variants-of-structures) + - [Working with Structures](#working-with-structures-1) + - [Accessing Components of Structures](#accessing-components-of-structures) + - [Filling Structures](#filling-structures) + - [Clearing Structures](#clearing-structures) + - [Structures in Use in the Context of Tables](#structures-in-use-in-the-context-of-tables) + - [Excursion: Including Structures](#excursion-including-structures) + - [More Information](#more-information) + - [Executable Example](#executable-example) + +## Structures ... + +- (or structured [data + objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_object_glosry.htm "Glossary Entry")) + are ABAP variables typed with [structured + types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstructured_type_glosry.htm "Glossary Entry"). +- are [complex data + types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomplex_data_type_glosry.htm "Glossary Entry"). +- are composed of a sequence of other data objects which are called + [components](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_glosry.htm "Glossary Entry"). +- have components that can be of any type, that is, they can + themselves be, for example, structures or [internal + tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninternal_table_glosry.htm "Glossary Entry"). +- summarize different pieces of information, that is, data objects, + that belong together. A typical example is the following: an address + has several components like name, street, city, and so on. +- mostly serve as line types of internal tables and [database + tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendatabase_table_glosry.htm "Glossary Entry"). +- are often used to process data sequentially, such as the data stored + in the rows and columns of a database table. +- and structured types can typically be found in the [ABAP Dictionary + (DDIC)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_dictionary_glosry.htm "Glossary Entry"), + sometimes in [global + classes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenglobal_class_glosry.htm "Glossary Entry"); + or they can be defined locally in ABAP programs. + - Most of the structures that are worked with in ABAP programs may + be globally defined structures in the DDIC. + - Why? Apart from globally defined structures in the DDIC, each + database table or + [view](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenview_glosry.htm "Glossary Entry") + constitutes a structured type. When a database table etc. is + activated, a globally available structured type of the same name + is created, too. Hence, in an ABAP program, a database table's + name is typically used as type name to declare data objects, for + example, structures or internal tables. +- can be addressed as a whole. You can also address the individual + components of structures. + +## Creating Structures and Structured Types + +> **💡 Note**
+> This cheat sheet focuses on locally defined structures and structured types. + +The typical syntactical elements are [`BEGIN OF ... END OF ...`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptypes_struc.htm). +They are used in combination with +[`TYPES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptypes.htm) +to create a structured type and +[`DATA`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata.htm) +to create a structure. + +**Creating structured types** + +The structures' components are listed between `... BEGIN OF ...` and `... END OF ...`. +``` abap +TYPES: BEGIN OF struc_type, + comp1 TYPE ..., + comp2 TYPE ..., + comp3 TYPE ..., + ..., + END OF struc_type. +``` +Alternatively, you could go with the following syntax, however, a chained statement with the colon `:` above is preferable due to +better readability. +``` abap +TYPES BEGIN OF struc_type. + TYPES comp1 TYPE ... . + TYPES comp2 TYPE ... . + TYPES comp3 TYPE ... . +... . +TYPES END OF struc_type. +``` +As mentioned above, the components of structures can be of any type. +They can be +[elementary](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenelementary_data_type_glosry.htm "Glossary Entry") +and also complex, that is, a structure component can be a structure or +internal table. Besides this, the components can be [reference +variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_variable_glosry.htm "Glossary Entry"), +too. + +For the components, the additions +[`TYPE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata_simple.htm) +and +[`LIKE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata_referring.htm) +are possible. +> **💡 Note**
+> Setting default values with +[`VALUE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata_options.htm) +is - in contrast to the creation of structures using a `DATA` +statement as shown further down - not possible in this case. + +``` abap +TYPES: BEGIN OF struc_type, + comp1 TYPE i, "elementary type + comp2 TYPE c LENGTH 5, "elementary type + comp3 TYPE local_structured_type, "local structured type + + comp4 TYPE itab_type, "internal table type + + comp5 TYPE ddic_type, "DDIC type + comp6 TYPE REF TO i, "reference + comp7 LIKE data_object, "deriving type from a data object + ..., + END OF struc_type. +``` + +**Creating structures** + +There are multiple ways to create structures in a program using a `DATA` statement: + +- Creating a structure either based on a local type or a globally available type from the DDIC: + + ``` abap + DATA ls_from_local TYPE struc_type, + ls_from_global TYPE ddic_type. + ``` + +- Creating a structure by directly specifying the components using `... BEGIN OF ... END OF ...`. The syntax is similar to the `TYPES` statement. Here, default values can be set with +`VALUE`. + + ``` abap + DATA: BEGIN OF struc, + comp1 TYPE ..., + comp2 TYPE ... VALUE ..., + comp3 TYPE i VALUE 99, + comp4 TYPE i VALUE IS INITIAL, + comp5 TYPE local_structured_type, + ..., + END OF struc. + ``` + + Alternatively and similar to the `TYPES` statement, you + could use the following syntax, however, a chained statement with the colon `:` as above is preferable due to better + readability. + + ``` abap + DATA BEGIN OF struc. + DATA comp1 TYPE ... . + DATA comp2 TYPE ... VALUE ... . + ... . + DATA END OF struc. + ``` +- Creating a structure by referring to a local structured data object using `LIKE` or to an internal table using `LIKE LINE OF`. + ``` abap + DATA struc1 LIKE other_struc. + + DATA struc2 LIKE LINE OF itab. + ``` +- Creating a structure by inline declaration, e. g. using `DATA( ... )`. + ``` abap + "Type is derived from the right-hand structure; + "the content of struc is assigned, too. + + DATA(struc1) = struc. + + "Using the VALUE operator; structured type is specified before the + "first parenthesis; component values can be assigned, too + + DATA(struc2) = VALUE struc_type( comp1 = ... ). + + "It is particularly handy for declaring the structure where you actually need it + "without prior extra declaration of the structure in various contexts; + "e. g. SELECT or LOOP AT statements; structured types are automatically + "derived from the context + + SELECT SINGLE * + FROM zdemo_abap_fli + WHERE carrid = 'LH' + INTO @DATA(struc3). + + LOOP AT itab INTO DATA(wa). + ... + ENDLOOP. + ``` + +## Variants of Structures + +Depending on the component type, the structure can be a [flat +structure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenflat_structure_glosry.htm "Glossary Entry"), +a [nested +structure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abennested_structure_glosry.htm "Glossary Entry"), +or a [deep +structure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendeep_structure_glosry.htm "Glossary Entry"). + +**Flat structure** + +Flat structures contain only elementary types that have a fixed length, that is, there are no internal tables, reference types or strings as components: +``` abap +DATA: BEGIN OF structure, + comp1 TYPE i, + comp2 TYPE c LENGTH 15, + comp3 TYPE p LENGTH 8 DECIMALS 2, + ..., + END OF structure. +``` +> **💡 Note**
+> Nesting does not play a role in this context. Even a nested structure is flat unless a substructure contains a deep component. + +**Nested structure** + +At least one component of a structure is a +[substructure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstructure_glosry.htm "Glossary Entry"), +that is, it refers to another structure. The following example has +multiple substructures. +``` abap +DATA: BEGIN OF address_n, + BEGIN OF name, + title TYPE string VALUE `Mr.`, + prename TYPE string VALUE `Duncan`, + surname TYPE string VALUE `Pea`, + END OF name, + BEGIN OF street, + name TYPE string VALUE `Vegetable Lane`, + number TYPE string VALUE `11`, + END OF street, + BEGIN OF city, + zipcode TYPE string VALUE `349875`, + name TYPE string VALUE `Botanica`, + END OF city, + END OF address_n. +``` + +**Deep structure** + +A deep structure contains at least one internal table, reference type, or string as a component. +``` abap +DATA: BEGIN OF address_d, + name TYPE string VALUE `Mr. Duncan Pea`, + street TYPE string VALUE `Vegetable Lane 11`, + city TYPE string VALUE `349875 Botanica`, + details TYPE TABLE OF some_table WITH EMPTY KEY, + END OF address_d. +``` +Despite the fact that the following structure looks fairly simple, it is not to be considered a flat structure but a deep structure since it contains strings. +``` abap +DATA: BEGIN OF address, + name TYPE string VALUE `Mr. Duncan Pea`, + street TYPE string VALUE `Vegetable Lane 11`, + city TYPE string VALUE `349875 Botanica`, + END OF address. +``` + +## Working with Structures + +### Accessing Components of Structures + +The structure as a whole and also the individual components can be +addressed. To address the components, you use the [structure component +selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstructure_component_sel_glosry.htm "Glossary Entry") +`-`: +``` abap +structure-comp1 ... + +address-name ... +``` + +Nested components can be addressed via chaining: +``` +structure-substructure-comp1 ... + +address_n-name-title ... +``` + +> **✔️ Hints**
+>- You can refer to structure components when creating new data types and data objects: +> ``` abap +> TYPES: lty_1 TYPE structured_type-comp1, +> lty_2 LIKE structure-comp1. +> +> DATA: lv_1 TYPE structured_type-comp1, +> lv_2 LIKE structure-comp1. +> ``` +>- ADT and the ABAP Editor provide code completion for structure components after the component selector. +>- When declaring a variable with reference to a structured data object, the object component selector `->` can be used: + `...dref->comp ...` (apart from the needlessly longer syntax `... dref->*-comp ...`). + +### Filling Structures + +Filling structure components using the component selector. +``` abap +address-name = `Mr. Duncan Pea`. + +address-street = `Vegetable Lane 11`. + +address-city = `349875 Botanica`. +``` +Filling structure components using the +[`VALUE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_value.htm) +operator. Value assignments by addressing the structure +components individually can be very bulky. Hence, the use of the +`VALUE` operator is very handy for the value assignment, +especially for filling structure components at [operand position](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoperand_position_glosry.htm "Glossary Entry"). +In the example below, the `#` sign is used before the +parentheses which means that the type of the operand can be implicitly +derived. This is not the case for the example further down in which a +new structure is [declared inline](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_inline.htm). +Hence, the type must be explicitly specified before the parentheses. +Note that components that are not specified and assigned a value remain +initial. +``` abap +address = VALUE #( name = `Mr. Duncan Pea` + street = `Vegetable Lane 11`. + city = `349875 Botanica` ). +``` +Using the `VALUE` operator and inline declarations, structures can be created and filled in one go. +``` abap +TYPES address_type LIKE address. + +DATA(add2) = VALUE address_type( name = `Mrs. Jane Pea` + street = `Vegetable Lane 11`. + city = `349875 Botanica` ). +``` +Copying the content of a structure to another one that has the same type. For value assignments, generally +bear in mind that there are special [conversion](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_struc.htm) +and [comparison rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_rules_operands_struc.htm) +that apply to assignments involving structures.. +``` abap +address = add2. + +"When creating a new structure by inline declaration, the type of +"the right-hand structure is derived and the content is assigned. + +DATA(add3) = add2. +``` +Copying content of a structure to another one that has a different type. You can use statements with +[`MOVE-CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove-corresponding.htm) +and the +[`CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expr_corresponding.htm) +operator. Both are used to assign identically named components of +structures to each other. This syntax also works for structures that +have the same type. + +Note the rules mentioned above and consider the result of the value +assignment when using either of the two options with +`MOVE-CORRESPONDING` and the `CORRESPONDING` operator. +See more information and syntax variants in the ABAP Keyword +Documentation: +[`MOVE-CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencorresponding_constr_arg_type.htm) +and +[`CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencorresponding_constr_arg_type.htm). +In the examples below, the focus is only on flat structures. +``` abap +"Moves identically named components; content in other components +"of the targets structure are kept. + +MOVE-CORRESPONDING struc TO diff_struc. + +"Initializes target structure; moves identically named components + +diff_struc = CORRESPONDING #( struc ). + +"Same effect as the first MOVE-CORRESPONDING statement; +"addition BASE keeps existing content + +diff_struc = CORRESPONDING #( BASE ( diff_struc ) struc ). + +"MAPPING addition: Specifying components of a source structure that are +"assigned to the components of a target structure in mapping +"relationships. + +diff_struc = CORRESPONDING #( BASE ( diff_struc ) + struc MAPPING comp1 = compa ). + +"EXCEPT addition: Excluding components from the assignment. + +diff_struc = CORRESPONDING #( BASE ( diff_struc ) + struc EXCEPT comp1 ). +``` +**Excursion**: Copying content of a deep structure to another deep structure that has a different type. You can use statements with +[`MOVE-CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove-corresponding.htm) +and the +[`CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expr_corresponding.htm) +operator here, too. However, in the context of deep structures, more syntax variants are available. The focus of the following examples is on internal tables as structure components. See the executable example for visualizing the effect. + +> **💡 Note**
+> Bear in mind that there are special conversion and comparison rules that apply to assignments involving structures and that affect the value assignments in the internal table components. + +``` abap +"Nonidentical elementary component types are kept in target +"structure which is true for the below MOVE-CORRESPONDING statements; +"existing internal table content is replaced by content of +"the source table irrespective of identically named components + +MOVE-CORRESPONDING deep_struc TO diff_deep_struc. + +"Existing internal table content is replaced but the value +"assignment happens for identically named components only. + +MOVE-CORRESPONDING deep_struc TO diff_deep_struc + EXPANDING NESTED TABLES. + +"Existing internal table content is kept; table content of the source +"structure are added but the value assignment happens like the first +"MOVE-CORRESPONDING statement without further syntax additions. + +MOVE-CORRESPONDING deep_struc TO diff_deep_struc + KEEPING TARGET LINES. + +"Existing internal table content is kept; table content of the source +"structure are added; the value assignment happens like the statement +"MOVE-CORRESPONDING ... EXPANDING NESTED TABLES. + +MOVE-CORRESPONDING deep_struc TO diff_deep_struc + EXPANDING NESTED TABLES KEEPING TARGET LINES. + +"Target structure is initialized; the value assignment for an internal +"table happens irrespective of identically named components. + +diff_deep_struc = CORRESPONDING #( deep_struc ). + +"Target structure is initialized; the value assignment for an internal +"table happens for identically named components only. + +diff_deep_struc = CORRESPONDING #( DEEP deep_struc ). + +"Nonidentical elementary component types are kept in target structure; +"internal table content is replaced; there, the value assignment +"happens like using the CORRESPONDING operator without addition. + +diff_deep_struc = CORRESPONDING #( BASE ( diff_struc ) deep_struc ). + +"Nonidentical elementary component types are kept in target structure; +"internal table content is replaced; there, the value assignment +"happens like using the CORRESPONDING operator with the addition DEEP. + +diff_deep_struc = CORRESPONDING #( DEEP BASE ( diff_struc ) deep_struc ). + +"Nonidentical elementary component types are kept in target structure; +"internal table content is kept, too, and table content of the +"source structure are added; there, the value assignment +"happens like using the CORRESPONDING operator without addition. + +diff_deep_struc = CORRESPONDING #( APPENDING BASE ( diff_struc ) deep_struc ). + +"Nonidentical elementary component types are kept in target structure; +"internal table content is kept, too, and table content of the +"source structure are added; there, the value assignment +"happens like using the CORRESPONDING operator with the addition DEEP. + +diff_deep_struc = CORRESPONDING #( DEEP APPENDING BASE ( diff_struc ) deep_struc ). +``` + +## Clearing Structures +You can reset individual components to their initial value and clear the +complete structure using the keyword +[`CLEAR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclear.htm). +``` +CLEAR structure-component. + +CLEAR structure. +``` + +## Structures in Use in the Context of Tables +Structures are primarily used to process data from tables. In this +context, structures often assume the role of a [work +area](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwork_area_glosry.htm "Glossary Entry"). + +**Reading a line from a database table into a structure that has a matching type**. Note that, since database tables are flat, the +target structure must also be flat. In the example below, the addition +[`SINGLE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_single.htm) +reads only a single row into the structure. The first entry that is +found according to the `WHERE` condition is returned. + +> **💡 Note**
+> See more details on +[`SELECT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect.htm) +statements in the ABAP Keyword Documentation. The ABAP cheat sheet [ABAP +SQL: Working with Persisted Data in Database +Tables](03_ABAP_SQL.md) +also provides information and more code snippets when using +`SELECT` statements. +``` abap +"Creating a structure with a matching type +DATA ls_fli1 TYPE zdemo_abap_fli. + +SELECT SINGLE FROM zdemo_abap_fli + FIELDS * + WHERE carrid = 'LH' + INTO @ls_fli1. + +"Target structure declared inline +SELECT SINGLE FROM zdemo_abap_fli + FIELDS * + WHERE carrid = 'LH' + INTO @DATA(ls_fli2). +``` +**Reading a line from a database table into a structure that has a different type**. +``` abap +SELECT SINGLE FROM zdemo_abap_fli + FIELDS * + WHERE carrid = 'AA' + INTO CORRESPONDING FIELDS OF @ls_fli_diff. +``` +**Reading a line from an internal table into a structure** ... + +... using a `SELECT` statement. Note the specified alias name and that ABAP variables like internal tables must be escaped using `@`. The addition `INTO CORRESPONDING FIELDS OF` also applies here. +``` abap +SELECT SINGLE FROM @itab AS itab_alias + FIELDS * + WHERE ... + INTO @DATA(ls_struc). + "INTO CORRESPONDING FIELDS OF @struc. +``` +... using a `READ TABLE` statement. The code snippet below shows the reading of one line +into a [work +area](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwork_area_glosry.htm "Glossary Entry"), +[field +symbol](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfield_symbol_glosry.htm "Glossary Entry") +and a [data reference +variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_reference_variable_glosry.htm "Glossary Entry"), +all representing structured data objects and declared inline below. In +the example below, the reading of a line is based on the line number by +specifying `INDEX`. See the section `Determining the target area` in the cheat sheet [Working with Internal Tables](01_Internal_Tables.md#) for more details. +``` abap +READ TABLE itab INTO DATA(wa) INDEX 1. + +READ TABLE itab ASSIGNING FIELD-SYMBOL(
+> See more syntax variants and code snippets for `READ TABLE` statements and statements with table expressions in the ABAP cheat sheet `Working with Internal Tables`. + +**Sequentially reading a line from** ... + +... a database table into a structure. A `SELECT` loop can be specified by using the syntax `SELECT ... ENDSELECT.`. +In the simple example below, the line that is found and returned in a structure, which is declared inline, can be further processed. +A `SELECT` loop might also have an internal table as data source. +``` abap +SELECT FROM zdemo_abap_fli + FIELDS * + WHERE carrid = 'AZ' + INTO @DATA(ls_sel_loop). + IF sy-subrc = 0. + ... + ENDIF. +ENDSELECT. +``` +... an internal table into a structure using a [`LOOP AT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_variants.htm) statement. There are numerous options for specifying the condition on which the loop is based. The example below covers the option of reading all lines sequentially into a field symbol which is declared inline. When using a field symbol, components can be directly modified, for example. +``` abap +LOOP AT itab ASSIGNING FIELD-SYMBOL(
+> - They are not additions of `... BEGIN OF ... END OF ...` but individual ABAP statements. +> - If a chained statement is used for the structure declaration with the colon, the inclusion of other structures with these statements interrupts the chained statement, that is, the components of the included structures are included as direct components of the [superstructure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensuperstructure_glosry.htm "Glossary Entry"). +>- Using the optional addition `AS` and the specification of a name, the included components can be addressed by this common name as if the components were actually components of a substructure. +>- Using the optional addition `RENAMING WITH SUFFIX` and the specification of a name, the included components are given a suffix name to avoid naming conflicts with other components. + +The example below shows how structured types and data objects are included in another structure. First, three structured types as well as a structured data object based on one of those types are created. Then, the types and the structure are included in the structured type `address_type`. The demonstration class visualizes a structure that includes other structures this way. +``` abap +TYPES: BEGIN OF name_type, + title TYPE string, + prename TYPE string, + surname TYPE string, + END OF name_type, + BEGIN OF street_type, + name TYPE string, + number TYPE string, + END OF street_type, + BEGIN OF city_type, + zipcode TYPE string, + name TYPE string, + END OF city_type. + +DATA city_struc TYPE city_type. + +TYPES BEGIN OF address_type. + INCLUDE TYPE name_type AS name. + INCLUDE TYPE street_type AS street RENAMING WITH SUFFIX _street. + INCLUDE STRUCTURE city_struc AS city RENAMING WITH SUFFIX _city. +TYPES END OF address_type. +``` + +## More Information +See the topic +[Structures (F1 docu for standard ABAP)](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abendata_objects_structure.htm) +for more information. + +## Executable Example +[zcl_demo_abap_structures](./src/zcl_demo_abap_structures.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/03_ABAP_SQL.md b/03_ABAP_SQL.md new file mode 100644 index 0000000..42e5311 --- /dev/null +++ b/03_ABAP_SQL.md @@ -0,0 +1,1499 @@ + + +# ABAP SQL: Working with Persisted Data in Database Tables + +- [ABAP SQL: Working with Persisted Data in Database Tables](#abap-sql-working-with-persisted-data-in-database-tables) + - [Database Tables in AS ABAP in a Nutshell](#database-tables-in-as-abap-in-a-nutshell) + - [ABAP SQL Intro](#abap-sql-intro) + - [Reading Data Using SELECT](#reading-data-using-select) + - [Basic Syntax](#basic-syntax) + - [Using SELECT for Multiple Purposes](#using-select-for-multiple-purposes) + - [Clause Variations and Additions in SELECT Statements](#clause-variations-and-additions-in-select-statements) + - [Further Clauses](#further-clauses) + - [Excursion: Operands and Expressions in ABAP SQL Statements](#excursion-operands-and-expressions-in-abap-sql-statements) + - [Excursion: SQL Conditions](#excursion-sql-conditions) + - [Using SELECT when Reading from Multiple Tables](#using-select-when-reading-from-multiple-tables) + - [Excursion: Using Common Table Expressions (CTE)](#excursion-using-common-table-expressions-cte) + - [Changing Data in Database Tables](#changing-data-in-database-tables) + - [Using INSERT](#using-insert) + - [Using UPDATE](#using-update) + - [Using MODIFY](#using-modify) + - [Using DELETE](#using-delete) + - [Further Information](#further-information) + - [Executable Example](#executable-example) + + +## Database Tables in AS ABAP in a Nutshell + +Database tables in [AS +ABAP](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenas_abap_glosry.htm "Glossary Entry") +... + +- are objects of the [ABAP Dictionary + (DDIC)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_dictionary_glosry.htm "Glossary Entry") +- consist of table rows and columns; each row represents a data record + whose components (or fields) are available in columns; each + component has a data type. +- are [relational + database](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrelational_database_glosry.htm "Glossary Entry") + tables, i. e. information can be stored in multiple database tables + that are related to each other. + - For example, there might be a table containing information on + flight connections, flight destinations and times, another table + is related to this one and includes further details on the + flights like occupied seats in the plane or price details. + - Such tables define a relationship using [foreign + key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddic_database_tables_forkeyrel.htm) + relations. +- have at least one key, i.e. the [primary + key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenprimary_key_glosry.htm "Glossary Entry"), + to uniquely identify table rows; this might be one or more columns + at the beginning of each database table. +- are either + cross-[client](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclient_glosry.htm "Glossary Entry") + or client-specific to keep the data separated; client-specific + tables, which are the vast majority of database tables, include a + client field (often named `MANDT`) as their first key + field. + - Note: ABAP SQL ensures that a statement only + manipulates data from the current client. +- have a [flat + structure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenflat_structure_glosry.htm "Glossary Entry") + type. +- are physically created on the database when activated - in contrast + to [internal + tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninternal_table_glosry.htm "Glossary Entry"). + Plus, a globally available [structured + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstructured_type_glosry.htm "Glossary Entry") + of the same name is created, too. Hence, in an ABAP program, a + database table's name can be used to declare data objects, for + example, internal tables. These can be accessed by ABAP SQL, too. +- are primarily processed through ABAP SQL statements that use + [structures](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstructure_glosry.htm "Glossary Entry") + for single rows and internal tables for multiple rows to be + processed. + +
+
+ +**Views ...** + +- are further ABAP Dictionary objects for grouping particular data. +- combine columns of one or more database tables. +- usually realize a + [join](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenjoin_glosry.htm "Glossary Entry") + with defined [join + conditions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenjoin_condition_glosry.htm "Glossary Entry"). +- Note: + - Similar to database tables, the columns of such a view form a + flat structure. Hence, the view's name can be used to declare + data objects, too. + - The views can be accessed by ABAP SQL, especially for reading + purposes using `SELECT`. + +**"Classic"** [DDIC +Views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenddic_view_glosry.htm "Glossary Entry") ... + +- are the oldest form of views and are not available in SAP BTP ABAP environments. +- can be accessed by ABAP SQL for read and write operations, however, writing is only supported if the view is created with only one database table. +- can only be created in the [ABAP Workbench](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_workbench_glosry.htm). + +**"Modern" Views (since release 7.40)** + +- [External + views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenexternal_view_glosry.htm "Glossary Entry") + as proxies for [SAP HANA + views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenhana_view_glosry.htm "Glossary Entry") + (attribute view, analytic view, calculation view) + - SAP HANA Views are entities of the SAP HANA database that are + defined using the [SAP HANA + Studio](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenhana_studio_glosry.htm "Glossary Entry"). + - They are based on HANA-specific data types. + - Using external views of the ABAP dictionary, you can make those + SAP HANA views "known" to the ABAP program. In doing so, the + external views can be used like classic DDIC views as structured + data types and as a source for reading operations with ABAP SQL. + - To be used only if the central database of the AS ABAP is an + [SAP HANA + database](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhana_database_glosry.htm "Glossary Entry"). +- [ABAP Core Data Services (ABAP + CDS)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_view_glosry.htm "Glossary Entry") + ... + - serve the purpose of defining semantically rich data models. + - have a lot more options than classic views, for example, they + support annotations (provide information about views or + individual fields), data sources can be combined using + associations, unions are possible, or views can be defined with + input parameters. + - are used like a classic database view as structured data types + and used as a source for reading operations with ABAP SQL (using + [`SELECT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect.htm)). + - are created using [Data Definition + Language (DDL)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddl_glosry.htm "Glossary Entry") + in the + [ADT](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenadt_glosry.htm "Glossary Entry") + (that is, a source code editor, in contrast to a form-based + editor) + - are, in contrast to External Views, supported by all database + systems (that support the ABAP CDS characteristics). + +> **💡 Note**
+> The code snippets below focus on database tables as [data +source](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_source_glosry.htm "Glossary Entry") +for ABAP SQL statements. +
+
+
+
+## ABAP SQL Intro
+
+- ABAP-specific form of standard [Structured Query Language
+ (SQL)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_glosry.htm "Glossary Entry")
+ which is the common language to access database tables.
+- What happens behind the scenes when using an ABAP SQL statement?
+ - Generally speaking, tables in relational database systems have a
+ programming interface allowing table access using standard SQL,
+ however, these interfaces are not entirely uniform and can have
+ individual characteristics.
+ - To make AS ABAP independent of the database used, the ABAP SQL
+ statements are converted to the corresponding [Native
+ SQL](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abennative_sql_glosry.htm "Glossary Entry")
+ statements of the current database system. In doing so, ABAP SQL
+ allows a hassle-free and uniform access to the database tables
+ no matter what database system is used.
+- The main ABAP SQL keywords to read and change data are the
+ following:
+
+ | Keyword | Purpose |
+ | -------- | ------------------------------------------------------------------------- |
+ | `SELECT` | Reads data from database tables |
+ | `INSERT` | Adds rows to database tables |
+ | `UPDATE` | Changes the content of rows of database tables |
+ | `MODIFY` | Inserts rows into database tables or changes the content of existing rows |
+ | `DELETE` | Deletes rows from database tables |
+
+- For a good level of performance of your ABAP programs when using
+ ABAP SQL, you should follow the rules in the performance notes
+ outlined
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_sql_perfo.htm).
+ The considerations there are not relevant for this cheat sheet since
+ the focus is on syntactical options.
+
+## Reading Data Using SELECT
+
+### Basic Syntax
+
+You use ABAP SQL `SELECT` statements to read records from the
+database, either by accessing a database table directly or via a view.
+The `SELECT` statement includes several clauses that serve
+different purposes. The following code snippet shows the basic syntax:
+``` abap
+SELECT FROM source "What db table or view to read from
+ FIELDS field_list "What columns should be read
+ WHERE condition "Specifies conditions on which a row/rows should be read
+ INTO target. "Data object into which data should be read
+```
+> **💡 Note**Excursion: Views
++ +**Views ...** + +- are further ABAP Dictionary objects for grouping particular data. +- combine columns of one or more database tables. +- usually realize a + [join](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenjoin_glosry.htm "Glossary Entry") + with defined [join + conditions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenjoin_condition_glosry.htm "Glossary Entry"). +- Note: + - Similar to database tables, the columns of such a view form a + flat structure. Hence, the view's name can be used to declare + data objects, too. + - The views can be accessed by ABAP SQL, especially for reading + purposes using `SELECT`. + +**"Classic"** [DDIC +Views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenddic_view_glosry.htm "Glossary Entry") ... + +- are the oldest form of views and are not available in SAP BTP ABAP environments. +- can be accessed by ABAP SQL for read and write operations, however, writing is only supported if the view is created with only one database table. +- can only be created in the [ABAP Workbench](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_workbench_glosry.htm). + +**"Modern" Views (since release 7.40)** + +- [External + views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenexternal_view_glosry.htm "Glossary Entry") + as proxies for [SAP HANA + views](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenhana_view_glosry.htm "Glossary Entry") + (attribute view, analytic view, calculation view) + - SAP HANA Views are entities of the SAP HANA database that are + defined using the [SAP HANA + Studio](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenhana_studio_glosry.htm "Glossary Entry"). + - They are based on HANA-specific data types. + - Using external views of the ABAP dictionary, you can make those + SAP HANA views "known" to the ABAP program. In doing so, the + external views can be used like classic DDIC views as structured + data types and as a source for reading operations with ABAP SQL. + - To be used only if the central database of the AS ABAP is an + [SAP HANA + database](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhana_database_glosry.htm "Glossary Entry"). +- [ABAP Core Data Services (ABAP + CDS)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_view_glosry.htm "Glossary Entry") + ... + - serve the purpose of defining semantically rich data models. + - have a lot more options than classic views, for example, they + support annotations (provide information about views or + individual fields), data sources can be combined using + associations, unions are possible, or views can be defined with + input parameters. + - are used like a classic database view as structured data types + and used as a source for reading operations with ABAP SQL (using + [`SELECT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect.htm)). + - are created using [Data Definition + Language (DDL)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddl_glosry.htm "Glossary Entry") + in the + [ADT](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenadt_glosry.htm "Glossary Entry") + (that is, a source code editor, in contrast to a form-based + editor) + - are, in contrast to External Views, supported by all database + systems (that support the ABAP CDS characteristics). + +> **💡 Note**
+> The code snippets below focus on database tables as [data +source](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_source_glosry.htm "Glossary Entry") +for ABAP SQL statements. +
+>- There are further clauses available of which some are dealt with + further down. +>- Especially in older ABAP programs, you will see other forms of the + `SELECT` syntax that you should no longer use. Depending on + the ABAP release in your on-premise system, strict syntax check modes might enforce the use + of specific ABAP SQL syntax. For example, the `INTO` clause + should be placed after the other clauses. This was not possible for + older statements. Furthermore, [host + variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhost_variable_glosry.htm "Glossary Entry") + or [host + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhost_expression_glosry.htm "Glossary Entry") + are required for variables and expressions, i. e. variables and + expressions must be preceded by `@` or `@( ... )`. + This is also true for other ABAP SQL statements further down. + Further information: [Release-Dependent Syntax Check + Modes](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_sql_strict_modes.htm). +>- The list of fields can also directly follow the `SELECT` + keyword and be positioned before the `FROM` clause. In this + case, a separate `FIELDS` clause cannot be specified. The + following two code snippets are basically the same: +> ``` abap +> SELECT FROM dbtab +> FIELDS comp1, comp2, comp3 +> ... +> +> SELECT comp1, comp2, comp3 +> FROM dbtab +> ... +> ``` +>- Regarding the target into which data is read: Instead of using a + variable that is (extra) declared beforehand, you can also make use + of [inline + declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninline_declaration_glosry.htm "Glossary Entry"), + for example `... INTO TABLE @DATA(itab).`, to comfortably + create an appropriate variable in place. Note that in case of + internal tables as targets, the resulting table is a standard table + and has an empty key which might have an impact when further + processing the internal table entries. Find more information in the + ABAP cheat sheet [Working with Internal Tables](01_Internal_Tables.md). + + + +### Using SELECT for Multiple Purposes + +**Reading a single row into a structure**. The read result can, for +example, be stored in an existing structure (`struc`) or a +structure that is declared inline. Specifying an asterisk (`*`) indicates +that all fields are to be read. Alternatively, you can list all the +fields separated by comma. +``` abap +"Reading all fields of a single row + +SELECT SINGLE FROM dbtab + FIELDS * + WHERE ... + INTO @struc. "Existing structure of dbtab's row type + +"Reading a selected set of fields of a single row + +SELECT SINGLE FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + INTO @DATA(struc2). "Structure declared inline + +"Alternative syntax without the FIELDS addition +"When reading into an existing target variable on the basis of a selected +"set of fields, use a CORRESPONDING addition in the INTO clause + +SELECT SINGLE comp1, comp2, comp3 "Selected set of fields + FROM dbtab + WHERE ... + INTO CORRESPONDING FIELDS OF @struc. "Existing structure +``` +> **💡 Note**
+>- When listing the fields, only those fields that are really of + interest should be read as a rule for performance reasons. +>- It makes a lot of sense to further restrict the read result, for + example and although it is optional, a `WHERE` clause should + always be specified for performance reasons too to restrict the read + result. +>- The addition `CORRESPONDING FIELDS OF` in the `INTO` + clause is required when using an existing variable as target and + listing the fields, otherwise a type compatibility issue might arise + because the variable is filled from left to right beginning with the + first field in the list of fields. + +**Reading multiple rows into an internal table**. The read result +can, for example, be stored in an existing internal table +(`itab`) or an internal table that is declared inline. +``` abap +SELECT FROM dbtab + FIELDS * "All fields + WHERE ... + INTO TABLE @itab. "itab has an appropriate row type + +"Alternative syntax without the FIELDS addition + +SELECT comp1, comp2, comp3 "Selected set of fields + FROM dbtab + WHERE ... + INTO TABLE @DATA(lv_itab). "Internal table declared inline + +"Reading a selected set of fields into an existing variable + +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 "Selected set of fields + WHERE ... + INTO CORRESPONDING FIELDS OF TABLE @itab. +``` + +`SELECT` **loop: Sequentially reading multiple rows into a structure**. If the row is found, the system field `sy-subrc` is set to `0`. +``` abap +SELECT FROM dbtab + FIELDS * + WHERE ... + INTO @struc. + IF sy-subrc = 0. + ... "For example, making changes on data and adding the row to an internal table. + ENDIF. +ENDSELECT. +``` + +**Reading into an existing target variable that does not have a matching type**. If you choose to store the result in a variable that has +not a matching type, the `CORRESPONDING FIELDS OF` addition +should be used so as not to mess up the result. Note that this addition +is also valid for `SELECT` statements that use an existing +target variable and only a selected set of fields should be read into +the target variable. + +``` abap +"Reading a single row into an existing structure that does not have a matching type + +SELECT SINGLE FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + INTO CORRESPONDING FIELDS OF @diff_struc. + +"Reading multiple rows into an existing internal table that does not +"have a matching type. Note that the target table is initialized +"with this addition. + +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + INTO CORRESPONDING FIELDS OF TABLE @diff_itab. +``` + +> **💡 Note**
+>- If only `INTO` is used, the selected columns must be in the + correct order fitting to the structure type of the target variable. + Only the content of columns for which there are components of the + same name in the structure of the target is read from the result + set. +>- If identically named components have different types, the system + tries to convert the content of source fields into the type of the + target field. In this case, there is a risk of data loss and runtime + errors due to conversion errors. +>- Find more information regarding the addition + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinto_clause.htm). + + + +### Clause Variations and Additions in SELECT Statements + +`SELECT`/`FROM` clause: + +**Checking the existence of a row in a database table** +``` abap +"Instead of @abap_true, you could use 'X' + +SELECT SINGLE @abap_true + FROM dbtab + WHERE ... + INTO @DATA(exists). + +IF exists = abap_true. + ... +ENDIF. +``` + +**Reading multiple rows into an internal table by excluding duplicate rows from the multiline result set** using `DISTINCT`. +The duplicate entries might occur due to a non-unique `WHERE` clause. +``` abap +SELECT DISTINCT comp1 + FROM dbtab + WHERE ... + INTO TABLE @itab. +``` +**Setting new field names by specifying an alias name** with [`AS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_list.htm)]. + +The alias name can be helpful for a situation like this: Data from a +database table is to be read into an existing table but the line type +does not match, some fields might have different names. Using an alias +name, you can read the data into the corresponding field names of the +target table (provided that there will not be an issue regarding the +type). +``` abap +SELECT FROM dbtab + FIELDS comp1 AS alias1, comp2 AS alias2, comp3 AS alias3 + WHERE ... + INTO CORRESPONDING FIELDS OF TABLE @itab. +``` + +**Getting data from a database table in another client** (not available in SAP BTP ABAP environments). Note that there are several variants of the `USING CLIENT` addition, for example, you can also specify `ALL CLIENTS` to select from database tables in all clients. Furthermore, the `USING CLIENT` addition is also available for the ABAP SQL statements that modify database table entries further down. +``` abap +"Not available in SAP BTP ABAP environments +SELECT * + FROM dbtab USING CLIENT '000' + WHERE ... + INTO TABLE @itab. + +SELECT * + FROM dbtab USING ALL CLIENTS + WHERE ... + INTO TABLE @itab. +``` + +`INTO` **clause**: + +**Restricting the absolute number of returned table rows** using the addition [`UP TO n +ROWS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_up_to_offset.htm). +In the example below, only five rows are to be returned at most. +``` abap +SELECT * FROM dbtab + WHERE ... + INTO TABLE @DATA(itab_upto) + UP TO 5 ROWS. +``` +**Appending the result set to an existing internal table**. By appending, you avoid the deletion of existing lines in internal tables. +``` abap +"itab has a matching line type +SELECT * FROM dbtab + WHERE ... + APPENDING TABLE @itab. +``` + +If the target table does not have a matching type, you can use the addition `CORRESPONDING FIELDS OF`. +``` abap +SELECT * FROM dbtab + WHERE ... + APPENDING CORRESPONDING FIELDS OF TABLE @diff_itab. +``` +**Reading single fields into individual variables**. Note that the number of columns specified (here, in the `FIELDS` clause) must match the number of elements in the `INTO` clause. +``` abap +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + INTO (@res1,@res2,@res3). +``` +**Reading into packages when reading into internal tables**. The +[package +size](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinto_clause.htm) +defines how many rows should be selected in one iteration. This is handy +in case a very large amount of data has to be processed that might be +too large for the memory capacity of an internal table, thus avoiding +program termination. The package size is specified by an integer value. +``` abap +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + INTO TABLE @DATA(itab_pack) PACKAGE SIZE i. +... +ENDSELECT. +``` + + + +### Further Clauses + +[`GROUP BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapgroupby_clause.htm) +clause: Combining groups of table rows in the result set. You +might also use [SQL expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_expression_glosry.htm "Glossary Entry") +here. Multiple clause elements are separated by a comma. Find more +information on SQL expressions further down. + +Note that the `GROUP BY` clause requires all columns that are +directly specified in the `SELECT` list or specified there as an +argument of an SQL expression to be specified. An exception to this is +[aggregate +functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenaggregate_function_glosry.htm "Glossary Entry") +in [aggregate +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenaggregate_expression_glosry.htm "Glossary Entry") +(except [grouping +functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abengrouping_glosry.htm "Glossary Entry")) +as shown in the following example. + +In the example below, the database table rows that have the same content in column `comp1` are combined. The lowest and highest values in column `comp2` are determined for each of these groups and placed into the combined row. +``` abap +SELECT FROM dbtab + FIELDS comp1, MIN( comp2 ) AS min, MAX( comp2 ) AS max + WHERE ... + GROUP BY comp1 + INTO ... +``` + +[`HAVING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaphaving_clause.htm) +clause: Limiting the number of table rows in groups in the +result by setting conditions on these rows. The rows for which a +logical expression is true are inserted in the target variable. Note +that `HAVING` can only be used together with `GROUP BY`. +``` abap +SELECT FROM dbtab + FIELDS comp1, MIN( comp2 ) AS min, MAX( comp3 ) AS max + WHERE ... + GROUP BY comp1 + HAVING comp1 LIKE '%XYZ%' AND SUM( comp4 ) > 100 + INTO ... +``` + +[`ORDER BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaporderby_clause.htm) +clause: Sorting the result set by specified columns. + +The following example shows the ordering of the result set based on the +content of the primary key of the [data +source](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_source_glosry.htm "Glossary Entry"). +You can also order by any columns and by explicitly specifying the sort +order. There are more ordering options, for example, by using SQL +expressions. +``` abap +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE ... + ORDER BY PRIMARY KEY + "comp2 ASCENDING + "comp2 DESCENDING + INTO ... +``` + +> **💡 Note**
+>- Not specifying `ORDER BY` means that the order of entries in the result set is undefined. +>- If `ORDER BY` and `GROUP BY` clauses are used, all columns specified after `ORDER BY` must also be specified after `GROUP BY`. +>- If aggregate functions are specified after `SELECT`, all columns that are specified after `ORDER BY` and that do not have an alias name for an aggregate function must also be specified after `SELECT` and after the `GROUP BY` clause which is required in this case, too. + + + +### Excursion: Operands and Expressions in ABAP SQL Statements + +ABAP offers plenty of [SQL +operands](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_operand_glosry.htm "Glossary Entry") +and +[expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_expression_glosry.htm "Glossary Entry") +that are possible in ABAP SQL statements, not only in the context of +`SELECT` statements and the `SELECT` lists which are +mainly used for the following demonstration examples. Questions about +when to use what, what is possible in which contexts and positions, is +beyond the scope of this cheat sheet. Check the details in the +respective topics in the ABAP Keyword Documentation. Find a general +overview of important operand positions in ABAP SQL +[here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_operand_positions_oview.htm). +Due to the rich variety of options, the cheat sheet covers a selection. + +**SQL operands** + +- Are elementary operands in an ABAP SQL statement +- Can be database table or view columns, a + [literal](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenliteral_glosry.htm "Glossary Entry"), + [host + variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhost_variable_glosry.htm "Glossary Entry") + (i. e. global or local data objects escaped using `@`: + `@dobj`) or [host + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhost_expression_glosry.htm "Glossary Entry") + (`@( ... )`) + - Regarding literals: They are not prefixed with the escape + character `@`. The literals can be + [typed](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentyped_literal_glosry.htm "Glossary Entry") + (using the type name and content within a pair of backquotes: +
char\`abc\`) with [built-in ABAP Dictionary
+ types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddic_builtin_types.htm)
+ or untyped. Typed literals are preferable for the following
+ reasons: Using untyped literals means extra cost in terms of
+ performance since they must be converted by the compiler. Plus,
+ their use can result in errors at runtime whereas typed literals
+ guarantee type compatibility at once.
+ - Regarding host expressions: Structures and internal tables are
+ possible as host expressions for statements modifying the
+ content of database tables as shown further down.
+- See more information
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_operands.htm).
+
+Example demonstrating possible operands:
+``` abap
+DATA upto TYPE i VALUE 3.
+
+SELECT FROM zdemo_abap_flsch
+ FIELDS
+ "Specifies a column of a data source directly using its name
+ cityfrom,
+
+ "Column selector ~ can be used to prefix every specified column.
+ "Here, it is optional. It is non-optional, e. g., if multiple data
+ "sources in an ABAP SQL statement are edited and the column name
+ "is not unique. ]
+ zdemo_abap_flsch~cityto,
+
+ 'Lufthansa' AS name, "Untyped literal
+
+ char`X` AS flag, "Typed literal
+
+ @upto as num, "Host variable
+
+ @( cl_abap_context_info=>get_system_date( ) ) as date "Host expression
+
+ WHERE carrid = 'LH' "Untyped literal
+ AND countryfr = char`DE` "Typed literal
+
+ "Data object created inline and escaped with @
+ INTO TABLE @DATA(it)
+
+ "The following clause shows all options having the same effect
+ UP TO 3 ROWS. "Untyped numeric literal
+ "UP TO int4`3` ROWS. "Typed numerice literal
+ "UP TO @upto ROWS. "Host variable
+ "UP TO @( 10 - 7 ) ROWS. "Host expression
+```
+
+**SQL Expressions**
+
+- Expressions in an ABAP SQL statement that are passed to the database
+ system for evaluation.
+- For example, SQL expressions can be specified as columns in the
+ `SELECT` as demonstrated in most of the following examples.
+ Find information on more possible positions and general information
+ on SQL expressions
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapsql_expr.htm)
+ and the subtopics there.
+
+**Elementary expressions**
+
+- An elementary expression represents one of the four mentioned
+ operands above: A value from the database (the column name) or
+ values from an ABAP program passed to the database (literal, host
+ variable or host expression).
+- As an example, see the `SELECT` list in the example above.
+- See more information
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_elem.htm).
+
+**SQL functions**
+
+- You can use built-in functions in ABAP SQL.
+- Result: Value with the associated dictionary type.
+- Arguments of the functions: Cover one or more SQL expressions.
+- See more information
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_sql_builtin_functions.htm).
+
+Example: [Numeric functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_arith_func.htm)
+``` abap
+SELECT SINGLE
+ carrname,
+
+ "Division, result rounded to an integer
+ "Result: 2
+ div( 4, 2 ) AS div,
+
+ "Division, 3rd argument: result is rounded to the specified
+ "number of decimals
+ "Result: 0.33
+ division( 1, 3, 2 ) AS division,
+
+ "Result is rounded to first greater integer
+ "Result: 2
+ ceil( decfloat34`1.333` ) AS ceil,
+
+ "Result is the remainder of division
+ "Result: 1
+ mod( 3, 2 ) AS mod,
+
+ "Result: Largest integer value not greater than the specified value
+ "Result: 1
+ floor( decfloat34`1.333` ) AS floor,
+
+ "Returns the absolute number
+ "Result: 2
+ abs( int4`-2` ) AS abs,
+
+ "Result is rounded to the specified position after the decimal separator
+ "Result: 1.34
+ round( decfloat34`1.337`, 2 ) AS round
+
+ FROM zdemo_abap_carr
+ WHERE carrid = 'AA'
+ INTO @DATA(numeric_functions).
+```
+
+Example: [String functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_string_func.htm)
+
+``` abap
+SELECT SINGLE
+ carrid, "LH
+ carrname, "Lufthansa
+ url, "http://www.lufthansa.com
+
+ "Concatenates strings, ignores trailing blanks
+ "Result: LHLufthansa
+ concat( carrid, carrname ) AS concat,
+
+ "Concatenates strings, number denotes the blanks that are inserted
+ "Result: LH Lufthansa
+ concat_with_space( carrid, carrname, 1 ) AS concat_with_space,
+
+ "First letter of a word -> uppercase, all other letters -> lowercase;
+ "note that a space and other special characters means a new word.
+ "Result: Http://Www.Lufthansa.Com
+ initcap( url ) AS initcap,
+
+ "Position of the first occurrence of the substring specified
+ "Result: 6
+ instr( carrname,'a' ) AS instr,
+
+ "String of length n starting from the left of an expression;
+ "trailing blanks are ignored
+ "Result: Luft
+ left( carrname, 4 ) AS left,
+
+ "Number of characters in an expression, trailing blanks are ignored
+ "Result: 24
+ length( url ) AS length,
+
+ "Checks if expression contains a PCRE expression;
+ "case-sensitive by default (case_sensitive parameter can be specified)
+ "Notes on the result: 1 = found, 0 = not found
+ "Result: 1
+ like_regexpr( pcre = '..', "Period that is followed by any character
+ value = url ) AS like_regex,
+
+ "Returns position of a substring in an expression,
+ "3rd parameter = specifies offset (optional)
+ "4th parameter = determines the number of occurrences (optional)
+ "Result: 9
+ locate( carrname, 'a', 0, 2 ) AS locate,
+
+ "Searches a PCRE pattern, returns offset of match;
+ "many optional parameters: occurrence, case_sensitive, start, group
+ "Result: 21
+ locate_regexpr( pcre = '..', "Period followed by any character
+ value = url,
+ occurrence = 2 ) "2nd occurrence in the string
+ AS locate_regexpr,
+
+ "Searches a PCRE pattern, returns offset of match + 1;
+ "many optional parameters: occurrence, case_sensitive, start, group
+ "Result: 2
+ locate_regexpr_after( pcre = '.', "Any character
+ value = url,
+ occurrence = 1 ) AS locate_regexpr_after,
+
+ "Removes leading characters as specified in the 2nd argument,
+ "trailing blanks are removed
+ "Result: ufthansa
+ ltrim( carrname, 'L' ) AS ltrim,
+
+ "Counts all occurrences of found PCRE patterns
+ "Result: 2
+ occurrences_regexpr( pcre = '..',
+ value = url ) AS occ_regex,
+
+ "Replaces the 2nd argument with the 3rd in an expression
+ "Result: Lufth#ns#
+ replace( carrname, 'a', '#' ) AS replace,
+
+ "Replaces a found PCRE expression;
+ "more parameters possible: occurrence, case_sensitive, start
+ "Result: http://www#ufthansa#om
+ replace_regexpr( pcre = '..',
+ value = url,
+ with = '#' ) AS replace_regex,
+
+ "Extracts a string with the length specified starting from the right
+ "Result: hansa
+ right( carrname, 5 ) AS right,
+
+ "Expands string to length n (2nd argument); trailing blanks produced
+ "are replaced by the characters from the (3rd) argument
+ "Note that if n is less than the string, the expression is truncated
+ "on the right.
+ "Result: Lufthansa###
+ rpad( carrname, 12, '#' ) AS rpad,
+
+ "All trailing characters that match the character of the 2nd argument
+ "are removed; trailing blanks are removed, too
+ "Result: Lufthans
+ rtrim( carrname, 'a' ) AS rtrim,
+
+ "Returns a substring; 2nd argument = position from where to start;
+ "3rd argument: length of the extracted substring
+ "Result: fth
+ substring( carrname, 3, 3 ) AS substring,
+
+ "Searches for a PCRE expression and returns the matched substring
+ "More parameters possible: occurrence, case_sensitive, start, group
+ "Result:.lu
+ substring_regexpr( pcre = '...',
+ value = url ) AS substring_regexpr,
+
+ "All lower case letters are transformed to upper case letters
+ "Result: LUFTHANSA
+ upper( carrname ) AS upper
+
+ FROM zdemo_abap_carr
+ WHERE carrid = 'LH'
+ INTO @FINAL(string_functions).
+```
+
+Example: [Special functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_sql_special_functions.htm)
+
+``` abap
+SELECT SINGLE
+ carrid,
+
+ "Conversion functions
+ "When used: Special conversions that cannot be handled in a general
+ "CAST expression
+
+ "Type conversion: string of fixed length (e.g. of type c) to variable
+ "length string of type string
+ to_clob( carrid ) AS clob,
+
+ "Byte string -> character string
+ bintohex( raw`3599421128650F4EE00008000978B976` ) AS bintohex,
+
+ "Character string -> byte string
+ hextobin( char`3599421128650F4EE00008000978B976` ) AS hextobin,
+
+ "Byte field of type RAW to a byte string (BLOB) of type RAWSTRING
+ to_blob( raw`3599421128650F4EE00008000978B976` ) AS blob,
+
+ "Unit and currency conversion functions
+ "More parameters are available.
+
+ "Converts miles to kilometers
+ unit_conversion( quantity = d34n`1`,
+ source_unit = unit`MI`,
+ target_unit = unit`KM` ) AS miles_to_km,
+
+ "Converts Euro to US dollars using today's rate
+ currency_conversion(
+ amount = d34n`1`,
+ source_currency = char`EUR`,
+ target_currency = char`USD`,
+ exchange_rate_date = @( cl_abap_context_info=>get_system_date( ) )
+ ) AS eur_to_usd,
+
+ "Date and time functions
+ add_days( @( cl_abap_context_info=>get_system_date( ) ), 4 ) AS add_days,
+ add_months( @( cl_abap_context_info=>get_system_date( ) ), 2 ) AS add_months,
+ is_valid( @( cl_abap_context_info=>get_system_date( ) ) ) AS date_is_valid,
+ is_valid( @( cl_abap_context_info=>get_system_time( ) ) ) AS time_is_valid
+
+FROM zdemo_abap_carr
+INTO @FINAL(special_functions).
+```
+
+[Aggregate expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_aggregate.htm)
+
+- Consist of [aggregate
+ functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenaggregate_function_glosry.htm "Glossary Entry")
+ and aggregate the values of multiple rows of the result set of a
+ [query](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenquery_glosry.htm "Glossary Entry")
+ into a single value
+- See more information
+ [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_aggregate.htm).
+
+Example:
+``` abap
+"The example shows a selection of available functions
+SELECT
+ carrid,
+
+ "Average value of the content of a column in a row set
+ AVG( fltime ) AS fltime1,
+
+ "AVG with data type specification for the result
+ AVG( fltime AS DEC( 14,4 ) ) AS fltime2,
+
+ "Maximum value of the results in a row set
+ MAX( fltime ) AS max,
+
+ "Minimum value
+ MIN( fltime ) AS min,
+
+ "Sum of the results in a row set.
+ SUM( fltime ) AS sum,
+
+ "Returns the number of rows in a row set.
+ "The following two have the same meaning.
+ COUNT( * ) AS count2,
+ COUNT(*) AS count3,
+
+ "Chains the results in a row set.
+ "An optional separator can be specified
+ STRING_AGG( airpfrom, ', ' ) AS string_agg
+
+ FROM zdemo_abap_flsch
+ WHERE carrid = 'LH'
+ GROUP BY carrid
+ INTO TABLE @FINAL(agg_exp).
+```
+
+**More SQL Expressions**
+
+- [Arithmetic
+ expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_arith.htm)
+ to perform arithmetic calculations using the operators `+`,
+ `-`, [`*]`, `/`,
+- [Cast
+ expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_cast.htm)
+ to convert the value of operands to a dedicated dictionary type.
+ Note that there are special [conversion
+ rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_cast_rules.htm).
+- [String
+ expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_string.htm)
+ using the operator `&&` to concatenate character strings.
+- [Case
+ distinctions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_case.htm)
+ to carry out either a simple (comparison of the values of a
+ dedicated operand) or complex (searched case; evaluation of multiple
+ logical expressions) case distinction.
+
+The following example demonstrates the expressions mentioned above:
+``` abap
+SELECT SINGLE
+ carrid,
+
+ "Arithmethic expressions
+ "operators + - *
+ "Note that / is not allowed in integer expressions as the one below
+ ( 1 + 2 ) * 3 AS calc,
+
+ "/ used in an expression using type adjustment in ABAP SQL.
+ "A cast expression converts the value of the operands to the
+ "specified dictionary type. The result is a representation of the
+ "source value in the specified type.
+ CAST( 1 AS D34N ) / CAST( 2 AS D34N ) AS ratio,
+
+ "String expression using && to concatenate two character strings;
+ "the result of the concatenation must not be longer than
+ "255 characters.
+ carrid && carrname AS concat,
+
+ "Case distinction
+ "Simple case distinction
+ "The expression compares the values of an operand with other
+ "operands. Result: The first operand after THEN for which the
+ "comparison is true. If no matches are found, the result specified
+ "after ELSE is selected.
+ CASE currcode
+ WHEN 'EUR' THEN 'A'
+ WHEN 'USD' THEN 'B'
+ ELSE 'C'
+ END AS case_simple,
+
+ "Complex case distinction
+ "The expression evaluates logical expressions. Result: The first
+ "operand after THEN for which the logical expression is true. If no
+ "logical expressions are true, the result specified after ELSE is
+ "selected.
+ CASE WHEN length( carrname ) <= 5 THEN 'small'
+ WHEN length( carrname ) BETWEEN 6 AND 10 THEN 'mid'
+ WHEN length( carrname ) BETWEEN 11 AND 15 THEN 'large'
+ ELSE 'huge'
+ END AS case_complex
+
+FROM zdemo_abap_carr
+WHERE carrid = 'AA'
+INTO @DATA(more_sql_expr).
+```
+
+[Window expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwindow_expression_glosry.htm "Glossary Entry")
+
+How they work:
+
+- Defines a subset of the result set (i. e. the
+ "[window](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwindow_glosry.htm "Glossary Entry")")
+ of a database query that implements ABAP SQL
+- Applies a [window
+ function](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwindow_function_glosry.htm "Glossary Entry") -
+ which evaluates the rows of the window and which can, for example,
+ be an [aggregate
+ function](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenaggregate_function_glosry.htm "Glossary Entry")
+ like
+ [`AVG`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_agg_func&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_VARIANT_1@1@&tree=X)
+ to determine the average value - to the result set
+- I. e. a window is constructed by the rows of the result set for
+ which all the window functions have the same result; a value is then
+ determined for the rows of a window
+
+Setup of a statement with window expressions:
+
+- Window function, e. g. an aggregate function like `AVG`,
+ followed by `OVER( ... )` (the content in the parentheses
+ defines the "window")
+- The content in the parentheses can contain the following additions:
+ - Optional `PARTITION BY`: Defines the windows using a
+ comma-separated list of [SQL
+ expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapsql_expr.htm);
+ the window function is calculated for the rows of this window;
+ note that if the addition is not specified, the window comprises
+ all rows of the result set
+ - Optional `ORDER BY`: Introduces both an order (you can
+ use `ASCENDING` and `DESCENDING`) and a frame
+ (as outlined below) within the current window, which further
+ restricts the rows for which the window function is calculated
+ - A window frame, which stands for a subset of rows inside a
+ window, can optionally be defined if `ORDER BY` is
+ specified; there are 3 options to define the starting and ending
+ frame boundaries (see the example)
+
+See more information on window expressions and the syntax
+[here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_over.htm).
+
+Examples:
+``` abap
+"Example 1: A simple window is constructed in the OVER clause;
+"window functions - here aggregate functions - are applied
+SELECT carrid, currency,
+ SUM( paymentsum ) OVER( PARTITION BY carrid ) AS sum,
+ AVG( price AS DEC( 14,2 ) ) OVER( PARTITION BY carrid ) AS avg,
+ MAX( price ) OVER( PARTITION BY carrid ) AS max
+ FROM zdemo_abap_fli
+ ORDER BY carrid
+ INTO TABLE @DATA(win).
+
+"Example 2:
+SELECT carrid, currency, fldate,
+ "Sorts the rows by some columns and counts the number of rows from
+ "the first row of the window to the current row.
+ COUNT( * ) OVER( ORDER BY currency, fldate
+ ROWS BETWEEN
+ "UNBOUNDED PRECEDING: frame starts at the
+ "first row of the window
+ UNBOUNDED PRECEDING
+ "CURRENT ROW: determines starting or ending
+ "at the current row; here, it ends
+ AND CURRENT ROW ) AS count1,
+
+ "If no window frame is used, the default window frame is
+ "BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW,
+ "i. e. the result of count1 equals the result of count2.
+ COUNT( * ) OVER( ORDER BY currency, fldate ) AS count2,
+
+ "Sorts the rows by some columns and counts the number of rows from
+ "the current row to the last row of the window.
+ "The result is reverse numbering.
+ COUNT( * ) OVER( ORDER BY currency, fldate
+ ROWS BETWEEN CURRENT ROW
+ "UNBOUND FOLLOWING:
+ "Determines the ending frame boundary,
+ "this addition specifies the last row of the window
+ AND UNBOUNDED FOLLOWING ) AS count_reverse,
+
+ "Sorts the rows by some columns and calculates the rolling averages
+ "of a subset of rows from column price. The subset consists of the
+ "current row plus one preceding and one following row. Another use
+ "case as below example that uses prices would be that, for example,
+ "you can calculate the 3-day-average temperature for every day from
+ "a list of temperature data.
+ AVG( price AS DEC( 14,2 ) ) OVER( ORDER BY currency, fldate
+ ROWS BETWEEN
+ "n PRECEDING: for both start and end of frame;
+ "frame to start/end n rows above the current row
+ 1 PRECEDING
+ "n FOLLOWING: for both start and end of frame;
+ "frame to start/end n rows beneath the current row
+ AND 1 FOLLOWING ) AS avg
+
+ FROM zdemo_abap_fli
+ INTO TABLE @DATA(result).
+```
+
+### Excursion: SQL Conditions
+
+You can formulate conditions in ABAP SQL statements, i. e. [logical
+expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogical_expression_glosry.htm "Glossary Entry"),
+especially in the `WHERE` clause to restrict the result. Note
+that without a `WHERE` clause, all rows are respected for the
+operation.
+
+See below a selection of the operators that are possible when specifying
+conditions. For more information, see the subtopics of the [SQL
+Conditions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenasql_cond.htm)
+topic.
+
+
+| Operator | Meaning |
+|----------|:-------------:|
+ | `=`, `EQ` | The content of two operands is equal.|
+| `<>`, `NE` | The content of two operands is not equal.|
+ | `<`, `LT` | The content of one operand is less than the content of the other operand.|
+ | `>`, `GT` | The content of one operand is greater than the content of the other operand.|
+ | `<=`, `LE` | The content of one operand is less than or equal to the content of the other operand.|
+ | `>=`, `GE` | The content of one operand is greater than or equal to the content of the other operand.|
+ | `... [NOT] BETWEEN ... AND ...` | The value of an operand is (not) between the value of the two other operands.|
+ | `... [NOT] LIKE ...` | The content of an operand matches (does not match) a specified pattern. The pattern can be specified by using wildcard characters. `%` stands for any character string, including an empty string.◾`_` stands for any character.|
+ | `... IS [NOT] INITIAL ...` | The value of an operand is (not) the initial value of its built-in dictionary type.|
+ | `... EXISTS ...` | Checks the result set of a [subquery](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubquery_glosry.htm "Glossary Entry"). The expression is true if the result set contains at least one row. See more information [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwhere_logexp_subquery.htm).|
+ | `... [NOT] IN ( ... )` | Checks whether the operands on the left side match a value from a set of values specified in parentheses. On the left side, a single operand or an operand list are possible. On the right side, a comma-separated lists or subqueries can be specified.|
+
+> **💡 Note**+>You can combine multiple logical expressions into one +logical expression using `AND` or `OR`. To further +detail out the desired condition, expressions within parentheses are +possible. + +The clause parts that are commented out in the following code snippet +just demonstrate how the `WHERE` clause might look like. + +``` abap +SELECT FROM dbtab + FIELDS comp1, comp2, comp3 + WHERE comp1 = 'abc' "Equals some value + + "More example WHERE conditions: + "comp2 > 100 "Greater than some value; alternatively GT is possible + + "Not equals plus an additional condition that must be respected + "comp2 <> 100 AND comp4 = 'xyz' + + "(Not) between a value range + "comp1 BETWEEN 1 AND 10 + + "A character literal has a certain pattern, preceded and + "followed by any string. + "comp1 LIKE '%XYZ%' + + "The second character is not Y. _ stands for any character. + "comp1 NOT LIKE '_Y%' + + "Contains one of the values specified in the parentheses + "comp1 IN ( 'ABC', 'DEF', 'GHI' ) + + "Does not contain one of the values specified in the parentheses + "comp1 NOT IN ( 'JKL', 'MNO' ) + + "Checking if an operand has an initial value + "comp1 IS INITIAL + + "Combination of logical expression using AND, OR and parentheses + "( comp1 = a AND comp2 < b ) OR ( comp3> c AND comp4 <> d ) + + INTO TABLE @DATA(itab_where). +``` + + +### Using SELECT when Reading from Multiple Tables + +[`FOR ALL ENTRIES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwhere_all_entries.htm) +addition: Reading data from a database table depending on the +content of an internal table. +``` abap +"Checking that table is not initial +IF ( 0 < lines( itab2 ) ). + + SELECT comp1, comp2, comp3 + FROM dbtab + FOR ALL ENTRIES IN @itab2 "Host variable before internal table + WHERE comp1 = @itab2-comp1 ... "Relational expression on the right side of a comparison + INTO TABLE @itab1 + +ENDIF. +``` + + +> **💡 Note**
+>- The entire logical expression after `WHERE` is evaluated for each individual line in the internal table. +>- There must be at least one comparison with a column of the internal +table in the `WHERE` clause. +>- Ensure that the internal table from which to read is not initial. It is recommended that you use a subquery, which is shown in the next example, and a `SELECT` statement that reads from the internal table (`... ( SELECT ... FROM itab2 WHERE ...`). + +**Using a subquery** with the addition `EXISTS` to read data from a database table depending +on data of another database table. More information: +[`EXISTS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwhere_logexp_exists.htm). The components of the table are referenced by `~`. +``` abap +SELECT comp1, comp2, comp3 + FROM dbtab AS tab1 + WHERE EXISTS + ( SELECT comp1 FROM dbtab2 + WHERE comp1 = tab1~comp1 AND comp2 = tab1~comp2 ) + INTO ... +``` + +**Combining data of multiple database tables ...** + +**... using an inner join**. In this kind of join, columns with rows of the left-hand side and those of the right-hand side are only joined if the rows meet join conditions (`ON ...`). If there are no equivalent entries in the first or second table, the rows are not joined. + +If the same column name appears in multiple data sources of a single +join expression, these sources must be identified in all other additions +of the `SELECT` statement using the [column +selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentable_comp_selector_glosry.htm "Glossary Entry") +`~`. +``` abap +SELECT a~comp1, a~comp2, b~comp3, c~comp4 + FROM dbtab1 AS a + INNER JOIN dbtab2 AS b + ON a~comp1 = b~comp1 AND a~comp2 = b~comp2 + INNER JOIN dbtab3 AS c + ON a~comp1 = c~comp1 + WHERE ... + INTO ... +``` + +**... using a left outer join**. The columns of each row on the right-hand side that do not meet the `ON` condition are filled with initial values and linked with the columns of the left-hand side. If the conditions of the `WHERE` clause are met, each row on the left-hand side of the left outer join produces at least one row in the selection, irrespective of the `ON` condition. +``` abap +SELECT a~comp1, a~comp2, b~comp3, + FROM dbtab1 AS a + LEFT OUTER JOIN dbtab2 AS b + ON a~comp1 = b~comp1 + WHERE ... + INTO ... +``` + +**... using a union**. The columns of the result set keep the names defined in the statement on the left of `UNION`. The result set of rows of the `SELECT` statement on the right of `UNION` are inserted into the results set of the `SELECT` statement on the left of `UNION`. +``` abap +SELECT FROM dbtab1 + FIELDS ... + WHERE ... +UNION + SELECT FROM dbtab2 + FIELDS ... + WHERE ... + INTO ... +``` +> **💡 Note**
+> There are more join variants available. See the ABAP +Keyword Documentation on +[joins](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapselect_join.htm) +for more information. + + +#### Excursion: Using Common Table Expressions (CTE) + +When used: + +- Whenever you need intermediate results in a `SELECT` + statement and especially if you need them more than once. +- You get the option of selecting directly from a subquery [SELECT + FROM subquery], which is not possible in ABAP SQL. + +How it works: + +- The ABAP SQL keyword + [`WITH`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwith.htm) + introduces the definition of CTEs. +- Each CTE creates a tabular result set in a + [subquery](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubquery_glosry.htm "Glossary Entry"). +- The result set of such a CTE can then be used in subsequent queries + as data source; CTEs can be considered as temporary views, which + only exist for the duration of the database access. +- The CTEs (at least one) are then used in a final [main + query](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmainquery_glosry.htm "Glossary Entry"), i. + e. a `SELECT` statement accesses the result of the + expressions. + +Setup of a statement with CTEs: + +- Introductory keyword `WITH` +- A comma-separated list with at least one definition of a CTE + - Each CTE has a unique name with an initial `+` character + - An optional list of column names, which should be used in the + result set, within parentheses + - `AS` followed by a subquery with `SELECT` which + creates the tabular result set of the CTE +- A closing main query with `SELECT` in which the previous + CTEs are to be used as data source +- If a `SELECT` loop is opened and data is written into a work + area in the closing main query, the loop must be closed with + `ENDWITH.` (which fulfills the same task as + `ENDSELECT.`). + +> **💡 Note**
+>- Each CTE must be used at least once, either in another CTE or in the + main query. The main query must access at least one CTE. +>- The result set of a CTE never has a [client + column](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclient_column_glosry.htm "Glossary Entry"). +>- See more information in [this topic](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwith.htm) +and further options and additions when using CTEs in the subtopics. + +Example: The result sets of both common table expressions +`+connections` and `+sum_seats` are merged in the +subquery of the CTE `+result` in a join expression. An explicit +name list assigns names to the resulting columns. These names are used +in the main query to sort the results. For each flight connection of the +selected airline, the total number of occupied seats is stored in the +internal table. +``` abap +WITH ++connections AS ( + SELECT zdemo_abap_flsch~carrid, carrname, connid, cityfrom, cityto + FROM zdemo_abap_flsch + INNER JOIN zdemo_abap_carr + ON zdemo_abap_carr~carrid = zdemo_abap_flsch~carrid + WHERE zdemo_abap_flsch~carrid BETWEEN 'AA' AND 'JL' ), ++sum_seats AS ( + SELECT carrid, connid, SUM( seatsocc ) AS sum_seats + FROM zdemo_abap_fli + WHERE carrid BETWEEN 'AA' AND 'JL' + GROUP BY carrid, connid ), ++result( name, connection, departure, arrival, occupied ) AS ( + SELECT carrname, c~connid, cityfrom, cityto, sum_seats + FROM +connections AS c + INNER JOIN +sum_seats AS s + ON c~carrid = s~carrid AND + c~connid = s~connid ) +SELECT * + FROM +result + ORDER BY name, connection + INTO TABLE @DATA(result). +``` + + + + +## Changing Data in Database Tables + +### Using INSERT + +Using the ABAP SQL statement +[`INSERT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinsert_dbtab.htm), +you can insert one or more rows into a database table (or a [DDIC table +view](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abentable_view_glosry.htm "Glossary Entry")). +As mentioned above, structures and internal tables from which to insert +content should be specified as host variables (with `@`) or host +expressions (with `@( ... )`) depending on your ABAP release +and strict syntax enforcement. The examples below all use the preceding +`@`. The system fields `sy-subrc` (0 = single row or all +rows inserted successfully, 4 = row not or not all rows inserted) and +`sy-dbcnt` (number of rows that are inserted) are set. + +``` abap +"Inserting a single row into a database table + +INSERT dbtab FROM @row. +INSERT INTO dbtab VALUES @row. "Alternative syntax, same effect + +"Line is created inline using the VALUE operator as part of a host expression + +INSERT dbtab FROM @( VALUE #( comp1 = ... comp2 = ... ) ). + +"Inserting multiple lines from an internal table into a database table. +"Make sure that the internal table does not contain a line having the same key +"as an existing row in the database table. Otherwise, a runtime error occurs. + +INSERT dbtab FROM TABLE @itab. + +"Inserting lines from a table declared inline using the VALUE operator +"as part of a host expression + +INSERT dbtab FROM TABLE @( VALUE #( ( comp1 = ... comp2 = ... ) + ( comp1 = ... comp2 = ... ) ) ). + +"ACCEPTING DUPLICATE KEYS addition: To avoid the runtime error mentioned above, +"all lines that would produce duplicate entries in the database table +"regarding the keys are discarded and sy-subrc is set to 4. + +INSERT dbtab FROM TABLE @itab ACCEPTING DUPLICATE KEYS. + +"Inserting the result set of an embedded subquery +"Here, multiple result sets can be joined, e. g. using UNION. + +INSERT dbtab FROM ( SELECT ... ). +``` + + + +### Using UPDATE + +Using the ABAP SQL statement +[`UPDATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapupdate.htm), +you can update one or more rows in a database table. Similar to +`INSERT`, `sy-subrc` and `sy-dbcnt` are set. +After `FROM`, you can specify a structure or an internal table +as host variable (with `@`) or a host expression (with `@( ... )`). + + +``` abap +"Changing content by overwriting entire rows based on a work area + +UPDATE dbtab FROM @row. +UPDATE dbtab FROM @( VALUE #( comp1 = ... comp2 = ... ) ). "Using a host expression + +"Changing content by overwriting entire rows based on rows in an internal table + +UPDATE dbtab FROM TABLE @itab. + +"Using a host expression + +UPDATE dbtab FROM TABLE @( VALUE #( ( comp1 = ... comp2 = ... ) + ( comp1 = ... comp2 = ... ) ) ). + +"INDICATORS addition: Changing content of specific fields without overwriting +"existing values of other fields +"Example: +"- Structured type is created with WITH INDICATORS addition +"- Internal table from which to update dbtab is created; +" it includes the indicator structure comp_ind +"- Internal table is filled; only one component is flagged as to be updated +"- Other fields remain unchanged; note that key fields must be included +" in ind_tab (indicator setting for key fields has no effect) + +TYPES ind_wa TYPE dbtab WITH INDICATORS comp_ind TYPE abap_bool. + +DATA ind_tab TYPE TABLE OF ind_wa. + +ind_tab = VALUE #( + ( comp1 = ... comp2 = ... comp_ind-comp2 = abap_true ) + ( comp1 = ... comp2 = ... comp_ind-comp2 = abap_true ) ). + +UPDATE dbtab FROM TABLE @ind_tab + INDICATORS SET STRUCTURE comp_ind. + +"Reverses the logic + +UPDATE dbtab FROM TABLE @ind_tab + INDICATORS NOT SET STRUCTURE comp_ind. + +"SET addition: Changing values of specific fields in all table rows +"There are mutliple options for the value assignment. E. g. you can use +"a literal, host variable/expression, SQL function, and so on. + +UPDATE dbtab SET comp2 = ... . +``` + + + +### Using MODIFY + +Using the ABAP SQL statement +[`MODIFY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_dbtab.htm), +you can insert one or more rows in a database table or overwrite +existing ones. Similar to the statements above, `sy-subrc` and +`sy-dbcnt` are set. After `FROM`, you can specify a +structure or an internal table as host variable (with `@`) or a +host expression (with `@( ... )`). + +``` abap +"Inserting a single row into a database table or changing an existing row + +MODIFY dbtab FROM @row. + +"Using a host expression + +MODIFY dbtab FROM @( VALUE #( comp1 = ... comp2 = ... ) ). + +"Inserting/Changing multiple rows + +MODIFY dbtab FROM TABLE @itab. + +"Using a host expression + +MODIFY dbtab FROM TABLE @( VALUE #( ( comp1 = ... comp2 = ... ) + ( comp1 = ... comp2 = ... ) ) ). + +"Inserting/Changing multiple rows based on a result set of an embedded subquery + +MODIFY dbtab FROM ( SELECT ... ). +``` + + + +### Using DELETE + +Using the ABAP SQL statement +[`DELETE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdelete_dbtab.htm), +you can delete one or more rows in a database table. Similar to the +statements above, `sy-subrc` and `sy-dbcnt` are set. + +``` abap +"Variant DELETE FROM ...: Either all rows are deleted or restricted + +"All rows are deleted + +DELETE FROM dbtab. + +"Rows are deleted based on a condition + +DELETE FROM dbtab WHERE .... + +"Note that there are further options available, e. g. ORDER BY, UP TO +"Variant DELETE ... FROM ...: Deleting a single row or multiple row + +DELETE dbtab FROM @row. + +"Using a host expression + +DELETE dbtab FROM @( VALUE #( comp1 = ... ) ). + +DELETE dbtab FROM TABLE @itab. + +"Using a host expression + +DELETE dbtab FROM TABLE @( VALUE #( ( comp1 = ... ) + ( comp1 = ... ) ) ). +``` + + + +## Further Information +Find more information on the topics covered here or not (e. g. topics like [table buffering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensap_puffering.htm)) in the respective sections in the ABAP Keyword Documentation. + + +## Executable Example +[zcl_demo_abap_sql](./src/zcl_demo_abap_sql.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/04_ABAP_Object_Orientation.md b/04_ABAP_Object_Orientation.md new file mode 100644 index 0000000..d5cb13a --- /dev/null +++ b/04_ABAP_Object_Orientation.md @@ -0,0 +1,1213 @@ + + +# ABAP Object Orientation + +> **💡 Note**
+> This cheat sheet provides an overview on selected syntax options and concepts related to ABAP object orientation. It is supported by code snippets and an executable example. They are **not** suitable as role models for object-oriented design. Their primary focus is on the syntax and functionality. For more details, refer to the respective topics in the ABAP Keyword Documentation. Find an overview in the topic [ABAP Objects - Overview](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_objects_oview.htm). + +- [ABAP Object Orientation](#abap-object-orientation) + - [Classes and Objects](#classes-and-objects) + - [Creating Classes](#creating-classes) + - [Creating a Local Class](#creating-a-local-class) + - [Creating a Global Class](#creating-a-global-class) + - [Visibility of Components](#visibility-of-components) + - [Creating the Visibility Sections](#creating-the-visibility-sections) + - [Defining Components](#defining-components) + - [Working with Objects and Components](#working-with-objects-and-components) + - [Notes on Inheritance](#notes-on-inheritance) + - [Notes on Polymorphism and Casting](#notes-on-polymorphism-and-casting) + - [Working with Interfaces](#working-with-interfaces) + - [Further Concepts](#further-concepts) + - [Factory Methods](#factory-methods) + - [Friendship](#friendship) + - [Events](#events) + - [Executable Example](#executable-example) + +## Classes and Objects + +Object-oriented programming in ABAP means dealing with +[classes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_glosry.htm "Glossary Entry") +and +[objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_glosry.htm "Glossary Entry"). + +Objects ... + +- are + [instances](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstance_glosry.htm "Glossary Entry") + of a + [type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentype_glosry.htm "Glossary Entry"). + In this context, they are instances of a + [class](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_glosry.htm "Glossary Entry"). + The terms object and instance are used synonymously. +- exist in the [internal + session](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninternal_session_glosry.htm "Glossary Entry") + of an [ABAP + program](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_program_glosry.htm "Glossary Entry") + + +Classes ... +- are templates for objects, i. e. they determine the appearance of + all instances of a class. All instances are created based on this + template (this is what is called + [instantiation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstantiation_glosry.htm "Glossary Entry")). + - If, for example, a vehicle represents a class, then the + instances of the class `vehicle` have the same setup. + That means they all share the same kind of data like the brand, + model and color or the same functionality like the acceleration. + However, the values are different from instance to instance. + Hence, an instance has a unique identity. For example, one + instance is a red sedan of brand A having a certain + acceleration; another instance is a black SUV of brand B and so + on. You create an object (or instance respectively) that stands + for an actual vehicle to work with in your ABAP program. + - Basically, you might create any number of objects that are based + on a class. +- contain + [components](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_glosry.htm "Glossary Entry"): + - [Attributes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenattribute_glosry.htm "Glossary Entry") + of the objects (the data declarations) + - [Methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmethod_glosry.htm "Glossary Entry") + that typically operate on this data + - [Events](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenevent_glosry.htm "Glossary Entry") + + + +### Creating Classes + +You can either create local or global classes: + +
| Local classes | +
|
+
| Global +classes | +
|
+
+> - Regarding the names of global and local classes and usage of classes in ABAP programs when, for example, calling methods, the system searches for a local class with the specific name at first. Then, if a local class with that name is not found, the systems searches for a global class. +> - The class design must be done with care. If a class is only used in one program (or class), choosing a local class is enough. However, global +classes must be prepared to be used anywhere. A later change of that class, especially regarding the visibility of components (see +further down) or the data types of attributes that are used in other programs might cause problems. +> - Apart from ADT, global classes can also be created in the ABAP Workbench (`SE80`) or with transaction `SE24` in on-premise systems. + +The basic structure of classes consists of a declaration and an implementation part that are both introduced by `CLASS` and ended by `ENDCLASS`. + +#### Creating a Local Class + +``` abap +CLASS local_class DEFINITION. + + "Here go the declaration for all components and visibility sections. + "You should place the declaration at the beginning of the program. + +ENDCLASS. + +CLASS local_class IMPLEMENTATION. + + "Here go the method implementations. + "Only required if you declare methods in the DEFINITION part. + +ENDCLASS. +``` + +#### Creating a Global Class +The code snippet shows a basic skeleton of a global class. There are [further +additions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclass_options.htm) +possible. + +``` abap +CLASS global_class DEFINITION + PUBLIC "Makes the class a global class in the class library. + FINAL "Means that no subclasses can be derived from this class. + CREATE PUBLIC. "This class can be instantiated anywhere it is visible. + + ... + + "Here go the declaration for all components and visibility sections. + +ENDCLASS. + +CLASS global_class IMPLEMENTATION. + + "Here go the method implementations. + "Only required if you declare methods in the DEFINITION part. + +ENDCLASS. +``` +> **💡 Note**
+> The addition `... CREATE PROTECTED.` of the class declaration part means that the class can only be instantiated in methods of its +[subclasses](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubclass_glosry.htm "Glossary Entry"), +of the class itself, and of its +[friends](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfriend_glosry.htm "Glossary Entry"). +The addition `... CREATE PRIVATE` means that the class can only +be instantiated in methods of the class itself or of its friends. Hence, +it cannot be instantiated as an inherited component of subclasses. + + + +### Visibility of Components + +In the class declaration part, you must specify (at least one of the) +[visibility +sections](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenvisibility_section_glosry.htm "Glossary Entry") +to determine how to interact with the class. For example, you want to +hide and thus disallow the usage of certain data. The visibility +sections are as follows: + +
PUBLIC. |
+ Components declared in this section can be accessed from within the class and from outside including subclasses. | +
PROTECTED. |
+ Components declared in this section can be + accessed from within the class and from subclasses and friends + - topics related to inheritance. | +
PRIVATE. |
+ Components declared in this section can only be accessed from within the class in which they are declared and its friends. | +
+> You can declare static attributes that should not be +changed using +[`CONSTANTS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapconstants.htm) +statements. You specify the values for the constants when you declare +them. Furthermore, the addition +[`READ-ONLY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata_options&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ADDITION_2@2@&tree=X) +can be used in the public visibility section as a means of securing data +objects against undesired changes from outside. A change is only +possible via the methods of the class or it subclasses. + +Declaring attributes in visibility sections. In the snippet below, all attributes are declared in the `PUBLIC.` section of a local class. +``` abap +CLASS local_class DEFINITION. + + PUBLIC. + TYPES: some_type TYPE c LENGTH 3. "Type declaration + + DATA: inst_number TYPE i, "Instance attributes + inst_string TYPE string, + dobj_r_only TYPE c LENGTH 5 READ-ONLY. "Read-only attribute + + CLASS-DATA: stat_number TYPE i, "Static attributes + stat_char TYPE c LENGTH 3. + + CONSTANTS: const_num TYPE i VALUE 123. "Non-changeable constant + + PROTECTED. + "Here go more attributes. + + PRIVATE. + "Here go more attributes. + +ENDCLASS. + +CLASS local_class IMPLEMENTATION. + + "Here go all method implementations. + +ENDCLASS. +``` + + + +**Methods** + +- Are internal + [procedures](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenprocedure_glosry.htm "Glossary Entry") + determining the behavior of the class. +- Can access all of the attributes of a class and, if not defined + otherwise, change their content. +- Have a [parameter + interface](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenparameter_interface_glosry.htm "Glossary Entry") + (also known as + [signature](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensignature_glosry.htm "Glossary Entry")) + with which methods can get values when being called and pass values + back to the caller. +- [Static + methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstatic_method_glosry.htm "Glossary Entry") + can only access static attributes of a class and trigger static + events. You declare them using `CLASS-METHODS` statements in + a visibility section. +- [Instance + methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstance_method_glosry.htm "Glossary Entry") + can access all of the attributes of a class and trigger all events. + You declare them using `CLASS` statements in a visibility + section. Since instance methods are bound to instances, an instance + of the class must first be created before using them. + +**Parameter Interface** + +In the simplest form, methods can have no parameter at all. Apart from that, methods can be defined with the following parameters: + +| Addition | Details | +|---|---| +|`IMPORTING`|Defines one or multiple parameters that are imported (or input) by the method (e. g. from another object or an ABAP program) with which the method can work. | +|`EXPORTING`|Defines one or multiple parameters that are exported (or output) by the method (e. g. to another object or an ABAP program). | +|`CHANGING`|Defines one or multiple parameters that can be both imported and exported. | +|`RETURNING`|Only one `RETURNING` parameter can be defined for methods. These methods are called functional methods. Like `EXPORTING` parameters, `RETURNING` parameters pass back values (note that the formal parameters of returning parameters must be passed by value), i. e. they are output parameters. The difference is that there can be multiple `EXPORTING` parameters in a method. However, `RETURNING` parameters simplify the syntax if there is only one value to be passed back. It shortens the method call and enables method chaining. Furthermore, functional methods can, for example, be used in arithmetic or logical expressions. In case of standalone method calls, the returned value can be accessed using the addition `RECEIVING`. | +|`RAISING` | Used to declare the class-based exceptions to handle errors. | + + +> **💡 Note**
+> - You may find the addition `EXCEPTIONS` especially in definitions of older classes. They are for non-class-based exceptions. The exceptions are based on the system field `sy-subrc` and raised according to setting this field. You can then check the value of `sy-subrc` and act accordingly. This addition should not be used in ABAP for Cloud Development. +> - [Formal + parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenformal_parameter_glosry.htm "Glossary Entry") + versus [actual + parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenactual_parameter_glosry.htm "Glossary Entry"): + You define method parameters by specifying a name with a type which + can be a + [generic](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abengeneric_data_type_glosry.htm "Glossary Entry") + or + [complete](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomplete_data_type_glosry.htm "Glossary Entry") + type. This formal parameter includes the specification of how the + value passing should happen. Parameters can be [passed by + reference](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpass_by_reference_glosry.htm "Glossary Entry") + (`... REFERENCE(param) ...`; note that just specifying the + parameter name `... param ...` - as a shorter syntax - + means passing by reference by default) or [by + value](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpass_by_value_glosry.htm "Glossary Entry") + (`... VALUE(param) ...`). The actual parameter represents + the data object whose content is passed to or copied from a formal + parameter as an argument when a procedure is called. If + pass-by-reference is used, a local data object is not created for + the actual parameter. Instead, the procedure is given a + [reference](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_glosry.htm "Glossary Entry") + to the actual parameter during the call and works with the actual + parameter itself. Note that parameters that are input and passed by + reference cannot be modified in the procedure. However, the use of a + reference is beneficial regarding the performance compared to + creating a local data object. +>- Parameters can be defined as optional using the + [`OPTIONAL`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_parameters&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ONE_ADD@1@&tree=X) + addition. In doing so, it is not mandatory to pass an actual + parameter. The + [`DEFAULT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_parameters&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ONE_ADD@1@&tree=X) + addition also makes the passing of an actual parameter optional. + However, when using this addition, as the name implies, a default + value is set. + + + +**Constructors** + +- [Constructors](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_glosry.htm "Glossary Entry") + are special methods that are usually used for setting a defined + initial state of objects, e. g. for setting a particular starting + value for attributes in an object. +- A class can only have one [instance + constructor](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstance_constructor_glosry.htm "Glossary Entry") + and one [static + constructor](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstatic_constructor_glosry.htm "Glossary Entry"). +- Constructors always exist implicitly in classes. However, their + declaration and use is optional. If they are declared explicitly, + they must consequently be implemented. Note that they are always + called automatically even if not declared and implemented. +- Static constructor: Automatically called when calling a class for + the first time in an internal session. This constructor is declared + using the predefined name `class_constructor` as part of a + `CLASS-METHODS` statement in the public visibility section. + Static constructors cannot have any parameters. +- Instance constructor: Automatically called when a class is + instantiated and an object is created. The constructor is declared + using the predefined name `constructor` as part of a + `METHODS` statement. In contrast to local classes, instance + constructors must be declared in the public visibility section of + global classes. They can only have `IMPORTING` parameters + and exceptions. In case of exceptions, make sure that you use a + [`TRY ... ENDTRY.`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptry.htm) + block in the implementation since otherwise the instance is not + created if uncaught errors occur. + +Example for method definitions: The following snippet shows +multiple method definitions in the public section. Most of the formal +parameters of the demo methods below are defined by just using the +parameter name. This means passing by reference (returning parameters +require to be passed by value). +``` abap +CLASS local_class DEFINITION. + PUBLIC. + METHODS: inst_meth1 IMPORTING a TYPE i "instance methods + EXPORTING b TYPE i, + + inst_meth2 IMPORTING c TYPE string + + inst_meth2 IMPORTING d TYPE string + RETURNING VALUE(e) TYPE string, + + inst_meth3 IMPORTING f TYPE i + EXPORTING g TYPE i + CHANGING h TYPE string_table + RETURNING VALUE(i) TYPE i + RAISING cx_sy_zerodivide, + + constructor IMPORTING j TYPE i. "instance constructor with importing parameter + + CLASS-METHODS: stat_meth1 IMPORTING k TYPE i "static methods + EXPORTING l TYPE i, + stat_meth2, "no formal parameters + class_constructor, "static constructor + + "Formal parameter definitions + stat_meth3 IMPORTING VALUE(m) TYPE i "pass by value + REFERENCE(n) TYPE i "pass by reference + o TYPE i, "same as n + + "OPTIONAL/DEFAULT additions + stat_meth4 IMPORTING p TYPE i DEFAULT 123 + q TYPE i OPTIONAL. + +ENDCLASS. + +CLASS local_class IMPLEMENTATION. + METHOD inst_meth1. + ... "Here goes the method implementation. + ENDMETHOD. + + ... "Note that all declared methods must be implemented. +ENDCLASS. +``` + + + +## Working with Objects and Components + +**Declaring reference variables**: To create an object, a +[reference +variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_variable_glosry.htm "Glossary Entry") +must be declared. Such an [object reference +variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_refer_variable_glosry.htm "Glossary Entry") +is also necessary for accessing objects and their components, i. e. +objects are not directly accessed but only via references that point to +those objects. This reference is stored in the reference variables. +``` abap +DATA: ref1 TYPE REF TO local_class, + ref2 TYPE REF TO global_class, + ref3 LIKE ref1. +``` + +**Creating objects**: You create an object by using the instance +operator +[`NEW`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_new.htm). +In doing so, a new instance of a class is created and the reference to +it is assigned to an object reference variable. The `#` sign +means that the type (`TYPE REF TO ...`) can be derived from the +context (in this case from the type of the reference variable). You can +also omit the explicit declaration of a reference variable by declaring +a new reference variable +[inline](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_inline.htm), +for example, using `DATA`. In this case, the name of the class +must be placed after `NEW` and before the first parenthesis. The `NEW` operator replaces the older +[`CREATE OBJECT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcreate_object.htm) +statements. +``` abap +ref1 = NEW #( ). "Type derived from already declared ref1 + +DATA(ref2) = NEW local_class( ). "Reference variable declared inline, explicit type + "(class) specification + +"Old syntax. Do not use. +"CREATE OBJECT ref3. "Type derived from already declared ref3 +``` + +**Assigning or copying reference variables**: To assign or copy +reference variables, use the [assignment +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenassignment_operator_glosry.htm "Glossary Entry") +`=`. In the example below, both reference variables have the same +type. + +``` abap +DATA: ref1 TYPE REF TO local_class, + ref2 TYPE REF TO local_class. + +ref1 = NEW #( ). +ref2 = ref1. +``` + +**Overwriting reference variables**: An [object +reference](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_reference_glosry.htm "Glossary Entry") +is overwritten when a new object is created with a reference variable +already pointing to an instance. +``` abap +ref1 = NEW #( ). +ref1 = NEW #( ). +``` + +**Keeping object references in internal tables**: If your use case is to retain the object references, for example, if you create a series of objects and you want to prevent object references to be overwritten when using the same reference variable, you can put the reference variables in internal tables. The following code shows that three objects are created with the same reference variable. The internal table includes all object references and, thus, their values are retained. +``` abap +DATA: ref TYPE REF TO local_class, + itab TYPE TABLE OF REF TO local_class. + +DO 3 TIMES. + ref = NEW #( ). + itab = VALUE #( BASE itab ( ref ) ). "Adding the reference to itab +ENDDO. +``` +**Clearing object references**: Use +[`CLEAR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclear.htm) +statements to explicitly clear a reference variable. +``` +CLEAR ref. +``` +> **💡 Note**
+> Since objects use up space in the memory, they should be +cleared if they are no longer needed. The [garbage +collector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abengarbage_collector_glosry.htm "Glossary Entry") +takes over this task automatically, i. e. all objects without any +reference are cleared and the memory space is released. + +**Accessing attributes**: Instance attributes are accessed using +the [object component +selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_component_select_glosry.htm "Glossary Entry") +`->` via a reference variable. Visible static attributes are +accessed using the [class component +selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_component_select_glosry.htm "Glossary Entry") +`=>` via the class name. You can also declare data objects and +types by referring to the static attributes. +``` abap +"Accessing instance attribute via a reference variable + +... ref->some_attribute ... + +"Accessing static attributes via the class name + +... local_class=>static_attribute ... + +"Without the class name only within the class +... static_attribute ... + +"Type and data object declarations + +TYPES some_type LIKE local_class=>some_attribute. +DATA dobj1 TYPE local_class=>some_type. +DATA dobj2 LIKE local_class=>some_attribute. +``` + +**Calling methods**: Similar to accessing attributes, instance +methods are called using `->` via a reference variable. Static +methods are called using `=>` via the class name. When used +within the class in which it is declared, the static method can also be +called without `class_name=>...`. You might also see method +calls with [`CALL METHOD`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcall_method_static.htm) +statements which are not used here (however, these statements are the +only option in the context of dynamic programming. +When methods are called, the parameters must be specified within the +parentheses. + + +Examples for instance method calls and static method calls: +``` abap +"Calling instance methods via reference variable + +ref->inst_meth( ... ). + +"Calling static methods via/without the class name + +class_name=>stat_meth( ... ). + +"Only within the program in which it is declared. +stat_meth( ... ). + +"Calling (static) methdod having no parameter + +class_name=>stat_meth( ). + +"Calling (static) methods having a single importing parameter: + +"Note that in the method call, the caller exports values to the +"method having importing parameters defined; hence, the ABAP word +"EXPORTING is relevant. The three following method calls are the same + +"Explicit use of EXPORTING. +class_name=>meth( EXPORTING a = b ). + +"Only importing parameters in the signature: explicit EXPORTING not needed + +class_name=>meth( a = b ). + +"Only a single value must be passed: parameter name (a) and EXPORTING not needed + +stat_meth( b ). + +"Calling (static) methods having importing/exporting parameters +"Parameters must be specified if they are not marked as optional + +class_name=>meth( EXPORTING a = b c = d "a/c: importing parameters + IMPORTING e = f ). "e: exporting parameter + +"If f is not yet available, you could also declare it inline. + +class_name=>meth( EXPORTING a = b c = d + IMPORTING e = DATA(f) ). "f receives type of e + +"Calling (static) methods having a changing parameter; +"should be reserved for changing an existing local variable and value + +DATA h TYPE i VALUE 123. +class_name=>meth( CHANGING g = h ). + +"Calling (static) methods having a returning parameter. +"Basically, they do the same as methods with exporting parameters +"but they are way more versatile and you save lines of code. + +"They do not need temporary variables. +"In the example, the return value is stored in a variable declared inline. + +"i and k are importing parameters +DATA(result) = class_name=>meth( i = j k = l ) + +"They can be used with other statements, e. g. logical expressions. +IF class_name=>meth( i = j k = l ) > 100. + ... +ENDIF. + +"They enable method chaining. +"The example shows a method to create random integer values. +"The methods have a returning parameter. + +DATA(random_no) = cl_abap_random_int=>create( )->get_next( ). + +"Receiving parameter: Available in methods defined with a returning parameter; +"used in standalone method calls only. +"In the snippet, m is the returning parameter; n stores the result. + +class_name=>meth( EXPORTING i = j k = l RECEIVING m = DATA(n) ). +``` + +**Self-Reference me** + +When implementing instance methods, you can make use of the implicitly available object reference variable `me` which is always available and points to the respective object itself. You can use it to refer to components of the instance of a particular class but it is not needed: +``` abap +... some_method( ... ) ... + +... me->some_method( ... ) ... +``` + +However, if you want to access attributes of the particular class and these attributes have identical names as local attributes within the method, you can make use of `me` to access the attributes that are outside of the method and within the class. The following example demonstrates the use of `me` in a method implementation. + +``` abap +METHOD me_ref. + + DATA str TYPE string VALUE `Local string`. + + DATA(local_string) = str. + + "Assuming there is a variable str declared in the class declaration part. + DATA(other_string) = me->str. + +ENDMETHOD. +``` + + + +## Notes on Inheritance + +- Concept: Deriving a new class (i. e. a + [subclass](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubclass_glosry.htm "Glossary Entry")) + from an existing one + ([superclass](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensuperclass_glosry.htm "Glossary Entry")) + to share common components between classes. In doing so, you create + hierarchies of classes (an [inheritance + tree](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninheritance_tree_glosry.htm "Glossary Entry")) + while a superclass includes components that are shared by all + subclasses to provide a better structure for your code. +- Subclasses ... + - inherit all components from superclasses + - can access instance components from superclasses + - can be made more specific by declaring new components and + redefining instance methods (i. e. replacing the implementations + of inherited methods). + - can access static components but not redefine them. + - can only handle components in the `PROTECTED` and + `PUBLIC` section of superclasses. + - know their direct superclass but they do not know which classes + inherit from them. [Note:] Handle component definitions + and implementations in the superclass with great care since a + change might have undesired consequences for the subclasses. +- Components ... + - that are changed and added to subclasses are not visible to + superclasses, hence, these changes are only relevant for this + class itself and its subclasses. + - that are added should have a different name than those of the + superclass. +- A class ... + - can only inherit from one superclass, i. e. a subclass can only + have one superclass, however, a superclass can have any number + of subclasses. + - must enable derivation, i. e. classes cannot inherit from + classes that are specified with the addition + [`FINAL`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclass_options&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ADDITION_4@4@&tree=X) + (e. g. `CLASS global_class DEFINITION PUBLIC FINAL CREATE PUBLIC. ...`). + + + +**Excursion: `ABSTRACT` and `FINAL`** +- A global class declared with the addition `FINAL` rules out + inheritance. The addition `FINAL` is also available for + [method + declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_abstract_final&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ADDITION_2@2@&tree=X) + in classes which rules out that such a method is redefined in + subclasses. In classes that are declared with `FINAL`, all + methods are implicitly final. Instance constructors are always final + by default. +- The addition + [`ABSTRACT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_abstract_final.htm) + is meant for abstract classes. +- The addition `ABSTRACT` enters the picture in the context of + abstract classes. These classes are used if you want to have a + template for subclasses and you do not need instances of such + classes. Instances are only possible for their subclasses. Instance + components of an abstract class can then be accessed via an + instantiated subclass. `ABSTRACT` is available for [class + declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclass_options&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ADDITION_3@3@&tree=X) + (e. g. `CLASS cl DEFINITION ABSTRACT. ...`) and [method + declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_abstract_final&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ADDITION_1@1@&tree=X) + (e. g. `METHODS meth ABSTRACT. ...`). Abstract methods can + only be declared within abstract classes. They are not implemented + in the implementation part of the abstract class. Instead, they must + be redefined in subclasses. Note that in abstract classes, + non-abstract methods can also be declared and that private methods + cannot be redefined, i. e. methods in this section cannot be + declared as abstract. See a high-level comparison of abstract + classes and interfaces further down. + + + +**Redefining Methods** + +- The non-final method from the superclass that is redefined must be + specified in the declaration part of the subclass as follows: + `METHODS meth REDEFINITION.` + + It must be specified with the same method name and in the same + visibility section as in the superclass. Specifying or changing the + signature is not possible. + +- If you want to access the original method in the superclass within + the method implementation of the subclass, use the [pseudo + reference](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpseudo_reference_glosry.htm "Glossary Entry") + `super->...`. + +> **💡 Note**
+> If the instance constructor is implemented in a subclass, the instance constructor of the superclass must be called explicitly using `super->constructor`, even if the latter is not explicitly declared. An exception to this: Direct subclasses of the root node object. + + + +## Notes on Polymorphism and Casting + +The object orientation concept +[polymorphism](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpolymorphism_glosry.htm "Glossary Entry") +means accessing different methods in different objects and with +different behavior via the same interface, i. e. you can use one and the +same reference variable to access various objects, for example, +references to a superclass can point to objects of a subclass. + +Note the concept of static and dynamic type in this context: + +- Object reference variables (and also interface reference variables + as outlined further down) have both a + [static](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstatic_type_glosry.htm "Glossary Entry") + and a [dynamic + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendynamic_type_glosry.htm "Glossary Entry"). +- When declaring an object reference variable, e. g. `DATA oref TYPE + REF TO cl`, you determine the static type, i. e. + `cl` is used to declare the reference variable that is + statically defined in your program. The dynamic type is determined + at runtime of the program and is the class of an object. Especially + in the context of assigning object or interface references (and also + [data + references](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_reference_glosry.htm "Glossary Entry")), + this differentiation enters the picture. +- The following basic rule applies: The assignment of an object or + interface reference variable to another one is possible if the + static type of the target reference variable is more general than or + the same as the dynamic type of the source reference variable. +- If it can be statically checked that an assignment is possible + although the types are different, the assignment is done using the + [assignment + operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenassignment_operator_glosry.htm "Glossary Entry") + `=` that triggers an + [upcast](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenup_cast_glosry.htm "Glossary Entry") + automatically. +- Otherwise, it is a + [downcast](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendown_cast_glosry.htm "Glossary Entry"). + Here, the assignability is not checked until runtime. The downcast + must be triggered explicitly using [casting + operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencasting_operator_glosry.htm "Glossary Entry"), + either with the [constructor + operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_operator_glosry.htm "Glossary Entry") + [`CAST`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_cast.htm) + or the older + [`?=`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_cast.htm), + for the assignment of object or interface reference variables. +- See more information in the topic [Assignment Rules for Reference + Variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_references.htm). + +> **✔️ Hints**
+> - If the static type is a class, the dynamic type must be the same class or one of its subclasses. +> - If the static type is an interface, the dynamic type must implement the interface. + +As an example, assume there is an inheritance tree with `lcl_super` as the superclass and `lcl_sub` as a direct subclass. `lcl_sub2` is a direct subclass of `lcl_sub`. + +In the following code snippet, the rule is met since the superclass is either the same as or more generic than the subclass (the subclass has, for example, redefined methods and is, thus, more specific). Hence, the assignment of an object reference variable pointing to the subclass to a variable pointing to a superclass works. An upcast is triggered. After this casting, the type of `oref_super` has changed and the methods of `lcl_sub` can be accessed via `oref_super`. + +``` abap +oref_super = NEW lcl_super( ). + +oref_sub = NEW lcl_sub( ). + +"Upcast +oref_super = oref_sub. + +"The casting might be done when creating the object. +DATA super_ref TYPE REF TO lcl_super. + +super_ref = NEW lcl_sub( ). +``` + +Such upcasts frequently occur if you want to access objects via an +object reference variable pointing to the superclass. However, there +might also be situations when you want to do the assignment the other +way round, i. e. going from specific to more generic. In this case, a +more generic reference variable is assigned to a specific variable which +can be depicted as moving downwards in the inheritance tree concerning +the assignment. As mentioned above, a downcast must be triggered +manually. Just an assignment like `oref_sub = oref_super.` +does not work. A syntax error occurs saying the right-hand variable's +type cannot be converted to the left-hand variable's type. + +If you indeed want to carry out this casting, you must use +`CAST` or `?=` to overcome this syntax error (but just +the syntax error!). Note: You might also use these two +operators for the upcasts. That means, `oref_super = +oref_sub.` has the same effect as `oref_super = CAST #( +oref_sub ).`. This syntax is usually not necessary. + +At runtime, the assignment is checked and if the conversion does not +work, you face a (catchable) runtime error. Even more so, the assignment +`oref_sub ?= oref_super.` does not throw a syntax error but it +does not work in this example either because it violates the rule +mentioned above (`oref_sub` is more specific than +`oref_super`). To check whether such an assignment is possible +on specific classes, you can use the predicate expression [`IS INSTANCE +OF`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_instance_of.htm) +or the case distinction [`CASE TYPE +OF`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcase_type.htm). +Carrying out an upcast before the downcast ensures that the left-hand +variable's type is compatible to the right-hand variable's type. + +``` abap +oref_super = NEW lcl_super( ). +oref_sub = NEW lcl_sub( ). +oref_sub2 = NEW lcl_sub2( ). + +"Downcast resulting in an error; error is caught + +TRY. + oref_sub = CAST #( oref_super ). + CATCH CX_SY_MOVE_CAST_ERROR INTO DATA(e). + ... +ENDTRY. + +"Working downcast with a prior upcast + +oref_super = oref_sub2. + +"Due to the prior upcast, the following check is actually not necessary. + +IF oref_super IS INSTANCE OF lcl_sub. + oref_sub = CAST #( oref_super ). + ... +ENDIF. +``` + + + +## Working with Interfaces + +Interfaces ... + +- represent a template for the components in the public visibility + section of classes and thus enhance the components of classes by + adding components of interfaces. +- represent a means to deal with multiple inheritance in ABAP Object + Orientation. +- serve the concept of + [polymorphism](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpolymorphism_glosry.htm "Glossary Entry"). + Any number of classes can implement the same interface. +- are beneficial if you want to share and reuse common components + across classes especially if those classes are not in an inheritance + relationship. +- are possible as both + [local](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlocal_interface_glosry.htm "Glossary Entry") + and [global + interfaces](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenglobal_interface_glosry.htm "Glossary Entry"). +- are different from classes in the following ways: + - They only consist of a part declaring the components without an + implementation part. The classes using the interfaces are + responsible for the implementation. + - They do not include visibility sections. All interface + components are public. + - No instances can be created from interfaces. + - Declarations as mentioned for classes, e. g. `DATA`, + `CLASS-DATA`, `METHODS`, + `CLASS-METHODS`, are possible. Constructors are not + possible. + + + +**Defining Interfaces** + +> **💡 Note**
+> The addition `DEFINITION` is not relevant here since there is no implementation part. + +``` abap +INTERFACE intf. +"The addition PUBLIC is for global interfaces: +"INTERFACE intf_g PUBLIC. + + DATA ... + CLASS-DATA ... + METHODS ... + CLASS-METHODS ... + +ENDINTERFACE. +``` + + + +**Using Interfaces in Classes** + +- A class can implement multiple interfaces. +- As a prerequisite, the interfaces must be specified in the + declaration part of a class using the statement + [`INTERFACES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinterfaces.htm). +- Since all interface components are public, you must include this + statement and the interfaces in the public section of a class. +- In doing so, the interface components become part of the class + itself. Methods that are specified in interfaces must be implemented + in the class unless the methods are marked as optional in the + interface using the additions [`DEFAULT + IGNORE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_default.htm) + or [`DEFAULT FAIL`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_default.htm). + Furthermore, you can specify the addition [`ABSTRACT + METHODS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinterfaces_class.htm) + for the `INTERFACES` statement in the declaration part of + classes followed by method names. In this case, the class need not + implement the methods of the interface. The implementation is then + relevant for a subclass inheriting from a superclass that includes + such an interface declaration. Find more information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapinterfaces_class.htm). +- You can specify alias names for the interface components using the + statement [`ALIASES ... FOR + ...`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapaliases.htm). + The components can then be addressed using the alias name everywhere + (since the alias is public). + +Syntax for using interfaces in classes: +``` abap +CLASS class DEFINITION. + PUBLIC SECTION. + INTERFACES intf1. + INTERFACES intf2 ABSTRACT METHODS meth1. "No implementation required for meth1 + INTERFACES intf3 ALL METHODS ABSTRACT. "All methods abstract + + ALIASES meth_alias FOR intf1~some_method. +ENDCLASS. + +CLASS class IMPLEMENTATION. + METHOD intf1~some_meth. "Method implementation using the original name + ... + ENDMETHOD. + + "Just for demo purposes: Method implementation using the alias name + "METHOD meth_alias. + " ... + "ENDMETHOD. + + ... +ENDCLASS. +``` + + + +**Accessing Interface Components** + +- Interface components can be addressed using the [interface component + selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninterface_comp_selector_glosry.htm "Glossary Entry"): + `... intf~comp ...`. + - Note: Due to the unique interface name and the use of + the name as prefix (e. g. `intf~`) that is followed by + a component name, there is no problem regarding the component + naming within a class, i. e. the class can have components with + the same name, and other interfaces can have components with the + same name, too. +- You can then access them either using class references or interface + references: + - Class references: `... class_ref->intf~comp ...` + - Interface references: `... i_ref->comp ...`. In this + case, the [object component + selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_component_select_glosry.htm "Glossary Entry") + is used to access the components without the interface name. + +Before making use of interface references, an [interface reference +variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninterface_ref_variable_glosry.htm "Glossary Entry") +must be created: `DATA i_ref TYPE REF TO intf.` Interfaces +cannot be instantiated, i. e. an object cannot be created, however, +interface references can point to the objects of any class that includes +the interface so that interface components (and only them) can be +accessed via the variable. Accessing an object via an interface +reference variable is basically the same as accessing a subclass object +via a superclass reference variable. + + + +**Assigning Interface Reference Variables** + +As mentioned above, interface references can point to the objects of any +class that includes the interface. This is true when object references +are assigned to interface references. Here, as touched on before, the +concept of +[upcasting](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenup_cast_glosry.htm "Glossary Entry") +enters the picture. +``` abap +DATA i_ref TYPE REF TO intf. + +DATA cl_ref TYPE REF TO class. + +cl_ref = NEW #( ). + +"Upcast +i_ref = cl_ref. + +"Method call using the interface reference variable +i_ref->some_method( ... ). +``` + +The other way round, i. e. the assignment of an interface reference to +an object reference, is also possible +([downcast](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendown_cast_glosry.htm "Glossary Entry") +or narrowing cast). However, as mentioned before, this assignment can be +problematic since a successful assignment is dependent on whether the +object the interface reference points to is actually an object of the +implementing class. If this is not the case, a runtime error occurs. You +can carry out a downcast using the casting operator +[`CAST`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_cast.htm) +or the operator +[`?=`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_cast.htm). +The example shows the use of an [`IS INSTANCE +OF`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_instance_of.htm) +expression to prevent a runtime error as also shown before. + +``` abap +DATA i_ref TYPE REF TO intf. + +DATA cl_ref TYPE REF TO class. + +cl_ref = NEW #( ). + +IF i_ref IS INSTANCE OF class. + cl_ref = CAST #( i_ref ). +... +ENDIF. +``` + +> **✔️ Hints**
+> Interfaces versus abstract classes
+> Coming back to +[abstract](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabstract_glosry.htm "Glossary Entry") +classes in the context of interfaces. Like interfaces, abstract classes +cannot be instantiated - only their subclasses. The following list +includes differences between abstract classes and interfaces that should +be considered when creating them: +>- Abstract classes can have components (including abstract and + non-abstract methods) in other visibility sections than only public. +>- Multiple inheritance is impossible with abstract classes since there + can be only one abstract class as superclass. +>- Non-abstract methods in abstract classes can be implemented whereas + interfaces do not allow any method implementations. + + + +## Further Concepts + +### Factory Methods + +A factory method is relevant if you want to restrict and control the +instantiation of a class by external users of this class. Still, the +users should be able to work with objects of the class. This is true for +cases when, for example, there must be only a single object of a class +(a singleton) or certain checks must be carried out before a class can +be instantiated so as to guarantee a consistent creation of all objects. + +A (static) factory method implemented in such a class does the trick: It +creates an object of the class and returns a reference to the object. + +Example for a class and factory method: +``` abap +"Addition CREATE PRIVATE +CLASS class DEFINITION CREATE PRIVATE. + + PUBLIC SECTION. + CLASS-METHODS factory_method + IMPORTING ... + RETRUNING VALUE(obj) TYPE REF TO class. "Returns an object + +ENDCLASS. +... + +"Calling a factory method. +DATA obj_factory TYPE REF TO class. + +obj_factory = class=>factory_method( ... ). +``` + + + +### Friendship + +Classes can grant friendship to other classes and interfaces to enable +the access to protected and private components. However, the friendship +is not reciprocal. If class `a` grants friendship to class `b`, class `b` must +also explicitly grant friendship to class `a` if the component should be +made accessible also the other way round. + +Friends of a class can create instances of the class without any +restrictions. They are not automatically made friends of the subclasses +of the class. + +Friendship prevents that the components are made available to all users. +A typical use case for friendship between classes is [unit +tests](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenunit_test_glosry.htm "Glossary Entry"), +i. e. friendship is granted to test classes so that they can access and +test private components, too. + +You specify the befriended class in the definition part: +``` abap +CLASS class DEFINITION FRIENDS other_class. +... +``` + + + +### Events + +[Events](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenevent_glosry.htm "Glossary Entry") +are components of classes that can be triggered by methods. If an event +is raised (by a [`RAISE EVENT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapraise_event.htm) +statement), specific [event handler +methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenevent_handler_glosry.htm "Glossary Entry") +are called to react on the event. The following points are relevant for +raising events: + +- Defining events + - Events must be defined in a visibility section of the + declaration part of a class or in an interface, e. g. as + instance (using an + [`EVENTS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapevents.htm) + statement) or static events + ([`CLASS-EVENTS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclass-events.htm)). + - Similar to methods, static events can be triggered by instance + and static methods, instance events can only be triggered by + instance methods. + - Events allow exporting parameters to be defined. They must be + passed by value. Each instance event also includes the implicit + output parameter `sender` representing an object + reference variable for the instance for which the event is + defined. +- Defining and implementing [event handler + methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenevent_handler_glosry.htm "Glossary Entry"). + These methods are defined with a special syntax: + +``` abap +CLASS-METHODS handler_meth FOR EVENT evt OF class +... +``` + +- Registering event handler methods + + - Event handler methods must be registered using a [`SET + HANDLER`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapset_handler.htm) + statement at runtime so that they can handle a raised event at + all and react accordingly. + - You can register instance events for a specific instance or for + all instances of a class. Static events are registered to the + whole class without any addition to the `SET HANDLER` + statement. + +```abap +SET HANDLER handler_meth FOR ref. "Specific instance + +SET HANDLER handler_meth FOR ALL INSTANCES. "All instances + +SET HANDLER handler_meth. "For static events +``` + + + +## Executable Example +[zcl_demo_abap_objects](./src/zcl_demo_abap_objects.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/05_Constructor_Expressions.md b/05_Constructor_Expressions.md new file mode 100644 index 0000000..9f39ff0 --- /dev/null +++ b/05_Constructor_Expressions.md @@ -0,0 +1,899 @@ + + +# Working with Constructor Expressions + +- [Working with Constructor Expressions](#working-with-constructor-expressions) + - [Introduction](#introduction) + - [`VALUE`](#value) + - [`CORRESPONDING`](#corresponding) + - [`NEW`](#new) + - [`CONV`](#conv) + - [`EXACT`](#exact) + - [`REF`](#ref) + - [`CAST`](#cast) + - [`COND`](#cond) + - [`SWITCH`](#switch) + - [`FILTER`](#filter) + - [`REDUCE`](#reduce) + - [Iteration Expressions with `FOR`](#iteration-expressions-with-for) + - [`LET Expressions`](#let-expressions) + - [Executable Example](#executable-example) + +## Introduction + +- [Constructor + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_glosry.htm "Glossary Entry") + include a [constructor + operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_operator_glosry.htm "Glossary Entry") + followed by the specification of a [data + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_type_glosry.htm "Glossary Entry") + or [object + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_type_glosry.htm "Glossary Entry") + (or a `#` character that stands for such a type) and + specific parameters specified within parentheses. Example using the + `VALUE` operator: + + ``` abap + ... VALUE string( ... ) ... + ... VALUE #( ... ) ... + ``` + +- As the name implies, these expressions construct results of a + specific type and their content. Either the type is specified + explicitly before the first parenthesis or the said `#` + character can be specified if the type can be derived implicitly + from the [operand + position](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoperand_position_glosry.htm "Glossary Entry"). + The `#` character symbolizes the [operand + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoperand_type_glosry.htm "Glossary Entry"). + If no type can be derived from the operand position, for some + constructor operators, the type can also be derived from the + arguments in the parentheses. +- Why use them? Constructor expressions can make your code leaner and + more readable since you can achieve the same with fewer statements. +- Apart from the concept of deriving types from the context, another + concept is very handy particularly in this context: [Inline + declaration](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninline_declaration_glosry.htm "Glossary Entry"). + - This means that you can declare a variable using + `DATA(var)` (or an immutable variable + [`FINAL(var)`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfinal_inline.htm)) + as an operand in the current [write + position](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwrite_position_glosry.htm "Glossary Entry"). + In doing so, such a variable declared inline can be given the + appropriate type and result of the constructor expression in one + go: `DATA(dec) = VALUE decfloat34( '1.23' )`. + +> **✔️ Hint**
+> The construction of a result, i. e. a target [data +object](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_object_glosry.htm "Glossary Entry"), +implies that the data object is initialized. However, for some +constructor operators, there is an addition with which the +initialization can be avoided. + + + +## `VALUE` + +- Expressions with the + [`VALUE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_value.htm) + operator construct a result in place based on a data type. +- This result can be initial values for any non-generic data types, + structures or internal tables. +> **💡 Note**
+> Elementary data types and reference types cannot be + explicitly specified for the construction of values here. +- Regarding the type specifications before and parameters within the + parentheses: + - No parameter specified within the parentheses: The return value + is set to its type-specific initial value. This is possible for + any non-generic data types. See more information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenvalue_constructor_params_init.htm). + - Structured and internal table type before the parentheses or + `#` stands for such types: Individual components of + structures can be specified as named arguments while each + component of the return value can be assigned a data object that + has the same data type as the component, or whose data type can + be converted to this data type. See more information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenvalue_constructor_params_struc.htm). + To construct internal tables, you have multiple options, for + example, you can add individual table lines using an inner pair + of parentheses. More syntax options, for example, using the + additions `BASE` and `FOR` are possible, too. + See more information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenvalue_constructor_params_itab.htm). + +Example: Structure + +``` abap +"Creating a structured type +TYPES: BEGIN OF struc_type, + a TYPE i, + b TYPE c LENGTH 3, + END OF struc_type. + +DATA struc TYPE struc_type. "Structured data object + +struc = VALUE #( a = 1 b = 'aaa' ). "Deriving the type using # +``` + + +As mentioned above, the concept of [inline +declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninline_declarations.htm) +enters the picture here, which simplifies ABAP programming. You can +construct a new data object (for example, using `DATA(...)`), +provide the desired type with the constructor expression and assign +values in one go. + +``` abap +"Explicit type specification needed +DATA(structure) = VALUE struc_type( a = 2 b = 'bbb' ). +``` + +Note that initial values can be created by omitting the specification of +components or by providing no content within the parentheses. + +``` abap +"Component b not specified, b remains initial +struc = VALUE #( a = 2 ). + +"Explicit setting of initial value for a component +struc = VALUE #( a = 1 b = value #( ) ). + +"The whole structure is initial +struc = VALUE #( ). + +"Creating initial values for an elementary data type +DATA num1 TYPE i. + +num1 = VALUE #( ). + +"Inline declaration +DATA(num2) = VALUE i( ). +``` + +Regarding internal tables, the line specifications are enclosed in an +inner pair of parentheses `( ... )`. In the following examples, +three lines are added to a table. + +``` abap +"Creating an internal table type and an internal table +TYPES tab_type TYPE TABLE OF struc_type WITH EMPTY KEY. +DATA itab TYPE tab_type. + +"Filling the internal table using the VALUE operator with # +itab = VALUE #( ( a = 1 b = 'aaa' ) + ( a = 2 b = 'bbb' ) + ( a = 3 b = 'ccc' ) ). + +"Internal table declared inline, explicit type specification +DATA(itab2) = VALUE tab_type( ( a = 1 b = 'aaa' ) + ( a = 2 b = 'bbb' ) + ( a = 3 b = 'ccc' ) ). + +"Unstructured line types work without component names. +"Here, the internal table type is a string table. +DATA(itab3) = VALUE string_table( ( `abc` ) ( `def` ) ( `ghi` ) ). +``` + +In case of +[deep](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendeep_structure_glosry.htm "Glossary Entry") +and [nested +structures](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abennested_structure_glosry.htm "Glossary Entry") +or [deep +tables](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abendeep_table_glosry.htm "Glossary Entry"), +the use of `VALUE` expressions is handy. The following example +demonstrates a nested structure. +``` abap +"Creating a nested structure +DATA: BEGIN OF nested_struc, + a TYPE i, + BEGIN OF struct, + b TYPE i, + c TYPE c LENGTH 3, + END OF struct, + END OF nested_struc. + +"Filling the deep structure +nested_struc = VALUE #( a = 1 struct = VALUE #( b = 2 c = 'abc' ) ). +``` + +`BASE` addition: A constructor expression without the +`BASE` addition initializes the target variable. Hence, you can +use the addition if you do not want to construct a structure or internal +table from scratch but keep existing content. + +``` abap +"Filling structure +struc = VALUE #( a = 1 b = 'aaa' ). + +"struc is not initialized, only component b is modified, value of a is kept +struc = VALUE #( BASE struc b = 'bbb' ). + +"Filling internal table with two lines +itab = VALUE #( ( a = 1 b = 'aaa' ) + ( a = 2 b = 'bbb' ) ). + +"Two more lines are added instead of initializing the internal table +itab = VALUE #( BASE itab + ( a = 3 b = 'ccc' ) + ( a = 4 b = 'ddd' ) ). +``` + +`LINES OF` addition: All or some lines of another table can be included in the target internal table (provided that they have +appropriate line types): +``` abap +itab = VALUE #( ( a = 1 b = 'aaa' ) + ( a = 2 b = 'bbb' ) + ( LINES OF itab2 ) "All lines of itab2 + ( LINES OF itab3 FROM 2 TO 5 ) ). "Specific lines of itab3 +``` + +Using the inline construction of structures and internal tables, you can +avoid the declaration of extra variables in many contexts, for example, +ABAP statements like +[`MODIFY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_itab.htm) +for modifying internal tables or [ABAP +SQL](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_sql_glosry.htm "Glossary Entry") +statements like +[`MODIFY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_dbtab.htm) +(which is not to be confused with the ABAP statement having the same +name) for modifying database tables. + +Examples: +``` abap +"ABAP statements +"Modifiying individual internal table entries based on a structure created inline + +"Modifying a table line +MODIFY TABLE some_itab FROM VALUE #( a = 1 ... ). + +"Inserting a table line +INSERT VALUE #( a = 2 ... ) INTO TABLE some_itab. + +"Deleting a table line +DELETE TABLE some_itab FROM VALUE #( a = 3 ). + +"ABAP SQL statement +"Modifying multiple database table entries based on an internal table +"constructed inline within a host expression +MODIFY zdemo_abap_carr FROM TABLE @( VALUE #( + ( carrid = 'XY' + carrname = 'XY Airlines' + currcode = 'USD' + url = 'some_url' ) + ( carrid = 'ZZ' + carrname = 'ZZ Airways' + currcode = 'EUR' + url = 'some_url' ) ) ). +``` + +> **💡 Note**
+> Some of the additions and concepts mentioned here are +also valid for other constructor expressions further down but not +necessarily mentioned explicitly. See the details on the syntactical +options of the constructor operators in the ABAP Keyword Documentation. + + + +## `CORRESPONDING` + +- Expressions with the + [`CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expr_corresponding.htm) + operator construct structures and internal tables based on a data + type (i. e. a [table + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentable_type_glosry.htm "Glossary Entry") + or [structured + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstructured_type_glosry.htm "Glossary Entry")). +- The components or columns of the target data object are filled using + assignments of the parameters specified within the parentheses. +- The assignments are made using identical names or based on [mapping + relationships](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencorresponding_constr_mapping.htm) +- Note: Pay attention to the [assignment and conversion + rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_rules.htm) + to avoid errors when using the operator. Consider, for example, the + impact of assigning the values of identically named fields having + different types (e. g. one field is of type `c` and another + field is of type `string`). + +The following table includes a selection of various possible additions to +this constructor operator. There are more variants available like the +addition `EXACT`, using a lookup table, the option of discarding +duplicates or +[RAP](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_glosry.htm "Glossary Entry")-specific +variants that are not part of this cheat sheet. Find the details in +[this +topic](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expr_corresponding.htm). + +| Addition | Details | +|---|---| +| `BASE` | Keeps original values. Unlike, for example, the operator `VALUE`, a pair of parentheses must be set around `BASE`. | +| `MAPPING` | Enables the mapping of component names, i. e. a component of a source structure or source table can be assigned to a differently named component of a target structure or target table (e. g. `MAPPING c1 = c2`). | +| `EXCEPT` | You can specify components that should not be assigned content in the target data object. They remain initial. In doing so, you exclude identically named components in the source and target object that are not compatible or convertible from the assignment to avoid syntax errors or runtime errors. | +| `DEEP` | Relevant for deep tabular components. They are resolved at every hierarchy level and identically named components are assigned line by line. | +| `[DEEP] APPENDING` | Relevant for (deep) tabular components. It ensures that the nested target tables are not deleted. The effect without `DEEP` is that lines of the nested source table are added using `CORRESPONDING` without addition. The effect with `DEEP` is that lines of the nested source table are added using `CORRESPONDING` with the addition `DEEP`. | + +See the executable example for demonstrating the effect of the variants: +``` abap +"Assignment of a structure/internal table to another one having a different type +struc2 = CORRESPONDING #( struc1 ). + +tab2 = CORRESPONDING #( tab1 ). + +"BASE keeps original content, does not initialize the target +struc2 = CORRESPONDING #( BASE ( struc2 ) struc1 ). + +tab2 = CORRESPONDING #( BASE ( tab2 ) tab1 ). + +"MAPPING/EXACT are used for mapping/excluding components in the assignment +struc2 = CORRESPONDING #( struc1 MAPPING comp1 = comp2 ). + +tab2 = CORRESPONDING #( tab1 EXCEPT comp1 ). + +"Complex assignments with deep components using further additions +st_deep2 = CORRESPONDING #( DEEP st_deep1 ). + +st_deep2 = CORRESPONDING #( DEEP BASE ( st_deep2 ) st_deep1 ). + +st_deep2 = CORRESPONDING #( APPENDING ( st_deep2 ) st_deep1 ). + +st_deep2 = CORRESPONDING #( DEEP APPENDING ( st_deep2 ) st_deep1 ). +``` +> **✔️ Hint**
+> `CORRESPONDING` operator versus +[`MOVE-CORRESPONDING`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove-corresponding.htm): +Although the functionality is the same, note that, as the name implies, +constructor operators construct and - without the addition +`BASE` - target objects are initialized. Hence, the following +two statements are not the same: +>``` abap +>struc2 = CORRESPONDING #( struc1 ). +> +>"Not matching components are not initialized +>MOVE-CORRESPONDING struc1 TO struc2. +>``` + + + +## `NEW` + +- Using the instance operator + [`NEW`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_new.htm), + you can create [anonymous data + objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenanonymous_data_object_glosry.htm "Glossary Entry") + or + [instances](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstance_glosry.htm "Glossary Entry") + of a class and also assign values to the new object. As a result, + you get a [reference + variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_variable_glosry.htm "Glossary Entry") + that points to the created object. In doing so, the operator + basically replaces [CREATE + DATA](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcreate_data.htm) + and [CREATE + OBJECT](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcreate_object.htm). +- For the type specification preceding the parentheses, you can use + - non-generic data types which creates a [data reference + variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_reference_variable_glosry.htm "Glossary Entry") + pointing to the anonymous data object. + - classes which creates objects of these classes. The result is a + [object reference + variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_refer_variable_glosry.htm "Glossary Entry") + pointing to an object. +- Regarding the created object reference variables, you can use the + [object component + selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_component_select_glosry.htm "Glossary Entry") + `->` in certain contexts to ... + - point to a class attribute: `... NEW class( ... )->attr` + - introduce + [standalone](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcall_method_static_short.htm) + and + [functional](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcall_method_functional.htm) + method calls, including [chained method + calls](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenchained_method_call_glosry.htm "Glossary Entry") + which is a big advantage because you do not need to declare an + extra variable: `... NEW class( ... )->meth( ... ) ...` +- Regarding the type specifications before and parameters within the + parentheses: + - No parameter specified within the parentheses: An anonymous data + object retains its type-specific initial value. In case of + classes, no parameter specification means that no values are + passed to the instance constructor of an object. However, in + case of mandatory [input + parameters](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninput_parameter_glosry.htm "Glossary Entry"), + the parameters must be specified. + - Single parameter specified: If the type specified before the + parentheses is a non-generic elementary, structured, table, or a + reference type (or such a type can be derived using + `#`), a single data object can be specified as an + unnamed argument. Note the [assignment + rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_rules.htm) + regarding the value assignments within the parentheses and that + a constructor expression itself can be specified there. + - Structures and internal tables specified: If the type specified + before the parentheses is a structured data type or `#` + stands for it, you can specify the individual components as + named arguments (`comp1 = 1 comp2 = 2 ...`; see more + information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abennew_constructor_params_struct.htm)). + For the construction of anonymous internal tables, multiple + options are available. Among them, there is the use of + `LET` and `FOR` expressions and others. See more + details + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abennew_constructor_params_itab.htm). + - Classes: As mentioned, non-optional input parameters of the + instance constructor of the instantiated class must be filled. + No parameters are passed for a class without an explicit + instance constructor. See more information: + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abennew_constructor_params_class.htm). + +Examples: +``` abap +"Data references +"Declaring data reference variables +DATA dref1 TYPE REF TO i. "Complete type +DATA dref2 TYPE REF TO data. "Generic type + +"Creating anonymous data objects +"Here, no parameters are specified within the parentheses meaning the +"data objects retain their initial values. +dref1 = NEW #( ). +dref2 = NEW string( ). + +"Assigning single values; specified as unnamed data objects +dref1 = NEW #( 123 ). +dref2 = NEW string( `hallo` ). + +"Using inline declarations to omit a prior declaration of a variable +DATA(dref3) = NEW i( 456 ). + +DATA text TYPE string VALUE `world`. + +"Another constructor expression specified within the parentheses +dref2 = NEW string( `Hello ` && text && CONV string( '!' ) ). + +DATA dref4 TYPE REF TO string_table. +dref4 = NEW #( VALUE string_table( ( `a` ) ( `b` ) ) ). + +"Structured type; named arguments within the parentheses +DATA(dref5) = NEW scarr( carrid = 'AA' carrname = 'American Airlines' ). + +"Object references +"Declaring object reference variables +DATA oref1 TYPE REF TO cl1. "Assumption: class without constructor implementation +DATA oref2 TYPE REF TO cl2. "Assumption: class with constructor implementation + +"Creating instances of classes +oref1 = NEW #( ). + +"Listing the parameter bindings for the constructor method +"If there is only one parameter, the explicit specification of the +"parameter name is not needed and the value can be specified directly +oref2 = NEW #( p1 = ... p2 = ... ). + +"Using inline declaration +DATA(oref3) = NEW cl2( p1 = ... p2 = ... ). + +"Method chaining +... NEW some_class( ... )->meth( ... ). + +"Chained attribute accesses +... NEW some_class( ... )->attr ... +``` + + + +## `CONV` + +- The + [`CONV`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_conv.htm) + operator enforces conversions from one type to another and creates + an appropriate result. +- Note that the conversion is carried out according to [conversion + rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_rules.htm). + - Further [special + rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconv_constructor_inference.htm) + apply if the constructor expression is passed to an [actual + parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenactual_parameter_glosry.htm "Glossary Entry") + with a generically typed [formal + parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenformal_parameter_glosry.htm "Glossary Entry"). +- The operator is particularly suitable for avoiding the declaration + of helper variables. + +Examples: +``` abap +"Result: 0.2 +DATA(a) = CONV decfloat34( 1 / 5 ). + +"Comparison with an expression without CONV; the result is 0 +DATA(b) = 1 / 5. +``` + +Excursion: As outlined above, you can construct structures and internal +tables using the `VALUE` operator. Using this operator for +constructing [elementary data +objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenelementary_data_object_glosry.htm "Glossary Entry") +is not possible apart from creating a data object with an initial value, +for example `DATA(str) = VALUE string( ).`. The `CONV` +operator closes this gap. However, in some cases, the use of +`CONV` is redundant. + +``` abap +DATA(c) = CONV decfloat34( '0.4' ). + +"Instead of +DATA d TYPE decfloat34 VALUE '0.4'. + +"Redundant conversion +"Derives the string type automatically +DATA(e) = `hallo`. + +"Produces a syntax warning +"DATA(f) = CONV string( `hallo` ). +``` + + + + +## `EXACT` + +- The + [`EXACT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_exact.htm) + operator enforces either a [lossless + assignment](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlossless_move.htm) + or a [lossless + calculation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlossless_calculation.htm) + depending on the data object specified within the parentheses and + creates an appropriate result. +- In case of calculations, [rules of lossless + assignments](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_exact.htm) + apply. In other cases, the result is created according to the + [conversion + rules](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_rules.htm) + mentioned above and an additional check is performed in accordance + with the [rules of lossless + assignments](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_exact.htm). + +Examples: +``` abap +"Leads to a data loss when converting to a data object accepting only a single character +TRY. + DATA(exact1) = EXACT abap_bool( 'XY' ). + CATCH CX_SY_CONVERSION_DATA_LOSS INTO DATA(error1). +ENDTRY. + +"The calculation cannot be executed exactly; a rounding is necessary +TRY. + DATA(exact2) = EXACT decfloat34( 1 / 3 ). + CATCH CX_SY_CONVERSION_ROUNDING INTO DATA(error2). +ENDTRY. +``` + + + +## `REF` + +- The + [`REF`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_ref.htm) + operator creates a [data reference + variable](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_reference_variable_glosry.htm "Glossary Entry") + pointing to a specified data object. +- The type specified after `REF` and directly before the first + parenthesis determines the [static + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstatic_type_glosry.htm "Glossary Entry") + of the result. +- The operator replaces [`GET + REFERENCE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapget_reference.htm) + and is particularly useful for avoiding the declaration of helper + variables that are only necessary, for example, to specify data + reference variables as actual parameters. + +Examples: +``` abap +"Data references +"Declaring data object and assign value + +DATA number TYPE i VALUE 5. + +"Declaring data reference variable + +DATA dref_a TYPE REF TO i. + +"Getting references + +dref_a = REF #( number ). + +"Inline declaration and explicit type specification +DATA(dref_b) = REF string( `hallo` ). + +"Object references + +DATA(oref_a) = NEW some_class( ). + +DATA(oref_b) = REF #( oref_a ). +``` + + + +## `CAST` + +- Using the + [`CAST`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_cast.htm) + operator, you can carry out + [upcasts](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenup_cast_glosry.htm "Glossary Entry") + and + [downcasts](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendown_cast_glosry.htm "Glossary Entry") + and create a reference variable of a static type as a result. +- It replaces the + [`?=`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_cast.htm) + operator and enables [chained method + calls](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenchained_method_call_glosry.htm "Glossary Entry"). +- The operator is particularly helpful for avoiding the declaration of + helper variables and more contexts. +- Similar to the `NEW` operator, constructor expressions with + `CAST` can be followed by the object component selector + `->` to point to a class or interface attribute (`... CAST class( ... )->attr`) and methods (`... CAST class( ... + )->meth( ... )`). Method chaining, standalone and + functional method calls are possible, too. See more information + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_cast.htm). + +[Run Time Type Identification +(RTTI)](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrun_time_type_identific_glosry.htm "Glossary Entry") +examples: +``` abap +"Getting component information +DATA(components) = + CAST cl_abap_structdescr( + cl_abap_typedescr=>describe_by_data( some_object ) )->components. + +"Getting method information +DATA(methods) = + CAST cl_abap_objectdescr( + cl_abap_objectdescr=>describe_by_name( 'LOCAL_CLASS' ) )->methods. +``` + + + +## `COND` + +- The + [`COND`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconditional_expression_cond.htm) + operator is used for either creating a result depending on [logical + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogical_expression_glosry.htm "Glossary Entry") + or raising a [class-based + exception](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_based_exception_glosry.htm "Glossary Entry") + (which is specified within the parentheses after the addition + [`THROW`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconditional_expression_result.htm)). +- There can be multiple logical expressions initiated by + `WHEN` followed by the result specified after + `THEN`. If none of the logical expressions are true, you can + specify an `ELSE` clause at the end. If this clause is not + specified, the result is the initial value of the specified or + derived data type. +- Note that all operands specified after `THEN` must be + convertible to the specified or derived data type. + +Example: +``` abap +DATA(b) = COND #( WHEN a BETWEEN 1 AND 3 THEN w + WHEN a > 4 THEN x + WHEN a IS INITIAL THEN y + ELSE z ). +``` + + + +## `SWITCH` + +The +[`SWITCH`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconditional_expression_switch.htm) +operator is fairly similar to the `COND` operator and works in +the style of +[`CASE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcase.htm) +statements, i. e. it uses the value of only a single variable that is +checked in the case distinction. + +``` abap +DATA(b) = SWITCH #( a + WHEN 1 THEN w + WHEN 2 THEN x + WHEN 3 THEN y + ELSE z ). +``` + + + +## `FILTER` + +- The + [`FILTER`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_filter.htm) + operator constructs an internal table line by line based on an + existing table and conditions specified in a `WHERE` clause. +- The conditions can either be based on single values or a [filter + table](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expr_filter_table.htm). +- Additions: + +|Addition |Details | +|---|---| +|`USING KEY` | Specifies the [table key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentable_key_glosry.htm "Glossary Entry") with which the `WHERE` condition is evaluated, i. e. a [sorted key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensorted_key_glosry.htm "Glossary Entry") or a [hash key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhash_key_glosry.htm "Glossary Entry"). If the internal table has neither of them, a [secondary table key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensecondary_table_key_glosry.htm "Glossary Entry") must be available and specified. | +| `EXCEPT` | The specification of `EXCEPT` means that those lines of the existing table are used that do not meet the condition specified in the `WHERE` clause. Hence, if `EXCEPT` is not specified, the lines of the existing table are used that meet the condition. | + + +Examples: +``` abap +DATA(f1) = FILTER #( tab WHERE comp > 5 ). + +DATA(f2) = FILTER #( tab EXCEPT WHERE comp < 3 ). + +DATA(f3) = FILTER #( tab USING KEY x WHERE comp = 4 ). + +"Filtering based on another table +DATA(f3) = FILTER #( tab IN filter_tab + WHERE comp = 3 ). +``` + + + +## `REDUCE` + +- The + [`REDUCE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_reduce.htm) + operator creates a result of a specified or derived type from one or + more [iteration + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeniteration_expression_glosry.htm "Glossary Entry"). +- It basically reduces sets of data objects to a single data object. + For example, the numeric values of a table column are summed up. As + a result, the total number is constructed. + +The following example calculates the total of the numbers from 1 to 10 +using the `REDUCE` operator: +``` abap +DATA(sum) = REDUCE i( INIT s = 0 + FOR i = 1 UNTIL i > 10 + NEXT s += i ) ). "sum: 55 +``` + +> **💡 Note**
+> - `INIT ...`: A temporary variable is specified that sets an + initial value for the result variable. +>- `FOR ...`: Represents a loop. The loop is carried out until + the condition is met after `UNTIL`. +>- `NEXT ...`: Represents the assignment to the temporary + variable after every iteration. +>- Once the loop has finished, the target variable is assigned the + resulting value. + + + +## Iteration Expressions with `FOR` + +- Using [iteration + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeniteration_expression_glosry.htm "Glossary Entry") + with the language element + [`FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfor.htm), + you can carry out [conditional + iterations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfor_conditional.htm) + (including the ABAP words `UNTIL` and `WHILE` which + have the semantics of ABAP statements + [`DO`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdo.htm) + and + [`WHILE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwhile.htm)) + or [table + iterations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentable_iteration_glosry.htm "Glossary Entry") + (having the semantics of [[LOOP + AT]](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_variants.htm); + the expressions include the ABAP word `IN`). +- Such expressions are possible in the following contexts: + - `REDUCE`: The reduction result is created in the + iteration steps. + - `NEW` and `VALUE`: Used in the context of + looping across internal tables. New table lines are created in + the iteration steps and inserted into a target table. + +`FOR ... WHILE`: The following example with `REDUCE` +has the same effect as the example using `UNTIL` shown above. + +``` abap +DATA(sum) = REDUCE i( INIT y = 0 + FOR n = 1 THEN n + 1 WHILE n < 11 + NEXT y += n ). +``` + +`FOR ... UNTIL`: See the example in the `REDUCE` +section. + +`FOR ... IN`: + +- The operand specified after `FOR` represents an iteration + variable, i. e. a [work + area](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwork_area_glosry.htm "Glossary Entry") + that contains the data while looping across the table. +- This variable is only visible within the `FOR` + expression, i. e. it cannot be used outside of the expression. +- The type of the variable is determined by the type of the internal + table specified after `IN`. +- One or more iteration expressions can be specified using + `FOR`. +- The components or the whole table line that is to be returned are + specified within the pair of parentheses before the closing + parenthesis. +- In contrast to `LOOP` statements, the sequential processing + cannot be debugged. + +Some examples for looping across tables and storing values in target +tables: +``` abap +"Looping across table and storing the whole line in a new table; +"the target table must have the same table type as the source table itab; +"without the WHERE condition, all lines are respected + +TYPES t_type LIKE itab. + +... = VALUE t_type( FOR wa IN itab + "WHERE ( comp1 > 2 ) + ( wa ) ). + +"Storing specific components having different names by specifying the assignment +"individually; assumption: the target type is not compatible to the type of itab; +"a field mapping is provided; pay attention to potential type conversion + +... = VALUE t_type( FOR wa IN itab + "WHERE ( comp1 > 2 ) + ( compX = wa-comp1 + compY = wa-comp2 ) ). + +"Storing specific components having the same names; +"assumption: Target type is not compatible to the type of itab; +"if there are identically named components in the table types, you might +"also use CORRESPONDING + +... = VALUE t_type( FOR wa IN itab + "WHERE ( comp1 > 2 ) + ( CORRESPONDING #( wa ) ) ). + +"Multiple iteration expressions + +... = VALUE t_type( FOR wa1 IN itab1 WHERE ( comp1 = 4 ) + FOR wa2 IN itab2 WHERE ( comp2 > 5 ) + FOR wa3 IN itab3 WHERE ( comp3 < 3 ) + ( compX = wa1-comp1 + compY = wa2-comp2 + compZ = wa3-comp3 ) ). +``` + + + +## `LET Expressions` + +- [`LET`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaplet.htm) + expressions allow you to declare local helper fields (variables or + fields symbols) and assign values (the type is derived from the + defined value) to be used in constructor expressions, for example, + in iteration expressions using `FOR` or results specified in + the conditional expressions of `COND` and `SWITCH`. +- Note that the helper field is only valid in the context in which the + `LET` expression is specified. + +Examples: +``` abap +"Creating a string table using a LET expression + +DATA(str_tab) = VALUE string_table( LET it = `be` IN + ( |To { it } is to do| ) + ( |To { it } or not to { it }| ) + ( |To do is to { it }| ) + ( |Do { it } do { it } do| ) ). + +"Conditional expressions + +DATA(a) = COND #( LET b = c IN + WHEN b > x THEN ... + WHEN b < y THEN ... + ... + ELSE ... ). +``` + + + +## Executable Example +[zcl_demo_abap_constructor_expr](./src/zcl_demo_abap_constructor_expr.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/06_Dynamic_Programming.md b/06_Dynamic_Programming.md new file mode 100644 index 0000000..482aa6d --- /dev/null +++ b/06_Dynamic_Programming.md @@ -0,0 +1,866 @@ + + +# Dynamic Programming + + +- [Dynamic Programming](#dynamic-programming) + - [Notes on "Dynamic"](#notes-on-dynamic) + - [Excursion: Field Symbols and Data References](#excursion-field-symbols-and-data-references) + - [Field Symbols](#field-symbols) + - [Data References](#data-references) + - [Dynamic ABAP Statements](#dynamic-abap-statements) + - [Runtime Type Services (RTTS)](#runtime-type-services-rtts) + - [Further Information](#further-information) + - [Executable Example](#executable-example) + +## Notes on "Dynamic" + +Some considerations regarding "dynamic" in contrast to "static" aspects: + +- ABAP programs can include both dynamic and static parts. +- Consider a [data + object](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_object_glosry.htm "Glossary Entry") + you declare in a program having dedicated technical properties like + the [data + type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_type_glosry.htm "Glossary Entry") + or the actual name of the data object, i. e. these properties are + already (statically) known to the program at compile time and they + do not change throughout the program execution. +- On the other hand, there can be use cases where these properties + **are not known or not yet determined at compile time** at all. +- They are **only known at a program's runtime**, i. e. the + properties are defined and passed to programs at runtime. +- Consider a program that does not work with a specific kind of table + but should be able to work with any kind of table, for example, a + user must input the table name first in a UI. The tables to be used + in the program certainly have different properties, line types, + field names, number of rows, and so on. Nevertheless, the program + must be able to work with all of them, no matter what table is + processed. +- You might also need to determine information about data types and + data objects at runtime or even create them. + +Dynamic programming is a powerful means to make ABAP programs more +flexible and versatile. However, as implied above, dynamic programming +techniques must be handled with care and you must be aware of some +downsides, too. For example: + +- Dynamic features implemented in a program cannot be checked or + analyzed by the ABAP compiler. The exact data is not known at + compile time but only when the program is executed which has also an + impact on performance since the checks must be carried out at + runtime. +- Testing + [procedures](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenprocedure_glosry.htm "Glossary Entry") + including dynamic parts is difficult. + + + +## Excursion: Field Symbols and Data References + +[Field +symbols](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfield_symbol_glosry.htm "Glossary Entry") +and [data +references](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_reference_glosry.htm "Glossary Entry") +support dynamic programming and working with data objects whose +properties are only known at runtime. + +### Field Symbols + +Field symbols ... + +- can be considered as alias names for existing data objects. +- can only be used if they are assigned to a data object first. And if + assigned, you can access the content of variables via the field + symbol name. +- do not consume any space but act as a sort of label for the + particular memory area that is used by a data object which the field + symbol is assigned to. +- can be used in ABAP programs as if working with the actual data + object. +- can be statically typed with both [complete data + types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomplete_data_type_glosry.htm "Glossary Entry") + and [generic data + types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abengeneric_data_type_glosry.htm "Glossary Entry"). +- are especially helpful for accessing and editing data in structures + or internal tables at runtime without the need to copy the data + somewhere which boosts performance. + +**Declaring field symbols** + +Field symbols are declared with the `FIELD-SYMBOLS` statement. +You provide the name of the field symbol between angle brackets. You can +either type them with a complete data type or with a generic type. + +> **💡 Note**
+>- There are plenty of options for generic ABAP types. A prominent one + is `data` that stands for any data type (the older generic + type `any` has the same effect). See more information in the + topic [Generic ABAP + Types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbuilt_in_types_generic.htm). +>- Field symbols cannot be declared in the declaration part of + [classes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_glosry.htm "Glossary Entry") + and + [interfaces](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoo_intf_glosry.htm "Glossary Entry"). +>- Untyped field symbols are not supported in object-oriented contexts. +>- Field symbols can also be [declared + inline](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfield-symbol_inline.htm). + +Syntax: +``` abap +"Complete types +FIELD-SYMBOLS:
+> - When working with field symbols, you should make sure that they are assigned. Otherwise, a runtime error occurs. You can check the + assignment with the following logical expression. The statement is true if the field symbol is assigned. +> ``` abap +> IF
+>- Data reference variables are considered to be + [deep](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendeep_glosry.htm "Glossary Entry") + like strings and internal tables since none of them have an assigned + dedicated memory area. Internally, strings and internal tables are + addressed using references. +>- [Object + references](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_reference_glosry.htm "Glossary Entry") + and [object reference + variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenobject_refer_variable_glosry.htm "Glossary Entry") + are not part of this cheat sheet. To get more details, refer to the + ABAP Keyword Documentation or the cheat sheet [ABAP Object Orientation](04_ABAP_Object_Orientation.md). + +**Declaring data reference variables** + +Like field symbols, data reference variables can be declared with both a complete and a generic data type using `DATA` statements and the +addition `REF TO`. The type after `REF TO` represents the static data type. + +When declared, data reference variables do not yet point to a data object. + +Examples: +``` abap +DATA: ref1 TYPE REF TO i, "Complete data type + ref2 TYPE REF TO some_dbtab, "Complete data type + ref3 LIKE REF TO some_data_object, + ref4 TYPE REF TO data. "Generic data type +``` + +**Assigning data references** + +There are multiple options to assign data references: + +**Creating data references to existing data objects**: Using the +[reference +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_operator_glosry.htm "Glossary Entry") +`REF`, you can get a data reference to an existing data object. +The older syntax [`GET REFERENCE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapget_reference.htm) +has the same effect as using the newer reference operator but should not +be used anymore. +``` abap +"Declaring a data object + +DATA num TYPE i VALUE 5. + +"Declaring data reference variables + +DATA ref1 TYPE REF TO i. +DATA ref_gen TYPE REF TO data. + +"Creating data references to data objects. +"The # sign means that the type is derived from the context. + +ref1 = REF #( num ). +ref_gen = REF #( num ). + +"You can also use inline declarations to omit the explicit declaration. + +DATA(ref2) = REF #( num ). + +"You can explicitly specify the data type after REF. + +DATA(ref3) = REF string( `hallo` ). + +"GET REFERENCE OF; do not use anymore +"GET REFERENCE OF num INTO ref1. +"GET REFERENCE OF num INTO DATA(ref4). +``` + +**Creating new data objects at runtime**: You create a [anonymous +data +object](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenanonymous_data_object_glosry.htm "Glossary Entry") +at runtime by placing the reference in the variable and providing the +desired type. You can use the [instance +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninstance_operator_glosry.htm "Glossary Entry") +[`NEW`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_new.htm). +The older syntax [`CREATE DATA`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcreate_data.htm) +has the same effect as using the newer instance operator. + +Examples: +``` abap +"Declaring data reference variables + +DATA ref1 TYPE REF TO i. "Complete type +DATA ref_gen TYPE REF TO data. "Generic type + +"Creating anonymous data objects +"Using the # sign and the explicit type: see REF #( ) above. + +ref1 = NEW #( ). +ref_gen = NEW string( ). + +"For directly assigning values, insert the values within the parentheses. + +ref1 = NEW #( 123 ). + +"Using inline declarations to omit a prior declaration of a variable. + +DATA(ref2) = NEW i( 456 ). + +TYPES i_table TYPE STANDARD TABLE OF i WITH EMPTY KEY. + +DATA(ref3) = NEW i_table( ( 1 ) ( 2 ) ( 3 ) ( 4 ) ( 5 ) ). + +"Older syntax. + +DATA ref4 TYPE REF TO string. +DATA ref5 TYPE REF TO data. + +CREATE DATA ref4. + +"Note: TYPE ... needed because of generic type data +CREATE DATA ref5 TYPE p LENGTH 6 DECIMALS 2. + +CREATE DATA ref5 LIKE ref4. +``` + +**Assigning/Copying existing data references**: You can copy a data reference into another one. Note that static types of both data +reference variables must be compatible and that only the reference is copied and not the data object as such. That means that, when copied, both data reference variables point to the same data object. + +Notes: +- Data reference variables have both a +[static](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstatic_type_glosry.htm "Glossary Entry") +and a [dynamic +type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendynamic_type_glosry.htm "Glossary Entry"). +- When declaring a data reference variable, e. g. `DATA ref TYPE REF TO +i.`, you determine the static type. This type is either a +non-generic (`i` in the example) or a generic type (like +`data` or `any`; e. g. `DATA ref TYPE REF TO +data.`). +- The dynamic type is determined at runtime of the +program and is the data type of a referenced data object. Especially in +the context of assigning data references (and also object references), +this differentiation is relevant. +- The following basic rule applies: The +assignment of a data reference variable to another one is possible if +the static type of the target reference variable is more general than or +the same as the dynamic type of the source reference variable. +- If it can +be statically checked that an assignment is possible, the assignment is +done using the [assignment +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenassignment_operator_glosry.htm "Glossary Entry") +`=` that triggers an +[upcast](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenup_cast_glosry.htm "Glossary Entry") +automatically. Otherwise, it is a +[downcast](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendown_cast_glosry.htm "Glossary Entry"). +Here, the assignability is not checked until runtime. The downcast must +be triggered explicitly using [casting +operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencasting_operator_glosry.htm "Glossary Entry"), +either with the [constructor +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_operator_glosry.htm "Glossary Entry") +[`CAST`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_cast.htm) +or the older +[`?=`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmove_cast.htm), +for the assignment of data reference variables. +- See more information in +the topic [Assignment Rules for Reference +Variables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconversion_references.htm). + +The following example demonstrates up- and downcasts with the assignment +of data reference variables typed with a complete and generic data type: + +Syntax: + +``` abap +"Declaring data reference variables + +DATA ref1 TYPE REF TO i. + +DATA ref2 TYPE REF TO i. + +ref1 = NEW #( 789 ). + +"Copying data reference +ref2 = ref1. + +"Casting + +"Complete type +DATA(ref3) = NEW i( 321 ). + +"Generic type +DATA ref4 TYPE REF TO data. + +"Upcast +ref4 = ref3. + +"Downcasts +DATA ref5 TYPE REF TO i. + +"Generic type +DATA ref6 TYPE REF TO data. + +ref6 = NEW i( 654 ). +ref5 = CAST #( ref6 ). + +"Alternative syntax to the CAST operator +ref5 ?= ref6. +``` + +**Accessing data references** + +The content of data objects a data reference refers to can only be +accessed via dereferencing data reference variables using the +[dereferencing +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendereferencing_operat_glosry.htm "Glossary Entry") +`->*`. + +> **💡 Note**
+>- When dereferencing a data reference variable that has a structured + data type, you can use the [component + selector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_selector_glosry.htm "Glossary Entry") + `->` to access individual components. +>- In older ABAP releases, you could not dereference data reference + variables typed with a generic type. You had to do an assignment to + a field symbol first. + +Syntax: + +``` abap +"Creating data reference variables and assign values + +DATA(ref_i) = NEW i( 1 ). +DATA(ref_carr) = NEW zdemo_abap_carr( carrid = 'LH' carrname = 'Lufthansa' ). + +"Generic type + +DATA ref_gen TYPE REF TO data. +ref_gen = ref_i. "Copying reference + +"Accessing + +"Variable number receives the content. +DATA(number) = ref_i->*. + +"Content of referenced data object is changed. +ref_i->* = 10. + +"Data reference used in a logical expression. +IF ref_i->* > 5. + ... +ENDIF. + +"Dereferenced generic type +DATA(calc) = 1 + ref_gen->*. + +"Structure +"Complete structure +DATA(struc) = ref_carr->*. + +"Individual component +DATA(carrid) = ref_carr->carrid. +ref_carr->carrid = 'UA'. + +"This syntax also works but it is less comfortable. +ref_carr->*-carrname = 'United Airlines'. +``` + +> **💡 Note**
+> - You can check if a data reference can be dereferenced by using a + logical expression with [`IS BOUND`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_bound.htm): +> ``` abap +> IF ref IS BOUND. +> ... +> ENDIF. +> ``` +>- If you explicitly want to remove a reference from a data reference variable, you can use a `CLEAR` statement. However, the + [garbage collector](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abengarbage_collector_glosry.htm "Glossary Entry") + takes over the reference removal automatically once the data is not used any more by a reference. +> ``` abap +> CLEAR ref. +> ``` + +**Using data references** + +Some contexts of using data references are as follows: + +**Overwriting data reference variables**: A data reference variable is overwritten when a new object is created with a data reference +variable already pointing to a data object. +``` abap +ref = NEW i( 1 ). +ref = NEW i( 2 ). +``` +**Keeping data references**: If your use case is to retain the data references and you want to prevent that data references are overwritten +when using the same reference variable, you can put the reference variables in internal tables. The following code shows that three data +references are created with the same reference variable. + +``` abap +DATA: ref TYPE REF TO data, + itab TYPE TABLE OF REF TO data, + number TYPE i VALUE 0. + +DO 3 TIMES. + "Adding up 1 to demonstrate a changed data object. + number += 1. + + "Creating data reference and assigning value. + "In the course of the loop, the variable gets overwritten. + ref = NEW i( number ). + + "Adding the reference to itab + itab = VALUE #( BASE itab ( ref ) ). +ENDDO. +``` + +**Processing internal tables**: Similar to using field symbols, you can avoid the copying of table rows into a work area, for example, in a +loop using data reference variables and a `REFERENCE INTO` statement. In doing so, the processing of internal tables is much faster +than copying table lines to a work area. In the code snippet, an inline declaration is used in the `LOOP` statement. + +``` abap +"Fill an internal table. +SELECT * FROM zdemo_abap_fli + INTO TABLE @DATA(fli_tab). + +LOOP AT fli_tab REFERENCE INTO DATA(ref). + + "A component of the table line might be addressed. + ref->carrid = ... + + ... +ENDLOOP. +``` + +**Data reference variables as part of structures and internal tables**: In contrast to field symbols, data reference variables can be used as components of structures or columns in internal tables. +``` abap +"Structure + +DATA: BEGIN OF struc, + num TYPE i, + ref TYPE REF TO i, + END OF struc. + +"Some value assignment + +struc2 = VALUE #( num = 1 ref = NEW #( 2 ) ). + +"Internal table + +DATA itab LIKE TABLE OF struc WITH EMPTY KEY. + +"Some value assignment in the first table line +"assuming the table is filled and a line is available. + +itab[ 1 ]-ref->* = 123. +``` + +> **✔️ Hint**
+> The question might now arise when to actually use either a field symbol +or a data reference variable. It depends on your use case. However, data +reference variables are more powerful as far as their usage options are +concerned, and they better fit into the modern (object-oriented) ABAP +world. Recommended read: [Accessing Data Objects +Dynamically](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abendyn_access_data_obj_guidl.htm "Guideline"). + + + +## Dynamic ABAP Statements + +Dynamic aspects come particularly into the picture when considering the +options of dynamic ABAP statements. In this context, you can make use of +[tokens](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentoken_glosry.htm "Glossary Entry") +put within parentheses and included as operands in many ABAP statements +(e. g. `SORT table BY (field_name).`). The content of the token +is character-like and should be provided in capital letters. The content +is determined at runtime, e. g. a user entry in an input field whose +content is then part of an ABAP statement. + +Note that especially in this context, static checks are not possible, i. +e. if you have an ABAP statement using such a token, it cannot be +determined at compile time whether the operand that is passed is valid. +This can cause runtime errors. + +You can make use of the following dynamic token specification options: + +1. **Dynamic specification of data objects and fields** + +The names of data objects and fields are determined at runtime. + +Examples: +``` abap +"The sorting is done by a field that is determined at runtime. + +SORT itab BY (field_name). + +"A field symbol is assigned a data object; here, an attribute of a class + +ASSIGN class=>(attribute_name) TO FIELD-SYMBOL(
+CL_ABAP_TYPEDESCR + | + |--CL_ABAP_DATADESCR + | | + | |--CL_ABAP_ELEMDESCR + | | | + | | |--CL_ABAP_ENUMDESCR + | | + | |--CL_ABAP_REFDESCR + | |--CL_ABAP_COMPLEXDESCR + | | + | |--CL_ABAP_STRUCTDESCR + | |--CL_ABAP_TABLEDESCR + | + |--CL_ABAP_OBJECTDESCR + | + |--CL_ABAP_CLASSDESCR + |--CL_ABAP_INTFDESCR ++So, the +[superclass](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensuperclass_glosry.htm "Glossary Entry") +`CL_ABAP_TYPEDESCR` has multiple +[subclasses](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubclass_glosry.htm "Glossary Entry"), +for example, to deal with each kind of type. Among them, there are, for +example, structures or tables. Working with this superclass and its +subclasses means making use of +[casts](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abencast_glosry.htm "Glossary Entry"), +especially +[downcasts](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendown_cast_glosry.htm "Glossary Entry"). +Detailing out all the possibilities for the information retrieval and +type creation is beyond scope. Check the information, options and +various methods that can be used in the class documentation, e. g. using +F2 help information in +[ADT](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenadt_glosry.htm "Glossary Entry"), +for more details. + +The following examples show the retrieval of information. Instead of the +cumbersome extra declaration of data reference variables, you can use +[inline +declarations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninline_declaration_glosry.htm "Glossary Entry"). +[Method +chaining](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmethod_chaining_glosry.htm "Glossary Entry") +comes in handy, too. +``` abap +"The properties of a type are retrieved. + +DATA(some_type) = cl_abap_typedescr=>describe_by_data( var ). + +"The components of a structure are retrieved. +"Like above, the describe_by_data method is used together with a variable. + +DATA(components) = CAST cl_abap_structdescr( + cl_abap_typedescr=>describe_by_data( some_struc ) + )->components. + +"The attributes of a global class are retrieved. In contrast to the +"example above the describe_by_name method is used together with the actual name. + +DATA(attributes) = CAST cl_abap_classdescr( + cl_abap_classdescr=>describe_by_name( 'CL_SOME_CLASS' ) + )->attributes. +``` + +The following example demonstrates the creation of an internal table +type based on a [DDIC +type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddic_type_glosry.htm "Glossary Entry"). +Furthermore, an internal table is created based on this type. The type +itself is a sorted table (constants can also be used here). Unique keys +are defined in a dedicated table of type +`ABAP_KEYDESCR_TAB` that is part of the +`cl_abap_tabledescr=>create` method call. + +Note the [`TYPE HANDLE`](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abapcreate_data_handle.htm) +addition as part of the `CREATE DATA` statement that is used +when referring to dynamically created data types. + +``` abap +DATA(line_type) = CAST cl_abap_structdescr( + cl_abap_tabledescr=>describe_by_name( `ZDEMO_ABAP_CARR` ) ). + +"Defining primary table keys of internal table type to be created + +DATA(key_tab) = VALUE abap_keydescr_tab( ( name = 'CARRID' ) + ( name = 'CARRNAME' ) ). + +"Creating internal table type + +DATA(table_type) = cl_abap_tabledescr=>create( + p_line_type = line_type + p_table_kind = cl_abap_tabledescr=>tablekind_sorted + p_unique = cl_abap_typedescr=>true + p_key = key_tab ). + +"Create internal table based on the created table type + +DATA ref_tab TYPE REF TO data. + +CREATE DATA ref_tab TYPE HANDLE table_type. +``` + + + +## Further Information +- It is recommended that you also consult section [Dynamic Programming Techniques (F1 docu for standard ABAP)](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abendynamic_prog_technique_gdl.htm) in the ABAP Keyword Documentation since it provides important aspects that should be considered when dealing with dynamic programming in general (e. g. security aspects or runtime error prevention). +- There are even further dynamic programming techniques in the unrestricted language scope like the +generation or execution of programs at runtime. They are not part of this cheat sheet. Find more details on the related syntax (e. g. `GENERATE SUBROUTINE POOL`, `READ REPORT` and `INSERT REPORT` in the ABAP Keyword Documentation for Standard ABAP: [Dynamic Program Development](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_language_dynamic.htm) + +## Executable Example +[zcl_demo_abap_dynamic_prog](./src/zcl_demo_abap_dynamic_prog.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/07_String_Processing.md b/07_String_Processing.md new file mode 100644 index 0000000..5eb331c --- /dev/null +++ b/07_String_Processing.md @@ -0,0 +1,1178 @@ + + +# String Processing + +- [String Processing](#string-processing) + - [Introduction](#introduction) + - [Variable Length and Fixed Length Character Strings](#variable-length-and-fixed-length-character-strings) + - [Declaring Character-Like Data Types and Objects](#declaring-character-like-data-types-and-objects) + - [Assigning Values](#assigning-values) + - [String Templates](#string-templates) + - [Determining the Length of Strings](#determining-the-length-of-strings) + - [Concatenating Strings](#concatenating-strings) + - [Splitting Strings](#splitting-strings) + - [Modifying Strings](#modifying-strings) + - [Processing Substrings](#processing-substrings) + - [Searching and Replacing](#searching-and-replacing) + - [Searching for Specific Characters](#searching-for-specific-characters) + - [Replacing Specific Characters in Strings](#replacing-specific-characters-in-strings) + - [Searching for Substrings in Strings](#searching-for-substrings-in-strings) + - [Replacing Substrings in Strings](#replacing-substrings-in-strings) + - [Pattern-Based Searching and Replacing in Strings](#pattern-based-searching-and-replacing-in-strings) + - [Simple Pattern-Based Searching Using Comparison Operators](#simple-pattern-based-searching-using-comparison-operators) + - [Complex Searching and Replacing Using Regular Expressions](#complex-searching-and-replacing-using-regular-expressions) + - [Searching Using Regular Expressions](#searching-using-regular-expressions) + - [Replacing Using Regular Expressions](#replacing-using-regular-expressions) + - [Executable Example](#executable-example) + + +## Introduction + +ABAP offers plenty of options for processing [character +strings](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencharacter_string_glosry.htm "Glossary Entry"). +The options include ABAP statements (e. g. +[`FIND`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapfind.htm)), +[character string +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_expression_glosry.htm "Glossary Entry") +(e. g. [string +templates](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_template_glosry.htm "Glossary Entry")) +and built-in [string +functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_function_glosry.htm "Glossary Entry") +(e. g. +[`strlen`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlength_functions.htm)). + +> **💡 Note**
+>- Expressions and string functions can help make your ABAP code more + concise and straightforward. For example, string operations can be + done directly in [operand + position](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoperand_position_glosry.htm "Glossary Entry") + and, thus, you can avoid temporary variables. +>- In ABAP statements, modify operations on strings are frequently done + on the source field which is the target field at the same time. + String functions never modify the source field. Instead, the + modified string is provided as a [return + value](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreturn_value_glosry.htm "Glossary Entry"). +>- In most cases, string functions offer the same functionality as the + corresponding ABAP statements. The return value of string functions + that return character strings is always of type `string`. + + + +### Variable Length and Fixed Length Character Strings + +Built-in character-like types in ABAP are as follows: + +| Type | Length | Value Range | Initial Value | +|---|---|---|---| +| `string` | Variable, i. e. the length of [data objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_object_glosry.htm "Glossary Entry") of this type can change during the execution during the execution of ABAP programs (hence, they are also referred to as [dynamic data objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendynamic_data_object_glosry.htm "Glossary Entry")); no standard length | Any characters | Empty string with length 0 | +| `c` | Data objects of this type contain a string of fixed length (between 1 and 262143 characters); standard length: 1 | Any characters | blank for every position | +| `n` | Same as for c | Any characters; valid values are only the digits 0 to 9.
Note that the restrictions for this type to only accept digits are not enforced, hence, fields may contain invalid data. The type is especially used for digits that are not meant for arithmetic calculations like zip codes or article numbers. | "0" for every position | + +> **💡 Note**
+> [Byte-like data +types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbyte_like_data_typ_glosry.htm "Glossary Entry") +(`x`, `xstring`) and types that are specializations of +the type `c` (`n`, `d` referring to date and +`t` referring to time) are not covered in this cheat sheet. + +> **⚡ Differences between variable length and fixed length strings**
+>- **Initial value**: The initial value of variable length strings is an + empty string with length 0. Fixed length strings have a standard + length of 1 character. +>- **Performance**: Data objects of both type `c` and + `string` are considered as [elementary data + objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenelementary_data_object_glosry.htm "Glossary Entry"). + However, data objects of type `string` are internally + managed as + [references](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreference_glosry.htm "Glossary Entry") + and are, thus, considered as + [deep](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendeep_glosry.htm "Glossary Entry"). + This fact enables the performance boosting concept of + [sharing](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensharing_glosry.htm "Glossary Entry") + for data objects of this type when making value assignments. +>- **Length**: Theoretically, a variable length string can use up to 2 GB. + The maximum length of a fixed length string is 262143 characters. +>- **Handling trailing blanks**: Usually, the [operand + position](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenoperand_position_glosry.htm "Glossary Entry") + determines whether trailing blanks are respected or not. Fixed + length strings usually ignore trailing blanks; variable length + strings respect them. For example, if a fixed length string is + assigned to a variable length string, the target string does not + contain any trailing blanks. Note in this context the section + *Condensing Strings*. +>- **Flexibility**: Variable length strings are more flexible than fixed + length strings because you can easily shorten or extend them without + worrying that, for example, parts of the character string are + truncated when processing. +>- **Specifying values** for character strings in the ABAP source code + ([literals](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenliteral_glosry.htm "Glossary Entry")) + with the types `c` and `string`: With quotes + (`'...'`), you create [text field + literals](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentext_field_literal_glosry.htm "Glossary Entry") + of type `c`, with backquotes (
\`...\`), you create [text
+ string
+ literals](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentext_string_literal_glosry.htm "Glossary Entry")
+ of type `string`.
+
+So, when to actually use what? Fixed length strings make sense when
+actually determining a maximum or mandatory length, e. g. a country code
+that must consist of a maximum of two characters or input fields in
+forms that should not exceed a certain length. If restricting a string
+is not relevant, variable length strings are a good choice.
+
+
+
+## Declaring Character-Like Data Types and Objects
+
+Character-like data types and objects are declared like other types and
+objects using
+[`TYPES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptypes.htm)
+and
+[`DATA`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapdata.htm)
+statements. This cheat sheet focuses on the built-in types `c`
+and especially on `string` in most examples.
+
+Syntax examples:
+``` abap
+"Type declarations using built-in types
+
+TYPES: c_type TYPE c LENGTH 3, "Explicit length specification
+ str_type TYPE string.
+
+"Data object declarations using built-in, local and DDIC types
+
+DATA: flag TYPE c LENGTH 1, "Built-in type
+ str1 TYPE string, "Built-in type
+ char1 TYPE c_type, "Local type
+ str2 LIKE str1, "Deriving type from a local data object
+ str3 TYPE str_type, "Local type
+ char2 TYPE s_toairp, "DDIC type (used e. g. for a field in a demo table)
+ char3 TYPE spfli-carrid. "Using the type of a DDIC table component
+
+"You might also stumble upon declarations with type c and the length
+"specified in parentheses. It is not recommended so as not to confuse
+"with the use of parentheses in dynamic programming.
+
+DATA char(4) TYPE c.
+```
+
+
+
+## Assigning Values
+
+When declaring character-like data objects, you can directly provide
+default values. For the assignment of values, you can, for example, use
+the [assignment
+operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenassignment_operator_glosry.htm "Glossary Entry")
+`=`. To do both data object declaration and value assignment in
+one go, you can make use of [inline
+declaration](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_inline.htm)
+that supports declarations in [write
+positions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwrite_position_glosry.htm "Glossary Entry").
+In doing so, a variable specified in parentheses preceded by
+`DATA` on the left side of the assignment operator automatically
+derives a data type from the operand on the right. This helps make your
+programs leaner.
+
+Syntax examples:
+``` abap
+"Data object declarations including default values with VALUE
+DATA: flag TYPE c LENGTH 1 VALUE 'X',
+ str1 TYPE string VALUE `Hallo!`.
+
+"Examples for type n
+DATA zip_code TYPE n LENGTH 5 VALUE '12345'.
+DATA isbn_number TYPE n LENGTH 13 VALUE '1234567890123'.
+
+"More data object declarations
+DATA: char1 TYPE c LENGTH 5,
+ html TYPE string,
+ str2 LIKE html.
+
+"Value assignments
+char1 = 'ab123'.
+html = `hallo
`. + +"Escaping backquotes in text string literals with another one +str1 = `This is a backquote: ``.`. + +"If possible, avoid unnecessary type conversion; in principle, every +"convertible type can be specified +str2 = 'abc'. "Fixed length string assigned to data object of type string +DATA str3 TYPE string VALUE 'X'. "type c length 1 +DATA str4 TYPE string VALUE -1. "type i + +"Inline declarations +DATA(char2) = 'abcd'. "Type c length 4 +DATA(str5) = `efgh`. + +"Since char2 is of type c length 4 (the length is also derived), +"characters are truncated in the following example assignment +char2 = 'ijklmnopq'. "ijkl + +"Trailing blanks after assigning fixed length to variable length string +DATA(char3) = 'ab '. +DATA(str6) = `cdefgh`. +str6 = char3. "'ab' (trailing blanks are not respected due to conversion rule) +``` + +When assigning strings, not only data objects can be placed on the right +side. Various expressions and strings can be chained using the +[concatenation +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconcatenation_operator_glosry.htm "Glossary Entry") +`&&`. Alternatively, you might chain strings using [string +templates](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_template_glosry.htm "Glossary Entry") +and as outlined in the section [Concatenating Strings]. `Concatenating Strings`. +``` abap +str5 = str3 && ` ` && str4 && `!`. "X 1-! +"Note the output for str4 that includes the conversion of type i to +"string above demonstrating a possibly inadvertent specification +"of an integer value for str4 that is of type string. +``` + +Note that there is also the [literal +operator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenliteral_operator_glosry.htm "Glossary Entry") +`&` that joins [text string +literals](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentext_string_literal_glosry.htm "Glossary Entry"), +however, with [significant +differences](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenliteral_operator.htm) +to `&&`. + + + +## String Templates +Using string templates, you can construct strings very elegantly from +literal text and - which is the primary use case - by also including +embedded ABAP +[expression](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenexpression_glosry.htm "Glossary Entry") +within a pair of delimiter characters: `|...|` if these expressions can be converted to `string`. To embed expressions, you include them within curly brackets: `{ ... }`. + +> **💡 Note**+> String templates form a [string +expression](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_expression_glosry.htm "Glossary Entry") +that is compiled at runtime. Hence, a string template that only contains +literal text is handled like an expression which has impact on the +performance. In such a case, using a text string literal with backquotes +is preferable. + +Syntax examples: +``` abap +"Value assignment with string templates +"The expression must be convertible to a string. A blank (not within the curly brackets) +"means a blank in the resulting string. +DATA(s1) = |Hallo { cl_abap_context_info=>get_user_technical_name( ) }!|. + +DATA(s2) = `How are you?`. "Literal text only with backquotes +DATA(s3) = |{ s1 } { s2 }|. "Hallo ...! How are you? + +"Chaining of string templates using && +DATA(s4) = |{ s1 }| && ` ` && |{ s2 }|. "Hallo ...! How are you? +``` + +String templates interpret certain character combinations as [control +characters](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenstring_templates_separators.htm). +For example, `n` is interpreted as line feed. A new line is +set. Plus, string templates support various [formatting +options](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcompute_string_format_options.htm). +Check the ABAP Keyword Documentation for all options. + +Syntax examples: +``` abap +"Control characters +s4 = |{ s1 }\n{ s2 }\nSee you.|. "\n is interpreted as a line feed + +"Various formatting options +"Time and date +"Formatting according to the user master data +DATA(d) = |The date is { cl_abap_context_info=>get_system_date( ) DATE = USER }.|. + +"Formatting in accordance with ISO 8601 +DATA(tm) = |The time is { cl_abap_context_info=>get_system_time( ) TIME = ISO }.|. + +"Formatting to UTC; date and time are represented in ISO 8601 +DATA(ts) = |Timestamp: { utclong_current( ) TIMESTAMP = SPACE }.|. + +"Lowercase and uppercase +s1 = |AbCdEfG|. +s2 = |{ s1 CASE = LOWER }|. "abcdefg +s2 = |{ s1 CASE = UPPER }|. "ABCDEFG + +"Width and alignment +s1 = `##`. +s2 = |{ s1 WIDTH = 10 ALIGN = LEFT }<---|. "'## <---' +s2 = |{ s1 WIDTH = 10 ALIGN = CENTER }<---|. "' ## <---' + +"PAD: Used to pad any surplus places in the result with the specified character. +s2 = |{ s1 WIDTH = 10 ALIGN = RIGHT PAD = `.` }<---|. "'........##<---' + +"Numbers +s1 = |{ CONV decfloat34( - 1 / 3 ) DECIMALS = 3 }|. "'-0.333' +``` + +> **💡 Note**
+> Escape `|{}` in string templates using `\`, i. e. `\\` means `\`. + + + +## Determining the Length of Strings + +To determine the length of a string you can use the string function +[`strlen`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlength_functions.htm). +Note that the result depends on the type of the string, i. e. the result +for a data object of type `string` includes trailing blanks. A +fixed length string does not include them. To exclude trailing blanks in +all cases irrespective of the data type, you can use the built-in +function +[`numofchar`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlength_functions.htm). + +Syntax examples: +``` abap +"strlen +DATA(len_c) = strlen( 'abc ' ). "3 +DATA(len_str) = strlen( `abc ` ). "6 + +"numofchar +len_c = numofchar( 'abc ' ). "3 +len_str = numofchar( `abc ` ). "3 +``` + + + +## Concatenating Strings + +Two or more strings can be concatenated using the concatenation operator +`&&` and string templates. Alternatively, you can use +[`CONCATENATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapconcatenate.htm) +statements. It is also possible to concatenate lines of internal tables +into a string to avoid a loop. In a more modern way, you can make use of +the string function +[`concat_lines_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconcatenation_functions.htm). + +Syntax examples: +``` abap +"&& and string template +s1 = `AB` && `AP`. "ABAP +s2 = `ab` && `ap` && ` ` && s1. "abap ABAP +s3 = |{ s1 }. { s2 }!|. "ABAP. abap ABAP! + +"CONCATENATE statements +CONCATENATE s1 s2 INTO s3. "ABAPabap ABAP + +"Multiple data objects and target declared inline +CONCATENATE s1 ` ` s2 INTO DATA(s5). "ABAP abap ABAP + +CONCATENATE s1 s2 s5 INTO DATA(s6). "ABAPabap ABAPABAP abap ABAP + +"You can also add a separation sign using the addition SEPARATED BY +CONCATENATE s1 s2 INTO s3 SEPARATED BY ` `. "ABAP abap ABAP + +CONCATENATE s1 s2 INTO s3 SEPARATED BY `#`. "ABAP#abap ABAP + +"Keeping trailing blanks in the result when concatenating fixed length +"strings. The ones of variable length strings are respected by default. +CONCATENATE 'a ' 'b ' 'c ' INTO DATA(ch) RESPECTING BLANKS. "'a b c ' + +"Concatenating lines of internal tables into a string +CONCATENATE LINES OF itab INTO t SEPARATED BY ` `. + +"Using concat_lines_of +s1 = concat_lines_of( table = itab ). "Without separator +s1 = concat_lines_of( table = itab sep = ` ` ). "With separator +``` + + + +## Splitting Strings + +You can use +[`SPLIT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapsplit.htm) +statements to split strings in multiple segments. The result of the +splitting can be stored in separate data objects or internal tables that +have a character-like line type. Note that if the specified targets are +fewer than the segments retrieved by the splitting, the last target is +given the rest of the segments that have not yet been split. If there +are more targets specified, the targets not given a segment are +initialized. Hence, specifying individual targets with `SPLIT` +statements is useful if the number of expected segments is known. +Otherwise, splitting into tables is a good choice. + +If you want to get the value of a specific segment, you can use the +string function +[`segment`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensegment_functions.htm). + +Syntax examples: +``` abap +s1 = `Hallo,world,123`. + +SPLIT s1 AT `,` INTO s2 s3 s4. "s2 = Hallo / s3 = world / s4 = 123 + +"Less data objects than possible splittings +SPLIT s1 AT `,` INTO s2 s3. "s2 = Hallo / s3 = world,123 + +"Splitting into internal table +DATA itab TYPE TABLE OF string. +SPLIT s1 AT ',' INTO TABLE itab. "Strings are added to itab in individual lines without comma + +"String function segment returning the occurrence of a segment +"index parameter: number of segment +s2 = segment( val = s1 index = 2 sep = `,` ). "world +``` + + + +## Modifying Strings +**Transforming to Lowercase and Uppercase** + +The string functions +[`to_lower`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencase_functions.htm) +and +[`to_upper`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencase_functions.htm) +transform characters of a string to either lowercase or uppercase and +store the result in a target variable. If the transformation should be +applied to the source directly, you can use +[`TRANSLATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptranslate.htm) +statements. + +Syntax examples: +``` abap +"String functions +s1 = to_upper( `abap` ). "ABAP +s1 = to_lower( `SOME_FILE.Txt` ). "some_file.txt + +"TRANSLATE statements +s1 = `Hallo`. +TRANSLATE s1 TO UPPER CASE. "HALLO +TRANSLATE s1 TO LOWER CASE. "hallo +``` + +**Shifting Content** + +You can shift content within a string to a specific position on the left +or right of a string. +[`SHIFT`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapshift.htm) +statements have different additions for specific use cases. + +In a more modern way, you can use the string functions +[`shift_left`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenshift_functions.htm) +and +[`shift_right`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenshift_functions.htm) +that store the result in a variable. These functions offer an additional +functionality. The `sub` parameter can be used to specify a +substring. All substrings in the string that match the specified value +in `sub` either on the left or right side of the string are +removed. + +Syntax examples: +``` abap +"SHIFT statements +"Note that all results below refer to s1 = `hallo`. +s1 = `hallo`. "Type string + +SHIFT s1. "No addition; string shifted one place to the left: allo +SHIFT s1 BY 2 PLACES. "Without direction, left by default: llo +SHIFT s1 BY 3 PLACES RIGHT. "With direction, variable length strings are extended: ' hallo' + +"Note that all results below refer to ch4 = 'hallo'. +DATA(ch4) = 'hallo'. "Type c length 5 + +SHIFT ch4 BY 3 PLACES RIGHT. "Fixed length string: ' ha' + +"CIRCULAR addition: characters that are moved out of the string are +"added at the other end again +SHIFT ch4 BY 3 PLACES LEFT CIRCULAR. "lohal +SHIFT ch4 UP TO `ll`. "Shift characters up to a specific character set: llo + +"Deleting leading and trailing characters +s2 = ` hallo `. +s3 = s2. + +SHIFT s2 LEFT DELETING LEADING ` `. "'hallo ' +SHIFT s3 RIGHT DELETING TRAILING ` `. "' hallo' (length is kept) + +"Removing trailing blanks for strings without leading blanks with this sequence +s4 = `hallo `. +SHIFT s4 RIGHT DELETING TRAILING ` `. "' hallo' +SHIFT s4 LEFT DELETING LEADING ` `. "'hallo' + +"String functions with parameters +s1 = `hallo`. + +s2 = shift_left( val = s1 places = 3 ). "lo +s2 = shift_left( val = s1 circular = 2 ). "lloha + +"Note that shift_right does not extend a variable length string. +s2 = shift_right( val = s1 places = 3 ). "ha +s2 = shift_right( val = `abc ` sub = ` ` ). "'abc' +s2 = shift_right( val = `abc ` ). "'abc' (same result as above) +``` + +**Condensing Strings** + +You can use +[`CONDENSE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcondense.htm) +statements or the string function +[`condense`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencondense_functions.htm) +to remove blanks in strings. The advantage of using the string function +is that you can also specify any characters to be removed and not only +blanks. + +Syntax examples: +``` abap +"CONDENSE statements +s1 = ` ab cd `. +s2 = ` ef gh ij `. +s3 = ` kl mn op `. + +CONDENSE s1. "Trailing and leading blanks are removed: 'ab cd' +CONDENSE s2. "It also replaces sequences of multiple blanks with a single blank: 'ef gh ij' +CONDENSE s3 NO-GAPS. "Removes all blanks: 'klmnop' + +"String function condense +s1 = ` ab cd `. + +"No parameters specified, i. e. their default values are provided. +"Works like CONDENSE statement without the NO-GAPS addition. +s2 = condense( s1 ). "ab cd + +"Parameters del/to not specified. from parameter with initial string +"(could also be a text field literal: from = ' '). This way, leading and +"trailing blanks are removed. +s2 = condense( val = s1 from = `` ). "ab cd + +"Parameter to specified with an initial string. No other parameters. +"Works like CONDENSE statement with the NO-GAPS addition. +s2 = condense( val = s1 to = `` ). "abcd + +"Parameter del specifies the leading/trailing characters to be removed. +s2 = condense( val = `##see###you##` del = `#` ). "see###you + +"If from and to are specified along with del, leading/trailing +"characters specified in del are first removed. Then, in the remaining string, all +"substrings composed of characters specified in from are replaced with +"the first character of the string specified in the to parameter +s2 = condense( val = ` Rock'xxx'Roller` del = `re ` + from = `x` to = `n` ). "Rock'n'Roll +``` + +**Reversing Strings** + +The string function +[`reverse`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreverse_functions.htm) +reverses a string: +``` abap +"Result: 'abap' +s1 = reverse( `paba` ). +``` + +**Inserting Content** + +The string function +[`insert`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeninsert_functions.htm) +inserts a substring into any position within a given string. Using +various parameters, you can construct your desired string: + +- `val`: Original string. +- `sub`: Substring. +- `off`: Optionally sets the offset, i. e. the position where to add the substring. The default value is 0. When using the function with the default value, the result is like concatenating a string with `&&` (like `res = sub && text`). + +Syntax examples: +``` abap +"Result: 'abcdefghi' +s1 = insert( val = `abcghi` sub = `def` off = 3 ). + +"Result: 'defabcghi' +s1 = insert( val = `abcghi` sub = `def` ). +``` + + + +## Processing Substrings + +Using the string function +[`substring`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstring_functions.htm), +you can specify the position (parameter `off`) and the length +(`len`) of a substring that should be extracted from a given +string (`val`). At least one of the two parameters `off` +or `len` must be specified. The default value of `off` +is 0, i. e. when using the default value, the substring is extracted +from the beginning of the string. Not specifying `len` means +that the rest of the remaining characters are respected. If the offset +and length are greater than the actual length of the string, the +exception `CX_SY_RANGE_OUT_OF_BOUNDS` is raised. + +You might also stumble on the syntax for accessing substrings via offset +and length specification using the `+` character after a variable. Here, the +length is specified within parentheses. Providing an asterisk (`*`) means +that the rest of the remaining string is respected. This syntax option +even enables write access on substrings for fixed length strings. Read +access is possible for both fixed length and variable length strings. +However, this syntax might be confused with the use of tokens in the +context of dynamic programming. + +There are further string functions available to deal with substrings, +for example, +[`substring_after`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstring_functions.htm), +[`substring_before`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstring_functions.htm), +[`substring_from`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstring_functions.htm) +and +[`substring_to`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensubstring_functions.htm). + +These functions offer more options in terms of parameters, for example, +a [PCRE regular +expression](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpcre_regex_glosry.htm "Glossary Entry") +which are dealt with further down. + +Syntax examples: +``` abap +s1 = `Lorem ipsum dolor sit amet`. "Type string + +"Extracting substring starting at a specific position +"'len' not specified means the rest of the remaining characters are +"respected +s2 = substring( val = s1 off = 6 ). "ipsum dolor sit amet + +"Extracting substring with a specific length +"'off' is not specified and has the default value 0. +s2 = substring( val = s1 len = 5 ). "Lorem + +"Specifying both off and len parameters +s2 = substring( val = s1 off = 6 len = 5 ). "ipsum + +DATA(ch5) = 'Lorem ipsum dolor sit amet'. "Type c + +"Offset and length specification using the + sign after a variable +DATA(ch6) = ch2+0(5). "Lorem + +"* means respecting the rest of the remaining string +DATA(ch7) = ch2+12(*). "dolor sit amet + +CLEAR ch5+11(*). "Lorem ipsum + +ch5+0(5) = 'Hallo'. "Hallo ipsum dolor sit amet + +"Further string functions +s1 = `aa1bb2aa3bb4`. + +"Extracting a substring ... +"... after a specified substring +s2 = substring_after( val = s1 sub = `aa` ). "1bb2aa3bb4 (only the first occurrence is respected) + +"... after a specified substring specifying the occurence in a string +"and restricting the length +s2 = substring_after( val = s1 sub = `aA` occ = 2 len = 4 case = abap_false ). "3bb4 + +"... before a specified substring +s2 = substring_before( val = s1 sub = `b2` ). "aa1b + +"... from a specified substring on. It includes the substring specified +"in sub. len/off and other parameters are possible. +s2 = substring_from( val = s1 sub = `a3` ). "a3bb4 + +"... up to a specified substring. It includes the substring specified +"in sub. len/off and other parameters are possible. +s2 = substring_to( val = s1 sub = `3b` ). "aa1bb2aa3b +``` + + + +## Searching and Replacing + +In ABAP, there are a lot of options to carry out search and replace +operations with strings. This includes the use of [comparison +operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomp_operator_glosry.htm "Glossary Entry") +or the prominent ABAP statements +[`FIND`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapfind.htm) +and +[`REPLACE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapreplace.htm), +or the more modern built-in string functions +[`find`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm) +and +[`replace`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreplace_functions.htm), +among others, with their considerable amount of additions or parameters +respectively. Many of these options support rather simple operations +with respect to only single characters or more complex, pattern-based +operations on character sequences using [PCRE regular +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpcre_regex_glosry.htm "Glossary Entry"). + + + +### Searching for Specific Characters + +- You can use the [comparison + operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomp_operator_glosry.htm "Glossary Entry") + [`CA`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains any) or its negation + [`NA`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains not any) in [comparison + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomparison_expression_glosry.htm "Glossary Entry") + to determine if any character of a given character set is contained + in a string. Such an expression is true if at least one character is + found. + - The search is case-sensitive. + - The system variable `sy-fdpos` contains the offset of + the first found character. If nothing is found, + `sy-fdpos` contains the length of the string. + - Note that offset 0 stands for the very first position. +- The string functions + [`find_any_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm) + or its negation + [`find_any_not_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm) + return the offset of the occurrence of any character contained in a + substring. + - If nothing is found, the value -1 is returned + - There are further optional parameters possible. For example, the + specification of `occ` determines the search + direction, i. e. a positive value means the search is performed + from left to right. A negative value means searching from right + to left. +- If the position of characters is not of interest but rather how + often characters occur in a string, you can use the string functions + [`count_any_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm) + or its negation + [`count_any_not_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm). +- To determine if a string only contains a specific set of characters, + you can use the comparison operators + [`CO`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains only) or its negation + [`CN`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains not only) in comparison expressions. + - Regarding `CO`, a comparison is true if the left operand + only contains characters that are also contained in the right + operand. If the comparison is not true, you can get the position + of the first character from text that is not contained in the + character set via `sy-fdpos`. Regarding `CN`, a + comparison is true if a string not only contains characters from + the character set. + +Syntax examples: +``` abap +s1 = `cheers`. +IF s1 CA `aeiou` ... "true, sy-fdpos = 2 +IF s1 NA `xyz`... "true, sy-fdpos = 6 + +s2 = find_any_of( val = s1 sub = `aeiou` ). "2 +s2 = find_any_not_of( val = s1 sub = `c` ). "1 + +s2 = count_any_of( val = s1 sub = `e` ). "2 +s2 = count_any_not_of( val = s1 sub = `s` ). "5 + +IF s1 CO `rs` ... "not true, sy-fdpos = 0 +IF s1 CN `cheers` ... "not true, sy-fdpos = 6 +``` + + + +### Replacing Specific Characters in Strings + +You can use the string function +[`translate`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentranslate_functions.htm) +to replace specific characters by others. Here, the parameter +`from` denotes the characters to be placed in a string and +`to` specifies the target characters. Note: The +replacement is done as follows: Each character specified in +`from` is replaced by the character in `to` that is on +the same position, i. e. the second character in `from` is +replaced by the second character specified in `to`. If there is +no equivalent in `to`, the character in `from` is +removed from the result. + +Using +[`TRANSLATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptranslate.htm) +statements, you can carry out replacements directly on the source field. + +Syntax examples: +``` abap +s1 = `___abc_def_____ghi_`. +s2 = translate( val = s1 from = `hi_` to = `##` ). "abcdefg## +s2 = translate( val = s1 from = `_` to = `##` ). "###abc#def#####ghi# + +"TRANSLATE statement. The value after USING is interpreted as a string composed of character pairs. +"Starting with the first pair, a search is performed in text for the +"first character in every pair and each occurrence is replaced with the +"second character of the pair. +TRANSLATE s1 USING `_.a#g+`. "...#bc.def.....+hi. +``` + + + +### Searching for Substrings in Strings + +- For simple substring searches, you can use the [comparison + operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomp_operator_glosry.htm "Glossary Entry") + [`CS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains string) or its negation + [`NS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) + (contains no string) in [comparison + expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomparison_expression_glosry.htm "Glossary Entry"). + Here, the search is not case-sensitive. The system variable + `sy-fdpos` contains the offset of the found substring. If + the substring is not found, `sy-fdpos` contains the length + of the searched string. +- For more complex and iterating search operations, it can be + beneficial to use `FIND` statements or the string function + [`find`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensearch_functions.htm). + If you are only interested in the offset of a substring within a + string, the string function offers more options than using the + logical operator, for example, you can specify if the search should + be case-sensitive or not. You can also further restrict the search + using parameters. +- Find out how often a substring occurs using the string function + [`count`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencount_functions.htm). + Special variants are available: + [`count_any_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencount_functions.htm), + [`count_any_not_of`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencount_functions.htm). +- Since the string function `find` is derived from the ABAP + statement `FIND`, `FIND` covers the same + functionality as mentioned above and beyond using the many addition + options. + +Syntax examples: +``` abap +s3 = `cheers`. + +IF s3 CS `rs` ... "true, sy-fdpos = 4 + +IF s3 NA `xyz`... "not true, sy-fdpos = 6 + +"String function find +s1 = `Pieces of cakes.`. + +s2 = find( val = s1 sub = `OF` case = abap_false ). "7 + +s2 = find( val = s1 sub = `hallo` ). "-1 (no occurrence returns -1) + +s2 = find( val = s1 sub = `ce` off = 1 len = 7 ). "3 + +"Parameter occ: Positive value means the nth position from the left, +"a negative value the nth position from the right +s2 = find( val = s1 sub = `es` occ = -1 ). "13 + +"String function count +s2 = count( val = s1 sub = `es` ). "2 + +"FIND statements with selected additions +s1 = `abc def ghi abc`. + +FIND `def` IN s1. +IF sy-subrc = 0. "If there is an occurrence, sy-subrc is set to 0. + ... "Some action +ENDIF. +FIND SUBSTRING `abc` IN s1. "Addition SUBSTRING is optional + +FIND `aBC` IN s1 IGNORING CASE. "Case-insensitive search + +"MATCH additions can be specified individually or combined +FIND ALL OCCURRENCES OF `abc` IN s1 + MATCH COUNT DATA(fcnt) "2 (number of occurrences) + MATCH OFFSET DATA(foff) "12 (offset of last occurrence) + MATCH LENGTH DATA(flen). "3 (length of last occurrence) + +"Finding the first occurrence +FIND FIRST OCCURRENCE OF `abc` IN s1 MATCH OFFSET foff. "0 + +"Returning all of these pieces of information in a table for all occurrences +FIND ALL OCCURRENCES OF `abc` IN s1 RESULTS DATA(fres). + +"Restricting the search area (OFFSET/LENGTH can be specified individually) +FIND `abc` IN SECTION OFFSET 4 LENGTH 11 OF s1 + MATCH OFFSET foff. "12 + +"Searching in internal tables; search results are returned in an internal table +DATA(str_table) = VALUE string_table( ( `ZxZ` ) ( `yZ` ) ( `Zz` ) ). + +FIND ALL OCCURRENCES OF `Z` IN TABLE str_table RESULTS + DATA(findings) RESPECTING CASE. +``` + + + +### Replacing Substrings in Strings + +Using the string function +[`replace`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenreplace_functions.htm), +you can store the result of a substring replacement in a separate +variable. What makes it very powerful in particular is the fact that it +returns a value and can, thus, be used in almost all [read +positions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenread_position_glosry.htm "Glossary Entry"). +Using +[`REPLACE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapreplace.htm) +statements, you can carry out replacements on strings directly +(including substrings, which is not possible with the string function). +Regarding the multiple additions `REPLACE` offers, +`REPLACE` is syntactically similar to `FIND`. Regarding +the parameters of `replace`: +- `with`: The replacement text. +- `sub`: Specifies the substring to be replaced. +- `case`: Sets the case sensitivity. +- `occ`: Specifies the number of occurrences of a substring. The default value is `1`, i. e. the first occurrence starting from the left. Setting `occ` to `0` means that all occurrences are respected for the replacement. + +Syntax examples: +``` abap +s1 = `abc def ghi abc`. + +s2 = replace( val = s1 sub = `def` with = `###` ). "abc ### ghi abc + +s2 = replace( val = s1 sub = `ABC` with = `###` case = abap_false occ = 2 ). "abc def ghi ### + +s2 = replace( val = s1 sub = `abc` with = `###` occ = 0 ). "### def ghi ### + +"REPLACE statements with selected additions +"Note that all results below refer to s1 = `abc def ghi abc`. +REPLACE `def` IN s1 WITH `###`. "abc ### ghi abc + +REPLACE FIRST OCCURRENCE OF `abc` IN s1 WITH `###`. "### def ghi abc + +REPLACE `abc` IN s1 WITH `###`. "### def ghi abc (first found is replaced) + +REPLACE SUBSTRING `abc` IN s1 WITH `###`. "### def ghi abc (SUBSTRING is optional) + +REPLACE ALL OCCURRENCES OF `abc` IN s1 WITH `###`. "### def ghi ### + +REPLACE `aBC` IN s1 WITH `###` IGNORING CASE. "### def ghi abc + +"REPLACEMENT additions; can be specified individually or combined +REPLACE ALL OCCURRENCES OF `abc` IN s1 WITH `###` "### def ghi ### + REPLACEMENT COUNT DATA(cnt) "2 (number of replacements) + REPLACEMENT OFFSET DATA(off) "12 (offset of last replacement) + REPLACEMENT LENGTH DATA(len). "3 (length of last substring inserted) + +"Returning all of these pieces of information in a table for all replacements +REPLACE ALL OCCURRENCES OF `abc` IN s1 WITH `###` + RESULTS DATA(res). "### def ghi ### + +"Position-based replacement (OFFSET/LENGTH can be specified individually ) +REPLACE SECTION OFFSET 4 LENGTH 7 OF s1 WITH `###`. "abc ### abc + +"Replacements in internal tables +DATA(str_tab) = VALUE string_table( ( `ZxZ` ) ( `yZ` ) ( `Zz` ) ). + +REPLACE ALL OCCURRENCES OF `Z` + IN TABLE str_tab WITH `` + RESPECTING CASE. "x / y / z +``` + +## Pattern-Based Searching and Replacing in Strings + +You can carry out complex search and replace operations based on +patterns. [PCRE regular +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpcre_regex_glosry.htm "Glossary Entry") +help you process strings effectively. +> **💡 Note**
+> Do not use [POSIX +regular +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenposix_regex_glosry.htm "Glossary Entry") +any more since they are obsolete. + + + +### Simple Pattern-Based Searching Using Comparison Operators + +For simple patterns, you can use the [comparison +operators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomp_operator_glosry.htm "Glossary Entry") +[`CP`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) +(conforms to pattern) or its negation +[`NP`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlogexp_strings.htm) +(does not conform to pattern) in [comparison +expressions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomparison_expression_glosry.htm "Glossary Entry") +to determine if a set of characters is contained in a string that +matches a certain pattern. For the patterns, you can use the following +special characters: + +| Special Character | Details | +|---|---| +| `*` | Any character sequence (including blanks). | +| `+` | Any character (only one character, including blanks). | +| `#` | Escape character. The following character is marked for an exact comparison. | + +Patterns are not case-sensitive except for characters marked by +`#`. If a pattern is found, the system variable +`sy-fdpos` returns the offset of the first occurrence. +Otherwise, it contains the length of the searched string. +``` abap +s1 = `abc_def_ghi`. + +"Pattern: f is preceded by any character sequence, must be followed +"by '_' and then followed by any character sequence +IF s1 CP `*f#_*`. ... "true; sy-fdpos = 6 + +"Pattern: 'i' is not followed by another character +IF s1 NP `i+`. ... "true; sy-fdpos = 11 (length of searched string) +``` + + + +### Complex Searching and Replacing Using Regular Expressions + +**Excursion: Common Regular Expressions** + +There are various options to carry out complex searching in strings using PCRE expressions. They can be fairly complex. The following overview shows common PCRE expressions with simple examples. + +Characters and character types + +| Expression | Represents | Example | Matches | Does not Match | +|---|---|---|---|---| +| `.` | Any single character | `.` | a, 9, Ä, # | aa, empty | +| `\d` | Any digit (0-9) | `\d` | 1, 3, 7 | A, b, c | +| `\D` | Any character that is not a digit, equivalent to `[^0-9]` | `\D` | D, e, f | 4, 5, 8 | +| `\s` | Any whitespace character such as a blank, tab and new line | `\s`
(example string: hi there) | the blank in between | hi | +| `\S` | Any character that is not a whitespace | `\S`
(example string: a 1) | a, 1 | the blank in between | +| `\w` | Any word character (letter, digit or the underscore), equivalent to `[a-zA-Z0-9_]` | `\w`
(example string: ab 12) | a, b, 1, 2 | the blank in between | +| `\W` | Any character that is not a word character, equivalent to `[^a-zA-Z0-9_]` | `\W`
(example string: cd 34) | the blank in between | c, d, 3, 4 | +| `\...` | To include special characters like
[] \ / ^, use `\` to escape them. Use `\.` to match a period ("."). | `\\` | `\` | `/` |
+
+
+Repetitions and Alternatives
+
+| Expression | Represents | Example | Matches | Does not Match |
+|---|---|---|---|---|
+| `r*` | Zero or more repetitions of `r` | `ab*` | a, ab, abb, abbb | b, aba |
+| `r+` | One or more repetitions of `r` | `ab+` | ab, abb, abbb | a, b, aba |
+| `r{m,n}` | Between `m` and `n` repetitions | `a{2,4}` | aa, aaa, aaaa | a, aaaaa, aba |
+| `r{m}` | Exactly `m` repetitions | `a{3}` | aaa | a, aa, aaaa, bbb |
+| `r?` | Optional `r` | `ab?a` | aa, aba | abba, aca |
+| `r\|s` | Matching alternatives, i. e. `r` or `s` | `a+\|b+` | a, b, aa, bb, aaa | ab, aabb |
+
+
+Character Sets, Ranges, Subgroups and Lookarounds
+| Expression | Represents | Example | Matches | Does not Match |
+|---|---|---|---|---|
+| `[aA1-]` | Character set, matches a single character present in the list | `[aA1-]` | a, A, 1, - | b, B, cc, 3 |
+| `[a-z0-9]` | Character range, matches a single character in the specified range, note that ranges may be locale-dependent | `[a-c0-5]` | b, c, 2, 4 | d, Z, x, 9 |
+| `[^aA1]` | Negation, matches any single character not present in the list | `[^aA1]` | b, C, 3, - | a, A, 1 |
+| `[^0-9]` | Negation, matches any single character not within the range | `[^0-9]` | a, B, c | 1, 2, 3 |
+| `(...)` | Capturing group to group parts of patterns together | `a(b\|c)a` | aba, aca | aa, abca |
+| `(?=...)` | Positive lookahead, returns characters that are followed by a specified pattern without including this pattern | `a(?=b)` (example string: abc ade) | the first a | the second a | +| `(?!...)` | Negative lookahead, returns characters that are not followed by a specified pattern without including this pattern | `a(?!b)`
(example string: abc ade) | the second a | the first a | +| `(?<=...)` | Positive lookbehind, returns characters that are preceded by a specified pattern without including this pattern | `(?<=\s)c`
(example string: ab c abcd) | the first c since it is preceded by a blank | the second c | +| `(?example string: ab c abcd) | the second c since it is not preceded by a blank | the first c | + +> **💡 Note**
+> Subgroups are handy in replacements. Using an expression with `$` and a number, e. g. `$1`, you can refer to a particular group. For example, you have a string `abcde`. A PCRE expression might be +`(ab|xy)c(d.)`, i. e. there are two subgroups specified within two pairs of parentheses. In a replacement pattern, you can refer to the first group using `$1` and the second group using `$2`. Hence, the replacement pattern `$2Z$1` results in `deZab`. + +Anchors and Positions + +| Expression | Represents | Example | Matches | Does not Match | +|---|---|---|---|---| +| `^` | Beginning of line, alternative: `\A` | `^a.`
(example string: abcde) | ab | bc | +| `$` | End of line, alternative: `\Z` | `$`
(example string: abcde) | the position right after e | any other position | +| `\b` | beginning and end of word | 1) `\ba\d`
2) `\Dd\b`
(example string: abcd a12d) | 1) `a1`
2) `cd` | 1) `ab`
2) `2d` | + + + +### Searching Using Regular Expressions + +Multiple string functions support PCRE expressions by offering the +parameter `pcre` with which you can specify such an expression. +`FIND` and `REPLACE` statements support regular +expressions with the `PCRE` addition. + +The string function +[`match`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmatch_functions.htm) +exclusively works with regular expressions. It returns a substring that +matches a regular expression within a string. For comparisons, you could +also use the [predicate +function](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpredicate_function_glosry.htm "Glossary Entry") +[`matches`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmatches_functions.htm) +that returns true or false if a string matches a given pattern or not. + +Syntax examples: +``` abap +s1 = `Cathy's black cat on the mat played with Matt.`. + +"Determining the position of the first occurrence +"Here, the parameter occ is 1 by default. +s2 = find( val = s1 pcre = `at.` ). "1 + +"Determining the number of all occurrences. +"Respects all 'a' characters not followed by 't', all 'at' plus 'att' +s2 = count( val = s1 pcre = `at*` ). "6 + +"Respects all 'at' plus 'att' +s2 = count( val = s1 pcre = `at+` ). "4 + +"Extracting a substring matching a given pattern +s1 = `The email address is jon.doe@email.com.`. +s2 = match( val = s1 + pcre = `\w+(\.\w+)*@(\w+\.)+(\w{2,4})` ). "jon.doe@email.com + +"Predicate function matches +"Checking the validitiy of an email address +s1 = `jon.doe@email.com`. +IF matches( val = s1 + pcre = `\w+(\.\w+)*@(\w+\.)+(\w{2,4})` ). "true +... +ENDIF. + +"Examples with the FIND statement +"Storing submatches in variables. +"Pattern: anything before and after ' on ' +FIND PCRE `(.*)\son\s(.*)` IN s1 IGNORING CASE SUBMATCHES DATA(a) DATA(b). +"a = 'Cathy's black cat' / b = 'the mat played with Matt'. + +"Determinging the number of letters in a string +FIND ALL OCCURRENCES OF PCRE `[A-Za-z]` IN s1 MATCH COUNT DATA(c). "36 + +"Searching in an internal table and retrieving line, offset, length information +DATA(itab) = value string_table( ( `Cathy's black cat on the mat played with the friend of Matt.` ) ). +"Pattern: 't' at the beginning of a word followed by another character +FIND FIRST OCCURRENCE OF PCRE `\bt.` IN TABLE itab + IGNORING CASE MATCH LINE DATA(d) MATCH OFFSET DATA(e) MATCH LENGTH DATA(f). "d: 1, e: 21, f: 2 +``` + + +### Replacing Using Regular Expressions + +To carry out replacement operations using regular expressions both +string function `replace` and `REPLACE` statements can +be used with the `pcre` parameter or the `PCRE` addition +respectively. Similar to the `find` function, among others, and +`FIND` statements, the `replace` function and +`REPLACE` statements offer a variety of parameters or additions +respectively to further restrict the area to be replaced. Check the ABAP +Keyword Documentation for a more detailed insight. The executable +example covers numerous PCRE expressions listed above with the +`replace` function. + +Syntax examples: +``` abap +s1 = `ab apppc app`. + +"Replaces 'p' with 2 - 4 repetitions, all occurences +s2 = replace( val = s1 pcre = `p{2,4}` with = `#` occ = 0 ). "ab a#c a# + +"Replaces any single character not present in the list, all occurences) +s2 = replace( val = s1 pcre = `[^ac]` with = `#` occ = 0 ). " "a##a###c#a## + +"Replaces first occurence of a blank +s2 = replace( val = s1 pcre = `\s` with = `#` ). "ab#apppc app + +"Greedy search +"The pattern matches anything before 'p'. The matching is carried out as +"often as possible. Hence, in this example the search stretches until the +"end of the string since 'p' is the final character, i. e. this 'p' and +"anything before is replaced. +s2 = replace( val = s1 pcre = `(.*)p` with = `#` ). "# + +"Non-greedy search (denoted by '?' below) +"The pattern matches anything before 'p'. The matching proceeds until +"the first 'p' is found and does not go beyond. It matches as few as +"possible. Hence, the first found 'p' including the content before +"is replaced. +s2 = replace( val = s1 pcre = `(.*?)p` with = `#` ). "#ppc app + +"Replacements with subgroups +"Replaces 'pp' (case-insensitive here) with '#', the content before and after 'pp' is switched +s2 = replace( val = s1 pcre = `(.*?)PP(.*)` + with = `$2#$1` case = abap_false ). "pc app#ab a + +"Changing the source field directly with a REPLACE statement; same as above +REPLACE PCRE `(.*?)PP(.*)` IN s1 WITH `$2#$1` IGNORING CASE. "pc app#ab a +``` + + + +## Executable Example +[zcl_demo_abap_string_proc](./src/zcl_demo_abap_string_proc.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/08_EML_ABAP_for_RAP.md b/08_EML_ABAP_for_RAP.md new file mode 100644 index 0000000..f245fdd --- /dev/null +++ b/08_EML_ABAP_for_RAP.md @@ -0,0 +1,1183 @@ + + +# ABAP for RAP: Entity Manipulation Language (ABAP EML) + +- [ABAP for RAP: Entity Manipulation Language (ABAP EML)](#abap-for-rap-entity-manipulation-language-abap-eml) + - [Excursion: EML in the Context of RAP](#excursion-eml-in-the-context-of-rap) + - [ABAP Behavior Pools (ABP)](#abap-behavior-pools-abp) + - [RAP Handler Classes and Methods](#rap-handler-classes-and-methods) + - [RAP Saver Class and Saver Methods](#rap-saver-class-and-saver-methods) + - [BDEF Derived Types](#bdef-derived-types) + - [Components of BDEF Derived Types](#components-of-bdef-derived-types) + - [EML Syntax](#eml-syntax) + - [EML Syntax for Modifying Operations](#eml-syntax-for-modifying-operations) + - [EML Syntax for Reading Operations](#eml-syntax-for-reading-operations) + - [Persisting to the Database](#persisting-to-the-database) + - [EML Statements in ABAP Behavior Pools](#eml-statements-in-abap-behavior-pools) + - [Excursion: Using Keys and Identifying RAP BO Instances in a Nutshell / RAP Concepts](#excursion-using-keys-and-identifying-rap-bo-instances-in-a-nutshell--rap-concepts) + - [Further Information](#further-information) + - [Executable Examples](#executable-examples) + +## Excursion: EML in the Context of RAP + +[ABAP Entity Manipulation Language](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenaeml_glosry.htm) (or EML for short) is a subset of ABAP that allows you to access the data of [RAP](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenarap_glosry.htm) business objects in an ABAP program. +The following points are meant to touch on RAP-related buzzwords like +*RAP business objects* and others for setting the context: + +- RAP business objects (RAP BO) + - A RAP BO is based on a special, tree-like hierarchical structure + of [CDS + entities](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_entity_glosry.htm "Glossary Entry") + of a data model + - Such a structure of entities consists of [parent + entities](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenparent_entity_glosry.htm "Glossary Entry") + and [child + entities](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenchild_entity_glosry.htm "Glossary Entry") + that are themselves defined using [CDS + compositions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_composition_glosry.htm "Glossary Entry") + and [to-parent + associations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abento_parent_association_glosry.htm "Glossary Entry"). + - The top parent entity of a [CDS composition + tree](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_composition_tree_glosry.htm "Glossary Entry") + is the root entity that represents the business object. With a + large composition tree, RAP BOs can be fairly complex. Or they + can be very simple by just consisting of one root entity alone. + - Note: There is a special syntax for the CDS root view + entity of a RAP BO: [`define root view + entity`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_define_root_view_v2.htm) +- [CDS behavior + definition](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_behavior_definition_glosry.htm "Glossary Entry") + (BDEF) + - RAP BOs are described by the definitions specified in a special + [DDIC](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddic_glosry.htm "Glossary Entry") + artifact: CDS behavior definition (BDEF) + - A BDEF defines the [RAP business object + behavior](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_behavior_glosry.htm "Glossary Entry") + (i. e. the transactional behavior of a RAP BO) + - Transactional behavior means a BDEF defines [behavior + characteristics](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_entity_properties_glosry.htm "Glossary Entry") + and [RAP BO + operations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_operation_glosry.htm "Glossary Entry") i. + e. [RAP BO standard + operations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_standard_operation_glosry.htm "Glossary Entry") + ([CRUD + operations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencrud_glosry.htm "Glossary Entry")), + [non-standard + operations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_nstandard_operation_glosry.htm "Glossary Entry") + like specific [RAP + actions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_action_glosry.htm "Glossary Entry") + and + [functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_function_glosry.htm "Glossary Entry"), + and more. + - There are many other things that can be included impacting the + RAP BO behavior like [RAP feature + control](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_feature_control_glosry.htm "Glossary Entry"), + for example, defining which data is mandatory and which is + read-only, or + [determinations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_determination_glosry.htm "Glossary Entry") + and + [validations](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_validation_glosry.htm "Glossary Entry"). + - BDEFs use [Behavior Definition + Language](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_glosry.htm "Glossary Entry") + (BDL) for the definitions. Find more information on the topic + and various options to define the transactional behavior in + section [BDL for Behavior + Definitions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl.htm) + in the ABAP Keyword Documentation. +- Transactional buffer and implementation types + - A BDEF defines the behavior of a RAP BO and, thus, how to handle + its data. This data is available in the [RAP transactional + buffer](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentransactional_buffer_glosry.htm "Glossary Entry"). + - It is a storage for a RAP BO's data that is used and worked on + during a [RAP + LUW](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_luw_glosry.htm "Glossary Entry"). + - This data includes [RAP BO + instances](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_instance_glosry.htm "Glossary Entry") + (i. e. concrete data sets of an entity). This is where EML + enters the picture: EML is used to access this data in the + transactional buffer. + - Currently, there are two kinds of RAP BOs: + [managed](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmanaged_rap_bo_glosry.htm "Glossary Entry") + and [unmanaged RAP + BOs](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenunmanaged_rap_bo_glosry.htm "Glossary Entry"). + - Managed and unmanaged are implementation types that are also + specified in the BDEF. + - The implementation type determines the [RAP BO + provider](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_provider_glosry.htm "Glossary Entry"), i. + e. how the transactional buffer is provided and how the behavior + of a RAP BO is implemented. +- Managed RAP BOs: + - The managed RAP BO provider fully or partly provides the + transactional buffer and RAP BO behavior (for standard + operations only). In this case, the developers need not cater + for the transactional buffer and implement the standard + operations. This implementation is mostly relevant for + greenfield scenarios when starting from scratch. + - Example: Regarding CRUD operations in managed RAP BOs, + developers need not cater for an implementation at all. The + standard operations work out of the box. For example, in case of + an update operation, RAP BO instance data that is to be updated + is automatically read into the transactional buffer, and then + updated accordingly there. Finally, when triggering the saving, + the updated instance in the transactional buffer is + automatically saved to the database without any custom + development needed. + - The transactional buffer is provided, too. You do not need to + create the buffer yourself. + - Note: Usually, the behavior of a RAP BO requires some + additional implementations also in the context of managed RAP + BOs. For example, non-standard operations or feature controls + must be self-implemented in [ABAP behavior + pools](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbehavior_pool_glosry.htm "Glossary Entry") + (see the details further down). +- Unmanaged RAP BOs: + - Everything must be provided by the [unmanaged RAP BO + provider](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenunmanaged_rap_bo_prov_glosry.htm "Glossary Entry"), i. + e. the transactional buffer and all RAP BO operations must be + provided or self-implemented by developers in an ABAP behavior + implementation + - Unmanaged RAP BOs are, for example, relevant for brownfield + scenarios, i. e. in scenarios in which business logic is already + available and should be embedded in the RAP world. +- ABAP behavior implementation in an ABAP behavior pool (ABP) + - An [ABAP behavior + pool](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbehavior_pool_glosry.htm "Glossary Entry") + is a special [class + pool](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenclass_pool_glosry.htm "Glossary Entry") + for an ABAP behavior implementation that implements the + unmanaged RAP BO provider based on definitions in a BDEF. The + class pool's name is specified in the BDEF. + - The [global + class](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenglobal_class_glosry.htm "Glossary Entry") + of a behavior pool does not implement the behavior itself. It is + basically empty. The behavior implementation is coded in local + [RAP handler + classes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_handler_class_glosry.htm "Glossary Entry") + and a [RAP saver + class](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_saver_class_glosry.htm "Glossary Entry") + in the [CCIMP + include](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenccimp_glosry.htm "Glossary Entry") + of the behavior pool. These classes are called by the [RAP + runtime + engine](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_runtime_engine_glosry.htm "Glossary Entry") + when the RAP BO is accessed. This is touched on in more detail + further down. + - Usually, saver classes are not needed in managed RAP BOs (except + for special variants of managed RAP BOs which are not touched on + here). Local handler classes are, as mentioned above, usually + needed in managed RAP BOs if implementations are required that + go beyond standard operations. + - Note: In more complex scenarios, with RAP BOs that + consist of many entities, you can define behavior pools for + individual entities by adding the syntax to the [`define + behavior + for`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_define_beh.htm) + notation. There is not a saver class for each entity but only + one saver class for the BO as a whole. Any number of behavior + pools can be assigned to a BDEF allowing applications a + structuring into multiple units. + +There are more artifacts and concepts related to RAP that go way beyond +the scope of this cheat sheet. For example, a RAP BO can be exposed as a +[business +service](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbusiness_service_glosry.htm "Glossary Entry") +to be accessed from outside [AS +ABAP](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenas_abap_sys_environ_glosry.htm "Glossary Entry") +and consumed. A [RAP BO +consumer](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_consumer_glosry.htm "Glossary Entry") +is either the [RAP transactional +engine](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_transac_engine_glosry.htm "Glossary Entry") +that handles requests from outside the AS ABAP or, from inside AS ABAP, +an ABAP program using ABAP EML (which this cheat sheet and the examples +focus on). + + + +## ABAP Behavior Pools (ABP) + +As mentioned above, you can access RAP BO data from inside AS ABAP using +EML. Among other things, EML allows you to read or modify RAP BOs by +accessing the RAP BO data (the RAP BO instances) in the transactional +buffer and trigger the persistent storage or reset changes. More +precisely, when EML statements are executed, the calling of [RAP handler +methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_handler_method_glosry.htm "Glossary Entry") +is triggered to access the transactional buffer of a RAP BO. As +mentioned, for unmanaged RAP BOs or unmanaged parts of managed RAP BOs, +the handler methods that are called are part of an ABAP behavior pool. + +The global class of an ABP has the addition [`FOR BEHAVIOR OF +bdef`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapclass_for_behavior_of.htm) +to the definition while `bdef` stands for the name of the BDEF. +This class is usually empty. + +The implementation is done in local classes in the CCIMP include. There, +two kinds of local classes are to be defined and implemented that are +related to the RAP BO's runtime: one or more [handler +classes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_handler_class_glosry.htm "Glossary Entry") +to implement the RAP BO behavior (in RAP handler methods) during the +[RAP interaction +phase](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_int_phase_glosry.htm "Glossary Entry") +(the data reading and modification phase) and a [saver +class](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_saver_class_glosry.htm "Glossary Entry") +to implement the [RAP save +sequence](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_save_seq_glosry.htm "Glossary Entry") +(in [saver +methods](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_saver_method_glosry.htm "Glossary Entry") +to save data from the transactional buffer to the database). + + + +### RAP Handler Classes and Methods + +- One or more handler classes implement the RAP interaction phase. For + modularization purposes, one behavior pool can define multiple + handler classes. For example, each entity can have its own handler + class, or individual handler classes can be defined to distinguish + between reading and changing RAP BO entities. +- A handler class inherits from class + `CL_ABAP_BEHAVIOR_HANDLER`. +- These classes are implicitly `ABSTRACT` and `FINAL` + since instantiating and calling only happens through the RAP runtime + engine. +- [ADT](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenadt_glosry.htm "Glossary Entry") + helps you create the classes and methods (and basically the ABP as + such) when creating the BDEF. A quick fix is available that creates + the method definitions and a skeleton of the implementations + automatically. + +Example: Handler class definition +``` abap +CLASS lhc_root DEFINITION INHERITING FROM cl_abap_behavior_handler. +... +ENDCLASS. +``` +- Handler method definitions include the additions `... FOR ... FOR + ...` followed by the kind of operations. There are various + options depending on the RAP BO operation. +- Depending on the definition in the BDEF, there might be more ABAP + words with dedicated method parameters. For example, an action might + be defined with a result parameter, hence, the method must be + defined with the addition `RESULT` and a parameter. +- The `FOR MODIFY` handler method can handle multiple entities + and operations, i. e. not only create but also update or delete + might be integrated in the method definition. However, it might be + useful to split the handler method into separate methods for better + readability. +- See more details on the handler method definitions in the topic + [`METHODS, FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmethods_for_rap_behv.htm). + +Example: Handler method definitions +``` abap +"Create +METHODS create FOR MODIFY + IMPORTING entities FOR CREATE bdef. + +"Read: Specifying a read result is mandatory. +METHODS read FOR READ + IMPORTING keys FOR READ bdef RESULT result. + +"Action: action name is preceded by the BDEF name and a tilde after FOR ACTION +METHODS some_action FOR MODIFY + IMPORTING keys FOR ACTION bdef~some_action. +``` + +**Parameters of Handler Methods** + +- The handler method definition contains RAP-specific additions like + `FOR MODIFY`, `FOR CREATE` or `FOR READ` as + well as mandatory or optional additions like `RESULT` that + are followed by parameters. +- Nearly all parameters are typed with [BDEF derived + types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_derived_type_glosry.htm "Glossary Entry") + that have special RAP-related components as touched on further down. +- The parameters' names can be chosen freely. This is also true for + the method names except for some predefined names. +- Each handler method must have at least one importing parameter. The + addition `IMPORTING` is optional since it is used + implicitly. In most cases, the whole instance or just the key values + of an instance are imported. +- All handler methods have changing parameters that are usually not + explicitly specified in the definition but implicitly used. The + addition `CHANGING` is not needed. In most cases, these are + [RAP response + parameters](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_response_param_glosry.htm "Glossary Entry"). + The following image shows the F2 information in ADT for the create + handler method. +  +- The response parameters `mapped`, `failed` and + `reported` (the names are predefined) can be considered as + containers for information - information a RAP BO consumer is + provided with by a RAP BO provider, for example, an SAP Fiori app + displays an error message if something went wrong. The availability + of the parameters depends on the handler method used (e. g. + `mapped` is only available for operations creating + instances). + - `mapped`: Used to provide mapping information on RAP BO + instances, for example, which key values were created for given + content IDs ( + [`%cid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid.htm)). + - `failed`: Information for identifying the data set for + which an error occurred in a RAP operation + - `reported`: Used to exchange error messages for each + entity defined in the BDEF and [not related to a specific + entity](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_other.htm). + - Example: Technically, the `reported` parameter is a + [deep + structure](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendeep_structure_glosry.htm "Glossary Entry") + containing, for example, the messages of the root entity and + child entities. For example, if a create operation fails for a + RAP BO instance of the root entity, a message, information about + the instance key and other things can be included in this + parameter which is passed to a RAP BO consumer. You could + imagine that such an error message is displayed on an SAP Fiori + UI if something goes wrong to inform the user. + + + + +### RAP Saver Class and Saver Methods + +- A RAP saver class implements the [RAP save + sequence](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_save_seq_glosry.htm "Glossary Entry"). + A saver class is usually only available in unmanaged RAP BOs (except + for special variants of managed RAP BOs that are not outlined here). +- The saver class is implicitly `ABSTRACT` and `FINAL` + since the instantiating and calling only happens through the RAP + runtime engine. +- A saver class can be defined in the CCIMP include of an ABAP + behavior pool. It includes the definitions and implementations of + RAP saver methods. +- The saver methods consist of a set of predefined methods having + predefined names. Some of them are mandatory to implement, some are + optional. The + [`adjust_numbers`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensaver_adjust_numbers.htm) + method is only available in [late + numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_late_numbering_glosry.htm "Glossary Entry") + scenarios. +- A saver class inherits from class + `CL_ABAP_BEHAVIOR_SAVER`. The saver methods are + declared by redefining predefined methods of the superclass. They + implicitly have response parameters. +- In contrast to RAP handler methods, saver methods do not have data + of RAP BO instances as import parameter. Therefore, instance data + must be handled via the transactional buffer when self-implementing + the saver methods. +- All saver methods are called after at least one successful + modification of data in the current RAP LUW, for example, by + triggering the save sequence using a [`COMMIT + ENTITIES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcommit_entities.htm) + statement. +- Find more information on RAP saver methods + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabp_saver_class.htm). + +Example: Definition of a RAP saver class and saver methods +``` abap +CLASS lsc_bdef DEFINITION INHERITING FROM cl_abap_behavior_saver. + PROTECTED SECTION. + + "For final calculations and data modifications involving all + "BOs in the current RAP LUW + METHODS finalize REDEFINITION. + + "Checks the consistency of the transactional buffer before + "the save method saves data to the database + METHODS check_before_save REDEFINITION. + + "Preliminary IDs are mapped to final keys. Only for late numbering. + METHODS adjust_numbers REDEFINITION. + + "Saves the current state of the transactional buffer to the database + METHODS save REDEFINITION. + + "Clear the transactional buffer + METHODS cleanup REDEFINITION. + METHODS cleanup_finalize REDEFINITION. + +ENDCLASS. +``` + + + +## BDEF Derived Types + +The operands of EML statements and parameters of handler and saver +methods are mainly special messenger tables for passing data and +receiving results or messages, i. e. the communication between a RAP BO +consumer and the RAP BO provider using EML consists (in most cases) of +exchanging data stored in internal tables that have special ABAP types - +[BDEF derived +types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_derived_type_glosry.htm "Glossary Entry"). +These types are tailor-made for RAP purposes. + +As the name implies, the types are derived by the [ABAP runtime +framework](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_runtime_frmwk_glosry.htm "Glossary Entry") +from CDS entities and their behavior definition in the BDEF. With these +special types, a type-safe access to RAP BOs is guaranteed. + +You can create internal tables (using [`TYPE TABLE +FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptype_table_for.htm)), +structures (using [`TYPE STRUCTURE +FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptype_structure_for.htm)) +and data types with BDEF derived types. For all operations and behavior +characteristics defined in the BDEF, types can be derived. + +The syntax uses - similar to the method definitions mentioned before - +the addition `FOR` followed by the operation and the name of an +entity (and, if need be, the concrete name, e. g. in case of an action +defined in the BDEF). + +Each BDEF derived type can be categorized as +[input](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_input_der_type_glosry.htm "Glossary Entry") +or [output derived +type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_output_der_type_glosry.htm "Glossary Entry") +according to its use as importing or exporting parameters in methods of +RAP BO providers. In most cases, structures of type `TYPE STRUCTURE +FOR` can be considered as serving as [work +area](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenwork_area_glosry.htm "Glossary Entry") +and line type of the internal tables. However, there are also structured +derived types that do serve as types for handler method parameters. + +The response parameters `mapped`, `failed` and +`reported` have dedicated derived types: [`TYPE RESPONSE +FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaptype_response_for.htm). +They are deep structures containing the information for the individual +entities of the RAP BO. The components of these structures are internal +tables of appropriate types with `TYPE TABLE FOR`. + +Examples for BDEF derived types: + +``` abap +"Data objects with input derived types (entity = name of a root entity) + +"For an EML create operation + +DATA create_tab TYPE TABLE FOR CREATE entity. + +"For an update operation + +DATA update_tab TYPE TABLE FOR UPDATE entity. + +"Type for create-by-association operations specifying the name of the entity +"and the association + +DATA cba_tab TYPE TABLE FOR CREATE entity\_child. + +"For an action execution; the name of the action is preceded by a tilde + +DATA action_imp TYPE TABLE FOR ACTION IMPORT entity~action1. + +"Data objects with output derived types + +"For a read operation + +DATA read_tab TYPE TABLE FOR READ RESULT entity. + +"For an action defined with a result + +DATA action_res TYPE TABLE FOR ACTION RESULT entity~action2. + +"Examples for structures and types + +DATA create_wa TYPE STRUCTURE FOR CREATE entity. + +"For permission retrieval + +DATA perm_req TYPE STRUCTURE FOR PERMISSIONS REQUEST entity. + +"For retrieving global features + +DATA feat_req TYPE STRUCTURE FOR GLOBAL FEATURES RESULT entity. + +"Type declaration using a BDEF derived type + +TYPES der_typ TYPE TABLE FOR DELETE entity. + +"Response parameters + +DATA map TYPE RESPONSE FOR MAPPED entity. +DATA fail TYPE RESPONSE FOR FAILED entity. +DATA rep TYPE RESPONSE FOR REPORTED entity. +``` +> **💡 Note**
+> Some of the derived types can only be created and accessed in implementation classes. + + + +### Components of BDEF Derived Types + +Many of the BDEF derived types contain components of CDS entities like +key and data fields that retain their original line type, for example, a +messenger table typed with `TYPE TABLE FOR CREATE`. Certainly, +if an instance is to be created, key and field values of a RAP BO +instance are of relevance. + +Yet, all BDEF derived types contain special RAP components serving a +dedicated purpose. The names of these RAP components begin with +`%` to avoid naming conflicts with components of the CDS +entities. The following image shows the F2 information of a BDEF derived +type containing the `%` components and fields from the CDS +entity. + + + +Some of the `%` components are [component +groups](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_group_glosry.htm "Glossary Entry") +summarizing groups of table columns under a single name. In doing so, +they simplify the handling of derived types for developers. For example, +the component group +[`%data`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_data.htm) +contains all primary key and data fields of a RAP BO entity (actually, +by containing the keys, it also contains the component group +[`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_key.htm) +in the case above). The F2 information in ADT helps you find out about +the available components in a variable. The image below shows the +details of `%data` when clicking the `derived type` +link in the first ADT F2 information screen. + + + +The availability of `%` components depends on definitions in the +BDEF. Their availability also depends on more criteria, for example, the +scenario. For example, the component +[`%pid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pid.htm) +that represents a preliminary ID for a RAP BO instance is only available +in [late +numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_late_numbering_glosry.htm "Glossary Entry") +scenarios. The draft indicator +[`%is_draft`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_is_draft.htm) +is only available in the context of +[draft](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_with_draft.htm). + +Find more details on the available components in section [Components of +BDEF Derived +Types](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_comp.htm). + +Bullet points on selected `%` components: + +- [`%cid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid.htm) + - A string to define a content ID. + - Content IDs are used as a unique and preliminary identifier for + RAP BO operations in which instances are created and especially + in cases where the key values of RAP BO instances are not yet + determined + - Assume that you create a RAP BO instance with an EML create + request and the key value has not yet been determined. In the + same request - a save has not yet been triggered - an update is + requested for this RAP BO instance. Using the content ID, it is + guaranteed that the update operation happens for the desired + instance. For this purpose, derived types for operations like + update or delete include the component + [`%cid_ref`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid_ref.htm) + to refer to the content ID `%cid` as the name implies. + - Note: You should always fill `%cid` even if not + needed. The specified content ID is only valid within one ABAP + EML request. +- [`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_key.htm)/[`%tky`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_tky.htm) + - Both are component groups summarizing all primary keys of a RAP + BO instance. + - Where possible, it is recommended that you use `%tky` + instead of `%key`. `%tky` includes + `%key` and also the draft indicator + `%is_draft`. When using `%tky` in non-draft + scenarios, you are prepared for a later, potential switch to a + draft scenario. In doing so, you can avoid lots of adaptations + in your code by manually adding the indicator. +- [`%control`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_control.htm) + - Component group that, for example, contains the names of all key + and data fields of a RAP BO instance which indicate flags. + - Used to get information on which fields are provided or set a + flag for which fields are requested by RAP BO providers or RAP + BO consumers respectively during the current transaction. + - For this purpose, the value of each field in the + `%control` structure is of type + `ABP_BEHV_FLAG`. For the value setting, + you can use the structured constant `mk` of interface + `IF_ABAP_BEHV`. Note that the technical + type is `x length 1`. + - Example: If you want to read data from a RAP BO instance and + particular non-key fields in `%control` are set to + `if_abap_behv=>mk-off`, the values of these fields + are not returned in the result. + + + +## EML Syntax + +The focus is here on selected EML statements. These statements can be +fairly long and various additions are possible. Find more information on +the EML statements +[here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeneml.htm). + +### EML Syntax for Modifying Operations + +The modifying operations covered include the standard operations (using +the additions +[`CREATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), +[`CREATE +BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), +[`UPDATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), +and +[`DELETE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm) +and non-standard operations (actions) using the addition +[`EXECUTE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm). +All EML statements for the mentioned operations begin with +[`MODIFY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities.htm). +The following commented code snippets demonstrate the +[short](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_short.htm) +and [long +form](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entities_long.htm) +of EML `MODIFY` statements. + +Create operation for creating new instances of a RAP BO entity: + +``` abap +"Declaration of data objects using BDEF derived types + +DATA: cr_tab TYPE TABLE FOR CREATE root_ent, "input derived type + mapped_resp TYPE RESPONSE FOR MAPPED root_ent, "response parameters + failed_resp TYPE RESPONSE FOR FAILED root_ent, + reported_resp TYPE RESPONSE FOR REPORTED root_ent. + +"Input derived type for the EML statement is filled using the VALUE operator +"Assumption: key_field is the key field having type i, +"field1 and field2 are data fields with character-like data type. +"Specify %cid even if not used or of interest; it must be unique within a RAP LUW + +cr_tab = VALUE #( + ( %cid = 'cid1' key_field = 1 + field1 = 'A' field2 = 'B' ) + ( %cid = 'cid2' + "Just to demo %data/%key. You can specify fields with or without + "the derived type components + %data = VALUE #( %key-key_field = 2 + field1 = 'C' + field2 = 'D' ) ) ). + +"EML statement, short form +"root_ent must be the full name of the root entity, it is basically the name of the BDEF + +MODIFY ENTITY root_ent + CREATE "determines the kind of operation + FIELDS ( key_field field1 field2 ) WITH cr_tab "Fields to be respected for the + "input derived type and the input + "derived type itself + MAPPED mapped_resp "mapping information + FAILED failed_resp "information on failures with instances + REPORTED reported_resp. "messages +``` + +> **💡 Note**
+> - Addition [`FIELDS ( ... ) WITH`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_fields.htm): + This field selection option specifies which fields are to be + respected for the operation. The derived type, i. e. an internal + table containing the concrete RAP BO instance values, follows + `WITH`. If a field is specified in the field list within the + pair of parentheses after `FIELDS`, the `%control` + flag for this field is automatically set to + `if_abap_behv=>mk-on`. Likewise, if a field is not + contained in the list, the flag in `%control` is set to + `if_abap_behv=>mk-off`. Assume `field2` is not + specified in the list. The value for `field2` will not be + respected (even if a value is specified in the internal table). The + initial value will be used for the field. +>- Retrieving the responses and specifying the parameters is optional. + Assuming a data set with the value 2 for `key_field` + already exists on the database for this BO, you should expect an + entry for this particular instance in the `failed_resp` + operand and potentially an error message in + `reported_resp`, too. Nevertheless, especially in ABP + implementations and depending on the context, you should implement + and fill these parameters according to the [RAP BO + contract](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_contract_glosry.htm "Glossary Entry") + to meet the variety of implementation rules. +>- `%cid` should be provided even if you are not interested in + it and subsequent operations do not require the reference. + +Long form of an EML `MODIFY` statement: +``` abap +MODIFY ENTITIES OF root_ent "full name of root entity + ENTITY root "root or child entity (alias name if available) + CREATE FROM "FROM as further field selection variant + VALUE #( ( %cid = 'cid' "Input derived type created inline + key_field = 3 + field1 = 'E' + field2 = 'F' + %control = VALUE #( "Must be filled when using FROM + key_field = if_abap_behv=>mk-on + field1 = if_abap_behv=>mk-on + field2 = if_abap_behv=>mk-on ) ) ) + MAPPED DATA(m) "Target variables declared inline + FAILED DATA(f) + REPORTED DATA(r). +``` + +> **💡 Note**
+>- The entity specified after `ENTITY` can be either the root + entity itself or a child entity. If an alias is defined, the alias + should be used. +>- The addition `FIELDS ( ... ) WITH` from the previous + snippet is basically a shortcut for the addition + [`FROM`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_fields.htm) + that is used here. When using `FROM`, the values of the + `%control` structure must be specified explicitly. +>- The BDEF derived types can also be created + [inline](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_inline.htm) + as shown in the example using a [constructor + expression](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenconstructor_expression_glosry.htm "Glossary Entry") + for the input derived type and with `DATA` or + [`FINAL`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfinal_inline.htm) + for the responses. +>- The long form allows you to bundle several operations in one + statement, either different operations on the same entity (for + example, deleting some instances and updating some others) or + operations on different entities of the same RAP BO (for example, + creating a root entity instance and related instances of a child + entity in one EML request). Long and short forms are also available + for other EML statements. + +The following EML statement combines multiple operations in one EML +request. It demonstrates the use of `%cid` and +`%cid_ref`. First, two instances are created by specifying +`%cid`. An update operation in the same request only specifies a +certain field within the parentheses of the `FIELDS ( ... ) +WITH` addition which denotes that only this particular field +should be updated. The other field values remain unchanged. The +reference to the instance is made via `%cid_ref`. Consider an +EML request in which no instance to refer to using `%cid_ref` +exists, e. g. for an update operation. You can also make the reference +using the unique key. A delete operation is available in the same +request, too. `DELETE` can only be followed by the addition +`FROM`. In contrast to other derived types, the derived type +that is expected here (`TYPE TABLE FOR DELETE`) only has +`%cid_ref` and the key as components. +``` abap +MODIFY ENTITIES OF root_ent + ENTITY root + CREATE FIELDS ( key_field field1 field2 ) WITH + VALUE #( ( %cid = 'cid4' key_field = 4 + field1 = 'G' field2 = 'H' ) + ( %cid = 'cid5' key_field = 5 + field1 = 'I' field2 = 'J' ) ) + + UPDATE FIELDS ( field2 ) WITH + VALUE #( ( %cid_ref = 'cid4' field2 = 'Z' ) ) + + DELETE FROM + VALUE #( ( %cid_ref = 'cid5' ) "Instance referenced via %cid_ref + ( key_field = 9 ) ) "Instance referenced via the key +... +``` + +EML statement including the execution of an action: +``` abap +MODIFY ENTITIES OF root_ent + ENTITY root + EXECUTE some_action + FROM action_tab + RESULT DATA(action_result) "Assumption: The action is defined with a + "result parameter. + ... +``` + +The following code snippet shows a deep create. First, an instance is +created for the root entity. Then, in the same request, instances are +created for the child entity based on the root instance. In the example +below, the assumption is that a composition is specified in the root +view entity like `composition [1..*] of root_ent as _child` and `key_field` and +`key_field_child` are the keys of the child view entity. The +[`%target`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_target.htm) +component group enters the picture here which contains the target's +primary key and data fields. +``` abap +MODIFY ENTITIES OF root_ent + ENTITY root_ent + CREATE FIELDS ( key_field field1 field2 ) WITH + VALUE #( ( %cid = 'cid6' key_field = 6 + field1 = 'I' field2 = 'J' ) ) + CREATE BY \_child + FIELDS ( key_field_child field1_child field2_child ) WITH + VALUE #( ( %cid_ref = 'cid6' + %target = VALUE #( ( %cid = 'cid_child_1' + key_field_child = 1 + field1_child = 'aa' + field2_child = 'bb' ) + ( %cid = 'cid_child_2' + key_field_child = 2 + field1_child = 'cc' + field2_child = 'dd' ) ) ) ) +... +``` + + + +### EML Syntax for Reading Operations + +- Read-only operations always return a result, i.e. the syntax of the + EML statement requires the addition `RESULT` and an operand. +- When RAP BO instances are read, the returned data include the + current status of instances in the transactional buffer which + includes unsaved modifications on instances. If an instance is not + yet available in the transactional buffer, the currently persisted + data set is automatically read into the transactional buffer. +- Note that read operations are always implicitly enabled for each + entity listed in a BDEF, i. e. there is no extra definition in the + BDEF in contrast to, for example, create or update. + +The following code snippet shows the long form of the EML +[`READ`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapread_entity_entities_op.htm) +statement for reading instances from the root entity. In `READ` +statements, the additions `FIELDS ( ... ) WITH` and +`FROM` can also be used to specify the fields that you intend to +read. Here, the addition [`ALL FIELDS +WITH`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapread_entity_entities_fields.htm) +is available for reading all field values. + +``` abap +READ ENTITIES OF root_ent + ENTITY root_ent + ALL FIELDS WITH + VALUE #( ( key_field = 1 ) "Derived type TYPE TABLE FOR READ IMPORT + "only includes the keys + ( key_field = 2 ) ) + RESULT DATA(result) + FAILED DATA(f) + REPORTED DATA(r). +``` + +Read-by-association operations include the optional addition +[`LINK`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapread_entity_entities_op&sap-language=EN&sap-client=000&version=X&anchor=!ABAP_ONE_ADD@1@&tree=X) +with which you can retrieve the keys of the source and target (i. e. the +associated entity). The by-association operations work reciprocally, i. +e. you can, for example, read a child instance via the parent and a +parent instance via the child, too. + +``` abap +"Read-by association operation: parent to child +READ ENTITIES OF root_ent + ENTITY root_ent + BY \_child + ALL FIELDS WITH VALUE #( ( key_field = 1 ) ) + RESULT DATA(rba_res1) + LINK DATA(links1). + ... + +"Read-by association operation: child to parent +READ ENTITIES OF root_ent + ENTITY child_ent + BY \_parent + ALL FIELDS WITH VALUE #( ( key_field = 1 key_field_child = 1 ) ) + RESULT DATA(rba_res2) + LINK DATA(links2). + ... +``` + + +### Persisting to the Database + +- A [`COMMIT + ENTITIES`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcommit_entities.htm) + statement triggers the RAP save sequence. Without such a statement, + the modified RAP BO instances that are available in the + transactional buffer are not persisted to the database. +- `COMMIT ENTITIES` implicitly includes [`COMMIT + WORK`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcommit.htm). +- Note: `COMMIT ENTITIES` statements cannot be used + in behavior implementations. In case of a natively supported RAP + scenario (for example, when using OData), the `COMMIT + ENTITIES` request is executed automatically. +- There a multiple variants available for the statement as described + in the ABAP Keyword Documentation + [here](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapcommit_entities.htm). +- `COMMIT ENTITIES` statements set the system field + `sy-subrc`. When using `COMMIT ENTITIES`, it is not + guaranteed that `COMMIT WORK` is carried out successfully. + Hence, you should include a check for `sy-subrc` after + `COMMIT ENTITIES` so that you can react to failures + accordingly. + +The following snippet shows a create operation. This operation has only +an impact on the database with the `COMMIT ENTITIES` statement. +Triggering the save sequence means that the execution of the statement +triggers the calling of the saver methods available in the saver class +of a behavior implementation. In managed scenarios (except for some +special variants), the saving is done automatically without implementing +a dedicated saver method. +``` abap +MODIFY ENTITIES OF root_ent + ENTITY root_ent + CREATE FIELDS ( key_field field1 field2 ) WITH + VALUE #( ( %cid = 'cid' key_field = 7 + field1 = 'K' field2 = 'L' ) ). + +COMMIT ENTITIES. + +IF sy-subrc <> 0. + ... +ENDIF. +``` + + + +### EML Statements in ABAP Behavior Pools + +- There are a [special additions when using EML in behavior + pools](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abeneml_in_abp.htm). + One of them is [`IN LOCAL MODE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapin_local_mode.htm). +- This addition can be used to exclude feature controls and + authorization checks. +- Consider the following use case: There is a field to display the + booking status of a trip on a UI. In the BDEF, this field is + specified as read-only. Hence, it cannot be modified by a user on + the UI. However, there is a button on the UI to book the trip. This + button might trigger an action to book the trip so that the value of + the field changes from open to booked. To enable this, the + underlying handler method for the modify operation with the action + to be executed has the addition `IN LOCAL MODE` that ignores + the feature control. + +Syntax: + +``` abap +MODIFY ENTITIES OF root_ent IN LOCAL MODE + ENTITY root + EXECUTE book + FROM action_tab + ... +``` + + + + +## Excursion: Using Keys and Identifying RAP BO Instances in a Nutshell / RAP Concepts + +
+
+ +The following bullet points outline important aspects regarding + keys and identifying [RAP BO +instances](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_instance_glosry.htm "Glossary Entry") in ABAP EML statements. + +**Why is it important?** + +- The [primary + key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenprimary_key_glosry.htm "Glossary Entry") + of a [RAP BO entity instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_entity_inst_glosry.htm "Glossary Entry") + is composed of one or more [key fields](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenkey_field_glosry.htm "Glossary Entry"). +- These key fields stand for the fields that are specified with + `key` in the underlying [CDS view entity](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_v2_view_glosry.htm "Glossary Entry") + of the RAP BO. +- The primary key uniquely identifies each RAP BO entity instance. +- After the creation of an instance and the primary key during a [RAP create operation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_create_operation_glosry.htm "Glossary Entry"), + the primary key cannot be changed. + - Note the concept of [late numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlate_numbering_glosry.htm "Glossary Entry") + where newly created entity instances are given their final key + only shortly before saving in the database. Until then, the + business logic uses a temporary key that has to be replaced. +- If a data set with a particular primary key already exists in the + persistent database table, the saving of a RAP BO instance with a + duplicate primary key is rejected. + +**How can a RAP BO instance be uniquely identified?** + +- It can be done by using a [RAP instance identifier](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_inst_identifier_glosry.htm "Glossary Entry") + or [RAP content identifier](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_cont_identifier_glosry.htm "Glossary Entry") + or both of them. +- RAP instance identifier: + - It consists of the primary key fields and all relevant [BDEF derived type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_derived_type_glosry.htm "Glossary Entry") + components. + - To ease the reference to all of these components, special + [component groups](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_group_glosry.htm "Glossary Entry") + are available to summarize the components and make them + addressable via one single name. + - [`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_key.htm): + Contains the primary key fields of a RAP BO instance + - [`%tky`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_tky.htm): + Specifies the transactional key. Comprises `%key` (and, + thus, the primary key fields of a RAP BO instance) and more + components that are relevant to uniquely identify a RAP BO + instance. Among them, + [`%pid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pid.htm) + (relevant for late numbering scenarios) and the draft indicator + [`%is_draft`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_is_draft.htm) + (relevant for + [draft](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_with_draft.htm) + scenarios). In non-late numbering or non-draft scenarios, these + extra components are just blank. However, it is recommended that + you use `%tky` in all scenarios since it simplifies a + possible later switch, for example, to a draft scenario. In + doing so, lots of adaptations to the code regarding the keys and + the inclusion of `%is_draft` can be avoided. +- RAP content identifier: + - Reflected in the component + [`%cid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid.htm) + which is a string of type + `ABP_BEHV_CID` to define a content ID. + - Used as a unique and preliminary identifier for RAP BO instances + in RAP create operations, especially where no primary key exists + for the particular instance. + - For newly created instances, the ID can then be used for + performing further, referencing modifications on those instances + using + [`%cid_ref`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid_ref.htm) + (which has the same value as `%cid` is then used, for + example, in RAP operations using [`CREATE BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), [`UPDATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm) + and + [`DELETE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), + as well as + [actions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_action.htm) + with + [`EXECUTE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm)). + - In contrast to the primary key and the preliminary ID + `%pid` for late numbering scenarios, `%cid` (and + `%cid_ref`) are only available on a short-term basis + for the current ABAP EML request within the [RAP interaction phase](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_int_phase_glosry.htm "Glossary Entry") in one [RAP LUW](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_luw_glosry.htm "Glossary Entry"). + - **Note:** The specification of `%cid` should be done even if there are no further operations referring to it. +- Special case: Late numbering + - As mentioned above, in late numbering scenarios newly created + entity instances are given their final key only shortly before + saving in the database, i. e. you deal with preliminary keys in + the RAP interaction phase and the early phase of the [RAP save sequence](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_save_seq_glosry.htm "Glossary Entry"). + - In this case, you can use `%key` to hold the preliminary + keys or use a preliminary ID in the dedicated component + [`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pid.htm) + which is of type `ABP_BEHV_PID` and + only available in late numbering scenarios. + - Similar to above, to uniquely identify RAP BO instances in late + numbering scenarios, you can use either `%key` or + `%pid` or both of them. In any case, the use of + `%tky` is handy because it includes both components. You + must ensure that `%tky` in total uniquely identifies the + instances. + - **Note:** A further component group to refer to the keys is available: [`%pky`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pky.htm). `%pky` contains `%pid` and `%key` in late numbering scenarios. In non-late numbering scenarios, it just contains `%key`. `%pky` itself is contained in `%tky`. There are contexts, for example, particular actions, where `%tky` is not available but `%pky` is. This way, there is still the option to summarize `%pid` and `%key` in one component group in the absence of `%tky`. + +**General rule**: A RAP BO instance must always be uniquely +identifiable by its transactional key (`%tky`) for internal +processing during the RAP interaction phase. `%tky` always +contains all relevant components for the chosen scenario. + +
+
+
+Using Keys and Identifying RAP BO Instances in a Nutshell
+ ++ +The following bullet points outline important aspects regarding + keys and identifying [RAP BO +instances](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_instance_glosry.htm "Glossary Entry") in ABAP EML statements. + +**Why is it important?** + +- The [primary + key](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenprimary_key_glosry.htm "Glossary Entry") + of a [RAP BO entity instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_bo_entity_inst_glosry.htm "Glossary Entry") + is composed of one or more [key fields](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenkey_field_glosry.htm "Glossary Entry"). +- These key fields stand for the fields that are specified with + `key` in the underlying [CDS view entity](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_v2_view_glosry.htm "Glossary Entry") + of the RAP BO. +- The primary key uniquely identifies each RAP BO entity instance. +- After the creation of an instance and the primary key during a [RAP create operation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_create_operation_glosry.htm "Glossary Entry"), + the primary key cannot be changed. + - Note the concept of [late numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenlate_numbering_glosry.htm "Glossary Entry") + where newly created entity instances are given their final key + only shortly before saving in the database. Until then, the + business logic uses a temporary key that has to be replaced. +- If a data set with a particular primary key already exists in the + persistent database table, the saving of a RAP BO instance with a + duplicate primary key is rejected. + +**How can a RAP BO instance be uniquely identified?** + +- It can be done by using a [RAP instance identifier](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_inst_identifier_glosry.htm "Glossary Entry") + or [RAP content identifier](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_cont_identifier_glosry.htm "Glossary Entry") + or both of them. +- RAP instance identifier: + - It consists of the primary key fields and all relevant [BDEF derived type](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_derived_type_glosry.htm "Glossary Entry") + components. + - To ease the reference to all of these components, special + [component groups](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencomponent_group_glosry.htm "Glossary Entry") + are available to summarize the components and make them + addressable via one single name. + - [`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_key.htm): + Contains the primary key fields of a RAP BO instance + - [`%tky`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_tky.htm): + Specifies the transactional key. Comprises `%key` (and, + thus, the primary key fields of a RAP BO instance) and more + components that are relevant to uniquely identify a RAP BO + instance. Among them, + [`%pid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pid.htm) + (relevant for late numbering scenarios) and the draft indicator + [`%is_draft`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_is_draft.htm) + (relevant for + [draft](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_with_draft.htm) + scenarios). In non-late numbering or non-draft scenarios, these + extra components are just blank. However, it is recommended that + you use `%tky` in all scenarios since it simplifies a + possible later switch, for example, to a draft scenario. In + doing so, lots of adaptations to the code regarding the keys and + the inclusion of `%is_draft` can be avoided. +- RAP content identifier: + - Reflected in the component + [`%cid`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid.htm) + which is a string of type + `ABP_BEHV_CID` to define a content ID. + - Used as a unique and preliminary identifier for RAP BO instances + in RAP create operations, especially where no primary key exists + for the particular instance. + - For newly created instances, the ID can then be used for + performing further, referencing modifications on those instances + using + [`%cid_ref`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_cid_ref.htm) + (which has the same value as `%cid` is then used, for + example, in RAP operations using [`CREATE BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), [`UPDATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm) + and + [`DELETE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm), + as well as + [actions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_action.htm) + with + [`EXECUTE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapmodify_entity_entities_op.htm)). + - In contrast to the primary key and the preliminary ID + `%pid` for late numbering scenarios, `%cid` (and + `%cid_ref`) are only available on a short-term basis + for the current ABAP EML request within the [RAP interaction phase](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_int_phase_glosry.htm "Glossary Entry") in one [RAP LUW](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_luw_glosry.htm "Glossary Entry"). + - **Note:** The specification of `%cid` should be done even if there are no further operations referring to it. +- Special case: Late numbering + - As mentioned above, in late numbering scenarios newly created + entity instances are given their final key only shortly before + saving in the database, i. e. you deal with preliminary keys in + the RAP interaction phase and the early phase of the [RAP save sequence](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_save_seq_glosry.htm "Glossary Entry"). + - In this case, you can use `%key` to hold the preliminary + keys or use a preliminary ID in the dedicated component + [`%key`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pid.htm) + which is of type `ABP_BEHV_PID` and + only available in late numbering scenarios. + - Similar to above, to uniquely identify RAP BO instances in late + numbering scenarios, you can use either `%key` or + `%pid` or both of them. In any case, the use of + `%tky` is handy because it includes both components. You + must ensure that `%tky` in total uniquely identifies the + instances. + - **Note:** A further component group to refer to the keys is available: [`%pky`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pky.htm). `%pky` contains `%pid` and `%key` in late numbering scenarios. In non-late numbering scenarios, it just contains `%key`. `%pky` itself is contained in `%tky`. There are contexts, for example, particular actions, where `%tky` is not available but `%pky` is. This way, there is still the option to summarize `%pid` and `%key` in one component group in the absence of `%tky`. + +**General rule**: A RAP BO instance must always be uniquely +identifiable by its transactional key (`%tky`) for internal +processing during the RAP interaction phase. `%tky` always +contains all relevant components for the chosen scenario. + +
+
+ +**RAP numbering** + +- A concept that deals with setting values for primary key fields. +- There are multiple options to handle the numbering for primary key + fields depending on when (early in the RAP interaction phase or late + in the RAP save sequence) and by whom (RAP BO consumer, behavior + pool, or framework) the primary key values are set. +- When: + - [Early numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_early_numbering_glosry.htm "Glossary Entry"): + The final key values are assigned during a RAP create operation + in the interaction phase. + - [Late numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_late_numbering_glosry.htm "Glossary Entry"): + The final key values are assigned during the RAP save sequence + (and here only in the RAP saver method + [`adjust_numbers`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensaver_adjust_numbers.htm)). +- By whom + - [External numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_ext_numbering_glosry.htm "Glossary Entry"): + Key values are provided by the RAP BO consumer. For example, in + a create operation, the key values are specified by the RAP BO + consumer like other non-key field values. Basically, this is the + concept with which the snippets above are tailored. + - [Internal numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_int_numbering_glosry.htm "Glossary Entry"): + Key values are provided by the RAP BO provider. For example, in + a create operation, the key values are not specified in an EML + create request by the RAP BO consumer but rather by the RAP BO + provider. In case of a managed RAP BO, the key is automatically + created by the framework which only works if the key is of a + certain type (16-character byte-like + [UUID](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenuuid_glosry.htm "Glossary Entry")). + In case of an unmanaged RAP BO, the key values are provided in a + dedicated handler method which must be self-implemented. Note + that late numbering is internal by default since no further RAP + BO consumer interaction is possible in the late phase of the RAP + save sequence. + +**Draft** + +- The draft concept in RAP allows the content of the transactional + buffer to be stored in intermediate storages ([draft tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendraft_table_glosry.htm "Glossary Entry")) + in order to allow transactions to expand over different ABAP + sessions. +- Like the concepts mentioned above, a RAP BO can be draft-enabled in + the BDEF. This concept enters the picture, for example, if you have + an application allowing data modifications and the temporary storage + of modifications but does not yet persist them to the database. You + can continue modifying this data later and you might even use a + different device from the one where you modified the data + previously. +- The draft indicator `%is_draft` enters the picture here for + RAP BO instance identification. It is used to indicate if a RAP BO + instance is a [draft instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_draft_instance_glosry.htm "Glossary Entry") + or an [active instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_active_instance_glosry.htm "Glossary Entry"). + Conveniently, the component group `%tky` contains + `%is_draft`. `%is_draft` can then be addressed via + `%tky`. + +> **💡 Note**
+> Late numbering and identification in the late phase of the RAP save sequence +>- Context: RAP saver method +> [`adjust_numbers`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensaver_adjust_numbers.htm) +> in which the final key values are assigned; the preliminary keys can +> be included in `%key` or `%pid` or both of them. +>- `%pid` and the preliminary key values in `%key` are +> automatically assigned to the following component groups when +> reaching the `adjust_numbers` method: +> - [`%tmp`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_tmp.htm): +> A component group that is assigned the preliminary key values +> contained in `%key`. In doing so, `%tmp` takes +> over the role that `%key` has had in the RAP interaction +> phase to hold the preliminary key values. +> - `%pid` remains as is. The component group +> [`%pre`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pre.htm) +> contains `%pid` and `%tmp` and, thus, all +> preliminary identifiers. +>- In the `adjust_numbers` method, the preliminary keys are +> transformed into the final keys, i. e. the preliminary keys are +> mapped to `%key` (which holds the final keys in this +> context) in the `mapped` [response parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_response_param_glosry.htm "Glossary Entry"). +>- Depending on your use case to use either `%pid` or (the +> preliminary key values in) `%key` (which is `%tmp` +> here in this method) during the interaction phase or both of them, +> you must ensure that `%pre` in total (since it contains both +> `%pid` and `%tmp`) is unique and mapped to the final +> keys that are to be contained in `%key`. + +
+
+
+
+## Further Information
+
+- Section [ABAP for RAP Business
+ Objects](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_for_rap_bos.htm)
+ in the ABAP Keyword Documentation including EML
+- [Development guide for the ABAP RESTful Application Programming
+ Model](https://help.sap.com/http.svc/ahp2/DRAFT/SAP_S4HANA_ON-PREMISE/2022.000/EN/28/9477a81eec4d4e84c0302fb6835035/frameset.htm)
+- [RAP
+ Contract](https://help.sap.com/http.svc/ahp2/DRAFT/SAP_S4HANA_ON-PREMISE/2022.000/EN/3a/402c5cf6a74bc1a1de080b2a7c6978/frameset.htm):
+ Rules for the RAP BO provider and consumer implementation to ensure
+ consistency and reliability
+
+
+
+
+## Executable Examples
+This cheat sheet is supported by different executable examples demonstrating various scenarios:
+- Demo RAP scenario with a managed RAP BO, external numbering: [zcl_demo_abap_rap_ext_num_m](./src/zcl_demo_abap_rap_ext_num_m.clas.abap)
+- Demo RAP scenario with an unmanaged RAP BO, external numbering: [zcl_demo_abap_rap_ext_num_u](./src/zcl_demo_abap_rap_ext_num_u.clas.abap)
+- Demo RAP scenario ("RAP calculator") with a managed, draft-enabled RAP BO, late numbering [zcl_demo_abap_rap_draft_ln_m](./src/zcl_demo_abap_rap_draft_ln_m.clas.abap)
+
+> **💡 Note**RAP Concepts
+ ++ +**RAP numbering** + +- A concept that deals with setting values for primary key fields. +- There are multiple options to handle the numbering for primary key + fields depending on when (early in the RAP interaction phase or late + in the RAP save sequence) and by whom (RAP BO consumer, behavior + pool, or framework) the primary key values are set. +- When: + - [Early numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_early_numbering_glosry.htm "Glossary Entry"): + The final key values are assigned during a RAP create operation + in the interaction phase. + - [Late numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_late_numbering_glosry.htm "Glossary Entry"): + The final key values are assigned during the RAP save sequence + (and here only in the RAP saver method + [`adjust_numbers`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensaver_adjust_numbers.htm)). +- By whom + - [External numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_ext_numbering_glosry.htm "Glossary Entry"): + Key values are provided by the RAP BO consumer. For example, in + a create operation, the key values are specified by the RAP BO + consumer like other non-key field values. Basically, this is the + concept with which the snippets above are tailored. + - [Internal numbering](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_int_numbering_glosry.htm "Glossary Entry"): + Key values are provided by the RAP BO provider. For example, in + a create operation, the key values are not specified in an EML + create request by the RAP BO consumer but rather by the RAP BO + provider. In case of a managed RAP BO, the key is automatically + created by the framework which only works if the key is of a + certain type (16-character byte-like + [UUID](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenuuid_glosry.htm "Glossary Entry")). + In case of an unmanaged RAP BO, the key values are provided in a + dedicated handler method which must be self-implemented. Note + that late numbering is internal by default since no further RAP + BO consumer interaction is possible in the late phase of the RAP + save sequence. + +**Draft** + +- The draft concept in RAP allows the content of the transactional + buffer to be stored in intermediate storages ([draft tables](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendraft_table_glosry.htm "Glossary Entry")) + in order to allow transactions to expand over different ABAP + sessions. +- Like the concepts mentioned above, a RAP BO can be draft-enabled in + the BDEF. This concept enters the picture, for example, if you have + an application allowing data modifications and the temporary storage + of modifications but does not yet persist them to the database. You + can continue modifying this data later and you might even use a + different device from the one where you modified the data + previously. +- The draft indicator `%is_draft` enters the picture here for + RAP BO instance identification. It is used to indicate if a RAP BO + instance is a [draft instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_draft_instance_glosry.htm "Glossary Entry") + or an [active instance](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_active_instance_glosry.htm "Glossary Entry"). + Conveniently, the component group `%tky` contains + `%is_draft`. `%is_draft` can then be addressed via + `%tky`. + +> **💡 Note**
+> Late numbering and identification in the late phase of the RAP save sequence +>- Context: RAP saver method +> [`adjust_numbers`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensaver_adjust_numbers.htm) +> in which the final key values are assigned; the preliminary keys can +> be included in `%key` or `%pid` or both of them. +>- `%pid` and the preliminary key values in `%key` are +> automatically assigned to the following component groups when +> reaching the `adjust_numbers` method: +> - [`%tmp`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_tmp.htm): +> A component group that is assigned the preliminary key values +> contained in `%key`. In doing so, `%tmp` takes +> over the role that `%key` has had in the RAP interaction +> phase to hold the preliminary key values. +> - `%pid` remains as is. The component group +> [`%pre`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapderived_types_pre.htm) +> contains `%pid` and `%tmp` and, thus, all +> preliminary identifiers. +>- In the `adjust_numbers` method, the preliminary keys are +> transformed into the final keys, i. e. the preliminary keys are +> mapped to `%key` (which holds the final keys in this +> context) in the `mapped` [response parameter](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenrap_response_param_glosry.htm "Glossary Entry"). +>- Depending on your use case to use either `%pid` or (the +> preliminary key values in) `%key` (which is `%tmp` +> here in this method) during the interaction phase or both of them, +> you must ensure that `%pre` in total (since it contains both +> `%pid` and `%tmp`) is unique and mapped to the final +> keys that are to be contained in `%key`. + +
+> - To reduce the complexity, the executable examples are purposely kept simple and only focus on the technical side. ABAP classes play the role of a RAP BO consumer here. +>- The examples do not represent real life scenarios and are not suitable as role models for proper RAP scenarios. They rather focus on the technical side by giving an idea how the communication and data exchange between a RAP BO consumer and RAP BO provider can work. Additionally, the examples show how the methods for non-standard RAP BO operations might be self-implemented in an ABAP behavior pool. +>- Due to the simplification, the examples might not fully meet the requirements of the [RAP BO contract](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenrap_bo_contract_glosry.htm) in many respects. +>- The "RAP calculator" example can be checked out using the preview version of an SAP Fiori Elements UI. See the comments in the class for more information. +>- See the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. diff --git a/09_Bits_and_Bytes.md b/09_Bits_and_Bytes.md new file mode 100644 index 0000000..4fa405e --- /dev/null +++ b/09_Bits_and_Bytes.md @@ -0,0 +1,182 @@ + + +# Excursion Down to Bits and Bytes + +This sheet goes a bit into the technical background of data types and +data objects. It may be helpful for a better understanding of how to +handle data in ABAP including a glance on casting and conversions. + +After its declaration, a [data +object](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abendata_object_glosry.htm "Glossary Entry") +is usable in its context (procedure, class, program) according to its +type. For example, a numeric data object can be assigned the result of a +calculation: + +> **💡 Note**
+> For checking out the code snippets in an SAP BTP ABAP environment, you can use the interface `if_oo_adt_classrun` in a class by implementing the method `if_oo_adt_classrun~main`. + +``` abap +DATA num TYPE i. + +num = 2 * 3 * 5 * 53 * 2267. + +cl_demo_output=>display( num ). +``` + +After this assignment, the data object `num` contains the +calculated value 3604530, which is also displayed accordingly with a +type-compliant output as, for example, +`cl_demo_output=>display`. And of course the same can be seen +in the display of the variable in the ABAP Debugger when setting a +breakpoint at the last statement. + +The ABAP Debugger also shows the hexadecimal value 32003700 of the data +object. This directly represents the binary value `0011 0010 0000 0000 +0011 0111 0000 0000` stored in the 4 bytes allocated to the 4-byte +integer number in the memory. This value is platform dependent and for +numeric types is defined by the [byte +order](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbyte_order_glosry.htm "Glossary Entry") +order, where either the most significant (big endian) or least +significant (little endian) byte is written to the first memory +location. The decimal value of the hexadecimal value `32003700` shown here +would be `838874880` and is not the integer value +`3604530` that ABAP deals with. This shows the meaning of +data types. A data object is a sequence of bytes stored in memory at its +address, which is interpreted by the ABAP runtime framework according to +the data type. The hexadecimal value is in most cases irrelevant to the +programmer. + +Let us now consider a character-like field text with a length of two +characters: + +``` abap +DATA text TYPE c LENGTH 2. + +text = '2' && '7'. + +cl_demo_output=>display( text ). +``` +This field can be assigned the result of a string operation as shown and +the result shown by `cl_demo_output=>display` as well as in +the ABAP Debugger is the character string `27`. Again, it is +the data type, that derives the value `27` from the actual hexadecimal +content, which is `32003700` as in the previous example! In +this case, `32003700` is the encoding of the string +`27` in the Unicode character representation +[UCS-2](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenucs2_glosry.htm "Glossary Entry"), +which is supported by ABAP in Unicode systems. The Unicode character +representation also depends on the platform-dependent byte order. + +Only for a byte-type data type does the value as interpreted by ABAP +directly correspond to the hexadecimal content. The following lines +modify the bits of a byte string with a bit-operation: + +``` abap +DATA hex TYPE x LENGTH 4 VALUE 'CDFFC8FF'. + +hex = BIT-NOT hex. + +cl_demo_output=>display( hex ). +``` + +Here, the output with `cl_demo_output=>display`, the value +display of the ABAP Debugger as well as the hexadecimal value are the +same, namely `32003700`. + +In the above examples, we presented three data objects that all occupy 4 +bytes in memory that have the same binary values, but are handled +differently by ABAP due to their data type. The data type is also +responsible for the fact, that different kind of operations (numeric +calculation, string concatenation, bit-operation) can be applied to the +respective data objects. Using these examples we can have now look at +the basic concepts of +[casting](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencast_casting_glosry.htm "Glossary Entry") +and [type +conversion](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abentype_conversion_glosry.htm "Glossary Entry") +and their relation to bits and bytes. + +In ABAP, the term casting means nothing more than treating a data object +according to a different data type than the one that is permanently +assigned to it. This can be done using [field +symbols](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfield_symbol_glosry.htm "Glossary Entry"), +with which a new (symbolic) name and a new type can be defined for the +memory area of a data object. When the memory area is accessed using a +field symbol, it is handled according to the type of the field symbol. +The following lines show an example. + +``` abap +DATA hex TYPE x LENGTH 4 VALUE '32003700'. +FIELD-SYMBOLS:
+> For reasons of simplicity this sheet is restricted to named elementary +variables. Note that in particular the same holds for +[literals](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_literal_glosry.htm "Glossary Entry") +that are handled internally in such a way as if they were constants of +the data type assigned to the literal. In the preceding example, +`text` can be replaced by a literal `'27'` yielding +the same results. + + diff --git a/10_ABAP_SQL_Hierarchies.md b/10_ABAP_SQL_Hierarchies.md new file mode 100644 index 0000000..9febe82 --- /dev/null +++ b/10_ABAP_SQL_Hierarchies.md @@ -0,0 +1,703 @@ + + +# ABAP SQL: Working with Hierarchies + +This cheat sheet summarizes the functions ABAP SQL offers together with +ABAP CDS for working with [hierarchical +data](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_glosry.htm "Glossary Entry") +that is stored in database tables. Hierarchical data in database tables +means that lines of one or more database tables are connected by +[parent-child +relationships](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenpcr_glosry.htm "Glossary Entry"). +There are many use cases where hierarchical data plays a role and where +accessing information about the hierarchical relationship is important. +For example, a common task can be to find out the descendants or +ancestors of a given hierarchy node or to aggregate values of subtrees. + +- [ABAP SQL: Working with Hierarchies](#abap-sql-working-with-hierarchies) + - [Overview](#overview) + - [SQL Hierarchies](#sql-hierarchies) + - [Creating SQL Hierarchies](#creating-sql-hierarchies) + - [ABAP CDS Hierarchies](#abap-cds-hierarchies) + - [ABAP SQL Hierarchy Generator HIERARCHY](#abap-sql-hierarchy-generator-hierarchy) + - [ABAP CTE Hierarchies](#abap-cte-hierarchies) + - [Hierarchy Navigators](#hierarchy-navigators) + - [Hierarchy Node Navigator HIERARCHY\_DESCENDANTS](#hierarchy-node-navigator-hierarchy_descendants) + - [Hierarchy Node Navigator HIERARCHY\_ANCESTORS](#hierarchy-node-navigator-hierarchy_ancestors) + - [Hierarchy Node Navigator HIERARCHY\_SIBLINGS](#hierarchy-node-navigator-hierarchy_siblings) + - [Hierarchy Aggregate Navigators](#hierarchy-aggregate-navigators) + - [Further Information](#further-information) + + +## Overview + +In former times you had to load the data from the database into internal +tables and program it all by yourself (if you did not find an +appropriate API). In between, +[meshes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmesh_glosry.htm "Glossary Entry") +offered some features for working with hierarchies, as shown in this +[example](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenmesh_for_reflex_sngl_abexa.htm), +but have not found wide distribution. + +Meanwhile, the standard AS ABAP database is a SAP HANA database that +offers a lot of helpful features. Among other things, you will find a +set of hierarchy functions there that allow you to deal with +hierarchical data directly on the database and that you can look up in +the [SAP HANA +documentation](https://help.sap.com/http.svc/ahp2/DRAFT/SAP_S4HANA_ON-PREMISE/2022.000/EN/20/ff532c751910148657c32fe3431a9/frameset.htm). +Now you might expect that you must use +[AMDP](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenamdp.htm) +in order to access these functions from your ABAP programs, but no need +to do so! ABAP SQL and ABAP CDS support hierarchies directly by wrapping +the HANA built-in functions without any loss of performance. You can +stay in the comfortable ABAP world and nevertheless have access to most +modern features. All you have to do, is to understand some concepts and +learn some additional syntax and then you can start right away. + +> **💡 Note**
+> The examples in this cheat sheet are only relevant for [standard ABAP](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenstandard_abap_glosry.htm), i. e. the unrestricted ABAP language scope. Find the artifacts used in the code snippets in your on-premise system. + +## SQL Hierarchies + +With [SQL +hierarchy](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensql_hierarchy_glosry.htm "Glossary Entry") +we denote a special [hierarchical data +source](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_data.htm) +that you can use in the `FROM` clause of ABAP SQL queries. A SQL +hierarchy is a tabular set of rows which form the hierarchy nodes of a +hierarchy and which contains additionally [hierarchy +columns](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_column_glosry.htm "Glossary Entry") +that contain hierarchy attributes with hierarchy-specific information +for each row. For creating a SQL hierarchy, you need the following: + +- Data Source + + This can be any data source you can access normally in an ABAP SQL + query, as most commonly a database table or a CDS view, but also a + CTE (common table expression). The structure and content of the data + source should be able to represent hierarchical data. + +- Parent-Child Relation + + A parent-child relation must be defined between two or more columns + of the data source. From the parent-child relation and the actual + data of the data source, the SQL hierarchy consisting of parent + nodes and child nodes can be created. The parent-child relation must + be defined by a self-association which we call hierarchy + association. This can be achieved with CDS associations or CTE + associations. A data source exposing a hierarchy association can be + used as a hierarchy source for creating a SQL hierarchy. + +- Hierarchy Creation + + From a hierarchy source, that is a data source exposing a hierarchy + association, a SQL hierarchy can be created. This can be done either + by defining a CDS hierarchy outside an ABAP program or with the + hierarchy generator of ABAP SQL directly in the `FROM` + clause of an ABAP SQL query inside an ABAP program. + +The following topics show you step-by-step how SQL hierarchies can be +created and accessed. + +## Creating SQL Hierarchies + +### ABAP CDS Hierarchies +With [CDS +hierarchies](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_column_glosry.htm "Glossary Entry"), +you outsource the hierarchy data source and the creation of the SQL +hierarchy from your ABAP program to ABAP CDS. Here the hierarchy is a +fully fledged CDS entity, it is reusable in different programs or in +other CDS entities (views), and can be part of your data model including +access control using CDS DCL. For a CDS hierarchy, the hierarchy source +cannot be anything else but a CDS view that exposes a [hierarchy +association](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_association_glosry.htm "Glossary Entry"). +Here is a very simple example for that: + +``` abap +@AccessControl.authorizationCheck: #NOT_REQUIRED +define view entity DEMO_CDS_SIMPLE_TREE_VIEW + as select from demo_simple_tree + association [1..1] to DEMO_CDS_SIMPLE_TREE_VIEW as _tree + on $projection.parent = _tree.id +{ + _tree, + key id, + parent_id as parent, + name +} +``` + +This CDS view entity accesses the database table +`DEMO_SIMPLE_TREE`, where the actual data is +stored, and exposes a +[self-association](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenself_association_glosry.htm "Glossary Entry") +`_tree`. The `ON` condition of the association +defines a parent-child relation between the elements `id` and +`parent`. It simply means that a row of the result set where +column `parent` has the same value as the column +`id` of another row is a child of the latter row in the +hierarchy that is constructed from that view. The CDS view exposes also +another column `name` of the database table that represents +the remaining data content. Note that you can define such CDS views for +any available data source and that the `ON` condition can be +more complex than shown in the simple example here. + +Now we can use the above CDS view as the hierarchy source of a CDS +hierarchy that can be defined as follows: + +``` abap +define hierarchy DEMO_CDS_SIMPLE_TREE + with parameters + p_id : abap.int4 + as parent child hierarchy( + source + DEMO_CDS_SIMPLE_TREE_SOURCE + child to parent association _tree + start where + id = :p_id + siblings order by + id ascending + ) + { + id, + parent, + name + } +``` + +The CDS DDL statement [`DEFINE +HIERARCHY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_f1_define_hierarchy.htm) +that can be used in the DDL source code editor of ADT defines a CDS +hierarchy as a CDS entity that can be accessed in CDS views or ABAP SQL +as a SQL hierarchy. The most important additions of the statement are: + +- `SOURCE` for specifying the hierarchy source, here our + `DEMO_CDS_SIMPLE_TREE_VIEW`. +- `CHILD TO PARENT ASSOCIATION` for specifying the + hierarchy association, here `_tree`. +- `START WHERE` for defining the root nodes of the SQL + hierarchy, here represented by an input parameter `p_id` + that must be passed when accessing the CDS hierarchy. +- `SIBLINGS ORDER BY` to define also a sort order for + sibling nodes besides the sort order that comes from the + parent-child relationship anyhow. +- An element list `{ ... }` that defines the columns of + the SQL hierarchy, here simply all elements of the hierarchy source. + +For a full description and all other additions see [`DEFINE +HIERARCHY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_f1_define_hierarchy.htm). + +When you access the CDS hierarchy, all lines are selected from the +original data source, in our case the database table +`DEMO_SIMPLE_TREE`, that fulfill the `START WHERE` condition. Those make up the root node set of the SQL +hierarchy. In the simplest case we have exactly one root node, but more +are possible. Then, for each root node, its descendants are retrieved. +That means each line from the database table that fulfills the +`ON`-condition of the hierarchy association is added to the +SQL hierarchy. And for each descendant this is done again and again +until all descendants are found. And that is basically all! Further +additions to `DEFINE HIERARCHY` allow you to control the +creation of the SQL hierarchy, for example, whether multiple parents are +allowed or how orphans or cycles should be handled. + +Besides the elements of the hierarchy, the element list can also contain +the hierarchy attributes listed under [Hierarchy +Attributes](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abencds_hierarchy_attributes.htm). +Then the SQL hierarchy is enriched with columns containing information +about the role, the current line plays as a hierarchy node, as, for +example, the hierarchy rank or the hierarchy level. In our example, we +did not add such elements, because ABAP SQL does that implicitly for you +when accessing the CDS hierarchy! + +The SQL hierarchy can be used in an ABAP SQL query by using the CDS +hierarchy directly as a data source of the `FROM` clause: + +``` abap +DATA root_id type demo_cds_simple_tree_view-id. + +... + +SELECT FROM demo_cds_simple_tree( p_id = @root_id ) + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(cds_result). +``` + +And although we did not define any hierarchy attributes in the element +list of the CDS hierarchy, we can add all the hierarchy columns listed +under [Hierarchy +Columns](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenddddl_hierarchy.htm) +to the `SELECT` list of our ABAP SQL statement! This is always +possible when a SQL hierarchy is accessed in ABAP SQL. We can pass any +ID to the CDS hierarchy now and see what happens. If such a line is +found in the database table, the respective hierarchical data will be +retrieved and delivered. Execute class +`CL_DEMO_SQL_HIERARCHIES` for filling the +database table with randomly generated data and inspect the tabular +result. As expected, all elements of the `SELECT` list appear as +columns. Note that the content of column `NAME` could be +anything. It is filled here with a string representation of the path +from the root node to the current node for demonstration purposes only. + +From the ABAP language point of view, CDS hierarchies are the most +convenient way of using SQL hierarchies. Now let us turn to other ways, +involving more ABAP, until we do not use any CDS more in the end. + +### ABAP SQL Hierarchy Generator HIERARCHY +The ABAP SQL [hierarchy +generator](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_generator_glosry.htm "Glossary Entry") +is a ABAP SQL function named +[`HIERARCHY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_generator.htm), +that allows you to define a SQL hierarchy in the ABAP program itself. +Let us look directly at an example: + +``` abap +DATA root_id TYPE demo_cds_simple_tree_view-id. + +... + +SELECT FROM HIERARCHY( SOURCE demo_cds_simple_tree_view + CHILD TO PARENT ASSOCIATION _tree + START WHERE id = @root_id + SIBLINGS ORDER BY id + MULTIPLE PARENTS NOT ALLOWED ) "hierarchy +] + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(asql_cds_result). + +ASSERT asql_cds_result = cds_result. +``` + +Looks familiar? Well, almost the same syntax used for defining the CDS +hierarchy is used in the brackets `HIERARCHY( ... )` and it +does exactly the same! The difference is the same as it is between ABAP +SQL joins and joins in CDS views: + +- If you code it in ABAP SQL, it is for usage in one program only. +- If you code it in ABAP CDS, it is for usage in many programs or + whole data models. + +And, as you can see, we dare to prove this with an `ASSERT` +statement. Also note that we use the hierarchy columns again. They exist +implicitly when an SQL hierarchy, here created by the hierarchy +generator, is accessed. + +The above hierarchy generator of ABAP SQL accesses the same hierarchy +source as the CDS hierarchy, namely the CDS view +`DEMO_CDS_SIMPLE_TREE_VIEW` that exposes the necessary +hierarchy association `_tree`. In the following code +snippet, we replace the CDS hierarchy source with a CTE: + +``` abap +DATA root_id type demo_cds_simple_tree_view-id. + +... + +WITH + +cte_simple_tree_source AS + ( SELECT FROM demo_simple_tree + FIELDS id, + parent_id AS parent, + name ) + WITH ASSOCIATIONS ( + JOIN TO MANY +cte_simple_tree_source AS _tree + ON +cte_simple_tree_source~parent = _tree~id ) + SELECT FROM HIERARCHY( SOURCE +cte_simple_tree_source + CHILD TO PARENT ASSOCIATION _tree + START WHERE id = @root_id + SIBLINGS ORDER BY id + MULTIPLE PARENTS NOT ALLOWED ) "hierarchy +] + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(asql_cte_result). ] + +ASSERT asql_cte_result = cds_result. +``` + +Common table expressions (CTEs) are a very powerful tool for defining +subqueries that can be used in subsequent queries of the same +[`WITH`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwith.htm) +statement. They can be regarded as an internal ABAP SQL definition of +data sources that fulfill the same functionality as program external +data sources, especially CDS views. As you see above, the CTE +`cte_simple_tree_source` does the same as the CDS view +`DEMO_CDS_SIMPLE_TREE_VIEW`: + +- It accesses the database table `DEMO_SIMPLE_TREE`. +- It exposes an association `_tree` by using the addition + [`WITH ASSOCIATIONS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwith_associations.htm). + +The main query of the `WITH` statement uses the hierarchy +generator in the same way as the `SELECT` above, just with the +CTE as a data source instead of the CDS view and the result is - of +course - the same. + +For a full description of the hierarchy generator and all other +additions see [`SELECT, FROM HIERARCHY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_generator.htm). + +We managed to create a SQL hierarchy with ABAP SQL means only. Last but +not least we will use CTEs as hierarchies themselves. You might skip the +following section and turn directly to the hierarchy navigators if you +are not too interested in this syntactic gimmicks. + +### ABAP CTE Hierarchies + +A CTE that produces hierarchical data can declare itself as a SQL +hierarchy of a freely defined name with the addition [`WITH HIERARCHY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapwith_hierarchy.htm). +That simply means that subsequent queries of the same `WITH` +statement can use the CTE as a hierarchy with its implicit hierarchy +columns or - more important - in hierarchy navigators. + +The following code snippets show the three ways in which a CTE can +produce hierarchical data: + +``` abap +DATA root_id TYPE demo_cds_simple_tree_view-id. + +... + +WITH + +tree AS + ( SELECT FROM demo_cds_simple_tree( p_id = @root_id ) + FIELDS * ) + WITH HIERARCHY demo_cds_simple_tree + SELECT FROM +tree "hierarchy ] + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(cte_cds_result). + +... + +WITH + +tree AS + ( SELECT FROM HIERARCHY( + SOURCE demo_cds_simple_tree_view + CHILD TO PARENT ASSOCIATION _tree + START WHERE id = @root_id + SIBLINGS ORDER BY id + MULTIPLE PARENTS NOT ALLOWED ) AS asql_hierarchy + FIELDS id, + parent, + name ) + WITH HIERARCHY asql_hierarchy + SELECT FROM +tree "hierarchy ] + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(cte_asql_result). + +... + +WITH + +cte_simple_tree_source AS + ( SELECT FROM demo_simple_tree + FIELDS id, + parent_id AS parent, + name ) + WITH ASSOCIATIONS ( + JOIN TO MANY +cte_simple_tree_source AS _tree + ON +cte_simple_tree_source~parent = _tree~id ), + +tree AS + ( SELECT FROM HIERARCHY( + SOURCE +cte_simple_tree_source + CHILD TO PARENT ASSOCIATION _tree + START WHERE id = @root_id + SIBLINGS ORDER BY id + MULTIPLE PARENTS NOT ALLOWED ) AS cte_hierarchy + FIELDS id, + parent, + name ) + WITH HIERARCHY cte_hierarchy + SELECT FROM +tree "hierarchy ] + FIELDS id, + parent, + name, + hierarchy_rank, + hierarchy_tree_size, + hierarchy_parent_rank, + hierarchy_level, + hierarchy_is_cycle, + hierarchy_is_orphan, + node_id, + parent_id + INTO TABLE @FINAL(cte_cte_result). + +ASSERT cte_cds_result = cds_result. +ASSERT cte_asql_result = cds_result. +ASSERT cte_cte_result = cds_result. +``` + +A CTE that is exposed as a SQL hierarchy must access a SQL hierarchy +itself and in the end these are always based on a CDS hierarchy or the +ABAP SQL hierarchy generator as shown above. Again, the hierarchy source +of the hierarchy generator can be a CDS view or a CTE exposing the +hierarchy association. Running +`CL_DEMO_SQL_HIERARCHIES` shows that all +assertions are fulfilled. + +## Hierarchy Navigators + +[Hierarchy +navigators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_navigator_glosry.htm "Glossary Entry") +are an additional set of [hierarchy +functions](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_function_glosry.htm "Glossary Entry") +in ABAP SQL that allow you to work on existing SQL hierarchies instead +of creating them. Hierarchy navigators can work on SQL hierarchies +created as shown above, namely on CDS hierarchies, the hierarchy +generator or a CTE hierarchy. They can be used as data sources in ABAP +SQL queries. If you need a SQL hierarchy multiple times, from a +performance point of view it is best to create it once with a given set +of root nodes and then access it with hierarchy navigators. Furthermore, +each hierarchy navigator can add further hierarchy columns to the result +set that offer additional options for the evaluation. + +In the following examples, we access our CDS hierarchy with hierarchy +navigators. But you could also replace it with the hierarchy generator +or a CTE hierarchy. Check the examples of the +[documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_navigators.htm), +where this is also shown. + +### Hierarchy Node Navigator HIERARCHY_DESCENDANTS + +As the name says, +[`HIERARCHY_DESCENDANTS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_node_navis.htm) +fetches all descendants for any nodes from a SQL hierarchy. It adds +`HIERARCHY_DISTANCE` as an additional hierarchy column to +the result set. Let us look at an example. All examples are code +snippets from `CL_DEMO_SQL_HIERARCHIES` again. + +``` abap +DATA root_id TYPE demo_cds_simple_tree_view-id. + +DATA sub_id TYPE demo_cds_simple_tree_view-id. + +... + +SELECT FROM HIERARCHY_DESCENDANTS( + SOURCE demo_cds_simple_tree( p_id = @root_id ) + START WHERE id = @sub_id ) + FIELDS id, + parent_id, + name, + hierarchy_distance + INTO TABLE @FINAL(descendants). +``` + +Our CDS hierarchy `DEMO_CDS_SIMPLE_TREE_VIEW` is used to +create a SQL hierarchy with a start node passed to parameter +`p_id` and for a node `sub_id` all descendants +are fetched. Running the program shows the result including the +additional column `HIERARCHY_DISTANCE` that contains the +distance to the respective start node. A further parameter +`DISTANCE` - not shown here - allows you to restrict the +distance to the respective start node. + +### Hierarchy Node Navigator HIERARCHY_ANCESTORS + +Now the other way around: ABAP SQL function +[`HIERARCHY_ANCESTORS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_node_navis.htm) +returns the ancestors of any given node of an existing hierarchy: + +``` abap +DATA root_id TYPE demo_cds_simple_tree_view-id. + +DATA max_id TYPE demo_cds_simple_tree_view-id. + +... + +SELECT FROM HIERARCHY_ANCESTORS( + SOURCE demo_cds_simple_tree( p_id = @root_id ) + START WHERE id = @max_id ) + FIELDS id, + parent_id, + name, + hierarchy_distance + INTO TABLE @FINAL(ancestors). +``` + +Looking at the result when running +`CL_DEMO_SQL_HIERARCHIES`, you see that the +value of column `HIERARCHY_DISTANCE` is negative now. Using +aggregate functions or evaluating the internal result table, you can now +easily extract further information like the number of ancestors and so +on. + +### Hierarchy Node Navigator HIERARCHY_SIBLINGS + +Besides descendants and ancestors, hierarchy nodes also can have +siblings, that is nodes that have the same parent node. You can find +these by looking for all nodes with the same value in hierarchy column +`HIERARCHY_PARENT_RANK`. But there is also +[`HIERARCHY_SIBLINGS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_node_navis.htm) +as a hierarchy function for that: + +``` abap +DATA root_id TYPE demo_cds_simple_tree_view-id. + +DATA sibl_id TYPE demo_cds_simple_tree_view-id. + +... + +SELECT FROM HIERARCHY_SIBLINGS( + SOURCE demo_cds_simple_tree( p_id = @root_id ) + START WHERE id = @sibl_id ) + FIELDS id, + parent_id, + name, + hierarchy_sibling_distance + INTO TABLE @FINAL(siblings). +``` + +You see that this function adds another hierarchy column +`HIERARCHY_SIBLING_DISTANCE` that contains the distance to +the respective start node. Running +`CL_DEMO_SQL_HIERARCHIES`, where we start with +a node that definitely has some siblings, shows the result. + +### Hierarchy Aggregate Navigators + +Finally let us turn to the [hierarchy aggregate +navigators](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenhierarchy_agg_navi_glosry.htm "Glossary Entry") +that allow you to apply some aggregate functions to descendants and +ancestors of any node of a SQL hierarchy: + +- [`HIERARCHY_DESCENDANTS_AGGREGATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_desc_agg.htm) +- [`HIERARCHY_ANCESTORS_AGGREGATE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_ancs_agg.htm) + +We will show an example for the descendants case and refer to the +[documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_ancs_agg.htm) +for the ancestors. + +Applying aggregate functions to columns normally means that you have +some data there for which this makes sense. In our simplistic SQL +hierarchy tree we do not have such meaningful data. On the other hand, +this can also be a use case: You can have the administrative data for +the parent-child relation in one database table and the real data in +another one. And for that use case, the hierarchy aggregate navigator +`HIERARCHY_DESCENDANTS_AGGREGATE` gives you the option of +joining such data to your SQL hierarchy: + +``` abap +TYPES: + BEGIN OF value, + id TYPE i, + amount TYPE p LENGTH 16 DECIMALS 2, + END OF value. + +DATA value_tab TYPE SORTED TABLE OF value WITH UNIQUE KEY id. + +DATA root_id TYPE demo_cds_simple_tree_view-id. + +DATA sub_id TYPE demo_cds_simple_tree_view-id. + +... + +SELECT FROM HIERARCHY_DESCENDANTS_AGGREGATE( + SOURCE demo_cds_simple_tree( p_id = @sub_id ) AS h + JOIN @value_tab AS v + ON v~id = h~id + MEASURES SUM( v~amount ) AS amount_sum + WHERE hierarchy_rank > 1 + WITH SUBTOTAL + WITH BALANCE ) + FIELDS id, + amount_sum, + hierarchy_rank, + hierarchy_aggregate_type + INTO TABLE @FINAL(descendants_aggregate). +``` + +In our example, we join an internal table `value_tab` of the +same program to the SQL hierarchy. In a real life example you would join +another database table, of course. On the other hand the example shows +ABAP SQL's capability of using internal tables as data sources. You +even can go so far to evaluate hierarchical data in internal tables with +ABAP SQL by using an internal table as data source for a CTE hierarchy! + +The example does the following: + +- We use the hierarchy aggregate navigator + `HIERARCHY_DESCENDANTS_AGGREGATE` as a data source of a + `FROM` clause. +- Our CDS hierarchy `DEMO_CDS_SIMPLE_TREE_VIEW` joined + with internal table `value_tab` is used as the data source. +- The ABAP SQL function returns a tabular result of nodes of the data + source. +- The aggregate function `SUM` behind `MEASURES` sums + up the values of the column amounts of the joined internal table for + all descendants of each node returned by the ABAP SQL function. +- The `WHERE` condition restricts the result set by a freely + programmable condition. +- The `WITH` additions add further rows to the result set that + can be recognized by values in an additional hierarchy column + `HIERARCHY_AGGREGATE_TYPE`: + + - `WITH SUBTOTAL` + + In the row where `HIERARCHY_AGGREGATE_TYPE` has + value 1, column `AMOUNT_SUM` contains the sum of the + values of all hierarchy nodes that meet the `WHERE` + condition. + + - `WITH BALANCE` + + In the row where `HIERARCHY_AGGREGATE_TYPE` has + value 2, column `AMOUNT_SUM` contains the sum of the + values of all hierarchy nodes that do not meet the + `WHERE` condition. + + For more `WITH` additions see the + [documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_desc_agg.htm). + +Running `CL_DEMO_SQL_HIERARCHIES` shows the +result. It also shows the result of the joined data source, where you +can check that the calculated values are correct. + +## Further Information +For the complete reference documentation about SQL hierarchies, see [`SELECT, FROM hierarchy_data`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenselect_hierarchy_data.htm). diff --git a/11_ABAP_SQL_Grouping_Internal_Tables.md b/11_ABAP_SQL_Grouping_Internal_Tables.md new file mode 100644 index 0000000..f7087f2 --- /dev/null +++ b/11_ABAP_SQL_Grouping_Internal_Tables.md @@ -0,0 +1,171 @@ + + +# ABAP SQL: Grouping Internal Tables + +- [ABAP SQL: Grouping Internal Tables](#abap-sql-grouping-internal-tables) + - [Introduction](#introduction) + - [Grouping by One Column](#grouping-by-one-column) + - [Grouping by More than One Column](#grouping-by-more-than-one-column) + - [Group Key Binding when Grouping by One Column](#group-key-binding-when-grouping-by-one-column) + - [Group Key Binding when Grouping by More than One Column](#group-key-binding-when-grouping-by-more-than-one-column) + - [Executable Example](#executable-example) + + +## Introduction + +Similar to SQL's [`GROUP BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapgroupby_clause.htm), +there is also a [`GROUP BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by.htm) +for working with internal tables that can be used behind [`LOOP AT itab`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_variants.htm) +or in the form [`IN GROUP`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfor_in_group.htm) +in a table iteration with +[`FOR`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenfor_itab.htm). +It replaces the clumsy group level processing with statements [`AT NEW ...`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abapat_itab.htm) +that relies on the order of table columns and content that is sorted +respectively. + +Thi cheat sheet explains the grouping of internal tables step by step +using a very simple case of an internal table `spfli_tab` that +is filled with data from the database table `SPFLI`. The +following steps show how the content of the internal table can be +grouped using [`LOOP AT GROUP BY`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by.htm). + +## Grouping by One Column + +The simplest form of grouping is by one column without explicitly +specifying the output behavior of the group loop: + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY wa-carrid. + ... wa-carrid ... +ENDLOOP. +``` + +Within the loop, there is access to the work area `wa`, in +particular to the component `wa-carrid` that is used for +grouping. The work area `wa` contains the first line of each +group and represents the group in the loop. This is called +representative binding. + +To access the members of a group, a member loop can be inserted into the +group loop: +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY wa-carrid. + ... + LOOP AT GROUP wa INTO DATA(member). + ... member-... ... + ENDLOOP. + ... +ENDLOOP. +``` + +The member loop is executed using the group represented by `wa` +and its members are assigned to `member` and are available in +the member loop. + +## Grouping by More than One Column + +To group by more than just one criterion, a structured group key is +defined as follows. In the simplest case, the grouping criteria are +columns of the internal table: + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY ( key1 = wa-carrid key2 = wa-airpfrom ). + ... wa-carrid ... wa-airpfrom ... +ENDLOOP. +``` + +This is also a representative binding in which the work area +`wa` is reused in the group loop to access the group key. + +To access the members of the groups, the exact same member loop can be +inserted as when grouping by one column. + +## Group Key Binding when Grouping by One Column + +By explicitly specifying an [output +area](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by_binding.htm) +for the group key, a group key binding can be defined explicitly instead +of the representative binding in which the output area of the group loop +is reused: + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY wa-carrid + INTO DATA(key). + ... key ... +ENDLOOP. +``` + +The difference to the example with representative binding is the +`INTO` addition after `GROUP BY`. Instead of reusing +`wa`, an elementary data object `key` represents the +group. This can be generated inline. The additions [`GROUP +SIZE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by_key.htm), +[`GROUP +INDEX`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by_key.htm), +and [`WITHOUT +MEMBERS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by.htm) +can only be used in the group key binding, which gives it more functions +than the representative binding. If these are not required, the +representative binding can be used. The group key binding can also be +used to make the use of the group key in the loop more explicit. + +Inserting a member loop works in the same way as in the representative +binding, with the difference that a group is now addressed by +`key` instead of `wa`. + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY wa-carrid + INTO key. + ... + LOOP AT GROUP key INTO member. + ... members ... + ENDLOOP. + ... +ENDLOOP. +``` + +## Group Key Binding when Grouping by More than One Column +Finally, the group key binding for structured group keys: + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY ( key1 = wa-carrid key2 = wa-airpfrom ) + INTO DATA(key). + ... key-key1 ... key-key2 ... +ENDLOOP. +``` + +Here, `key` is a structure with the components `key1` +and `key2`. A member loop can be inserted in exactly the same +way as when grouping by one column. + +If the group members are not relevant, the addition [`NO +MEMBERS`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by.htm) +can be used to save time and memory. + +``` abap +LOOP AT spfli_tab INTO wa + GROUP BY ( key1 = wa-carrid key2 = wa-airpfrom + index = GROUP INDEX size = GROUP SIZE ) + WITHOUT MEMBERS + INTO DATA(key). + ... key-key1 ... key-key2 ... key-index ... key-size ... +ENDLOOP. +``` + +It is no longer possible to use a member loop here. Instead, the group +key was enriched with optional components for further information using +[`GROUP +INDEX`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by_key.htm) +[`GROUP +SIZE`](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abaploop_at_itab_group_by_key.htm). + +## Executable Example +[zcl_demo_abap_sql_group_by](./src/zcl_demo_abap_sql_group_by.clas.abap) + +Note the steps outlined [here](README.md#🎬-getting-started-with-the-examples) about how to import and run the code. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/LICENSES/Apache-2.0.txt b/LICENSES/Apache-2.0.txt new file mode 100644 index 0000000..137069b --- /dev/null +++ b/LICENSES/Apache-2.0.txt @@ -0,0 +1,73 @@ +Apache License +Version 2.0, January 2004 +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. + +"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: + + (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + + You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + +To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d19e2c5 --- /dev/null +++ b/README.md @@ -0,0 +1,206 @@ +
+
+
+ 
+
+
+
+
+
+
+ ABAP Cheat Sheets
+ +
+ Explore ABAP syntax in a nutshell & executable examples
+
+
+
+ How to Use
+ ·
+ Cheat Sheets
+ ·
+ Examples
+
+
+
+ +ABAP cheat sheets[^1] ... +- provide a **collection of information on selected ABAP topics** in a nutshell for your reference. +- focus on **ABAP syntax**. +- include **code snippets**. +- are supported by easy-to-consume **demonstration examples** that you can import into your [SAP BTP ABAP environment](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abensap_btp_abap_env_glosry.htm) or on-premise ABAP system using [abapGit](https://abapgit.org/) to run and check out ABAP syntax in action in simple contexts. +- are enriched by links to glossary entries and chapters of the **ABAP Keyword Documentation** (the *F1 help*) for you to deep dive into the respective ABAP topics and get more comprehensive information. + +
+
+ +- Since the ABAP cheat sheets provide information in a nutshell, they do not claim to be exhaustive as far as the described syntax and concepts are concerned. If you want to go more into the details, just consult the ABAP Keyword Documentation, for example, by choosing `F1` for a keyword in your code or directly researching via the online version or the system-internal version. +- If not stated otherwise in the cheat sheets and examples, the content of this repository is relevant for these ABAP language versions: + - [ABAP for Cloud Development](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_for_sap_cloud_glosry.htm): Restricted ABAP language scope for developments in the [SAP BTP ABAP environment](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abensap_btp_abap_env_glosry.htm) → [Online version of the documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm) + - [Standard ABAP](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenstandard_abap_glosry.htm): Unrestricted ABAP language scope, for example, for developments in an on-premise ABAP system → [Online version of the documentation (latest version)](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap.htm) +- Check the [Known Issues](#⚡-known-issues) and [Disclaimer](#⚠️-disclaimer). +- In the cheat sheets, links are available to glossary entries and topics of the ABAP Keyword Documentation. Note that these links refer to the ABAP for Cloud Development version in most cases. +
+
+💡 Note
++ +- Since the ABAP cheat sheets provide information in a nutshell, they do not claim to be exhaustive as far as the described syntax and concepts are concerned. If you want to go more into the details, just consult the ABAP Keyword Documentation, for example, by choosing `F1` for a keyword in your code or directly researching via the online version or the system-internal version. +- If not stated otherwise in the cheat sheets and examples, the content of this repository is relevant for these ABAP language versions: + - [ABAP for Cloud Development](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_for_sap_cloud_glosry.htm): Restricted ABAP language scope for developments in the [SAP BTP ABAP environment](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abensap_btp_abap_env_glosry.htm) → [Online version of the documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm) + - [Standard ABAP](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenstandard_abap_glosry.htm): Unrestricted ABAP language scope, for example, for developments in an on-premise ABAP system → [Online version of the documentation (latest version)](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap.htm) +- Check the [Known Issues](#⚡-known-issues) and [Disclaimer](#⚠️-disclaimer). +- In the cheat sheets, links are available to glossary entries and topics of the ABAP Keyword Documentation. Note that these links refer to the ABAP for Cloud Development version in most cases. +
+ +## 🏗️ How to Use + +1. **ABAP syntax info**: Get info in a nutshell on ABAP syntax and concepts related to various ABAP topics in the [ABAP cheat sheets](#📝-abap-cheat-sheets-overview). +2. **Demo examples**: Import the ABAP development objects of this repository into your system using [abapGit](https://abapgit.org/) as described [here](#🎬-getting-started-with-the-examples) and run the demo classes by choosing `F9` in the [ABAP Development Tools (ADT)](https://tools.eu1.hana.ondemand.com/) for checking out the ABAP syntax in action. + + +## 📝 ABAP Cheat Sheets Overview + +| Cheat Sheet | Topics Covered | Demo Example | +| ------------- | ------------- | ----- | +|[Working with Internal Tables](01_Internal_Tables.md)| Creating, filling, reading from, sorting, modifying internal tables | [zcl_demo_abap_internal_tables](./src/zcl_demo_abap_internal_tables.clas.abap) | +|[Working with Structures](02_Structures.md)| Creating structures and structured types, variants of structures, accessing components of structures, filling structures, clearing structures, structures in use in the context of tables | [zcl_demo_abap_structures](./src/zcl_demo_abap_structures.clas.abap) | +|[ABAP SQL: Working with Persisted Data in Database Tables](03_ABAP_SQL.md)| Reading from database tables using `SELECT`, changing data in database tables using `INSERT`, `UPDATE`, `MODIFY` and `DELETE` | [zcl_demo_abap_sql](./src/zcl_demo_abap_sql.clas.abap) | +|[ABAP Object Orientation](04_ABAP_Object_Orientation.md)| Working with objects and components, concepts like inheritance, interfaces, and more | [zcl_demo_abap_objects](./src/zcl_demo_abap_objects.clas.abap) | +|[Working with Constructor Expressions](05_Constructor_Expressions.md)| Operators `VALUE`, `CORRESPONDING`, `NEW`, `CONV`, `EXACT`, `REF`, `CAST`, `COND`, `SWITCH`, `FILTER`, `REDUCE`, iteration expressions with `FOR`, `LET` expressions | [zcl_demo_abap_constructor_expr](./src/zcl_demo_abap_constructor_expr.clas.abap) | +|[Dynamic Programming](06_Dynamic_Programming.md)| Touches on field symbols and data references as supporting elements for dynamic programming, dynamic ABAP syntax components, runtime type services (RTTS), i. e. runtime type identification (RTTI) and runtime type creation (RTTC) | [zcl_demo_abap_dynamic_prog](./src/zcl_demo_abap_dynamic_prog.clas.abap) | +|[String Processing](07_String_Processing.md)| Creating strings and assigning values, chaining strings, string templates, concatenating, splitting, modifying strings, searching and replacing, regular expressions | [zcl_demo_abap_string_proc](./src/zcl_demo_abap_string_proc.clas.abap) | +|[ABAP for RAP: Entity Manipulation Language (ABAP EML)](08_EML_ABAP_for_RAP.md)| Setting EML in the context of RAP, standard (create, read, update, delete) and non-standard operations (actions) |
- [Demo RAP scenario with a managed RAP BO, external numbering (zcl_demo_abap_rap_ext_num_m)](./src/zcl_demo_abap_rap_ext_num_m.clas.abap)
- [Demo RAP scenario with an unmanaged RAP BO, external numbering (zcl_demo_abap_rap_ext_num_u)](./src/zcl_demo_abap_rap_ext_num_u.clas.abap)
- [Demo RAP scenario ("RAP calculator") with a managed, draft-enabled RAP BO, late numbering (zcl_demo_abap_rap_draft_ln_m)](./src/zcl_demo_abap_rap_draft_ln_m.clas.abap)
Note that this example can also be checked out using the preview version of an SAP Fiori UI. Check the comments in the class for the steps.
+
+ +- A few **DDIC artifacts**, for example, database tables, are part of the repository. They are used by the examples to ensure self-contained examples. For all examples to work, all artifacts must be imported. +- All examples are designed to **display some output in the ADT console**. Once successfully imported, you can **execute** the examples in ADT by choosing `F9` to display the output in the ADT console. +- The examples **include descriptions and comments** in the code for providing explanations and setting the context. +
+
+1) General info
++ +- A few **DDIC artifacts**, for example, database tables, are part of the repository. They are used by the examples to ensure self-contained examples. For all examples to work, all artifacts must be imported. +- All examples are designed to **display some output in the ADT console**. Once successfully imported, you can **execute** the examples in ADT by choosing `F9` to display the output in the ADT console. +- The examples **include descriptions and comments** in the code for providing explanations and setting the context. +
+
+ +**Prerequisites** +- [x] Before importing the code, you have made a system-wide search for, for example, classes named `ZCL_DEMO_ABAP*` so as not to run into issues when you try to import the code. If someone has already imported the content in the system, you can simply check out that imported version and proceed with the step *3) Run the code*. +- [x] You have access to an SAP BTP ABAP Environment instance (see [here](https://blogs.sap.com/2018/09/04/sap-cloud-platform-abap-environment) for additional information). +- [x] You have downloaded and installed ABAP Development Tools (ADT). Make sure that you use the most recent version as indicated on the [installation page](https://tools.hana.ondemand.com/#abap). +- [x] You have created an ABAP cloud project in ADT that allows you to access your SAP BTP ABAP Environment instance (see [here](https://help.sap.com/viewer/5371047f1273405bb46725a417f95433/Cloud/en-US/99cc54393e4c4e77a5b7f05567d4d14c.html) for additional information). Your logon language is English. +- [x] You have installed the [abapGit](https://github.com/abapGit/eclipse.abapgit.org) plug-in for ADT from the [update site](http://eclipse.abapgit.org/updatesite/). + +**Import Code** + +Use the abapGit plug-in to install the ABAP Cheat Sheets by carrying out the following steps: + +1. In your ABAP cloud project, create a package, for example, `ZABAP_CHEAT_SHEETS` as target package. It is recommended that you assign the package to a transport request suitable for demo content. +2. Add the package to the *Favorite Packages* in the *Project Explorer* view in ADT. +3. To add the abapGit Repositories view to the ABAP perspective, choose `Window` → `Show View` → `Other...` from the menu bar and choose `abapGit Repositories`. +4. On the abapGit Repositories view, click the `+` icon in the top right corner of the ADT tab to link a new abapGit repository. +
 + +5. The *Link abapGit Repository* pop-up is displayed. Insert the following URL: + +``` +https://github.com/SAP-samples/abap-cheat-sheets.git +``` + +6. Choose `Next`. + +7. On the *Branch and Package Selection* screen, insert the name of the created package (e. g. `ZABAP_CHEAT_SHEETS`) in the `Package` field. +8. Choose `Next`. +9. On the *Select Transport Request* screen, select the created transport request suitable for demo content and choose `Finish` to link the Git repository to your ABAP cloud project. If the created package is already assigned to a transport request for the demo content and a message that an object is already locked in a transport request is displayed, choose `Finish`, too. +10. In the *abapGit Repositories* view, filter for your package. The repository appears in the *abapGit Repositories* view with status Linked. +11. Right-click the new abapGit repository and choose `Pull...` to start the cloning of the repository contents. +12. On the *Branch and Package Selection* screen, choose `Next`. +13. If the *Locally Modified Object* screen is displayed, select the objects (for example, the package to automatically select all artifacts) in the list and choose `Next`. +14. On the next screen, select a transport request and choose `Finish`. Same as above, if an *object already locked* message is displayed, choose `Finish`, too. The status in the *abapGit Repositories* view changes to Pull running.... Note that the pull run may take a few minutes. +15. Once the cloning has finished, the status is set to `Pulled Successfully`. You might need to refresh the `abapGit Repositories` view to see the progress of the import. To do so, choose the icon for refreshing (`Refresh`) in the top right corner of the view. +16. Refresh your project tree. E. g. in ADT, right-click the package and choose `Refresh` or `F5`. The package should contain all artifacts from the GitHub repository. +17. Make sure that all artifacts are active. To activate all inactive development objects, choose the `Activate all inactive ABAP development objects` button from the menu (or choose `CTRL+Shift+F3`). +
+
+2a) SAP BTP ABAP environment
++ +**Prerequisites** +- [x] Before importing the code, you have made a system-wide search for, for example, classes named `ZCL_DEMO_ABAP*` so as not to run into issues when you try to import the code. If someone has already imported the content in the system, you can simply check out that imported version and proceed with the step *3) Run the code*. +- [x] You have access to an SAP BTP ABAP Environment instance (see [here](https://blogs.sap.com/2018/09/04/sap-cloud-platform-abap-environment) for additional information). +- [x] You have downloaded and installed ABAP Development Tools (ADT). Make sure that you use the most recent version as indicated on the [installation page](https://tools.hana.ondemand.com/#abap). +- [x] You have created an ABAP cloud project in ADT that allows you to access your SAP BTP ABAP Environment instance (see [here](https://help.sap.com/viewer/5371047f1273405bb46725a417f95433/Cloud/en-US/99cc54393e4c4e77a5b7f05567d4d14c.html) for additional information). Your logon language is English. +- [x] You have installed the [abapGit](https://github.com/abapGit/eclipse.abapgit.org) plug-in for ADT from the [update site](http://eclipse.abapgit.org/updatesite/). + +**Import Code** + +Use the abapGit plug-in to install the ABAP Cheat Sheets by carrying out the following steps: + +1. In your ABAP cloud project, create a package, for example, `ZABAP_CHEAT_SHEETS` as target package. It is recommended that you assign the package to a transport request suitable for demo content. +2. Add the package to the *Favorite Packages* in the *Project Explorer* view in ADT. +3. To add the abapGit Repositories view to the ABAP perspective, choose `Window` → `Show View` → `Other...` from the menu bar and choose `abapGit Repositories`. +4. On the abapGit Repositories view, click the `+` icon in the top right corner of the ADT tab to link a new abapGit repository. +
 + +5. The *Link abapGit Repository* pop-up is displayed. Insert the following URL: + +``` +https://github.com/SAP-samples/abap-cheat-sheets.git +``` + +6. Choose `Next`. + +7. On the *Branch and Package Selection* screen, insert the name of the created package (e. g. `ZABAP_CHEAT_SHEETS`) in the `Package` field. +8. Choose `Next`. +9. On the *Select Transport Request* screen, select the created transport request suitable for demo content and choose `Finish` to link the Git repository to your ABAP cloud project. If the created package is already assigned to a transport request for the demo content and a message that an object is already locked in a transport request is displayed, choose `Finish`, too. +10. In the *abapGit Repositories* view, filter for your package. The repository appears in the *abapGit Repositories* view with status Linked. +11. Right-click the new abapGit repository and choose `Pull...` to start the cloning of the repository contents. +12. On the *Branch and Package Selection* screen, choose `Next`. +13. If the *Locally Modified Object* screen is displayed, select the objects (for example, the package to automatically select all artifacts) in the list and choose `Next`. +14. On the next screen, select a transport request and choose `Finish`. Same as above, if an *object already locked* message is displayed, choose `Finish`, too. The status in the *abapGit Repositories* view changes to Pull running.... Note that the pull run may take a few minutes. +15. Once the cloning has finished, the status is set to `Pulled Successfully`. You might need to refresh the `abapGit Repositories` view to see the progress of the import. To do so, choose the icon for refreshing (`Refresh`) in the top right corner of the view. +16. Refresh your project tree. E. g. in ADT, right-click the package and choose `Refresh` or `F5`. The package should contain all artifacts from the GitHub repository. +17. Make sure that all artifacts are active. To activate all inactive development objects, choose the `Activate all inactive ABAP development objects` button from the menu (or choose `CTRL+Shift+F3`). +
+
+ +**Prerequisites** +- [x] The assumption is that you are on the latest [ABAP release](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abennews-75.htm). The content was also tested with release 7.56. +- [x] Before importing the code, you have made a system-wide search for, for example, classes named `ZCL_DEMO_ABAP*` so as not to run into issues when you try to import the code. If someone has already imported the content in the system, you can simply check out that imported version and proceed with the step *3) Run the code*. +- [x] You have downloaded and installed ABAP Development Tools (ADT). Make sure that you use the most recent version as indicated on the [installation page](https://tools.hana.ondemand.com/#abap). +- [x] You have created an ABAP Project in ADT that allows you to access your Application Server as mentioned above. Your logon language is English. +- [x] You have downloaded and installed the standalone version of the abapGit report. Make sure that you use the most recent version as indicated on the [installation page](https://docs.abapgit.org/). You can create a report, for example, `zabapgit_standalone` and copy and paste [this code](https://raw.githubusercontent.com/abapGit/build/main/zabapgit_standalone.prog.abap) into the program. +- [x] You have installed the certificate files for github.com, see [abapGit Documentation](https://docs.abapgit.org/guide-ssl-setup.html). + +**Import Code** + +Use the standalone version of the abapGit report to import the demo examples of the ABAP Cheat Sheets by carrying out the following steps: +1. In your ABAP project, create a package, for example, `TEST_ABAP_CHEAT_SHEETS` as target package suitable for demo content (e. g. by using `LOCAL` as software component). +2. Add the package to the *Favorite Packages* in the *Project Explorer* view in ADT. +3. Run the standalone version of the abapGit report. +4. Choose the `New Online` button. If the button is not available, for example, if another repository is already opened, choose the `Repository List` button. +5. On the *New Online Repository* screen, make the following entries: + - `Git Repository URL`: + + ``` + https://github.com/SAP-samples/abap-cheat-sheets.git + ``` + + - `Package`: Your demo package, for example, `TEST_ABAP_CHEAT_SHEETS` +6. Leave the other fields unchanged and choose `Create Online Repo`. +7. On the *Repository* screen, you will see the available ABAP artifacts to be imported into your ABAP system. +8. Choose the `Pull` button. The import of the artifacts is triggered. It might take some minutes. +9. If the `Inactive Objects` pop-up is displayed, select all artifacts and choose `Continue` (✔️). +10. Once the cloning has finished, refresh your project tree. E. g. in ADT, right-click the package and choose `Refresh` or `F5`. The package should contain all artifacts from the GitHub repository. +11. Make sure that all artifacts are active. To activate all inactive development objects, choose the `Activate all inactive ABAP development objects` button from the (or choose `CTRL+Shift+F3`). + +
+
+2b) Application Server ABAP On-Premise
++ +**Prerequisites** +- [x] The assumption is that you are on the latest [ABAP release](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abennews-75.htm). The content was also tested with release 7.56. +- [x] Before importing the code, you have made a system-wide search for, for example, classes named `ZCL_DEMO_ABAP*` so as not to run into issues when you try to import the code. If someone has already imported the content in the system, you can simply check out that imported version and proceed with the step *3) Run the code*. +- [x] You have downloaded and installed ABAP Development Tools (ADT). Make sure that you use the most recent version as indicated on the [installation page](https://tools.hana.ondemand.com/#abap). +- [x] You have created an ABAP Project in ADT that allows you to access your Application Server as mentioned above. Your logon language is English. +- [x] You have downloaded and installed the standalone version of the abapGit report. Make sure that you use the most recent version as indicated on the [installation page](https://docs.abapgit.org/). You can create a report, for example, `zabapgit_standalone` and copy and paste [this code](https://raw.githubusercontent.com/abapGit/build/main/zabapgit_standalone.prog.abap) into the program. +- [x] You have installed the certificate files for github.com, see [abapGit Documentation](https://docs.abapgit.org/guide-ssl-setup.html). + +**Import Code** + +Use the standalone version of the abapGit report to import the demo examples of the ABAP Cheat Sheets by carrying out the following steps: +1. In your ABAP project, create a package, for example, `TEST_ABAP_CHEAT_SHEETS` as target package suitable for demo content (e. g. by using `LOCAL` as software component). +2. Add the package to the *Favorite Packages* in the *Project Explorer* view in ADT. +3. Run the standalone version of the abapGit report. +4. Choose the `New Online` button. If the button is not available, for example, if another repository is already opened, choose the `Repository List` button. +5. On the *New Online Repository* screen, make the following entries: + - `Git Repository URL`: + + ``` + https://github.com/SAP-samples/abap-cheat-sheets.git + ``` + + - `Package`: Your demo package, for example, `TEST_ABAP_CHEAT_SHEETS` +6. Leave the other fields unchanged and choose `Create Online Repo`. +7. On the *Repository* screen, you will see the available ABAP artifacts to be imported into your ABAP system. +8. Choose the `Pull` button. The import of the artifacts is triggered. It might take some minutes. +9. If the `Inactive Objects` pop-up is displayed, select all artifacts and choose `Continue` (✔️). +10. Once the cloning has finished, refresh your project tree. E. g. in ADT, right-click the package and choose `Refresh` or `F5`. The package should contain all artifacts from the GitHub repository. +11. Make sure that all artifacts are active. To activate all inactive development objects, choose the `Activate all inactive ABAP development objects` button from the (or choose `CTRL+Shift+F3`). + +
+
+ +- Open your created package containing the imported ABAP artifacts in the ABAP Development Tools (ADT). +- Open an ABAP cheat sheet example class as listed in the [ABAP Cheat Sheets Overview](#📝-abap-cheat-sheets-overview) section, for example, `zcl_demo_abap_string_proc`. The classes are contained in folder `Source Code Library` → `Classes`. +- Choose `F9` to run the class. Alternatively, choose `Run` → `Run As` → `2 ABAP Application (Console)` from the menu. +- Check the console output. + +> **💡 Note**
+>- Check notes on the context and the ABAP syntax used included in the class as comments. +>- Due to the amount of output in the console, the examples include numbers (e. g. 1) ..., 2) ..., 3) ...) representing the header of the individual example code sections. Plus, the variable name is displayed in the console in most cases. Hence, to easier and faster find the relevant output in the console, just search in the console for the number (e. g. search for `3)` for the particular output) or variable name (`STRG+F` in the console) or use break points in the code to check variables in the debugger. +>- You might want to clear the console by making a right-click within the console and choosing `Clear` before running another demo class so as not to confuse the output of multiple classes. +
+
+3) Run the code
++ +- Open your created package containing the imported ABAP artifacts in the ABAP Development Tools (ADT). +- Open an ABAP cheat sheet example class as listed in the [ABAP Cheat Sheets Overview](#📝-abap-cheat-sheets-overview) section, for example, `zcl_demo_abap_string_proc`. The classes are contained in folder `Source Code Library` → `Classes`. +- Choose `F9` to run the class. Alternatively, choose `Run` → `Run As` → `2 ABAP Application (Console)` from the menu. +- Check the console output. + +> **💡 Note**
+>- Check notes on the context and the ABAP syntax used included in the class as comments. +>- Due to the amount of output in the console, the examples include numbers (e. g. 1) ..., 2) ..., 3) ...) representing the header of the individual example code sections. Plus, the variable name is displayed in the console in most cases. Hence, to easier and faster find the relevant output in the console, just search in the console for the number (e. g. search for `3)` for the particular output) or variable name (`STRG+F` in the console) or use break points in the code to check variables in the debugger. +>- You might want to clear the console by making a right-click within the console and choosing `Clear` before running another demo class so as not to confuse the output of multiple classes. +
+ +## ⚡ Known Issues +- Only one user on the system may import this repository as all object names must be globally unique. If you receive an error that the objects already exist when trying to import, search the system for classes named `ZCL_DEMO_ABAP*`. Someone has already imported the content in the system and you can simply check out that imported version. +- Since the repository contains self-contained examples, i. e. they work, for example, with demo database tables included in the repository (note that these tables are filled in the course of method executions), all demo artifacts must be imported so that all examples work. +- For the import into an on-premise system, note the following: The demos cover ABAP syntax irrespective of the ABAP release so as not to scatter information and to have the info in one go. Hence, there may be syntax that is not yet available with the ABAP version of your on-premise system. In that case, you might want to comment out affected code sections if an activation fails. +- Regarding potential code check warnings, for example, for the many strings in the code, not using an `ORDER BY` clause or messages regarding using `SELECT *`, the code purposely renounces pragmas and pseudo comments to keep the code fairly simple and to focus on the available ABAP syntax. See also the [Disclaimer](#⚠️-disclaimer). + +## 🛈 Further Information +- Regarding the system-internal version of the ABAP Keyword Documentation in your + - ... **on-premise system**: Access the documentation in SAP GUI via the transactions `ABAPDOCU` (opens the documentation directly) and `ABAPHELP` (opens an input field with which you can search the documentation content, for example, you can search for a keyword like `SELECT`). Or, certainly, in your code, choose `F1` for a keyword. If you are in SAP GUI (e. g. in `SE80`), the system-internal version is opened. If you are in ADT, the documentation is opened in the *ABAP Language Help* view. + - ... **SAP BTP ABAP environment**: In ADT, you find the documentation in the *ABAP Language Help* view where you can also search. When choosing `F1` for a keyword in your code, the documentation is opened there accordingly. +- Links to the online version of the ABAP Keyword Documentation for: + - **Standard ABAP**: Unrestricted ABAP language scope, for example, for developments in an on-premise ABAP system → [Online version of the documentation (latest version)](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap.htm) + - **ABAP for Cloud Development**: Restricted ABAP language scope for developments in the SAP BTP ABAP environment → [Online version of the documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm) +- Regarding demonstration examples of the ABAP Keyword Documentation in your on-premise system: Have you ever checked out the package `SABAPDEMOS`? This package contains all the examples used in the ABAP Keyword Documentation. To get the context, program names etc., check out the [example page](https://help.sap.com/doc/abapdocu_latest_index_htm/latest/en-US/index.htm?file=abenabap_examples.htm) (which is also available in the system-internal SAP GUI version as node in the topic tree) summarizing executable examples. Certainly, you also find the example topics in the context of the individual ABAP Keyword Documentation topic. The example topics have a ⚙️ sign: + +  + +- See [this blog](https://blogs.sap.com/2021/04/28/video-tutorials-on-how-to-use-the-abap-keyword-documentation-abap-f1-help/) for videos about the ABAP Keyword Documentation on the [Help Portal](https://www.youtube.com/watch?v=a4ckF1XkfG8), in [SAP GUI](https://www.youtube.com/watch?v=fsX-085MlD8) and in [ADT](https://www.youtube.com/watch?v=hNGEYFpWwh0). + +## ⚠️ Disclaimer +The code examples presented in this repository are only syntax examples and are not intended for direct use in a production system environment. The code examples are primarily intended to provide a better explanation and visualization of the syntax and semantics of ABAP statements and not to solve concrete programming tasks. For production application programs, a dedicated solution should therefore always be worked out for each individual case. +SAP does not guarantee either the correctness or the completeness of the code. In addition, SAP takes no legal responsibility or liability for possible errors or their consequences, which occur through the use of the example programs. + +## 📟 How to Obtain Support +This project is provided "as-is": there is no guarantee that raised issues will be answered or addressed in future releases. + +## 📜 License +Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSE) file. + +[^1]: "A written [...] aid (such as a sheet of notes) that can be referred to for help in understanding or remembering something complex" (Definition for "cheat sheet" in Merriam-Webster Dictionary). diff --git a/files/ABAP_Keyword_Documentation.png b/files/ABAP_Keyword_Documentation.png new file mode 100644 index 0000000..e0eb0a6 Binary files /dev/null and b/files/ABAP_Keyword_Documentation.png differ diff --git a/files/abapGit_Repositories.png b/files/abapGit_Repositories.png new file mode 100644 index 0000000..ea145f4 Binary files /dev/null and b/files/abapGit_Repositories.png differ diff --git a/files/bdef_derived_type_components.png b/files/bdef_derived_type_components.png new file mode 100644 index 0000000..c8a55ea Binary files /dev/null and b/files/bdef_derived_type_components.png differ diff --git a/files/bdef_derived_types.png b/files/bdef_derived_types.png new file mode 100644 index 0000000..b48b0a9 Binary files /dev/null and b/files/bdef_derived_types.png differ diff --git a/files/example_topics.png b/files/example_topics.png new file mode 100644 index 0000000..98e9d44 Binary files /dev/null and b/files/example_topics.png differ diff --git a/files/rap_handler_method_parameters.png b/files/rap_handler_method_parameters.png new file mode 100644 index 0000000..aa61074 Binary files /dev/null and b/files/rap_handler_method_parameters.png differ diff --git a/src/ezdemo_abap_lock.enqu.xml b/src/ezdemo_abap_lock.enqu.xml new file mode 100644 index 0000000..8d677f1 --- /dev/null +++ b/src/ezdemo_abap_lock.enqu.xml @@ -0,0 +1,44 @@ + +
Behavior implementation for RAP demo scenario (draft BO)
+"! The class represents a RAP BO provider (i. e. an ABAP behavior pool/ABP) for a RAP demo scenario +"! (managed, draft-enabled RAP BO with late numbering). +CLASS zbp_demo_abap_rap_draft_m DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF zdemo_abap_rap_draft_m. + PROTECTED SECTION. + PRIVATE SECTION. +ENDCLASS. + + + +CLASS zbp_demo_abap_rap_draft_m IMPLEMENTATION. +ENDCLASS. diff --git a/src/zbp_demo_abap_rap_draft_m.clas.locals_imp.abap b/src/zbp_demo_abap_rap_draft_m.clas.locals_imp.abap new file mode 100644 index 0000000..3293cf6 --- /dev/null +++ b/src/zbp_demo_abap_rap_draft_m.clas.locals_imp.abap @@ -0,0 +1,234 @@ +*********************************************************************** +* +* RAP BO provider (i. e. ABAP behavior pool/ABP) +* for a RAP demo scenario +* +* - RAP scenario: "RAP calculator" (managed, draft-enabled RAP BO with +* late numbering) +* - Data model: Consists of a root entity alone. +* The BDEF defines the behavior for this entity. The definitions in the +* BDEF determine which methods must be implemented in the ABAP behavior +* pool (ABP). Note that the view contains many annotations for the +* SAP Fiori UI. +* +* ----------------------------- NOTE ----------------------------------- +* This simplified example is not a real life scenario and rather +* focuses on the technical side by giving an idea how the communication +* and data exchange between a RAP BO consumer, which is a class +* in this case, and RAP BO provider can work. Additionally, it shows +* how the methods for non-standard RAP BO operations might be +* self-implemented in an ABP. The example is is intentionally kept +* short and simple and focuses on specific RAP aspects. For this reason, +* the example might not fully meet the requirements of the RAP BO contract. +* +* The code presented in this class is only meant for supporting the ABAP +* cheat sheets. It is not intended for direct use in a +* production system environment. The code examples in the ABAP cheat +* sheets are primarily intended to provide a better explanation and +* visualization of the syntax and semantics of ABAP statements and not to +* solve concrete programming tasks. For production application programs, +* a dedicated solution should therefore always be worked out for each +* individual case. There is no guarantee for either the correctness or +* the completeness of the code. In addition, there is no legal +* responsibility or liability for possible errors or their consequences +* which occur through the use of the example code. +*********************************************************************** + +CLASS lhc_calc DEFINITION INHERITING FROM cl_abap_behavior_handler. + PRIVATE SECTION. + + METHODS delete_all FOR MODIFY + IMPORTING keys FOR ACTION calc~delete_all. + + METHODS get_global_authorizations FOR GLOBAL AUTHORIZATION + IMPORTING REQUEST requested_authorizations FOR calc RESULT result. + + METHODS validate FOR VALIDATE ON SAVE + IMPORTING keys FOR calc~validate. + + METHODS det_modify FOR DETERMINE ON MODIFY + IMPORTING keys FOR calc~det_modify. + + METHODS calculation FOR MODIFY + IMPORTING keys FOR ACTION calc~calculation. + +ENDCLASS. + +CLASS lhc_calc IMPLEMENTATION. + + METHOD delete_all. + "Purpose: The method deletes all persisted database entries. + + DATA all_keys TYPE TABLE FOR DELETE zdemo_abap_rap_draft_m. + + SELECT id FROM zdemo_abap_tabca INTO CORRESPONDING FIELDS OF TABLE @all_keys. + + READ ENTITIES OF zdemo_abap_rap_draft_m IN LOCAL MODE + ENTITY calc + ALL FIELDS WITH CORRESPONDING #( all_keys ) + RESULT DATA(lt_del). + + IF lt_del IS NOT INITIAL. + + MODIFY ENTITY IN LOCAL MODE zdemo_abap_rap_draft_m + DELETE FROM CORRESPONDING #( lt_del ). + + APPEND VALUE #( %msg = new_message_with_text( text = 'All persisted calculations were deleted.' + severity = if_abap_behv_message=>severity-information ) + ) TO reported-calc. + + ELSE. + APPEND VALUE #( %msg = new_message_with_text( text = 'No persisted calculations available.' + severity = if_abap_behv_message=>severity-information ) + ) TO reported-calc. + + ENDIF. + + ENDMETHOD. + + METHOD get_global_authorizations. + "Purposely kept without implementation. + ENDMETHOD. + + METHOD validate. + + "Retrieving instances based on requested keys + READ ENTITIES OF zdemo_abap_rap_draft_m IN LOCAL MODE + ENTITY calc + ALL FIELDS + WITH CORRESPONDING #( keys ) + RESULT DATA(result_validate) + FAILED DATA(f). + + CHECK result_validate IS NOT INITIAL. + + "Various calculation errors are handled. + LOOP AT result_validate ASSIGNING FIELD-SYMBOL(Behavior implementation for RAP demo scenario (managed BO)
+"! The class represents a RAP BO provider (i. e. an ABAP behavior pool/ABP) for a RAP demo scenario +"! (managed RAP BO with external numbering). +CLASS zbp_demo_abap_rap_ro_m DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF zdemo_abap_rap_ro_m. + PROTECTED SECTION. + PRIVATE SECTION. +ENDCLASS. + + + +CLASS zbp_demo_abap_rap_ro_m IMPLEMENTATION. +ENDCLASS. diff --git a/src/zbp_demo_abap_rap_ro_m.clas.locals_imp.abap b/src/zbp_demo_abap_rap_ro_m.clas.locals_imp.abap new file mode 100644 index 0000000..fac796e --- /dev/null +++ b/src/zbp_demo_abap_rap_ro_m.clas.locals_imp.abap @@ -0,0 +1,123 @@ +*********************************************************************** +* +* RAP BO provider (i. e. ABAP behavior pool/ABP) +* for a RAP demo scenario +* +* - RAP scenario: managed RAP BO, external numbering +* - Data model: Consists of a root entity and one child entity. The BDEF +* defines the behavior for these two entities which are connected via +* a CDS composition relation. The definitions in the BDEF determine +* which methods must be implemented in this ABAP behavior pool (ABP). +* +* ----------------------------- NOTE ----------------------------------- +* This simplified example is not a real life scenario and rather +* focuses on the technical side by giving an idea how the communication +* and data exchange between a RAP BO consumer, which is a class +* in this case, and RAP BO provider can work. Additionally, it shows +* how the methods for non-standard RAP BO operations might be +* self-implemented in an ABP. The example is is intentionally kept +* short and simple and focuses on specific RAP aspects. For this reason, +* the example might not fully meet the requirements of the RAP BO contract. +* +* The code presented in this class is only meant for supporting the ABAP +* cheat sheets. It is not intended for direct use in a +* production system environment. The code examples in the ABAP cheat +* sheets are primarily intended to provide a better explanation and +* visualization of the syntax and semantics of ABAP statements and not to +* solve concrete programming tasks. For production application programs, +* a dedicated solution should therefore always be worked out for each +* individual case. There is no guarantee for either the correctness or +* the completeness of the code. In addition, there is no legal +* responsibility or liability for possible errors or their consequences +* which occur through the use of the example code. +*********************************************************************** + +CLASS lhc_root DEFINITION INHERITING FROM cl_abap_behavior_handler. + PRIVATE SECTION. + + METHODS get_global_authorizations FOR GLOBAL AUTHORIZATION + IMPORTING REQUEST requested_authorizations FOR root RESULT result. + + METHODS multiply_by_2 FOR MODIFY + IMPORTING keys FOR ACTION root~multiply_by_2. + + METHODS det_add_text FOR DETERMINE ON SAVE + IMPORTING keys FOR root~det_add_text. + + METHODS val FOR VALIDATE ON SAVE + IMPORTING keys FOR root~val. + +ENDCLASS. + +CLASS lhc_root IMPLEMENTATION. + + METHOD get_global_authorizations. + ENDMETHOD. + + METHOD multiply_by_2. + + "Retrieving instances based on requested keys + READ ENTITIES OF zdemo_abap_rap_ro_m IN LOCAL MODE + ENTITY root + FIELDS ( field3 field4 ) WITH CORRESPONDING #( keys ) + RESULT DATA(result) + FAILED failed. + + "If read result is initial, stop further method execution. + CHECK result IS NOT INITIAL. + + "Multiply integer values by 2 + MODIFY ENTITIES OF zdemo_abap_rap_ro_m IN LOCAL MODE + ENTITY root + UPDATE FIELDS ( field3 field4 ) WITH VALUE #( FOR key IN result ( %tky = key-%tky + field3 = key-field3 * 2 + field4 = key-field4 * 2 ) ). + ENDMETHOD. + + METHOD det_add_text. + + READ ENTITIES OF zdemo_abap_rap_ro_m IN LOCAL MODE + ENTITY root + FIELDS ( field2 ) WITH CORRESPONDING #( keys ) + RESULT DATA(lt_res). + + "If read result is initial, stop further method execution. + CHECK lt_res IS NOT INITIAL. + + "field2 is changed + MODIFY ENTITIES OF zdemo_abap_rap_ro_m IN LOCAL MODE + ENTITY root + UPDATE FIELDS ( field2 ) + WITH VALUE #( FOR key IN lt_res ( %tky = key-%tky + field2 = |{ key-field2 }_#| ) ). + + ENDMETHOD. + + METHOD val. + + READ ENTITIES OF zdemo_abap_rap_ro_m IN LOCAL MODE + ENTITY root + FIELDS ( field3 ) WITH CORRESPONDING #( keys ) + RESULT DATA(lt_res). + + "If read result is initial, stop further method execution. + CHECK lt_res IS NOT INITIAL. + + LOOP AT lt_res ASSIGNING FIELD-SYMBOL(Behavior implementation for RAP demo scenario (unmanaged BO)
+"! The class represents a RAP BO provider (i. e. an ABAP behavior pool/ABP) for a RAP demo scenario +"! (unmanaged RAP BO with external numbering). +CLASS zbp_demo_abap_rap_ro_u DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF zdemo_abap_rap_ro_u. + PROTECTED SECTION. + PRIVATE SECTION. +ENDCLASS. + + + +CLASS zbp_demo_abap_rap_ro_u IMPLEMENTATION. +ENDCLASS. diff --git a/src/zbp_demo_abap_rap_ro_u.clas.locals_imp.abap b/src/zbp_demo_abap_rap_ro_u.clas.locals_imp.abap new file mode 100644 index 0000000..b0ed153 --- /dev/null +++ b/src/zbp_demo_abap_rap_ro_u.clas.locals_imp.abap @@ -0,0 +1,1023 @@ +*********************************************************************** +* +* RAP BO provider (i. e. ABAP behavior pool/ABP) +* for a RAP demo scenario +* +* - RAP scenario: unmanaged RAP BO, external numbering +* - Data model: Consists of a root entity and one child entity. The BDEF +* defines the behavior for these two entities which are connected via +* a CDS composition relation. The definitions in the BDEF determine +* which methods must be implemented in this ABAP behavior pool (ABP). +* +* ----------------------------- NOTE ----------------------------------- +* This simplified example is not a real life scenario and rather +* focuses on the technical side by giving an idea how the communication +* and data exchange between a RAP BO consumer, which is a class +* in this case, and RAP BO provider can work. Additionally, it shows +* how the methods for non-standard RAP BO operations might be +* self-implemented in an ABP. The example is is intentionally kept +* short and simple and focuses on specific RAP aspects. For this reason, +* the example might not fully meet the requirements of the RAP BO contract. +* +* For demonstration purposes, some of the operations are +* impacted by feature controls and instance authorization as specified +* in the BDEF. +* +* The code presented in this class is only meant for supporting the ABAP +* cheat sheets. It is not intended for direct use in a +* production system environment. The code examples in the ABAP cheat +* sheets are primarily intended to provide a better explanation and +* visualization of the syntax and semantics of ABAP statements and not to +* solve concrete programming tasks. For production application programs, +* a dedicated solution should therefore always be worked out for each +* individual case. There is no guarantee for either the correctness or +* the completeness of the code. In addition, there is no legal +* responsibility or liability for possible errors or their consequences +* which occur through the use of the example code. +*********************************************************************** + +*********************************************************************** +* Class lcl_buffer +* +* To have a self-contained and simple scenario, the transactional +* buffer is realized by internal tables here. These tables - one for +* the root entity, one for the child entity - are designed in a way +* to include RAP BO instance data as well content IDs and flags to +* specify if an instance is to be changed or deleted (which is relevant +* for the save method in this example). +* +* The purpose of this class is to create these internal tables and +* provide a method implementation for the preparation of the tables, +* i. e. to prepare the content of the transactional buffer which is +* accessed throughout the handler and saver method implementations. +* The method/s is/are called in the context of each EML request. +* +*********************************************************************** +"Class that constitutes the transactional buffer +CLASS lcl_buffer DEFINITION. + PUBLIC SECTION. + + "Structure and internal table types for the internal table serving + "as transactional buffers for the root and child entities + TYPES: BEGIN OF gty_buffer, + instance TYPE zdemo_abap_rap_ro_u, + cid TYPE string, + changed TYPE abap_bool, + deleted TYPE abap_bool, + END OF gty_buffer. + + TYPES: BEGIN OF gty_buffer_child, + instance TYPE zdemo_abap_rap_ch_u, + cid_ref TYPE string, + cid_target TYPE string, + changed TYPE abap_bool, + END OF gty_buffer_child. + + TYPES gtt_buffer TYPE TABLE OF gty_buffer + WITH EMPTY KEY. + + TYPES gtt_buffer_child TYPE TABLE OF gty_buffer_child + WITH EMPTY KEY. + + CLASS-DATA: + "Internal tables serving as transactional buffers for the root and child entities + root_buffer TYPE STANDARD TABLE OF gty_buffer WITH EMPTY KEY, + child_buffer TYPE STANDARD TABLE OF gty_buffer_child WITH EMPTY KEY. + + "Structure and internal table types to include the keys for buffer preparation methods + TYPES: BEGIN OF root_keys, + key_field TYPE zdemo_abap_rap_ro_u-key_field, + END OF root_keys, + BEGIN OF child_keys, + key_field TYPE zdemo_abap_rap_ch_u-key_field, + key_ch TYPE zdemo_abap_rap_ch_u-key_ch, + full_key TYPE abap_bool, + END OF child_keys, + tt_root_keys TYPE TABLE OF root_keys WITH EMPTY KEY, + tt_child_keys TYPE TABLE OF child_keys WITH EMPTY KEY. + + "Buffer preparation methods + CLASS-METHODS: prep_root_buffer IMPORTING keys TYPE tt_root_keys, + prep_child_buffer IMPORTING keys TYPE tt_child_keys. + +ENDCLASS. + + +CLASS lcl_buffer IMPLEMENTATION. + + "Buffer preparation for the root entity based on the requested key values + METHOD prep_root_buffer. + + LOOP AT keys ASSIGNING FIELD-SYMBOL(