18
             The CNIDR Isite Information System

                              
                             The
                            Isite
                     Information System
                              
                        Version 1.04
                              
                              
                              
                              
                              
                              
            Kevin Gamiel (Kevin_Gamiel@cnidr.org)
                              
                              
  The Clearinghouse for Networked Information Discovery and
                          Retrieval
                              
                              
  This material is based on work sponsored by the National
   Science Foundation under Cooperative Agreement No. NCR-
     9216963.  The Government has certain rights in this
                          material.
                              
  Any opinions, findings and conclusions or recommendations
expressed in this publication are those of the author(s) and
do not necessarily reflect the views of the National Science
                         Foundation.
                              
Copyright (c) MCNC, Clearinghouse for Networked Information
Discovery and
Retrieval, 1994.

Permission to use, copy, modify, distribute, and sell this
software and
its documentation, in whole or in part, for any purpose is
hereby granted
without fee, provided that

1. The above copyright notice and this permission notice
appear in all
copies of the software and related documentation. Notices of
copyright
and/or attribution which appear at the beginning of any file
included in
this distribution must remain intact.

2. Users of this software agree to make their best efforts
(a) to return
to MCNC any improvements or extensions that they make, so
that these may
be included in future releases; and (b) to inform MCNC/CNIDR
of noteworthy
uses of this software.

3. The names of MCNC and Clearinghouse for Networked
Information Discovery
and Retrieval may not be used in any advertising or
publicity relating to
the software without the specific, prior written permission
of MCNC/CNIDR.

THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY
KIND,
EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION,
ANY WARRANTY
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL MCNC/CNIDR BE LIABLE FOR ANY SPECIAL,
INCIDENTAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY
DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT
ADVISED OF THE
POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY,
ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.



Table of Contents

1.  Isite Information System                               1
 1.1  Overview                                            1
     Figure 1:  Isite Information System Architecture     1
 1.2  Obtaining the System                                2
 1.3  Maintenance                                         2
2.  Search API System Administrator's Guide                2
 2.1  Overview                                            2
 2.2  Installation                                        3
 2.3  General Configuration                               3
 2.4  Database-specific Configuration                     4
  2.4.1  SCRIPT Databases                                 4
  2.4.2  ISEARCH Databases                                5
3.  zserver System Administrator's Guide                   7
 3.1  Overview                                            7
 3.2  Installation                                        7
 3.3  The Server Configuration File                       7
  3.3.1  Overview                                         7
  3.3.2  Server Configuration File Directives             8
    3.3.2.1  AccessLog                                    8
    3.3.2.2  DBList                                       8
    3.3.2.3  DebugLevel                                   9
    3.3.2.4  MaxSessions                                  9
    3.3.2.5  Port                                         9
    3.3.2.6  SAPI                                        10
    3.3.2.7  ServerType                                  10
    3.3.2.8  TimeOut                                     10
 3.4  Running the Server                                 11
  3.4.1  Running Under inetd                             11
  3.4.2  Running from the Command Line                   11
4. Stateful http to Z39.50 Gateway                        13
 4.1  Overview                                           13
 4.2 Architecture                                        13
     Figure 2:  Http to Z39.50 Stateful Gateway
     Architecture                                        13
 4.3 Installation                                        13
 4.4 Using the Stateful Gateway                          16
5.0  For More Information                                 16
Appendix A.  Copyright Statements                         17
Appendix B.  Default Field Map (bib-1)                    19


1.  Isite Information System


1.1  Overview

The Clearinghouse for Networked Information Discovery and
Retrieval (CNIDR), through the National Science Foundation
Cooperative Agreement NCR-9216963 and support from MCNC,
formerly the Microelectronics Center of North Carolina,
continues development and maintenance of Isite, a complete
Internet information system. Isite integrates database
systems with other open Internet systems and protocols such
as the World Wide Web, Gopher, electronic mail and,
primarily, ANSI/NISO Z39.50.  The primary protocol, Z39.50,
offers a variety of search and retrieval facilities suitable
for complex database operations.  Isite includes Z39.50
communications applications as well as an http to Z39.50
gateway and a complete text search system, Isearch.  See
figure 1 for an overall architectural view.

































Figure 1:  Isite Information System Architecture

1.2  Obtaining the System

Isite is freely available for all use subject to the
copyright statements in Appendix A.

The software may be downloaded from the Internet via the
file transfer protocol (FTP) from the host ftp.cnidr.org.
After connecting, change to the /pub/NIDR.tools/Isite
directory and read the README file.  Change to binary mode
and download the latest copy of either the source code or
the binaries.  The URL is

     ftp://ftp.cnidr.org/pub/NIDR.tools/Isite/

After downloading, you must unzip the compressed package.
If the filename ends in .gz, the file was compressed with
GNU's gzip compression utility.  To unzip a gzipped package,
enter the command

     gunzip Isite-x.xx.tar.gz
     
If the filename ends in .Z, the file was compressed with the
standard UNIX compression utility. In that case, uncompress
with the command

     uncompress Isite-x.xx.tar.Z.

You should then have a file of the form Isite-x.xx.tar.  To
untar the file, enter the command

     tar xvf Isite-x.xx.tar
     
A subdirectory will be created named Isite-x.xx and all
Isite-related files will reside in that subdirectory.

The source code requires a C++ compiler (GNU g++ preferred)
to build.  For more information on building the source code,
read the README file in the Isite-x.xx directory.


1.3  Maintenance

Maintenance of an Isite information system requires the
maintenance of the CNIDR Search API and the CNIDR Z39.50
server, zserver.


2.  Search API System Administrator's Guide


2.1  Overview

Many applications require access to text searching
facilities and database systems.  In response to this
general need, CNIDR has developed a Search API (SAPI) which
attempts to generalize access to arbitrary database systems
via a common API.  Any application that links with this API,
therefore, inherits the
functionality of any database system that may reside
"behind" the API.

To the system administrator, this requires you to maintain
one or more text files that describe which databases are
currently available, their location on the file system, etc.
By keeping this information up to date, all applications on
your system designed to use the Search API will always have
dynamic access to those databases.


2.2  Installation

Installation of the SAPI involves creating a single text
file, known as the SAPI Configuration File, in a convenient
location on your file system.  Name the file sapi.ini and
store in a location accessible by any SAPI-compliant
applications (such as zserver).  You will later need to
inform each SAPI-compliant application of the sapi.ini
file's location in the manner prescribed by each
application.

The remainder of this chapter describes the format of the
SAPI configuration file.


2.3  General Configuration

In general, the SAPI Configuration File describes each
database available through the API to SAPI compliant
applications.  Among other information, this file identifies
the type of database and the location of the database on the
file system.  This file has the general form:

[Group1]
Directive1=Value
Directive2=Value

[Group2]
Directive1=Value
Directive2=Value

...

The file is separated into named Groups of information.
Each Group has a series of Directives and associated Values.

Let's take a quick, high-level look at an example sapi.ini
file.  We will discuss this file in more detail later.

[Default]
DBList=CATALOG,ERIC

[CATALOG]
Type=ISEARCH
Location=/local/databases

[ERIC]
Type=SCRIPT
Location=/usr/local/bin/ManPageSearch
Results=/tmp/results

The first mandatory Group, named "Default", is where general
information about the Search API itself is described.
Currently, there is only a single directive defined for that
Group, the DBList directive.  The DBList directive lists all
databases accessible via the SAPI by name.

In the example, the DBList directive indicates that two
databases are available for searching; CATALOG and ERIC.

For each database name in the DBList, you must create a
Database Information Group.  In each Database Information
Group, you must specify at least a database Type and
Location and, depending on the search engine type, a Results
directive.


2.4  Database-specific Configuration

There are currently two Types of search engines supported by
the SAPI: ISEARCH and SCRIPT.

ISEARCH is the default search engine written and maintained
by CNIDR.  It provides relevance ranked, full text searching
as well as Boolean, fielded searching.

The SCRIPT "search engine" is really a mechanism for calling
scripts or other external applications for search and
retrieval.

In our example above, the first Database Information Group,
CATALOG, has a Type of ISEARCH, meaning the database was
indexed using the Iindex utility from the Isearch package.
We will discuss the other directives in the section on the
ISEARCH search engine below.

The second Database Information Group defines ERIC to be a
database of type SCRIPT.  More information on the SCRIPT
directives are discussed in the section on the SCRIPT search
engine below.


2.4.1  SCRIPT Databases

The SCRIPT search engine was initially developed simply to
test the Search API.  However, we felt that others might
find it useful, so we left it in.

The purpose of the SCRIPT search engine is to allow system
administrators to offer new, interesting databases quickly
and easily without having a specific database system or tool
and without having to extend the source code of Isite.

We chose to implement this by describing a simple interface
between the Search API and external applications.  There are
three components involved in this interface:  The Database
Information Group, the external application and the results
file.

A Database Information Group is an entry in a sapi.ini file
that describes a database.  For SCRIPT-type databases, the
database information group must have the directives Type,
Location and Results.  Consider:

[ManPages]
Type=SCRIPT
Location=/usr/bin/ManSearch.sh
Results=/tmp/results

In this example, the database name is ManPages and the
database type is SCRIPT.  For SCRIPT type databases, the
Location directive is mandatory and specifies a fully-
qualified pathname of an external application or shell
script.  The Results directive is also mandatory and acts as
a prefix
for a temporary storage file for the results of the search.
When the Search API receives a request to search the
ManPages database for a term of 'strcmp', for example, it
constructs a command of the form:

/usr/bin/ManSearch.sh /tmp/results.<pid>
strcmp[attr1,value1,]

and executes that command with a system() call.  Therefore,
the calling of a SCRIPT search engine is quite simple,
however the results file must be structured to allow the
Search API to read the search results.

The Results file must be adhere to the following format:

[Default]
HitCount=1
Diagnostic=0
Separator=##separator string - your choice##
[Data]
Record data for record number 1
##separator string - your choice##
Record data for record number 2
##separator string - your choice##
Record data for record number 3

If the Results file is not of this format, you can expect
unexpected results! The file begins with a group named
"Default".  Within the Default group, "HitCount" is the
number of documents matching the user's query and available
for retrieval.  As of this writing, "Diagnostic" can be one
of two values, 0 or 1.  A value of 0 indicates success and
1, failure.  The "Separator" directive should be a unique
string (unique among the data records) that will be used to
separate the data records themselves.  This provides the
Search API with a dynamic mechanism for retrieving records
based on a caller's request.

Next, we have a group named "Data".  The actual data records
(HitCount of them) are listed sequentially after the Data
group name, separated by a single line containing only the
Separator value.

Therefore, if you wish to write a SCRIPT type search engine
to be used with the Search API (hence any applications that
use the Search API), you need to do the following:

 Write a script or program that accepts 2 command line
  arguments, a temp file name and query term.

 In the script, perform whatever operation you wish and
  then write the results of your operation into the temp
  file you received on the command line.  You must adhere
  to the file format described above!

 Edit your sapi.ini file and add your new database by
  adding the database name to the DBList directive and add
  a Database Information Group as described above.

Any applications (zserver, for example) that use the Search
API should be made aware of the Search API's new databases.
Refer to the documentation for each application for more
details.  That should be all!


2.4.2  ISEARCH Databases

Isearch is the default search engine.  An ISEARCH type
database requires Type and Location directives.
The Location directive specifies the directory in which your
Iindex-ed database exists.  The actual database filename is
constructed internally by concatenating the Location with a
slash and the database name (CATALOG).  A trailing slash,
therefore, should never be included in the Location.  The
database name is case sensitive.

For example:

[Default]
DBList=CATALOG

[CATALOG]
Location=/local/databases

In this example, the Iindex-ed database named CATALOG should
reside in the /local/databases directory on the file system.
Any SAPI-compliant application, then, can search the CATALOG
database.  For more information on building databases with
Iindex, refer to the Isearch documentation.

Optionally, ISEARCH databases may include a directive named
FieldMaps.  In order for Z39.50 clients to search your
Isearch database in a standardized manner, you must provide
a mapping from Z39.50 database information to Isearch style
information.  This currently involves mapping Z39.50 Use
attributes (combination Attribute Set Id and integer Use
value representing a field name) to your field names as
indexed by Iindex.  For more information on Attribute Sets
and Z39.50 in general, see
http://lcweb.loc.gov/z3950/agency.  The default Z39.50
attribute set is bib-1.  By default, the bib-1 field names
listed in Appendix C are recognized and mapped
appropriately.  For example, if the client sends a search
request specifying the bib-1 Attribute Set with the Use
attribute value 4, zserver will attempt to search a field
named title in your Iindexed database.  If no field named
title exists in your database, the search will fail.  To
override the default field name with one of your own, you
must create a file with custom mappings.  A  single mappings
file can be used for as many different databases as needed
and can be combined with other mapping files, each
overlaying the values of the previous one.

Let us assume you index a collection of files of the
following form:

<title>Document Number 1</title>
<h1>The subject of my document</h1>
<body>blah blah</body>

By default, clients attempting to search with an Attribute
Set of bib-1 and Use attribute of 4 will successfully search
the <title> field.  In order to allow clients to search the
<h1> field, however, we must provide a custom mapping.
First, decide which bib-1 Use attribute is most appropriate.
In this case, a Use value of 21, Subject Heading, seems most
appropriate.  Next, create a custom mapping file called, for
example, mymap.ini.  This file might look like this:

[Default]
bib1/21=h1

How do you map from a Z39.50 Use Attribute to an Isearch
full text search?  Simple:

[Default]
bib1/21=h1
bib1/1035=

In Isearch, a field with no name is considered to be full
text.

Now you must inform the Search API of the existence of this
mapping file.  To do so, add the FieldMaps directive to the
appropriate database information group in the sapi.ini file.
For example:

[Default]
DBList=CATALOG

[CATALOG]
Location=/local/databases
FieldMaps=mymap.ini

When the server starts, it will read the mymap.ini file and
override the value of bib1/21 and map it to the Isearch
field name of <h1>.  You can add as many field map files as
you wish, separated by commas, to the FieldMaps directive:

FieldMaps=mymap.ini,another.ini,yetanother.ini

The entries in each map file will overlay the ones before.

What if you cant find a Z39.50 Use Attribute that maps to
your Isearch field?  First of all, make sure you check all
available Z39.50 Attribute Sets.  As of this writing, there
are two defined; bib-1 and STAS (Scientific and Technical
Attribute Set).  The bib-1 set is defined in the Z39.50
standard itself and is available at
http://lcweb.loc.gov/z3950/agency.  The STAS attribute set
is maintained by CNIDR and is found at
http://stas.cnidr.org/STAS.html.  If you still cant find
one that works, I suggest you send a request to the Isite
mailing list for more information (I really dont want to
promote custom attribute sets.)

3.  zserver System Administrator's Guide


3.1  Overview

Isite provides access to database systems via the ANSI/NISO
Z39.50 search and retrieval protocol.  The Z39.50
communications server, zserver, is linked with the CNIDR
Search API in order to accomplish this task.

This document assumes that you have obtained a copy of the
Isite software and have the binaries at your disposal.


3.2  Installation

There are two files involved in the installation of zserver:
the zserver binary and the zserver configuration file.

The zserver binary is the communications server itself.  It
accepts Z39.50 TCP connections and accepts requests to
search and retrieve from databases available through the
CNIDR Search API.  Copy the zserver binary to a suitable
location such as /usr/local/bin.

The characteristics of the server are defined in the server
configuration file, typically named zserver.ini.  This file
should be in a location accessible to the zserver
application, preferably in the same directory.

The remainder of this chapter describes the format of the
zserver configuration file and usage of the server.


3.3  The Server Configuration File


3.3.1  Overview
The zserver Server Configuration File is a simple text file
that can be created and maintained with your favorite text
editor.  The file contains all information needed by zserver
for operation.  The file should be named zserver.ini.  A
zserver.ini file is made up of Groups and Directives and has
the general form:

[Group1]
Directive1=Value
Directive2=Value

[Group2]
Directive1=Value
Directive2=Value

...

A Group begins with a group name in square brackets and
continues until the end of the file or until another group
name is encountered.  A group provides a mechanism for
grouping directives under a common name for an intended set
of functionality.

Within each group are a series of Directives, each with an
associated Value.  A Directive is text string with no spaces
immediately followed by an equal sign. The Value associated
with a particular directive should immediately follow the
equals sign.

There is currently only one Group within a zserver.ini, the
Server Information Group.

The Server Information Group should be named [Default].


3.3.2  Server Configuration File Directives

The following is the list of directives recognized by
zserver from its configuration file, zserver.ini, under the
[Default] group.


3.3.2.1  AccessLog

     Syntax:

          AccessLog=/tmp/zserver_access.log

     Description:

          Specifies a file to which client access
information is written.

     Default:

          AccessLog=/tmp/zserver_access.log


3.3.2.2  DBList

     Syntax:

          DBList=DBNAME1,DBNAME2

     Description:

          Lists database names accessible to Z39.50 clients
from
          zserver.  These names must correspond to and be a
subset
          of those in the DBList directive within the SAPI
configuration
          file.

     Default:

          DBList=


3.3.2.3  DebugLevel
     Syntax:

          DebugLevel=9

     Description:

          Specifies the level of debugging information to be
printed to standard error during
          server operation.  Values range from 0 to 9 from
less verbose to more verbose.

     Default:

          DebugLevel=3


3.3.2.4  MaxSessions

     Syntax:

          MaxSessions=50

     Description:

          If ServerType is set to STANDALONE, up to
MaxSessions may be
          active at any time.  If MaxSessions is reached,
clients will
          be refused Z39.50 initialization.

     Default:

          MaxSessions=50


3.3.2.5  Port

     Syntax:

          Port=210

     Description:

          Indicates the TCP port on which connections will
be accepted.
          Port 210 is the official port for Z39.50.

     Default:

          Port=210


3.3.2.6  SAPI

     Syntax:

          SAPI=/usr/local/etc/sapi/sapi.ini

     Description:

          Specifies which file to use as the Search API
configuration
          file.  See documentation on the SAPI for more
information
          on the format of that file.

     Default:

          SAPI=sapi.ini



3.3.2.7  ServerType

     Syntax:

          ServerType=INETD
               or
          ServerType=STANDALONE

     Description:

          Running in INETD mode will run a single copy of
the server and
          the process exits upon termination of the Z39.50
session.

          In STANDALONE mode, the server runs as a forking
daemon,
          forking a separate process for each Z39.50 client
connection.

          Up to MaxSessions processes can be active
simultaneously if
          in STANDALONE mode.

     Default:

          ServerType=STANDALONE




3.3.2.8  TimeOut

     Syntax:

          TimeOut=3600

     Description:

          Specifies the number of seconds the server should
wait for
          client interaction before closing the session due
to
          inactivity.

     Default:

          TimeOut=3600



3.4  Running the Server


3.4.1  Running Under inetd

Read the man pages for your particular inetd.conf file.
Read section 3.4.2 below for more information on the command
line syntax for zserver.


3.4.2  Running from the Command Line

To run zserver from the command line:

     zserver [[-i[IniFile][,Group]]] [-oOption=Value] [...]

Examples:

     zserver

          This example assumes that zserver is in your path
and
          that a file named zserver.ini is in the current
working
          directory.

     /usr/local/bin/zserver -i/usr/local/bin/zserver.ini

          This example assumes that the zserver executable
and
          zserver.ini files reside in the /usr/local/bin
directory.

     /usr/local/bin/zserver -
i/usr/local/bin/zserver.ini,MyGroup

          This example assumes that the zserver executable
and
          zserver.ini files reside in the /usr/local/bin
directory
          and that the server should read its configuration
information
          from the group named MyGroup instead of the usual
group
          named Default.

     zserver -oPort=8888 -oDebugLevel=9

          This example assumes that zserver is in your path
and
          that a file named zserver.ini is in the current
working
          directory.  It also overrides the Port and
DebugLevel
          directives defined in zserver.ini.  Any valid
directive
          from the zserver.ini may be overridden in the same
manner
          on the command line.


4. Stateful http to Z39.50 Gateway


4.1  Overview

Using several utilities included with Isite, one can
establish a stateful session between a standard http (World
Wide Web) server and any remote Z39.50 server.  By stateful,
we mean that a Z39.50 session is initialized only once and
is interactively used by a stateless WWW browser.  The
gateway has an inactivity timer that automatically closes
the session after a pre-configured period of time with no
user input.


4.2 Architecture














Figure 2:  Http to Z39.50 Stateful Gateway Architecture

In figure 2, the combination of http server, zgate and zcon
represents the gateway running on a single machine.  A WWW
browser connects to the http server and posts an HTML form
containing information related to a new or existing Z39.50
session.  The zgate CGI application parses that form and
either starts a new zcon process or connects to an existing
zcon process.  The users request is then passed from zgate
to the appropriate zcon which in turn communicates with the
remote Z39.50 server.  The results are passed back from the
Z39.50 server to zcon, back to zgate, back to the http
server and back to the WWW browser for display to the user.
The zgate CGI process then exits, but the associated zcon
process stays alive, holding open the Z39.50 connection.  If
a zcon process receives no input for a pre-configured period
of time, the process exits.


4.3 Installation

Installation of the gateway requires a CGI-capable http
server, such as NCSAs httpd (http://hoohoo.ncsa.uiuc.edu.)
Copy the zgate and zcon executables to the cgi-bin directory
used by your http server.   The executables MUST reside in
the same directory.

Next, start with the HTML form template provided below,
customize it to suit your needs and install under the
DocumentRoot directory of your http server (make the
document accessible to WWW browsers.)   We refer to this
HTML form as the Gateway Initialization Form.


<HTML><HEAD>
<TITLE>CNIDR Z39.50 Stateful Gateway</TITLE>
</HEAD>
<BODY>
<H1><A HREF=http://www.cnidr.org>CNIDR</A> Z39.50 Stateful
Gateway Text</H1>
<I>This is an experimental stateful Z39.50 gateway.</I>
<HR>
When you click the "Connect to Service" button, you will
establish a stateful Z39.50 connection to the selected
service.  You may then interact with that service.  If no
input is received for five minutes, your session will expire
and you will need to return to this page to log in again.
<BR>
<FORM METHOD=POST ACTION=http://your.host/cgi-bin/zgate>
Select a Database:
<BR>
<SELECT NAME="FORM_HOST_PORT" SIZE="5">
<OPTION
VALUE="/tmp/melvy.html,melvyl.ucop.edu,210">University of
California MELVYL
<OPTION VALUE="/tmp/unc.html,library.unc.edu,210">University
of North Carolina at Chapel Hill
<OPTION VALUE="/tmp/loc.html,ibm2.loc.gov,2210">Library of
Congress
</SELECT>
<BR>
<INPUT TYPE="SUBMIT" VALUE="Connect to Service">
<INPUT NAME="ACTION" VALUE="INIT" TYPE="HIDDEN">
</FORM>
</BODY>

The CGI variable named FORM_HOST_PORT is the most crucial
to the operation of the stateful gateway.  Set this variable
to the full path and filename of your HTML search form
(described later), the hostname and port of the desired
Z39.50 server.  Separate each value with a comma.  When such
a form is posted to zgate, zgate attempts to initiate a
Z39.50 connection to the specified server and if successful,
presents the search form to the user.  These CGI variables
are mandatory:

CGI Variable Name       Value             Description
ACTION             INIT             Indicates the action
                                    the gateway is to take.
FORM_HOST_PORT     filename,host,p   The filename of an
                   ort              HTML search form, the
                                    Internet hostname and
                                    port of the desired
                                    Z39.50 server.
GROUP_ID           GroupId or       The Group authenticated
                   anonymous        to access the specified
                                    server.
USER_ID            UserId or        The User authenticated
                   anonymous        to access the specified
                                    server.
PASSWORD           Password or      The Password for the
                   email address    Groupname/Username
                                    combination required to
                                    access the specified
                                    server. If USERID is
                                    anonymous, PASSWORD
                                    should be the user's e-
                                    mail address




The search form is not automatically generated in order to
allow you to customize it to suit your needs.  You must,
however, include the following mandatory CGI variables:

CGI Variable Name    Value              Description
ACTION            SEARCH        Indicates the action the
                                gateway is to take.
DBNAME            database_na   Name of Z39.50 database
                  me
ESNAME            element_set   Element set name for the
                  _name         headline documents.
                                Defaults to B for Brief.
RECSYNTAX         record_synt   Record syntax for the
                  ax            headline documents.
                                Defaults to USMARC
                                (1.2.840.10003.5.10).
TERM_1            query_term    First query term
USE_1             field_to_se   First Z39.50 Use attribute.
                  arch          The default attribute set is
                                bib-1.  The default Use
                                attribute is 1035
                                (Anywhere.)  For Isearch
                                databases, this is mapped to
                                full text.
TERM_2            query_term    Second query term (optional)
USE_2             field_to_se   Second Z39.50 Use attribute
                  arch          (optional)
BOOLEAN_OP        Boolean_ope   If second query term is
                  rator         included, performs this
                                Boolean operation.  The
                                default is AND.  Choices are
                                AND and OR.
MAXRECORDS        maximum_rec   Maximum number of records to
                  ords          display per page.  Default
                                is 10.
SESSION_ID        gateway_ses   This variable is required
                  sion_id       and is automatically
                                inserted into the search
                                form by the zgate
                                application.  It should not
                                be included in the static
                                copy of your search form! In
                                other words, dont worry
                                about it, I just wanted to
                                let you know it was there

For each server described in the gateway initialization
form, you must include a search form. Again, the search form
is not automatically generated in order to allow you to
customize it to suit your needs.  Here is an example you can
work from:

<TITLE>Example Search Form: Library of Congress</TITLE>
<H1>Example Search Form: Library of Congress</H1>
<I>This is an example search form for the stateful gateway.
Customize this form to suit your needs and save somewhere in
your file system.  In the server initialization form, you
will reference this file (see the <A
HREF="guide.html">guide</A> for complete details.)
<HR>This form allows you to search the entire card catalog
for the Library of Congress or a catalog of names.</I>
<FORM METHOD="POST" ACTION="/cgi-bin/zgate">
<HR>
Database to Query: <SELECT NAME="DBNAME">
<OPTION SELECTED VALUE="BOOKS">Catalog of Books
<OPTION VALUE="NAMES">Catalog of Names
</SELECT>
<BR>
<INPUT NAME="ACTION" VALUE="SEARCH" TYPE="HIDDEN">
<INPUT NAME="RECSYNTAX" VALUE="1.2.840.10003.5.10"
TYPE="HIDDEN">
<INPUT NAME="ESNAME" VALUE="B" TYPE="HIDDEN">
<INPUT NAME="TERM_1" SIZE="10">
<SELECT NAME="USE_1">
<OPTION SELECTED VALUE="21">Subject
<OPTION VALUE="1">Personal Name
<OPTION VALUE="2">Corporate Name
<OPTION VALUE="4">Title
<OPTION VALUE="5">Title Series
<OPTION VALUE="6">Title Uniform
<OPTION VALUE="7">ISBN
<OPTION VALUE="8">ISSN
</SELECT>
<SELECT NAME="BOOLEAN_OP">
<OPTION SELECTED>AND
<OPTION>OR
</SELECT>
<INPUT NAME="TERM_2" SIZE="10">
<SELECT NAME="USE_2">
<OPTION SELECTED VALUE="21">Subject
<OPTION VALUE="1">Personal Name
<OPTION VALUE="2">Corporate Name
<OPTION VALUE="4">Title
<OPTION VALUE="5">Title Series
<OPTION VALUE="6">Title Uniform
<OPTION VALUE="7">ISBN
<OPTION VALUE="8">ISSN
</SELECT>
<BR>
<INPUT TYPE="SUBMIT" VALUE="Search">
</FORM>
<HR>Comments?  Send mail to <A
HREF=MAILTO:kgamiel@vinca.cnidr.org>kgamiel@vinca.cnidr.org<
/A>


4.4 Using the Stateful Gateway

To use the gateway, you must always begin a session by
loading the Gateway Initialization Form described in section
4.3 into your WWW browser.  You will be presented a list of
services (Z39.50 servers) from which to choose.  Select one
of the services and press the Connect to Service button.
The form will be posted to your http server which will start
the zgate CGI application.  The zgate application will parse
the form and start a new zcon process which will attempt to
initialize to the specified Z39.50 server.  If successful,
you will be presented with the specified search form.  From
that form, you may interact with the server, searching and
retrieving records.

5.0  For More Information

Post any questions and/or comments to the Isite mailing
list.  Feel free to contact me as well (kgamiel@cnidr.org).
Have fun!


Appendix A.  Copyright Statements

------------------------------------------------------------
--------------
Copyright (c) MCNC, Clearinghouse for Networked Information
Discovery and
Retrieval, 1994.

Permission to use, copy, modify, distribute, and sell this
software and
its documentation, in whole or in part, for any purpose is
hereby granted
without fee, provided that

1. The above copyright notice and this permission notice
appear in all
copies of the software and related documentation. Notices of
copyright
and/or attribution which appear at the beginning of any file
included in
this distribution must remain intact.

2. Users of this software agree to make their best efforts
(a) to return
to MCNC any improvements or extensions that they make, so
that these may
be included in future releases; and (b) to inform MCNC/CNIDR
of noteworthy
uses of this software.

3. The names of MCNC and Clearinghouse for Networked
Information Discovery
and Retrieval may not be used in any advertising or
publicity relating to
the software without the specific, prior written permission
of MCNC/CNIDR.

THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY
KIND,
EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION,
ANY WARRANTY
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL MCNC/CNIDR BE LIABLE FOR ANY SPECIAL,
INCIDENTAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY
DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT
ADVISED OF THE
POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY,
ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
------------------------------------------------------------
--------------
This material is based on work sponsored by the National
Science
Foundation under Cooperative Agreement No. NCR-9216963.  The
Government
has certain rights in this material.

Any opinions, findings and conclusions or recommendations
expressed in
this publication are those of the author(s) and do not
necessarily reflect
the views of the National Science Foundation.
------------------------------------------------------------
--------------
(c)1992 OCLC Online Computer Library Center, Inc., 6565
Frantz Road, Dublin,
Ohio 43017-0702.  OCLC is a registered trademark of OCLC
Online Computer
Library Center, Inc.

NOTICE TO USERS:  The BER Utilities ("Software") has been
developed by OCLC
Online Computer Library Center, Inc.  Subject to the terms
and conditions set
forth below, OCLC grants to user a perpetual, non-exclusive,
royalty-free
license to use, reproduce, alter, modify, and create
derivative works from
Software, and to sublicense Software subject to the
following terms and
conditions:

SOFTWARE IS PROVIDED AS IS.  OCLC MAKES NO WARRANTIES,
REPRESENTATIONS, OR
GUARANTEES WHETHER EXPRESS OR IMPLIED REGARDING SOFTWARE,
ITS FITNESS FOR ANY
PARTICULAR PURPOSE, OR THE ACCURACY OF THE INFORMATION
CONTAINED THEREIN.

User agrees that OCLC shall have no liability to user
arising therefrom,
regardless of the basis of the action, including liability
for special,
consequential, exemplary, or incidental damages, including
lost profits,
even if it has been advised of the possibility thereof.

User shall cause the copyright notice of OCLC to appear on
all copies of
Software, including derivative works made therefrom.
------------------------------------------------------------
--------------
/*
 * Copyright (c) 1992 The Regents of the University of
California.
 * All rights reserved.
 *
 * Author:     Ray Larson, ray@sherlock.berkeley.edu
 *        School of Library and Information Studies, UC
Berkeley
 *
 * Redistribution and use in source and binary forms, with
or without
 * modification, are permitted provided that the following
conditions
 * are met:
 * 1. Redistributions of source code must retain the above
copyright
 *    notice, this list of conditions and the following
disclaimer.
 * 2. Redistributions in binary form must reproduce the
above copyright
 *    notice, this list of conditions and the following
disclaimer in the
 *    documentation and/or other materials provided with the
distribution.
 * 3. All advertising materials mentioning features or use
of this software
 *    must display the following acknowledgement:
 *   This product includes software developed by the
University of
 *   California, Berkeley.
 * 4. Neither the name of the University nor the names of
its contributors
 *    may be used to endorse or promote products derived
from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND THE AUTHOR
``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF
 * SUCH DAMAGE.
 */


Appendix B.  Default Field Map (bib-1)

[Default]
bib1/1=Name-personal
bib1/2=Name-corporate
bib1/3=Name-conference
bib1/4=Title
bib1/5=Title-series
bib1/6=Title-uniform
bib1/7=Identifier-ISBN
bib1/8=Identifier-ISSN
bib1/9=Control-number-LC
bib1/10=Control-number-BNB
bib1/11=Control-number-BNF
bib1/12=Control-number-local
bib1/13=Classification-Dewey
bib1/14=Classification-UDC
bib1/15=Classification-Bliss
bib1/16=Classification-LC
bib1/17=Classification-NLM
bib1/18=Classification-NAL
bib1/19=Classification-MOS
bib1/20=Classification-local
bib1/21=Subject
bib1/22=Subject-RAMEAU
bib1/23=Subject-BDI
bib1/24=Subject-INSPEC
bib1/25=Subject-MESH
bib1/26=Subject-PA
bib1/27=Subject-LC
bib1/28=Subject-RVM
bib1/29=Subject-local
bib1/30=Date
bib1/31=Date-publication
bib1/32=Date-acquisition
bib1/33=Title-key
bib1/34=Title-collective
bib1/35=Title-parallel
bib1/36=Title-cover
bib1/37=Title-added-title-page
bib1/38=Title-caption
bib1/39=Title-running
bib1/40=Title-spine
bib1/41=Title-other-variant
bib1/42=Title-former
bib1/43=Title-abbreviated
bib1/44=Title-expanded
bib1/45=Subject-PRECIS
bib1/46=Subject-RSWK
bib1/47=Subject-subdivision
bib1/48=Identifier-national-bibliography
bib1/49=Identifier-legal-deposit
bib1/50=Classification-government-publication
bib1/51=Identifier-publisher-for-music
bib1/52=Control-number-DB
bib1/53=Identifier-local-call
bib1/54=Code-language
bib1/55=Code-geographic-area
bib1/56=Code-institution
bib1/57=Name-and-title
bib1/58=Name-geographic
bib1/59=Name-geographic-place-publication
bib1/60=Identifier-CODEN
bib1/61=Code-microform-generation
bib1/62=Abstract
bib1/63=Note
bib1/1000=Author-name-and-title
bib1/1001=Code-record-type
bib1/1002=Name
bib1/1003=Author-name
bib1/1004=Author-name-personal
bib1/1005=Author-name-corporate
bib1/1006=Author-name-conference
bib1/1007=Identifier-standard
bib1/1008=Subject-LC-children's
bib1/1009=Subject-name-personal
bib1/1010=Body-of-text
bib1/1011=Date/time-added-to-database
bib1/1012=Date/time-last-modified
bib1/1013=Identifier-authority/format
bib1/1014=Concept-text
bib1/1015=Concept-reference
bib1/1016=Any
bib1/1017=Server-choice
bib1/1018=Name-publisher
bib1/1019=Record-source
bib1/1020=Name-editor
bib1/1021=Bib-level
bib1/1022=Geographic-class
bib1/1023=Indexed-by
bib1/1024=Map-scale
bib1/1025=Music-key
bib1/1026=Related-periodical
bib1/1027=Identifier-report
bib1/1028=Identifier-stock
bib1/1030=Identifier-thematic
bib1/1031=Material-type
bib1/1032=Identifier-document
bib1/1033=Host-item
bib1/1034=Content-type
bib1/1035=Anywhere            // This maps to an Isearch
full text search
bib1/1036=Author-Title-Subject
