20. Writing 4GL Statements : Forms-Control Statements : Manipulating Table Fields and Arrays
 
Share this page                  
Manipulating Table Fields and Arrays
4GL provides the following statements for manipulating rows and columns in table fields:
validrow
insertrow
clearrow
deleterow
loadtable
The first four of these statements operate on individual rows of the table field's visible display. The loadtable statement operates on the table field's dataset; this can affect the visual display.
To manipulate all rows in a table field's data set, use the unloadtable statement. This statement sets up a loop that processes all the rows sequentially. You cannot indicate specific rows in an unloadtable loop.
The insertrow, clearrow, and deleterow statements also operate on the records in arrays. In addition, there are a number of built-in 4GL procedures that you can use to operate on arrays. See Built-In Frames and Procedures for a brief description of these procedures.
Records and Rows in Table Fields
A table field consists of two parts:
An underlying data set that contains all records retrieved from the database
A display window that contains rows visible to the user; this generally is a portion of the dataset
Except for the loadtable and unloadtable statements, all the statements that you use with table fields operate only on rows in the visible display window. For example, the insertrow statement inserts a row after the row number that you specify. If this row currently is not visible, you can use the scroll statement to move it into the display window.
The position of a record in the data set (as determined by the _record constant) can be different from its position in the visible display. When you use a table field statement such as insertrow, you always specify the row number in the display window.
The following figure illustrates the relationship between a table field's data set and display window. Deleted rows are handled as follows:
Deleted rows whose state previously was "Changed" or "Unchanged" are moved to the end of the data set (that is, the unloadtable statement processes them after all other records). The rows are given non-positive record numbers.
Deleted rows whose state previously was "Undefined" or "New" are removed from the dataset altogether.
You cannot Mode scroll to a deleted row.
Validating a Row
Use the validrow statement to perform a validation check on columns in a particular row of the table field. Ingres validates the indicated columns in the row on which the cursor is currently resting, unless you specify a row number, as in the statement below:
validrow partstbl[3] (partno, cost);
To validate all the table field's displayed rows at one time, use validate field tablefieldname. The validate and validrow statements perform validation checks on columns as you have defined them with the ABF FormEdit operation. If any field fails a check, ABF displays an error message and places the cursor in the field that failed, to permit reentry of data. The validrow statement does not work with arrays, as arrays do not have validations.
Inserting a Row or Record
The insertrow statement opens up a new row in a table field or a new record in an array following the row or record you specify by number.
When adding rows to a table field, you are dealing only with visible rows in the window. If you do not specify a numbered row, the statement inserts a row just after the row on which the cursor rests. If you enter 0, the statement inserts a new top row in the display. The following statement opens up a new row immediately following row 4 in the table field partstbl.
insertrow partstbl[4]
This is the fourth visible row in the window; the number has no relationship to the position the row might have in the underlying data set of the table field. Assuming that the table field's mode is fill, update, or query, the user can enter or change values in the new row.
When adding records to an array, the insertrow statement inserts a new record after the record designated by the number within the square brackets. You must include such a number when adding a record to an array. This number refers only to the location of the record in the array, and has no relationship to the number the record might have if displayed in the window in a table field.
If you enter 0, insertrow inserts a record at the beginning of the array. (Remember that the first record in an array is numbered 1.) The default _state attribute of the new record is "Unchanged." You can specify a different value for _state in the insertrow statement.
To add new records to an array, either use the insertrow statement or reference the record that is one position beyond the last record in the dataset.
You also can use the arrayinsertrow() built-in function to add records to an array. In this case, the record is added at the index number that you specify, and all the following records are renumbered. See the section ArrayInsertRow() for more information on using this function.
For example, to load an array with constant values, specify several insertrow statements in their 4GL code:
insertrow array[0] 
  (coll = 1.0, col2 = 'Record1');
insertrow array[1] 
  (coll = 2.0, col2 = 'Record2');
insertrow array[2] 
  (coll = 3.0, col2 = 'Record3');
You also can insert new records by direct reference:
array[1].coll = 1.0; 
array[1].col2 = 'Record1'; 
array[2].col2 = 2.0; 
array[2].col2 = 'Record2';
array[3].col3 = 3.0; 
array[3].col2 = 'Record3';
For more information, see insertrow Statement--Insert Rows into the Table Field.
You can use the loadtable statement to append a row after the last row of a table field's dataset, eliminating concern about which rows of the table field currently are displayed.
The loadtable statement has the following syntax:
loadtable tablefieldname (columnname = expression
    {,columnname = expression} )
You cannot use the loadtable statement with arrays.
Clearing or Deleting a Row or Record
To clear a row or specific columns within a row of a table field, use the clearrow statement. The FRS clears the row, leaving a blank row. The cursor remains on this row unless you specify a different (displayed) row number. If you specify column names as well, the FRS clears only those columns.
The following example clears the cost and total columns of the row on which the cursor is resting in the currently displayed table field partstbl:
clearrow partstbl (cost, total);
The deleterow statement deletes a record from a table field or array and closes up the table or array after the deletion. When you use the deleterow statement on a record of an array, the record's _state value is set to "Deleted" and its record number becomes non-positive. Records to be deleted are assigned record numbers beginning with "0," then "-1," and so on.
For example, assume you have an array called "Emparray" that contains two deleted records and four non-deleted records. The following statement:
deleterow emparray[3]
deletes the third non-deleted record. This record has its _state value set to "4" and its _record value set to "-2." You now can refer to this record explicitly as "emparray[-2]."
When you use the deleterow statement on a row of a table field, one of the following situations occurs:
If the row's _state value was "0" (Undefined) or "-1" (New), then the row is removed from both the table field display window and the table field's dataset.
If the row's _state value was "2" (Unchanged) or "3" (Changed), then the row is removed from the table field's display window, but it remains in the table field's data set.
However, its _state value is set to "4" (Deleted), and its _record value is set to "-3." The deleted record is accessible only through an unloadtable loop.
For example, assume the table field "partstbl" currently displays the fifth record of the underlying dataset in the third row of the display window. The current state of this record is "2" (Unchanged). Then the statement:
deleterow partstbl[3]
deletes from the display window the fifth record of the dataset. The record remains in the dataset, but its _record value is changed from "5" to "-3," and its _state value is changed from "2" (Unchanged) to "4" (Deleted).