SORT

Sort a file

SORT(INPUT=filename[, RECORD=record[/rec_switch]]
&   [, KEY=(key_field[/key_switch, ...])][, OUTPUT=out_file][, END=end_val]
&   [, TEMPFILE=temp_file][, OPTIONS=option_string])

Arguments

INPUT=filename

Specifies the name of the input file to sort. (a)

RECORD=record

(optional) Specifies the name of the record that defines the file record format. If RECORD is not specified, the RECSIZE qualifier must be included in the OPTIONS string. (a)

rec_switch

(optional) One of the following switches that identifies the record as either fixed-length or variable-length. Each switch must be preceded by its own slash (/). (a)

f = Fixed-length records (default)

v = Variable-length records

KEY=key_field

(optional) Specifies one or more fields within record to use as a sort key. You can specify up to 15 keys. SORT precedence is determined by the order in which the keys are specified. If KEY is not specified, the KEY qualifier must be specified in the OPTIONS qualifier string. To use this compile-time KEY argument, you must also specify the compile-time RECORD argument. (a)

key_switch

(optional) One of the key switches that indicates the order of the sort. Each switch must be preceded by its own slash (/). (a)

Sort order

f = Forward (ascending) sort order (default)

r = Reverse (descending) sort order

Sort type

a = Alpha key (no case distinction)

c = Character key (case-sensitive ordering) (default)

d = Decimal key (numeric ordering)

You can specify a maximum of one sort order switch and one sort type switch (for example, /f/c).

OUTPUT=out_file

(optional) Specifies the name of the output filename. If OUTPUT is not specified, the input file is replaced by the resulting sorted file. If OUTPUT is specified, the input file is sorted, the resulting file is out_file, and the input file is not modified. (a)

END=end_val

(optional) Specifies an alpha or decimal value to use as either the logical end-of-file character or the maximum record count for the input file. (a or n)

TEMPFILE=temp_file

(optional) Specifies the name of a temporary file to be used during the SORT. If TEMPFILE is not specified, or if temp_file consists of a device or directory name only, SORT builds a file with a unique name in the default or specified device and directory. This file is created and deleted during the SORT. (a)

OPTIONS=option_string

(optional) Specifies one or more SORT options to be parsed at runtime. See The OPTIONS string in the Discussion for the syntax of option_string. (a)

Discussion

The SORT statement sorts a file in a specified key order. You can place the result into a new file or back into the original file.

SORT always creates a temporary file, regardless of whether or not you specify the TEMPFILE qualifier. If the TEMPFILE qualifier is not specified and you’re sorting locally,

On	The temporary file is created in
Windows	One of the following directories: The directory specified by the TMP environment variable. The directory specified by the TEMP environment variable if TMP is not defined. The Windows directory if neither TMP nor TEMP is defined.
UNIX	The current directory (where the program was started, not where in_file or out_file is located).
OpenVMS	SYS$SCRATCH, if it exists.

The temporary file is created in

Windows

One of the following directories:

The directory specified by the TMP environment variable.
The directory specified by the TEMP environment variable if TMP is not defined.
The Windows directory if neither TMP nor TEMP is defined.

UNIX

The current directory (where the program was started, not where in_file or out_file is located).

OpenVMS

SYS$SCRATCH, if it exists.

Make sure sufficient free disk space is available wherever temporary files are created. See Sorting a file remotely for information about the default temporary file in a client/server configuration.

In 32-bit Synergy programs (and version 9.1.* 64-bit Synergy programs), there is a 4-GB size limit to files that can be sorted with the SORT statement. See Synergex KnowledgeBase article 2474 for more information.

The SORT statement automatically determines the optimal amount of memory to use when sorting. The default maximum is 65536K on Windows and 4096K on UNIX (for 64 MB and 4 MB, respectively). You can use the SORTMEMMAX environment variable to change this limit.

You must use the RECSIZE switch when sorting records that may contain binary data, such as RFAs and integer data types.

The SORT statement opens and closes the input file, so it should be closed when starting a SORT or you will get a “file in use by another user” error ($ERR_FINUSE).

Key_field should not reference a pseudo array element (for example, myarr(1)). Use a named overlay of the array element instead.

If end_val is an alpha value, the first record containing the individual end_val character as the first character of the record denotes the end-of-file. The record containing the end-of-file character is not sorted. If end_val is a numeric value, it represents the number of the last record in the file to be sorted. If end_val is not specified, the file is sorted until the physical end-of-file is reached.

The order of duplicates (where more than one sorted record contains the exact same combined key) is undefined and should not be relied upon.

On Windows and UNIX, SORT outputs a relative file (variable or fixed) regardless of the type of the input file. ISAM files cannot be sorted.

The OPTIONS string

Option_string has a maximum size of 256 and the following format:

[RECSIZE=size[/rec_swch]][, KEY=(key)][, OUTPUT=out_file][, TEMPFILE=temp_file][, END=end_val]

RECSIZE=size

(optional) Specifies the size of the records in the file. This qualifier must be specified if the RECORD compile-time qualifier is not specified. For files containing variable-length records, use the maximum record length. (n)

rec_swch

One of the following switches. Each switch must be preceded by its own slash (/). (a)

f = Size is the size of a fixed-length record. (default)

v = Size is the size of a variable-length record.

e = Size is the exact size of a fixed-length record, including record terminators.

KEY=(key)

(optional) This qualifier must be specified if the KEY compile-time qualifier is not specified. Specifies up to 15 SORT keys in the format pos:len[/swch, …]: (a)

pos

The position of the key field within the record (n)

len

The length of the given key (n)

swch

(optional) Any one of the switches listed above under key_switch. Each switch must be preceded by its own slash (/). (a)

OUTPUT=out_file

(optional) Specifies an output filename. This qualifier is functionally similar to the OUTPUT compile-time qualifier, except that only literal values are accepted.

TEMPFILE=temp_file

(optional) Specifies the name of a temporary file to use during the SORT. This qualifier is functionally similar to the TEMPFILE compile-time qualifier, except that only literal values are accepted.

END=end_val

(optional) Specifies an alpha or decimal literal to use as either a logical end-of-file character or maximum record count for the input file. This qualifier is functionally similar to the END compile-time qualifier, except that only literal values are accepted.

The options specified by the OPTIONS qualifier override their corresponding SORT qualifiers. OPTIONS enables you to build SORT commands during program execution. This causes some minor extra runtime overhead, so we recommend that you use the corresponding compile-time arguments wherever possible.

Sorting a file remotely

In a client/server configuration, the SORT statement is passed to xfServer which performs the sort locally on the server, rather than sorting across the network. For this reason, the filenames specified on the SORT statement must refer to the same machine, either all local or all remote. For example, if the input file is on the server, the output file must also exist on the server. The following SORT statement shows proper syntax:

SORT(input="DAT:orders", output="DAT:ordered, ...)

while this SORT statement generates an error:

SORT(input="DAT:orders", output="ordered", ...)

If you want to sort a file on one machine and have the resulting file copied to another machine, use XCALL COPY in conjunction with the SORT statement.

On a remote sort, the default location of the temporary file varies by operating system:

On Windows, it is placed in the directory that TMP or TEMP is set to in the Windows registry (not the environment); if they are not set, it is placed in C:\Users\Public\Public Documents. TMP/TEMP should be set to a local directory. Do not set it to a location on the xfServer machine; doing so can cause Visual Studio and other Windows applications to crash.
On UNIX, it is placed in /tmp.
On OpenVMS, it is placed in SYS$SCRATCH.

Examples

The following example sorts a file by two keys and creates a sorted output file.

subroutine srtfil
record customer
    id                  ,a6
    name                ,a30
    addr                ,2a30
    city                ,a15
    state               ,a2
    zip                 ,a9
literal
    CLIENTS             ,a*, "DAT:clients.ddf"
    SRTFIL              ,a*, "SRT:clients.srt"
proc
    sort(input=clients, record=customer, key=(zip,name), output=srtfil)
    xreturn
endsubroutine

The following subroutine does the same thing as the above example, but uses the runtime option string instead of the compile-time qualifiers.

subroutine srtfil               ;Sort any file that needs two sort keys
                                ; and an output file.
    a_srtfile           ,a      ;File to sort.
    a_recsize           ,d
    a_key1pos           ,d
    a_key1len           ,d
    a_key1sw            ,a
    a_key2pos           ,d
    a_key2len           ,d
    a_key2sw            ,a
    a_outfile           ,a
record
    optlen              ,d3
    srtopts             ,a160
proc
    xcall s_bld(srtopts, optlen, "rec=%d, key=(%d:%d/%a, %d:%d/%a), 
  &       out=%a", a_recsize, a_key1pos, a_key1len, a_key1sw, a_key2pos, 
  &       a_key2len, a_key2sw, a_outfile)
    sort(input=a_srtfile, options=srtopts)
    xreturn
endsubroutine