# Compaq COBOL
Reference Manual

Previous | Contents | Index

## 6.8.10 DISPLAY

Function

The DISPLAY statement transfers low-volume data from the program to the default system output device or to the object of a mnemonic-name. The WITH CONVERSION phrase in Format 1 contains a Compaq extension to the DISPLAY statement. The Compaq extensions to Formats 2 and 3 are COBOL language additions that facilitate video forms design and data handling.

Format 4 sets a program variable to the current command line argument number (to read with a Format 7 ACCEPT), Format 5 sets the name of an environment variable or system logical, and Format 6 sets the value of an environment variable or system logical.

> ### src-item

> is a literal or the identifier of a data item. The literal can be any figurative constant.

> ### arg-position

> is a literal or identifier that specifies the desired argument position (on the run command line). It must be an unsigned integer.

> ### argument-number

> is a mnemonic name associated with ARGUMENT-NUMBER in the SPECIAL-NAMES paragraph in the Environment Division, representing the current argument position.

> ### environment-name

> is a mnemonic name associated with ENVIRONMENT-NAME in the SPECIAL-NAMES paragraph in the Environment Division, representing the name of an environment variable or system logical.

> ### environment-value

> is a mnemonic name associated with ENVIRONMENT-VALUE in the SPECIAL-NAMES paragraph in the Environment Division, representing the contents of the variable associated with the ENVIRONMENT-NAME.

> ### envlog-name

> references an alphanumeric data item, or is a nonnumeric literal.

> ### envlog-value

> references an alphanumeric data item, or is a nonnumeric literal.

> ### output-dest

> is a mnemonic-name defined in the SPECIAL-NAMES paragraph of the Environment Division.

> ### line-num

> is a numeric literal that specifies a line position on the terminal screen. line-num must be a positive integer. It cannot be zero.

> ### line-id

> is the identifier of a data item that provides a line position on the terminal screen. It must be a positive integer; it cannot be zero.

> ### plus-num

> is a numeric literal that increments the current value for line or column position, or that increments the value of line-id or column-id. plus-num can be zero or a positive integer.

> ### column-num

> is a numeric literal that specifies a column position on the terminal screen. column-num must be a positive integer. It cannot be zero.

> ### column-id

> is the identifier of a data item that provides a column position on the terminal screen. It must be a positive integer; it cannot be zero.

> ### screen-name

> is the name of a screen item defined in the SCREEN SECTION of the program.

> ### stment

> is an imperative statement executed if an exception condition exists; for Format 6, this means the name of the environment variable or logical has not been set by DISPLAY, or not enough space can be allocated to store the environment variable or logical.

> ### stment2

> is an imperative statement executed if the exception condition does not exist.

Syntax Rules

All Formats

1. In a DISPLAY statement, the number of src-item entries cannot exceed 254.
2. Each DISPLAY phrase can be specified only once for any src-item.

Formats 1 and 2

3. The WITH NO ADVANCING phrase can be specified only once per DISPLAY statement. It must be specified last (or just preceding END-DISPLAY, if used) if multiple src-item entries or options are specified in the statement.

Format 1

4. The UPON phrase can be specified only once per DISPLAY statement.

General Rules

Formats 1 and 2

1. The UPON and WITH NO ADVANCING phrases apply to all instances of src-item.
2. All phrases other than UPON and WITH NO ADVANCING apply to the immediately preceding src-item only.
3. If there is a WITH NO ADVANCING phrase, the DISPLAY statement does not transfer any device positioning information after the last src-item value.

CONVERSION Phrase (Formats 1 and 2)

4. The CONVERSION phrase allows you to display data in a field and achieve data conversion, sign, and decimal point placement. How the CONVERSION phrase affects data handling depends on the category of src-item. (Numeric data can be described by any USAGE clause.)
5. Numeric items do not require the CONVERSION phrase to be displayed correctly with conversion if you specify /DISPLAY_FORMATTED (on OpenVMS Alpha) or `-display_formatted` (on Tru64 UNIX) when you compile. (For more information on the qualifier, refer to the Compaq COBOL User Manual.)
6. The CONVERSION phrase or the /DISPLAY_FORMATTED (OpenVMS Alpha) qualifier displays nonnumeric items and numeric edited items without change.
7. The CONVERSION phrase or the /DISPLAY_FORMATTED (OpenVMS Alpha) qualifier displays non-floating-point numeric items according to the following rules:
   - The size of the displayed field is determined from the PICTURE character string.
   - Leading zeroes are displayed only when they immediately precede a decimal point.
   - If the sign is negative, a minus sign (-) is displayed. If the sign is positive, a space character is displayed. If the item is unsigned, no sign position is displayed.
   - Items with DISPLAY usage (for example, PIC 99, or PIC S99V99) are displayed after including a space, when needed, for a decimal point or sign or both.
     If you specify the SIGN TRAILING SEPARATE clause for the data item, the sign is displayed as a trailing sign. Otherwise, the sign is displayed as a leading sign.
   - Items other than DISPLAY (for example, PIC 99 COMP, or PIC S9V999 COMP SYNC) are displayed after conversion to DISPLAY usage SIGN LEADING.
   - Nonprinting numeric values are not human-readable on the terminal display unless the CONVERSION phrase or the /DISPLAY_FORMATTED qualifier (on OpenVMS Alpha) or `-display_formatted` (on Tru64 UNIX) is specified.
8. On OpenVMS, the CONVERSION phrase or /DISPLAY_FORMATTED (OpenVMS Alpha), or `-display_formatted` (on Tru64 UNIX), displays floating-point items as follows:
   - The floating-point data item is converted from internal floating point to E-notation representation. (E-notation consists of a mantissa and, optionally, an exponent.)
     The E-notation is described as follows:

     Size of mantissa | COMP-1 has 7 digits (F-floating, S-floating) plus decimal point and sign COMP-2 has 15 digits (G-floating, T-floating) or 16 digits (D-floating) plus decimal point and sign
     Sign of mantissa | Sign shown only for negative, space if positive
     Form of mantissa | d.dddddd for COMP-1 d.dddddddddddddd for COMP-2 (G-floating, T-floating) d.ddddddddddddddd for COMP-2 (D-floating) "." replaced by "," if DECIMAL POINT IS COMMA
     Size of exponent | 2 decimal digits for COMP-1 (F-floating, S-floating) 2 decimal digits for COMP-2 (D-floating) 3 decimal digits for COMP-2 (G-floating, T-floating)
     Range of exponent | -38 to +38 (base 10) for COMP-1 (F-floating, S-floating) -38 to +38 (base 10) for COMP-2 (D-floating) -308 to +308 (base 10) for COMP-2 (G-floating, T-floating)
     Form of exponent | E begins exponent sign shown for negative and positive; all digits shown (for example, E+01)

   - The size of the displayed field is 13 characters for COMP-1, and 22 characters for COMP-2. <>

9. The CONVERSION phrase or the /DISPLAY_FORMATTED qualifier (on OpenVMS Alpha) or `-display_formatted` (on Tru64 UNIX) displays floating-point items as follows:
   - The floating-point data item is converted from internal floating point to E-notation representation. (E-notation consists of a mantissa and, optionally, an exponent.)
   - The size of the displayed field is 13 characters for COMP-1 and 22 characters for COMP-2.
   - On Tru64 UNIX systems, the E-notation is described as follows:

     Size of mantissa | COMP-1 has 7 digits (plus decimal point and sign). COMP-2 has 16 digits (plus decimal point and sign).
     Sign of mantissa | Sign shown only for negative; space if positive.
     Form of mantissa | d.dddddd for COMP-1. d.ddddddddddddddd for COMP-2. "." replaced by "," if DECIMAL POINT IS COMMA.
     Size of exponent | 3 decimal digits for COMP-1 and COMP-2.
     Range of exponent | -308 to +308 (base 10) for COMP-1 and COMP-2.
     Form of exponent | E begins exponent sign shown for negative and positive; both digits shown (for example, E+01). <>

     On OpenVMS Alpha systems, compiled with the appropriate option on the /FLOAT qualifier, the E-notation is described as follows:

     Size of mantissa | COMP-1 has 7 digits (F-floating, S-floating) plus decimal point and sign. COMP-2 has 15 digits (G-floating, T-floating) or 16 digits (D-floating) plus decimal point and sign.
     Sign of mantissa | Sign shown only for negative; space if positive.
     Form of mantissa | d.dddddd for COMP-1 (F-floating, S-floating) d.dddddddddddddd for COMP-2 (G-floating, T-floating.) d.ddddddddddddddd for COMP-2 (D-floating). "." replaced by "," if DECIMAL POINT IS COMMA.
     Size of exponent | 2 decimal digits for COMP-1 (F-floating, S-floating). 2 decimal digits for COMP-2 (D-floating). 3 decimal digits for COMP-2 (G-floating, T-floating).
     Range of exponent | -38 to +38 (base 10) for COMP-1 (F-floating, S-floating). -38 to +38 (base 10) for COMP-2 (D-floating). -308 to +308 (base 10) for COMP-2 (G-floating, T-floating).
     Form of exponent | E begins exponent sign shown for negative and positive; all digits shown (for example, E+01). <>

Format 1

10. The DISPLAY statement transfers data from each src-item (in its order of appearance in the statement) to output-dest.
11. No editing or conversion occurs during DISPLAY execution unless there is an applicable WITH CONVERSION phrase.
12. If src-item is a figurative constant, only one occurrence is displayed.
13. When there is more than one src-item, sending item size is the sum of the src-item sizes.
14. If there is no UPON phrase, the DISPLAY statement transfers data to the default system output device.
15. If there is no WITH NO ADVANCING phrase, the DISPLAY statement transfers device positioning information. It resets the output-dest position to the leftmost position on the next line.
16. If DECIMAL POINT IS COMMA is specified, comma replacement occurs upon display.

Format 2

17. The presence of either the LINE NUMBER phrase or the COLUMN NUMBER phrase implies NO ADVANCING; that is, no line feed or carriage return is generated automatically following data output. The cursor remains on the character position immediately following the position of the last character displayed. This is the default starting position for the next data item you input from or display upon the terminal.
18. If you specify neither the LINE NUMBER phrase, the COLUMN NUMBER phrase, nor the WITH NO ADVANCING phrase, data is output according to Format 1 positioning rules for the DISPLAY statement. That is, a line feed and carriage return are generated automatically following data display.

LINE NUMBER Phrase (Format 2)

19. The LINE NUMBER phrase positions the cursor on a specific line of the video screen prior to displaying.
20. If the LINE NUMBER phrase does not appear but the COLUMN NUMBER phrase does, then data is displayed to the current specified column position.
21. If line-num or the value of line-id is greater than the bottommost line position of the current screen, program results are undefined.
22. If you use line-id without its PLUS option, the line position is the value of line-id.
23. If you use line-id with its PLUS option, the line position is the sum of plus-num and the value of line-id.
24. If you use the PLUS option without line-id, the line position is the sum of plus-num and the value of the current line position.
25. If you use the PLUS option, but you do not specify plus-num, then PLUS 1 is implied.
26. Data output results are undefined if your program generates a value for line-id that is one of the following:
    - Zero
    - Negative
    - Greater than the bottommost line position of the current screen

COLUMN NUMBER Phrase (Format 2)

27. The COLUMN NUMBER phrase positions the cursor on a specific column of the video screen.
28. If the COLUMN NUMBER phrase does not appear but the LINE NUMBER phrase does, then data is displayed to column 1 of the specified line position.
29. If you use column-id without its PLUS option, the column position is the value of column-id.
30. If you use column-id with its PLUS option, the column position is the sum of plus-num and the value of column-id.
31. If you use the PLUS option without column-id, the column position is the sum of plus-num and the value of the current column position.
32. If you use the PLUS option, but do not specify plus-num, PLUS 1 is implied.
33. Data output results are undefined if the program generates a value for column position that is one of the following:
    - Zero
    - Negative
    - Greater than the last column position on the screen

LINE NUMBER and COLUMN NUMBER Phrases (Format 3)

34. The LINE NUMBER and COLUMN NUMBER phrases together give the starting screen coordinates.
35. The position of each screen item within the referenced screen-name is offset from the LINE and COLUMN positions.
36. If either LINE or COLUMN is not specified, the default value is 1.

ERASE Phrase (Format 2)

37. The ERASE phrase erases all, or part, of a line (or screen) before displaying data. You must specify SCREEN or LINE.
38. If you use its TO END option, the ERASE phrase erases the line (or screen) from the implied, or stated, cursor position to the end of the line (or screen).
39. If you do not use its TO END option, the ERASE phrase erases the entire line (or screen).

BELL Phrase (Format 2)

40. The BELL phrase rings the terminal bell before displaying data.

UNDERLINED Phrase (Format 2)

41. The UNDERLINED phrase displays characters on the screen with the underscore on character attribute.

BOLD Phrase (Format 2)

42. The BOLD phrase displays characters on the screen with the bold on character attribute. The BOLD attribute is only detectable when any of the following conditions are true:
    - Nonspace characters are displayed.
    - The underlined or reversed attributes are specified.
    - The terminal screen is set to light background.

BLINKING Phrase (Format 2)

43. The BLINKING phrase displays characters on the screen with the blink on character attribute. The BLINKING attribute is only detectable when any of the following conditions are true:
    - Nonspace characters are displayed.
    - The underlined or reversed attributes are specified.
    - The terminal screen is set to light background.

REVERSED Phrase (Format 2)

44. The REVERSED phrase displays characters on the screen with the reverse video on character attribute.

Formats 4, 5, and 6

45. When a Format 4 DISPLAY statement is specified, the value stored in arg-position is moved to argument-number. This updates the current argument position indicator for the command line (see ARGUMENT-NUMBER in the SPECIAL-NAMES paragraph in Chapter 4). This points to the selected argument to be read by a Format 7 ACCEPT statement.
46. arg-position must be in the range 0 to 99 and can refer to arguments, switches, and flags that appear on the run command line of the COBOL program. When the current argument position indicator is zero, it refers to the zeroth command line argument, in other words the command that invoked the COBOL program.
47. When a Format 5 DISPLAY statement is specified, the value stored in envlog-name is moved to environment-name (see ENVIRONMENT-NAME in the SPECIAL-NAMES paragraph in Chapter 4). The updated value of environment-name becomes the environment variable or logical to be accessed by subsequent Format 6 DISPLAY and Format 8 ACCEPT statements.
48. environment-value, when used with a Format 6 DISPLAY, receives the value stored in envlog-value. The environment variable or logical is the one named by a Format 5 DISPLAY statement (see ENVIRONMENT-VALUE in the SPECIAL-NAMES paragraph in Chapter 4).
49. stment is executed if the name of the environment variable or logical has not been set by a Format 5 DISPLAY, or if the environment variable or logical does not exist.
50. stment2 is executed if the exception condition does not exist.

Technical Notes

Format 1

1. On OpenVMS, the DISPLAY statement transfers data through the I/O system (RMS), using the Variable with Fixed-Length Control (VFC) format. <>
2. A DISPLAY statement without the UPON phrase transfers data to the default output device (the terminal). To transfer data to a file on Tru64 UNIX systems, the environment variable COBOL_OUTPUT can be used to specify a text file containing output data. To transfer data to a file on OpenVMS systems the logical COB$OUTPUT or SYS$OUTPUT can be used to specify a text file containing output data.
   Alternatively, output device redirection (>) can be used on Tru64 UNIX systems to name an output file.
3. A DISPLAY statement that includes the UPON phrase transfers data to the file-device-name associated with the SPECIAL-NAMES paragraph description of output-dest.
4. Because the object of a logical name (on OpenVMS systems) is not necessarily a device, no open mode is implied. As a result, output-dest can be associated with any device-name in the SPECIAL-NAMES paragraph. For example, output-dest can refer to PAPER-TAPE-READER as well as PAPER-TAPE-PUNCH.

Format 2

5. Format 2 is a Compaq extension to the standard COBOL use of the DISPLAY statement.
6. The Compaq extensions to the ACCEPT and DISPLAY statements support data input and display only on the VT100 and later terminal types, including emulators of these terminal types.
7. The UNDERLINED, BOLD, BLINKING, and REVERSED character attributes are not available on VT100 terminals without the advanced video option.
8. You should display data only on fields that are within screen boundaries. That is, the terminal operator should see all the characters displayed. If data is displayed on fields that position the cursor outside screen boundaries, it does not result in an error condition. However, your program might not produce the results you expect.
   Values for screen boundaries depend on the terminal type and the column mode in which it is operating. Refer to the appropriate terminal user's guide for more information on screen boundaries.
9. Line positioning can be a one- or two-step process. The first (or only) step is absolute positioning, which is using the value of line-num or line-id to determine the line position. The second step is relative positioning, which is adding the value of plus-num to line-id to determine the line position.
   The following sample statements would produce undefined results because they use absolute line positioning to reach a line beyond the bottom of the screen (assume ITEMB has a value of 25):

       DISPLAY SRC-EXAMPLE AT LINE NUMBER 25.
       DISPLAY SRC-EXAMPLE AT LINE NUMBER ITEMB.
       DISPLAY SRC-EXAMPLE AT LINE NUMBER ITEMB PLUS 0.

   The last DISPLAY statement illustrates that use of the PLUS option does not necessarily mean that relative positioning will always occur. When you specify line-id, absolute line positioning always occurs before a PLUS option can execute. In this case, line-id (ITEMB) is specified, and it has a value of 25. Therefore, the line position is outside the screen boundary before the PLUS option executes, and program results are undefined.
10. When there is more than one src-item, each specific src-item is displayed, after application of any phrases specific to that src-item, in order of occurrence in the DISPLAY statement.

Formats 2 and 3

11. On OpenVMS, control sequences from SMGTERMS.TXT are used to accomplish cursor positioning, screen erasure, and video attributes. Refer to the Support for Non-Compaq Terminals chapter of the OpenVMS RTL Screen Management (SMG$) Manual if you wish to customize SMGTERMS.TXT. <>

All Formats

12. Compaq COBOL parses the contents of the data being displayed to determine how they affect the terminal and the cursor position. The parsing of control sequences is performed according to the DEC STD 138-0 Registry of Control Functions for Character Imaging Devices. Compaq COBOL does not modify the control sequences in any way; if an invalid control sequence is found, Compaq COBOL does not attempt to correct the sequence.
    Therefore when you display an escape or control sequence, the entire sequence must be displayed in one operation:
    - If you use DISPLAY Format 1, the complete sequence must be contained in one or more src-items within one DISPLAY statement.
    - If you use DISPLAY Format 2, the complete sequence must be contained in one src-item.
    - If you use DISPLAY Format 3, the complete sequence must be contained within one elementary screen item.
13. A DISPLAY statement used in an ACCEPT [NOT] ON EXCEPTION statement must be terminated (with, for example END-DISPLAY) on Alpha systems. If you are concerned with the different VAX behavior, refer to the appendix on compatibility in the Compaq COBOL User Manual.

Additional References

- Section 4.1.3, SPECIAL_NAMES section in Chapter 4
- Compaq COBOL User Manual sections on using command line arguments and environment variables

Examples

In the example results, the character "s" represents a space. The examples assume a maximum screen size of 24 lines. They also assume the following Environment and Data Division entries:

    SPECIAL-NAMES.
        LINE-PRINTER IS ERR-REPORTER.

    01  ITEMA PIC X(6) VALUE "ITEMS ".
    01  ITEMB PIC X(8) VALUE "VALID".
    01  ITEMC PIC X(5) VALUE "TODAY".
    01  ITEMD PIC 99 VALUE 2.
    01  ITEME PIC X(10) VALUE "MONDAY".

                                                        RESULT:

    1.  DISPLAY ITEMC.                                  TODAY

    2.  DISPLAY ITEMD UPON ERR-REPORTER.                02

    3.  DISPLAY ITEMD ITEMA "ARE" ITEMB.                02ITEMSsAREVALIDsss

    4.  DISPLAY ITEMD  SPACE ITEMA "AREs" ITEMB.        02sITEMSsAREsVALIDsss

    5.  DISPLAY ITEMC "sISs" NO ADVANCING.
        DISPLAY ITEME.
        DISPLAY ITEME.
                                                        TODAYsISsMONDAYssss
                                                        MONDAYssss

The following program uses Compaq DISPLAY extensions (Format 2).

    IDENTIFICATION DIVISION.
    PROGRAM-ID. EXAMPLES.
    ENVIRONMENT DIVISION.
    DATA DIVISION.
    WORKING-STORAGE SECTION.
    01 ITEMF        COMP-1.
    01 ITEMG        COMP-2 .
    01 ITEMH        PIC S9(9) COMP VALUE IS 123456789.
    01 ITEMI        PIC S9(9) COMP-3.
    PROCEDURE DIVISION.
    01.
        MOVE 101.000000000 TO  ITEMF.
        MOVE .109999999 TO ITEMG.
        MOVE  123456789 TO ITEMI.
        DISPLAY
            ITEMF   WITH CONVERSION LINE PLUS
            ITEMG   WITH CONVERSION LINE PLUS
            ITEMH   WITH CONVERSION LINE PLUS
            ITEMI   WITH CONVERSION LINE PLUS
            .
            .
            .

The Compaq COBOL User Manual contains additional examples using Compaq extensions to the DISPLAY statement. Refer to the chapters that describe screen handling, command line variables, environment variables and logicals.

Previous | Next | Contents | Index