PreviousCOBOL System Library Routines Introduction to On-line HelpNext

Chapter 7: Windowing Support for Text-based Systems

Windowing syntax is supplied for backward compatibility only. We recommend that you do not use it when creating new applications.

Your COBOL system supports syntax which enables you to draw lines and boxes on the terminal screen, and create virtual terminal windows on a physical terminal. All ACCEPT and DISPLAY statements then act within the current window (except for ACCEPT format 1, 2, or 3 statements, DISPLAY format 1 statements, and DISPLAY WINDOW/LINE/BOX statements). The syntax also enables underlying displays to be kept and restored.

The following syntax for windowing support is available:

DISPLAY WINDOW - This statement creates a terminal window (a rectangular region of the screen) and makes it the current window. This is like a virtual terminal, in which screen positions used by subsequent ACCEPT/DISPLAY statements are relative to the top left corner of the window.

DISPLAY LINE - This statement enables you to draw lines on the terminal (real or virtual). The best mode available on the terminal is used automatically. Used with the DISPLAY BOX statement, the DISPLAY LINE statement enables you to draw lines on the terminal.

DISPLAY BOX - This statement enables you to draw boxes on the terminal. The best mode available on the terminal is used automatically. Used with the DISPLAY LINE statement, the DISPLAY BOX statement enables you to draw forms on the terminal.

CLOSE WINDOW - This statement removes a window. If you specify the window as being a POP-UP window, the underlying display can be restored.

7.1 Enabling Windowing Support

In order to use the windowing syntax, you must use the PREPROCESS"WINDOW1" Compiler directive. For the UNIX operating system the directive must be specified in lower case ("window1").

You can specify this directive in one of two ways.

The PREPROCESS "WINDOW1" directive must be the last Compiler directive apart from NOERRQ, AUTOCLOSE or COLOR. If an error is encountered, the Compiler asks if you wish to ontinue, and waits for your response. In order to disable this function, you must specify the NOERRQ directive after PREPROCESS "WINDOW1".

UNIX:
On the UNIX operating system, if you create a new RTS that is to make use of windowing syntax, you must include the -I COBWIN2 flag on the command line. The following is an example of a command line you could use to create a new RTS to include windowing support:

cob -x -I COBWIN2 -o rts.new

7.2 Windowing Support Syntax

The following sections give details of the windowing syntax enabled by the PREPROCESS "WINDOW1" directive.

7.2.1 The DISPLAY Statement

This section explains COBOL windowing, which provides three additional formats of the DISPLAY verb for creating windows and drawing lines and boxes. Other formats are described in your Language Reference.

Format 1 - DISPLAY WINDOW

The DISPLAY WINDOW statement is part of the windowing syntax enabled by the PREPROCESS"WINDOW1" directive. The DISPLAY WINDOW statement is for creating windows.

Format 2 - DISPLAY LINE

The DISPLAY LINE statement is for drawing lines.

Format 3 - DISPLAY BOX

The DISPLAY BOX statement is for drawing boxes.

Syntax Rules

  1. line-num is a numeric literal or data item that specifies the line position on the terminal screen. It must be a nonnegative integer.

  2. col-num is a numeric literal or data item that specifies the column position on the terminal screen. It must be a nonnegative integer.

  3. length is a numeric literal or data item that specifies the window-width, line-width or box-width in character positions. It must be a nonnegative integer.

  4. height is a numeric literal or data item that specifies the number of lines in the window, line or box. It must be a nonnegative integer.

  5. title is a nonnumeric literal or alphanumeric data item.

  6. save-area is an elementary data item described by a PIC X(10) clause.

  7. REVERSE and REVERSED and REVERSE-VIDEO are equivalent.

  8. The COLOR clause is only supported when the preprocessor directive COLOR is used. This adds support for existing non-Micro Focus syntax.

  9. Exactly one of the SIZE or LINES phrases must be specified for a Format 2 DISPLAY statement.

  10. identifier-1, identifier-2, integer-1 and integer-2 must take a value in the range 0-7 as follows:

    0 black
    1 blue
    2 green
    3 cyan
    4 red
    5 magenta
    6 brown or yellow
    7 white

  11. identifier-3 and integer-3 must take a value which is obtained by adding together the appropriate values from the following:

    Color
    Foreground
    Background
    Black 1 32
    Blue 2 64
    Green 3 96
    Cyan 4 128
    Red 5 160
    Magenta 6 192
    Brown 7 224
    White 8 256


    Note: The foreground color values for use with the COLOR clause are different from the standard Micro Focus color values for; FOREGROUND-COLOR, BACKGROUND-COLOR and so on.


    In addition you can specify the following video attributes with the following values:

    Reverse video 1024
    Low intensity 2048
    High intensity 4096
    Underline 8192
    Blink 16384

  12. If a COLOR clause is present at the same time as FOREGROUND-COLOR and/or BACKGROUND-COLOR, then the colors defined in the COLOR clause are ignored, but any non-color attributes are actioned (where appropriate).

General Rules

All Formats
  1. The LINE and COLUMN phrase s must specify a line or column on the physical screen.

  2. On color systems, both the settings given in COLOR or FOREGROUND-COLOR and BACKGROUND-COLOR and other attribute settings (for example blink) are used. On monochrome systems, all color information supplied is ignored, and only other attribute settings used.

  3. Not all combinations of attributes are supported on all systems. For example, on a standard DOS PC, set to monochrome mode, REVERSE and UNDERLINE are mutually exclusive - only one of these attributes is actioned.

  4. If the color value for either foreground or background is set to 0 in the COLOR field, then the corresponding color of the default system attribute is used.
Format 1 (DISPLAY WINDOW)
  1. The DISPLAY WINDOW statement creates and makes current a terminal window. The terminal window is a rectangular region of your screen. Any ACCEPT or DISPLAY statements (apart from another DISPLAY WINDOW/LINE/BOX or a Format 1, 2 or 3 ACCEPT or Format 1 DISPLAY as described in your Language Reference) affect only the current window. Furthermore, line and column numbers for all ACCEPT and DISPLAY statements (apart from another DISPLAY WINDOW/LINE/BOX or a Format 1, 2 or 3 ACCEPT or Format 1 DISPLAY as described in your Language Reference) are computed from the upper left hand corner of the current window. That is, the current window defines a virtual terminal screen which occupies some area of your physical screen.

  2. The initial window is set to the entire screen.

  3. The only way to change the current window is with another DISPLAY WINDOW statement or with the CLOSE WINDOW statement.

  4. The LINE NUMBER phrase sets the top line of the window. Line number one refers to the top line of the screen. Line numbers are relative to the screen, and not to the current window.

  5. If the LINE NUMBER phrase is not specified, is specified as zero, or is off the physical screen, the top line of the screen is used.

  6. The COLUMN NUMBER phrase sets the leftmost column of the window. Column number one refers to the left side of the screen. Column numbers are relative to the screen, and not to the current window.

  7. If the COLUMN NUMBER phrase is not specified, is specified as zero, or is off the physical screen, column number one is used.

  8. The SIZE phrase sets the number of columns the window contains. If this causes the window to extend past the right edge of the screen, the window's width extends off the screen.

  9. If the SIZE phrase is not specified or is specified as zero, the window extends to the right edge of the screen.

  10. The LINES phrase sets the number of rows the window contains. If this causes the window to extend past the bottom of the screen, the window extends off the screen.

  11. If the LINES phrase is not specified or is specified as zero, the window extends to the bottom edge of the screen.

  12. When the ERASE phrase is specified, the window is cleared immediately after it is created. Otherwise the window's contents are not changed. Clearing a window sets it to spaces.

  13. The BOXED phrase causes a box to be drawn around the new window. The box is drawn outside the window. Any portions of the box that lie off the screen are not drawn.

  14. The terminal's line drawing set is used to draw the box. If the terminal does not have a line drawing set, equivalent ASCII characters are used. If the POP-UP phrase is also specified, the box overlays any other boxes on the screen. If this phrase is not specified, the box drawn is attached to any other boxes it intersects. When a boxed non-popup window intersects a boxed popup window, if the popup window is created first, when it is closed the points where the two window boxes intersected is not redrawn. That is, intersection characters remain even though there is no longer an intersection.

  15. The ERASE phrase is implied by the BOXED phrase.

  16. The REVERSED phrase exchanges the window's foreground and background colors. This affects every ACCEPT and DISPLAY statement in the new window.

  17. The REVERSED phrase implies the ERASE phrase. This usually causes the entire window to be set to reverse video spaces when it is initially created.

  18. The TITLE phrase causes the title to be printed in the window's border. This has its effect only if the BOXED phrase is also specified.

  19. Titles can be placed in one of six positions in the border region: top left, top center, top right, bottom left, bottom center and bottom right. If TOP or BOTTOM is not specified, TOP is used. If LEFT, CENTERED or RIGHT is not specified, CENTERED is used.

  20. The POP-UP AREA phrase causes your COBOL system to save system information prior to creating the new window. This information can be used by the CLOSE WINDOW statement to subsequently remove the new window and restore the underlying windows. This gives a popup window.

  21. The save-area data item is filled in with system information. This data item must not be subsequently modified in any way or results are undefined. It can be referenced in a CLOSE WINDOW statement to restore an earlier window to the screen and re-establish that window as the current window.
Format 2 (DISPLAY LINE)
  1. The DISPLAY LINE statement enables you to draw vertical and horizontal lines in a machine- and terminal-independent manner. The lines are drawn using the best mode available on the display device. Used together with the DISPLAY BOX statement, this provides the ability to draw lines on your screen. The DISPLAY LINE statement does not affect the positioning of full screen ACCEPT and DISPLAY statements.

  2. Lines are drawn so that when they intersect other lines on the screen, the appropriate intersection character is used. This is done so that when the end of a line intersects another line, the appropriate corner or three-way intersection is used.

  3. If the SIZE phrase is specified, the line drawn is horizontal. The value of length gives the size of the line in screen columns. If the LINES phrase is used instead, the line drawn is a vertical line and height describes the number of screen rows to use.

  4. Lines never wrap around or cause scrolling. If the LINES or SIZE phrase would cause the line to leave the current window, the line is truncated at the edge of the window. If LINES or SIZE is zero, no line is drawn.

  5. The value of line-num gives the starting row of the line. The value of col-num gives the starting column. Lines are always drawn to the right or downward as appropriate. line-num and col-num must specify a position that is contained in the current window.

  6. If the LINE NUMBER or COLUMN NUMBER phrases specify a point outside the physical screen, that is, line-num = 0 or 24 (or your screen's maximum), or col-num = 0 or > 80, no line is drawn.

  7. The TITLE phrase has effect only when drawing horizontal lines. When specified, title-string is printed in part of the line.

  8. The title can be printed near the right side, near the left side or in the center of the line depending on the RIGHT, LEFT or CENTERED phrase specified. If none is specified, CENTERED is used.

  9. The REVERSE phrase exchanges the foreground and background color of the line.
Format 3 (DISPLAY BOX)
  1. The DISPLAY BOX statement enables you to draw a box in a machine- and terminal-independent manner. The boxes are drawn using the best mode available on the display device. If the lines used in drawing a box intersect other lines already present on the screen, the appropriate intersection characters are used. The DISPLAY BOX statement does not affect the positioning of full screen ACCEPT and DISPLAY statements.

  2. The location of the box is specified by providing the location of the upper-left corner. The size of the box is specified by providing a height and a width.

  3. If the LINE NUMBER or COLUMN NUMBER phrases specify a point outside the physical screen no box is drawn.

  4. The SIZE phrase specifies the width of the box. The LINES phrase specifies its height. If the SIZE phrase is not specified, or zero, or such that the box would extend beyond the physical screen or the edge of the window, the box extends to the right edge of the current window. If the LINES phrase is not specified, or zero, or such that the box would extend beyond the physical screen, the box extends to the bottom of the current window.

  5. The REVERSE phrase operates in the same manner as it does for a DISPLAY WINDOW statement.

  6. The TITLE phrase operates in the same manner as it does for the DISPLAY WINDOW statement.

7.2.2 The CLOSE WINDOW Statement

The CLOSE WINDOW statement closes the current video terminal window.

Format

CLOSE WINDOW window-save-area

Syntax Rules

  1. window-save-area must be an elementary data item described with a PIC X(10) clause. It must have been the object of a POP-UP AREA phrase in a DISPLAY WINDOW statement.

General Rules

  1. The CLOSE WINDOW statement is used to remove popup windows created by the POP-UP AREA option of the DISPLAY WINDOW statement.

  2. window-save-area must have been the object of a POP-UP phrase of a DISPLAY WINDOW statement that has been executed in this run-unit. Furthermore, since that execution, it must not have been the object of a CLOSE WINDOW statement, nor can it have been modified by any other statement. Violation of these rules causes undefined results.

  3. The CLOSE WINDOW statement restores the contents of the terminal screen that was in the active window when the corresponding DISPLAY WINDOW statement executed. In other words, the window that was created by that DISPLAY WINDOW statement is removed from the screen and replaced by the contents of the screen which were under that popup window.

  4. The window that was active when the corresponding DISPLAY WINDOW statement executed becomes the active window, thereby becoming the top window and overlaying any other windows that might be present.

    The current window is selected by closing windows identified by their respective window-save-area data items, as in the following example:

    If five popup windows are created, a, b, c, d and e in that order:

7.3 Windowing Restrictions

7.4 Windowing Error Messages

The following errors might be encountered during preprocessing windowing.

 001  Unexpected numeric literal:
 002  Unexpected alphanumeric literal:
 003  Unsupported keyword or noiseword:
 004  Unrecognized clause to DISPLAY WINDOW:
 005  Unrecognized clause to DISPLAY LINE:
 006  Unrecognized clause to DISPLAY BOX:
 007  Unrecognized clause to ACCEPT FROM SCREEN:
 008  This keyword has already been used:
 009  This keyword conflicts with another:
 010  This reserved word is used incorrectly:
 011  Wrongly formed or ordered clause with keyword:
 012  Error during preprocessing - no further details

The edit/compile/animate loop returns to an incorrect line within your source program after returning an error.

7.5 Windowing Supplementary Information

When the first windowing statement in your program is encountered the screen is redisplayed. This is expected behavior and does not affect your program in any way.

7.6 Windowing Syntax Example

$set preprocess(window1)
 working-storage section.
 78 note-height  value 16. 
 78 note-width  value 41.
 78 no-of-chars  value note-height * note-width.
 01 note-window  pic x(10).
 01 dummy    pic x.
 01 note-data value all "- wallpaper ".
   03 note-char pic x occurs no-of-chars.
 screen section.
 01 input-data highlight.
   03 line 4 column 6 value " Accept and Display positions ".
   03 line 5 column 6 value " are relative to the top left ".
   03 line 6 column 6 value " corner of the window. ".
   03    pic x using dummy.
 01 note-screen  pic x(no-of-chars)
               using note-data prompt " " reverse-video.
 procedure division.
* Put a blank window on the screen with a border and title
      display window, line 2, column 38, lines note-height,
               size note-width, boxed, erase, reverse
* Define a reference for this window so that it can be removed
* and the previous display restored
               pop-up area is note-window
               bottom right title "Press Enter to remove window"
* Fill the window with the contents of note-screen
      display note-screen
      display input-data
      accept input-data
      close window note-window.


Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousCOBOL System Library Routines Introduction to On-line HelpNext