The SORT Statement

The SORT statement can also be used to sort the elements of a table.

General Formats for Format 1

General Formats for Format 2

Directives

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
- CALLSORT - specifies the program to be used to handle SORT and MERGE operations.

Syntax Rules for All Formats

A Format 1 SORT statement cannot appear in the declaratives portion of the Procedure Division, or in an input or output procedure associated with a SORT or MERGE statement.
A Format 2 SORT can appear in the declaratives portion.
Data-name-1 is a KEY data-name and is subject to the following rules:
1. KEY data-names can be qualified.
2. The data items identified by KEY data-names must not be variable length items.
3. KEY data items can be floating-point items.
4. If the KEY is an external floating-point item, the Compiler treats the data item as character data, rather than numeric data. The sequence in which the records are sorted depends on the collating sequence used.
5. If the KEY data item is internal floating-point, the records are sorted in numeric order of key values.

Syntax Rules for Format 1

File-name-1 must be described in a Sort-Merge File Description entry in the Data Division.
Data-name-1 is a KEY data-name and is subject to the following rules:
1. The data items identified by KEY data-names must be described in records associated with file-name-1.
2. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions.
3. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.
4. If the file referenced by file-name-1 contains variable-length records, all the data items identified by key data-names must be contained within the first x character positions of the record, where x equals the minimum record size specified for the file referenced by file-name-1.
The words THRU and THROUGH are equivalent.
File-name-2 and file-name-3 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
The files referenced by file-name-2 and file-name-3 can reside on the same multiple file reel.
If file-name-3 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.
No pair of file-names in the same SORT statement can be specified in the SAME SORT AREA or SAME SORT-MERGE AREA clause. File-names associated with the GIVING phrase cannot be specified in the same SAME clause.
If the GIVING phrase is specified and the file referenced by file-name-3 contains variable-length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor larger than the largest record described for file-name-3. If the file referenced by file-name-3 contains fixed-length records, the size of the records contained in the file referenced by file-name-1 must not be larger than the largest record described for the file referenced by file-name-3.
If the data descriptions of the elementary items that make up these records are not identical, it is the programmer's responsibility to describe the corresponding records in such a manner as to cause equal amounts of character positions to be allocated for the corresponding records.
If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
Procedure-name-1 represents the name of an input procedure. Procedure-name-3 represents the name of an output procedure.
Procedure-name-1, procedure-name-2, procedure-name-3 and procedure-name-4 must be section-names.
This restriction is removed.
If you want to specify more than 10 file-names in the USING or GIVING clause, you must use the Compiler directive CALLSORT"EXTSM"; this allows you to specify up to 255 files.

Syntax Rules for Format 2

Data-name-2 can be qualified and must have an OCCURS clause in the data description entry.
The data item referenced by data-name-1 must be the same as the data item referenced by data-name-2, or an entry subordinate to the data item referenced by data-name-2.
Unless data-name-1 and data-name-2 are the same, the data item referenced by data-name-1 must not be described by an entry containing an OCCURS clause. The data item referenced by data-name-1 must not be subordinate to an entry containing an OCCURS clause that is also subordinate to data-name-2.
The KEY phrase can be omitted only if the description of the table referenced by data-name-2 contains a KEY phrase.
If data-name-2 references a data item subordinate to a data item that contains an OCCURS clause, an index-name must be associated with each data item containing an OCCURS clause to which the data item referenced by data-name-2 is subordinate.

General Rules for All Formats

The words ASCENDING and DESCENDING are transitive across all occurrences of data-name-1 until another word ASCENDING or DESCENDING is encountered.
The data items referenced by the specifications of data-name-1 are the key data items which determine the order in which records are returned from the file referenced by file-name-1 or the order in which the table elements are stored after sorting takes place. The order of significance of the keys is the order in which they are specified in the SORT statement, without regard to their association with ASCENDING or DESCENDING phrases.
If the DUPLICATES phrase is specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records is:
1. The order of the associated input files as specified in the SORT statement, or by means of an RTS switch. Within a given input file the order is that in which the records are accessed from that file.
2. The order in which these records are released by an input procedure, when an input procedure is specified.
3. The relative order of the contents of these table elements before sorting takes place.
If the DUPLICATES phrase is not specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records or the relative order of the contents of these table elements is undefined.
The collating sequence that applies to the comparison of the nonnumeric key data items specified is determined at the beginning of the execution of the SORT statement in the following order of precedence:
1. First, the collating sequence established by the COLLATING SEQUENCE phrase, if specified, in the SORT statement.
2. Second, the collating sequence established as the program collating sequence.

General Rules for Format 1

The SORT statement releases all the records in the file referenced by file-name-2 or released by an input procedure to the file referenced by file-name-1, and returns them to an output procedure, or to the file referenced by file-name-3, in an order determined by the ASCENDING and DESCENDING phrases and the values of the data items referenced by the specifications of data-name-1.
To determine the relative order in which two records are returned from the file referenced by file-name-1, the contents of corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item:
1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the record containing the key data item with the lower value is returned first.
2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the record containing the key data item with the higher value is returned first.
3. If the contents of the corresponding key data items are equal, the determination is made on the contents of the next most significant key data item.
The execution of the SORT statement consists of three distinct phases as follows:
1. Records are made available to the file referenced by file-name-1. This is achieved either by the execution of RELEASE statements in the input procedure or by the implicit execution of READ statements for file-name-2. When this phase commences, the file referenced by file-name-2 must not be in the open mode. When this phase terminates, the file referenced by file-name-2 is not in the open mode.
2. The file referenced by file-name-1 is sequenced. No processing of the files referenced by file-name-2 and file-name-3 takes place during this phase.
3. The records of the file referenced by file-name-1 are made available in sorted order. The sorted records are either written to the file referenced by file-name-3, or, by the execution of a RETURN statement, are made available for processing by the output procedure. When this phase commences, the file referenced by file-name-3 must not be in the open mode. When this phase terminates, the file referenced by file-name-3 is not in the open mode.
The input procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RELEASE statement to the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the input procedure. The range of the input procedure must not cause the execution of any MERGE, RETURN or SORT statement.
If an input procedure is specified, control is passed to the input procedure before the file referenced by file-name-1 is sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the input procedure and when control passes the last statement in the input procedure, the records that have been released to the file referenced by file-name-1 are sorted.
If the USING phrase is specified, all the records in the file(s) referenced by file-name-2 are transferred to the file referenced by file-name-1. For each of the files referenced by file-name-2 the execution of the SORT statement causes the following actions to be taken:
1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the INPUT and the WITH LOCK phrases had been executed .
2. The logical records are obtained and released to the sort operation. Each record is obtained as if a READ statement with the NEXT and AT END phrases had been executed. If the file referenced by file-name-1 contains fixed-length records, any record in the file referenced by file-name-2 containing fewer character positions than that specified for file-name-1 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is released to the file referenced by file-name-1. If the file referenced by file-name-1 is described with variable-length records, the size of any record written to file-name-1 is the size of that record when it was read from file-name-2 or file-name-3, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-1.
3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. This termination is performed before the file referenced by file-name-1 is sequenced by the SORT statement.
  For a relative file, the content of the relative key data item is undefined after the execution of a SORT statement if file-name-2 is not referenced in the GIVING phrase.
  
  These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-2 or accessing the record area associated with file-name-2.
  
  The value of the data item referenced by a RECORD VARYING DEPENDING ON clause specified in the File Description entry for file-name-2 is undefined upon completion of the SORT statement.
The output procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RETURN statement in sorted order from the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the output procedure, as well as all statements in the declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the output procedure must not cause the execution of any MERGE, RELEASE or SORT statement.
If an output procedure is specified, control passes to it after the file referenced by file-name-1 has been sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure and when control passes the last statement in the output procedure, the return mechanism provides for termination of the sort and then passes control to the next executable statement after the SORT statement. Before entering the output procedure, the sort procedure reaches a point at which it can select the next record in sorted order when requested. The RETURN statements in the output procedure are the requests for the next record.
If the GIVING phrase is specified, all the sorted records are written to the file referenced by file-name-3 as the implied output procedure for the SORT statement. For each of the files referenced by file-name-3, the execution of the SORT statement causes the following actions to be taken:
1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the OUTPUT phrase had been executed. This initiation is performed after the execution of any input procedure.
2. The logical records are returned and written to the file. The records are written as if a WRITE statement without any optional phrases had been executed. If the file referenced by file-name-3 is described with fixed-length records, any record in the file referenced by file-name-1 containing fewer character positions than that specified for file-name-3 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is returned to the file referenced by file-name-3. If the file referenced by file-name-3 is described with variable-length records, the size of any record written to file-name-3 is the size of that record when it was read from file-name-1, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-3.
  For a relative file, the relative key data item for the first record returned has the value 1; for the second record returned, the value 2, and so on. The content of the relative key data item is undefined after execution of a SORT statement.
3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed.
  These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-3 or accessing the record area associated with file-name-3. On the first attempt to write beyond the externally-defined boundaries of a file, the USE AFTER EXCEPTION procedure, if any, associated with the file is executed; if control is returned as specified by the rules of the USE statement, no additional implicit write operations are executed for that file and the processing of the file is terminated as specified in this part.
The value of the data item referenced by a RECORDING VARYING DEPENDING ON clause specified in the File Description entry for file-name-1 is undefined upon completion of the SORT statement for which the GIVING phrase is specified.
Segmentation, as defined in the topic Segmentation, can be applied to programs containing the SORT statement. However, the following restrictions apply:
1. If a SORT statement appears in a section that is not in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
  - Totally within non-independent segments
  - Wholly contained in a single independent segment.
2. If a SORT statement appears in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
  - Totally within non-independent segments
  - Wholly within the same independent segment as that SORT statement.
The SORT-RETURN special register is available to SORT runtime elements. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of a sort operation. You can set the SORT-RETURN special register to 16 in an error declarative or input/output procedure to terminate a sort operation before all records are processed. The operation is terminated on the next RETURN or RELEASE statement.

General Rules for Format 2

The SORT statement sorts the table referenced by data-name-2 and presents the sorted table in data-name-2 either in the order determined by the ASCENDING or DESCENDING phrases, if specified, or in the order determined by the KEY phrase associated with data-name-2.
To determine the relative order in which the table elements are stored after sorting, the contents of the corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item.
1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the table element containing the key data item with the lower value has the lowest occurrence number.
2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the table element containing the key data item with the higher value has the lowest occurrence number.
3. If the contents of the corresponding key data items are equal, the determination is based on the contents of the next most significant key data item.
The number of occurrences of table elements referenced by data-name-2 is determined by the rules in the OCCURS clause.
If data-name-2 references a data item which is subordinate to a data item which contains an OCCURS clause, the first or only index-name associated with each such superordinate table must be set to the desired occurrence number before the SORT statement is executed.
If the KEY phrase is not specified, the sequence is determined by the KEY phrase in the Data Description entry of the table referenced by data-name-2.
If the KEY phrase is specified, it overrides any KEY phrase specified in the Data Description entry of the table referenced by data-name-2.
If the key phrase is specified but data-name-1 is omitted, the data item referenced by data-name-2 is the KEY data item.
The sorted table elements of the table referenced by data-name-2 are placed in the table referenced by data-name-2.
SORT procedures should not be invoked by multiple threads simultaneously.

Examples

Examples of using the SORT verb are provided in the topics SORT a File Using Input and Output Procedures and SORT Table Entries.