RELEASE and RETURN
The two verbs of the previous lesson deserve their own page, because they are the only place in COBOL where a record enters a sort and the only place where one leaves it. Both work on the record area of the SD entry, and both are easy to use one time too many.
RELEASE: a record into the sort
RELEASE takes the record in the SD area and hands a copy of it to the sort. The program may use the area for the next record at once, which is how a table in memory, with no input file at all, feeds a sort:
IDENTIFICATION DIVISION.
PROGRAM-ID. REL.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT SORT-F ASSIGN TO "sortw.dat"
FILE STATUS IS WS-SORT-ST.
SELECT OUT-F ASSIGN TO "picked.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-OUT-ST.
DATA DIVISION.
FILE SECTION.
SD SORT-F.
01 SORT-REC.
05 S-NAME PIC X(8).
05 S-AMOUNT PIC 9(5).
FD OUT-F.
01 OUT-REC.
05 OUT-NAME PIC X(8).
05 OUT-AMOUNT PIC 9(5).
WORKING-STORAGE SECTION.
01 WS-SORT-ST PIC XX.
01 WS-OUT-ST PIC XX.
01 WS-RELEASED PIC 9(2) VALUE 0.
01 WS-SKIPPED PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
SORT SORT-F
ON ASCENDING KEY S-AMOUNT
INPUT PROCEDURE IS FEED
GIVING OUT-F.
DISPLAY "sort " WS-SORT-ST.
DISPLAY "released " WS-RELEASED " skipped " WS-SKIPPED.
OPEN INPUT OUT-F.
PERFORM UNTIL WS-OUT-ST = "10"
READ OUT-F
AT END MOVE "10" TO WS-OUT-ST
NOT AT END DISPLAY OUT-NAME " " OUT-AMOUNT
END-READ
END-PERFORM.
CLOSE OUT-F.
STOP RUN.
RELEASE-ONE.
IF S-AMOUNT >= 100
RELEASE SORT-REC
ADD 1 TO WS-RELEASED
ELSE
ADD 1 TO WS-SKIPPED
END-IF.
FEED SECTION.
MOVE "pear" TO S-NAME.
MOVE 300 TO S-AMOUNT.
PERFORM RELEASE-ONE.
MOVE "fig" TO S-NAME.
MOVE 40 TO S-AMOUNT.
PERFORM RELEASE-ONE.
MOVE "apple" TO S-NAME.
MOVE 250 TO S-AMOUNT.
PERFORM RELEASE-ONE.
MOVE "date" TO S-NAME.
MOVE 75 TO S-AMOUNT.
PERFORM RELEASE-ONE.
MOVE "kiwi" TO S-NAME.
MOVE 500 TO S-AMOUNT.
PERFORM RELEASE-ONE.
cobc -x -free -Wall -o rel rel.cob
./rel
sort 00
released 03 skipped 02
apple 00250
pear 00300
kiwi 00500
Five names went through one eight-byte field and three records came out, in amount order. Each RELEASE copied the area, so the later MOVEs did not change what the sort had already taken. The output is a file because the sort still has a GIVING clause; a sort with an output procedure instead of it would return these records to the program.
The helper paragraph sits before the section on purpose. A paragraph that follows the last statement of a section is still inside the program, and a first version of this page with the helper after FEED fell through into it and released one extra record: the counter said four released while the table held five names. The fall-through lesson is the full story of that bug.
RETURN and the record area
RETURN is the other direction. Each call puts the next sorted record into the SD area, and the program copies out what it wants to keep. A value it reads into a field of its own stays; the area itself belongs to the sort:
IDENTIFICATION DIVISION.
PROGRAM-ID. RET.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IN-F ASSIGN TO "names.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-IN-ST.
SELECT SORT-F ASSIGN TO "sortw2.dat"
FILE STATUS IS WS-SORT-ST.
DATA DIVISION.
FILE SECTION.
FD IN-F.
01 IN-REC.
05 IN-NAME PIC X(8).
05 IN-AMOUNT PIC 9(5).
SD SORT-F.
01 SORT-REC.
05 S-NAME PIC X(8).
05 S-AMOUNT PIC 9(5).
WORKING-STORAGE SECTION.
01 WS-IN-ST PIC XX.
01 WS-SORT-ST PIC XX.
01 WS-EOF PIC X VALUE "N".
01 WS-N PIC 9(2) VALUE 0.
01 WS-TOTAL PIC 9(7) VALUE 0.
01 WS-FIRST PIC X(8) VALUE SPACES.
01 WS-LAST PIC X(8) VALUE SPACES.
PROCEDURE DIVISION.
OPEN OUTPUT IN-F.
MOVE "pear" TO IN-NAME.
MOVE 300 TO IN-AMOUNT.
WRITE IN-REC.
MOVE "fig" TO IN-NAME.
MOVE 40 TO IN-AMOUNT.
WRITE IN-REC.
MOVE "apple" TO IN-NAME.
MOVE 250 TO IN-AMOUNT.
WRITE IN-REC.
MOVE "date" TO IN-NAME.
MOVE 75 TO IN-AMOUNT.
WRITE IN-REC.
CLOSE IN-F.
SORT SORT-F
ON ASCENDING KEY S-NAME
USING IN-F
OUTPUT PROCEDURE IS SHOW-OUT.
DISPLAY "sort " WS-SORT-ST.
DISPLAY "returned " WS-N " total " WS-TOTAL.
DISPLAY "first " WS-FIRST " last " WS-LAST.
DISPLAY "area holds " S-NAME " " S-AMOUNT.
STOP RUN.
SHOW-OUT SECTION.
PERFORM UNTIL WS-EOF = "Y"
RETURN SORT-F
AT END MOVE "Y" TO WS-EOF
NOT AT END
ADD 1 TO WS-N
ADD S-AMOUNT TO WS-TOTAL
IF WS-N = 1
MOVE S-NAME TO WS-FIRST
END-IF
MOVE S-NAME TO WS-LAST
DISPLAY WS-N ". " S-NAME " " S-AMOUNT
END-RETURN
END-PERFORM.
cobc -x -free -Wall -o ret ret.cob
./ret
01. apple 00250
02. date 00075
03. fig 00040
04. pear 00300
sort 00
returned 04 total 0000665
first apple last pear
area holds pear 00300
The three lines after the sort are the proof of the copy. The first name survived in WS-FIRST, the last in WS-LAST, and the SD area holds the fourth record because that was the last one returned. A program that kept the first name by leaving it in S-NAME would have reported pear as the first name of the file.
The loop ends on its own flag rather than on the file status, because a sort is not a file: RETURN has no AT END status to leave in WS-SORT-ST. The status of the sort itself is 00, and the counters of the step are the three fields the program keeps.
A RELEASE after the sort
A RELEASE belongs inside an input procedure: after the SORT statement has finished there is no sort left to take the record. GnuCOBOL builds this program and reports status 00 for the late release, and the record is not in the output:
IDENTIFICATION DIVISION.
PROGRAM-ID. LATE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT SORT-F ASSIGN TO "sortw3.dat"
FILE STATUS IS WS-SORT-ST.
SELECT OUT-F ASSIGN TO "late.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-OUT-ST.
DATA DIVISION.
FILE SECTION.
SD SORT-F.
01 SORT-REC PIC X(8).
FD OUT-F.
01 OUT-REC PIC X(8).
WORKING-STORAGE SECTION.
01 WS-SORT-ST PIC XX.
01 WS-OUT-ST PIC XX.
PROCEDURE DIVISION.
SORT SORT-F
ON ASCENDING KEY SORT-REC
INPUT PROCEDURE IS FEED
GIVING OUT-F.
MOVE "zzz" TO SORT-REC.
RELEASE SORT-REC.
DISPLAY "release after sort " WS-SORT-ST.
OPEN INPUT OUT-F.
PERFORM UNTIL WS-OUT-ST = "10"
READ OUT-F
AT END MOVE "10" TO WS-OUT-ST
NOT AT END DISPLAY "in the file: " OUT-REC
END-READ
END-PERFORM.
CLOSE OUT-F.
STOP RUN.
FEED SECTION.
MOVE "aa" TO SORT-REC.
RELEASE SORT-REC.
MOVE "mm" TO SORT-REC.
RELEASE SORT-REC.
cobc -x -free -Wall -o late late.cob
./late
release after sort 00
in the file: aa
in the file: mm
Two records in the file, none of them zzz, and a status of 00 for the release that was too late. This is the worst shape a batch bug takes: no error, no warning, and one record missing from a report that looks right. Put the RELEASE where the sort runs, and check the count of released records against the count of records the report holds.
Exercises
- Release all five names of rel and print the count. How many records does the output file hold?
- Move the MOVE "zzz" TO SORT-REC of late into FEED, before the other two releases. Is zzz in the file now?
- Change the loop of ret to keep the second name as well. Which field does it need?
- Print WS-SORT-ST after each RETURN of ret. Which value does it hold during the loop?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does RELEASE do with the record in the SD area?
Answer
It hands the sort a copy, so the area can be reused at once
Five names went through one field and three released records came out unchanged.
-
What does RETURN place in the SD area?
Answer
The next record in sorted order
The loop printed the four names in ascending order.
-
What does the SD area hold after the RETURN loop ends?
Answer
The last record returned
The program printed area holds pear 00300 after four returns.
-
What did the late RELEASE print?
Answer
Status 00, and the record was not in the output
The run printed release after sort 00 and the file held only aa and mm.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC X(4) VALUE "aaaa". 01 W-B PIC X(4) VALUE SPACES. 01 W-C PIC X(4) VALUE SPACES. PROCEDURE DIVISION. MOVE W-A TO W-B. MOVE "bbbb" TO W-A. MOVE W-B TO W-C. DISPLAY W-C " " W-A. STOP RUN.Answer
aaaa bbbb
The copy into W-B kept the old value, which is what a RELEASE copy does.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9(2) VALUE 0. 01 W-T PIC 9(5) VALUE 0. 01 W-I PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM VARYING W-I FROM 1 BY 1 UNTIL W-I IS GREATER THAN 4 ADD W-I TO W-T ADD 1 TO W-N END-PERFORM. DISPLAY W-N " " W-T. STOP RUN.Answer
04 00010
Four passes count four records and add 1 + 2 + 3 + 4.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 250. 01 W-B PIC 9(3) VALUE 40. 01 W-BIG PIC 9(3) VALUE 0. PROCEDURE DIVISION. IF W-A IS GREATER THAN W-B MOVE W-A TO W-BIG ELSE MOVE W-B TO W-BIG END-IF. DISPLAY W-BIG. STOP RUN.Answer
250
The larger of the two amounts is kept, which is the comparison of a sort.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-E PIC X VALUE "N". 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM UNTIL W-E = "Y" ADD 1 TO W-N IF W-N = 3 MOVE "Y" TO W-E END-IF END-PERFORM. DISPLAY W-N " " W-E. STOP RUN.Answer
3 Y
The loop ends on its own flag on the third pass, the shape the RETURN loop uses.
-
Why does the RETURN loop end on a flag of its own instead of the file status?
Answer
A sort is not a file, and RETURN leaves no end status in the sort status field
The sort status stayed 00 for the whole loop and the counters had to end it.
-
A report shows one record fewer than the count of released records. Where does the search start?
Answer
At a RELEASE outside the input procedure, which silently loses its record
The late program released a record after the sort, got status 00 and lost 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