HP 3000 Manuals HP 3000 Manuals
Windowing Support Syntax
The following sections give details of the syntax of the CLOSE WINDOW
statement and the OPEN WINDOW statements.
The CLOSE WINDOW Statement
The CLOSE WINDOW statement closes the current video terminal window.
Format.
CLOSE WINDOW window-save-area
Syntax Rule.
window-save-area must be an elementary data item described by 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 pop-up 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 pop-up 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 pop-up windows are created, a, b, c, d and e in that order:
* If d is closed, c becomes current.
* If b is then closed, a becomes current.
* If e is subsequently closed, c becomes current again.
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 (which are also applicable to ANSI and Screen
Section types) are described in your Language Reference .
Format 1.
![[]](../../pic3k/M015153/FFN3073c50.gif)
Format 2.
![[]](../../pic3k/M015153/FFN3083c50.gif)
Format 3.
![[]](../../pic3k/M015153/FFN3093c50.gif)
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 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. 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 PICTURE X(10)
clause.
7. REVERSE and REVERSED are equivalent.
8. Exactly one of the SIZE or LINES phrases must be specified for a
Format 2 DISPLAY statement.
General Rules
All Formats.
1. The LINE and COLUMN phrases must specify a line or column on the
physical screen.
Format 1 (DISPLAY WINDOW).
2. 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, ACCEPT or DISPLAY statement format 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, ACCEPT or DISPLAY
statement format 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 virtual screen.
3. The initial window is set to the entire screen.
4. The only way to change the current window is with another DISPLAY
WINDOW statement or with the CLOSE WINDOW statement.
5. The LINE NUMBER phrasesets 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.
6. 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.
7. The COLUMN NUMBER phrasesets 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.
8. If the COLUMN NUMBER phrase is not specified, is specified as
zero, or is off the physical screen, column number one is used.
9. The SIZE phrasesets 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.
10. If the SIZE phrase is not specified or is specified as zero, the
window extends to the right edge of the screen.
11. The LINES phrasesets the number of rows the window will contain.
If this causes the window to extend past the bottom of the screen,
the window extends off the screen.
12. If the LINES phrase is not specified or is specified as zero, the
window extends to the bottom edge of the screen.
13. When the ERASE phraseis 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.
14. The BOXED phrasecauses 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.
15. 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 phraseis 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 pop-up window intersects a boxed
pop-up window, if the pop-up 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.
16. The ERASE phrase is implied by the BOXED phrase.
17. The REVERSED phraseexchanges the window's foreground and
background colors. This will affect every ACCEPT and DISPLAY
statement in the new window.
18. 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.
19. The TITLE phrasecauses the title to be printed in the window's
border. This has its effect only if the BOXED phrase is also
specified.
20. 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.
21. The POP-UP AREA phrasecauses your COBOL system to save system
information prior to creating the new window. This information
can be used by the CLOSE WINDOWstatement to subsequently remove
the new window and restore the underlying windows. This gives a
pop-up window.
22. 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
reestablish that window as the current window.
Format 2 (DISPLAY LINE).
23. The DISPLAY LINEstatement 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 forms on your screen. The DISPLAY
LINE statement does not affect the positioning of full screen
ACCEPT and DISPLAY statements.
24. 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.
25. If the SIZE phraseis 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.
26. 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.
27. 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 downwards as appropriate. line-num and
col-num must specify a position that is contained in the current
window.
28. If the LINE NUMBERor COLUMN NUMBERphrases 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.
29. The TITLE phrasehas effect only when drawing horizontal lines.
When specified, title-string is printed in part of the line.
30. The title may 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.
31. The REVERSE phraseexchanges the foreground and background color of
the line.
Format 3 (DISPLAY BOX).
32. The DISPLAY BOXstatement 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.
33. 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.
34. If the LINE NUMBER or COLUMN NUMBER phrases specify a point
outside the physical screen, that is line-num &> 24 (or your
screen's maximum) or col-num &>80, no box is drawn.
35. 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, the box will extend 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.
36. The REVERSE phrase operates in the same manner as it does for a
DISPLAY WINDOW statement.
37. The TITLE phrase operates in the same manner as it does for the
DISPLAY WINDOW statement.
Windowing Restrictions
* This feature is not guaranteed to be intermediate code compatible,
so you may need to recompile your source code between product
releases.
* If you create a new RTS that is to make use of windowing syntax
you must include the -I cob flag on the command line as follows:
-I COBWIN1
See the appendix Descriptions of cob Flags for more information on
the use of the -I cob flag.
* When using the ACCEPT or DISPLAY statements with this new
windowing syntax, you must include the AT LINE NUMBERsyntax (see
your Language Reference ) or the syntax will not appear in the
windows.
* You should not use cobprintf() with these DISPLAY statements.
* You should not use COPY REPLACINGor REPLACEstatements.
* The following reserved words have been introduced by the windowing
syntax, so you should avoid specifying them:
BOX
BOXED
CENTERED
POP-UP
WINDOW
* You should use only the ACCEPT and DISPLAY statements documented
in your Language Reference with this windowing syntax.
* When using windowing syntax, the ANS85 Compiler directive
is implied. You must not unset this directive either explicitly
or implicitly.
* Alphanumeric literals must not be continued over the end of any
line which includes a windowing statement.
* Some syntax errors, for example, spelling PROCEDURE DIVISION
incorrectly, will be flagged, but may result in spurious error
messages for the next source lines.
* You must not use windowing syntaxin nested programs or in programs
which use nested COPY statements.
* Windowing syntax errorsare serious errors, but are flagged in the
form:
xnnn-P*******
* The -P cob flag should not be used with windowing syntax. You
should instead use "-C list".
* Column 73 must not be used within source programs which use
windowing syntax, as this column is always treated as being set to
a space character.
* The Compiler asks if you wish to continue after any error occurs.
You can disable this function by using the NOERRQ directive. You
should not, however, use the NOERRQ directive when compiling from
within Toolbox.
If no error occurred, or if an error occurred but you replied "no"
to the question "do you wish to continue", the Compiler will
return a zero error return-code.
* Color is not supported within ACCEPT/DISPLAY statements. Normal
attributes are displayed.
* No part of the following statements may appear on the same line:
DISPLAY WINDOW
DISPLAY BOX
DISPLAY LINE
CLOSE WINDOW
EXIT PROGRAM
* The windowing subsystem is initialized automatically upon
encountering the first windowingstatement. When the windowing
subsystem is loaded, color is not supported at run time (normal
attributes are displayed) and nonwindowing ACCEPT/DISPLAY
performance may be slightly slower.
* The windowing subsystem can be implicitly and automatically
unloaded by an EXIT PROGRAM statement if you specify the
preprocessor directive AUTOCLOSE on an initial source line as
shown below:
$set preprocess "window1" autoclose
This causes all EXIT PROGRAM statements within that source module
to close down the windowing system before exiting the subprogram.
The windowing subsystem is reinitialized upon encountering another
windowing statement. Each time the windowing subsystem
initializes, the background screen and contents are redisplayed.
You can create a subroutine to explicitly close the windowing
system by compiling the following subroutine:
$set preprocess "window1" autoclose procedure division para-1.
exit program.
You need simply call this subprogram.
* You should not mix calls to Panels and calls to windowing
syntaxwithin the same run-unit.
* When a window is active, or has been active in the run-unit, use
of the DISPLAY SPACES UPON CRT statement clears the window to
spaces but leaves attributes unchanged.
Windowing Error Messages
The following errors may be encountered during windowing. An explanation
of the error will appear after the colon.
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.
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.
Demonstration Programs
Two windowing and box drawing syntax demonstration programs, note.cbl
and calc.cbl, are included in your software delivery. You can call both
of these programs from an application program, and you can also run them
from the command line. The note.cbl program implements a simple notepad
which you can call from an application in order to make notes, read or
write notes to a file, or invoke the calc.cbl program, which in turn
implements a simple on-screen calculator and pastes the results into the
current note.
In order to run the demonstration programs you should install your Micro
Focus COBOL software and copy the demonstration programs into a working
directory, and then compile them. You should enter:
cp $COBDIR/demo/WINDOW1/note.cbl . cp $COBDIR/demo/WINDOW1/calc.cbl .
cob -u note.cbl calc.cbl
If the COBDIR environment variable is not in use, you should substitute
/usr/lib/cobol in place of $COBDIR in the line above.
Ensure the run-time environment is set correctly: the TERM environment
variable must be set to reference the correct terminfo entry for your
terminal, and the stty settings must be able to handle 8-bit characters
if necessary. The demonstration uses line drawing characters if
supported, as well as normal video attributes and function keys. If
special line drawing characters are not available, suitable ASCII
characters are used instead to provide an approximate rendition of boxes
and lines.
When you have compiled the demonstration programs, you can run the
notepad demonstration by entering the following:
cobrun note
A window appears on your screen, into which you can enter notes using the
data keys, Enter and the cursor keys (<- -> ^ v). To view the menu,
press F1. From this you can use the cursor keys or the letters to select
an option from Escape, Load, Save or Calculator. If you choose
Calculator, a window representing a calculator appears.
You can run the calculator demonstration without the notepad
demonstration by entering the following:
cobrun calc
rather than cobrun note as above. Note that the calculator shows zero
prior to your entering each number. Enter the following:
256 * 4 - 8 =
The result of (256 x 4) - 8 = 1016 is displayed. Press Escape, and the
calculator window disappears and 1016 is entered into the note.
If you press Escape again, the note also disappears.