INSERT is a keyword used in SAP ABAP programming.
This tutorial covers its introduction & syntax details.
INSERT
INSERT – Insert in a database table
Variants
1. INSERT INTO dbtab VALUES wa. or
INSERT INTO (dbtabname) VALUES wa.
2. INSERT dbtab. or
INSERT *dbtab. or
INSERT (dbtabname) …
3. INSERT dbtab FROM TABLE itab. or
INSERT (dbtabname) FROM TABLE itab.
Effect
Inserts new lines in a database table .
You
can specify the name of the database table either in the program itself
in the form dbtab or at runtime as the contents of the field dbtabname
. In both cases, the database table must be defined in the ABAP/4
Dictionary . If the program contains the name of the database table, it
must also include a corresponding TABLES statement. Normally, lines are
inserted only in the current client. Data can only be inserted using a
view if the view refers to a single table and was defined in the ABAP/4
Dictionary with the maintenance status “No restriction”.
INSERT belongs to the Open SQL command set.
Notes
You
cannot insert a line if a line with the same primary key already exists
or if a UNIQUE index already has a line with identical key field values.
When
inserting lines using a view , all fields of the database table that
are not in the view are set to their initial value (see TABLES ) – if
they were defined with NOT NULL in the ABAP/4 Dictionary . Otherwise
they are set to NULL .
Since the INSERT statement does not perform authorization checks , you must program these yourself.
Lines
specified in the INSERT command are not actually added to the database
table until after the next ROLLBACK WORK . Lines added within a
transaction remain locked until the transaction has finished. The end
of a transaction is either a COMMIT WORK , where all database changes
performed within the transaction are made irrevocable, or a ROLLBACK
WORK , which cancels all database changes performed within the
transaction.
Variant 1
INSERT INTO dbtab VALUES wa. or
INSERT INTO (dbtabname) VALUES wa.
Addition
… CLIENT SPECIFIED
Effect
Inserts one line into a database table.
The
line to be inserted is taken from the work area wa and the data read
from left to right according to the structure of the table work area
dbtab (see TABLES ). Here, the structure of wa is not taken into
account. For this reason, the work area wa must be at least as wide
(see DATA ) as the table work area dbtab and the alignment of the work
area wa must correspond to the alignment of the table work area.
Otherwise, a runtime error occurs.
When the command has been executed, the system field SY-DBCNT contains the number of inserted lines (0 or 1).
The return code value is set as follows:
SY-SUBRC = 0 Line was successfully inserted.
SY_SUBRC = 4 Line could not be inserted since a line with the same key already exists.
Example
Insert the customer Robinson in the current client:
TABLES SCUSTOM.
SCUSTOM-ID = ‘12400177’.
SCUSTOM-NAME = ‘Robinson’.
SCUSTOM-POSTCODE = ‘69542’.
SCUSTOM-CITY = ‘Heidelberg’.
SCUSTOM-CUSTTYPE = ‘P’.
SCUSTOM-DISCOUNT = ‘003’.
SCUSTOM-TELEPHONE = ‘06201/44889’.
INSERT INTO SCUSTOM VALUES SCUSTOM.
Addition
… CLIENT SPECIFIED
Effect
Switches
off automatic client handling. This allows you to insert data across
all clients even when dealing with client-specific tables. The client
field is then treated like a normal table field which you can program
to accept values in the work area wa that contains the line to be
inserted.
The addition CLIENT SPECIFIED must be specified immediately after the name of the database table.
Example
Insert the customer Robinson in client 2:
TABLES SCUSTOM.
SCUSTOM-MANDT = ‘002’.
SCUSTOM-ID = ‘12400177’.
SCUSTOM-NAME = ‘Robinson’.
SCUSTOM-POSTCODE = ‘69542’.
SCUSTOM-CITY = ‘Heidelberg’.
SCUSTOM-CUSTTYPE = ‘P’.
SCUSTOM-DISCOUNT = ‘003’.
SCUSTOM-TELEPHONE = ‘06201/44889’.
INSERT INTO SCUSTOM CLIENT SPECIFIED VALUES SCUSTOM.
Variant 2
INSERT dbtab. or
INSERT *dbtab. or
INSERT (dbtabname) …
Additions
1. … FROM wa
2. … CLIENT SPECIFIED
Effect
These are the SAP -specific short forms for the statements explained under variant 1.
INSERT INTO dbtab VALUES dbtab. or
INSERT INTO dbtab VALUES *dbtab. or
INSERT INTO (dbtabname) VALUES wa.
When the command has been executed, the system field SY-DBCNT contains the number of inserted lines (0 or 1).
The return code value is set as follows:
SY-SUBRC = 0 Line successfully inserted.
SY_SUBRC = 4 Line could not be inserted, since a line with the same key already exists.
Example
Add a line to a database table:
TABLES SAIRPORT.
SAIRPORT-ID = ‘NEW’.
SAIRPORT-NAME = ‘NEWPORT APT’.
INSERT SAIRPORT.
Addition 1
… FROM wa
Effect
The
values for the line to be inserted are not taken from the table work
area dbtab , but from the explicitly specified work area wa . The work
area wa must also satisfy the conditions described in variant 1. As
with this variant, the addition allows you to specify the name of the
database table directly or indirectly.
Note
If a work area is
not explicitly specified, the values for the line to be inserted are
taken from the table work area dbtab if the statement is in a FORM or
FUNCTION where the table work area is stored in a formal parameter or
local variable of the same name.
Addition 2
… CLIENT SPECIFIED
Effect
As for variant 1.
Variant 3
INSERT dbtab FROM TABLE itab. or
INSERT (dbtabname) FROM TABLE itab.
Additions
… CLIENT SPECIFIED
… ACCEPTING DUPLICATE KEYS
Effect
Mass
insert: Inserzts all lines of the internal table itab in a single
operation. The lines of itab must satisfy the same conditions as the
work area wa in variant 1.
When the command has been executed, the system field SY-DBCNT contains the number of inserted lines.
The return code value is set as follows:
SY-SUBRC = 0 All lines successfully inserted. Any other result causes a runtime error .
Note
If the internal table itab is empty, SY-SUBRC and SY-DBCNT are set to 0 after the call.
Addition 1
… CLIENT SPECIFIED
Effect
As for variant 1.
Addition 2
… ACCEPTING DUPLICATE KEYS
Effect
If
a line cannot be inserted, the processing does not terminate with a
runtime error, but the return code value of SY-SUBRC is merely set to
4. All the remaining lines are inserted when the command is executed.
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. INSERT – Insert into a field group
Basic form
INSERT f1 f2 … INTO fg.
Effect
Inserts one or more fields into the field group fg (see FIELD-GROUPS ).
Notes
This basic form of INSERT is not a declarative, but an operational, statement, i.e. it must be executed at runtime.
A field group can only accept global data objects, not data objects which have been defined locally in a FORM or FUNCTION .
The actual data transport is performed by EXTRACT .
As
soon as the first dataset for a field group has been extracted with
EXTRACT , the field group can no longer be extended with INSERT . The
field group HEADER cannot be extended at all after the first EXTRACT
(regardless of the field group).
Note
Runtime errors
EXTRACT_INSERT_LOCAL_DATA : Attempt to insert local data objects into a field group.
INSERT_INTO_LOCKED_FIELD_GROUP : INSERT into field group after records of this type had already been extracted with EXTRACT .
INSERT – Insert a program
Basic form
INSERT REPORT prog FROM itab.
Effect
Inserts
the program prog from the internal table itab into the library. The
internal table itab contains the source code; the lines of the table
cannot be more than 72 characters long. The program attributes (type,
date, …) are set by the system, but you can change them manually or
in the program (table TRDIR ).
Note
Runtime errors
INSERT_PROGRAM_INTERNAL_NAME :
The program name prog is reserve internally; it begins with ‘%_T’ .
INSERT_PROGRAM_NAME_BLANK :
The program name prog must not contain any blanks characters.
INSERT_PROGRAM_NAME_TOO_LONG :
The program name prog is too long; it cannot be more than 8 characters long.
INSERT_REPORT_LINE_TOO_LONG :
One of the source code lines is longer than 72 characters.
INSERT – Insert text elements
Basic form
INSERT TEXTPOOL prog …FROM itab …LANGUAGE lg.
Effect
Assigns
the text elements in the internal table itab to the program prog and
the language lg and inserts them in the library. The line structure of
the table itab is described in the section Text elements .
Example
The following program uses the internal table TAB to set the text elements of the program PROGNAME .
DATA: PROGRAM(8) VALUE ‘PROGNAME’,
TAB LIKE TEXTPOOL OCCURS 50 WITH HEADER LINE.
TAB-ID = ‘T’. TAB-KEY = SPACE. TAB-ENTRY = ‘Sales’.
APPEND TAB.
TAB-ID = ‘I’. TAB-KEY = ‘200’. TAB-ENTRY = ‘Tax’.
APPEND TAB.
TAB-ID = ‘H’. TAB-KEY = ‘001’. TAB-ENTRY = ‘Name Age’.
APPEND TAB.
TAB-ID = ‘S’. TAB-KEY = ‘CUST’. TAB-ENTRY = ‘Customer’.
APPEND TAB.
TAB-ID = ‘R’. TAB-KEY = SPACE. TAB-ENTRY = ‘Test program’.
APPEND TAB.
SORT TAB BY ID KEY.
INSERT TEXTPOOL PROGRAM FROM TAB LANGUAGE SY-LANGU.
Notes
As
in the example, the internal table should be sorted by the components
ID and KEY to enable faster access to the text elements at runtime.
However, this is not obligatory.
The component LENGTH (see text
elements ) for the length of a text element does not have to be set
explicitly. In this case – as in the example – the actual length of the
text element is used.
The value of LENGTH cannot be smaller than the
text to which it applies. If your length specification is too short, it
is ignored by INSERT and the actual length is used instead.
On the
other hand, larger values are allowed and can be used to reserve space
for texts that may be longer when translated into other languages.