Insert rows using the INSERT statement

This topic shows the basic SQL statements and clauses that insert data into tables and views. Examples using these SQL statements are supplied to help you develop SQL applications.

You can use the INSERT statement to add new rows to a table or view in one of the following ways:

Specifying values in the INSERT statement for columns to be added.
Including a select-statement in the INSERT statement to tell SQL what data for the new row is contained in another table or view.
Specifying the blocked form of the INSERT statement to add multiple rows.

For every row you insert, you must supply a value for each column defined with the NOT NULL attribute if that column does not have a default value. The INSERT statement for adding a row to a table or view may look like this:

   INSERT INTO table-name
      (column1, column2, ... )
   VALUES (value-for-column1, value-for-column2, ... )

The INTO clause names the columns for which you specify values. The VALUES clause specifies a value for each column named in the INTO clause. The value you specify can be:

A constant. Inserts the value provided in the VALUES clause.
A null value. Inserts the null value, using the keyword NULL. The column must be defined as capable of containing a null value or an error occurs.
A host variable. Inserts the contents of a host variable.
A special register. Inserts a special register value; for example, USER.
An expression. Inserts the value that results from an expression.
A scalar fullselect inserts the value that is the result of running the select statement.
The DEFAULT keyword. Inserts the default value of the column. The column must have a default value defined for it or allow the NULL value, or an error occurs.

You must provide a value in the VALUES clause for each column named in an INSERT statement's column list. The column name list can be omitted if all columns in the table have a value provided in the VALUES clause. If a column has a default value, the keyword DEFAULT may be used as a value in the VALUES clause. This causes the default value for the column to be placed in the column.

It is a good idea to name all columns into which you are inserting values because:

Your INSERT statement is more descriptive.
You can verify that you are providing the values in the proper order based on the column names.
You have better data independence. The order in which the columns are defined in the table does not affect your INSERT statement.

If the column is defined to allow null values or to have a default, you do not need to name it in the column name list or specify a value for it. The default value is used. If the column is defined to have a default value, the default value is placed in the column. If DEFAULT was specified for the column definition without an explicit default value, SQL places the default value for that data type in the column. If the column does not have a default value defined for it, but is defined to allow the null value (NOT NULL was not specified in the column definition), SQL places the null value in the column.

For numeric columns, the default value is 0.
For fixed length character or graphic columns, the default is blanks.
For fixed length binary columns, the default is hexadecimal zeros.
For varying length character, graphic, or binary columns and for LOB columns, the default is a zero length string.
For date, time, and timestamp columns, the default value is the current date, time, or timestamp. When inserting a block of records, the default date/time value is extracted from the system when the block is written. This means that the column will be assigned the same default value for each row in the block.
For DataLink columns, the default value corresponds to DLVALUE('','URL','').
For distinct-type columns, the default value is the default value of the corresponding source type.
For ROWID columns or columns that are defined AS IDENTITY, the database manager generates a default value.

When your program attempts to insert a row that duplicates another row already in the table, an error might occur. Multiple null values may or may not be considered duplicate values, depending on the option used when the index was created.

If the table has a primary key, unique key, or unique index, the row is not inserted. Instead, SQL returns an SQLCODE of -803.
If the table does not have a primary key, unique key, or unique index, the row can be inserted without error.

If SQL finds an error while running the INSERT statement, it stops inserting data. If you specify COMMIT(*ALL), COMMIT(*CS), COMMIT(*CHG), or COMMIT(*RR), no rows are inserted. Rows already inserted by this statement, in the case of INSERT with a select-statement or blocked insert, are deleted. If you specify COMMIT(*NONE), any rows already inserted are not deleted.

A table created by SQL is created with the Reuse Deleted Records parameter of *YES. This allows the database manager to reuse any rows in the table that were marked as deleted. The CHGPF command can be used to change the attribute to *NO. This causes INSERT to always add rows to the end of the table.

The order in which rows are inserted does not guarantee the order in which they will be retrieved.

If the row is inserted without error, the SQLERRD(3) field of the SQLCA has a value of 1.

Note: For blocked INSERT or for INSERT with select-statement, more than one row can be inserted. The number of rows inserted is reflected in SQLERRD(3) in the SQLCA. It is also available from the ROW_COUNT diagnostics item in the GET DIAGNOSTICS statement.