.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Z3950::Simple2ZOOM::Config 3pm"
.TH Net::Z3950::Simple2ZOOM::Config 3pm "2007-09-14" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Z3950::Simple2ZOOM::Config \- configuration file for the Simple2ZOOM gateway
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\& <client>
\&   <authentication>http://some.url/{user}/pwd={pass}<authentication>
\&   <database name="srubooks">
\&     <zurl>http://z3950.loc.gov:7090/voyager</zurl>
\&     <option name="sru">get</option>
\&     <charset>marc\-8</charset>
\&     <search>
\&       <querytype>cql</querytype>
\&       <map use="4"><index>title</index></map>
\&       <map use="1003"><index>creator</index></map>
\&     </search>
\&   </database>
\& </client>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The universal Swiss Army Gateway \f(CW\*(C`simple2zoom\*(C'\fR is configured by a
single file, named on the command-line, and expressed in \s-1XML\s0.  This
file specifies which back-end databases are supported, how the
back-ends are contacted, what character-sets they provide records in,
and how to map Z39.50 searches to \s-1CQL\s0.
.PP
The structure of the file is pretty simple.
.SS "Top Level"
.IX Subsection "Top Level"
.IP "<client>" 4
.IX Item "<client>"
The top-level element is <client>.  It contains a single optional
<authentication> element, any number of <database> elements and a
single optional <search> element.  The second of these specifies how
to interpret requests to search in the configured databases; the last
provides query mapping specifications for dynamically specified
databases.
.IP "<authentication>" 4
.IX Item "<authentication>"
This element contains a \s-1URL\s0 template, specifying the address of an
\&\s-1HTTP\s0 authentication server.  The template must include the special
strings \f(CW\*(C`{user}\*(C'\fR and \f(CW\*(C`{pass}\*(C'\fR, which are substituted with the
username and password supplied in the Init request, if any.  The
resulting \s-1URL\s0 is actioned and the result examined: any successful
response (\s-1HTTP\s0 status 200) indicates that the username/password
combination is acceptable, and that the session can continue; any
other response (e.g. 401 Authorization Required) results in the Init
request being refused with \s-1BIB\-1\s0 diagnostic 1014 (Init/AC:
Authentication System error).
.Sp
If the <authentication> element is omitted from the configuration, no
authentication credentials are required, and any that are provided are
ignored.
.Sp
(A trivial example of an authentication server script is included in
the Simple2ZOOM distribution, as \f(CW\*(C`etc/sru\-auth\*(C'\fR.)
.IP "<database>" 4
.IX Item "<database>"
The <database> element carries a \f(CW\*(C`name\*(C'\fR attribute specifying the
Z39.50 database name by which is it is known to clients.  It contains
several complex elements, and is discussed in more detail below.
.IP "<search>" 4
.IX Item "<search>"
Each <search> element, whether contained within a specific <database>
(see below)
or at the top level, consists of a single mandatory <querytype>
element followed by any number of <map>s.  The content of <querytype>
indicates the type of query that should be sent to the back-end
server, with Simple2ZOOM reposible for translating incoming queries as
required into that format.  At present, the only supported value is
\&\f(CW\*(C`cql\*(C'\fR.
.IP "<map>" 4
.IX Item "<map>"
Each <map> element carries a \f(CW\*(C`use\*(C'\fR attribute, which is the
numeric value of \s-1BIB\-1\s0 use attribute to be supported, and optionally
contains a single <index> element which in turn contains the name of
the corresponding \s-1CQL\s0 index.  Type\-1 searches against the specified
\&\s-1BIB\-1\s0 access point are mapped to \s-1CQL\s0 searches against the specified
index.
.Sp
If the <index> is omitted within a <map>, then the generated \s-1CQL\s0 query
term has no index specified.  This can be useful for \s-1BIB\-1\s0 attributes
such as 1016 (any) and 1035 (anywhere).
.SS "Databases"
.IX Subsection "Databases"
The <database> element which describes each database contains the
following elements in the specified order.
.PP
In general, <database> entries are of two kinds: those connecting
through to a Z39.50 database will have no <search> element, since no
query mapping is necessary to translate an incoming Type\-1 query; but
those connecting to an \s-1SRU\s0 or \s-1SRW\s0 database will have a <search>
element with <querytype> set to \f(CW\*(C`cql\*(C'\fR and containing information on
how to map from specified \s-1BIB\-1\s0 use attributes to \s-1CQL\s0 indexes.
.IP "<zurl>" 4
.IX Item "<zurl>"
Contains the target address of the
back-end database (e.g. \f(CW\*(C`tcp:z3950.indexdata.com/gils\*(C'\fR or
\&\f(CW\*(C`http://z3950.loc.gov:7090/voyager\*(C'\fR).
.IP "<resultsetid>" 4
.IX Item "<resultsetid>"
Optional.  If provided, it must take one of the following values, and
if it is omitted then the value \f(CW\*(C`fallback\*(C'\fR is assumed:
.RS 4
.ie n .IP """id""" 4
.el .IP "\f(CWid\fR" 4
.IX Item "id"
When queries are received that include references to existing
result-sets, these are translated into result-set references using the
\&\f(CW\*(C`cql.resultSetId\*(C'\fR index.  It is an error if the server does not
support this facility.
.ie n .IP """search""" 4
.el .IP "\f(CWsearch\fR" 4
.IX Item "search"
References to existing result-sets are rewritten as resubmissions of
the query.  This works on all servers, but does not reliably give
precisely correct results if the database is updated between searches.
.ie n .IP """fallback""" 4
.el .IP "\f(CWfallback\fR" 4
.IX Item "fallback"
Result-set references are used when supported, but resubmissions of
prior queries are used when this facility is unavailable.
.RE
.RS 4
.RE
.IP "<nonamedresultsets>" 4
.IX Item "<nonamedresultsets>"
This is optional.  If provided, it is empty and indicates that the
back-end database does not support named result sets.
.IP "<option>" 4
.IX Item "<option>"
There may be any number of these.
Each <option> element carries a \f(CW\*(C`name\*(C'\fR attribute and contains a
corresponding value.  These are \s-1ZOOM\s0 options which are applied to the
connection when it is first created, and can be used to control, for
example, the desired \f(CW\*(C`elementSetName\*(C'\fR or \f(CW\*(C`schema\*(C'\fR of the records
provided by the back-end.  A particularly important option is \f(CW\*(C`sru\*(C'\fR,
which may be set to \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`post\*(C'\fR or \f(CW\*(C`soap\*(C'\fR to request vanilla \s-1SRU\s0,
\&\s-1SRU\s0 over \s-1POST\s0 and \s-1SRW\s0 respectively.
.IP "<charset>" 4
.IX Item "<charset>"
Optional.  Contains the name of the character-set in which the
back-end target supplies records (e.g. \f(CW\*(C`marc\-8\*(C'\fR)
.IP "<search>" 4
.IX Item "<search>"
Optional.  Provides specifications for how to search the database,
exactly like the top-level <search> element described above.
.IP "<schema>" 4
.IX Item "<schema>"
Optional and repeatable: each element indicates special handling for
when records are requested in a particular schema.  See below.
.IP "<sutrs\-record>, <usmarc\-record>, <grs1\-record>." 4
.IX Item "<sutrs-record>, <usmarc-record>, <grs1-record>."
Optional.  Provides specifications for how to construct records in the
relevant syntaxes when they are requested by clients.
.Sp
The format is the same in all cases: the specification contains a list
of <field> elements, each of which has an \f(CW\*(C`xpath\*(C'\fR attribute and
textual content.  Records are built by accessing the data addressed by
the specified XPath expressions, and encoding each as an element
addressed as specified by the element content.  The interpretation of
the content is different for different record-syntaxes:
.RS 4
.IP "\s-1SUTRS\s0" 4
.IX Item "SUTRS"
The content is ignored.
.IP "\s-1USMARC\s0" 4
.IX Item "USMARC"
The content indicates a \s-1MARC\s0 field by a string consisting of the
following parts, in order: a three-digit field number; optionally a
slash followed by the first indicator; optionally another slash
followed by the second indicator; optionally a dollar sign followed by
a subfield tag.  In other words, \s-1MARC\s0 field specifications much match
the regular expression \f(CW\*(C`/^\ed\ed\ed(/w)?(/w?)(\e$\ew)?$/\*(C'\fR.  It is
impossible to specify the second indicator without the first, but a
subfield may be specified along with zero, one or two indicators.
.Sp
As usual, a few examples are worth any amount of explanation:
.Sp
.Vb 5
\&        001
\&        260$c
\&        500$a
\&        100/1$a
\&        245/1/0$a
.Ve
.IP "\s-1GRS\-1\s0" 4
.IX Item "GRS-1"
The content indicates an address within a \s-1GRS\-1\s0 record in the form of
one or more consecutive (type,value) pairs, each enclosed in
parentheses.  For example, \f(CW\*(C`(1,14)\*(C'\fR would indicate an element of
type 1 (tagSet-M) with value 14 (localControlNumber).  A longer path
such as \f(CW\*(C`(3,admin)(2,6)\*(C'\fR indicates an abstract field (tagSet-G
element 6) within an \*(L"admin\*(R" sub-record.
.RE
.RS 4
.RE
.SS "Schemas"
.IX Subsection "Schemas"
Each <schema> element is empty, but carries the following attributes,
which are used to provide records to Z39.50 clients in \s-1MARC\s0 formats.
.IP "oid" 4
.IX Item "oid"
Mandatory.  This is the \s-1OID\s0 of a Z39.50 record-syntax which is to be
handled by schema mapping.  Requests in this database for this
record-syntax are handled as specified.
Example value: \f(CW1.2.840.10003.5.10\fR
.IP "sru" 4
.IX Item "sru"
Mandatory.  This is the \s-1URI\s0 of an \s-1SRU/W\s0 schema which is requested from
the \s-1SRU\s0 or \s-1SRW\s0 back-end in order to fulfill the request.
Example value: \f(CW\*(C`info:srw/schema/1/marcxml\-v1.1\*(C'\fR
.IP "format" 4
.IX Item "format"
Optional.  Indicates which of the \s-1MARC\s0 variants is in use, so that the
record can be formatted correctly.  Defaults to \f(CW\*(C`MARC21\*(C'\fR if omitted.
Example values: \f(CW\*(C`MARC21\*(C'\fR, \f(CW\*(C`USMARC\*(C'\fR, \f(CW\*(C`UNIMARC\*(C'\fR
.IP "encoding" 4
.IX Item "encoding"
Optional.  Indicates which character-set to use for the formatted
record.  Defaults to \f(CW\*(C`UTF\-8\*(C'\fR if omitted.
Example values: \f(CW\*(C`UTF\-8\*(C'\fR, <\s-1MARC\-8\s0>
.PP
\&\fB\s-1NOTE\s0\fR that in its current form this schema-mapping only works for
the specific though common combination of Z39.50 front-end, \s-1SRU\s0
back-end and \s-1MARC\s0 record syntax.
.SH "CONFIGURATION FILE SCHEMA"
.IX Header "CONFIGURATION FILE SCHEMA"
The Simple2ZOOM distribution includes, in the \f(CW\*(C`etc\*(C'\fR directory, an \s-1XML\s0
schema which can be used to validate configuration files.  This schema
is provided in four formats:
.IP "simple2zoom.rnc" 4
.IX Item "simple2zoom.rnc"
Relax-NG compact format: a simple, elegant, terse and wholly
comprehensible \s-1XML\s0 constraint language that you don't even need to
learn in order to understand.  This is the master version: the others
are automatically generated from it.
.IP "simple2zoom.rng" 4
.IX Item "simple2zoom.rng"
Relax-NG \s-1XML\s0 format: the world seems to have this zany fetish that
everything must be specified in \s-1XML\s0, so Relax-NG has an \s-1XML\s0 syntax
that corresponds trivially with the much nicer compact syntax.  The
principle value of this is that \f(CW\*(C`xmllint\*(C'\fR understands it.
.IP "simple2zoom.dtd" 4
.IX Item "simple2zoom.dtd"
An old-fashioned \s-1DTD\s0 (document type definition).
.IP "simple2zoom.xsd" 4
.IX Item "simple2zoom.xsd"
If you must.
.PP
Use whichever you like.  For example,
.PP
.Vb 3
\& xmllint \-\-relaxng simple2zoom.rng \-\-noout test.xml
\& xmllint \-\-dtdvalid simple2zoom.dtd \-\-noout test.xml
\& xmllint \-\-schema simple2zoom.xsd \-\-noout test.xml
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The \f(CW\*(C`simple2zoom\*(C'\fR program.
.PP
The \f(CW\*(C`Net::Z3950::Simple2ZOOM\*(C'\fR module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Taylor <mike@indexdata.com>
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2007 by Index Data.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.