Screen fields are defined in the Screen Section of the Data Division, and are manipulated in the Procedure Division by ACCEPT SCREEN and DISPLAY SCREEN statements, in conjunction with SET statements.
There are three main types of defined fields.
USING THE MOUSE
The mouse may be used to select screen items by clicking the left or right
button. The item selected is the one the mouse is one when the pressed button
is actually released. If therefore, you press a button on an item then slide
the mouse to another location before releasing it, that item has not been
selected.
SCREEN CONCEPTS
GROUP
A group is a set of logically related screen fields and items. It may
represent a full screen or part of a screen. Under program control, the
program user may access the fields in a group sequentially, either forwards or
backwards. Control returns to the program only when a special control key is
pressed by the user, or the mouse is used to select a field or an option, or
the user moves from a field which has been defined to return control.
A group is defined with a group-name, which is used to reference the group
within the program.
MENU
A menu is a set of logically related menu items to be displayed on the screen.
The user may use the arrow keys or the mouse to select a menu item which is
then returned to the program.
A menu is defined with a menu-name, which is used to reference the menu within
the program.
FIELD
A screen field is defined within a group or menu in the SCREEN SECTION.
Except for button items (see below), a screen field is associated with a data item already defined in the Data Division. More than one screen field may be associated with any one data item. There are four type of screen fields.
CONTROL FIELDS
These fields are defined by the system and are used to communicate between the
Screen Module and the user program. They are altered only by the user program,
and by the module when reading data. They may be used in the program in any
statement for which the corresponding data type is valid. The implicit
definitions are:
SCREEN-POINTER PIC 9999 COMP.
SCREEN-COLUMN PIC 9999 COMP.
SCREEN-FIELD PIC 9999 COMP.
SCREEN-STATUS PIC X.
Two of these fields are used on entry to the Screen Module.
SCREEN-POINTER
The first or only field to be processed by the statement, or the menu item to
be highlighted on entry. If there is no field with that number, it normally
defaults to field one. If the field contains zero, no field is highlighted
and the module waits until a control key is pressed or the mouse is clicked on
a field.
SCREEN-COLUMN
Used only with the ACCEPT SCREEN statement, the column within SCREEN-POINTER
in which the cursor is to be placed.
Only the ACCEPT SCREEN statement affects the contents of these fields. Their contents on exit from the Screen Module are described later.
CONTROL KEYS
The keyboard keys, together with the mouse, fall into three groups, which are described below. Any other keys not specified below are ignored by the system.
If the field has been specified to return to the program when it is left, the cursor is not moved, and the standard fields are set up as follows so that a subsequent ACCEPT SCREEN would continue as above.
   Mouse clicks:
The standard fields will be set as follows.
MENUS
On exit from a menu, SCREEN-STATUS has the following values.
SCREEN-FIELD identifies the current item when Enter or Esc was pressed, or the item that the mouse was clicked on. SCREEN-POINTER is the same as SCREEN-FIELD, and SCREEN-COLUMN is always 1.
 
Data Division Statements
SCREEN SECTION.
|group-name GROUP.|
|menu-name MENU. |
Display Fields Format
dataname AT rrcc DISPLAY [BLANK WHEN ZERO] [DISABLE].
dataname AT rrcc |FOR rrcc| DISPLAY [DISABLE].
|TO rrcc|
Accept Fields Format
dataname AT rrcc [|FOR | TO| rrcc]
[DISABLE].
dataname AT rrcc [|ALPHABETIC-UPPER | BLANK WHEN ZERO|]
[|RETURN | AUTO-TERMINATE|]
[DISABLE].
Button Item Format
BUTTON AT rrcc |FOR | TO| rrcc ["x"]
[DISABLE].
Note.
Group-name and Field-name all commence in column two. All other words
commence in not less than column six.
GROUP
This statement commences a new group of screen fields. It must precede the
first field definition of each group. Group-name is a user-defined reference
for the group. The sequence of the groups in the Screen Section has no effect.
MENU
This statement commences a new menu of screen fields. Menus are similar to
groups and may be mixed with groups in any sequence.
Dataname
The data item associated with this field, which contains the data to be
displayed, and into which data will be stored. The data USAGE may be any valid
type, including DATE. If it is subject to an OCCURS clause, it must be
subscripted, and only by a literal value.
AT rrcc
The four digit number specifying the starting screen row and column, in the
same format as in the Format Module.
FOR rrcc
The four digit number specifying the number of rows and columns for this text
field or button item. If this definition begins with a dataname, it is a text
field. Note that the length of the lines (columns) multiplied by the number of
lines (Two rows each) should not be greater than the defined length of
'dataname'. If the 'dataname' length is greater than this, it is not treated
as an error; the remaining space in 'dataname' is ignored by any screen
action.
TO rrcc
An alternative to "FOR rrcc", not generally used. The four digit number
specifying the last screen row and column for this text field or BUTTON item.
Refer to the Format Module for a description of screen lines, rows and columns, as specified by the rrcc construct. In this Module, ll is always the first row of a specified line.
DISPLAY
A display field, not an accept field. These fields are ignored when the cursor
is moving automatically from field to field.
DISABLE
This field or button will be ignored by all Screen Module operations, but it
will still be included in the field numbering. Fields may be enabled and
disabled as required during the program.
ALPHABETIC-UPPER
This accept field is to contain only upper case characters. Input data will
automatically be converted to upper case regardless of the use of the shift
key.
BLANK WHEN ZERO
This numeric accept field will be displayed as blank if the value is zero.
AUTO-TERMINATE
This accept field will automatically terminate without a control key whenever
the cursor passes the last character of the field. Text fields cannot be
auto-terminated.
RETURN
This keyword is used to specify an accept field which is to cause a return to
the program whenever this field is left, regardless of the control key which
the user presses.
BUTTON
This is an item which may be clicked by the mouse or selected by its Alt key
if one is defined.
"x"
This defines a letter key by which this button may optionally be selected by
pressing this letter while holding the Alt key.
Procedure Division Statements
SET MOUSE |LEFT | RIGHT|
This statement allows you to switch the significance of the mouse buttons,
mainly for left-handed users. The normal state is LEFT, nominating the left
button as the main button. This may be altered during the program.
SET |DISPLAY|
|ACCEPT |
|CURRENT|
|COMMENT| ATTRIBUTE TO |dataname | literal|
This statement allows you to change the attributes of the screen fields during
the course of the program. The required attribute is in the same form as in
the Format Module. The meaning of each attribute, together with its default
attribute, is as follows.
SET SCREEN COMMENT TO |dataname | literal|
DISPLAY All display fields GW Gray on White
ACCEPT Accept fields, not current NW Black on White
CURRENT The current read field WN White on Black
COMMENT Comment WR White on Red
The SCREEN COMMENT is the comment field at the bottom of a window. This statement assigns a comment to be displayed in this field with a maximum length of 32 characters. Dataname or literal must be a display field. If it is longer than 32 characters, only the first 32 characters will be displayed.
The display takes place only on the next ACCEPT SCREEN statement, described
below. When the first field is displayed, this comment will also be displayed,
and remains there until the user takes some action to move the cursor from
this field, when it is cleared from the screen and the setting is cancelled.
It is not affected by any other screen statement before the next ACCEPT SCREEN
statement.
ACCEPT SCREEN [FIELD]
This statement is used to accept data from the screen. All display and disabled fields are ignored. The first field highlighted is the field identified by SCREEN-POINTER.
If SCREEN-POINTER contains zero, no field is highlighted and the module waits until a control key is pressed or the mouse is clicked on a field. The cursor is placed in SCREEN-COLUMN.
FIELD This option specifies that only the field identified by SCREEN-POINTER will accept data. Control then returns to the program regardless of which key the user presses to complete the field.
If SCREEN-POINTER is currently pointing to an item within a MENU, the SCREEN-
POINTER item is highlighted and the user may navigate to the required item and
press Enter, or click on the required item, or select a button by clicking on
it or pressing its Alt key.
DISPLAY SCREEN [|ENABLE | DISABLE | ERASE|] [FIELD]
This statement is used to display data on the screen, to clear fields, and to enable or disable fields. This statement is used with menus only to enable or disable fields.
FIELD This option will process only the one field identified by SCREEN-POINTER, even if it is disabled. Thus, it is possible to display a specific disabled field. Otherwise, all fields starting from the one identified by SCREEN-POINTER will be processed.
ENABLE This cancels the disabled status, either of a specific field, or of all fields through to the end of the group, commencing from the field currently identified by SCREEN-POINTER. If the field or fields are currently enabled, this has no effect.
DISABLE This sets the disabled status, either of a specific field, or of all fields through to the end of the group, commencing from the field currently identified by SCREEN-POINTER. If the field or fields are currently disabled, this has no effect.
ERASE
This clears the contents of accept and display fields, commencing from the
field currently identified by SCREEN-POINTER through to the end of the group.
Buttons, and fields which are disabled, are NOT affected by this statement.
Numeric fields are cleared to zero, and all others to spaces. As each field is
cleared it is redisplayed on the screen.
SET SCREEN TO |group-name | menu-name|
This statement is use to assign a specific group or menu to be processed by the Screen module. It also sets SCREEN-POINTER to 1 automatically. At the start of the program, SCREEN is automatically set to the first group or menu defined in the Screen Section, and SCREEN-POINTER is set to 1.
Demonstration Program The program SCRDEMO.RUN provides a demonstration of the Screen Module and the values returned to the program when various keys are pressed, or the mouse is clicked on fields or buttons. There is the provision also to change the control fields and return to the Screen Module. The source program is also available in SCRDEMO.COB.