READ - Read an internal table


Basic form

READ TABLE itab.
READ TABLE itab INTO wa.

Additions



1a. ... WITH KEY k1 = v1 ... kn = vn
1b. ... WITH KEY = value
1c. ... WITH KEY key
2. ... BINARY SEARCH
3. ... INDEX idx
4a. ... COMPARING f1 f2 ...
4b. ... COMPARING ALL FIELDS
5a. ... TRANSPORTING f1 f2 ...
5b. ... TRANSPORTING NO FIELDS

Effect

Reads an internal table entry. An entry can be chosen using a key or its index.

With " READ TABLE itab. ", the header line of the internal table itab is used as the output area; with " READ TABLE itab INTO wa. " the explicity specified work area wa is used for this purpose.

The return code value of SY-SUBRC specifies whether a suitable entry was found. In turn, this determines the value of the table index SY-TABIX .

SY-SUBRC = 0 Entry found

SY-TABIX is set to the index of the found entry.

SY-SUBRC <> 0 Entry not found

The value of SY-TABIX is undefined.
The output area remains unchanged.

Note

In the case of internal tables with a header, a table line can be accessed without specifying an explicit key (addition: WITH KEY ... ) or index (addition: INDEX idx ). The system then uses (as an implicit key) all table header fields that are not number fields (type I, F, P), are not tables themselves (compare default keys of internal tables) and whose contents are unequal to SPACE . It searches for the first entry which matches the header in all key fields and transfers this entry into the output area.

The implicit key is only set up (dynamically) at runtime. If the search key is already known at the time of generation (static), the read with an explicit key is faster than with an implicit key, and is therefore preferable.

Addition 1a

... WITH KEY k1 = v1 ... kn = vn

Effect

Accesses the first entry which matches v1 ... vn in the components specified with k1 ... kn . Here, the component type forms the basis for the comparison between the components and the values. If the type of a value and the type of a component are not compatible, the value is converted to the type of the component before the read access is performed.

Notes

If a component is not determined until runtime, you can use WITH KEY ... (ni) = vi ... to specify it dynamically as the contents of the field ni . If ni is empty at runtime, the component is ignored. If ni contains an invalid component name, a runtime error occurs.
You can use offset and/or length specifications to further restrict components, regardless of whether they have been specified statically or dynamically.

Addition 1b

... WITH KEY = value

Effect

Accesses the first entry which matches value . In this case, the type of the table line forms the basis for the comparison between table lines and the specified value. If the type of the specified value and the type of the table line are not compatible, the specified value is converted to the type of the table line before the read access is performed.

Note

Even with internal tables containing lines with no components, the addition WITH KEY = value allows you to access an entry via an explicity specified key. Internal tables without line components result when you define internal tables directly via an elementary data type or a table type, but not via a field string.

Addition 1c

... WITH KEY key

Effect

Accesses the first entry which begins with key (left-justified). The type of the specified key forms the basis for the comparison between table lines and the specified key.

Note

The key key can be neither a table nor a structure that contains tables as components.

Note

Runtime errors (only when using addition 1c):

Addition 2

... BINARY SEARCH

Effect

The addition BINARY SEARCH only makes sense with one of the WITH-KEY additions (1a-1c).

The read access is performed using a binary search method and is non-sequential. It is assumed that the internal table is sorted in ascending order according to the specified key, with addition 1a in the order of the specified key fields.

If the specified key is not unique, the entry with the lowest index is placed in the output area.

The return code value of SY-SUBRC specifies whether a suitable entry was found. In turn, this determines the value of the table index SY-TABIX .

SY-SUBRC = 0 Entry found

SY-TABIX is set to the index of the found entry

SY-SUBRC <> 0 Entry not found

The output area remains unchanged.

SY_SUBRC = 4 SY-TABIX points to the next largest entry.

SY-SUBRC = 8 The key sought is greater than that of the last table entry.

SY-TABIX is set to (number of all entries + 1).

Example


DATA: BEGIN OF INT_TABLE  OCCURS 100,
        COMP1,
        COMP2,
        COMP3,
      END OF INT_TABLE.

FORM PUT_ENTRY USING ENTRY LIKE LINE OF INT_TABLE.
  READ TABLE INT_TABLE WITH KEY COMP2 = ENTRY-COMP2
                       BINARY SEARCH
                       TRANSPORTING NO FIELDS.
  IF SY-SUBRC <> 0.
    INSERT ENTRY INTO INT_TABLE INDEX SY-TABIX.
  ENDIF.
ENDFORM.

The method used in this subroutine makes it easy (and desirable for performance) to add new entries to a table and sort them.
Before PERFORM PUT_ENTRY , you fill the transferred work area ENTRY with the new values. The READ statement checks (in the sorted internal table INT_TABLE ) whether an entry with the specified key already exists. The system fields SY-SUBRC and SY-TABIX are set accordingly. Then, if ( SY-SUBRC <> 0 ), the new entry is inserted at the appropriate place.

Addition 3

... INDEX idx

Effect

Accesses the entry with the index idx of an internal table.

The return code value of SY-SUBRC specifies whether a suitable entry was found. In turn, this determines the value of the table index SY-TABIX .

SY-SUBRC = 0 Entry found

SY-TABIX is set to the index of the found entry.

SY-SUBRC <> 0 Entry not found

The value of SY-TABIX is undefined.
The output area remains unchanged.

Addition 4a

... COMPARING f1 f2 ...

Effect

This addition has no effect on the read process itself, i.e. it is normally used together with one of the additions 1, 2 or 3.

Only when an entry - regardless of the read method - already exists does this addition cause the contents of the sub-fields f1, f2, ... of the found entry to be compared with the corresponding fields of the output area before transporting the found entry to the output area.

The return code value of SY-SUBRC specifies whether the value sought was found and, if so, the result of the comparison:

SY-SUBRC = 0 Entry found, field contents identical
SY-SUBRC = 2 Entry found, field contents different
SY-SUBRC > 2 Entry not found
If you want to indicate explicitly that no fields are compared (even though this is the default), you can use COMPARING NO FIELDS .

Notes

If you use COMPARING together with an explicitly specified work area, the lattter must be compatible with the line type of the internal table.
If a comparison criterion is not known until runtime, you can use COMPARING ... (name) ... to specify it dynamically as the contents of the name . If name is blank at runtime, the comparison criterion is ignored. If name contains an invalid component name, a runtime error occurs.
You can use offset and/or length specifications to further restrict comparison criteria, regardless of whether they have been specified statically or dynamically.
If you use READ TABLE itab in its basic form (i.e. without one of its additions 1, 2 or 3, the addition COMPARING f1 f2 ... makes sense only if the fields f1, f2, ... are not part of the read key, i.e. if f1, f2, ... are number fields (type I, F or P).

Addition 4b

... COMPARING ALL FIELDS

Effect

As with addition 4a, but compares all sub-fields.

Addition 5a

... TRANSPORTING f1 f2 ...

Effect

If an entry is found, not all sub-fields are transported to the output area (default), but only the specified sub-fields f1, f2, ... ; the other sub-fields remain unchanged.
If you want to indicate explicitly that all fields are transported (even though this is the default), you can use TRANSPORTING ALL FIELDS .

Notes

If you use TRANSPORTING f1 f2 ... together with an explicitly specified output area, the latter must be compatible with the line type of the internal table.
If a transport field is not known until runtime, you can use TRANSPORTING ... (name) ... to specify it dynamically as the contents of the name . If name is blank at runtime, the transport criterion is ignored. If name contains an invalid component name, a runtime error occurs.
You can use offset and/or length specifications to further restrict transport fields, regardless of whether they have been specified statically or dynamically.
If you use the additions " COMPARING " and " TRANSPORTING " together, " COMPARING " must come before " TRANSPORTING ".

Addition 5b

... TRANSPORTING NO FIELDS

Effect

Does not change the output area of the internal table. The only purpose of the access is to set the system fields SY-SUBRC and SY-TABIX .

Note

Performance

The fastest way of reading a single record from an internal table is to make a direct access by specifying an index, because this is not dependent on the number of table entries and is much the same as the cost of transporting one line.
If you use a key to access the table, the required runtime increases with the number of lines and the size of the search key. A binary search is considerably faster than a linear search. Therefore, it is usually advisable to keep the table sorted and to use the addition BINARY SEARCH .

Reading a record from a table with 100 entries with an index specification requires about 7 msn (standardized microseconds). Access with a 30-byte wide key takes about 25 msn. with a binary search, and about 100 msn. without a binary search.
If you use statements with an explicit work area for internal tables with a header line, you can avoid unnecessary assignments.

Index
© SAP AG 1996