				   SEARCH
			  UltraSoft Search Utility

WHAT IS SEARCH?

	SEARCH is a useful system utility that lets you search files for text
	patterns.  SEARCH was originally part of UltraTools, and has been
	donated to AMUS because of its popularity.  Full source is on the
	network.  This help file documents version 3.0 of SEARCH.

	SEARCH can handle both sequential and random files.

HOW DO I USE SEARCH?

	Using SEARCH is easy.  Type the word SEARCH from AMOS command level
	and press RETURN.  You should see the SEARCH option screen displayed,
	which looks like this:

                           ENTER SEARCH PARAMETERS

                       Files to search:
                 Text to search for: 1.
                                     2.
                                     3.
                                     4.
                                     5.
                        Output to file:
               Show matching filenames? Y
                   Show matching lines? Y
                    Wildcard character: ?
              Matches to list per file:
                           Ignore case? Y
                 Find mid-word matches? Y
                    Ignore white space? N

	The search parameters are discussed below.

	To start the search, press TAB.  To abort the search, press ESC.

BATCH SEARCH

	Another way to use search is from AMOS command level.  If you
	specify command line arguments, you can bypass the option screen.

		.SEARCH {output=} files text

	This method is useful for such things as command files and automated
	searching, but has the drawback that you are stuck with the default
	parameter settings, and can only specify one text string to search
	for.

SEARCH OPTIONS

	Files to search:

		This is where you specify the files that are to be
		searched.  This is a wildcard specification.  Below are
		sample file specifications:

			*.M68		CUST.*
			ALL:*.WRT[]	DSK0:AM????.M68[10,2]

	Text to search for:

		These five fields let you specify search text.  Enter one
		or more lines.  As SEARCH finds a line in a file containing
		one or more matches to your search text, it will display
		the line.

	Output to file:

		Leaving this field blank outputs to the terminal only.  If
		you specify a filename here, the results of the search will
		be output to this file.  The default extension is .LST.

	Show matching filenames?

		This option only has meaning if you are outputting to a
		file.  If you answer Y)es, the names of matching files
		will be output to the list file.  If you answer N)o, only
		matching lines of the source file will be output, without
		filenames.

	Show matching lines?

		This option only has meaning if you are outputting to a
		file.  If you answer Y)es, each line that contains a match
		will be output to the list file.  If you answer N)o, only
		filenames will be output, without matching lines.

	Wildcard character:

		This character lets you put wildcards in your search text.
		For example, if the wildcard character is a question mark,
		and your search text is LA?D, SEARCH would match all of
		the following:

				LARD	LAUD	LANDING

	Matches to list per file:

		Normally, SEARCH goes and finds every match in each file
		it searches.  If you specify a number in this field, SEARCH
		will stop after finding that many matches in a file.  For
		example, setting this field to 1 will cause SEARCH to go
		on to the next file after finding a single match.  This is
		sometimes useful when you don't care about the number of
		matches and just want the filenames, as fast as possible.

	Ignore Case?

		This option contols whether or not SEARCH takes upper and
		lower case into consideration.  If the default setting of
		Y)es is in effect, case is ignored.  If this field is set
		to N)o, only exact case matches are found.  Example:

				Search Text = Alpha

		In File			Set to Y)es	Set to N)o
		-------			-----------	----------
		ALPHA MICRO...		match		not a match
		In AlphaCALC, you...	match		match

	Find mid-word matches?

		If this field is set to N)o, only words beginning with
		your search text will be located.  If this field is set
		to Y)es, all occurrences of your search text will be
		located.  Example:

				Search Text = WRITE

		In File			Set to Y)es	Set to N)o
		-------			-----------	----------
		Each disk write is...	match		match
		If AlphaWRITE can't...	match		not a match
		writer's block		match		match

	Ignore white space?

		This field controls how spaces and tabs are considered
		during searching.  If this field is set to Y)es, spaces
		and tabs are completely ignored.  If this field is set
		to N)o, spaces and tabs are treated no differently from
		other characters.  Example:

				Search Text = cannot

		In File			Set to Y)es	Set to N)o
		-------			-----------	----------
		I cannot understand...	match		match
		I can not go on...	match		not a match
		The toucan notices...	match		not a match

STARTING THE SEARCH

	If you specify your search criteria on the command line, searching
	begins as soon as you enter the command and press RETURN.  If you
	are entering options interactively, searching begins when you press
	TAB.

	During the search, you see statistics on the top portion of the
	screen, filenames in the middle portion, and matching lines in the
	lower portion.  Filenames are shown in high intensity if they
	contain one or matches to your search text.

SEARCH COMMANDS

	While the search is underway, there are several commands you
	may enter.

		N - advance to next file

			Pressing N stops processing of the current file
			and moves on the next one.

		H - help

			Pressing H displays a summary of these commands.
			Press any key to continue with the search.

		SPACE - suspend

			Pressing SPACE suspends the search until you
			press another key.

		ESC - abort

			Pressing ESC aborts the search and returns you to
			AMOS command level.

COMPATIBILITY

	SEARCH is compatible with AMOS/L 1.3C and later.

LIMITATIONS

	SEARCH will not process more than 10,000 files, even if your
	wildcard specification indicates more.

	SEARCH requires approximately 130K bytes of memory to run.  This
	amount can be reduced, if necessary, by changing the FI.MAX
	symbol in the source code.

	SEARCH was written by David Pallmann.


.
