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

  1. 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

  1. 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)

  1. 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.)
  2. 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.)
  3. The CONVERSION phrase or the /DISPLAY_FORMATTED (OpenVMS Alpha) qualifier displays nonnumeric items and numeric edited items without change.
  4. The CONVERSION phrase or the /DISPLAY_FORMATTED (OpenVMS Alpha) qualifier displays non-floating-point numeric items according to the following rules:
  5. On OpenVMS, the CONVERSION phrase or /DISPLAY_FORMATTED (OpenVMS Alpha), or -display_formatted (on Tru64 UNIX), displays floating-point items as follows:
  1. The CONVERSION phrase or the /DISPLAY_FORMATTED qualifier (on OpenVMS Alpha) or -display_formatted (on Tru64 UNIX) displays floating-point items as follows:

Format 1

  1. The DISPLAY statement transfers data from each src-item (in its order of appearance in the statement) to output-dest.
  2. No editing or conversion occurs during DISPLAY execution unless there is an applicable WITH CONVERSION phrase.
  3. If src-item is a figurative constant, only one occurrence is displayed.
  4. When there is more than one src-item, sending item size is the sum of the src-item sizes.
  5. If there is no UPON phrase, the DISPLAY statement transfers data to the default system output device.
  6. 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.
  7. If DECIMAL POINT IS COMMA is specified, comma replacement occurs upon display.

Format 2

  1. 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.
  2. 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)

  1. The LINE NUMBER phrase positions the cursor on a specific line of the video screen prior to displaying.
  2. If the LINE NUMBER phrase does not appear but the COLUMN NUMBER phrase does, then data is displayed to the current specified column position.
  3. If line-num or the value of line-id is greater than the bottommost line position of the current screen, program results are undefined.
  4. If you use line-id without its PLUS option, the line position is the value of line-id.
  5. If you use line-id with its PLUS option, the line position is the sum of plus-num and the value of line-id.
  6. 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.
  7. If you use the PLUS option, but you do not specify plus-num, then PLUS 1 is implied.
  8. Data output results are undefined if your program generates a value for line-id that is one of the following:

COLUMN NUMBER Phrase (Format 2)

  1. The COLUMN NUMBER phrase positions the cursor on a specific column of the video screen.
  2. 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.
  3. If you use column-id without its PLUS option, the column position is the value of column-id.
  4. If you use column-id with its PLUS option, the column position is the sum of plus-num and the value of column-id.
  5. 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.
  6. If you use the PLUS option, but do not specify plus-num, PLUS 1 is implied.
  7. Data output results are undefined if the program generates a value for column position that is one of the following:

LINE NUMBER and COLUMN NUMBER Phrases (Format 3)

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

ERASE Phrase (Format 2)

  1. The ERASE phrase erases all, or part, of a line (or screen) before displaying data. You must specify SCREEN or LINE.
  2. 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).
  3. If you do not use its TO END option, the ERASE phrase erases the entire line (or screen).

BELL Phrase (Format 2)

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

UNDERLINED Phrase (Format 2)

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

BOLD Phrase (Format 2)

  1. 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:

BLINKING Phrase (Format 2)

  1. 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:

REVERSED Phrase (Format 2)

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

Formats 4, 5, and 6

  1. 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.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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

  1. Format 2 is a Compaq extension to the standard COBOL use of the DISPLAY statement.
  2. 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.
  3. The UNDERLINED, BOLD, BLINKING, and REVERSED character attributes are not available on VT100 terminals without the advanced video option.
  4. 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.
  5. 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.

  6. 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

  1. 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

  1. 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:
  2. 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

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