The Form Design Tool is part of the Screen Management Facility (SMF) in ACCENT R. It allows the design of forms for data entry and display.
Follow these steps to design, display, and process a form in an application.
1. Define the form and its data fields with a LAYOUT SCREEN definition.The LAYOUT SCREEN definition is a group of statements that are specified in a Process Module (PM) Declare Section, Global Storage (GS), or a Code Segment (CS). The statements in a LAYOUT SCREEN definition define:
- the size and the rendition of the form
- the position, width, and rendition of each data field
- for each field, a PM trigger to execute after data is entered
- for each field, a help box or a help trigger
- messages in the form
- horizontal and vertical lines
- boxes
2. Create the form with a GENERATE statement/command.
The GENERATE statement in a PM or the GENERATE command checks the syntax of LAYOUT SCREEN statements and creates the form. If the syntax is correct, the Screen Management Facility (SMF) compiles the form and stores it in an internal table.
When the form is created, GENERATE returns a form ID that is used in subsequent commands/statements and functions to identify the form. The form ID is a unique non-zero value that lasts throughout the entire ACCENT R session if it is stored in a global variable (such as in a GS).
If the form ID is stored in a global variable, the form can be used by different PM’s or Command Modules (CM) within the same ACCENT R session. To restart a form, issue a FILL statement/command with the proper form ID without going through another GENERATE. This allows the form operation to be repeatedly invoked without regenerating the form.
3. Start the form operation with a FILL/command.
Once the form has been successfully created, execute the FILL statement/command to perform the form operation. This displays the form on the screen so that the user can display, enter, or change data in a predefined order or selectively (using arrow keys). If there are other forms, menus, or windows already displayed on the screen, the new form may overlay them.
The data fields in the form can be system fields, GS fields, or user-defined fields. In a PM, a data field can be from the Declare Section, related Data Sets (DS), or a ready area. A field can be defined to be modifiable or read-only.
In a PM, a trigger (routine) can be associated to each data field with a PERFORM substatement in the LAYOUT SCREEN definition. Such a trigger can validate the input value, perform a security check, or perform calculations based on the input value so that the result is reflected in other data fields. The optional clauses in the PERFORM statement can specify exactly when to execute the trigger.
With the /ALWAYS/ BEFORE clause, the trigger is executed as soon as the cursor moves to the field.
With the /ALWAYS/ AFTER clause, the trigger is executed if the user does one of the following:
enters data in the field;
moves the cursor to another field;
presses one of the keys in the system field @END_CODE or @CANCEL_CODE.
PERFORM ALWAYS AFTER executes the trigger unconditionally, even if the user just presses one of the cursor arrow keys.
If neither clause is used, the trigger is executed if the user enters data into the field and:
the number of digits or character entered from the keyboard equals the width of the data entry area;
presses one of the arrow keys (if data was not entered, the trigger is not executed);
presses one of the keys in the system field @TERM_LIST;
presses the key contained in the system field @END_CODE or @CANCEL_CODE.
After the execution of a field's trigger, the cursor normally goes to the next modifiable field. However, the form operation can be controlled by assigning a new value to the system field @FILL_ACTION within the trigger.
"INVALID" - After the trigger completes execution, the form re-prompts for the data. The terminal bell will ring and all data entry areas will retain their previous values. If a data entry error is detected in the trigger, @FILL_ACTION can be set to "INVALID" and an error message can be displayed that asks the user to reenter the data.
"END" - Terminates the form operation in this trigger.
"REDISPLAY" - causes SMF to update all values in the form. "REDISPLAY" enables new values to be displayed for form fields that were changed in the trigger.
- "REDO" - causes SMF to position the cursor at this field again and wait for operator input. All fields retain their previous values. This is useful when there are additional steps needed after the user has entered data for a field correctly.
In a PM, a trigger that is performed or a window that is displayed can be assigned when the user positions the cursor on a modifiable data field and presses the key defined in the system field @HELP_CODE. The default value for @HELP_CODE is a question mark '?'.
End the form operation.
The user terminates the form operation at any time by entering one of the characters stored in the system field @CANCEL_CODE or @END_CODE. After the user presses one of these characters, the final trigger is performed (if defined) and the form operation ends. The form is removed from the screen and the statement following the FILL is then executed.
The value returned by the system field @FILL_ACTION indicates which key that the user pressed to end the form operation:
@CANCEL_CODE "CANCEL" (Control-G)
@END_CODE "OK" (Control-Z)The value in the system field @FILL_ACTION can be referenced in the final trigger or in the statement or command following the FILL statement/command.
A final trigger can be designated in the LAYOUT SCREEN definition that is performed when the key defined in the system field @CANCEL_CODE or @END_CODE is pressed. After the trigger executes, the form operation terminates.
In the final trigger, a new value can be assigned to the system field @FILL_ACTION so that the form operation will resume when the trigger completes execution.
"INVALID" preserves the data that the user has entered or displayed on the form and moves the cursor to the first modifiable data field. This allows the user to make changes to the data.
- "RESTART" Blanks the data entry areas on the screen and the cursor moves to the next modifiable field.
Use the Window Control Tools with the Form.
The form using the Window Control Tools can be dynamically modified. Here are some examples of what can be done. See the Window Control Tools section for more.
Preview a Form - Use the SCREEN PASTE_WINDOW statement/command to display a form without starting a form operation.
Keep a Form Pasted - Use SCREEN PASTE_WINDOW to put the form on the screen before executing the FILL statement/command so that the form is not removed from the screen after normal termination.
When a form has been pasted in this way, the only way to remove it from the screen is to execute SCREEN UNPASTE_WINDOW.
If the form is displayed by SCREEN PASTE_WINDOW, the subsequent execution of FILL will not redisplay the form even if the form's display position is different from its pasted position.
- Remove a Form - There are several ways to remove a form before it terminates normally. (Keep in mind that a form can have other windows associated with it, such as help boxes). SCREEN DELETE_WINDOW removes a form, but does not remove its associated windows. FLUSH removes a form and all its associated windows. SCREEN KILL_SCREEN removes all generated forms. After execution, all stored form ID’s are no longer valid.
A form can have fields that function like menu items. For more information see the explanation for the CHOICE display type (FIELD statement option).