DISPLAY src-item (ANSI format)

Format 9

DISPLAY src-item (ANSI format) sends data directly to the screen without using the ACUCOBOL-GT window 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.
• In the DOS/VS COBOL compatibility mode, output may be sent to a simulated card punch. See Appendix G, section 1.1 "DISPLAY UPON SYSPUNCH" for details.