READ is a keyword used in SAP ABAP programming.This tutorial covers its introduction & syntax details.
READ
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):
READ_BAD_KEY_ALIGN : The alignment requirements of the key take priority over those of individual table lines.
READ_BAD_KEY_PARTIAL : The key is longer than a table line and cannot be shortened.
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.
READ – Read a list line
Variants
1. READ LINE lin.
2. READ LINE lin OF CURRENT PAGE.
3. READ LINE lin OF PAGE pag.
4. READ CURRENT LINE.
Variant 1
READ LINE lin.
Additions
1. … INDEX idx
2. … FIELD VALUE f1 INTO g1
…
fm INTO gm
Effect
Reads line no. lin in the list, for instance by line selection ( AT LINE-SELECTION , AT PFxx, AT USER-COMMAND ).
Places
the read line in the field SY-LISEL and automatically restores all
‘hidden’ information (see HIDE ) to the original fields.
Sets the output format of the read line for all subsequent MODIFY LINE and WRITE statements.
The return code value is set as follows:
SY-SUBRC = 0 Line exists
SY-SUBRC <> 0 Line does not exist
Addition 1
… INDEX idx
Effect
With multiple line selection, reads the line from the list generated in level idx (0,1,2,…).
Addition 2
… FIELD VALUE f1 INTO g1
…
fm INTO gm
Effect
Transports
the contents of the fields f1 , f2 , … from the read list line to the
fields g1 , g2 , … . (The field contents stored in the list line
always have the type C; type conversion is the same as for MOVE .)
Note
All
formatting characters in the list output of f1 , f2 , … count as
field contents. If a field is output several times on the selected
line, only the first occurrence is taken into account. If the field
(such as f2 ) is not output on the line at all, the field g2 remains
unchanged. The addition INTO g2 , for example, can be omitted if the
field contents are to be restored to the original field (e.g. f2 ), i.e.
… FIELD VALUE … f2
has the same effect as
… FIELD VALUE … f2 INTO f2
Since
the return code value in SY-SUBRC is not affected by the addition FIELD
VALUE , it depends only on the existence of the selected list line.
Note
The
addition FIELD VALUE is especially suitable for processing user input
in list fields (see FORMAT , WRITE ) in the program. (Field contents
entered by the user cannot be addressed with HIDE .)
Example
You can make a line “selectable” with
DATA MARKFIELD(1) TYPE C.
…
WRITE: / MARKFIELD INPUT, ‘Text’.
After line selection, you can use
CLEAR MARKFIELD.
READ LINE SY-CUROW FIELD VALUE MARKFIELD.
in the program to check whether the user has selected the line or not ( IF MARKFIELD = SPACE … ).
Variant 2
READ LINE lin OF CURRENT PAGE.
Additions
As with variant READ LINE
Effect
As
with variant READ LINE lin . The line number lin refers to the current
page (as specified in the system field SY-CPAGE at the beginning of the
current event. If the contents of SY-CPAGE is changed by the
application program, this does not affect the display.)
Notes
With multiple level line selection, the read operation is always take place in the list where line selection was performed.
When
returning from line selection, the system always resets the positioning
to the last page displayed. (For scrolling purposes, you can use the
SCROLL statement.)
Variant 3
READ LINE lin OF PAGE pag.
Additions
As with variant READ LINE
Effect
As with variant 2, but reads the page pag instead of the current page.
Variant 4
READ CURRENT LINE.
Addition
… FIELD VALUE f1 INTO g1
…
fm INTO gm
Effect
Reads
the last line to be read (by line selection or with READ LINE ) once
again. You can use this variant, for example, in connection with the
addition FIELD VALUE (see below) .u.) if you want to retrieve field
contents from the selected line (in cases where you cannot retrieve
from the HIDE area).
Addition
… FIELD VALUE f1 INTO g1
…
fm INTO gm
Effect
See addition 2 of the variant READ LINE lin
READ – Read a program
Basic form
READ REPORT prog INTO itab.
Effect
Reads the program prog from the database into the internal table itab . Table itab should be at least 72 lines long.
The return code value is set as follows:
SY-SUBRC = 0 Program was read.
SY-SUBRC <> 0 Program could not be read.
Example
DATA: PROGRAM LIKE SY-REPID VALUE ‘PROGNAME’,
BEGIN OF T OCCURS 500,
LINE(72),
END OF T.
READ REPORT PROGRAM INTO T.
IF SY-SUBRC <> 0.
…
ENDIF.
READ – Read text elements
Basic form
READ TEXTPOOL prog … INTO itab … LANGUAGE lg.
Effect
Reads
the text elements for the program prog and the language lg from the
library into the internal table itab . The line structure of the table
itab is described in the section on text elements
The return code value is set as follows:
SY-SUBRC = 0 Text elements were read.
SY-SUBRC <> 0 Unable to read text elements.
Example
Read text elements for the program PROGNAME :
DATA: PROGRAM(8) VALUE ‘PROGNAME’,
TAB LIKE TEXTPOOL OCCURS 50 WITH HEADER LINE.
READ TEXTPOOL PROGRAM INTO TAB LANGUAGE SY-LANGU.
READ – Read a file
Basic form
READ DATASET dsn INTO f.
Addition
… LENGTH len
Effect
Reads
a record from the sequential file specified in dsn (a field or a
literal) and stores it in the field f (usually a field string).
Binary mode (addition IN BINARY MODE in the OPEN DATASET statement:
Read from file in length of field f .
Text mode (addition IN TEXT MODE in the OPEN statement):
Read a line.
If
the specified file is not open, READ DATASET attempts to open the file
dsn ( IN BINARY MODE FOR INPUT or with the specifications of the last
OPEN command for this file). Any errors result in the termination of
the program.
To read all the records in a file, you are recommended to place READ DATASET in a DO loop that you leave with EXIT .
The return code value is set as follows:
SY-SUBRC = 0 Record read from file.
SY_SUBRC = 4 End of file reached.
Example
Define the field string REC :
DATA: BEGIN OF REC,
TEXT(30),
NUMBER TYPE I,
END OF REC.
Read the file “/usr/test”:
DO.
READ DATASET ‘/usr/test’ INTO REC.
IF SY-SUBRC <> 0.
EXIT.
ENDIF.
WRITE: / REC-TEXT, REC-NUMBER.
ENDDO.
Notes
You can use TRANSFER to output records to a sequential dataset.
The
format of file names depends largely on the operating system. You can
access portable programs by using the function module FILE_GET_NAME
which returns the physical name for a given logical file name.
Addition
… LENGTH len
Effect
Stores the length of the record read from the file in the field len .
READ – Read a database table
Basic form
READ TABLE dbtab.
Additions
1. … SEARCH FKEQ
2. … SEARCH FKGE
3. … SEARCH GKEQ
4. … SEARCH GKGE
5. … WITH KEY key
6. … VERSION vers
Note
This
variant is no longer maintained and should therefore not be used (see
also obsolete lanuguage elements ). Please use a SELECT (SINGLE)
statement instead.
Effect
Accesses the database table dbtab
The
table dbtab must be declared under TABLES in the program. dbtab is a
table name which begins with “T” and comprises no more than five
characters altogether.
You must fill the argument fields of the table first; then you can use READ TABLE to make direct access to the table entry.
Example
Declare table:
TABLES T006.
Fill argument fields:
MOVE: ‘001’ TO T006-MANDT,
‘STD’ TO T006-MSEHI.
Access:
READ TABLE T006.
Process fields:
WRITE T006-DIMID.
Addition 1
… SEARCH FKEQ Full Key Equal (Default)
Addition 2
… SEARCH FKGE Full Key Greater or Equal
Addition 3
… SEARCH GKEQ Generic Key Equal
Addition 4
… SEARCH GKGE Generic Key Greater or Equal
Effect
Access table using one of the above search methods.
Note
You can only specify one of the additions 1 – 4
Addition 5
… WITH KEY key
Effect
Access table with the key key .
Addition 6
… VERSION vers
Note
You
should use this addition only if absolutely necessary. In some cases,
it is possible (and it makes sense) to avoid this READ addition by
using a generation program.
Effect
Specifies a dynamically
definable table name. The field vers must be a 4-character C field
which contains the table name. It is generally declared under
PARAMETERS and evaluated at runtime.
The entry read is always made available in the permanently assigned table T…
The return code value of SY-SUBRC specifies whether a suitable entry was found:
SY-SUBRC = 0 Entry found
SY-SUBRC <> 0 Entry not found
If the entry is not found, the system automatically sets the function part of the table entry to SPACE .
READ – Determine calendar information
The READ CALENDAR statement exists only in the R/2 System. In the R/3 System, the following function modules are substituted:
DATE_COMPUTE_DAY :
Returns the day for a date
DATE_CONVERT_TO_FACTORYDATE :
Returns the factory calendar date for a date
DATE_GET_WEEK :
Returns the week in which a date occurs
EASTER_GET_DATE :
Returns the Easter dates for a year
FACTORYDATE_CONVERT_TO_DATE :
Returns the date for a factory calendar date
HOLIDAY_CHECK_AND_GET_INFO :
Checks whether a date is a public holiday and, if necessary, returns information
WEEK_GET_FIRST_DAY :
Returns the first day of a week