SRT.COM Version 1.1h

General comments:
     I	wanted a general purpose routine to sort on any character
position,  any	key length and able to recognize  membership in a
desired set.  A further requirement  was that  the sort had to be
performed  in memory but not be  limited to the few hundred lines
that can ordinarily be accomodated.

     The methodology chosen was to:
     1)   Recognise the key and save it in an array.

     2)   Associate  each  key with a descriptor node in  a  node
	  array.

     3)   Sort the keys,  moving only the node pointers to  avoid
	  excessive overhead.

     4)   Refer  to the 'K' switch to see whether the user wanted
	  only	the keys or the entire source line to be  written
	  to the destination device or file.  Note that for short
	  files  to be sorted beginning at the	first  character,
	  the  'K' option produces an in-memory sort of the whole
	  file,  which	is much faster than the random read  from
	  source to destination used otherwise.

Specific Examples:

A)   Sort a file, beginning at the first character and displaying
     results to the console only.

     A>SRT filename.typ

     Variations:

     A>SRT filename.typ ;()K,132
	will (if the file is short enough to fit in  memory) only
	take one pass over the input file.
     A>SRT outfile.typ=infil.typ
	will also output the results to outfile.typ.

B)   Sort a fielded file on the 10th through 15th characters.
     Note  that SRT counts zero-relative,  so the first character
     on  the  line  is interpreted as  line+0,	or  the  "zeroth"
     character.

     A>SRT outfile.typ=infil.typ ;10,5
	The key length is 5 characters long,  so that's what  you
	specify, not the ending character position.

Now it gets interesting:

C)   Sort a file with a key pointer string consisting of a  colon
     ":".  A listing of all files on all drives in the form:

     A0:FILE.TYP
     B15:WS.COM
     A2:AAAA.XX
	might be the form of your input list.

     A>SRT outfile.typ=infil.typ ;(:)
	will produce the desired sort on the filename field.

     A2:AAAA.XX
     A0:FILE.TYP
     B15:WS.COM

	If the desired sort was on the .typ field, then
     A>SRT outfile.typ=infil.typ ;(.)
	would be the command to produce

     B15:WS.COM
     A0:FILE.TYP
     A2:AAAA.XX

D)   If the list also contained header or other information  such
     as:

     DIRECTORY LISTING ON 26-JAN-86
     A0:FILE.TYP
     B15:WS.COM
     A2:AAAA.XX
	the output file would still be the same as above because
	does not contain either a colon or a period.

Variations:
     I	wanted	to  sort  only those  lines  which  met  the  key
     criteria,	but  begin the sort at an arbitrary point in  the
     line.

     A>SRT outfile.typ=infil.typ ;(.)O0,15
     meets  that requirement  by  defining  the  "O"ffset  as the
     first character in the line (remember,  it's  zero-relative)
     and  the  key  length  as	15.   As  before,  the	inclusion
     criterion was the presence of the period in the line.

Bugs:
     None  discovered  in version  1.1h - please report any to me
     post-haste!

Abnormal termination and recovery:
     In the event you abort during the output process, the output
     file  (if	any) is written to disk,  closed and  renamed  to
     yourname.$$$ to distinguish it from a successfully completed
     file.

Online documentation:
     The  following  is  a  screen  dump  of  the   documentation
     available by invoking SRT with no parameters.  The screen is
     cleared via the byte sequence described below.
			    SRT.COM Version 1.2a
Usage:
A>SRT OUTFIL.TYP=INFIL.TYP [/switches]
Switches take one of two forms:
			     /[offset],[keylen]
     where offset and keylen are numeric and represent the offset
     from the beginning of  the line and  the length  of the key,
     respectively; and
		/<skip string>[switches][,keylen][switches]
     where the "<" character can be any one of <,(,",',{ or [.	A
     matching right delimiter is required as shown in the example
     above.  A switch may occur after  the skip string either be-
     fore or after the	keylen parameter.  "C" in either position
     produces a contiguous skip-string request,  "K" says to save
     the  keys as output,  and "O" sets the offset value manually.
     The  default offset is the character following the last skip-
     string character.	Delimiter nesting  is  not allowed.   Note
     that in both cases the  keylen argument  is optional  and de-
     faults to 22 decimal.  SRT also  takes  three  special output
     devices;  LST:,  CON:  and PUN:  They  perform  as in PIP and
     STAT.   Reset 140h,  141h to disable source  display, process
     messages.	Set 142h for descending sort.  143h = switch char-
     acter storage  location.  Byte 144h  begins the  clear screen
     sequence, which is stored in the format: DB LEN CH1,CH2,..CH8
     To use lower case or other difficult/impossible characters in
     the skip-string,  use  the command  format "SRT <CMDLIN.FIL",
     where the first line  of CMDLIN.FIL consists  of the  desired
     command tail terminated by carriage return.

	  An Explanation of potentially confusing terms:


delimiter(s)	    any of the set <>,	(),  "", '', {} or [] are
		    valid delimiters

switch(es)	    the  switch character is the character stored
		    at 143h - sorry about the cryptic comment  in
		    the on-line documentation,	but I was running
		    out of space.

skip-string	    the  string (of length 0 to 127.  characters)
		    that is to be skipped.   The sort key  begins
		    at the next character position. Example:
		    Given the following lines in the file IN.FIL

		    MYFILEAAATYP
			MYFILEXXXTYP
		      MYFILEBBBTYP

			 the command line
		    A>SRT CON:=IN.FIL /(MYFILE)
		    would  sort  the three lines as if they  were
		    all  left-justified.   The reason is that  we
		    begin sorting on the character following  the
		    skip-string, in this case "MYFILE".  Thus the
		    output would be

		    MYFILEAAATYP
		      MYFILEBBBTYP
			MYFILEXXXTYP

		    Note that the indenting is preserved.

key		    the  characters  on which to  sort.   In  the
		    above example,  the keys were all of the line
		    after  "MYFILE",  or "AAATYP",  "BBBTYP"  and
		    "XXXTYP".

keylen		    length  of the key to use for  sorting.   The
		    default   is  22,	but  any  length  may  be
		    specified.	 Longer keys mean less lines  may
		    be sorted before you run out of memory.  This
		    will  not  be a problem until you get  up  to
		    over 1000 lines to sort if you stick with the
		    default length of 22.

LST:, CON: and PUN: these  are the same output devices listed  in
		    your CP/M manuals (see the PIP section).

		    Reset 140h, 141h to disable  source  display,
		    process messages.	Set 142h for descending
		    sort.  Byte 144h begins the clear screen se-
		    quence, which is stored in the format:

			 DB LEN,CH1,CH2...CH8  143h = switch

Byte 140h	    controls  the  display  of the input  file	-
		    patch it to zero to suppress the display.
Byte 141h	    controls the display of the process  messages
		    (ENTERING SORT ROUTINE etc)
Byte 142h	    is	set to zero in the distribution  version.
		    patch to non-zero for a descending sort.
Byte 143h	    is	the switch character.	I waffle  between
		    "/" and ";" - you may use any character there
		    you wish.
Byte 144h	    begins  the clear screen sequence,	which  is
		    stored in the format
		    DB	LEN	       ;length of string  to send
		    DB	CH1,CH2...CH8  ;chars to send (8 total 8)

command tail	    that  part	of the command line which  occurs
		    after the task name.  e.g. in the example

		    A>SRT OUTFIL.TYP=INFIL.TYP [/switches]
			  !------------------------------!

		    the  command line from the initial '!' to the
		    end of the line is the command tail.