READ TABLE - free_key
Short Reference
ABAP Syntax ... WITH KEY { comp1
= operand1 comp2 = operand2 ... [BINARY
SEARCH] }
| { keyname COMPONENTS
comp1 = operand1
comp2 = operand2 ... } ... .
ABAP_VARIANTS:
1
... WITH KEY comp1 = operand1 comp2 = operand2 ... [BINARY
SEARCH] ... .
2 ... WITH KEY keyname COMPONENTS comp1 = operand1 comp2 =
operand2 ... .
What does it do? Specifies a free search key. The free search key can be
defined freely or linked to the specification of a
secondary table key in
keyname .
Latest notes: Outside of classes, the two obsolete variants of the
addition WITH KEY are possible.
Table expressions enable reads to
be performed in operand positions too. The free key search is used
whenever components are specified without an explicit
key specified .
ABAP_VARIANT_1 ... WITH KEY comp1 = operand1 comp2 = operand2 ...
[BINARY SEARCH] ... .
ABAP_ADDITION:
... BINARY SEARCH
What does it do? Components comp1 comp2 ... can be declared as
search keys behind the WITH KEY addition, following the rules
here . An operand operand1 operand2 ...
is assigned to each of these search keys and must be
compatible with the data type of the
component (or convertible to this data type). No duplicate or
overlapping key declarations can be made.
operand1 operand2 ... are
general expression positions .
If necessary, the content of the operands is converted to the data type
of the components before the comparison. If an
arithmetic expression is
specified, the calculation type is
determined from its operands and the data type of the component and the
result, if necessary, is converted to the data type of the component.
The first row of the internal table is searched for whose values in
the specified components (or their subareas or attributes) match the
values in the assigned operands operand1 operand2 ...
The search runs as follows for the individual table types, without
BINARY SEARCH being specified:
Standard tables are searched in a
linear fashion.
Sorted tables are sorted in a binary
fashion if the specified search key is an initial part of the
primary table key or includes this
key; otherwise the search is linear.
The hash algorithm is used for hashed
tables if the specified search key is an initial part of the
primary table key or includes this
key; otherwise the search is linear.
If the name field of a component
comp is initial, the first row that matches the search key is
read. If all name fields are initial, the first row of the
internal table is read.
The system field sy-tabix is set in accordance with the table
type:
For index tables it is set to the number of rows found in the primary
table index
For hashed tables it is set to the value 0.
Latest notes: If the search key includes components that supply a
secondary table key of the
internal table without the key being declared in keyname , then a
warning is raised by the syntax check.
If there are multiple hits (due to an incomplete search key or
duplicate entries in the table), binary searches (using the BINARY
SEARCH addition in standard tables; automatic in sorted tables) also
return the first hit in accordance with the order of the rows in the
primary index. This is the row with the lowest row number.
If WITH KEY is used, note that the values of incompatible
operands operand1 operand2 ... are converted to the data type of
the columns before the comparison. This means that the
comparison rules do not apply to incompatible
data types. If a WHERE condition is used in the statements
LOOP ,
MODIFY , and
DELETE , however, the comparison
rules do apply, which can produce differing results.
Example ABAP Coding The internal table html_viewer_tab contains
references to HTML controls . The
READ statement reads the reference that points to a HTML
control in a specific container control.
DATA: container TYPE REF TO cl_gui_container,
html_viewer TYPE REF TO cl_gui_html_viewer.
DATA html_viewer_tab LIKE TABLE OF html_viewer.
...
CREATE OBJECT html_viewer EXPORTING parent = container.
APPEND html_viewer TO html_viewer_tab.
...
READ TABLE html_viewer_tab
WITH KEY table_line->parent = container
INTO html_viewer.
...
ABAP_ADDITION ... BINARY SEARCH
What does it do? The addition BINARY SEARCH produces a binary
search of the table, not linear. In the case of large tables (from
approximately 100 entries), this can significantly reduce runtime. The
table must, however, be sorted in ascending order by the components
specified in the search key. The priority of the sort order must match
exactly the order of the components in the search key. If this
requirement is not met, the correct row is not usually found.
The addition BINARY SEARCH is recommended for standard tables
where no appropriate sorted
secondary table key is defined.
The BINARY SEARCH addition can only be declared for
sorted tables if the specified search
key is in the correct sequence and is an initial part of the table key,
or includes the key. It has no special effect in this situation.
The addition BINARY SEARCH cannot be specified for
hashed tables .
Latest notes: The READ statement always uses the BINARY
SEARCH addition to perform an index access; this index access can
therefore only be used for tables with the appropriate type.
Formal parameters or a
field symbol must have at least the
generic type INDEX TABLE .
The addition BINARY SEARCH is based on standard sorting
according to the size of the components. Text sorting with the addition
AS TEXT of the statement SORT can
produce unexpected results, since the result for text-like components no
longer depends on the binary representation, but on the
locale of the current
text environment .
When the BINARY SEARCH addition is used, if there are multiple
hits (due to an incomplete search key or duplicate entries in the
table), the first hit according to the order of the rows in the primary
index is returned. This is the row with the lowest row number.
ABAP_VARIANT_2 ... WITH KEY keyname COMPONENTS comp1 = operand1
comp2 = operand2 ... .
What does it do? keyname can be used to declare
a table key . The same applies to the
declaration of the components as in the variant without key declaration.
If a secondary table key is
declared in keyname , the behavior is as follows:
If a sorted key is declared, the
specified search key must be an initial part of the secondary table key
or include it. The associated
secondary table index is then searched in a binary fashion. If
multiple entries are found when using a non-unique search key, the first
hit, that is the row with the lowest row number, is read in the
secondary index. Additional search criteria can also be specified which
are also evaluated.
If a hash key is declared, the specified
search key must include the secondary table key and the hash algorithm
is used. Additional search criteria can also be specified which are also
evaluated.
The system field sy-tabix is set with respect to the specified
secondary table key:
For sorted secondary keys, it is set to the number of the found row in
the corresponding secondary table index
For hash keys it is set to the value 0.
If the primary table key is
declared in keyname under the name primary_key , the
behavior is the same as in the variant without key declaration.
Latest notes: When free keys are specified, secondary table keys differ
from the table_key variant (for
declaring the table key) by making it possible to specify additional
conditions in the search key. These conditions can reduce the length of
the hitlist. For secondary sorted keys, however, free search keys make
it possible to specify an incomplete search key, which can make the
hitlist longer.
If a secondary table key is used, when the value of sy-tabix is
used subsequently as an index specification in other processing
statements for the internal table, it must be ensured that the same
table key is used.
Example ABAP Coding The DEMO_SECONDARY_KEYS
program demonstrates the specification of a secondary table key
compared to the completely free specification of a key and the resulting
performance benefits.
Documentation extract taken from SAP system, � Copyright SAP AG. All rights reserved