Messages, exit codes and logs
A batch job is read by a person at a terminal and by a scheduler that never looks at the screen. The three things this lesson builds are what both of them need: a line of log with the time and the severity, a message that says what went wrong in words, and an exit status that says it in a number.
A log line on standard error
Standard output is the report and standard error is the log, and COBOL can write to both. UPON STDERR sends a DISPLAY to the second, and the timestamp is the twenty-one characters of CURRENT-DATE cut and joined:
IDENTIFICATION DIVISION.
PROGRAM-ID. MSG1.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-NOW PIC X(21).
01 WS-STAMP PIC X(19).
PROCEDURE DIVISION.
MOVE FUNCTION CURRENT-DATE TO WS-NOW.
STRING WS-NOW(1:4) "-" WS-NOW(5:2) "-" WS-NOW(7:2) " "
WS-NOW(9:2) ":" WS-NOW(11:2) ":" WS-NOW(13:2)
INTO WS-STAMP
END-STRING.
DISPLAY WS-STAMP " INFO job started" UPON STDERR.
DISPLAY WS-STAMP " ERROR input file missing" UPON STDERR.
DISPLAY "on standard output".
STOP RUN.
cobc -x -free -Wall -o msg1 msg1.cob
./msg1 > out.txt 2> err.txt
cat out.txt
cat err.txt
on standard output
2026-11-18 11:18:54 INFO job started
2026-11-18 11:18:54 ERROR input file missing
The first line of the output is the file of standard output and the other two are the file of standard error, shown in the order the two cat commands ran. A report written to standard output can be redirected into a file and printed while the log of the same run goes to the terminal or to the log of the scheduler.
The timestamp is built from the date and time of the run, so two log lines of one job carry the same second and two jobs of one night do not. A line without a time is a line that cannot be placed in the order of events, and that is the first thing an operator needs.
A message file
A message written into the program is a message that needs a new build to change a word. The shops that care about the words keep them in a file of code and text, and the program looks a code up:
IDENTIFICATION DIVISION.
PROGRAM-ID. MSG2.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MSG-F ASSIGN TO "messages.txt"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-ST.
DATA DIVISION.
FILE SECTION.
FD MSG-F.
01 MSG-REC.
05 MSG-CODE PIC 9(2).
05 MSG-TEXT PIC X(30).
WORKING-STORAGE SECTION.
01 WS-ST PIC XX.
01 WS-EOF PIC X VALUE "N".
01 WS-WANT PIC 9(2).
01 WS-FOUND PIC X VALUE "N".
01 WS-LINE PIC X(40).
PROCEDURE DIVISION.
OPEN OUTPUT MSG-F.
MOVE 04 TO MSG-CODE.
MOVE "bad version of the interface" TO MSG-TEXT.
WRITE MSG-REC.
MOVE 12 TO MSG-CODE.
MOVE "input file is not there" TO MSG-TEXT.
WRITE MSG-REC.
MOVE 35 TO MSG-CODE.
MOVE "file not found by the open" TO MSG-TEXT.
WRITE MSG-REC.
CLOSE MSG-F.
MOVE 12 TO WS-WANT.
PERFORM LOOKUP.
MOVE 99 TO WS-WANT.
PERFORM LOOKUP.
DISPLAY "return " RETURN-CODE.
STOP RUN.
LOOKUP.
MOVE "N" TO WS-FOUND.
MOVE SPACES TO WS-LINE.
OPEN INPUT MSG-F.
MOVE "N" TO WS-EOF.
PERFORM UNTIL WS-EOF = "Y"
READ MSG-F
AT END MOVE "Y" TO WS-EOF
NOT AT END
IF MSG-CODE = WS-WANT
MOVE "Y" TO WS-FOUND
STRING WS-WANT " " MSG-TEXT DELIMITED BY SIZE
INTO WS-LINE
END-STRING
END-IF
END-READ
END-PERFORM.
CLOSE MSG-F.
IF WS-FOUND = "Y"
DISPLAY "code " FUNCTION TRIM(WS-LINE)
ELSE
DISPLAY "code " WS-WANT " unknown message"
MOVE 8 TO RETURN-CODE
END-IF.
cobc -x -free -Wall -o msg2 msg2.cob
./msg2
echo $?
code 12 input file is not there
code 99 unknown message
return +000000008
8
The first code was found and printed with its text. The second was not in the file, and the program did two things about it: printed a line that says the code is unknown, and set the exit status of the step. A job that reads a message file is a job whose operator can fix a wording without a compiler, and the default branch is what stops a new code from being silent.
The look-up rereads the whole file for each code, which is right for three messages and wrong for three hundred. A real message table is read once into an OCCURS table and searched with SEARCH ALL, the subject of the SEARCH ALL lesson.
The exit status
Three numbers came out of these two runs: 0 from the log program, 8 from the message program, and the same 8 in the shell. The convention of a batch step is the one the file errors lesson set: 0 for a step that did its work, 4 or 8 for a job whose input was wrong and can be fixed and run again, 12 for a job that needs a person.
RETURN-CODE is the register that carries it, and the last line of the program is where a shop decides what it means. STOP RUN hands the register to the shell, so a program that sets it in a helper paragraph and forgets it in another leaves the value of the previous run. The lesson on RETURNING and RETURN-CODE is the full story of the register.
Exercises
- Add a third line to the log program with the level WARN and read the difference between the two files again.
- Give the message program a code of three digits and a message file to match.
- Make the unknown message set 12 instead of 8 and read the exit status.
- Print the run date of the message program before its first line, using the CURRENT-DATE of the log program.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How does a COBOL program write to standard error?
Answer
DISPLAY ... UPON STDERR
The two log lines went to err.txt and the report line to out.txt.
-
Why does a log line carry a timestamp?
Answer
It is how an operator puts the events of a night in order
The program built its stamp from CURRENT-DATE for that reason.
-
What does the message program do with a code that is not in the file?
Answer
It prints an unknown-message line and sets the exit status
Code 99 printed its line and the shell saw 8.
-
Which register becomes the exit status of the step?
Answer
RETURN-CODE
The program printed return +000000008 and the shell printed 8.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-NOW PIC X(21) VALUE "2026111810540609+0000". 01 W-STAMP PIC X(10). PROCEDURE DIVISION. STRING W-NOW(1:4) "-" W-NOW(5:2) "-" W-NOW(7:2) INTO W-STAMP END-STRING. DISPLAY W-STAMP. STOP RUN.Answer
2026-11-18
The year, two dashes, the month and the day fill the ten characters.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9(2) VALUE 12. 01 W-T PIC X(20) VALUE "found". PROCEDURE DIVISION. IF W-C = 12 DISPLAY W-C " " W-T ELSE DISPLAY "unknown" END-IF. STOP RUN.Answer
12 found
The code matches the branch that prints the message.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-R PIC 9(2) VALUE 0. PROCEDURE DIVISION. MOVE 8 TO W-R. IF W-R IS GREATER THAN 4 ADD 4 TO W-R END-IF. DISPLAY W-R. STOP RUN.Answer
12
Eight is above four, so four is added to it.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-T PIC X(10) VALUE " done ". PROCEDURE DIVISION. DISPLAY "[" FUNCTION TRIM(W-T) "]". STOP RUN.Answer
[done]
TRIM removes the spaces on both sides of the word.
-
Why is the message of a job kept in a file rather than in the program?
Answer
A wording can change without a rebuild, and a new code has a place to live
The program looked its texts up by code and printed the unknown branch for 99.
-
What is wrong with the look-up of this page for a large message table?
Answer
It rereads the whole file for every code
The page says a real table is read once into an OCCURS table and searched.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev