SCREEN INPUT-OUTPUT MODULE

The Screen Module provides full screen editing for input and output of data on the video screen, including the use of the mouse and option buttons. It does not include the display of fixed data on the screen; this is provided by the Format Module. The Screen Module is used for the display of variable fields and the input of data fields by the program user. It also provides for the display of menus on the screen and the selection of menu items.

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.

  1. Display fields.
    These fields are used to display variable data on the screen from the associated data item. The program user may not enter data in these fields. They are displayed under program control, either for a complete group or for specific fields.

  2. Accept fields.
    These are the fields in which the program user may enter data into the associated data item from the screen. When data is entered, the cursor moves to the next - or the preceding - field, except under the following conditions:

  3. Text fields.
    These are also accept fields, but they provide for the input of a string of text into a field which extends over more than one line of the screen. Word wrapping is provided, and new lines may be commenced when required. In other respects they are the same as the accept fields described above.

  4. Buttons.
    These items are accessed only by the mouse to nominate an option. Buttons may also have an alphabetic letter assigned to them, by which they may be selected by pressing that key while holding the Alt key.
The fields within a group or menu are assigned a consecutive number in the order in which they are defined, commencing from 1 for the first in the group. All fields and items are included in this numbering system. These numbers are used to identify a field to and from the Screen module.

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.

  1. Navigation within a field
    These keys and mouse clicks cause processes which are performed internally, to move the cursor from column to column within a field, and to insert characters in the field.

  2. Navigation within a group
    These keys and mouse clicks move the cursor from field to field within a group of fields. These actions are performed internally except when the current field has been specified to return to the program when it is left: in these cases it returns to the program without moving the cursor.

    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.

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 [|ALPHABETIC-UPPER | BLANK WHEN ZERO|] 
                 [|RETURN | AUTO-TERMINATE|]      
                 [DISABLE].

dataname AT rrcc [|FOR | TO| rrcc] [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.

   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

SET SCREEN COMMENT TO |dataname | literal|

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.