insertrow Statement--Insert Rows into the Table Field
The insertrow statement inserts a row at the beginning or middle of the data set.
This statement has the following syntax:
insertrow formname tablename [row]
[(columnname = data {, columnname = data})];
Most of the syntax elements are described in
loadtable Statement--Load a Data Set. The
row element, specifies where the new row is to be inserted.
Row must be an integer value corresponding to the number of the
displayed row in the table field after which the new row is to be inserted.
Row must be in the range from 0 to the number of displayed rows as specified in Visual Forms Editor. If
row is 0, the new row is inserted as the top row in the display. If
row is omitted, the row is inserted after the row on which the cursor is currently positioned. In contrast to the constant _record,
row refers to the row's position in the display, not to its position in the data set; rows added to the data set by insertrow always appear in the table field display.
Row cannot be greater than the number of rows actually containing data in the table field. For example, if the display has the capacity to hold four rows, but currently contains only two having data, then row must be in the range of 0 to 2, because the third and fourth rows do not yet exist.
When a new row is inserted, all rows below it are scrolled down. In a table field with four displayed rows, inserting a new row after row 2 causes row 3 to become the last displayed row and row 4 to be scrolled out of the display. When you insert a row after the last displayed row (in this case, by specifying row as 4), the rows in the display are scrolled up one, causing the first row to leave the display, and the new row appears as the last row in the display.
By default, rows inserted into a table field using insertrow have a state of UNCHANGED. (See
Table Field Row States for more information about states.) You can, however, override this default when you load the table. This is done by specifying the
columnname as the constant _state and assigning it a value corresponding to an alternate row state, such as UNDEFINED or NEW. See
Setting Row States for more information.
The column list in insertrow is optional. If the column list is not included, the newly inserted row takes on the default value of zero or blank. By this means, your program can provide the user with the ability to add rows to the middle of the data set.
The following example demonstrates the insertrow statement. Assume that FRS key 5 has been mapped to Ctrl F. (FRS key mapping is described elsewhere in this guide.) Then, if you provide your program with the following activate section, a user can insert a row into the middle of a table field by pressing Ctrl F.
...
exec frs activate frskey5;
exec frs begin;
/*
** Insert a new row after the current row, leaving it
** clear for the user to fill.
*/
exec frs insertrow empform employee;
exec frs end;
...