STEMSORT

Syntax:

STEMSORT(stemname[,startsub][,stemcount][,sortfields])

Arguments:

stemname

the stem of the family of variables to sort. The combined lengths of the stemname argument and the largest subscript (plus the period, if specified) cannot exceed the REXX maximum length for symbols (250 characters). If stemname is a true REXX stem, code a period (.) as the last character. If you do not specify the period, the subscripts will be assumed to abut the stem name without an intervening period. For example, if you specify a stemname of "ABC.", STEMSORT will look for variables of the form "ABC.1", "ABC.2", "ABC.3", etc. If you specify a stemname of "ABC" (no period), STEMSORT will look for variables of the form "ABC1", "ABC2", "ABC3", etc.

startsub

the element of the pseudo-array to begin the sort on. The value for startsub must be a REXX printable integer from 0 to 231-1. The default value is element 1.

stemcount

the number of elements to sort. This argument must be a REXX printable integer from 2 to 231-1. If you do not specify stemcount, STEMSORT will sort variables beginning with startsub, and continuing until:

an un-initialized variable is found (i.e., a variable which has its name for a value).
a variable with a null value is found.
100,000 variables have been retrieved.

sortfields

a character string which contains the sort specification. There are 3 possibilities:

'A': specifies that a "full length" sort with blank padding is to be applied, with the elements sorted in character ascending order. This is the default.
'D': specifies that a "full length" sort with blank padding is to be applied, with the elements sorted in character descending order
'(sortspec...)': See "Specifying Sort Fields" below.

Module Name:

SWXSSORT

Service Description:

The STEMSORT function is used to sort the contents of REXX stem variables into a desired order. STEMSORT assumes that the variables to be sorted have numeric subscripts appended to the end. Other numbers are permitted in the stem names of the variables to be sorted.

Note: The subscript numbers are assumed to contain only significant digits (i.e., leading zeros are not permitted).

Specifying Sort Fields:

STEMSORT uses a sort fields specification format similar to the SORT FIELDS statement for DFSORT (and "plug-compatible" competitors). When using the "sortspec" format, the sortfields argument is a character string with the following components:

'(fldstart,fldlen,fldtype,flddir)'

Where:

fldstart: is the starting position of the sort field. The value for this field must be a positive REXX integer. This position must lie within the length of the longest variable value or the sort will fail.
fldlen: is the length of the sort field. The value for this field must be a positive REXX integer. The sum of fldlen and fldstart must be less than or equal to the length of the longest variable value or the sort will fail.
fldtype: the type of data. Only character data can be sorted properly (negative REXX numbers, binary, float and packed numbers will not sort correctly).
You must specify 'CH' for this sub-field. For this release of REXXTOOLS, only character data sorts are supported.
flddir: is the direction of the sort. The valid values are 'A' , for ascending, and 'D' , for descending.

Notes:

You may specify 1 to 5 sort fields.
As with all option fields, you must separate sub fields with commas, and there can be no embedded blanks.
Although sortfields itself may be skipped, if you supply a value for this argument, you are not permitted to skip any sub-fields. You must supply a value for every sub-field.
You must place parentheses around the value for the sortspec format of sortfields or it is an error.
If you do not specify sortfields, STEMSORT will sort using the 'A' format (full length ascending sort).

Returned Information:

The STEMSORT function returns a return code that indicates whether the sort was successful. If you CALL the STEMSORT function, the returned value is contained in the RESULT special variable. In addition, the REXX special variable, RC, is also set to contain the STEMSORT return code.

The following STEMSORT return code values are possible:

0: The sort was successful.
4: There were no stems matching the description given in stemname.
16: The sort failed. This may have happened because you have specified sort fields that do not fit all of the variables you want sorted.

Examples:

Call the STEMSORT routine to sort 100 variables in ascending order. The variables to sort begin with the characters "LINE.":
```
call stemsort 'line.', , 100
```
We have not specified the sortfields argument, because we want to sort on the entire width of each element, and we want the default order (ascending).
Call the STEMSORT routine to sort all of the variables with the stem "MYSTEM." . Sort the data in columns 1 to 10 in ascending sequence; sort the data in columns 20 to 25 in descending sequence:
```
call stemsort 'mystem.', , ,'(1,10,CH,A,20,6,CH,D)'
```