READ - Reading an Internal Table

Variants:

1. READ TABLE itab FROM wa [ additions].


2. READ TABLE itab WITH TABLE KEY k1 = v1 ... kn = vn [additions].


3. READ TABLE itab WITH KEY k1 = v1 ... kn = vn [BINARY SEARCH] [additions].


4. READ TABLE itab INDEX i [additions].

Obsolete Variants

The syntax check performed in an ABAP Objects context is stricter than in other ABAP areas. See Short Forms of Line Operations not Allowed.

In some cases, the syntax rules that apply to Unicode programs are different than those for non-Unicode programs.See Key Specifications and Unicode.

Effect

Reads an entry from an internal table, using either its key or its index. The return code SY-SUBRC specifies whether an entry could be read. If you specify a non-unique key (the table must have a NON-UNIQUE key for this to be valid), the system returns the entry with the lowest index from the set of entries that meet the condition.

SY-SUBRC = 0:
An entry was read.
SY-TABIX is set to the index of the entry.
SY-SUBRC = 2:
An entry was read.
SY-TABIX is set to the index of the entry. This return code can only occur when you use the COMPARING addition. For further detauls, refer to the COMPARING section of the additions
SY-SUBRC = 4:
No entry was read.
The value of SY-TABIX depends on the table type and whether the BINARY SEARCH addition was specified.
If the table is a SORTED TABLE or a table sorted in ascending order of the type STANDARD TABLE with the BINARY SEARCH addition, SY-TABIX refers to the next-highest index.
Otherwise, SY-TABIX is undefined.
SY-SUBRC = 8:
No entry was read.
This return code only occurs with a SORTED TABLE or a STANDARD TABLE with the BINARY SEARCH addition. SY-TABIX is set to the number of all entries plus 1.

The READ TABLE statement also fills the system fields SY-TFILL and SY-TLENG.

Variant 1

READ TABLE itab FROM wa [additions].

Variant 2

READ TABLE itab WITH TABLE KEY k1 = v1 ... kn =

vn [additions].

Effect

The system uses the specified table key values to locate the correct line. If there is more than one entry with the same key, the system returns the first. The way in which the system looks for table entries depends on the table type:

Notes

  1. When you specify the table key using k1 = v1 ... kn = vn you must specify values for all of the key fields. If the type of a value is not compatible with the type of the corresponding key field,the system uses MOVE logic to convert it to the type of the key field before reading from the table.

  2. If you do not know the name of a component until runtime, you can use the expression WITH TABLE KEY ... (ni) = vi ... to specify it dynamically as the contents of the field ni. If ni is empty at runtime, the key specification is ignored.

  3. If a table has a non-structured line type, you can use the pseudocomponent TABLE_LINE to address the entire line as the table key (see also Pseudocomponent TABLE_LINE in Internal Tables).

  4. If you specify the key implicitly using FROM wa, the values for the table key are taken from the corresponding components of the (structured) field wa. wa must be compatible with the line type of itab. In this way, you can access a table using READ without having to know the table key statically. If the table key is empty, the system reads the first line.


Variant 3

READ TABLE itab WITH KEY k1 = v1 ... kn = vn
[BINARY SEARCH] [additions].

Effect

The system evaluates the specified key to identify the correct line. If the type of a value is not compatible with the type of the corresponding key field, the system uses MOVE logic to convert the value into the type of the component before reading the table. This is an asymmetric comparison logic, in which the component type takes precedence over the value type.
The way in which the system looks for an entry in the table depends on its table type. The system optimizeds the key access whenever possible (see Optimized Key Operations With Internal Tables).

Notes

  1. The system reads the first entry in which the specified components k1 ... kn correspond with the values of v1 ... vn. If the type of a value and the type of the corresponding key are incompatible, the system uses MOVE logic to convert the value into the type of the component before reading the table.

  2. If your table has a non-structured line type, you can use the pseudocomponent TABLE_LINE to address the entire line as the key (see also Pseudocomponent TABLE_LINE with Internal Tables).

  3. If you do not know the name of a component until runtime, you can use the expression WITH KEY ... (ni) = vi ... to specify it dynamically as the contents of the field ni. If ni is empty at runtime, the system ignores the component. If ni contains an invalid component name, a runtime error occurs. If ni contains an empty name, the system ignores the key specification.

  4. If the line type of the internal table contains object reference variables as componetns or the entire line type is a reference variable, you can use the attributes of the object to which the reference is pointing in a particular line as key values (see Attributes of Objects as the Key of an Internal Tables).

  5. If you specify a completely empty key, the system reads the first entry from the table.


  6. You restrict your specification using offset and length. This is valid for both the static and dynamic variant.


Variant 4

READ TABLE itab INDEX i [additions].


Effect

Accessing the table entry with the index i.

Notes

Performance:

  1. The quickest way to access a single line of an internal table is direct access using an index, because the response time is then not linked to the size of the table, and is restricted more or less to the transport costs for a single line.
    For hashed tables, the response time is constant. Accessing a table using the hash administration makes the response time around 3 times slower than using index access.
    If you use the key to access a table, the response time increase as the number of table entries and the size of the search key increase. Searching using a binary search is considerably quicker than using a linear search. Therefore, in many cases it can be quicker to sort the table and then use the BINARY SEARCH addition.

    The runtime required to read a line from a table with 100 entries using the index is around 7 msn (standard microseconds), to read a line using a key of 30 bytes using a binary search, around 25 msn, and without binary search, around 100 msn.

  2. Using statements that use an explicit work area for internal tables with a header line can avoid unnecessary value assignments.

Exceptions

Non-Catchable Exceptions

Additional help

Reading Table Lines

Reading Table Lines Using the Index