The unloadtable statement provides a means by which the program can access values in each row of the data set in turn and perform actions based on those values.

This statement has the following syntax:

When tablename is unloaded, the FRS first validates the values displayed in tablename. Then, the program starts with the first row in the data set and places the values in the specified columnnames into the variables. The host language and embedded query language statements in the statement block are then performed using those values. Next, the program unloads the second row in the data set and executes the statements on those values, and so on, through all the rows in the data set. The unloadtable statement causes a program loop to execute once for each row in the data set. It does not change any of the values in the data set; it merely provides a means for scanning the values. (In the unloadtable loop, avoid including any statements that change the ordering of the rows in the data set. Such statements can have unforeseen consequences.)

The unloadtable statement can appear wherever it makes sense to scan all the rows in the data set. A common location for it is at the end of a form's display, so that the values in the data set can be processed at that time. Be aware that an unloadtable loop does not clear the data set of its values. Data remains in the data set even after the end of a form's display. To clear the data set of values, you must use the clear field statement, with the name of the table field as the argument (see Forms Statements for details).

You can terminate an unloadtable loop prematurely with the endloop statement. This statement breaks to the statement immediately following the unloadtable's program block. You can also terminate the unloadtable loop with a resume statement, back to the enclosing display loop.

During an unloadtable loop, the program can determine the record number and the state of the row being unloaded by using the special constants _record and _state as columnnames in the column list. These constants return integer values.

The _record constant returns the record number of the row currently being unloaded, with 1 signifying the first row in the data set. If the row has been deleted (see deleterow Statement—Delete Rows from the Table Field), _record returns a negative number. The _state constant returns an integer that corresponds to the row's state. The state indicates the most recent event a row's displayed columns have undergone.

Table Field Row States discusses the _state constant and its interaction with the various table field statements, and explains how to change table field row states dynamically.

Although a deleted row is no longer accessible through the table field display, with two exceptions, it still exists in the data set and can be accessed by an unloadtable statement. The exceptions are rows whose states were UNDEFINED or NEW before deletion. These rows disappear forever when they are deleted.

The next example shows a simple use of the _record and _state constants within an unloadtable loop and illustrates how a program can update the database by means of the changes made to the data set by the user.