PHASES

Discussion

During the configuration phase, local edits are loaded to terminals that support the local edit feature (see Appendix G), and the output device and error lights to be lit are identified for data capture devices. During the initialization phase, all fields in the form are initialized; during the field edit phase, all fields (in screen order left to right, top to bottom) are validated and edited. An application usually requests execution of the finish phase only when all fields have passed the edit tests of the field phase. Finish statements apply to the entire form. (Refer to Figure 4-1 “Field Menu with Processing Specifications”for an illustration of the flow of form execution under ENTRY control.)

You can specify that a statement be executed during a particular phase with the phase specification statements. It is important to note that while specifications are entered field by field, execution of the phases applies to the entire form. If you omit these phase headings altogether, all statements are executed in the field edit phase.

Example

CONFIG 
LOCALEDITS alphabetic 
LIGHTB 
DEVICE printer 
INIT 
SET TO 20.00 
FIELD 
IN 20:200 
IF IN 100:200 THEN JUSTIFY RIGHT 
FINISH 
SET TO SAVE_FIELD_1

If you want statements to be executed in a particular phase, you must precede the statements by the appropriate phase headings. Phase headings must be specified in the order shown above.

Configuration Phase

If you use the configuration phase, the CONFIG statement must be the first statement in the processing specification area on the field menu. The CONFIG statement is processed only for the field in which it appears. The commands that can be used in the configuration phase are: DEVICE, LIGHT and LOCALEDITS. (Refer to the "Processing Specifications for Configuration" earlier in this section.)

Initialization Phase

The initialization phase occurs when VINITFORM is called. The processing that precedes the display of the form is usually performed in this phase.

For each field in the form, the field is first initialized to any value specified in the Initial Values box of the Field Menu. (By default, all fields are set to $EMPTY, all blanks). If any initialization statements are included in the field processing specifications, these are executed next. This process continues until all fields in the form are initialized.

If the form being initialized is a child or sibling to the previous form, data from the previous form is transferred to this form (with conversion if necessary) before initializations occur. Refer to "Form Families" in Section 3 for more information.

A SET TO source statement may be used to initialize field values.

Figure 4-4 Flow a Phase Execution for ENTRY

Field Edit Phase

The field edit phase occurs when VFIELDEDITS is called. The field edit phase is usually requested by the application after the form is displayed on the screen, and the user has input data. During this phase, the entered data is checked according to the field attributes and any processing specifications entered by the designer. The Edit statements can be executed only in the field edit phase.

Each field in turn is examined. The first action is to check the field type. If it is optional and the field is blank, the rest of the field edit phase for this field is skipped. If the field is required, it must contain a nonblank value. If it has a value, the data is checked to see if it conforms to the field's data type. If it does, then any field processing statements are executed in the order they were entered.

Edit failures detected in this phase cause the field to be flagged in error so the user can be informed. All further processing on this field is stopped when an error is detected, and control passes to the next field.

ENTRY loops through all processing statements in the field edit phase until all errors have been corrected by the user.

Finish Phase

The finish phase occurs when VFINISHFORM is called. The finish phase usually is requested by the application after all data has been entered and validated for the entire form. The ENTRY program executes statements in this phase only when no errors are detected after ENTER is pressed. Finish statements direct irreversible processing during which the global environment can be altered.

Under ENTRY control, any processing performed by the preceding two phases can be undone prior to the FINISH phase. For instance, if the user presses REFRESH, the initial values replace any that were entered. In the finish phase, such changes can no longer be made.

Under ENTRY control, the batch file is written as soon as the finish phase is complete. The assumption is that all fields have been tested and corrected; fields with errors are not enhanced in the finish phase.