From: francois@welchgate.welch.jhu.edu (Francois Schiettecatte)
Subject: HyperWais 1.6
Organization: Welch Medical Library
Date: Thu, 7 Jan 1993 14:14:13 GMT



                     HyperWais 1.6 is here.


HyperWais is a Hypercard stack for searching WAIS (Wide Area
Information Servers).  It is available from mendel.welch.jhu.edu
[128.220.59.42] by anonymous ftp. The application is located in
/incoming/HyperWais.sea.hqx, and the source is in
/incoming/HyperWais.src.sea.hqx.



Hilites of this release include:


- Added support to allow users to define which applications
they want to launch when retrieving a particular document type.
This is done through the "Edit Applications" card, the user needs to 
fill in the wais document type, the file type (a default of '????"
is used if no file type is specified), an application (which 
is selected by using either the "select application" button or 
clinking in the application field) and clicking on the MacBinary
box to indicate whether the user wants to convert the document
from a macbinary format (as far as I know only one wais server
serves documents in a macbinary format, that being the sample
-pictures server). When the user has finished entering the
information, "save" can be pressed to add the entry to the table. 
If the document type is already handled by the stack (such as
TEXT, WSRC, WCAT and PICT),v the user will be asked whether they 
want to override the built-in handler or use the selected application. 
If the user chooses to override the built in handler, then the
application will be used to view a document and the file type 
will be used when saving a document. The handler which uses an 
external application to view the document will prompt the user 
for a file name for saving the document before displaying it. 
This facility allows the user to choose which applications to 
use to display documents and also allows the internal handlers 
to be over-ridden. This allows HyperWais to retrieve and display
any document type provided there is an application to view it
with. Currently the format of the table is not really very pretty 
and could be cleaned up considerably.

A couple of things I should mention here, some applications do 
not like to be opened with a document when they are already 
open (they beep at you) while other are better behaved and will
allow that. I have found that GIFConverter does not behave well
whereas JPEGView does, but I may well have an older view of 
GIFConverter. You will have to experiment for yourselves here
with your favorite applications.

- Added support for easier selection of sources  when adding
them to the source list. A dialog box will appear listing all the
sources in the wais-sources folder. This dialog box  allows
the user to select any number of sources using the shift-key
to select ranges or the option key to select any source and 
then pressing the "Add" button to add all the selected 
sources to the source list.  Note that the wais source files 
have to be of type TEXT or WSRC.

- The document type is now sent when adding to 
relevance feedback. This was done to support the FTP
extensions in the WAIS server implemented by UNC.

- Added support for MBIN (MacBinary type documents),
the stack will prompt the user for a name to save under
and will then proceed to unbinify the document. The document
will be saved whether the user selects "view" or "save" from
the document menu. Currently there are no sources that I
know of which will provide documents in MacBinary 
format, but this would be useful to someone who wanted to
provide an archive of Mac applications for people to search
and download applications from.

- The usual slew of bug fixes which are listed in the release
notes.




Below is the README file for HyperWais:


HyperWais 1.6:
--------------

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:/incoming/HyperWais.sea.hqx,
mendel.welch.jhu.edu:/incoming/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 of sessions either
from the same client or different client, and either from the same user
or different users on different mac.

At the other end, there are a set of stubs which implement the Apple
Events calling functions making it easier for people to integrate them
into their applications. And on top of that a set of XFCN for Hypercard
or others.

All this is written in a layered manner so that people who want to
integrate wais services into their applications can do so at various
levels. Either one could use Apple Events, or call the glue routines
directly and just link in the C library into their application, or if
you want to program on the 'bare metal', you could go directly against
the basic routines.


      -----------------------
      |      XFCN           |
      ----------------------- 
      |   Apple Events      |
      ----------------------- 
              |
              |
              |
      -----------------------         This whole block
      |   Apple Events      |         is the wais listener
      ----------------------- 
      |    Glue Routines    |
      ----------------------- 
      |    Basic Routines   |
      ----------------------- 
      |    WAIS protocol    |
      ----------------------- 
      |    MacTCP           |
      ----------------------- 



francois 

Francois Schiettecatte
Software Engineer
Advanced Technology Group
Welch Medical Library
Johns Hopkins University
Internet: francois@library.welch.jhu.edu
Phone	: (410) 955-7581


Xref: sparky comp.infosystems.wais:807 alt.wais:768