Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## INSERT statement

> Creates a new database record, displays the initial values for the fields in the record, prompts for values of those fields, and assigns those values to the record.

> The INSERT statement is a combination of the following statements:

> - CREATE — Creates an empty record buffer.

> - DISPLAY — Moves the record from the record buffer into the screen buffer and displays the contents of the buffer on the screen.

> - PROMPT-FOR — Accepts input from the user, and puts that input into the screen buffer.

> - ASSIGN — Moves data from the screen buffer into the record buffer.

> Note: Does not apply to SpeedScript programming.

> #### Data movement

> 1. CREATE — Creates an empty record buffer.

> 2. DISPLAY — Moves the contents of the record buffer to the screen buffer and displays the screen buffer.

> 3. PROMPT-FOR — Accepts input from the user into the screen buffer.

> 4. ASSIGN — Moves the contents of the screen buffer to the record buffer.

> #### Syntax

>     INSERT record [ EXCEPT field ... ]
>       [ USING { ROWID ( nrow ) | RECID ( nrec ) } ]
>       [ frame-phrase ]
>       [ NO-ERROR ]

> ``record``

> The name of the record you want to add to a database file. Progress creates one record buffer for every file you use in a procedure. This buffer is used to hold a single record from the file associated with the buffer. Use the DEFINE BUFFER statement to create additional buffers, if necessary. The CREATE part of the INSERT statement creates an empty record buffer for the file in which you are inserting a record.

> To insert a record in a file defined for multiple databases, you must qualify the record’s filename with the database name. See the Record phrase reference entry for more information.

> `EXCEPT `field``

> Inserts all fields except those listed in the EXCEPT phrase.

> `USING { ROWID ( `nrow` ) | RECID ( `nrec` ) }`

> Allows you to insert a record in an RMS relative file (for backward compatibility only) using a specific record number, where `nrow` is the ROWID relative record number of the record you want to insert and `nrec` is the RECID relative record number of the record you want to insert.

> ``frame-phrase``

> Specifies the overall layout and processing properties of a frame. For more information on `frame-phrase`, see the Frame phrase reference entry.

> `NO-ERROR`

> Specifies that any errors that occur when you try to insert the record are suppressed. After the INSERT statement completes, you can check the ERROR-STATUS system handle for information on errors that have occurred.

> Example

> In this procedure the user adds a new order record. After the user adds a new order record, the procedure creates order-lines for that record. The procedure uses the CREATE statement to create order-lines rather than the INSERT statement. When you use the INSERT statement, the PROMPT-FOR and ASSIGN parts of the INSERT let you put data into all the fields of the record being inserted. In the case of order-lines, this procedure only lets you add information into a few of the order-line fields. Use CREATE together with UPDATE to single out the order-line fields.

> r-insrt.p
>     REPEAT:
>       INSERT order WITH 1 COLUMN.
>       REPEAT:
>         CREATE order-line.
>         order-line.order-num = order.order-num.
>         UPDATE line-num order-line.item-num qty price.
>         /* Verify the item-num by finding an item
>           with that number */
>         FIND item OF order-line.
>       END.
>     END.

> #### Notes

> - If an error occurs during the INSERT statement, Progress retries the data entry part of the statement and processes the error associated with the block that contains the statement. (For example, an error might occur when the user enters a duplicate index value for a unique index.)

> - Any frame characteristics described by an INSERT statement contribute to the frame definition. When Progress compiles a procedure, it uses a top-to-bottom pass of the procedure to design all the frames required by that procedure, including those referenced by INSERT statements, and adds field and related format attributes as it goes through the procedure.

> - If you receive input from a device other than the terminal, and the number of characters read by the INSERT statement for a particular field or variable exceeds the display format for that field or variable, Progress returns an error. However, if you set a logical field that has a format of y/n and the data file contains a value of yes or no, Progress converts that value to y or n.

> - If you use a single qualified identifier with the INSERT statement, the compiler first interprets the reference as `dbname.filename`. If the compiler cannot resolve the reference as `dbname.filename`, it tries to resolve it as `filename.fieldname`.

> When inserting fields, you must use filenames that are different from field names to avoid ambiguous references. See the Record phrase reference entry for more information.

> - The INSERT statement causes any related database CREATE triggers to execute. All CREATE triggers execute after the record is actually created. If a CREATE trigger fails (or executes a RETURN statement with the ERROR option), the record creation is undone. See OpenEdge Development: Progress 4GL Handbook for more information on database triggers.

> #### See also

> DEFINE BUFFER statement, Frame phrase

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095