display Statement--Initiate Form Display
This statement initiates the display of a form.
Syntax
display formname [mode]
[with style=fullscreen[(screenwidth = value)]
| popup [(option=value {, option=value})]]
Description
The display statement marks the beginning of the form's display block in the program and, when executed, initiates the form's display loop. (For a description of display blocks and loops, see
Part 4: Embedded Forms Programming.)
The form, identified by formname, appears on the screen in the specified mode. Four modes are available:
fill
Displays data on the screen and allows the data to be modified by the user. Data displayed when the form first appears comes from one of two sources:
• The default values specified in the form's VIFRED definition
• Values placed in fields by the initialize statement
The fill mode clears all fields on the form except those containing VIFRED-defined default values before any initialization code is executed. This is the default mode.
update
Like fill mode, displays data that the user can modify.
The update mode does not clear the form's fields before executing the initialization code. Consequently, when you display a form in update mode, the fields retain any values entered into them by data transfer statements (such as a putform) or present when a previous display terminated. Even clearing a field on the screen does not clear the data that is redisplayed when the form is called again.
read
Lets the user examine but not change the data on the form
query
Presents a form with cleared fields so that users can enter data to construct a query on the database. This mode allows users to enter comparison operators (for example, "<>" or ">" in addition to normal data. (The creator of the form must supply the extra space in a field for the operators.)
If you display a form in fill, update, or read mode, any derived fields on the form are calculated and displayed, if possible. (For more information about derived fields, see
Table Fields.) In query mode, derived fields are displayed with blanks.
If no mode is specified in the display statement, the mode defaults to fill.
You can express both formname and mode as character strings, with or without quotes, or as program string variables.
Including the style clause allows you to override the form's default style definition as specified in VIFRED. The form displays in either fullscreen or pop-up, as specified, regardless of the style specified with VIFRED.
If you choose the fullscreen style, the form is displayed over the entire screen. However, the optional screenwidth argument lets you choose the effective width of your terminal screen. Your fullscreen form can appear on a narrow or wide screen. The actual width of each choice differs depending on your terminal.
The value assigned to screenwidth can be an integer or string literal or an integer variable. It must be one of the following values:
default | 0
Specifies that the FRS uses the screenwidth option that was defined in VIFRED
current | 1
Specifies that the screenwidth remains as it is
narrow | 2
Specifies the smaller of two possible widths
wide | 3
Specifies the wider of two possible widths
A pop-up form covers only part of the screen. It is most useful when you want to display a form on top of another form. Also, because they do not cover the entire screen, you can display more than one pop-up at a time. The only limit on the number of pop-up forms that can be active at one time is the amount of available memory.
The option arguments specify the screen location and border style of a pop-up form. The options are:
Startcolumn
Specifies the column position of the upper left hand corner of the pop-up form
Startrow
Specifies the row position of the upper left hand corner of the pop-up form
Border
Determines the type of border around the form
The value assigned to the startcolumn or startrow option can be an integer literal, an integer variable, or either of the keywords, default or floating. Values assigned as integer literals or by means of variables can be any of the following:
>0
Specifies that values greater than 0 are interpreted as terminal screen coordinates. (The terminal screen origin, in the upper left hand corner, is defined as 1,1. Values increase to the right and down the screen.)
0
Specifies that a value of 0 is equivalent to the keyword default. The FRS checks to see if the option has a value defined in VIFRED. If it does, then the FRS uses that value. If not, FRS selects a value near the current field in the parent form.
-1
Specifies that the value -1 is equivalent to the keyword floating. The FRS chooses a value close to the current field in the parent form.
If the values you select for the options do not allow the entire form to be displayed on the screen, the FRS tries to adjust the starting location to do so. If the form is larger than the screen, the form is displayed in fullscreen style.
You can assign the border option an integer literal value, an integer variable, or one of the keywords, default, none, or single. Default uses the form's default border definition. If the form does not have a default border definition, the default is a simple, single-line border. None eliminates the pop-up's border. Single forces the use of a single-line border, regardless of the default border definition.
The integer literal or variable can be one of three values, each equivalent to one of the keywords:
0
Is equivalent to the keyword default
1
Is equivalent to the keyword none
2
Is equivalent to the keyword single
If you do not specify the options when you display a form with style = popup, the FRS uses the pop-up defaults rather than any corresponding defaults specified for the form when it was created. The pop-up defaults are a starting location as close as possible to the current field (defined as the field on which the cursor currently rests) and a single-line border.
If the style clause is not specified, the form's default style (specified with VIFRED) is used to determine the display style.
Examples--display statement:
Example 1:
Display empform in update mode, with only an initialize and finalize statement.
exec frs display empform update;
exec frs initialize (ename = :ename, age = :age);
exec frs finalize (:ename = ename, :age = age);
Example 2:
Display empform in the default fill mode, with two activate sections and no initialize or finalize statements.
exec frs display empform;
exec frs activate menuitem 'Fill';
exec frs begin;
program code;
exec frs end;
exec frs activate menuitem 'End';
exec frs begin;
exec frs breakdisplay;
exec frs end;
program code;
Example 3:
Display empform in a pop-up window, using the default border and placing the upper left hand corner of the form in the fifth column and fifth row.
exec frs display empform with style=popup
(startcolumn=5, startrow=5, border=default);
Example 4:
Display empform, setting the terminal screen to narrow width.
exec frs display empform with
style=fullscreen(screenwidth=narrow);