AppleSearch ACGI supports two types of WWW client interfaces. The simplest uses the <isindex> search arguments passed from a WWW client like Mosaic or MacWeb to perform searches on an AppleSearch information source. There is a more comprehensive interface available that uses fill-in forms to collect search arguments from the user. To use the forms interface, you must access WebSTAR and AppleSearch ACGI using a WWW client capable of supporting forms. Netscape Navigator, MacWeb and Mosaic 2.0 both support forms.

AppleSearch ACGI is invoked by WebSTAR in response to a client's request for a particular URL. WebSTAR passes arguments to AppleSearch ACGI through custom AppleEvents. These arguments are obtained from the path and search arguments contained in the URL sent to WebSTAR. If you are unfamiliar with path and search arguments, you may want to read through the documentation and examples that come with WebSTAR.

AppleSearch ACGI uses these arguments to perform search operations with the AppleSearch server that it is connected to. The results are formatted into an HTML document that is automatically generated by AppleSearch ACGI and returned to WebSTAR (and then to the WWW client.) Much of the information in the generated forms can be modified by changing TEXT resources within the AppleSearch ACGI application.

http://your.host.addr/AppleSearch.acgi$SOURCES

This starts the AppleSearching process, presenting the user with a list of active sources available from the AppleSearch server that AppleSearch ACGI is communicating with. Selecting a server from the list will continue the process, prompting the user for search terms to look for in the selected source. After the user enters the search terms and starts the search, the gateway will return a list of documents that match the search criteria.

Each entry in this list starts with a row of asterisks, indicating the relevance level from 1 to 5, 5 being the best match. The title of the document follows, with the approximate size of the document listed last. Selecting a document from this list causes the gateway to retrieve the document and display it. The gateway is limited to returning 30K chunks of data, so large documents will be divided into multiple parts with a "Click here for more" link at the bottom of the page. This link will cause the next portion of the document to be retrieved.

http://your.host.addr/AppleSearch.acgi$FORM

This form attempts to match the user interface provided by the AppleSearch client as shipped by Apple. The different form elements are defined as follows:

FORM - starts the form interface. Takes no arguments.

SOURCES - starts the simple interface. Takes no arguments.

UPDATESOURCES - identical to SOURCES, but it causes AppleSearch ACGI to request an updated list of sources from the AppleSearch server, rather than using those cached in memory.

The next two commands are very risky to use "stand-alone", mainly because the source number and document number for particular AppleSearch sources and documents may be subject to change if you add new sources, or reindex an existing source. These path arguments are normally generated by the AppleSearch ACGI application on the fly, in response to user requests.

SEARCH,<source number>[?<keywords>] - If "?<keywords>" is omitted, this generates a page that prompts for search arguments for the AppleSearch source numbered "source number". If search arguments are present ("?<keywords>"), then the entire query is performed, returning the first 40 matches, ranked from best match to worst.

RETRIEVE,<source number>,<doc number>,<chunk size>,<offset> - retrieves the requested number of bytes (chunk size) from the specified document contained in the specified source, starting at the specified offset and continuing until "chunk size" bytes have been returned.

You may modify any of the text contained in these resources to suit your purposes, subject to the following restrictions:

Changing "GET" to "PUT" will cause the WWW client to send data to WebSTAR using the PUT method, which will allow up to 2K of search arguments to be passed from WebSTAR to AppleSearch ACGI.

You may modify the HTML resources, rearrange the form components, and otherwise mutate the TEXT resources. It is STRONGLY recommended that you perform this surgery on a copy of the original application.