COBOL Tutorial

COBOL DISPLAY UPON Clause - Quick Reference

Progress0 of 0 lessons

Overview

The UPON clause in DISPLAY statements specifies the destination or device where output should be sent. It provides control over where program output is directed, allowing output to specific devices, files, or destinations.

Purpose and Usage

Destination control - Specify where output should be sent
Device output - Direct output to specific devices
File output - Send output to files
Multi-destination - Output to multiple destinations
System integration - Interface with system devices

Output Destination Concept

Program Output → DISPLAY UPON → Destination

Destinations: Console, Printer, File, Device

Without UPON: Default destination (usually console)

UPON provides destination control

UPON clause controls where DISPLAY output is directed.

Syntax

The UPON clause follows specific syntax patterns within DISPLAY statements and can specify various types of destinations.

Basic Syntax

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
* Basic DISPLAY UPON syntax
DISPLAY data UPON destination
 
* With literal data
DISPLAY "Hello World" UPON CONSOLE
 
* With variables
DISPLAY WS-MESSAGE UPON PRINTER
 
* With multiple items
DISPLAY WS-NAME " " WS-VALUE UPON FILE-NAME
 
* With figurative constants
DISPLAY "Error message" UPON SYSERR
 
* Complete example
DISPLAY "Processing complete" UPON CONSOLE
DISPLAY WS-RESULT UPON PRINTER
DISPLAY WS-LOG-MESSAGE UPON "LOG.TXT"

UPON can specify various destinations including devices, files, and figurative constants.

Common UPON Destinations

Destination	Purpose	Example
CONSOLE	Console/terminal output	UPON CONSOLE
PRINTER	System printer	UPON PRINTER
SYSERR	Error output	UPON SYSERR
SYSOUT	Standard output	UPON SYSOUT
File name	File output	UPON "OUTPUT.TXT"

Figurative Constants for UPON

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
* Standard figurative constants
DISPLAY "Message" UPON CONSOLE      * Console output
DISPLAY "Report" UPON PRINTER       * Printer output
DISPLAY "Error" UPON SYSERR         * Error output
DISPLAY "Output" UPON SYSOUT        * Standard output
 
* Mainframe specific
DISPLAY "Data" UPON SYSIN           * Standard input (rare)
DISPLAY "Log" UPON SYSPRINT         * System printer
DISPLAY "Debug" UPON SYSLIST        * System listing
 
* Device-specific
DISPLAY "Alert" UPON TERMINAL       * Terminal output
DISPLAY "Status" UPON MONITOR       * Monitor output

Figurative constants provide standard device references for UPON.

Practical Examples

These examples demonstrate how to use the DISPLAY UPON clause effectively in different output scenarios.

Basic Device Output

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
IDENTIFICATION DIVISION.
PROGRAM-ID. BASIC-DISPLAY-UPON.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-MESSAGE         PIC X(50) VALUE "Hello from COBOL program".
01  WS-ERROR-MESSAGE   PIC X(50) VALUE "An error occurred".
01  WS-STATUS-MESSAGE  PIC X(50) VALUE "Processing complete".
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Display to console
    DISPLAY "Starting program..." UPON CONSOLE
    DISPLAY WS-MESSAGE UPON CONSOLE
    
    * Display error to error output
    DISPLAY WS-ERROR-MESSAGE UPON SYSERR
    
    * Display status to standard output
    DISPLAY WS-STATUS-MESSAGE UPON SYSOUT
    
    * Display to printer
    DISPLAY "Program completed successfully" UPON PRINTER
    
    STOP RUN.

Basic device output using different UPON destinations for various types of messages.

File Output with UPON

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
IDENTIFICATION DIVISION.
PROGRAM-ID. FILE-OUTPUT-UPON.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-LOG-MESSAGE     PIC X(100).
01  WS-TIMESTAMP       PIC X(26).
01  WS-PROCESS-COUNT   PIC 9(4) VALUE 0.
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Initialize log message
    MOVE "Program started at " TO WS-LOG-MESSAGE
    MOVE FUNCTION CURRENT-DATE TO WS-TIMESTAMP
    STRING WS-LOG-MESSAGE DELIMITED BY SIZE
           WS-TIMESTAMP DELIMITED BY SIZE
           INTO WS-LOG-MESSAGE
    
    * Write to log file
    DISPLAY WS-LOG-MESSAGE UPON "PROGRAM.LOG"
    
    * Process some data
    PERFORM PROCESS-DATA
    
    * Write completion message
    MOVE "Program completed successfully" TO WS-LOG-MESSAGE
    DISPLAY WS-LOG-MESSAGE UPON "PROGRAM.LOG"
    
    STOP RUN.
 
PROCESS-DATA.
    ADD 1 TO WS-PROCESS-COUNT
    MOVE "Processing record " TO WS-LOG-MESSAGE
    STRING WS-LOG-MESSAGE DELIMITED BY SIZE
           WS-PROCESS-COUNT DELIMITED BY SIZE
           INTO WS-LOG-MESSAGE
    DISPLAY WS-LOG-MESSAGE UPON "PROGRAM.LOG".

File output using UPON to write log messages to a file.

Multi-Destination Output

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
IDENTIFICATION DIVISION.
PROGRAM-ID. MULTI-DESTINATION-OUTPUT.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-USER-MESSAGE    PIC X(50) VALUE "Welcome to the system".
01  WS-DEBUG-MESSAGE   PIC X(50) VALUE "Debug information".
01  WS-ERROR-MESSAGE   PIC X(50) VALUE "System error detected".
01  WS-REPORT-DATA     PIC X(50) VALUE "Report data line".
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Send user message to console
    DISPLAY WS-USER-MESSAGE UPON CONSOLE
    
    * Send debug info to debug file
    DISPLAY WS-DEBUG-MESSAGE UPON "DEBUG.LOG"
    
    * Send error to error output
    DISPLAY WS-ERROR-MESSAGE UPON SYSERR
    
    * Send report data to printer
    DISPLAY WS-REPORT-DATA UPON PRINTER
    
    * Send summary to both console and file
    DISPLAY "Processing summary" UPON CONSOLE
    DISPLAY "Processing summary" UPON "SUMMARY.TXT"
    
    STOP RUN.

Multi-destination output sending different types of messages to appropriate destinations.

Error Handling with UPON

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
IDENTIFICATION DIVISION.
PROGRAM-ID. ERROR-HANDLING-UPON.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-ERROR-CODE      PIC X(2).
01  WS-ERROR-MESSAGE   PIC X(100).
01  WS-USER-MESSAGE    PIC X(50).
01  WS-LOG-ENTRY       PIC X(150).
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Simulate error condition
    MOVE "01" TO WS-ERROR-CODE
    
    * Handle different error types
    EVALUATE WS-ERROR-CODE
        WHEN "01"
            MOVE "File not found" TO WS-ERROR-MESSAGE
            MOVE "Please check file path" TO WS-USER-MESSAGE
        WHEN "02"
            MOVE "Invalid data format" TO WS-ERROR-MESSAGE
            MOVE "Please verify input data" TO WS-USER-MESSAGE
        WHEN OTHER
            MOVE "Unknown error occurred" TO WS-ERROR-MESSAGE
            MOVE "Contact system administrator" TO WS-USER-MESSAGE
    END-EVALUATE
    
    * Send user-friendly message to console
    DISPLAY WS-USER-MESSAGE UPON CONSOLE
    
    * Send detailed error to error output
    DISPLAY WS-ERROR-MESSAGE UPON SYSERR
    
    * Log error details to file
    MOVE "Error occurred during processing" TO WS-LOG-ENTRY
    DISPLAY WS-LOG-ENTRY UPON "ERROR.LOG"
    DISPLAY WS-ERROR-MESSAGE UPON "ERROR.LOG"
    
    STOP RUN.

Error handling using UPON to direct different types of error messages to appropriate destinations.

Best Practices and Considerations

Understanding best practices ensures proper output handling and system integration.

DISPLAY UPON Best Practices

Use appropriate destinations - Match message type to destination
Handle errors gracefully - Use SYSERR for error messages
Log important events - Use files for logging
Consider user experience - Use CONSOLE for user messages
Test destination availability - Ensure destinations are accessible

Common Pitfalls to Avoid

Pitfall	Problem	Solution
Wrong destination	Messages sent to wrong place	Use appropriate destinations
Unavailable device	Output failures	Check device availability
File permission issues	File output failures	Check file permissions
Inconsistent logging	Poor debugging	Use consistent logging
Performance issues	Slow output	Optimize output frequency

Platform-Specific Considerations

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
* Windows-specific destinations
DISPLAY "Message" UPON "CON"           * Console
DISPLAY "Output" UPON "PRN"            * Printer
DISPLAY "Error" UPON "NUL"             * Null device
 
* Unix/Linux-specific destinations
DISPLAY "Message" UPON "/dev/tty"      * Terminal
DISPLAY "Output" UPON "/dev/lp0"       * Printer
DISPLAY "Error" UPON "/dev/stderr"     * Error output
 
* Mainframe-specific destinations
DISPLAY "Message" UPON SYSOUT          * System output
DISPLAY "Report" UPON SYSPRINT         * System printer
DISPLAY "Error" UPON SYSERR            * Error output
 
* Cross-platform approach
DISPLAY "Message" UPON CONSOLE         * Portable console output
DISPLAY "Error" UPON SYSERR            * Portable error output

Different platforms may have different destination names and capabilities.

DISPLAY UPON Clause Quick Reference

Usage	Syntax	Example
Console output	DISPLAY data UPON CONSOLE	DISPLAY "Hello" UPON CONSOLE
Printer output	DISPLAY data UPON PRINTER	DISPLAY "Report" UPON PRINTER
Error output	DISPLAY data UPON SYSERR	DISPLAY "Error" UPON SYSERR
File output	DISPLAY data UPON "filename"	DISPLAY "Log" UPON "LOG.TXT"
Standard output	DISPLAY data UPON SYSOUT	DISPLAY "Output" UPON SYSOUT

Test Your Knowledge

1. What is the primary purpose of the UPON clause in DISPLAY statements?

To specify input sources
To specify output destinations or devices
To format data
To validate input

2. Which of the following is a valid UPON destination?

PRINTER
CONSOLE
FILE
All of the above

3. What happens if you don't specify UPON in a DISPLAY statement?

The program crashes
Output goes to the default destination (usually console)
Output is discarded
Output goes to a file

4. How does UPON differ from regular DISPLAY?

There is no difference
UPON specifies the destination, regular DISPLAY uses default
UPON is only for input
UPON is deprecated

5. When is DISPLAY UPON most useful?

When you need to send output to specific devices
When you need to format data
When you need to validate input
When you need to read files

Frequently Asked Questions

Related Concepts

DISPLAY Statement

Understanding the DISPLAY statement for output operations.

WRITE Statement

WRITE statement for file output operations.

File Output

File output and processing techniques.

Error Handling

Error handling and output strategies.

Device I/O

Device input/output operations.

COMPUTE ROUNDED EJECT

COBOL Tutorial

COBOL DISPLAY UPON Clause - Quick Reference

Overview

Purpose and Usage

Output Destination Concept

Syntax

Basic Syntax

Common UPON Destinations

Figurative Constants for UPON

Practical Examples

Basic Device Output

File Output with UPON

Multi-Destination Output

Error Handling with UPON

Best Practices and Considerations

DISPLAY UPON Best Practices

Common Pitfalls to Avoid

Platform-Specific Considerations

DISPLAY UPON Clause Quick Reference

Test Your Knowledge

Frequently Asked Questions

What is the difference between DISPLAY UPON and WRITE statements?

How do you handle errors when using DISPLAY UPON?

Can you use variables with DISPLAY UPON for dynamic destinations?

What are the performance implications of using DISPLAY UPON?

How does DISPLAY UPON work with different operating systems?

Related Concepts

DISPLAY Statement

WRITE Statement

File Output

Error Handling

Device I/O

Related Pages