HyperWais 1.7:
--------------

Welcome to HyperWais, a Hypercard stack for searching Wide Area
Information Servers.



What is HyperWais:
------------------

HyperWais is a hypercard stack which can be used to access Wide Area
Information Servers (WAIS) on the internet, currently there about about
300 public access servers available.

HyperWais allows you to connect up to any number of servers, search
them, download documents and view/save them either with built-in handlers
or using other applications to view them. Support is also provided
for doing relevance feedback. All this functionality is provided within
hypercard in the form of a stack, in fact there are two stacks, one
built for Macs with small screens and one built for Macs with larger
screens. Because the search interface is built using Hypercard, users
can completely remodel it to their taste.

Two versions of the product are provided, one (HyperWais.sea.hqx) is
aimed at users who just want to use the system, and the other
(HyperWais.src.sea.hqx) includes all the C source code used to build
HyperWais for those of you who want to see hows it's built.



Where can I get HyperWais:
--------------------------

HyperWais can be obtained by anonymous FTP from:

mendel.welch.jhu.edu:/pub/fs/HyperWais.sea.hqx,
mendel.welch.jhu.edu:/pub/fs/HyperWais.src.sea.hqx,

the internet address for mendel is [128.220.59.42],


or from:

sunsite.oit.unc.edu:/pub/wais/Mac/HyperWais.sea.hqx,
sunsite.oit.unc.edu:/pub/wais/Mac/HyperWais.src.sea.hqx,

the internet address for sunsite is [152.2.22.81].

HyperWais.sea.hqx contains the User Distribution and
HyperWais.src.sea.hqx contains the Source Code Distribution.



What does HyperWais cost:
-------------------------

Nothing, but be sure to read the COPYRIGHT file to see what the 
restrictions are.



What is included in the User distribution:
------------------------------------------

After you have uncompressed the archive, you should find:  

- This file (named README).

- The copyright file (named COPYRIGHT).

- A Hypercard stack called HyperWais, which is a sample stack for
searching WAIS databases. This stack contains a set of XCMDs which
allow the stack to communicate (via Apple Events) with the "Wais
Listener". There is also another stacks called HyperWais 12 for 12"
monitors.

- A application called "Wais Listener", this is the Faceless Background
Application (FBA) which allows the Hypercard stack to communicate with
WAIS servers. This application just sits in the background and listens
out to Apple Events. All you need to do is start it up. Note that the
"Wais Listener" will grab a chunk of memory (about 450K) which will be
added to the system software in the "About this mac" box.

- Another application called "Wais Listener.debug", this is the same
application as the "Wais Listener" but will have a visible debug window
which will list out all the events/data received and events/data
returned. You may want to use this application to see what is going
on.  Both "Wais Listener" and "Wais Listener.debug" create log files
which can be looked at with any text editor.

- A folder called wais-sources where HyperWais stores the WAIS source
description files.

- A folder called wais-documents where HyperWais stores some WAIS
document files.

- A folder called wais-questions which does nothing at this time.

- Dont forget to read the release notes located in the Release Notes
folder, these list out all the changes that were made with each
version of HyperWais.



What is included in the Source distribution:
--------------------------------------------

- All that is included in the User Distribution.

- All the source code (there is a lot and I have yet to list it).



Other software you need to run HyperWais:
-----------------------------------------

To run HyperWais you will need to run system 7.0, Hypercard 2.1 and
MacTCP 1.1. Hypercard will have to be allocated 1500K of memory, this
is done using the "Get Info" menu in the Finder.

The Wais Listener should have about 450K of allocated to it.

If you want to compile the source code, you will need Think C 5.0.X ( There
is a bug in 5.0.3 and I would not recomend using it ), and the MacTCP
toolkit from APDA.  The software was built with the standard library
distribution from Symantec, but you will have to recompile them with the 
4 byte integers option set, ( you may well be able to compile the application
with 2 byte integers set, but you will need to recompile *all* the code in the
distribution software).
Note that I have been very specific about my integers, so compiling
with either 2 byte integers or 4 bytes integers should make no difference.



Starting up:
------------

To start up you need to launch the "Wais Listener" application, then
start HyperWais. HyperWais will need the wais-sources folder and the
wais-documents folder in the folder it is located in (these are in the
archive and should be created automatically). Note that the "Wais Listener"
needs MacTCP to communicate with wais sources.  You may want to place the 
"Wais Listener" in the startup folder located in the system folder. 
This will ensure that the "Wais Listener" is started up everytime you 
start up your mac.



Some limitations:
-----------------

The "Wais Listener" will support any number of connections, any number
of open sources per connection, number of document headlines per
connection and any number of relevance feedback entries per
connection.  The main limitation imposed is the amount of memory
available to the "Wais Listener'. The connections can be opened by
clients located either on the same macintosh as the "Wais Listener" or on 
a different macintosh. This feature would enable you to set up a 
"Wais Listener" gateway on one macintosh with a connection to
the Internet and have a number of other macintoshs using appletalk to
connect up to that Wais Listener.



Technical Overview:
-------------------

The are three components to the HyperWais software:

- There are a set of C routines which handle the MacTCP communications
and the WAIS protocols. These can be linked in with any other
applications which want to use WAIS.

- On top of the C routines, there is the module that handle the Apple
Events and maps them to the C routines.

- There is also another Apple Event module which deals with the
communication between the client program and the "Wais Listener".



Below is a diagram of how the software is layered. There are a set of
basic routines which support basic services to wais servers via
MacTCP. These routines provide very basic services such as connection,
disconnection, init, query and downloading data. The glue routines
provide an abstracted view of the basic routines and allow a user to
access wais services without having to worry about the protocol and
MacTCP. These are the routines that someone would use to integrate wais
in their products.

There is an FBA (called the "Wais Listener") which will listen out to
apple events and call the appropriate glue routines. This FBA can
either run on the same mac as the wais client (using the FBA that is)
or on another mac. The FBA will support any number 