NAME

Net::Z3950::DBIServer::Run - Invoking the zSQLgate Server

SYNOPSIS

zSQLgate config-file [YAZ-options] [listener] ...

DESCRIPTION

zSQLgate provides an Z39.50 interface to your relational databases. That is, it provides a generic gateway between the Z39.50 Information Retrieval protocol and pretty much any relational database you care to mention.

This document describes how to invoke the zSQLgate server from the command-line: what the options do and how to specify listener addresses. For other information, including details of the configuration file format, see the ::zSQLgate manpage and the linked pages.

OPTIONS

Besides the mandatory configuration-file name, the following options may be provided on the command-line. These are all inherited from the YAZ back-end server on which zSQLgate is built.

-a APDUfile
APDU file. Specifies a file for dumping APDUs (for diagnostic purposes). The special name ``-'' sends output to the standard error stream. It's better then even money that you'll never, ever do this. (Though now I've said that, you'll try it just to spite me.)

-S
Static. Prevents the server from fork()ing on connection requests. This can be useful for debugging, but is not recommended for real operation: although the server is asynchronous and non-blocking, there are potential efficiency gains in having separate server processes for each client connection: for example, a single intensive back-end operation on the behalf of one client will not cause simpler requests from other clients to be delayed.

-l logFile
Log file. Specifies a file to which to write logging messages, which by default go to the standard error stream.

-v verbosity
Verbosity. Specifies what information to write to the log file. The verbosity specification should be a comma-separated list of one or more of the following words: 
        fatal, debug, warn, log, all, none

The default logging level is fatal,warn,log - that is, everything except the very verbose debug messages.

-u userName
User. Sets the running server's real and effective user IDs to that of the specified user. This is useful if you need the server to start running as root so it can bind to a privileged port, but you don't otherwise want or need to run as root.

-w dir
Working directory. Tells the server to run in the specified directory.

-i
Inetd. Used when running zSQLgate from the inetd server. The default is to run in standalone mode.

-t minutes
Timeout. Tells the server to unilaterally close client connections after they are idle for the specified number of minutes.

-k Kb
Sets the maximum record size and message size to the specified number of kilobytes. You should really never need this.

-1
One-shot mode. Tells the server to serve a single connection, then exit immediately. This can be useful when debugging, but not in normal use.

-T
Threads. Asks the server to use threads, rather than multiple processes, on systems where that is an option. On Windows NT, this is the default (and indeed only) mode.

-s
SR. Instructs the server to use the obsolete ISO SR protocol rather than Z39.50. I don't think there's any reason to do this now, if there ever was, but it's there for completeness.

-z
Z39.50. Instructs the server to speak Z39.50 rather than the obsolete ISO SR protocol. This is the default.

LISTENER SPECIFICATIONS

Following any options on the command line, one or more listener specifications may be provided. A listener specification consists of a transport mode followed by a colon (:) followed by a listener address. The transport mode may be either tcp or ssl. The former is the default and may be omitted. The latter is experimental; please don't hassle me if you can't get it to work. (I know I can't.)

The address itself consists of a hostname or IP number, optionally followed by a colon and a port number; if the port number is omitted, it defaults to 210, the standard Z39.50 port. The special hostname @ is mapped to the address INADDR_ANY, which causes the server to listen on any local interface. This is nearly always what you want.

For example, to start zSQLgate in static (single-process) mode with logging going to the zsql.log file and listening for connections on ports 210 and 3950, use:

        zSQLgate -S -l zsql.log tcp:@ @:3950

AUTHOR

Mike Taylor <mike@miketaylor.org.uk>

First version Saturday 2nd February 2002.