VI.d.2 Shell searching
----------------------
Shell searching is a site-specific, database-specific search facility.  It is
very extensible as it is implemented in a DCL command file.  The command file
(and perhaps any program it invokes) interpret the search terms and index
specification provided by the client and construct a file which is literally
fed back to the client, containing 1-line link tuples representing the hits.
To define a Shell search, the path must specify a DCL command file with .SHELL
as its extension, as in:

	Path=7[search_engines]search_engine_1.shell

Any fixed parameters to the shell search should be included as part of the
path specification.  For example, using Bruce Tanner's indexed text search
engine:

	Path=7gopher_root1:[gopher.vms.server]search.shell -
		gopher_root1:[gopher.vms.server]server

The above specification results in the execution of the following DCL command
by the server on behalf of the client, where term1[,...] represents the
client's specified search terms:

	$ @gopher_root1:[gopher.vms.server]search.shell -
	_$ gopher_root1:[gopher.vms.server]server output -
	_$ "term1[,...]" "host" port "cfg"

Continuation as shown here is for clarity.  The server supplies the Path= text
first, invoking the DCL command file and supplying whatever parameters were
set up as constants within the Path= (in this case, only p1, an index
specification to search.shell).  The server then supplies a parameter naming
the output file where the shell search is to place its results.  This might be
p1, p2, p7, etc. depending on how many fixed parameters are supplied in the
Path= specification.  Next the server supplies, enclosed inside double quotes,
the client's terms for the search.  Again, these might be p2, p3, p8, etc.,
depending on how many fixed parameters were coded for the Path=.  Finally the
server supplies three parameters which may be used by the shell if needed.
These are a text string specifying the host name of the server, a numeric
value specifying the port the server is serving, and a text string specifying
the *device* part of the server's default data directory.  The last of these
may be used to verify the client should have access to the indexes being
requested by checking to insure they are within the gopher database area,
while the host and port may be used to supply default values as part of the
output link tuples.

The DCL command file is expected to interpret the supplied parameters and to
create the specified output file.  It is expected to populate the output file
with records, one record per search hit, of the form:

<character Object Type><TAB><Name><TAB><Path><TAB><Host><TAB><Port>

See III.a, Creating .LINKS, for a description of the values of these fields.

Note that server-specific selector strings may be passed back.  For example,
Bruce Tanner's search engine supplies link tuples which use the
server-internal R (range) object type to specify ranges within a single
document in the <Path>, while supplying the universal 0 (file) <character
Object Type>.  When the client selects one of the search result's menu items,
the server interprets the R object type in the <Path> and returns a segment of
a file, which the client will then display as if it were a file due to the 0
in the <character Object Type>.  Another application might search a set of
fielded records in a database, and actually return the *values* of the
individual matching records for the <Name>, while returning the same
"0filespec" for the <Path> for every menu item, resulting in the same file (a
help file, maybe, about the record supplied in <Name>?) being returned should
the client select any item in the search's result menu.

A file, [.DOC]ABOUT.BOOLEAN_KEYWORD_QUERIES, is supplied to provide a basis
for a document you might want to include a link to whenever you provide a link
to a Shell search using the QUERY.EXE search engine.  Boolean operators and
keywords are the heart of such a search, but it is not a given that your users
will understand what they are and how to use them. 

.