Screen Design Utility

The screen management utility is used to interactively create and maintain user interfaces for use in a program. The utility creates a database that contains the design information. Screens are designed as one or more pages or screens each containing fields that are used to display text and to prompt for and accept user input. VT100A, VT200 and VT300 video attributes of bold, reverse video, underscoring and blink can be specified for any field. Screens are combined with the program source by a precompiler that generates optimized source code which is then compiled. This approach allows the designer the flexibility of an interactive design utility and efficient run time performance. The screen management utility can be used with programs written in Basic, Fortran and Cobol.

To activate the utility enter at the DCL prompt

$ DSI SCREEN

or define a symbol such as

$ SCREEN == "$DSILIB:SCREEN".

The following page is displayed :

                               Screen Maintenance                     V3.5

       File Name   ____________________________________________________________
       Page Name
       Field Name

       Prompt

       Vert Pos    0                             Bold

       Hor Pos     0                             Underscore

       Length      0                             Reverse

       Vert Offset 0                             Blink

       Hor Offset  0

       Mask


Default :

                                    F10=Exit

Each field in the screen you are designing is identified by a page name and a field name. A single screen file can contain many pages each with many fields. Generally there will be one screen file for each program although several programs could reference the same screen file.

FILE NAME:

Enter the name of the screen file that you wish to create or edit. Wild card characters may be entered to display all matching file names. The required file extension is .SCR. If the file does not already exist, you will be prompted to confirm that you want to create a new screen file. The input file name will default to the last screen file accessed if the screen utility has previously been run.

PAGE NAME :

The page name may be any printable sequence of characters up to 20 characters long. Embedded spaces and tabs will be edited out. The SELECT key will produce a list of all pages that are in the current file. The EXIT key will exit the program.

FIELD NAME :

The field name may be any printable sequence of characters up to 20 characters long. Embedded spaces and tabs will be edited out.

If the page/field does not exist the prompt "Add " will appear at the bottom of the screen. A RETURN will place the cursor at the prompt entry and a new field may be added. An N or any escape sequence will return the cursor to the field entry.

If the page/field already exists then the current value will be displayed and the cursor will move to the Change/Delete entry. A C or a RETURN will move the cursor to the prompt entry where any field may be updated. A D will prompt you with a 'Sure DELETE field '. If a Y is now entered the currently displayed field will be deleted. Any escape sequence or RETURN will return the cursor to the Field Name entry.

PROMPT :

The prompt is the text displayed on the screen for this entry field.

VERT POS :

The vertical position is the row on the screen. Allowable values are from 1 to 24.

HOR POS :

The horizontal position is the column on the screen. Allowable values are -1 and from 1 to 80. A value of -1 will automatically center the prompt on the line.

LENGTH :

The length is the number of the underscores displayed to show the extent of the entry field. A length of 0 is used for titles or text where no actual data will be entered. If the length is greater than 40 characters then the MASK field is automatically blanked.

VERT OFFSET :

The vertical offset allows the data entry position to be above or below the line that the prompt is on. This can be combined with a negative horizontal offset to produce a horizontal line of data entry fields with the prompts above.

HOR OFFSET :

The Horizontal offset is an additional distance between the end of a prompt and the start of the entry field. This is to allow the vertical alignment of the fields and is usually determined after all fields on a page are entered. There is automatically one space between the last character of the prompt and the first position of the entry field. This can be removed by an offset of -1.

MASK :

If the field length is greater than 40 this field is skipped. Edit masks must conform to the mask rules for DSI_MASK (see the Callable Module Guide).

BOLD, REVERSE, UNDERSCORE and BLINK :

These four fields control the video attributes displayed on the prompt. The entry portion of the field is always displayed in bold. These attributes are transparent to terminals that cannot display them.

General Features

All four arrow keys can be used to position the cursor to a particular field to change it.

The DO key at any point updates any changes made. The EXIT key return the cursor to the field entry without updating the screen file.

At the page, field or Change/Delete entry a PF1 will switch to display mode and show the current page with all specified video attributes. If there is no current page, you will be asked the page to display.

At the page, field or Change/Delete entry a PF2 will ask for an output specification defaulting to SYS$OUTPUT. The contents of the screen file will be printed first in alpha sequence then in row, column sequence.

Display mode:

Once the page has been displayed with PF1, the up and down arrow keys will move the cursor from field to field. The page, field, x and y position are displayed at the bottom of the screen.

PF1 will return the screen to the field maintenance page with the values of the selected field from the display page filled in.

PF2 will prompt for an output file specification and then will output an image of the current page.

INSERT_HERE will insert a blank line above the currently selected field moving it and all fields below it down one line. Any fields that would be moved off the bottom of the screen will stop at the bottom.

REMOVE will delete a line from the screen by moving all lines from the currently selected field to the end of the screen up one line. If a field is already at the top of the screen, it will not be moved.

Neither the INSERT_HERE nor REMOVE line functions delete fields, they only add or delete lines on the screen. REMOVE may cause existing fields to overlap.

SELECT will allow a prompt or a field to be moved on the screen by using the arrow keys. SELECT operates in two modes: The first time SELECT is pressed, 'SELECT PROMPT' mode is activated and the prompt and field may be positioned with the arrow keys. The second time SELECT is pressed, 'SELECT FIELD' mode is activated and the FIELD alone may be positioned. Press SELECT again to return to the normal field to field mode for the arrow keys.

PF3 in the display mode changes the screen to graphics mode to access the VT100/VT200/VT300 series line drawing set. The cursor goes to the upper left corner and the message 'UP' is displayed in the upper right corner. In the graphic mode the arrow keys are used to move the cursor on the page. When the 'pen' is up no changes to the screen are made. When you want to draw lines, press D for down and the pen mode will change to down. The pen will now draw lines on the screen as it is moved. Pressing the E for erase changes the pen mode to erase and any line that the cursor goes over will be erased. The pen mode can be changed to up by pressing U for up. When the pen mode is down the numeric keypad is mapped to allow corners and intersections to be displayed. Each of the keys 1 thru 9 is a corner or intersection according to the following sequence:

Typing F for finish will exit the graphics mode and return to the normal display mode. All the graphics for a page is stored as a single structure so if multiple graphic images are to be stored, they must be on separate pages.

There is no check for fields that overlap each other and no support for 132 columns screens.

Programming

Screen files may be used in programs by inserting directives into the program that are read by the precompiler. Each directive begins with the character sequence $DSI. Remember that the precompiler makes a single pass and directives are executed in lexical order. Each field on the screen is composed of two areas. The first is the prompt area where the text for a field is displayed and the second is the data area where the data for the field is entered.

SCREEN FILE

To reference a screen file in a program the following directive must appear before any other screen directive:

$DSI SCREEN

This will cause the screen file to be opened. This directive can appear more than once but each use will close the previously referenced screen file. The screen file extension if not specified will default to .SCR.

SCREEN PAGE

Next the current screen page is selected with the following directive:

$DSI PAGE

This page name is used by the DISPLAY and PRINT directives with the field name to locate the field record in the screen file. until another page directive changes the current page.

FIELD DISPLAY

Each field is painted by the DISPLAY directive. The optional argument must be a string and will be displayed as the default field value.

$DSI DISPLAY [string]

If the screen has already been painted with the field text by the DISPLAY directives the PRINT directive can be used to update the data portion of the display.

$DSI PRINT

If the data to be displayed is not a string then a string function can be used to format the data. Most of the ENTER_* modules have a corresponding DSI_FORMAT function that will ensure a consistent display between fields that are entered through ENTER_* modules and PRINT or DISPLAY directives.

CLEARING THE SCREEN

The screen is cleared by using the directive:

$DSI CLEAR [Text]

If the text parameter is present it will be displayed in normal video. This is the standard way to exit a program to turn off the video attributes.

GRAPHICS

$DSI GRAPH

This will load the graphics stored on the page into the screen buffer. It does not actually display the graphics but they will appear after the next screen repaint. I/O OPTIMIZATION

The precompiler optimizes I/O based on the expected sequence of:

$DSI CLEAR
$DSI GRAPH page
$DSI DISPLAY field string
.
.
.

The precompiler will insert a call to DSI_REPAINT after the display directives automatically so the entire screen will paint in one output operation. The optimized sequence stops when anything other than a blank line, a DISPLAY or a PRINT directive. Therefore any formatting of strings should be performed before the CLEAR and any conditional fields should be placed after the DISPLAYS or PRINTS that are always executed.

Basic Precompiler Specifics

The data entry modules that position the cursor all start with the format:

CALL ENTER_(x position, y position, length, ...

In order to use the information from the screen file, replace the first three parameters with a percent sign and then the field name.

CALL ENTER_type(%field, ...

-- or --

CALL ENTER_type({field}, ...

-- or --

CALL XYPRINT({field}, ...

In the last two formats the {field} can be modified by appending a :ROW, :COL, and/or :LEN to the field name. For example:

CALL ENTER_STRING({COMPANY:ROW+J:LEN+3}, COMPANY, COMPANY)

The input will be taken J rows down from where the screen field COMPANY is defined and the data field will be extended 3 spaces. The same logic applies to XYPRINT.

Also the module TERM_POS which is normally referenced as

CALL TERM_POS(x, y)

can be written to use the x and y position of the prompt of a field as follows

a) CALL TERM_POS(%field)
b) CALL TERM_POS({field})
c) CALL TERM_POS({field} + value, value)
d) CALL TERM_POS(value, {field} + value)
e) CALL TERM_POS({field} + value, {field} + value)

All directives will be deleted and all field references will be replaced in the output file which is then passed on to the compiler. Examples c thru e will fill in only the appropriate vertical or horizontal position. This allows indexing from a screen designated screen position. EG:

CALL TERM_POS({TEXT} + J, 10) FOR J = 10 TO 15

Normally the precompiler is called by issuing the command:

$ DSI PREBASIC

The program extension may not be specified and is always taken as .BAS. If the program requires a command procedure to build it, use the following sequence to obtain a VAX Basic version of the source code:

$DSI DSICOM
$BASIC/TYPE:EXPLICIT .TMP
$LINK ,,...

Cobol Precompiler Specifics

The calls to the data entry modules are made through the following directive:

$DSI ENTER_

The data type parameter must be one of the types supported by the callable modules. The allowable data types are DATE, DOUBLE, INTEGER, LONG, MONEY, REAL, SINGLE, STRING, TIME and WORD.

The field name parameter, along with the page name in the last screen directive, specifies the field to use. This defines the row, column, length of the input field.

The result and default parameters must both be of the same variable type as the beginning data type parameter. Dates and times are string data type and money is a double floating data type. The value entered is returned in the variable specified by the result parameter. The value returned if the user just enters a carriage return is specified by the default parameter.

An example of a call to input a date field at the screen position defined by page MAIN, field INVDATE, returning a value into INVOICE-DATE and defaulting to DEF-DATE would be:

$DSI PAGE MAIN
$DSI ENTER_DATE({INVDATE}, INVOICE-DATE, DEF-DATE)

Note that the PAGE directive is only required once for all the fields on the same page.

The current screen can be saved by moving the data in DSI_SCREEN_BUFFER to a local variable. To restore the screen move the local variable back into DSI_SCREEN_BUFFER and call DSI_REPAINT.

In order to compile a program with screen directives the programmer enters DSICOB . This invokes the precompiler which reads the source program, interprets the directives and writes a new file name>.TMP. This is then passed through the Cobol compiler and linked against the callable module library.

If the program also calls other subprograms then a command procedure can be constructed that runs the precompiler on each source segment. If a program MAIN calls three subprograms SUB1, SUB2 and SUB3 then the following command procedure will precompile, compile and link the program: $! MAIN.COM
$! Build program MAIN which calls SUB1, SUB2 and SUB3
$
$RUN DSILIB:PRECOBOL MAIN
$COBOL MAIN.TMP
$DEL MAIN.TMP;*
$
$RUN DSILIB:PRECOBOL SUB1
$COBOL SUB1.TMP
$DEL SUB1.TMP;*
$
$RUN DSILIB:PRECOBOL SUB2
$COBOL SUB2.TMP
$DEL SUB2.TMP;*
$
$RUN DSILIB:PRECOBOL SUB3
$COBOL SUB3.TMP
$DEL SUB3.TMP;*
$
$LINK MAIN,SUB1,SUB2,SUB3,-
DSILIB:DSILIB/LIBRARY,DSILIB:DSILIB/OPTION