Ansicht
Dokumentation

ABAPLOOP_AT_ITAB_COND - LOOP AT ITAB COND

ABAPLOOP_AT_ITAB_COND - LOOP AT ITAB COND

General Material Data   ROGBILLS - Synchronize billing plans  
This documentation is copyright by SAP AG.
SAP E-Book

LOOP AT itab, cond

Short Reference



... $[USING KEY keyname$]
    $[FROM idx1$] $[TO idx2$] $[STEP n$]
    $[WHERE log_exp$|(cond_syntax)$] ...


Additions

1. ... USING KEY keyname

2. ... $[FROM idx1$] $[TO idx2$]

3. ... STEP n

4. ... WHERE log_exp

5. ... WHERE (cond_syntax)

Effect

These optional additions to LOOP AT itab specify a subset of lines to be processed and the order in which the loop is executed.

  • The subset of lines can be defined with:
  • FROM and TO that define an interval of line numbers for index tables

  • WHERE that selects lines that fulfill a condition specified in a logical expression

  • STEP that allows lines to be skipped by defining a step size greater than 1.

  • The processing order can be defined with:
  • USING KEY keyname that defines the table key that is used for the loop and thus overrides the standard order determined by the table category.

  • STEP that can define a reverse order by specifying a negative step size.

If none of the conditions are specified, all table lines are read in the standard order that is defined by the table category as described under LOOP AT itab.

Addition 1

... USING KEY keyname

Effect

The optional addition USING KEY specifies a table key keyname with which the processing is executed. The specified table key affects the order in which the table lines are accessed, and the evaluation of the other conditions.

If the primary table key is specified using its name primary_key, the processing behaves in the same way as if no key were explicitly specified. If a secondary table key is specified, the order in which the lines are accessed is as follows. STEP.

The lines are processed by ascending line number in the secondary table index In each loop pass, the system field sy-tabix contains the line number of the current line in the associated secondary table index.
The lines are processed in the order in which they were inserted into the table. In each loop pass, the system field sy-tabix contains the value 0. A preceding sort using the statement SORT does not change this processing order.

The order defined by USING KEY can be reversed by using the addition STEP with a negative step size.

Within the loop, the key used can be addressed using the predefined name loop_key. This is possible in all statements where the table key keyname to be used can be specified explicitly. This type of statement must then be listed in the loop itself. Including the statement in a procedure that is called in the loop is not sufficient.

Notes

  • The fact that the processing order defined by a secondary hash key is not affected by a preceding sort using the statement SORT is a different behavior than for the processing order defined by the primary key of a hashed table that is affected by a preceding sort.
  • If a secondary table key is specified, a simultaneously specified WHERE condition also must be optimizable, otherwise a syntax error occurs or an exception is raised.

Example

The example demonstrates the difference between loops across a standard table of random numbers with and without a sorted secondary table key specification. The first loop returns the lines in the order in which they were appended. The second loop returns the lines sorted in ascending order.

Loop Across Internal Table with Key Specified

Addition 2

... $[FROM idx1$] $[TO idx2$]

Effect

If you use these additions, only the table rows from row number idx1, or up to row number idx2, are taken into account in the table index used. If only FROM is specified, all rows of the table from row number idx1 up to and including the last row are taken into account. If only TO is specified, all rows in the table from the first row up to row number idx2 are taken into account.

If the addition USING KEY is not used, or the primary table key is specified in keyname, the additions FROM and TO can only be used for index tables. In this case, they refer to the row numbers of the primary table index.

If a sorted secondary key is specified in keyname after USING KEY, the additions FROM and TO can be used for all table types and refer to the row numbers of the secondary table index.

idx1 and idx2 are numerical expression positions of operand type i. The following restrictions apply:

  • If the value of idx1 is less than or equal to 0, it is set to 1 in the LOOP statement and causes a runtime error in every other statement. If the value of idx1 is greater than the total number of table rows, no processing takes place.

  • If the value of idx2 is less than or equal to 0, the LOOP statement is not carried out and in every other statement it leads to a runtime error. If the value of idx2 is greater than the number of table rows, it is set to the number of table rows.

  • If the value of idx2 is less than the value of idx1, no processing takes place.

The value of idx1 is evaluated once when the loop is entered. Any changes to idx1 during loop processing are ignored. In contrast, the value of idx2 is evaluated in each loop pass and any changes made to idx2 during loop processing are respected.

The additions FROM and TO can be specified together with STEP and then special rules apply.

Note

To determine when loop processing is exited and whether the value specified in idx2 has been reached, the current line number is evaluated. Note that this number can be changed if lines are inserted or deleted during a loop pass as described in LOOP. When lines are inserted, the loop may be processed less often and when lines are deleted, it may be processed more often than specified by the difference between idx2 and idx1.

Example

Determination of the primary index of a particular table line using the built-in function line_index and a loop across the internal table from this line.

Addition 3

... STEP n

Effect

The optional addition STEP n defines the step size and the direction of the loop. The step size is defined by the absolute value of n and the direction is defined by the positive or negative sign of n. n is a numeric expression position of operand type i. If the addition STEP is not specified, the step size is 1 and the loop order is defined by the table category or the addition USING KEY only.

The addition step size can be combined with the additions FROM, TO and WHERE and then works on the subset of table lines defined by these conditions. For such combinations the following special rules apply:

  • If FROM idx1 or TO idx2 are combined with STEP:
  • If the value of n is greater than 0, idx1 needs to be less than or equal to idx2.

  • If the value of n is less than 0, idx1 needs to be greater than or equal to idx2.

If none of the above restrictions are met, the loop is interpreted as empty. All other settings for FROM idx1 and TO idx2 are described as for ... $[FROM idx1$] $[TO idx2$].
  • If a WHERE condition is combined with STEP, the argument n can only have the value 1 or -1. Other values lead to a syntax error or the uncatchable runtime error ITAB_ILLEGAL_STEP_SIZE. The WHERE condition needs to be placed after STEP n.

The detailed effect of the addition STEP is as follows:

  • Step size
The absolute value of n specifies the step size of the loop over all table lines or the subset of table lines defined by the conditions FROM, TO and WHERE. Starting from the first line of the table or subset for a forwards order or from the last line of the subset for a backwards order,
  • if the absolute value of n is equal to 1, every line is read,

  • if the absolute value of n is equal to 2, every second line is read,

  • and so on.

If the absolute value of n is greater than the lines available in the subset, only the first or last line of the subset are processed.
  • Loop order
The sign of n keeps or reverses the loop order as it is defined by the table category or the addition USING KEY:
  • If the value of n is greater than 0,the loop order is not changed. A forward loop is executed that starts with the first table line or the first line of the subset.

  • If the value of n is less than 0, the loop order is reversed. A backward loop is executed, that starts with the last table line or the last line of the subset.

Specifying a reverse loop order changes the standard order as follows:
  • A reverse loop order without specifying a secondary key behind USING KEY reverses the loop order defined by the table category. For index tables, the primary table index is processed backwards starting with the highest index entry in descending order and the corresponding table lines are read. For hashed tables, the table lines are read backward in the reverse order in which they were inserted into the table or are sorted after a SORT statement.

  • A reverse loop order together with a secondary key specified behind USING KEY reverses the loop order defined by the secondary key. For a sorted secondary key, the corresponding secondary index is processed backwards starting with the highest index entry in descending order and the corresponding table lines are read. For a secondary hashed key, the table lines are read backward in the reverse order in which they were inserted into the table (a preceding sort using SORT has no effect here).

The value of n must not be 0. If the value 0 is known statically for n, a syntax error occurs. If the value 0 is known at runtime only, the program is aborted with the runtime error ITAB_ILLEGAL_STEP_SIZE which is not catchable. Changing the value of n inside the loop has no effect on the step size or loop order.

As usual, sy-tabix contains the line number of the current line read in a loop pass when using a table index or 0 when using a hashed key.

Notes

  • The addition STEP does not change the actual sort order of the table as defined by table category or for a secondary index. It changes the processing order of the current loop with respect to this sort order.
  • STEP n can, however, be positioned otherwise. Its use after FROM idx1 and TO idx2 is recommended.

Example

The following example shows the use of STEP n as reverse loop in combination with FROM idx1 and TO idx2. As result, line 3, line 2, and line 1 as defined by the primary table index are processed in the mentioned order.

LOOP with Step Size

Exceptions

Non-Catchable Exceptions

  • Cause: Illegal step size for the statement.
    Runtime Error: ITAB_ILLEGAL_STEP_SIZE
  • Cause: The statement only supports integral data objects.
    Runtime Error: OBJECTS_NOT_INTEGRAL

Addition 4

... WHERE log_exp

Effect

Static WHERE condition. All rows are processed for which the condition after WHERE is met. You can declare WHERE for all table categories.

After WHERE, you can declare a logical expression log_exp in which the first operand of each operation is a component of the internal table. You cannot specify a predicate function. The components of the internal table must be declared as individual operands and not as part of an expression. You cannot use parenthesized character-type data objects to declare a component dynamically here. The remaining operands of an operation can be any suitable individual operands or calculation expressions, but not components of the internal table. All logical expressions are possible except for the IS ASSIGNED, IS SUPPLIED, and obsolete IS REQUESTED predicates. The specified components can be of any data type. For evaluations, the relevant comparison rules apply.

When standard tables are accessed without a secondary key being specified, access is not optimized since all rows of the internal table are checked for the logical expression of the WHERE addition.

When a sorted key or a hash key is used, that is, when a sorted table, a hashed table, or a secondary table key is accessed, access is optimized in the following circumstances:

  • If a sorted key is declared, the logical expression uses comparisons linked with AND with the relational operator = (or EQ) to include an initial part of the key that consists of at least one component. An AND operation with further comparisons is possible.
  • If a hash key is declared, the logical condition uses comparisons linked with AND with the relational operator = (or EQ) to include all components of the key. An AND operation with further comparisons is possible
  • The logical expression selects the same rows as a READ TABLE statement, in which the relevant components are specified as keys.

If the prerequisites for accessing a sorted or hashed table by means of the primary key are not met, optimization is not achieved and all rows of an internal table are checked as with standard tables.

,,When a secondary table key is accessed, that is, if one is specified in keyname after USING KEY, optimized execution is ensured, provided that the prerequisites above are met. Otherwise, a syntax error or exception occurs.

Notes

  • When using a WHERE condition, note that the comparison rules for incompatible data types apply when incompatible data objects are compared, whereby the data types involved determine which operand is converted. In contrast, when the WITH TABLE KEY and WITH KEY additions of the READ statements are used, the content of the specified data objects is always converted into the data type of the columns before the comparison is made, which can lead to different results.
  • When access is optimized, the WHERE condition is mapped internally to a READ statement with specification of the relevant key.
  • Since the WHERE condition can only optimized if it produces the same results as a READ statement with the corresponding key specification, all operands of the logical expression should be compatible in pairs, if possible. This ensures that the result is not affected by the different behavior of the WHERE condition and the READ statement with a key specification.
  • If a selection table is specified after IN as a logical expression, note that the expression for the initial table is always true and all rows are then processed.
  • The logical expression specified after WHERE is evaluated once when the loop is entered. Any changes to the second operand during loop processing are ignored.

Example

The following example demonstrates the differences in behavior of a WHERE condition and a key access with WITH TABLE KEY. In LOOP AT itab WHERE, the rule for the comparison of character-like data types applies. The short column content "AA" is first padded with blanks to extend the length to 4 and then compared with "AAXX". No matching line is found. Using READ TABLE itab WITH TABLE KEY, the content of text_long is converted to the value "AA" before the comparison, by cutting off two characters, and then compared with the column content. The read is therefore successful.

Addition 5

... WHERE (cond_syntax)

Effect

Dynamic WHERE Condition cond_syntax can be specified as a character-like data object or standard table with character-like data type that, when the statement is executed, contains the syntax of a logical expression (in accordance with the rules of the static WHERE condition) or is initial.

The syntax in cond_syntax is, as in the ABAP Editor, not case-sensitive. When specifying an internal table, you can distribute the syntax over multiple rows. If cond_syntax is initial when the statement is executed, the logical expression is true. Invalid logical expressions trigger an exception from the class CX_SY_ITAB_DYN_LOOP.

The obsolete relational operators (><, =>, and =<) are not supported in cond_syntax.

Notes

Example

Reading of lines with certain line numbers in the primary table index that meet a condition. Demonstration of the static and dynamic declaration of a WHERE condition.






TXBHW - Original Tax Base Amount in Local Currency   BAL_S_LOG - Application Log: Log header data  
This documentation is copyright by SAP AG.

Length: 27390 Date: 20240623 Time: 194540     sap01-206 ( 493 ms )