
                                        **********General Help**********

This program sorts "properly prepared input data" and outputs the sorted results to a separate file. In
very simple terms a sort rearranges the ordering of individual members in a set of data. The rearrang-
ing is based on the ordering of the characters in the alphabet and the ordering of natural numbers (1,
2, 3, ...). For example, suppose you have data that contains the following five (5) members:

     Zeta
     Gamma
     Alpha
     Beta
     Rho

If so, a sort of this data in "A"scending order would result in the following output:

     Alpha
     Beta
     Gamma
     Rho
     Zeta

An ascending sort follows the "natural" order of the alphabet ("A", first, then "B", then "C", etc.) and
the numbers (from the smallest to the largest, such as "1", then "2", then "3", etc.). Conversely, the
above input could be sorted in "D"escending order. The output would be:

     Zeta
     Rho
     Gamma
     Beta
     Alpha

Descending order is the reverse of ascending order.

Suppose the data is numeric. For example:

     1001
     23
     12345
     999

If so, a numeric sort in ascending order would produce:

     23
     999
     1001
     12345

A sort in descending order would produce:

     12345
     1001
     999
     23


The program completes the following types of sorts, per your request:

     1.     "C"ase sensitive alphabetic
     2.     "D"ate
     3.     Case "I"nsensitive alphabetic
     4.     "N"umeric
     5.     "T"ime

For each of the above, you can elect to sort in "A"scending  or "D"escending order.

Actual sorting is slightly more complicated than simply following the order of alphabetic characters and
natural numbers. The program in fact uses the extended American Standard Code for Information Interchange
(extended ASCII) to sort data. Extended ASCII uses a 8-bit numerical character set (= 256 numbers) to
represent the characters found in a standard United States (U.S.) keyboard. For example, the upper case
character "D" is numerically represented by 68 in extended ASCII decimal (base ten (10)). Similarly,
a lower case "z" equals 122 in extended ASCII decimal.

Using the above information, case sensitive alphabetic sorts involve the fact that the capitalized alphabetic
characters appear before their lower case equivalents in extended ASCII placement. For example, "A" = 65 in
extended ASCII decimal, while "a" = 97. Therefore, a case sensitive ascending sort on:

     alpha
     Alpha

produces:

     Alpha
     alpha

A case insensitive ascending sort would not change the order, because "a" and "A" would be equivalent.

The program can sort negative, positive and/or decimal numerical data. For data containing decimals
it will accurately sort up to three (3) places in the decimal position. Values beyond the third place are
ignored. That means, for example, the sort will correctly place "1.2345" and "1.2346" before "2.9876"
in an ascending numerical sort. However, it might place "1.2346" before "1.2345", because it ignores
the "5" and the "6", which occupy the fourth decimal position. 

For date sorts the program orders the data chronologically by dates. For example, data containing the
date, "10/11/2010", appears in the sorted output before data containing the date, "12/01/2010", assuming
that the sort order is ascending.

For time sorts the program orders the data chronologically by time of day. Data containing "11:05 am",
for example, appears in the sorted output before data containing "10:00 pm", assuming that the sort
order is ascending.

The program can sort data within sorts (sequential data sorting). It can sequentially sort up to nine (9)
times (ten (10) sorts in total, counting the first one). Again, all of this is according to your request.
The program uses "least significant bit (LSB) Radix" sorting to complete all sorts. It is one of the
fastest methods.


To execute a sort you must complete the following tasks:

     1.     Properly prepare the data you want to sort.
     2.     Specify the location of that data.
     3.     Specify the parameters of the sort.
     4.     Press the "SORT" button.

Each of these tasks requires individual attention and discussion. Refer to the section entitled, "Help on
Preparing the Data for Sorting", below, to review detailed information on how to prepare the data for sorting.
The section entitled, "Help on Locating the Data You Want to Sort", has information on specifying the location
of your data. The section, "Help on Specifying Your Sorting Parameters", provides details on the parameters of
your sort. The section entitled, "Help on Executing Sequential Sorts" explains what sequential sorts are and
how to complete them. Finally, note that the "SORT" button remains disabled on the program Main
window, until you correctly complete the first three (3) of the above tasks. See the information contained in
the section, "Help on Enabling the SORT Button". That section also explains where the program saves the sorted
file results.




                            **********Help on Preparing the Data for Sorting**********

This program sorts "properly prepared" input data. For the purposes of this discussion, we classify any
input as belonging to one (1) of two (2) distinct data types:

     1.     An ASCII (or text) file
     2.     Data created by using the REXX SysFileTree function

For the first data type, you must correctly prepare the data, before specifying its location for use in
the program. For the second type, the program internally prepares the data. You simply tell it the
location of that data. With that distinction in mind, this help window discusses only the first data type,
an ASCII file. For the second type please consult the information on locating the data. Press the Radio
Button entitled, "Locating the data you want to sort".

NOTE: You elect to use an ASCII file as your source by pressing the Radio Button entitled, "No". It is
located on the Main form, next to the Text Tool, "Generate and sort REXX SysFileTree Information?".
Alternatively, use the SysFileTree data source by pressing the other Radio Button, "Yes".


The concepts of "input data members", or simply "records", and "sort fields" are important for understanding
how to correctly prepare input data. A specific example will help the explanation. Suppose
you wish to sort the following data:

     6/13/95 2:10a 47391 ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\COBO____.PFB
     5/16/97 1:02a 64327 A-HRS C:\Acrobat\Acrobat3\ReadOS2\aapdf.dll
    12/18/96 10:55a 278026 ----- C:\Acrobat\Acrobat3\ReadOS2\acrobat.pdf
     6/13/95 210a 684 ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\pfm\ZY______.PFM
     5/16/97 124a 37376 A---- C:\Acrobat\Acrobat3\ReadOS2\del_ini.exe
    10/14/96 354p 9305 ----- C:\Acrobat\Acrobat3\ReadOS2\license.pdf
 
If so, this data contains six (6) members (think of them as data records). Each record has five (5) sort
fields. The first field contains date information, such as "6/13/95" and "10/14/96". The second field contains
time information, such as "2:10a" and "1:02a". The third field contains numerical data, such as
"684" and "9305" (file sizes, in bytes). The fourth field contains file extended attribute data and the
fifth field has file path data, such as "C:\Acrobat\Acrobat3\ReadOS2\license.pdf" (part of the sixth, or
last record).

To properly prepare this data, you must complete following 5 tasks:

     1.     Store the data in an ASCII file, located somewhere in your computer data storage.
     2.     Start any given sort field at the same character position across all the records.
     3.     Construct any given sort field to the same length across all the records.
     4.     Properly format the dates in any date-containing field.
     5.     Properly format the times in any time-containing field.

To satisfy the first requirement you could use a text editor application to create and save the data.
To satisfy the remaining requirements, you could edit the example data, perhaps in a text editor, so
that it appears as follows:

    6/13/95  2:10a  47391  ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\COBO____.PFB
    5/16/97  1:02a  64327  A-HRS C:\Acrobat\Acrobat3\ReadOS2\aapdf.dll
    12/18/96 10:55a 278026 ----- C:\Acrobat\Acrobat3\ReadOS2\acrobat.pdf
    6/13/95  2:10a  684    ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\pfm\ZY______.PFM
    5/16/97  1:24a  37376  A---- C:\Acrobat\Acrobat3\ReadOS2\del_ini.exe
    10/14/96 3:54p  9305   ----- C:\Acrobat\Acrobat3\ReadOS2\license.pdf

Disregarding the five (5) place indentation at the start of each record (the indentation is used here
only to set apart this data from remaining portions of the help explanation), note that the first sort
field starts at character position N 1 and has a length of eight (8) characters. This is true across all
six (6) data records. The table, below, shows the starting position and the length of the 5 sort fields
across all 6 records:

     Sort Field  Starting    Field
          N       Position   Length

          1            1            8
          2           10            6
          3           17            6
          4           24            5
          5           30           50

Each field is constructed from the ASCII character set (256 characters available). Any character can
be used in any position, including the space character. However, a sufficient number of spaces are
added at the end of the field, as required, to make that field have the same length across all the
records. For example, the field containing the date, "5/16/97", has a single space at the end to make
it be the same length (8 characters) as the record containing "10/14/96". In a similar fashion, "684"
has three (3) spaces at the end of to make it have the same length as "278026". Also, the last three
time entries, "210a", "124a" and "354p", are changed to "2:10a", "1:24a" and "3:54p", respectively, to
correctly format them as time values (additional information below).

IMPORTANT!! IMPORTANT!! Use only spaces (" ") to ensure that each field has the same length across
all the records! Insert the required number of spaces only at the end of each field in each record! The
Sort program will not work correctly, if done any other way!

Note that the dates are correctly formatted. Specially, dates must be in the "mm/dd/yy" format, or the
"mm/dd/yyyy" format, with or without a leading zero for any of the first nine months or the first nine
days. The program internally calculates the REXX base date (the number of days since and including
01 January 0001) for each date in the input data. It adds a sufficient number of leading zeros to the
REXX base dates, such that all of the base dates have the same number of digits. It uses the internally
calculated dates to perform the sort, leaving your original data unaltered. At the completion of the
sort, it returns your data in its original format, but now sorted.

In the above records the time values are all correctly formatted. The data is in a recognizable "12-hour
AM/PM" format. The following examples are recognizable, and acceptable, as 12-hour AM/PM times:

     "hh:mmx" or "hh:mm:ssx" or "hh:mm x" or "hh:mm:ss x" or "hh:mm xm" or "hh:mm:ss xm"

Above, the hours, minutes and/or seconds can be single digit for values less than 10. That is, a leading
zero (0) is not required for values less than 10, but it can be used, if desired. Also above, x = "a" or
x = "p". The "AM/PM" portion of the time can be lower case, upper case, or mixed case. As shown
above, the "AM/PM" portion can be separated from the "hh:mm:ss" portion by a single space, or no
space at all. If the "AM/PM" portion is missing ("01:25", for example), the value is treated as an "AM"
time. The program internally calculates the equivalent number of seconds for each time value in the
data. It adds a sufficient number of leading zeros to the seconds, such that all the times have the same
number of digits. It uses the internally calculated values to perform the sort, leaving your original data
unaltered. At the completion of the sort, it returns your data in its original format, but now sorted.

In a similar fashion the program internally adds a sufficient number of leading zeros to numerical data
(the file sizes in the above example), such that all the values have the same number of digits. It uses
that data to complete the sort. It returns your numerical data in its original format, but now sorted.


Use the above explanations and the examples to properly prepare your own ASCII input data file.
This distribution also includes the "EqulFlds" program. Use it to help you prepare your ASCII text
(data) file. "EqulFlds" performs the following tasks:

     1.     Equalizes all the sort fields across all the records
     2.     Adds one (1) or more new sort fields to an existing data file

Equalizing refers to making each given sort field start at the same location across all the records
and making each one have the same length across all the records. Please refer to the documentation
and online help that come with "EqulFlds".




                        **********Help on Locating the Data You Want to Sort**********

This program sorts "properly prepared" input data. For the purposes of this discussion, we classify any
input as belonging to one (1) of two (2) distinct data types:

     1.     An ASCII, or text, file
     2.     Data created by using the REXX SysFileTree function

To sort any data, you must first select the type that you are going to use (1 of the above 2). Secondly,
you must locate the actual data for the program. It's location will be somewhere in your computer data
storage (a hard drive, for example).

Select the data type by pressing the "Yes" or the "No" Radio Button next to the Text Tool entitled,
"Generate and sort REXX SysFileTree information?". These buttons are on program Main window.
Selecting "Yes" means that you want to use data created from the SysFileTree function. Selecting
"No", the default, means that you want to use an ASCII data file.

Locate your actual data by pressing the Radio Button entitled, "Find the file containing the information
for the sort", assuming you selected the "No" Radio Button for the SysFileTree sort. If you selected
"Yes", press the Radio Button that displays: "Find the folder containing the information for the sort".
That button opens the Browse window. It is a new window, similar to a "file open" window in look
and function.

For the ASCII data file choice the Browse window has the several features to aid you in finding and
selecting your file. Starting at the top of the window and proceeding to the bottom, it has the following controls:

     1.     A message area, showing you the currently selected drive, folder or file
     2.     A second message area, showing you whether or not you selected an ASCII data file
     3.     A Check Box to retain the configuration of the window at its next opening
     4.     A Check Box to display removable media and networked drives (volumes)
     5.     A Check Box to not remember open subfolders inside of subfolders
     6.     One or more drive (volume) selection Radio Buttons
     7.     A List Box, showing all of the folders on the selected drive
     8.     A List Box, showing all of the files in the selected folder
     9.     A "HELP" button
    10.     An "OK" button
    11.     A "CANCEL" button

Use the first message to identify what you are selecting in the 2 List Boxes. The beginning portion of
the message tells you the selection object type: a drive, folder or file. The second portion, after the
semicolon, tells you the path to the selected drive, folder or file. If the path description is too long to
fit in the message area, the program shows you the first part of the path, followed by a " ..., ", followed
by the last part of the path. For example, it might show:

     C:\Acrobat\AcrobatReader51Pre1\Adobe\Acrobat 5.0\ ..., \ZY______.MMM

The second message is just to the right of the first message. It says "NO" in red font until you select a
"correctly prepared ASCII" file. It tests each file as you select it. For the purposes of the test, a correctly
prepared file is one that has at least 2 lines and all the lines have the same length (the same number
of characters). This must be true because each line in an ASCII file represents a data member (record)
for sorting. Sorting can only occur, if there are 2 or more "things" (records) to sort. The records
must all be the same length, because each given sort field must be the same length across all the
records. And each field must start at the same location (position) across all the records. If a
If a data file passes the test, the message changes to "OK" in dark green font.

The first Check Box, near the top of the window, allows you to retain your Browse window configuration
after pressing the "CANCEL" button. You can later go back to the Browse window (reenter it).
You will see the same selections that you had, when you last left it. This works only if the Check Box
is checked, when you press the "CANCEL" button (the opening default for this window). If it is not
checked, you will not retain your selections, if you later return. It does not matter what you do to the
control before pressing "CANCEL". You can toggle it to your liking. It's status when you press "CANCEL"
determines whether or not you retain your selections. It only works with the "CANCEL" button.
We assume that, if you press "OK", everything is correct and you will next complete the sort.

NOTE: You might experience a slight delay, if you reenter Browse after pressing "CANCEL" and the
Check Box is selected. Your system may require several seconds to redraw the window.

The second Check Box from the top allows you to select removable media and networked drives on
on your system (floppy, CD and DVD drives, for example). You must check this control to select any of
these drives. The opening default is unchecked for this control.

The third Check Box allows you to retain, or not retain, your selection of "opened" subfolders inside of
selected folders on the "Folders List Box". This is the List Box that shows the various folders on a selected
drive. It displays them a cascading treelike structure. The initial display shows only the first
level of folders on the drive (level 1 folders). It does not show any of the subfolders that may exist
inside the level 1 folders. If a given folder has a plus sign ("+") to the left of its name, that folder has
1 or more subfolders. The plus sign indicates that you have not "opened" that folder to display its subfolder(s).

Select any folder that has a + sign. Select it by clicking on it anywhere, including on the + sign. The +
sign changes to a minus ("-") and a cascading sublevel now appears, indented slightly to the right. The
sublevel shows all of subfolders of the selected folder. These are next level folders (level 2). If any
folder on this level has subfolders, it also has a + sign to the left of its name. If desired, you can continue
to select + signs at this or any level, thereby opening, or displaying, the subfolders of a given
folder. In this way you can display the cascading subfolders down to any level that contains subfolders.

In a similar fashion you can also select any folder that has been opened (one that has a - sign). Doing
so will collapse the view of all the subfolders underneath. They will all disappear from view and the
- sign becomes a + sign. If you later decide to reopen this folder, all of the cascading subfolders, that
you previously opened underneath it, if any, will reappear. You do not have to reopen them. This behavior
will occur as along as the Check Box entitled, "Do not remember opened subfolders inside of subfolders",
remains unchecked (the default for the Browse window).

Next, locate the set of drive Radio Buttons on the window. These buttons display the drives (volumes)
on your system and allow you to select the one that contains your file. When you select a particular
drive, the List Boxes display the level 1 folders on that drive and the files that reside in the drive root
directory, if any. A small delay may occur before the List Boxes display their information. The computer
must read and retrieve the data from hardware. This type of data access is typically the slowest.

If you select the Check Box for removable media and network drives, those drives also appear in this
section of the window. If you toggle the removable media and network drives Check Box, you will reset
the selections that you previously made. No drives will be selected and the List Boxes will not show
any folders or files.

Next, the List Box on the left side of the window shows all of the folders on a selected drive. The use
and operation of this control has already been explained. Please see the above discussion on the "Do
not remember opened subfolders inside of subfolders" Check Box.

The List Box on the right side shows the files that reside in the folder selected on the Folders List Box.
If no files are shown, the selected folder does not contain any. Regardless, you need to complete your
selection of the ASCII data file by finding it in this List Box and then selecting it (clicking on it). Be sure
that it is a "correctly prepared" ASCII file. That is, be sure that the second message toggles to "OK"
for data file that you want to use. If it does not, click on the HELP Radio Button entitled, "Enabling the
"SORT" button". Consult the help information under that topic to determine the reason why the program believes
that your data file has a problem. It will either be that your file has less than 2 lines, or
that it has 2 or more the lines of different lengths. Note that each line in an ASCII file is separated by
a "carriage return" and a "line feed". These are special characters. Also, every ASCII file ends with an
"end of file" character, which is another special character. Regardless, if you have a problem, use a
good text editor application to edit and correct your data file.

The "HELP" button displays a Help facility (window). It provides detailed information on the capabilities,
operation and use of Sort. You are presently using the Help facility.

Next, press the "OK" button to lock in your data file selection and return to the program Main window.
Alternatively, press the "CANCEL" button to terminate and return to the Main window without selecting
a file.


For a SysFileTree data type, the Browse window has the following controls:

     1.     A message area, showing you the currently selected drive or folder
     2.     A Check Box to retain the configuration of the window at its next opening
     3.     A Check Box to display removable media and networked drives (volumes)
     4.     A Check Box to not remember open subfolders inside of subfolders
     5.     One or more drive (volume) selection Radio Buttons
     6.     A List Box, showing all of the folders on the selected drive
     7.     Radio Buttons for electing whether or not to recursively search a folder for SysFileTree
     8.     Radio Buttons to select file data or folder data for sorting
     9.     "Yes" and "No" Radio Buttons for recursive search of subfolders
    10.     "Files" and "Folders" Radio buttons
    11.     A "HELP" button
    12.     An "OK" button
    13.     A "CANCEL" button

The message area has the same explanation as given above (for the ASCII data file choice), with the
following exception: it does not show any selected files, because for the SysFileTree data type you select
a drive or a folder, only.

The three (3) Check Box controls, the drive (volume) Radio Buttons and the List Box for the folders
each have the same explanations, previously given for the ASCII data file sort.

Next, the Browse window has "Yes" and "No" Radio Buttons to select, or not select, recursive searching
of the selected drive or folder. A recursive search means that the SysFileTree function will search all
of the subfolders of the selected folder and output the results. A non-recursive search means that
SysFileTree searches only the selected folder. The "Yes" and "No" buttons simply incorporate the
recursive versus non-recursive option built into SysFileTree.

Next, the Browse window has Radio Buttons that incorporate the SysFileTree option to output file
search information (the opening default), or folder search information.

Lastly, the "OK" and "CANCEL" buttons have the same explanation as given above. Note that a small
delay may occur after selecting "OK" (1 or 2 seconds). At this point the program creates the SysFileTree
information, which involves a data storage read. This type of data access is typically the slowest
for computers. If you selected a recursive search, the read could involve a large amount of data. After
the delay the program Main window reappears.




                        **********Help on Specifying Your Sorting Parameters**********

The program Main window contains the graphical user interface (GUI) for specifying the parameters of
your sort. These parameters tell the program how to step through the input data and output the specific
sort you requested. On the GUI you must particularize the following five (5) parameter sets:

     1.     The starting character N (position) for each sort field
     2.     The length of each sort field (how many characters it contains)
     3.     The type of sort for each field
     4.     The sort order for each field
     5.     The sort field progression

The setting of these parameters is slightly different, when you use an ASCII file as your input data,
compared to using data created from the REXX SysFileTree function. Because of the differences, we
separately discuss both situations. Directly below, please find the discussion for the ASCII  data file.
NOTE: See the help on preparing your data for more information on the two (2) input data types. Do
so by pressing the Radio Button entitled, "Preparing the data that you want to sort".


The concepts of "input data members", or simply "records", and "sort fields" are important for understanding
how to specify your sorting parameters. An example will help the explanation. Suppose you wish to sort the
following data, which has been properly prepared (see the information on preparing your data):

    6/13/95  2:10a  47391  ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\COBO____.PFB
    5/16/97  1:02a  64327  A-HRS C:\Acrobat\Acrobat3\ReadOS2\aapdf.dll
    12/18/96 10:55a 278026 ----- C:\Acrobat\Acrobat3\ReadOS2\acrobat.pdf
    6/13/95  2:10a  684    ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\pfm\ZY______.PFM
    5/16/97  1:24a  37376  A---- C:\Acrobat\Acrobat3\ReadOS2\del_ini.exe
    10/14/96 3:54p  9305   ----- C:\Acrobat\Acrobat3\ReadOS2\license.pdf
 
This data contains six (6) members (think of them as data records). Each record has five (5) sort
fields. The first field contains date information, such as "6/13/95" and "10/14/96". The second field has
time information, such as "2:10a" and "1:02a". The third field has numerical data (file sizes, in bytes),
such as "64327" and "684". The fourth field contains file extended attribute data and the fifth field
contains file path data, such as "C:\Acrobat\Acrobat3\ReadOS2\license.pdf" (part of the sixth, or last
record).

Disregarding the five (5) place indentation at the start of each record (the indentation is used here
only to set apart this data from remaining portions of the help explanation), note that the first sort
field starts at character position one (1) and has a length of eight (8) characters. The table, below,
shows the starting position and the length of all five (5) sort fields:

     Sort Field  Starting    Field
          N       Position   Length

          1            1            8
          2           10            6
          3           17            6
          4           24            5
          5           30           50

In the above example, assume that you want to sort on the first, third and fifth sort fields. If so, enter
1, 17 and 30 into the "Starting Character N" parameter entries, respectively, for those fields on the
Main window graphical user interface (GUI). Similarly, enter 8, 6 and 50 into the "Sort Field Length"
parameter entries for those fields. Do not change the values of the "Starting Character N" and the
"Sort Field Length" entries for any other sort field. Leave all of them at the default value of zero (0).

Notice that the "Starting Character N" parameter entries are self-correcting. That is, as you enter
values for a given sort field, the "Starting Character N" values for all fields, after the one you are
changing, adjust as needed. Specifically, the "Starting Character N" value for sort field (N + 1) must
always be greater than or equal to the sum of the starting character and the field length values for
sort field N.

Next, set the desired sort type and the desired sort order for first, third and fifth fields. For the sort
type you have the choices of "C"haracter sensitive, "D"ate, character "I"nsensitive, "N"umeric and
"T"ime. Because the first sort field is date data, cycle the "Sort Type" spin button for that field to "D".
Similarly, the third field is numerical data. Therefore, set its "Sort Type" spin button to "N". The fifth
field has alphabetic data. Set its "Sort Type" spin button to "C", or to "I", per your choice. Next, choose
the sort order for the three fields. Set each to "A"scending, or "D"escending, per your choice, by exercising
the appropriate spin button. Do not change the type or order spin buttons for any other field. Leave them all
at their default values (blank).

Finally, set the sort progression spin buttons for all ten (10) fields. The sort progression tells the program
the order in which you wish to sequentially sort, or progress, through the sort fields. This feature allows you
to independently arrange the ordering of the sort fields in the input data. The fields do not have to be in the
same of order in which you desire to sequentially sort them. This independence allows you greater flexibility.
For example, you can sequentially sort the same data two or more different ways, without having to change the
ordering of the sort fields in the input data in between each set of sorts.

For the illustrative example of sorting on the first, third and fifth fields, suppose you wish to sort on
the file path data first, then the date and finally the file size (fields 5, 1 and 3). If so, set the progression
values to 1, 2 and 3 for fields 5, 1 and 3, respectively. Next, set the progression values on the remaining fields
to unique values. All of the progression values have to be unique. You cannot have the same progression value for
any two or more sort fields. Please consult the information on enabling the "SORT" button for a detailed discussion
on this. Press the button entitled, "Enabling the "SORT" button" to view that information.

In summary, if you use an ASCII file as your input data, set the sort parameters for the "Starting Character N",
the "Sort Field Length", the "Sort Type" and the "Sort Order" parameter entries. Set them only for those fields
that you wish to sort. Leave these parameter entities at their default values (0 or blank) for fields that you
are not going to sort. Next, set the sort progression values for the fields you are going to sort. For the field
that you want to sort first, set its sort progression value to 1. For the field that you want to (sequentially)
sort second, if any, set its progression value to 2. If there is a third sequential sort field, set its progression
value to 3. Etc. Finally, set the sort progression values for all the remaining (up to nine (9)), unsorted fields,
to unique values. All ten fields must have unique sort progression values, even if you are not sorting over all ten fields.


Directly below, please find the discussion for input data created from the REXX SysFileTree function.

When you elect to use internally prepared REXX SysFileTree data, the Main window GUI defaults to
showing the parameter entries for only the first six (6) sort fields. The entries for the last four (4)
fields are hidden. The reason for this is that program creates only six (6) sort fields for this type of
input data. The program also labels the six (6) fields, so that you can identify the type of data in each
one. The first field contains file, or folder creation dates. The second field contains file or folder creation times, the
third contains file or folder sizes, in bytes, while the fourth contains file or folder path
information. The fifth field contains filenames or folder names. Finally, the sixth field contains file or
folder extended attribute data.

Next, note that the GUI shows zero (0) values of the "Starting Character N" and "Sort Field Length"
parameters. Also, it disables the entries for these parameters (you cannot change them). The reason
for this is that the program internally calculates these values, for all six (6) sort fields. All you have to
do is set the values of the sort type, sort order and sort progression parameters for the fields that you
wish to sort. Again, if you are not sorting on a particular field, leave its sort type and sort order parameters
at the default values (blank). However, the sort progression values must be unique, for all six (6) fields,
regardless of whether or not you are sorting over all of them.


NOTE: If you toggle between the two input data types, the program remembers the parameter values
that you set for each type. Therefore, when you toggle back to a given data type, it restores all
of the parameters to the values that previously existed, when you last toggled away. You can reset
the parameters back to their default (program opening) values by pressing the "Reset" button on the
Main form. Press it, when you have elected to sort an ASCII data file ("No" Radio Button selected),
to reset the parameters for an ASCII data file sort. Press it, when you have elected a SysFileTree
sort ("Yes" Radio Button selected), to reset the parameters for a SysFileTree sort.




                            **********Help on Executing Sequential Sorts**********

This program enables you to perform sorts within sorts (sequential sorts). If you are using an ASCII file,
you can perform up to ten (10) total sorts, nine (9) of them sequentially. If you are using data created
from the REXX SysFileTree function, you can perform up to six (6) sorts of the data (up to five (5) sequential
sorts).

An example will help explain the concept of sequential sorts. Suppose you wish to sort the following
"properly prepared" data:

    6/13/95  2:10a  47391  ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\COBO____.PFB
    5/16/97  1:02a  64327  A-HRS C:\Acrobat\Acrobat3\ReadOS2\aapdf.dll
    12/18/96 10:55a 278026 ----- C:\Acrobat\Acrobat3\ReadOS2\acrobat.pdf
    6/14/95  2:10a  684    ----- C:\Acrobat\Acrobat3\ReadOS2\fonts\pfm\ZY______.PFM
    5/16/97  1:24a  37376  A---- C:\Acrobat\Acrobat3\ReadOS2\del_ini.exe
    12/18/96 3:54p  9305   ----- C:\Acrobat\Acrobat3\ReadOS2\license.pdf

This data contains 5 sort fields. The first field contains date information, such as "6/13/95" and
"10/14/96". The second field contains time information, such as "2:10a" and "1:02a". The third field contains
numerical data (file sizes, in bytes), such as "64327" and "684". The fourth field contains extended
attribute data and the fifth field contains file path data ("C:\Acrobat\Acrobat3\ReadOS2\license.pdf",
for example).

Assume that you wish to first sort by dates (in field 1), next by time (field 2) and finally by file size
(field 3). If so, notice that the data contains 2 sets of records that have identical dates. That is, the
second and fifth records have the date: "5/16/97" and the third and sixth records have "12/18/96".
Therefore, after the program performs the date sort, the two records containing "5/16/97" will be
positioned together, one right after the other. After all they have the same dates and so the sort will
place them together in sequence. Similarly, the two records containing "12/18/96" will be positioned
together, one right after the other.

The program will next "attempt to perform the time sort". It will look for date sorted records that
have the same dates. If it finds any, it will subsort them by time. That is, it will only disturb (sort)
records with the same dates. Anything else retains its position resulting from the date sort. In a similar
fashion after completing the time sort, the program will look for records that have the same time
values. If it finds any, it will subsort them by file size. It will not disturb anything else.

This is the concept of sequential sorting. Note that it does not make any sense to sequentially sort
any other way. This is the only type of "next sorting" that does not potentially undo the currently
completed sort.

Referring to the above example, the program subsorts (rearranges) the two records that have
"5/16/97" date values and the two records with "12/18/96" date values. If the date sort is ascending
and the time sort is descending, for example, then the program will flip (exchange) the positions of
the two records with "5/16/97" dates and the two records with "12/18/96" dates. Alternatively, if
both sorts are ascending, the time sort will result no change to the positions of these records.

Next, after completing the time sort, the program looks for identical time values as the source for
applying a subsort on size (file size). In this particular example, all the time values are unique. Therefore,
a size sort is not performed. Instead, the program outputs the sorted results.

Summarizing the above explanation, the program performs the first sort normally. It produces an interim
result where the records are repositioned (rearranged), according to the ascending, or descending, values
of the data in the first applied sort field. For a next (sequential) sort, the program looks for sets of
records that contain identical values in the first applied sort field. If it finds any, the program then
subsorts the records in each of those sets. It subsorts (rearranges) the records in each set, according
to the ascending, or descending, values of the data in the second applied sort field. In a similar fashion,
if the program is evaluating the (N + 1)'th sort, it looks for sets of records in the N'th sort that contain
identical values in that N'th applied sort field. If it finds any, the program subsorts those records, only.
It subsorts according to the ascending or descending values of the data in the (N + 1)'th sort field. If
there are no sets containing identical values, the program ends the sort and outputs the results. Alternatively,
if the program evaluates and executes all requested sorts, it outputs the results at the end of the last sort.


To perform a sequential sort, you must complete the following tasks:

     1.     Specify the sort parameters for the two (2) or more fields that will be sorted.
     2.     Specify the sequencing of the sort through the two (2) or more sort fields.
     3.     Ensure that sort progression parameters have unique values for all sort fields.

To understand the first task, please review the information in the section entitled, "Help on Specifying
Your Sorting Parameters", directly above.

To complete the second task, specify the sort progression parameters for the 2 or more fields that will
be sorted. In the above example, the progression parameters would be 1, 2 and 3, respectively, for sort
fields 1, 2 and 3 (the date, time and size fields). If instead, you wish to sequentially sort the file path,
then the date, then the size and finally the time, set the progression parameters to 1, 2, 3 and 4 for
sort fields 5, 1, 3 and 2, respectively.

To understand the last task, review the information section entitled, "Help on Specifying Your Sorting
Parameters".


Sequential sorts often consume significant amounts of time and computer resources. The following
statistics from my computer may be helpful. It has an Intel Pentium 4, 3.2 GHz central processing unit
(CPU), 1 gigabyte (GB) of random access memory (RAM) and a 320 GB hard drive. The data sorts are
all the same: an ascending date sort of SysFileTree data, followed a sequential descending time sort
and finally a sequential descending size sort:

     N of records        Time required to finish the sorts (seconds)
          270                                    4
          558                                    9
          885                                  160

Unfortunately, the amount of time to complete sorts is not linear with the number of records. Also, as
resources are depleted, the computer really slows. Finally, REXX scripts are not particularly forgiving
on memory resources. They use a lot of memory and often do not release all of the memory after
execution. After several sorts you may find that the computer, and/or this program, do not behave
correctly. The program might not execute. It might sort incorrectly. Your computer could show evidence of
memory problems after using Sort. If any of these occur, reboot the computer to release the memory from
REXX usage.

NOTE: Your computer may or may not be more capable than mine.




                              **********Help on Enabling the SORT Button**********

The "SORT" button will remain disabled until you have correctly specified the sort parameters and located
a data source for the program to sort.

For an ASCII data file, that means having nonzero values for the "Starting Character N" and the "Sort
Field Length" entry positions and having non-blank values for the "Sort Type" and "Sort Order" entry
positions for at least one sort field. Also, the sort progression values must be unique across all ten
(10) sort fields. Finally, you have identified a specific ASCII file as the data source.

For data created from the REXX SysFileTree function, the "Sort Type" and "Sort Order" entry positions
must have non-blank values for at least one sort field. Also, the sort progression values must be
unique across all six (6) sort fields. Finally, you have identified a specific drive or folder as the data
source. For example:


        Field Start Field  Sort  Sort Field
          N   Pos   Len   Typ   Ord  Prg

          1
          2
          3
          4      X      X      X      X      X
          5
          6
          ..
          ..
          ..
         ...

After you press the "SORT" button the program completes the desired sort, or sorts, and places the
results in the following named file:

          SortedResults_MMDDYYYY_HHMMSS.TXT

Within that name, "MMDDYYYY" is the file creation date, with "MM" being the two (2) digit month
number, "DD" is the 2 digit day number and "YYYY" is the four (4) digit year number. "HHMMSS" is
the file creation time, with "HH" being the 2 digit hours, "MM" is the 2 digit minutes and "SS" is the 2
digit seconds. The program saves "SortedResults_MMDDYYYY_HHMMSS.TXT" to the same location as
the source input data. For example, if the source is an ASCII file, the program saves the results
to the same folder as that file. If the input is from the REXX SysFileTree function, the program saves
the result to the folder used in the SysFileTree execution.

HCM, 10/12/2012.
