HP 3000 Manuals

SORT Statement [ HP COBOL II/XL Reference Manual ] MPE/iX 5.0 Documentation

HP COBOL II/XL Reference Manual

SORT Statement

The SORT statement creates a sort file either by executing an input
procedure, or by transferring records from another file. The records of
the sort file are then sorted using a specified set of keys, and are made
available in sorted order to either an output procedure or an output
file.

Syntax

Parameters

file-name-1 a sort/merge file, and is described in a
sort/merge file description entry in the DATA
DIVISION.

data-name-1 data items described in records associated with
file-name-1. Each may be qualified and may
vary in length. None of these data names can
be described by an entry that either contains
an OCCURS clause, or is subordinate to an entry
containing such a clause. If file-name-1 has
more than one record description, then the data
items represented by these named need be
described in only one of the record
descriptions.

alphabet-name a name defined by you in the SPECIAL-NAMES
paragraph of the ENVIRONMENT DIVISION.

language-name an alphanumeric data item containing the name
of the language whose collating sequence should
be used. This parameter is an HP extension to
the ANSI COBOL standard.

language-id an integer data item containing the
identification number of the language to use.
This parameter is an HP extension to the ANSI
COBOL standard.

file-name-2 the files whose records are to be sorted.
These files must not be open at the time the
SORT statement is executed. Each must be a
sequential, relative, or indexed file
described in an FD level file description entry
in the DATA DIVISION. No more than one of these
file names may name a file on a multiple file
reel. Any given file name can be used only
once in a given SORT statement.

The actual size of the logical record or
records described by these files must be equal
to the actual size of the logical record or
records described by file-name-1. If the data
descriptions of the elementary items that make
up these records are not identical, it is your
responsibility to describe the corresponding
records in such a way as to cause an equal
number of character positions to be allocated
for the corresponding records.

procedure-name-1 the name of the first paragraph or section in
an input procedure.

procedure-name-2 the name of the last paragraph or section in
an input procedure.

procedure-name-3 the name of the first paragraph or section in
an output procedure.

procedure-name-4 the name of the last paragraph or section in
an output procedure.

file-name-3 the names of output files. These are subject
to the same restrictions and rules as
file-name-2 above.

Description

The words THROUGH and THRU are equivalent, and can be used
interchangeably.

The PROCEDURE DIVISION may contain more than one SORT statement appearing
anywhere except in a declarative procedure, or in the input and output
procedures associated with a SORT or MERGE statement. Files file-name-2
and file-name-3 must not be open when the SORT verb is executed or be
opened or closed during the execution of an input or output procedure if
such procedures are specified.

The data names following the word KEY are listed from left to right in
order of decreasing significance. This decreasing significance is
maintained from KEY phrase to KEY phrase.

When the SORT statement is executed, the records are first sorted in the
specified order (ASCENDING or DESCENDING) using the most significant key
data item. Next, within the groups of records having the same value for
the most significant key data item, the records are sorted using the next
most significant key data item, again, in ASCENDING or DESCENDING order
as specified for that key. Sorting continues in this fashion until all
key data items have been used.

NOTE Specifying the same file for the USING and GIVING file name is not
recommended. The file contents may be contaminated if the SORT
operation is abnormally terminated, for any reason. If the same
file is to be used, you should ensure that a backup copy exists in
case a file recovery becomes necessary.

For example, assume that the records to be sorted use the first three key
data items, and that the unsorted records appear as shown below.

-------------------------------------------------------------------------------------------------
- 1 - D - U - .... -
-------------------------------------------------------------------------------------------------
- 0 - A - N - .... -
-------------------------------------------------------------------------------------------------
- 1 - N - S - .... -
-------------------------------------------------------------------------------------------------
- 1 - F - O - .... -
-------------------------------------------------------------------------------------------------
- 1 - D - R - .... -
-------------------------------------------------------------------------------------------------
- 0 - X - T - .... -
-------------------------------------------------------------------------------------------------
- 0 - A - E - .... -
-------------------------------------------------------------------------------------------------
- 0 - B - D - .... -
-------------------------------------------------------------------------------------------------
- 1 - N - R - .... -
-------------------------------------------------------------------------------------------------
- 0 - X - E - .... -
-------------------------------------------------------------------------------------------------
- 1 - F - C - .... -
-------------------------------------------------------------------------------------------------
- 1 - C - S - .... -
-------------------------------------------------------------------------------------------------

If the SORT statement uses the first character position as the most
significant, and the third as the least significant, and the records are
to be sorted in ascending order for the first two keys, and in descending
order for the last key, then the results of each pass of the sort, as
well as the SORT statement, are shown in the following.

Examples

SORT TESTFILE ON ASCENDING KEY FIRSTCHAR, SECONDCHAR
ON DESCENDING KEY THIRDCHAR
USING INFILE
GIVING OUTFILE.

Where TESTFILE is, in part, described as:

SD TESTFILE.
01 TEST-REC.
03 FIRSTCHAR PIC 9.
03 SECONDCHAR PIC X.
04 THIRDCHAR PIC X.
:

and INFILE is described in part as:

FD INFILE.
01 IN-REC.
03 FIRST PIC 9.
03 SECOND PIC XX.
:

Note that the third pass of the sort left the records unchanged from
their order in the result of the second pass. The records are arranged
in their proper sequences by chance. The SORT statement would not
actually go through this third pass, as it recognizes the records as
already being sorted. This saves execution time.

DUPLICATES Phrase

If the DUPLICATES phrase is specified and the contents of all the key
data items associated with one data record are equal to the contents of
the corresponding key data items associated with one or more other data
records, then the order of return of these records is:

1. The order of the associated input files as specified in the SORT
statement. 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.

If the DUPLICATES phrase is not specified and the contents of all the key
data items associated with one data record are equal to the contents of
the corresponding key data items associated with one or more other data
records, then the order of return of these records is undefined.

ASCENDING and DESCENDING Phrases

When the ASCENDING phrase is used, the sorted records are in a sequence
starting from the lowest value of the key data items, and continuing to
the highest value.

When the DESCENDING phrase is used, the sorted records are in a sequence
from the highest value of the key data items to the lowest value.

Sorting takes place according to the rules for comparison of operands of
a relation condition.

COLLATING SEQUENCE Phrase

The COLLATING SEQUENCE phrase allows you to specify what collating
sequence to use in the sorting operation. This phrase is optional. The
program collating sequence is used if none is specified in the SORT
statement. If you do not specify an alphabet name in the PROGRAM
COLLATING SEQUENCE clause of the ENVIRONMENT DIVISION, the default is the
ASCII collating sequence. See the alphabet name clause of the
SPECIAL-NAMES paragraph in Chapter 6 for information on defining and
using collating sequences.

USING and INPUT PROCEDURE Phrases

You must specify either the USING or the INPUT PROCEDURE phrase in a SORT
statement.

If you specify the USING phrase, all records from file-name-2 are
automatically transferred to file-name-1. The files named by file-name-2
must not be open when the SORT statement is executed. The file named in
the USING phrase can be either relative or indexed.

The SORT process automatically opens these files, transfers their
records, and then closes them. If USE procedures are specified for the
files, they are executed at the appropriate times during these implicit
operations. The files are closed as though a CLOSE statement, without
any optional phrases, had been issued for them.

The records are then sorted in the file named by file-name-1, and are
released to file-name-3 or the specified output procedure during the
final phase of the sort operation.

If you do not specify a USING phrase, then you must specify an INPUT
PROCEDURE phrase.

If you do so, then section-name-1 through section-name-2 must define an
input procedure.

Control is passed to this procedure before file-name-1 is sorted. The
compiler inserts a return mechanism at the end of the last statement in
the statement in the section named by section-name-2, and when control
passes to the last statement in the input procedure, the records that
have been released to file-name-1 are sorted.

The input procedure can consist of any procedure needed to select,
modify, or copy the records that are made available contiguously by the
RELEASE statement to the file referenced by file-name-1. This includes
all statements executed by CALL, EXIT, GO TO, and PERFORM statements
within the range of the input procedure. This also includes declarative
procedure statements that are executed as a result of the execution
statements within the range of the input procedure. The input procedure
must not cause the execution of any MERGE, RETURN, or SORT statement.

GIVING and OUTPUT PROCEDURE Phrases

You must specify either the GIVING or the OUTPUT PROCEDURE phrase in a
SORT statement.

If you specify the GIVING phrase, then, as a last step in the sort
process, the sorted records in file-name-1 are automatically written to
each of the files referenced by file-name-3. The file can be relative or
indexed.

File-name-2 and File-name-3 must not be open when the sort process is
executed.

The sort process automatically opens, writes records to, and closes
file-name-3. If there are any USE procedures specified (whether
implicitly or explicitly) for file-name-3, they are executed if and when
appropriate, as part of the implicit function of the SORT statement.
When all records have been written to file-name-3, the file is closed in
a manner equivalent to issuing a CLOSE statement, with no optional
phrases, for the file.

If you specify the OUTPUT PROCEDURE phrase, there are several rules you
must follow in writing the procedure.

The output procedure can consist of any procedure needed to select,
modify, or copy contiguously available records using the RETURN statement
in sorted order from the file referenced by file-name-1. This includes
all statements executed by CALL, EXIT, GO TO, and PERFORM statements
within the range of the output procedure. This also includes declarative
procedure statements executed as a result of executing statements within
the range of the output procedure. The input procedure must not cause
the execution of any MERGE, RELEASE, or SORT statement.

Since the RETURN statement is the means of making sorted or merged
records available for processing, at least one such statement must appear
in the procedure. The procedure may consist of any procedures needed to
select, modify, or copy records. The records are returned one at a time
in sorted order from file-name-1. The procedure itself can contain no
RELEASE, SORT, or MERGE statements.

When an output procedure is specified in a SORT statement, the output
procedure is executed as part of the sort operation. The procedure is
used after the records have been sorted.

Output procedures, like input procedures, should be considered "slave"
procedures designed exclusively for the use of the SORT statement. If
the output procedures are not executed under the control of the SORT
statement, the RETURN statement causes the job to abort.
[REV BEG]

Sorting Large Files

Normally, the file descriptions compiled into the object program (using
information from the SELECT, FD, and SD clauses) provide all the
information required to execute the object program. However, to override
these file descriptions, you can supply MPE commands when executing the
program. These commands are effective only for the current execution of
the program.

You can use a :FILE command to specify the file size if the file to be
sorted is not a disk file and contains more than 10,000 records. In this
case, the :FILE command specifies the number of records in the SORT-FILE
(the file named in the SD statement). For example, if a program contains
the following statements:

SELECT SORT-FILE ASSIGN TO "SORT,DA".
SELECT NAME-FILE ASSIGN TO "INTAPE,UT".
:
SD SORT-FILE RECORD CONTAINS 100 CHARACTERS.
:
SORT SORT-FILE DESCENDING KEY DATA-ONE USING NAME-FILE GIVING
OUT-FILE.

And if the INTAPE magnetic tape file contains 15,000 records, enter the
following :FILE command before executing the program:

:FILE SORT;DISC=15000 Maximum number of records SORT is expected to process.

You should also use this command if an input procedure passes more than
10,000 records to SORT.

An alternate method for specifying the file size is to include the file
size parameter in the SELECT clause that defines the SORT-FILE (SD file
name).

For example:

SELECT SORT-FILE ASSIGN TO "SORT,DA,,,15000".

If you do not use either of these methods and you are sorting more than
10,000 records, a "TOO MANY INPUT RECORDS" error condition results and
the SORT program aborts. A disk file containing more than 10,000 records
does not require a file size specification because SORT programmatically
determines the file size.

NOTE To determine the file size parameter value to be passed to the SORT
subsystem with a CALL to SORTINIT, the compiler-generated code
opens the specified SORT-FILE using FOPEN. The actual file size
value that is used can be derived from the algorithm illustrated in
Figure 12-1 . SIZE-PARM is a temporary variable in Figure 12-1
.

Once the file size parameter is determined, any attempt to send
more records to the SORT subsystem with the RELEASE statement will
cause a run-time abort with the SORT error message:

SORTLIB: TOO MANY INPUT RECORDS

[REV END][REV BEG]

NOTE It is possible that a permanent file with the same name as the
SORT-FILE within job streams may cause undesired aborts. To avoid
this, include the following command in the stream file:[REV END]

:FILE SORT;NEW; DISC=15000
[REV BEG]

The file name used in the :FILE command is the one specified in the
SELECT clause.

[REV END]

Figure 12-1. Determining Local File Size (SIZE-PARM) Used in FOPEN

Segmentation Considerations

The following restrictions apply to the SORT statement when it is used in
a segmented program.

If the SORT statement appears in a section whose segment number is less
than 50, then any output procedure named in the SORT statement either
must be totally contained within a segment (or segments) whose segment
number (or numbers) is less than 50, or must be entirely contained in a
single segment whose segment number is greater than 49.

If the SORT statement appears in a segment whose segment number is
greater than 49, then any output procedure referenced by the SORT
statement must either be entirely contained within the same segment, or
be entirely contained within segments whose segment numbers are less than
50.

MPE/iX 5.0 Documentation