*------------------------------------------------------------------*
|    NAME:     SS (STRINGSEARCH)                                   |
|    FUNCTION: Search for a String in Files                        |
*------------------------------------------------------------------*

Provides  an  easy  method  of finding an ASCII or HEX string in any
file in any directory.  The string may be either case  sensitive  or
insensitive ASCII, or may be a HEX byte sequence.  The search may be
global  or  limited in paths and filespec. Far more useful than FIND
or LOCATE.  May be also used as a quick file finder  by  either  not
specifying a string, or by using the /B option. Invoked by:

      SS /?             ;(shows command format and options)
  or  SS [/options] ['string'] [[D:][path][filespec] ... ]
  or  SS [/options] ["string"] [[D:][path][filespec] ... ]

e.g.   SS  /c/s C:\*.ASM '"string"' will search all ASM files on all
directories on drive C for "string" in upper or lower case.

Note that multiple filespecs may be included on each command line.
e.g.  SS /C/S '"string"' C:\X*.XYZ B: will search all directories on
C: and from current directory on B: for "string" in the files X*.XYZ
without case sensitivity.

<ESC>  will  quit  scanning  current  file  and  go  to next file in
sequence. Any other key will pause/continue scanning and listing.

/7 - 7-bit comparisons
This is the default mode.  It may be used in conjunction with the /H
option   to  force  hexadecimal  byte  sequence  comparisons  to  be
insensitive to the top bit.  If used, it must follow the /H option.

/8 - 8-bit comparisons
Normally SS will strip the top bit of all bytes before  comparisons.
The  /8 option preserves the full 8-bit comparison and shows graphic
characters.  To test for 8-bit codes  use  the  <ALTnnn>  method  to
define the codes within the string.

/B - Brief mode (no string display)
If only a list of the files containing "string" are required, the /B
option will inhibit the string information.

/C - Case ignored
Normally  the  files  being searched will look only for an identical
match to "string".  e.g. the sequence HowiE in a file will not match
"Howie".  However, the /C switch option will allow either upper case
or lower case to be matched.  If the /C switch option is  used,  the
file display will be converted entirely to lower case.

/Fc - Filler character
The "filler" character is currently set to 0FAH (the  small  centred
dot).   It  can be altered to any other printable character with the
option /Fc, where "c" is any printable character.  Alternatively, it
can be permanently patched in SS.COM at location 0103H.

/H - Hex strings
String  sequences  are  normally  in  7-bit  ASCII  format.   If   a
hexadecimal  byte  sequence (i.e. non-ASCII) is required, use the /H
option,  placing  the  HEX  codes  (0-9,A-F)   within   the   string
delimiters.   (A-F may be upper or lower case).  This mode forces /8
(8-bit) mode, but  can  be  disabled  by  following  with  /7.   For
example,  to search for the sequence 4F,7F,3C,01 in all COM files in
the current path and all its subdirectories, but not show the string
results, use the command:

      SS/h/s/b *.com "4f7F3c01"

/Mn - Matches each file
Normally every match will be flagged in every file.  The  /M  option
will  limit  the  search  to  the first match in each file.  The /Mn
option (where n=1..9) will show the first "n" instances  of  matches
in each file.

/N - No unused paths displayed
Normally,  screen  output contains repeated carriage returns without
linefeeds as files are searched.  This results  in  overprinting  or
excessive  file lengths with redirection.  To limit path displays to
only those containing matched files, use the /N option.

/P - Pause each page
This option will cause the output to be suspended at the end of each
full screen.  Very useful on faster PCs.

/S - Subdirectory paths searched
By  default,  SS  will only use the current (or defined) path on the
specified drive.  All subdirectory  paths  below  the  path  can  be
searched if the /S switch option is selected.

/Tn- Text mode display
Selecting the /T switch option  will  display  the  matching  string
(where  possible)  as  three  lines  of  text,  with the middle line
containing  the  matching  string.   Selecting   /Tn  (n=0..9)  will
select 0..9 lines of text each side (about) the matching string

/U - Unix file input
For  text  mode  display,  the end-of-line character is <CR> and the
new-line character <LF> is ignored.   The  /U  option  reverses  the
order  of these comparisons and automatically selects /T option.  If
a  /Tn  option   other   than  the  default (1 line) is required, it
must be specified after the /U option.

/W - White space compression
The /W switch option will cause all  TABs  to  be  replaced  with  a
single  space,  and  all instances of two or more consecutive spaces
(or TABS) to be treated as a single space.

/B:dd/mm/yy - newest date "Before"
This option allows a newest date to be specified.  Any file of newer
date  will not be searched.  Format for the date must be /B:dd/mm/yy
and have a trailing space if other parameters follow.
e.g. SS /B:31/12/92 *.asm

This option does not affect the status of the /B option.

/D:dd/mm/yy - oldest date "Dated"
This option allows an oldest date to  be  specified.   Any  file  of
earlier  date  will  not  be  searched.  Format for the date must be
/D:dd/mm/yy and have a trailing space if  other  parameters  follow.
e.g. SS /D:1/1/92 *.asm

When  combined with the /B:date option, this allows search of only a
restricted date range.  e.g.  SS /B:31/12/92  /D:1/1/92  *.asm  will
only search *.ASM files with date ranges in 1992.


Pressing <ESC> will cause SS  to  skip  to  the  next  file  in  the
directory  at  the  next  occurrence  of a match.  The output can be
paused at any time by pressing any key.  A second keypress  restarts
the  output.   This  action  also  resets the page counter if the /P
option is in effect.

Hint:  to get single match outputs, touch the <SPACE> bar as soon as
the program starts.  Then restart the output by  pressing  any  <Fn>
key.    The   function  keys  generate  two  "keystrokes"  in  quick
succession, resulting in an immediate stop at the next output.





On Exit from SS, the ERRORLEVEL will be set to:

      0 if No string matches found
      1 if string matches found
      2 if /? Help was requested
      3 if an Error was detected in the command or program


                 NOTES ON COMPARISONS AND DISPLAYS

When  the /C case insensitivity option is  selected,  the  file  and
string  data  is  first scanned and any UPPER CASE characters (A..Z)
are converted to LOWER CASE.

If  the  /8  option  is also selected, then the full 8-bit codes are
retained, so case insensitivity will only occur with the strict A..Z
characters (i.e. 41H to 5AH) and not their equivalents with the  top
bit set (i.e. C1H to DAH).

For  display  purposes some characters are filtered out and replaced
with the filler character.

If no string is specified, all files matching the filespec  will  be
displayed as though the /B option were selected with a NUL string.

SS  now  automatically  detects  display lines count and changes the
number of lines per paged display to suit.  Each display page  shows
1 line less than the lines per page.

The /H option forces /8 to give genuine binary searches.  At the end
of the search, the match string is shown in HEX  format  within  the
delimiter  used,  and  also  in a filtered ASCII equivalence between
parenthesis.

The filespec now uses the ambiguous format "x*" conversion to "x*.*"

Author:         howard Harvey
Date Released:  5/MAY/94

