                                TSP Manual

Text Search and Print V2.21:
Searches for a string of text in a file or files.
Optionally sends results to the printer or to a file.

TSP [@][drive:][path]filename target_string [/C] [/AW] [/AP] [/AE] [/1] [/B]
	 [/S] [/X:[@]file.ext] [/L:outfile.ext] [/A:attributes]

  [drive:][path]filename   File specification including wildcards.
  @[drive:][path]filename  Search list of file specification(s) in filename.
  target_string            String to be searched for.
  /C                       Use case-sensitive search, by default ignores case.
  /AW                      Automatically write results to a file.
  /AP                      Automatically send results to the printer.
  /AE                      Automatically edit files when a match is found.
  /1                       Find first occurrence of target_string in each file.
  /B                       Write results to Brief .APX file in First-Only mode.
  /S                       Searches subdirectories under specified directory.
  /X:[@]file.ext           Excludes subdirectories from subdirectory search.
  /L:outfile.ext           Name of output file. Default name is FOUND.TSP.
                           The extension is always .APX when /B switch is used.
  /A:attributes            Also searches files with the specified attributes.
                           Attributes can be H (hidden) and/or S (system).

Options can appear in any order on the command line.
(Can use - instead of / and options are not case sensitive).

The easiest way to use tsp is just to specify a file spec. and what you are
searching for. Some examples:

        TSP *.foo bar
        TSP *.txt "foo bar"
        TSP *.c \"ok\"        ( is looking for "ok", "OK", "oK" and "Ok" )
        TSP "*.c *.h" foobar  ( look for foobar in *.c, then in *.h)

Note in example two that if the pattern you are looking for includes spaces,
it must be enclosed in quotes.  If the pattern you are looking for contains a
quote, the quotes must be preceded by backward slashes as in example three.
To search more than one file spec, enclose them in quotes with a space, tab
or comma separating them as in example 4.

If you ran example 3 from the D:\C700\FILES directory you might see something
like this (it loses something without the colors).


                             Text Search & Print

Search For: "OK"

File Name : D:\C700\FILES\JSI_CONV.C

Match Found at Line #   649
--------------------------------------------------------------------------------

   ushort x,left,right,lastfgd,newfgd;
   ushort oldtop,oldleft,oldbottom,oldright;
   ushort top = 8, bottom = top+4;
   int lastcursor, retval;
   long lastbgd,newbgd;
   static char *ok_msg = "OK";
   char *sScrn;

   lastfgd = _gettextcolor();
   lastbgd = _getbkcolor();
   oldpos = _gettextposition();



   Edit  Continue   Next file   Next Subdirectory   Write to file  Print  Quit

The string "OK" would be highlighted and 5 lines before and 5 lines after the
matched line are displayed.  If your screen mode is set for 43 or 50 lines
then 12 lines before and 12 lines after matched line are displayed.  At this
point you have several options.  Press the highlighted letter of the desired
option (usually the first letter) to execute it or press the Esc key to quit.

Edit: Opens the current file in an editor.  The default editor is Brief, but
      if you wish to use another editor, set the TSPEDIT environment variable
      to the name of your editor.  For example to use the DOS editor:

		set TSPEDIT=EDIT

      TSP parses the TSPEDIT environment variable and substitutes the current
      file name for %f and the current line number for %l.  If %f is not
      found in the TSPEDIT variable, the current file name is appended to
      the end of the command string.  Here are some examples, the current
      file is foo.txt and the current line number is 123:

	no TSPEDIT variable		will run B foo.txt -m"goto_line 123"
	set TSPEDIT=B %%f		will run B foo.txt
	set TSPEDIT=B -g%%l		will run B -g123 foo.txt
	set TSPEDIT=EDIT %%f /B     	will run EDIT foo.txt /B
	set TSPEDIT=Q %%f -n%%l		will run Q foo.txt -n123

      Note: when using the DOS set command, %%f will yield %f in the actual
      environment variable.

      When you are done editing the file TSP will not return to that file,
      but will continue searching with the next file meeting the file
      specification.

      The TSPEDIT environment variable doesn't have to be set to an editor.
      One TSP user sets TSPEDIT variable to a batch file. In this batch
      file he checks the extension and if it is .htm the file is opened with
      the Lynx browser, otherwise the file is opened with VIM.

Continue: Will resume search for target string in the same file, on the next
          line, unless the /1 option was used; then Continue will be the same
          as Next file. The /1 option is most useful with the /AP or /AW
          options (see below).

Next file: Will resume searching in the next file meeting the file spec.
           and ignore the rest of the current file.

Next Subdirectory: If the /S option was used, will resume searching in the
		   next subdirectory and ignore the rest of the files in
		   the current subdirectory.  Subdirectories listed with the
                   /X option (see below) will be ignored.

Write to file: If the /B switch is not used it will write to the
               file specified by the /L switch, or to FOUND.TSP if
               no output file is specified.  The file name and line number
	       are output on one line followed by the matching line on the
	       next.  For example:

D:\C700\FILES\JSI_CONV.C line 649
   static char *ok_msg = "OK";

               If the /B switch is used, it will write to the
               file specified by the /L switch, or to FOUND.APX if
               no output file is specified, in the following format:

D:\C700\FILES\JSI_CONV.C ;|D:\C700\FILES\JSI_CONV.C

               This is the format required by the dBrief macro package
               for its APX feature.

Print: Same as Write to file except output is directed to stdprn.
       (Normally LPT1).

Quit: Stop running TSP.


Other command line options:
Note: If you specify more than one option there must be a space between
options. For example:

         TSP *.prg net_use -b -aw /c

@filename.ext: filename.ext contains a list of file specifications each of
               which are run through TSP in turn. Default extension is .CLP
               for filename.ext and .* for file names inside filename.ext.
               For example, if you entered:

               TSP @my_clp fopen

               and my_clip.clp contained:

                main
                sub1
                \clipper5\common\laser.prg

                TSP would search for the pattern fopen, without regard to
                case, in main.*, sub1.* and \clipper5\common\laser.prg.

/C: Specifies a case-sensitive search, normally case is ignored during
    searches (everything gets converted to uppercase).

/1: Stop searching the current file after the first match of the search
    pattern. If using /AW or /AP TSP will go directly to the next file,
    otherwise will bring up the main screen before going to the next file.

/B: Writes to file or printer will be in dBrief APX format. Proceeds to the
    next file after writing.

/AW: Writes hits to the appropriate file without bringing each hit up
     on the screen.  The format written to the file is discussed above under
     Write info to file.  Use with the /B switch to create .APX files quickly.

/AP: Writes hits to the printer without bringing each hit up on the screen.
     The format written is discussed above under Write info to file.
     Use with the /1 switch to only print one match per file.  You
     cannot use the /AP switch and the /AW switch at the same time.  Also,
     /B cannot be used with /AP.

/AE: Opens a file in an editor whenever a match is found without bringing
     each hit up on the screen. See Edit section above. Options /AW or /AP
     can be used at the same time as /AE but only one entry will be written
     or printed per file (/1 mode).

/S: Searches directories under the current directory.

/X:[@]file.ext	Excludes a subdirectory or subdirectories from a subdirectory
		search.  If @ is not used, only the directory specified in
		file.ext is excluded.  If @ is the first character, file.ext
		contains a list of subdirectories each of which is excluded
		from the search.

/L:outfile.ext: Specifies name of output file. Default name is FOUND.TSP if
                the /B switch is not used and FOUND.APX if /B is used. The
                extension will always be .APX if the /B switch is used even
                if you specify another one.

/A:attributes	TSP will always search files and subdirectories with normal
		file attributes, but with this option files and subdirectories
		with hidden and/or system attributes can be searched also.
		Use /A:H for hidden files, /A:S for system files and /A:HS or
		/A:SH for hidden and system files.

New for version 2.21
Added automatic edit option.
Added attribute search option.
Changed the file open mode to stop sharing violation errors.
Prevented tsp from searching its own output file.

New for version 2.20
Added subdirectory exclusion from subdirectory search.
Added Next Subdirectory option.
Menu bar is now on bottom of screen if 43 or 50 line mode is used.  12 lines
are displayed on each side of the line with a match when 43 or 50 line mode
is used. (Thanks to Lechee Lai).
Fixed a bug where for files larger than 65,512 bytes, it would miss a match
if the 65,512 byte point was in the middle of a match.
Fixed a couple of minor display problems.
Search speed improved, especially for very large files.
Now only looks for one match per line.
When using Brief pressing E will now bring you to the proper line.
(Thanks to Lechee Lai). Note: If you are using an older version of Brief,
or another editor called B.EXE, set the environment variable TSPEDIT to B %f.
Added a call to Int 0x2F function 0x1680 to release time slice when waiting
for keyboard input (trying to be more Windows friendly).

New for version 2.19a
Fixed a bug where if the file specification was through a file,
(e.g. tsp @file.lst somestring)	and a file was edited, it wouldn't finish
processing the file specification file.

New for version 2.19
Can search more than one file specification at a time. Improved support
for editors other than Brief (requested by Lechee Lai).  TSP now parses
TSPEDIT environment variable and substitutes the current file name for
%f and the current line number for %l.

New for version 2.18
With previous versions if your search string started with - or / tsp
would flag this as an invalid option error.  Now it will handle it.

Paul Bosselaers
paulboss@erols.com
3/4/00

