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

  1. Release all five names of rel and print the count. How many records does the output file hold?
  2. Move the MOVE "zzz" TO SORT-REC of late into FEED, before the other two releases. Is zzz in the file now?
  3. Change the loop of ret to keep the second name as well. Which field does it need?
  4. 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.

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

  2. What does RETURN place in the SD area?

    Answer

    The next record in sorted order

    The loop printed the four names in ascending order.

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

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

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

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

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

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

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

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