Show TOC

INSERT itab

INSERT - Insert into an Internal Table



Variants:


1. INSERT [wa INTO|INITIAL LINE INTO] itab [INDEX idx].
2. INSERT [wa INTO|INITIAL LINE INTO] TABLE itab.
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.

See Short forms not allowed in line operations.

Variant 1

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

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 respective types of wa and itab are incompatible, the contents of wa are moved according to
MOVEy 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 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 = 4:

    The index specified was too large. The line was not inserted, since the table has less than idx - 1 entries.

    If you do not use INDEY idx,

    return code

    is set to 0.

    • Notes

  • Within a LOOP ... ENDLOOP, the

    insertion of table lines
    takes effect in the next loop pass.


    • 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.

    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.

    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 = 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.

      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 table, SY-SUBRC is set to 0.

        • Notes
      • 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.

          • Within a LOOP ... ENDLOOP,
          • inserting table entries
            affects subsequent loop passes.
          • 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.

          See Compatible line types with INSERT INTO TABLE.

          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 the key is non-unique, duplicates from the source table are inserted before the entries in the target table. The sequence of the duplicates is the same as in the source table.

          Notes



          Performance:



          • 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).

          • 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.
        • Note



          Runtime errors:


          • TABLE_INVALID_INDEX: Invalid index value (<= 0) in a FROM, TO or INDEX addition.

          • ITAB_DUPLICATE_KEY: You inserted a set of lines, more than one of which had the same key (target table defined with UNIQUE).
          • ITAB_ILLEGAL_SORT_ORDER: The sort sequence has not been maintained in an INSERT with index into a sorted table. duplicate key.
        • 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 Table Entries



          Inserting Table Entries Using the Index