Setting this property to a positive value affects the location of records added via RECORD-TO-ADD. When INSERTION-INDEX is set to zero (the default), records are added to the end of the grid. When it is positive, records are added immediately before the corresponding item instead. For example, setting this to 1 causes the record to be inserted as the first record of the list. When you finish adding the next record, INSERTION-INDEX automatically resets itself to a value of zero.
In statements that allow for multiple properties, the properties are set in the order specified. Therefore, you can set both INSERTION-INDEX and RECORD-TO-ADD in the same statement, providing you specify INSERTION-INDEX first. For example, the following statement will add a new record to the top of a grid:
MODIFY GRID-1, INSERTION-INDEX = 1, RECORD-TO-ADD = GRID-DATA-1
When you are inserting a record, the following properties are also affected: ROW-COLOR, ROW-FONT, CELL-COLOR, and CELL-FONT. If these are specified for a record past the insertion point, they will be moved down one record. For example, if you have ROW-COLOR specified for record 5, and you insert record 3, the ROW-COLOR will move to record 6. This causes row and cell properties to follow their data.