READ TABLE, result - ABAP Keyword Documentation

ABAP - Keyword Documentation → ABAP - Programming Language → Processing Internal Data → Internal Tables (itab) → itab - Processing Statements → READ TABLE itab →

Mail Feedback

READ TABLE, result

Short Reference

Syntax

... { INTO wa [transport_options] }
  | { ASSIGNING <fs> [CASTING] [ELSE UNASSIGN] }
  | { REFERENCE INTO dref }
  | { TRANSPORTING NO FIELDS }.

Alternatives:

1. ... INTO wa [transport_options]

2. ... ASSIGNING <fs> [CASTING] [ELSE UNASSIGN]

3. ... REFERENCE INTO dref

4. ... TRANSPORTING NO FIELDS

Programming Guideline

Output Behavior

Effect

Defines the output behavior of a READ statement for an internal table. There are four alternatives for the output behavior:

The addition INTO assigns the content of the found line to a work area. This addition can be used regardless of how itab is specified.
The addition ASSIGNING assigns the found line to a field symbol <fs>. This addition is possibly only if an existing internal table is specified for itab.
The addition REFERENCE INTO creates a reference to the found line in a reference table. This addition is possibly only if an existing internal table is specified for itab.
The addition TRANSPORTING NO FIELDS specifies that only the relevant system fields are filled. This addition can be used regardless of how itab is specified.

Hint

Outside of classes, the addition INTO can also be specified together with TRANSPORTING NO FIELDS, but this produces a warning in the syntax check

Alternative 1

... INTO wa [transport_options]

Effect

The content of the found line is assigned to the work area wa. The following can be specified for wa:

An existing work area that matches the line type of the internal table. The line type must be compatible with or convertible to the data type of the work area. If the work area is incompatible with the line type of the internal table, the content of the table line is converted to the data type of the work area in accordance with the conversion rules.
An inline declaration DATA(var) or FINAL(var), where a work area with the line type of the internal table is declared. The line type must be known statically and completely.

If no line is found, wa remains unchanged or initial. If a conversion error occurs in the assignment to wa, the exception cannot be handled using CX_SY_CONVERSION_ERROR and the associated runtime error occurs instead.

If the additions transport_options are used, the work area wa must be compatible with the line type of the internal table.

Hint

For READ TABLE, an obsolete short form exists where INTO wa can be omitted if the internal table has an identically named header line itab. INTO itab is then implicitly added to the statement. This short form is independent of the obsolete key specification, which also evaluates the header line.

Example

Reading of a particular line in the internal table sflight_tab and assignment to a work area sflight_wa declared inline. After a successful assignment, the content of a component of the line is changed in the internal table.

DATA: carrid TYPE sflight-carrid,
      connid TYPE sflight-connid,
      fldate TYPE sflight-fldate.

...

DATA sflight_tab TYPE SORTED TABLE OF sflight
                 WITH UNIQUE KEY carrid connid fldate.

SELECT *
       FROM sflight
       WHERE carrid = @carrid AND
             connid = @connid
       INTO TABLE @sflight_tab.

IF sy-subrc = 0.
  READ TABLE sflight_tab
       WITH TABLE KEY carrid = carrid
                      connid = connid
                      fldate = fldate
       INTO DATA(sflight_wa).
  IF sy-subrc = 0.
    sflight_wa-price *= '0.9'.
    MODIFY sflight_tab FROM sflight_wa INDEX sy-tabix.
  ENDIF.
ENDIF.

Alternative 2

... ASSIGNING <fs> [CASTING] [ELSE UNASSIGN]

Additions:

1. ... CASTING

2. ... ELSE UNASSIGN

Effect

The found table line is assigned to a field symbol. After the statement READ TABLE, the field symbol points to the table line in the memory. The addition cannot be specified if itab is specified as the return value or result of a functional method, a constructor expression, or a table expression, since this value no longer exists once the statement has been executed.

The following can be specified for <fs>:

An existing field symbol whose typing matches the line type of the internal table. The optional addition CASTING can be used to perform a casting.
An inline declaration FIELD-SYMBOL(<fs>), where a field symbol with the line type of the internal table is declared. If this cannot be known statically, the field symbol is declared with the generic type any and is assigned the constant space initially. The addition CASTING is not possible after an inline declaration.

If no table line is found, the state of <fs> depends on the addition ELSE UNASSIGN.

As long as the field symbol points to the line, assignments to the field symbol modify the line in the internal table. The following restrictions apply with respect to modifications to key fields of the primary and secondary table keys:

The key fields of the primary table key of sorted tables and hashed tables are read-only and must not be modified, since this would invalidate internal table administration. The processing statements for internal tables check whether writes are performed on individual key fields and a corresponding attempt raises an uncatchable exception. If writes are performed in write positions across the entire table line, for example, as a target field of assignments or as actual parameters for output parameters, an exception is always raised.
The key fields of a secondary table key, however, are only read-only, while the secondary table is used. This is the case for LOOP and when using the MODIFY statement where the secondary key is specified after USING KEY. Otherwise the key fields are not read-only.

The administration of unique secondary keys is updated after modifications are made to individual lines using field symbols the next time the internal table is accessed (delayed update). The administration of non-unique secondary keys is updated after the next explicit use of the secondary key (lazy update). The check on the uniqueness of a secondary key does not take place until the time of the update. An internal table might therefore be in an inconsistent state with respect to the secondary key after individual lines have been modified using field symbols, which does not raise an exception until the table is next used. If the next use is not directly after the modification, the secondary key can be explicitly updated using methods of the class CL_ABAP_ITAB_UTILITIES to handle any exceptions on the spot.

Hints

The typing of the field symbol must match the line type of the internal table.
If the READ statement is successful (sy-subrc has value 0), it is guaranteed that the field symbol immediately points to a memory area after the execution of the statement. A query using IS ASSIGNED is not necessary there.
If the addition ELSE UNASSIGN is not used, it is recommended that the return code sy-subrc is evaluated and that IS ASSIGNED is not used, since in case of an unsuccessful read, the field symbol keeps its previous state and a memory area can be assigned to field symbol. This applies in particular to inline declarations. If the addition ELSE UNASSIGN is used, sy-subrc as well as the predicate IS ASSIGNED can be used.
If the line to which the field symbol points is deleted, no more memory area is assigned to the field symbol and it can no longer be used instead of a data object. If the field symbol is not used directly after the READ statement, it may be useful to carry out a check using IS ASSIGNED.
Another form of the statement READ TABLE using the addition ASSIGNING is the specification of a table expression table_exp after the statement ASSIGN.

Addition 1

... CASTING

Effect

The addition CASTING has the same meaning as if it were specified without further additions in the statement ASSIGN: The field symbol must be either completely typed, or typed with one of the generic built-in ABAP types c, n, p, or x. The assigned table line is cast to the type of the field symbol. The same exceptions can be raised here as with ASSIGN.

The addition CASTING cannot be used if the field symbol is declared inline with FIELD-SYMBOL.

Addition 2

... ELSE UNASSIGN

Effect

The addition ELSE UNASSIGN sets the state of the field symbol to unassigned if no table line is found and sy-subrc is set to 4 or 8. If ELSE UNASSIGN is not specified, the field symbol keeps its previous state.

Hint

See also the addition ELSE UNASSIGN of the statement ASSIGN.

Example

Reading of a particular line in the internal table sflight_tab and assignment to a field symbol <sflight> declared inline. After a successful assignment, the content of a component of the line is changed in the internal table. See also the example of the assignment of a table expression to a field symbol.

DATA: carrid TYPE sflight-carrid,
      connid TYPE sflight-connid,
      fldate TYPE sflight-fldate.

...

DATA sflight_tab TYPE SORTED TABLE OF sflight
                 WITH UNIQUE KEY carrid connid fldate.

SELECT *
       FROM sflight
       WHERE carrid = @carrid AND
             connid = @connid
       INTO TABLE @sflight_tab.

IF sy-subrc = 0.
  READ TABLE sflight_tab
       WITH TABLE KEY carrid = carrid
                      connid = connid
                      fldate = fldate
       ASSIGNING FIELD-SYMBOL(<sflight>) ELSE UNASSIGN.
  IF <sflight> IS ASSIGNED.
    <sflight>-price *= '0.9'.
  ENDIF.
ENDIF.

Alternative 3

... REFERENCE INTO dref

Effect

A reference to the found table line is made in the data reference variable dref. The addition cannot be specified if itab is specified as the return value or result of a functional method or of a table expression of a constructor expression, since this value no longer exists once the statement has been executed.

The following can be specified for dref:

An existing data reference variable whose static type is compatible with the line type of the internal table or is the generic type data.
An inline declaration DATA(var) or FINAL(var), where a data reference variable is declared whose static type is the line type of the internal table. The line type must be known statically and completely.

If no table line is found, dref remains unchanged or initial.

By dereferencing the data reference, the content of the found table line can be evaluated and changed. The same restrictions apply to the modification of key fields of the primary and secondary table key as to access using field symbols (see ASSIGNING addition).

Hints

If the READ statement is successful (sy-subrc has value 0), it is guaranteed that the data reference variable immediately points to a line after the execution of the statement. A query using IS BOUND is not necessary here.
Alongside the statement GET REFERENCE and the reference operator REF, REFERENCE INTO is the only way of creating stack references. Stack references can become invalid if the referenced data object is deleted.
When applied to internal tables in the heap REFERENCE INTO creates memory-retaining heap references.
All references (heap references and stack references) that point to lines from internal tables can become invalid when lines are deleted. If a data reference variable is not used directly after the READ statement, it may be useful to carry out a check using IS BOUND.

Example

Reading of a particular line of the internal table sflight_tab and assignment of a reference to the found line to the data reference variable sflight_ref (declared inline). After a successful assignment, the content of a component of the line is changed in the internal table.

DATA: carrid TYPE sflight-carrid,
      connid TYPE sflight-connid,
      fldate TYPE sflight-fldate.

...

DATA sflight_tab TYPE SORTED TABLE OF sflight
                 WITH UNIQUE KEY carrid connid fldate.

SELECT *
       FROM sflight
       WHERE carrid = @carrid AND
             connid = @connid
       INTO TABLE @sflight_tab.

IF sy-subrc = 0.
  READ TABLE sflight_tab
       WITH TABLE KEY carrid = carrid
                      connid = connid
                      fldate = fldate
            REFERENCE INTO FINAL(sflight_ref).

  IF sy-subrc = 0.
    sflight_ref->price *= '0.9'.
  ENDIF.
ENDIF.

Alternative 4

... TRANSPORTING NO FIELDS

Effect

If the addition TRANSPORTING NO FIELDS is used, the statement READ TABLE only checks whether the line that is being searched for exists and fills the system fields sy-subrc and sy-tabix. The system cannot access the content of the found line.

Hints

The predicate function line_exists can also be used to check the existence of a table line.
The table function line_index can also be used to identify the line number in the table index.

Example

Check whether a particular line exists in the internal table sflight_carr and assignment of the line number in the primary table index of the found line in sy-tabix to idx.

DATA carrid TYPE scarr-carrid.

...

DATA: scarr_tab TYPE SORTED TABLE OF scarr
                WITH UNIQUE KEY carrid,
      idx TYPE i.

SELECT *
       FROM scarr
       INTO TABLE @scarr_tab.

READ TABLE scarr_tab
     WITH TABLE KEY carrid = carrid
     TRANSPORTING NO FIELDS.
IF sy-subrc = 0.
  idx = sy-tabix.
ENDIF.

Continue
READ TABLE, transport_options
Example

itab - Output Area