INSERT - Insert into an Internal Table

Variants:

1. INSERT [wa INTO|INITIAL LINE INTO] itab [INDEX
idx] [ASSIGNING <fs>|REFERENCE INTO dref].

2. INSERT [wa INTO|INITIAL LINE INTO] TABLE itab
[ASSIGNING <fs>|REFERENCE INTO dref].

3. INSERT LINES OF itab1 [FROM idx1] [TO idx2]
INTO itab2 [INDEX idx3].

4. INSERT LINES OF itab1 [FROM idx1] [TO idx2]
INTO TABLE itab2.

The syntax check performed in an ABAP Objects context is stricter than in other ABAP areas.

See Cannot Use Short Forms in Line Operations.

Variant 1

INSERT [wa INTO|INITIAL LINE INTO] itab [INDEX idx] [ASSIGNING <fs>|REFERENCE INTO dref].

Effect

Inserts a new line in the internal table itab using an explicit or implicit index specification. You can only use this variant with index tables (standard or sorted tables).

If you use "wa INTO" the contents of the work area wa are used as the new line. If the type of wa is not compatible with the line type of itab, then the contents of wa are copied across using MOVE logic.

If you use INITIAL LINE INTO a line is inserted in the table, filled with the initial values appropriate to the field types.

If you do not specify anything before itab, the new line is taken from the header line of the internal table itab.

You use INDEX idx to specify the table index before which the line is inserted into itab. If the table has idx - 1 entries, the line is appended to the end of the table.

If you are adding entries to an index table using a LOOP, you can leave out the INDEX idx specification. The source table is inserted before the current line in the LOOP (implicit index specification).

If you use the addition ASSIGNING <fs>, the field symbol <fs> is set to the line you have just inserted. If you use the addition REFERENCE INTO ref, the data reference dref is filled with the reference of the line you have just inserted. Both the field symbol and the reference are only set if the statement is executed sucessfully.

If the target table itab has the type SORTED TABLE, it must be correctly sorted after you have finished inserting lines, otherwise a runtime error is triggered.

If the target table is defined with a UNIQUE KEY, the uniqueness must be preserved when you insert new lines. If it is not, a runtime error is triggered.

The Return Code is set as follows:

When you specify the insertion point using INDEX idx:

SY-SUBRC = 0:

The line was inserted successfully

SY-SUBRC = 4:

The index specified was too large. The line was not inserted, since the table has less than idx - 1 entries. If you use the addition ASSIGNING or REFERENCE INTO, <wa> or ref remains unchanged.

If you do not specify the point of insertion, Return Code is set to 0.

Notes

1. Within a LOOP ... ENDLOOP, the insertion of table lines takes effect in the next loop pass.
   
   
2. Illegal index specifications (idx <= 0) cause a runtime error.
   
   
   

Example

Adding values to a table of whole numbers:

DATA: VALUE TYPE I,
      ITAB  TYPE I OCCURS 100 WITH HEADER LINE.

ITAB  = 5.
VALUE = 36.

INSERT ITAB INDEX 1.
INSERT VALUE INTO ITAB INDEX 2.
INSERT INITIAL LINE INTO ITAB INDEX 2.

Die Tabelle ITAB enthält nun drei Zeilen mit den Werten 5, 0 und 36.

Variant 2

INSERT [wa INTO|INITIAL LINE INTO] TABLE itab  [ASSIGNING <fs>|REFERENCE INTO dref].

Effect

Inserts generically with a key into an internal table. The key values are taken from the work area. If you specify the work area explicitly, it must have a type compatible with the line type of the table.

In contrast to variant 1, you can use this variant for any table. All additions have the same meaning as with variant 1.

If the target table has a UNIQUE KEY, the system ignores any duplicates when you insert lines and sets SY-SUBRC as described below.

The way in which the system inserts a new entry into the table depends on the table type:

• STANDARD TABLE:
  The new entry is added to the end of the table. Generic insertion is therefore the same as an APPEND.
  
  
• SORTED TABLE:
  The new entry is added in its appropriate place, determined by the table key. The key values are taken from the specified work area wa or from the header line of the table. If the key is NON-UNIQUE, the entry is placed at the top of the list of duplicates. The insertion point is determined internally using a binary search. This makes the relationship between the runtime required and the number of table entries logarithmic.
  
  
• HASHED TABLE:
  The new entry is placed in the internal hash administration of the table according to the table key. The key values are taken from the specifiedwork area wa or the header line of the table. The runtime required remains constant, since it does not depend on the number of table entries. The key must be unique.
  
  

The Return Code is set as follows:

SY-SUBRC = 0:

Entry added to the table.

SY-SUBRC = 4:

The entry could not be added to the table, since it duplicates an existing entry and the table is defined with a UNIQUE KEY. If you use the addition ASSIGNING or REFERENCE INTO, <wa> or ref remains unchanged.

Example

Construct a table sorted by name and age:

TYPES: BEGIN OF PERSON,
         NAME(10) TYPE C,
         AGE      TYPE I,
       END OF PERSON.

DATA: P    TYPE PERSON,
      PTAB TYPE SORTED TABLE OF PERSON
                WITH UNIQUE KEY NAME AGE.

P-NAME = 'Steve'. P-AGE = 20. INSERT P INTO TABLE PTAB.
P-NAME = 'Andy'.  P-AGE = 20. INSERT P INTO TABLE PTAB.
P-NAME = 'Steve'. P-AGE = 17. INSERT P INTO TABLE PTAB.
P-NAME = 'Andy'.  P-AGE = 20. INSERT P INTO TABLE PTAB.

Die Tabelle enthält nun die folgenden Einträge:

   Andy               20
   Steve              17
   Steve              20

SY-SUBRC is set to 4.

Variant 3

INSERT LINES OF itab1 [FROM idx1] [TO idx2] INTO itab2 [INDEX idx3].

Effect

Inserts the internal table itab1 or an extract of it into the internal table itab2. This operation is the same as using a loop at the source area and inserting the entries into the target table line-by-line.

In INDEX idx3, like in variant 1, you specify the table index position before which you want to insert the entry in itab2. itab2 cannot have the type HASHED or ANY TABLE, since these tables have no defined index operations.

If you are using a LOOP you can omit the INDEX idx3 specification. The entry is then inserted in the target table before the current LOOP line.

If the target table itab2 has the type SORTED TABLE, it must be correctly sorted when you have finished adding entries. Otherwise, a runtime error occurs.

If the target table is defined with a UNIQUE KEY, you must ensure that this characteristic is preserved when you add more entries to it. If you try to add duplicate records, a runtime error occurs.

You can restrict the number of lines taken from the source table itab1 by using FROM idx1 and TO idx2. If you omit FROM idx1, the range begins at the first line of itab1. If you omit TO idx2, the range ends at the last line of itab1. This means that if you omit both FROM and TO, the whole table is inserted into the target table. If itab1 has the table type HASHED or ANY TABLE, you may not use the FROM or TO additions, since these table types have no defined index operations.

Return Code is set in the same way as in variant 1. If you insert an empty source table, SY-SUBRC = 0.

Notes

1. You can find out the size of table itab1 before or after the INSERT statement using the DESCRIBE TABLE itab1 LINES ... statement. You can then see how many lines were added to the table.
   
   
   
2. Within a LOOP ... ENDLOOP, inserting table entries affects subsequent loop passes.
   
   
   
3. Illegal index specifications, such as idx1 <= 0, cause a runtime error.
   
   
   

Example

Insert one table of names into another table of names:

TYPES NAME(10) TYPE C.

DATA: NAME_TAB_1 TYPE STANDARD TABLE OF NAME WITH

                      NON-UNIQUE DEFAULT KEY INITIAL SIZE 5,
      NAME_TAB_2 TYPE STANDARD TABLE OF NAME WITH

                      NON-UNIQUE DEFAULT KEY INITIAL SIZE 5.

APPEND 'Alice'  TO NAME_TAB_1.
APPEND 'Martha' TO NAME_TAB_1.
APPEND 'Ruth'   TO NAME_TAB_1.

APPEND 'Harry'  TO NAME_TAB_2.
APPEND 'Walter' TO NAME_TAB_2.

INSERT LINES OF NAME_TAB_1 FROM 2 INTO NAME_TAB_2 INDEX 2.

Afterwards, NAME_TAB_2 contains four entries with the names Harry, Martha, Ruth and Walter.

Variant 4

INSERT LINES OF itab1 [FROM idx1] [TO idx2] INTO TABLE itab2.

The syntax check performed in an ABAP Objects context is stricter than in other ABAP areas. See Compatible Line Types When Using the INSERT INTO TABLE Statement.

Effect

Generic insertion of internal table itab1 or an extract of it into internal table itab2.

Unlike variant 3, you can use this variant for any source or target table.

The way in which the lines from the source table itab1 are inserted into the target table itab2 depends, as in variant 2, on the table type of itab2.

If the target table is defined with a UNIQUE KEY, you must ensure that this characteristic is preserved when you add new entries. If you try to add duplicate entries, a runtime error occurs. If it is defined with a non-unique key, duplicates from the source table will be inserted before the entries in the target table. The sequence of duplicates from the source table remains unchanged.

Notes

Performance:

1. When you add a line to an index table, index maintenance costs result. These depend on the insertion point in the table.
   
   Inserting a line into the middle of an internal table 100 bytes wide with 200 entries, requires around 90 msn (standard microseconds).
   
   
2. If you want to add an internal table to another internal table, the index maintenance costs only occur once when you use the INSERT LINES OF ... variant. This is considerably faster than using a LOOP to insert lines one-by-one from the source table into the target table.
   
   Inserting a table 100 bytes wide with 500 entries into the middle of a similar-sized table can be up to 20 times quicker.
   
   
3. 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.
   
   
   

Exceptions

Non-Catchable Exceptions

• Cause: Entries with an identical key occurred when a line set was inserted (target table defined with UNIQUE)
  Runtime Error: ITAB_DUPLICATE_KEY
  
• Cause: The sort sequence has been violated due to an INSERT with an index into a sorted table.
  Runtime Error: ITAB_ILLEGAL_SORT_ORDER
  
• Cause: Invalid index value (<= 0) in a FROM, TO or INDEX specification.
  Runtime Error: TABLE_INVALID_INDEX
  
  
  

Related

COLLECT itab, APPEND, SELECT / FETCH NEXT CURSOR ... INTO/APPENDING TABLE itab, MODIFY itab, WRITE f TO itab INDEX idx, SORT itab, READ TABLE itab, LOOP AT itab, DELETE itab

Additional help

Inserting Lines in Tables

Inserting Lines in Tables Using the Index