ACCEPT FROM ENVIRONMENT and RETURN-CODE

A batch step passes its settings two ways: on the command line, which the previous lesson read, and in the environment, which is what a scheduler uses for the values that do not change from run to run. COBOL reads the second with ACCEPT FROM ENVIRONMENT, and this lesson is mostly about the two ways that statement surprises people.

ACCEPT FROM ENVIRONMENT

The statement names the variable as a literal and copies its value into the receiving field, padded with spaces or cut to the length of the field:

IDENTIFICATION DIVISION. PROGRAM-ID. ENVDEMO. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-NAIVE PIC X(10) VALUE "prod". 01 WS-MODE PIC X(10) VALUE SPACES. 01 WS-HOME PIC X(40). 01 WS-PORT PIC 9(5) VALUE 8080. 01 WS-TEXT PIC X(6). PROCEDURE DIVISION. ACCEPT WS-NAIVE FROM ENVIRONMENT "APP_MODE" DISPLAY "the VALUE clause: [" FUNCTION TRIM(WS-NAIVE) "]". ACCEPT WS-MODE FROM ENVIRONMENT "APP_MODE" IF WS-MODE = SPACES MOVE "prod" TO WS-MODE END-IF DISPLAY "with a default: [" FUNCTION TRIM(WS-MODE) "]". ACCEPT WS-HOME FROM ENVIRONMENT "HOME" DISPLAY "home " FUNCTION TRIM(WS-HOME). ACCEPT WS-TEXT FROM ENVIRONMENT "APP_PORT" IF WS-TEXT NOT = SPACES MOVE FUNCTION NUMVAL(WS-TEXT) TO WS-PORT END-IF DISPLAY "port " WS-PORT. IF WS-MODE = "test" MOVE 4 TO RETURN-CODE END-IF. STOP RUN.

Run with nothing set, the program prints an empty mode, which is not what the VALUE clause on WS-NAIVE says:

cobc -x -free -Wall -o env env.cob
./env
echo $?

the VALUE clause: []
with a default: [prod]
home /home/agent
port 08080
0

The VALUE clause does not survive

A failed ACCEPT FROM ENVIRONMENT does not leave the field alone. It clears it, so the VALUE "prod" that the program looked as if it had is gone by the time the first DISPLAY runs. This is the first surprise, and it is a real one: the natural reading of a VALUE clause is "this is what the field holds unless something changes it", and here something did.

The repair is in the program above: give the field VALUE SPACES, accept into it, and treat spaces as "not set", which is the second line of the output. A variable that is set to the empty string in the environment is therefore the same as a variable that is not set, and a setting where the empty value means something needs a second field or a different marker.

The length rule is the other half. A value longer than the field is cut, not rejected:

APP_MODE="a very long mode name" ./env

the VALUE clause: [a very lon]
with a default: [a very lon]
home /home/agent
port 08080
0

Ten characters is all the field can hold, and ten are what arrives. A mode read into PIC X(10) therefore compares unequal to a longer name, and a program that tests for "production" in a ten-character field never matches it. Give such a field the length of the longest value you would accept, and check the length in the step that sets it.

A number from the environment

The port is an environment variable that arrives as text. MOVE FUNCTION NUMVAL(WS-TEXT) TO WS-PORT turns it into a number, and that is exactly as safe as it looks:

APP_PORT=nine ./env

the VALUE clause: []
with a default: [prod]
home /home/agent
port 00000
0

NUMVAL of a word is zero, the move puts zero in the port, and the program carries on and exits successfully. A service that then listens on port zero is a failure two steps later, in a different program, with a message that does not mention APP_PORT. That is the shape of most configuration bugs: the value was wrong, the program did not say so, and the failure surfaced somewhere else.

A default and a validated port

The fixed program tests the text with FUNCTION TEST-NUMVAL before it converts it, and refuses the run with status 5 when the value is not a number:

IDENTIFICATION DIVISION. PROGRAM-ID. ENVFIX. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-MODE PIC X(10) VALUE SPACES. 01 WS-PORT PIC 9(5) VALUE 8080. 01 WS-TEXT PIC X(6). PROCEDURE DIVISION. ACCEPT WS-MODE FROM ENVIRONMENT "APP_MODE" IF WS-MODE = SPACES MOVE "prod" TO WS-MODE END-IF ACCEPT WS-TEXT FROM ENVIRONMENT "APP_PORT" IF WS-TEXT NOT = SPACES IF FUNCTION TEST-NUMVAL(WS-TEXT) = 0 MOVE FUNCTION NUMVAL(WS-TEXT) TO WS-PORT ELSE DISPLAY "bad APP_PORT: " FUNCTION TRIM(WS-TEXT) UPON STDERR MOVE 5 TO RETURN-CODE STOP RUN END-IF END-IF DISPLAY "mode " FUNCTION TRIM(WS-MODE) " port " WS-PORT. STOP RUN.

Three runs: the defaults, a full set of settings, and the bad port that used to pass silently.

cobc -x -free -Wall -o envfix envfix.cob
./envfix
echo $?
APP_MODE=test APP_PORT=9090 ./envfix
echo $?
APP_PORT=nine ./envfix
echo $?

mode prod port 08080
0
mode test port 09090
0
bad APP_PORT: nine
5

The message names the variable and the value it got, which is what the person reading the job log needs. The status is what the scheduler needs. Both are cheap, and both are missing from the first version of the program.

RETURN-CODE and the shell

RETURN-CODE is a special register of the runtime: set it before the program ends and the process exits with that number. Everything from zero to 255 arrives in the shell unchanged, which is why the calculator of the previous lesson could use 2, 3 and 4 and this program uses 5.

Three rules make it reliable. Set it on every path that fails, and set it to zero on the path that succeeds, because a value left over from an earlier call in the same process stays there. Do not use it for a message: the message goes to standard error and the number says which kind of failure it was. And keep the numbers of one program stable, since a scheduler or a test script reads them.

The environment and the status are the two ends of the same contract. A step sets APP_MODE and APP_PORT, the program reads them, and the step reads the status to decide whether the next program may run. A program that treats a bad setting as success breaks the contract silently, and that is the bug this lesson is about.

Exercises

  1. Add a variable APP_DEBUG that turns on a second DISPLAY when it is set to 1. Which default does it need, and why is VALUE "0" not enough?
  2. Read APP_PORT into PIC X(2) and set it to 9090. What does TEST-NUMVAL say, and why?
  3. Make ENVFIX exit with 6 when HOME is empty. Which shell command shows the difference between 0 and 6 without reading the output?
  4. Run APP_MODE= ./envfix: an empty value. Which branch runs, and what does the output say?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does ACCEPT FROM ENVIRONMENT do when the variable is not set?

    Answer

    It clears the receiving field

    The VALUE clause was prod and the first line printed empty brackets.

  2. What happens to a value longer than the receiving field?

    Answer

    It is cut to the length of the field

    A twelve-character mode arrived in a ten-character field as a very lon.

  3. What does FUNCTION NUMVAL("nine") return?

    Answer

    Zero

    The port printed 00000, so NUMVAL gave zero and the program carried on.

  4. Which function tells you whether a string is a number before you convert it?

    Answer

    FUNCTION TEST-NUMVAL

    TEST-NUMVAL answers zero for a number and sent the bad port down the error path.

  5. What does this program print with APP_LIMIT unset? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 L PIC X(3) VALUE "999". PROCEDURE DIVISION. ACCEPT L FROM ENVIRONMENT "APP_LIMIT" IF L = SPACES MOVE "100" TO L END-IF DISPLAY L. STOP RUN.

    Answer

    100

    The failed ACCEPT clears the field, so the spaces test sets the default.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(2) VALUE 5. 01 B PIC 9(2) VALUE 2. PROCEDURE DIVISION. COMPUTE A = A - B DISPLAY A " " B. STOP RUN.

    Answer

    03 02

    A becomes 3 and B is untouched.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W PIC X(4) VALUE "ABCD". PROCEDURE DIVISION. INSPECT W CONVERTING "AB" TO "ba" DISPLAY W. STOP RUN.

    Answer

    baCD

    CONVERTING maps A to b and B to a, one character at a time.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-A PIC 9(2) OCCURS 3 TIMES. 01 I PIC 9(2). PROCEDURE DIVISION. MOVE 5 TO T-A(1) MOVE 6 TO T-A(2) PERFORM VARYING I FROM 1 BY 1 UNTIL I IS GREATER THAN 2 ADD 1 TO T-A(I) END-PERFORM. DISPLAY T-A(1) " " T-A(2). STOP RUN.

    Answer

    06 07

    Both entries are incremented once.

  9. Where does a batch program send the text of a bad setting?

    Answer

    Standard error, with a status that says which kind of failure it was

    The page sends bad APP_PORT to STDERR and sets status 5.

  10. Why set RETURN-CODE to zero on the successful path?

    Answer

    A value left from an earlier call in the same process would otherwise stay

    RETURN-CODE keeps its value until something changes it.

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