SORT and MERGE: input and output procedures

Eight transactions arrive in the order the branches keyed them, and the control-break report of this module needs them by branch, then account, with the largest amount first. SORT puts a whole file in that order with one statement.

Its procedures let the program choose what goes in and use what comes out, MERGE joins files that are already sorted, and the character set decides what “in order” means.

SORT with USING and GIVING orders a whole file by its keys

sortkeys.cob describes the records to sort in an SD entrySD entry: The sort description in the FILE SECTION: like an FD, but for the work file of a SORT or MERGE, with the record that names the key fields. The program never opens it., the sort description, and names its sort keyssort key: A field of the sort record named in the KEY phrase of SORT or MERGE, ASCENDING or DESCENDING. The leftmost key is the major key, and each later key decides only between records the earlier keys left equal. in the SORT statement. IBM’s reference gives the rule for several keys: “The leftmost data-name is the major key, the next data-name is the next most significant key, and so forth.” Here the branch is the major key, then the account, both ascending, and then the amount, descending. TX-SEQ, the last field, numbers the records in the order they arrived:

BR02AC0004C000001250001
BR01AC0002D000012500002
BR01AC0001C000250000003
BR02AC0004D000030000004
BR01AC0002D000012500005
BR03AC0006D000000999006
BR01AC0001D000004999007
BR03AC0007D000150000008

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SORTKEYS.
      * Sorts the day's transactions by branch and account, largest
      * amount first, keeping records with equal keys in the order
      * they arrived. TX-SEQ is the arrival number of each record.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT TXN-IN ASSIGN TO "TXNIN"
               ORGANIZATION IS LINE SEQUENTIAL.
           SELECT TXN-OUT ASSIGN TO "TXNOUT"
               ORGANIZATION IS LINE SEQUENTIAL.
           SELECT SORT-WORK ASSIGN TO "SORTWORK".
       DATA DIVISION.
       FILE SECTION.
       FD  TXN-IN.
       01  IN-REC           PIC X(23).
       FD  TXN-OUT.
       01  OUT-REC          PIC X(23).
       SD  SORT-WORK.
       01  SORT-REC.
           05  SR-BRANCH    PIC X(4).
           05  SR-ACCT      PIC X(6).
           05  SR-TYPE      PIC X.
           05  SR-AMOUNT    PIC 9(7)V99.
           05  SR-SEQ       PIC 9(3).
       WORKING-STORAGE SECTION.
       01  SHOW-RETURN      PIC 99.
       PROCEDURE DIVISION.
           SORT SORT-WORK
               ON ASCENDING KEY SR-BRANCH SR-ACCT
               ON DESCENDING KEY SR-AMOUNT
               WITH DUPLICATES IN ORDER
               USING TXN-IN
               GIVING TXN-OUT
           MOVE SORT-RETURN TO SHOW-RETURN
           DISPLAY "SORT-RETURN " SHOW-RETURN
           STOP RUN.

from session import files, run

# Eight transactions in the order they arrived, sorted by branch and account with the largest amount first.
files("sortkeys.cob", "arrivals.txt")
run("""
cobc -x sortkeys.cob
DD_TXNIN=arrivals.txt ./sortkeys && cat TXNOUT
""")

$ cobc -x sortkeys.cob
$ DD_TXNIN=arrivals.txt ./sortkeys && cat TXNOUT
SORT-RETURN 00
BR01AC0001C000250000003
BR01AC0001D000004999007
BR01AC0002D000012500002
BR01AC0002D000012500005
BR02AC0004D000030000004
BR02AC0004C000001250001
BR03AC0006D000000999006
BR03AC0007D000150000008

USING names the input file and GIVING the output file, and the sort opens, reads, writes and closes both itself, which is why IBM’s reference says they “must not be open” when the SORT starts. SORT-RETURN, which IBM documents as “0 (successful) or 16 (unsuccessful)”, printed 00. Within BR01 AC0001, the 2,500.00 credit came before the 49.99 debit because the amount is descending. BR01 AC0002 had two records with the same three keys, 125.00 each, and they kept their arrival order, 002 before 005. That is what WITH DUPLICATES IN ORDER promises; without it, IBM’s reference says, “the order of these records is undefined”. Step through the order the keys produced:

Procedures and MERGE replace either end of the sort

Either end of a SORT can be the program’s own code instead of a file. An INPUT PROCEDUREINPUT PROCEDURE: Paragraphs named in a SORT statement in place of USING. They read the input themselves and pass each record they choose to the sort with a RELEASE statement. reads the input itself and hands only the records it chooses to the sort, each with a RELEASE statement. An OUTPUT PROCEDUREOUTPUT PROCEDURE: Paragraphs named in a SORT or MERGE statement in place of GIVING. They receive the sorted records one at a time with a RETURN statement and use them as the program needs. receives the sorted records one at a time with RETURN, instead of GIVING writing them to a file.

MERGE combines two or more files that are each already sorted on the same keys into one file in that order. A MERGE reads its inputs through USING and writes through GIVING or an OUTPUT PROCEDURE, and it has no INPUT PROCEDURE, since its inputs are files that are already in order. A collating sequencecollating sequence: The order in which a program or a sort ranks characters when it compares them. ASCII puts digits before letters and EBCDIC puts letters before digits; COLLATING SEQUENCE names the one a SORT or MERGE uses., named by COLLATING SEQUENCE in the SORT or MERGE statement, decides how letters and digits are ordered against each other: ASCII ranks digits before letters, and EBCDIC, the order of z/OS, ranks letters before digits.

On z/OS the work is done by the system’s sort product: IBM’s Programming Guide says that with Enterprise COBOL it “must be DFSORT or an equivalent”.

Practise: keys, ends and order

These questions use the eight transactions and their sorted order, and every answer can be checked against the run.

INPUT and OUTPUT PROCEDUREs in depth: RELEASE, RETURN and a sort stopped with SORT-RETURN Pro: opens with a Pro, Premium or Ultimate pass

MERGE and collating order, run and compared, with a portability trap Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

First a warm-up with its answer, then three questions about sorts that changed a job’s results:

Key takeaways

• SORT with USING and GIVING orders a whole file by its keys, the major key first, each ascending or descending, and SORT-RETURN says 0 when it worked.
• WITH DUPLICATES IN ORDER keeps records with equal keys in their input order, as 002 and 005 stayed; without it their order is undefined.
• An INPUT PROCEDURE chooses the records that are sorted, an OUTPUT PROCEDURE uses the sorted records at once, and MERGE joins files that are each already sorted on the same keys.