SUNSORT

The SUNSORT utility sequences a data file in a particular order. The command line syntax for SUNSORT is as follows:

Parameters:

mode

The optional logging mode as described below.

log

The optional name of the log file.

Q

Data should be appended to the {log} file.

tnn

The maximum number of sort trains to allow. This value must be in the range of one to 16383. The default value is 999. The option must be the second argument on the command line.

inifile

The name of the program information file used.

in

The required name of the source data file to be sorted.

out

The name of the optional output text file.

tmp

The optional drive and/or path on which to place the temporary work files.

seq

The optional file specification for the alternate sort sequence file.

opts

The options to alter the behavior of the utility as described below.

keys

The required key specifications as described below.

Note the following:

1. If a path specification is not given on {int}, the current path is searched followed by all search paths.

2. When no file extension is given for {in} or {out}, the default text extension as specified in the screen definition file is used.

3. If neither {in} nor {out} are located in the current directory, the directories specified in the PLB_PATH environment variable are searched for the existence of both {in} and {out} files.

4. If {output} is not specified, the file is sorted to a temporary file and when the sort is finished, the temporary file is renamed to the original file.

5. If a path specification is not given on {out}, the file is placed in the same location as {in}.

6. If the {log} file option is specified, all program messages are written to the file named by the {log} parameter. The following are the values for the {mode} parameter:

 

Mode	Meaning
L	Write all messages to the log file.
Q	Append all messages to the log file.

 

7. {opts} refers to special options that affect the output of the sort.

B

Binary input file. Your file must be fixed length records to use this option reliably.

F={nn}

Records are fixed length binary with NO end of record bytes.

G={nn}

Records are fixed length binary with normal end of record bytes.

I{ininame}

When specified, the utility will first look for any operational keywords in {inifile}. If the keyword is not found, the UET is searched. The filename specified by {ininame} must be a fully qualified name. If a full path is not specified, the filename must exist in the current working directory.

K

Key tag file output. The output of a key tag sort is a file with record pointers to where the sorted records are located in the input file. The file is in a binary format with each pointer taking up four (4) bytes. There are no carriage returns or line feeds in the file. The file may be read with PL/B by reading an INTEGER 4 field followed by a semicolon to keep the record position at the current location.

M

Search for files using the SETDRIVE information in the SUNSCRN.DEF file.

P{nn}{=|#}{c}

Primary Record Selection. If specified, the sort is performed on each record that matches the specification while all records after a matching record up to the next matching record are treated as detail information for the primary record and are sorted with the corresponding primary record. Since only a single character may be specified for this option, multiple P options select on multiple record positions. The {nn} specifies the record starting position, the {=|#} specifies an equal or not equal condition comparison and the {c} is the character to match.

P{=|#}"{comp}{logical}{comp}...}"

Alternate Primary Record Specification for primary record sorting. If specified, the sort is performed on each record that matches the specification while all records after a matching record up to the next matching record are treated as detail information for the primary record and is sorted with the corresponding primary record. This form of the Primary Key Specification allows for logical 'and' and 'or' conditions, and the ability to use more than one column. The entire specification is enclosed in double quotes.

 

{comp} is of the form {c}{op}{string}, where {c} is the starting column position, {op} is the match operator and {string} is the string to compare. The match operator may be one of the following: =, E, !=, <>, NE, <, L, <=, LE, >, G, >=, or GE. The {string} is specified by a starting single quote, the actual text string and an ending single quote. To include a single quote in the string, use two single quotes.

 

{logical} is the optional operator to allow more than one primary record specification. It may be a '&' for an 'and' condition, or a '|' for an 'or' condition.

 

A single character for {c} may be specified between the double quotes characters as in -p3="X".

 

A valid example of a primary specification with two different strings in the same columns would be: p="5='CREDIT'|5='DEBIT'

R#{{startpos}-{endpos},'{literal}'}{,...}# // MS-DOS

R\"{{startpos}-{endpos},'{literal}'}{,...}\" // MS-DOS

 

R#{{startpos}-{endpos},\'{literal}\'}{,...}# // Linux

R\"{{startpos}-{endpos},\'{literal}\'}{,...}\" // Linux

Record Reformat. If specified, the sorted output is reformatted to the specifications identified. This option allows output of only certain columns of the input and allows adding constant data to the output. The reformat option generates fixed length records. If the input record was shorter, it is filled with spaces. If the input record was longer, it is truncated. {startpos} identifies a starting column position within a record. {endpos} identifies an ending column position within a record. {literal} - Identifies a literal string to be included in all records being output. The literal string must be enclosed between double quote (") characters and can include space characters. Additionally, some operating systems strip off the double quote character if it is not forced with a leading slash (\) as in the third format above.

S{nn}{=|#}{c}

Selective output. If specified, only the records that match the specification are included in the output file. Since only a single character may be specified for this option, multiple S options select on multiple record positions. The {nn} specifies the record starting position, the {=|#} specifies an equal or not equal condition test, and the {c} is the character to compare.

S{=|#}"{comp}{logical}{comp}...}"

Alternate Selective Output specification. If specified, only the records that match the specification are included in the output file. This form of the selective output allows for logical 'and' and 'or' conditions, and the ability to use more than one column. The entire specification is enclosed in double quotes.

 

{comp} is of the form {c}{op}{string}, where {c} is the starting column position, {op} is the match operator and {string} is the string to test with. The match operator may be one of the following: =, E, !=, <>, NE, <, L, <=, LE, >, G, >=, or GE. The {string} is specified by a starting single quote, the actual text string and an ending single quote. To include a single quote in the string, use two single quotes.

 

{logical} is the optional operator to allow more than one selective output specification. It may be a '&' for an 'and' condition, or a '|' for an 'or' condition.

 

A valid example of a selective output specification with two different strings in the same columns would be: s="5='CREDIT'|5='DEBIT '"

T

Tag file output. The output of a tag sort is a file with record pointers to where the sorted records are located in the input file and the data from the sorted fields. The file is in a binary format. There are no carriage returns or line feeds in the file. The first pseudo record is a map of the contents of the rest of the file. It looks like '0000000011xxxxxx'. The '00000000' denotes the location of the eight byte integer record address. The '11' denotes the location of the two byte length of record field. The 'xxxxxx' denotes the location and length of the actual key information. The file may be read with PL/B by reading an INTEGER 8 field followed by an INTEGER 2 field followed by a DIM x field (where x is the number of x's in the first pseudo record) and a semicolon to keep the record position at the current location.

W

This SUNSORT64 only option causes the utility to open the final output file in a Windows OS write-through cache mode. The write-through cache mode causes the Windows OS to immediately flush all data written to the cache for the output file. When the '-w' option is used, this prevents an excessive number of pending writes from building up in the Windows OS cache that need to be flushed to the output file. By eliminating the excessive number of cached writes for the output file, the overall performance of the system for other processes improves. However, when the '-w' option is used, the performance of the sunsort final output phase will be slower but there is less impact on other processes currently executing. (9.6)

X

Disable record counter display.

 

8. {keys} refers to the actual key information used in the sequencing of the file. Any keyspec may be preceded by one of the following options. The options affect every keyspec that follow until an alternate option is given.

A

(default) All data within this keyspec range is sorted in ascending order.

D

(optional) All data within this keyspec range is sorted in descending order.

L

(default) All lower case data within this keyspec range is treated as lower case.

U

(optional) All lower case data within this keyspec range is treated as upper case.

N

The sort key is sorted as a signed numeric. When the negative sign '-' character identifies a negative value, the sort output is in reverse order for negative numeric keys.

O{c}

Specifies a bias indicated as a character {c}. This causes the order of a key field to be changed allowing all characters equal to or greater than the specified character to be sorted above the characters less than the specified character.

 

9. A maximum aggregate key length plus primary specifications of one hundred and fifty (150) bytes is permitted.

10. The amount of work space required may be approximated by:
    2 * ( ( keylength + 6 ) * records ) 

11. If TMPDIR=path is defined in the User Environment Table when the SUNSORT utility is executed, the specified path is used as the default path for creating the temporary files. If neither {tmp} nor TMPDIR is specified, the temporary work files are placed in the root directory of the current drive.

12. The {seq} file is generated with the SORTSEQ utility. This utility allows the user to change the order that characters are sorted and/or change the character value that a character is sorted as. For example, one could swap 'A' and 'B' and then all sequences of uppercase 'B' would sort ahead of all sequences of uppercase 'A'. You could also alias lowercase 'a' with uppercase 'A' and then all sequences of both 'a' and 'A' would sort together as the same character 'A'.

13. SUNSORT supports the PLB_FNC keyword that forces file names to lowercase or mixed case when they are created.

14. The Alternate Primary Record Specification and the Alternate Selective output Specification expressions support mathematical comparisons for the {op} operations. This allows a mathematical type indicator ( i.e. {N|n} ) to be included in the expression after the {c} starting column position.

 

The mathematical type indicator can be specified in the {comp} expression using the following syntax format:

 

{comp} format using {N|n} mathematical type indicator:

 

{c}[{N|n}]{op}{string}

Where:

{c}

Required starting column position for source operand field.

{N|n}

Optional 'N' or 'n' character that indicates that the {op} operator is to be performed as a mathematical comparison.

{op}

Required comparison operator that is one of the following operations:

 

=, E, !=, <>, NE, <, L, <=, LE, >, G, >=, or GE

 

{string}

Required destination operand field to be compared or matched against the source operand field found in a data record. The {string} must be specified with a leading and trailing single quote (') character. The number of characters specified in the {string} identifies the field size to be used for the record operand field starting at the {c} record position.

 

Note:

1. If the optional {N|n} comparison type is used, the {string} must be specified as a valid numeric string as follows:

1. Leading blanks are skipped and count against the total field size being compared. Any blank or white-space characters found after the first valid numeric character causes and invalid numeric {string} declaration.

2. A single leading '-' (i.e. negative character) is supported which can ONLY be specified after any leading blanks and before any valid numeric digits or decimal point.

3. A single decimal point character can be specified in the {string} numeric declaration.

4. All other characters specified in the {string} numeric declaration must be '0' to '9' digits.

2. If the optional {N|n} comparison type is used, an invalid numeric {string} declaration causes an error from the sor tutility as follows:

"Invalid primary key information."

3. If the optional {N|n} comparison type is used, the record that includes an invalid numeric field found at the {c} starting position may or may not be included in the selection record output depending on the logical evaluation of the 'S=' or 'S#' expression being used.

Examples for {N|n} usage:

sunsort in.txt out.txt -1-7, S="1n<=' -1.00'"

Examples for {N|n} numeric type usage with invalid record fields:

sunsort in.txt out.txt -1-7, S="10n=' 1.00'"

In this scenario, any invalid numeric fields found in the in the record at character position 10 are ignored and not included in the sorted output. The output should only include records that have a field value of '1.00'.

sunsort in.txt out.txt -1-7, S#"10n=' 1.00'"

In this scenario, all records that do NOT have a value of '1.00' are included in the output records including records with invalid numeric fields.

sunsort in.txt out.txt -1-7, S="10n!=' 1.00'"

In this scenario, the selected record output does not include any invalid numeric fields encountered. In this case, the selected record output ONLY includes records that have valid numeric fields whose value is not equal to '1.00'.

See Also: SUNSORT Examples, Utilities