Format 9 - sends data directly to the screen without using the ACUCOBOL-GT display manager (ANSI format)
DISPLAY {src-item} ... [ UPON mnemonic-name ] [ WITH NO ADVANCING ]
Syntax Rules
1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
2. Src-item is a literal or data item. It must be USAGE DISPLAY unless the CONVERSION phrase is also specified. Src-item specifies the data to be displayed.
3. Mnemonic-name must be a user-defined word declared in Special-Names that refers to a display device, or it must be the name of the display device itself. See section 4.1.3, "Special-Names," for a list of valid devices.
4. If the UPON phrase is specified it must be the first optional phrase.
5. If the UPON phrase is omitted, then the "-Ca" compiler option must be specified. If it is not, then the statement is treated as a Format 1 DISPLAY statement instead.
General Rules
1. The data contained in src-item is sent to the output device named by the UPON phrase. If the UPON phrase is omitted, the output device is assumed to be the user's console.
2. If the WITH NO ADVANCING phrase is omitted, then the device is advanced to the next line after the last src-item is displayed. If WITH NO ADVANCING is specified, no additional action takes place after the data is sent to the output device. If line advancing is used, trailing spaces are removed from the last src-item before it is sent to the device.
3. If the output device is any of the following, the data is sent to the user's console:
CONSOLE, SYSOUT, SYSLST, SYSLIST
This data may be redirected with the "-o" runtime option or with operating system commands. If line advancing is used, the system's output buffer is flushed, but if NO ADVANCING is specified, then the buffer is not flushed. When data is sent to these devices, no editing or formatting of the data occurs.
4. If the output device is SYSOUT-FLUSH, the data is sent to the user's console. After the last src-item is sent, the output buffer is flushed, forcing the data to be sent immediately. No editing or formatting of the data occurs.
5. If the output device is SYSERR, the data is sent to the runtime's error output. This is either the user's screen or the file specified in the "-e" runtime option.
6. Technical Note: This form of the DISPLAY statement sends data directly to the user's screen without using ACUCOBOL-GT's window manager. On many machines, the window manager maintains an image of the user's screen in memory. (This improves efficiency by omitting redundant screen displays and is used to implement "pop-up" windows.) By sending data directly to the screen, you can cause the window manager's screen image to be in error. This can cause strange effects when mixed with ACUCOBOL-GT-specific DISPLAY statements, including:
lost data
incorrect functioning of CLOSE WINDOW
incorrect cursor position
incorrect character attributes
incorrect display in debugger
For these reasons, you must be careful when using ANSI DISPLAY. Here are some useful guidelines:
If your DISPLAY does not affect the screen image, then it's OK to use it. For example, you can use ANSI DISPLAY to send a control
sequence to an attached printer or cash register.
If you use only ANSI DISPLAY statements, then you should not experience any
problems (except that the debugger will not be able to restore the user's screen). With this approach, you should avoid all DISPLAY statements except
for Format 9.
If you must mix formats, then you can use the library routine "W$FORGET" to correct the behavior of the window manager. This routine causes the
window manager to enter its initial state, where it does not know the screen image
or current attribute settings. If you call this routine after a series of
Format 9 DISPLAY statements, the window manager will be set to a state where it can
correctly manage the screen. Note that this routine will cause the cursor to
be positioned to the last line on the screen.
You can always use UPON SYSERR safely. When sent to the screen, the output is
directed through the window manager. Normally, you would use this with the "-e"> runtime option to direct error messages to an error log file.