INSERT - Insert into internal table

Variants

1. INSERT [wa INTO|INITIAL LINE INTO] itab [INDEX idx].
2. INSERT LINES OF itab1 [FROM idx1] [TO idx2] INTO itab2
[INDEX idx3].

Variant 1

INSERT [wa INTO|INITIAL LINE INTO] itab [INDEX idx].

Effect

Inserts a new line into an internal table.

If you specify wa INTO , the new line is taken from the contents of the explicitly specified work area wa .

When using INITIAL LINE INTO , a line containing the appropriate initial value for its type is inserted into the table.

If you omit the specification before itab , the new line is taken from the header line of the internal table itab .

INDEX idx specifies the table index before which the line is inserted into the table itab . If the table has exactly idx - 1 entries, the line is appended to the table.

Within a LOOP , on an internal table, you do not have to specify the insertion point with INDEX idx . The source table is then inserted before the current LOOP line in the target table.

The return code value is set as follows:

When specifying the insertion point with INDEX idx :

SY-SUBRC = 0 The entry was inserted.
SY_SUBRC = 4 Index specification too large. The entry was not inserted because the table has fewer than idx - 1 entries.
Return code value If the insertion point is not specified, the is set to 0.

Note

Inserting lines within a LOOP ... ENDLOOP structure affects subsequent loop passes.
Invalid index specifications (for example, idx <= 0), result in a runtime error.

Example

Insert values into 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.

The table ITAB now contains three lines with the values 5, 0 and 36.

Variant 2

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

Effect

Inserts the internal table itab1 or a section of itab1 into the internal table itab2 .

As with variant 1, INDEX idx3 is to specifies the table index before which you want to insert in the target table itab2 .

Within a LOOP , on an internal table, you do not have to specify the insertion point with INDEX idx3 . The source table is then inserted before the current LOOP line in the target table.

By specifying FROM idx1 or TO idx2 , you can restrict the line area from which the source table itab1 is taken. If there is no FROM specification, the line area begins with the first line of itab1 . If there is no TO specification, the line area ends with the last line of itab1 . This means that the whole table is inserted, if neither a FROM nor a TO is specified.
Return code value
The is set as for variant 1.

Note

You can use DESCRIBE TABLE itab1 LINES ... to determine the size of the table itab1 before or after the INSERT statement and thus establish how many lines were actually inserted into the table.

Note

Inserting lines within a LOOP ... ENDLOOP structure affects subsequent loop passes.
Invalid index specifications (for example, idx <= 0), result in a runtime error.

Example

Insert a name table into another name table:


TYPES NAME(10) TYPE C.

DATA: NAME_TAB_1 TYPE NAME OCCURS 5,
      NAME_TAB_2 TYPE NAME OCCURS 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.

After the insertion, the table NAME_TAB_2 contains four entries with the names Harry , Martha , Ruth and Walter .

Note

Performance

Inserting a line into an internal table incurs index maintenance costs which depend on the insertion point.

For example, inserting a line in the middle of a 100-byte wide internal table with 200 entries requires about 90 msn (standardized microseconds).
If you want to insert the contents of one internal table into another internal table, you incur index maintenance costs only once with the variant INSERT LINES OF ... . Compared with a LOOP which inserts the lines of the source table one-by-one into the target table, this represents a distinct improvement in performance.

Inserting a table of 500 lines with a 100-byte line width in the middle of a similar size table can thus be amde up to 20 times faster.

Note

Runtime errors

TABLE_INVALID_INDEX : Invalid index value (<= 0) with a FROM , TO or INDEX specification.