Syntax Diagram
COLLECT
Basic form
COLLECT [wa INTO] itab.
Extras:
1. ... ASSIGNING <fs>
2. ... REFERENCE INTO dref
3. ... SORTED BY f
The syntax check performed in an ABAP Objects context is stricter than in other ABAP areas. See Cannot Use Short Forms in Line Operations.
Effect
COLLECT allows you to create unique or summarized datasets. The system first tries to find a table entry corresponding to the table key. (See also Defining Keys for Internal Tables). The key values are taken either from the header line of the internal table itab, or from the explicitly-specified work area wa. The line type of itab must be flat - that is, it cannot itself contain any internal tables. All the components that do not belong to the key must be numeric types ( ABAP Numeric Types).
If the system finds an entry, the numeric fields that are not part of the table key (see ABAPNumeric Types) are added to the sum total of the existing entries. If it does not find an entry, the system creates a new entry instead.
The way in which the system finds the entries depends on the kind of the internal table:
STANDARD TABLE:
The system creates a temporary hash administration for the table to find the entries. This means that the runtime required to find them does not depend on the number of table entries. The administration is temporary, since it is invalidated by operations (such as DELETE, INSERT, MODIFY, or SORT). A subsequent COLLECT is then no longer independent of the table size, because the system has to use a linear search to find entries. For this reason, you should only use COLLECT to fill standard tables.
SORTED TABLE:
The system uses a binary search to find the entries. There is a logarithmic relationship between the number of table entries and the search time.
HASHED TABLE:
The system uses the internal hash administration of the table to find records. Since (unlike standard tables), this remains intact even after table modification operations, the search time is always independent of the number of table entries.
For standard tables and SORTED TABLEs, the system field SY-TABIX contains the number of the existing or newly-added table entry after the COLLECT. With HASHED TABLEs, SY-TABIX is set to 0.
Notes
COLLECT allows you to create a unique or summarized dataset, and you should only use it when this is necessary. If neither of these characteristics are required, or where the nature of the table in the application means that it is impossible for duplicate entries to occur, you should use INSERT [wa INTO] TABLE itab instead of COLLECT. If you do need the table to be unique or summarized, COLLECT is the most efficient way to achieve it.
If you use COLLECT with a work area, the work area must be compatible with the line type of the internal table.
If you edit a standard table using COLLECT, you should only use the COLLECT or MODIFY ... TRANSPORTING f1 f2 ... statements (where none of f1, f2, ... may be in the key). Only then can you be sure that:
-The internal table actually is unique or summarized
-COLLECT runs efficiently. The check whether the dataset
already contains an entry with the same key has a constant
search time (hash procedure).
If you use any other table modification statements, the check for entries in the dataset with the same key can only run using a linear search (and will accordingly take longer). You can use the function module ABL_TABLE_HASH_STATE to test whether the COLLECT has a constant or linear search time for a given standard table.
Example
Summarized sales figures by company:
TYPES: BEGIN OF COMPANY,
NAME(20) TYPE C,
SALES TYPE I,
END OF COMPANY.
DATA: COMP TYPE COMPANY,
COMPTAB TYPE HASHED TABLE OF COMPANY
WITH UNIQUE KEY NAME.
COMP-NAME = 'Duck'. COMP-SALES = 10. COLLECT COMP INTO COMPTAB.
COMP-NAME = 'Tiger'. COMP-SALES = 20. COLLECT COMP INTO COMPTAB.
COMP-NAME = 'Duck'. COMP-SALES = 30. COLLECT COMP INTO COMPTAB.
Table COMPTAB now has the following contents:
NAME | SALES
---------------
Duck | 40
Tiger | 20
Addition 1
... ASSIGNING <fs>
Effect
If this statement is successfully executed, the field symbol <fs> is set to the changed or new entry. Otherwise the field symbol remains unchanged.
Addition 2
... REFERENCE INTO dref
Effect
If this statement is successfully executed the reference to the relevant line is placed in dref. Otherwise the data reference dref remains unchanged.
Addition 3
... SORTED BY f
Effect
COLLECT ... SORTED BY f is obsolete, and should no longer be used. It only applies to standard tables, and has the same function as APPEND ... SORTED BY f, which you should use instead. (See also Obsolete Language Elements).
Note
Performance:
If you are still using internal tables with headers but, as recommended, keep your data in work areas with a different name, you do not need to assign the data to the header first in order to pass it to the internal tables. Instead, you should use the work area directly as with tables without headers. For example, "APPEND wa TO itab." is roughly twice as fast as "itab = wa. APPEND itab.". The same applies to COLLECT and INSERT.
The runtime of a COLLECT increases with the width of the table key and the number of numeric fields whose contents are summated.
Exceptions
Catchable Exceptions
CX_SY_ARITHMETIC_OVERFLOW
Cause: Overflow in the integer field when forming totals
Runtime Error: COLLECT_OVERFLOW
Cause: overflow in type P field when forming totals
Runtime Error: COLLECT_OVERFLOW_TYPE_P
Non-Catchable Exceptions
Cause: COLLECT on non-numeric fileds
Runtime Error: TABLE_COLLECT_CHAR_IN_FUNCTION
Related
APPEND, WRITE ... TO, MODIFY, INSERT
Additional help
Inserting Summarized Table Lines
