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

AUTHOR

Ray R. Larson ()