Cheshire II Commands
zserver - Run the CheshireII Z39.50 Server
SYNOPSIS
zserver[-p port] [-c server_init_file]
.BE
DESCRIPTION
This command runs the Cheshire II Z39.50 Server from the command line.
Normally the server will be set up to run via INETD and will be run
when users connect on its defined port. Running the server from the
command line is useful for testing and "debugging" database and
server configurations.
Once started the server waits for a Z39.50 connection from a user and
processes all Z39.50 commands from that user until the connection is
terminated. The server then cleans up and exits.
There are two arguments for this command:
The -p argument provides a port
number for incoming connections. This is overridden by INETD, but it
overrides the PORT parameter in the initialization file (see below).
The -c argument provides the name of a server init file. If
not supplied the server tries to read a file called "server.init"
in the current directory.
INETD SERVER SETUP
Server setup to run under inetd will
require root access to modify some systems file.
A line like the following should be added to the /etc/services file,
(the 2100 can be any port you want -- the official "well-known port"
for z39.50 is 210)
cheshire 2100/tcp ir # Cheshire II server
Then a line like the following should be added to /etc/inetd.conf (note
that this should be a single line, even though it wraps here):
#
# Z39.50 Information Retrieval access...
#
cheshire stream tcp nowait nobody /usr/local/bin/zserver
zserver -c /usr/test/data/server.init
#
This means that when the "cheshire service" on port 2100 is connected to,
it will start up a session as user "nobody" using the program at
/usr/local/bin/zserver
The arguments passed to the zserver are what remains on the line above:
zserver -c /usr/test/data/server.init
This is argv[0] -- the program name -- argv[1] -- "-c" a flag indicating
that the following argument is the name of the initialization file for
the server.
ZSERVER INIT FILE CONTENTS
The server initialization file contains a variety of information on
the configuration of the server, and the database files associated
with the server. Most of the parameters in the server configuration
file are named to correspond with the matching parameters in the
Z39.50 Standard. Most of these are used to report back to
client programs during the init process
Each configuration parameter name and value must be in one
line. Double quote should be placed around a value if the value
contains more than one word. Comments may be included in the file
by preceding them with '#'.
This file is also used to define the TargetInfo portions of the Explain
database for the server. The parameters below that begin with "TARGETINFO"
are optional (but recommended) and are only used to define the
explain database.
-
PREFERRED_MESSAGE_SIZE
- Preferred message size to be negotiated with client.
-
MAXIMUM_RECORD_SIZE
- Maximum record size to be negotiated with client.
-
IMPLEMENTATION_ID
- Implementation ID to be reported to client.
-
IMPLEMENTATION_NAME
- Implementation name to be reported to client (suggest
"Cheshire II V3 ZServer"). This is also used as the Explain target name
-
IMPLEMENTATION_VERSION
- Implementation version to be reported to client. Current version is
"2.4"
-
PROTOCOL_VERSION
- Z39.50 protocol version to be reported to client. This should be "111"
(i.e. version 3 Z39.50-1994).
-
OPTIONS
- This is the options string for reporting to the client in the INIT response.
Each position in this numeric string
represents a capability and whether it is in effect(1) or not
(0). The capabilities are: search, present, delete, resource-report,
scan, sort, extended-services, trigger-resource-control, level 1 segmentation,
level 2 segmentation, concurrent operations, named result sets, resource-control
and access control.
-
PORT
- The port to listen for connections on. This is only in effect when zserver
is run from the command line. INETD will control the port used and override
this value when the program is run that way.
-
DATABASE_NAMES (obsolete)
- This is a list of the database names that the server will recognize when
requested by the client. Since multiple databases may be defined in
particular configuration files, there may not be a one-to-one correspondence
between database names and the directories and dtds. Note that
database names are now extracted directly from the configfiles, using the
same name in different configfiles will no longer work
-
DATABASE_DIRECTORIES
- This is a list of pathnames for the directories containing databases and
their configuration files. Each pathname is matched with the corresponding
configuration file in the DATABASE_CONFIGFILES list.
-
DATABASE_CONFIGFILES
- This is a list of database configuration file names that must correspond (by
position in the list) with the DATABASE directories containing those
configuration files.
-
SUPPORT_NAMED_RESULT_SET
- Indicates whether(1) or not(0) the system supports named result sets
(should be 1).
-
SUPPORT_MULTIPLE_DATABASE_SEARCH
- Indicates whether(1) or not(0) the system supports multiple database
searching (should be 1).
-
TIMEOUT
- Maximum time to wait for a response.
-
LOG_FILE_NAME
- Name of a file into which the transaction and error information for
a user session is put (this is a temporary file that is deleted at the
end of each session).
-
PERMANENT_LOG_FILE_NAME
- Name of a file into which the transaction information from the session
log file (above) is appended at the end of the session. If not included
no transaction information will be retained.
-
RESULT_SET_DIRECTORY
- Directory into which the log file and the (temporary) result sets will be
written. Note that this file must be writeable by the user defined in
the INETD setup or by the person who ran the server from the command line.
-
ATTRIBUTE_SET_ID
- This is a list of OIDs for the attribute sets supported.
-
SUPPORT_TYPE_0_QUERY
- Indicates whether TYPE-0 queries are supported.
-
SUPPORT_TYPE_1_QUERY
- Indicates whether TYPE-1 queries are supported.
-
SUPPORT_TYPE_2_QUERY
- Indicates whether TYPE-2 queries are supported.
-
SUPPORT_TYPE_100_QUERY
- Indicates whether TYPE-100 queries are supported.
-
SUPPORT_TYPE_101_QUERY
- Indicates whether TYPE-101 queries are supported.
-
SUPPORT_TYPE_102_QUERY
- Indicates whether TYPE-102 queries are supported.
-
SUPPORT_ELEMENT_SET_NAMES
- Indicates whether multiple element set names are supported in queries.
-
SUPPORT_SINGLE_ELEMENT_SET_NAME
- Indicates whether single element set name is supported in queries.
-
TARGETINFO_NEWS
- Explain information about the server -- News
-
TARGETINFO_WELCOME_MSG
- Explain information about the server -- Welcome message
-
TARGETINFO_CONTACT_NAME
- Explain information about the server -- Person to contact
-
TARGETINFO_CONTACT_DESCRIPTION
- Explain information about the server -- Contact person description/title
-
TARGETINFO_CONTACT_ADDRESS
- Explain information about the server -- Contact person address
-
TARGETINFO_CONTACT_EMAIL
- Explain information about the server -- Contact person email
-
TARGETINFO_CONTACT_PHONE
- Explain information about the server -- Contact person phone
-
TARGETINFO_DESCRIPTION
- Explain information about the server -- Server description
-
TARGETINFO_USAGE_RESTRICTION
- Explain information about the server -- Usage restrictions
-
TARGETINFO_PAYMENT_ADDRESS
- Explain information about the server -- Usage payment address
-
TARGETINFO_HOURS
- Explain information about the server -- Hours server is available
-
TARGETINFO_LANGUAGES
- Explain information about the server -- Languages used in the server
Here is a sample configuration file:
The following initialization file contains the following sorts of information:
(this comes from the zserver/server.init file)
#
# Z3950 Server Initialization File.
# The name and value must be in one line. Double quote should be
# placed around a value if the value contains more than one word.
#
# FIELD_NAME VALUE
PREFERRED_MESSAGE_SIZE 32768
MAXIMUM_RECORD_SIZE 131072
IMPLEMENTATION_ID "1998"
IMPLEMENTATION_NAME "Mycroft (Cheshire II V3 ZServer)"
IMPLEMENTATION_VERSION "2.4"
PROTOCOL_VERSION "111"
OPTIONS "111011111000001"
PORT "2222" # testing port number
DATABASE_NAMES "bibfile HDS_Catalogue"
DATABASE_DIRECTORIES "/usr/users/ray/Work/cheshire/index/TESTDATA /usr/users/ray/Work/ESSEX_TEST/"
DATABASE_CONFIGFILES "testconfig.new CONFIG.CODEBOOK" # list of configfiles
SUPPORT_NAMED_RESULT_SET 1 # 1 means YES
SUPPORT_MULTIPLE_DATABASE_SEARCH 1 # 0 means NO
TIMEOUT 120 # in seconds
LOG_FILE_NAME "zserver.log"
RESULT_SET_DIRECTORY "/usr/tmp"
ATTRIBUTE_SET_ID "1.2.840.10003.3.1 1.2.840.10003.3.2 1.2.840.10003.3.5" # BIB-1, EXP-1, and GILS
#
#
SUPPORT_TYPE_0_QUERY 1
SUPPORT_TYPE_1_QUERY 1
SUPPORT_TYPE_2_QUERY 0
SUPPORT_TYPE_100_QUERY 0
SUPPORT_TYPE_101_QUERY 1
SUPPORT_TYPE_102_QUERY 1
#
#
SUPPORT_ELEMENT_SET_NAMES 1
SUPPORT_SINGLE_ELEMENT_SET_NAME 0
#
#
# Information for generation of explain database
#
TARGETINFO_NEWS "No news at the present time."
TARGETINFO_WELCOME_MSG "Welcome the Mycroft Server powered by Cheshire II"
TARGETINFO_CONTACT_NAME "Ray Larson"
TARGETINFO_CONTACT_DESCRIPTION "Cheshire II Project Director"
TARGETINFO_CONTACT_ADDRESS "School of Information Management and Systems, University of California, Berkeley, 102 South Hall 4600, Berkeley, California 94720-4600 USA"
TARGETINFO_CONTACT_EMAIL ""
# TARGETINFO_CONTACT_PHONE
TARGETINFO_DESCRIPTION "This server is primarily for testing purposes and hosts a number of sample and test databases."
TARGETINFO_USAGE_RESTRICTION "No usage restrictions"
TARGETINFO_PAYMENT_ADDRESS "This server is free"
TARGETINFO_HOURS "Should never be down, except it may fail while development is ongoing"
TARGETINFO_LANGUAGES "eng" #can be a list of all languages avail
#
# End of The Server Initialization File.
#
OUTPUT FILES
A transaction log file is generated in the RESULT_SET_DIRECTORY with
the name defined in LOG_FILE_NAME. This will also contain system
error messages.
ERROR INFORMATION
It is not uncommon for server failure or indexing failure to be caused
by incorrect configuration files or server.init files. The first place to
look is in any log files (zserver.log) left in the RESULT_SET_DIRECTORY
location. All error messages from the server are sent to the log file
(unless the server is started from the command line). If the server fails
before the log file is opened, the cause of the failure will be written
(if possible) to the file /tmp/templog.
BUGS
None known
SEE ALSO
Configuration file documentation,
index_cheshire
AUTHOR
Ray R. Larson ()