ADDSORT

Add New Sort Sequence

This directive is used to create a new secondary sort key sequence for an MSORT or TISAM file. Each MSORT file may contain up to 16 sort key definitions; each TISAM file may contain up to 8 sort key definitions. Sort key definitions can contain up to 16 segment definitions, each with field and offset positioning.

Syntax

ADDSORT file-name, [ sort-name: ] sortdef [ :mode ],
disk-num, [,ERR=line-ref|,ERC=error-code]

file-name: is any string of 8 characters or fewer used to name this file.
sort-name:: is any string of 20 characters or fewer used to name this sort sequence. If not specified, the sequence number of this sort key definition, in string form, assigns the first available sequence number starting from zero. The colon (":") is required in the syntax. Sort-name should not be specified in a TISAM file.
sortdef: defines the sort key. There may be from 1 to 16 sort keys defined for MSORT, from 1 to 8 for TISAM, and the first sort key defined constitutes the primary key.
:mode: 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.
disk-num: specifies the logical disk directory that contains this file. Valid values are 0 through 35.
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

The values specified for sort-name, sortdef, and mode must contain constants. The sort-name and mode options are strings that must be enclosed in quotes.

An MSORT or TISAM 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 and TISAM directives 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.

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 is to 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. Field-num is only valid for MSORT files, and is ignored for TISAM files.
offset-num: is an integer from 1 to the length of the field or record 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 is set to null or binary zero. The sum of all key-lengths must not exceed 144.
sort-order: is a single character designating 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.

Examples

ADDSORT "TEST", [1:2:5] + [3:16:6] + [1:3:2:"D"] :"U", 3

creates a new secondary key for the MSORT file named “TEST” on logical disk directory number “3”; the new secondary key structure for each record contains three key segments:

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

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

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

order is descending.

Key segment 1 and 3 overlap; keys in this sort sequence must be unique.

ADDSORT

Syntax

Remarks

Examples

See also