MSORT

Define Multi-Keyed File

This directive is used to create a new, multiple key data file in a logical disk directory. Each MSORT file may contain up to 16 sort key definitions, each containing up to 16 segment definitions, which contain field and offset positioning.

Syntax

MSORT file-name, [ sort-name1: ] sortdef1 [ :mode1 ]
[, [ sort-name2: ] sortdef2 [ :mode2 ] [, ... [ sort-namen: ] sortdefn [
:moden ]]] , num-records, record-size, disk-num, sector-num
[,ERR=line-ref|,ERC=error-code]

file-name: is any string of 8 characters or fewer used to name this file.
sort-name1,2,n: is any string of 20 characters or fewer used to name this sort key sequence. If not specified, the sequence number of this sort key definition, in string form, is assigned the first available sequence number starting with zero. The colon (:) is required in the syntax.
sortdef1,2,n: defines the sort keys. There may be from 1 to 16 sort keys defined, and the first sort key defined constitutes the primary key.
:mode1,2,n: is any string whose first character is "U" or "u" signifying that this sort key sequence must have unique keys; "D" or "d", indicating that this sort key sequence may have duplicate keys. "U" is the default for the first sort key sequence defined; "D" is not valid for the first sort key sequence (it must be unique). "D" is the default for all other sort key sequences if not specified. The colon (:) is required in the syntax.
num-records: is a positive integer greater than zero, indicating the maximum number of records to be contained in this file, or 0 indicating that this file should automatically expand as records are added until all available disk space is used. An end of file error (ERR=02) is generated (if a value other than zero is specified) when either the specified number of records or the limit of available space is encountered.
record-size: is an integer in the range of 4 to 32600 indicating the number of bytes in each record in this file.
disk-num: specifies the logical disk directory that contains this file. Valid values are 0 through 35.
sector-num: is the number 0 (zero). Positive integer values other than 0 are allowed but are treated as 0; syntax requires this parameter. Each operating system allocates where the file is stored. Refer to your documentation for additional options.
line-ref: is the program line number or label to branch to if this directive produces an error.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

This directive is generally available starting with release level 8.1.

Sort key sequences are defined with the sortdef1,2,n parameters indicated in the above syntax. Each sort key sequence may contain multiple segments (up to 16 segments) and those segments may overlap one another. Syntax for a sort key sequence is shown by:

[ segdef1 [ + segdef2 [ ... + segdefn ]] ]

segdef1,2,n: is composed of field, offset, length, and ordering data so that expanding a segdef looks like:

[field-num :] offset-num : key-length
[: sort-order]

field-num: is an integer from 0 to the number of fields in a data record (not to exceed 255). A field is defined as a string of data ended with the field separator code $8A$ (system variable SEP). 0 specifies that the entire data record be considered as the field and that field separators should be ignored. 1 signifies the first field; 2, the second; etc. If not specified, 0 (entire record) is assumed.
offset-num: is an integer from 1 to the length of the field in bytes signifying the beginning byte position within the field for this key segment.
key-length: is an integer from 1 to 144 specifying the length, in bytes, of this key segment. If a length is specified that is longer than the field contains (starting at offset-num), the remaining byte positions are set to null or binary zero. The sum of all key-lengths must not exceed 144.
sort-order: is any valid string whose first character designates the sorting order for this key segment: "D" or "d" indicates descending order; "A" or "a" indicates ascending order. If not specified, ascending is assumed

The first sort key sequence defined is the primary sort key. Each data record must have a unique primary key. Secondary keys may contain duplicates unless their :mode is “U”.

An MSORT file can have multiple sort key sequences. Each sort key sequence can be made up of multiple segments (up to 16 each). Unlike DIRECT files, the segments that make up all keys must be contained within the actual data record on file.

The MSORT directive need only define a single sort key sequence. The ADDSORT directive provides for the addition of more sort key sequences, and the REMSORT directive provides for the deletion of specific sort key sequences.

The key structure that is used for all input/output operations is specified by the SRT= I/O option with [P]READ and [P]EXTRACT directives. If not specified, the default SRT is the first, or primary, sort key sequence.

Examples

MSORT "TEST",[1:2:5]+[3:16:6]+[1:3:2:"D"],[1:6]:"U",1000,256,3,0

creates the TEST MSORT file. The file contains 1000 records, and each record contains 256 bytes. The file is placed on logical disk directory number 3.

The primary key is composed of 3 segments:

segment 1 starts at the 2nd byte of the 1st field in the record and is 5 bytes long, with an

ascending sort order as default.

segment 2 starts at the 16th byte of the 3rd field in the record and is 6 bytes long, with an

ascending sort order as the default.

segment 3 starts at the 3rd byte of the 1st field in the record, is 2 bytes long, with a

descending sort order.

The secondary sort starts at the first byte of the entire record (default field-num is “0”) for 6 bytes and has unique keys.

MSORT

Syntax

Remarks

Examples

See also