doc/pazpar2_conf.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY % entities SYSTEM "entities.ent">
   8      %entities;
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <refentry id="pazpar2_conf">
  13  <refentryinfo>
  14   <productname>Pazpar2</productname>
  15   <productnumber>&version;</productnumber>
  16  </refentryinfo>
  17  <refmeta>
  18   <refentrytitle>Pazpar2 conf</refentrytitle>
  19   <manvolnum>5</manvolnum>
  20  </refmeta>
  21
  22  <refnamediv>
  23   <refname>pazpar2_conf</refname>
  24   <refpurpose>Pazpar2 Configuration</refpurpose>
  25  </refnamediv>
  26
  27  <refsynopsisdiv>
  28   <cmdsynopsis>
  29    <command>pazpar2.conf</command>
  30   </cmdsynopsis>
  31  </refsynopsisdiv>
  32
  33  <refsect1><title>DESCRIPTION</title>
  34   <para>
  35    The Pazpar2 configuration file, together with any referenced XSLT files,
  36    govern Pazpar2's behavior as a client, and control the normalization and
  37    extraction of data elements from incoming result records, for the
  38    purposes of merging, sorting, facet analysis, and display.
  39   </para>
  40
  41   <para>
  42    The file is specified using the option -f on the Pazpar2 command line.
  43    There is not presently a way to reload the configuration file without
  44    restarting Pazpar2, although this will most likely be added some time
  45    in the future.
  46   </para>
  47  </refsect1>
  48
  49  <refsect1><title>FORMAT</title>
  50   <para>
  51    The configuration file is XML-structured. It must be well-formed XML. All
  52    elements specific to Pazpar2 should belong to the namespace
  53    <literal>http://www.indexdata.com/pazpar2/1.0</literal>
  54    (this is assumed in the
  55    following examples). The root element is named "<literal>pazpar2</literal>".
  56    Under the  root element are a number of elements which group categories of
  57    information. The categories are described below.
  58   </para>
  59
  60   <refsect2 id="config-threads"><title>threads</title>
  61     <para>
  62       This section is optional and is supported for Pazpar2 version 1.3.1 and
  63       later . It is identified by element "<literal>threads</literal>" which
  64       may include one attribute "<literal>number</literal>" which specifies
  65       the number of worker-threads that the Pazpar2 instance is to use.
  66       A value of 0 (zero) disables worker-threads (all work is carried out
  67       in main thread).
  68     </para>
  69   </refsect2>
  70   <refsect2 id="config-server"><title>server</title>
  71    <para>
  72     This section governs overall behavior of a server endpoint. It is identified
  73     by the element "server" which takes an optional attribute, "id", which
  74     identifies this particular Pazpar2 server. Any string value for "id"
  75     may be given.
  76    </para>
  77    <para>The data
  78     elements are described below. From Pazpar2 version 1.2 this is
  79     a repeatable element.
  80    </para>
  81    <variablelist> <!-- level 1 -->
  82     <varlistentry>
  83      <term>listen</term>
  84      <listitem>
  85       <para>
  86        Configures the webservice -- this controls how you can connect
  87        to Pazpar2 from your browser or server-side code. The
  88        attributes 'host' and 'port' control the binding of the
  89        server. The 'host' attribute can be used to bind the server to
  90        a secondary IP address of your system, enabling you to run
  91        Pazpar2 on port 80 alongside a conventional web server. You
  92        can override this setting on the command line using the option -h.
  93       </para>
  94      </listitem>
  95     </varlistentry>
  96
  97     <varlistentry>
  98      <term>proxy</term>
  99      <listitem>
 100       <para>
 101        If this item is given, Pazpar2 will forward all incoming HTTP
 102        requests that do not contain the filename 'search.pz2' to the
 103        host and port specified using the 'host' and 'port'
 104        attributes. The 'myurl' attribute is required, and should provide
 105        the base URL of the server. Generally, the HTTP URL for the host
 106        specified in the 'listen' parameter. This functionality is
 107        crucial if you wish to use
 108        Pazpar2 in conjunction with browser-based code (JS, Flash,
 109        applets, etc.) which operates in a security sandbox. Such code
 110        can only connect to the same server from which the enclosing
 111        HTML page originated. Pazpar2s proxy functionality enables you
 112        to host all of the main pages (plus images, CSS, etc) of your
 113        application on a conventional webserver, while efficiently
 114        processing webservice requests for metasearch status, results,
 115        etc.
 116       </para>
 117      </listitem>
 118     </varlistentry>
 119
 120     <varlistentry>
 121      <term>relevance / sort / mergekey</term>
 122      <listitem>
 123       <para>
 124        Specifies character set normalization for relevancy / sorting
 125        and the mergekey - for the server. These definitions serves as
 126        default for services that don't have these given. For the meaning
 127        of these settings refer to the "relevance" element inside service.
 128       </para>
 129      </listitem>
 130     </varlistentry>
 131
 132     <varlistentry>
 133      <term>settings</term>
 134      <listitem>
 135       <para>
 136        Specifies target settings for the server.. These settings serves
 137        as default for all services which don't have these given.
 138        The settings element requires one attribute 'src' which specifies
 139        a settings file or a directory . If a directory is given all
 140        files with suffix <filename>.xml</filename> is read from this
 141        directory. Refer to
 142        <xref linkend="target_settings"/> for more information.
 143       </para>
 144      </listitem>
 145     </varlistentry>
 146
 147     <varlistentry>
 148      <term>service</term>
 149      <listitem>
 150       <para>
 151        This nested element controls the behavior of Pazpar2 with
 152        respect to your data model. In Pazpar2, incoming records are
 153        normalized, using XSLT, into an internal representation.
 154        The 'service' section controls the further processing and
 155        extraction of data from the internal representation, primarily
 156        through the 'metadata' sub-element.
 157       </para>
 158       <para>
 159        Pazpar2 version 1.2 and later allows multiple service elements.
 160        Multiple services must be given a unique ID by specifying
 161        attribute <literal>id</literal>.
 162        A single service may be unnamed (service ID omitted). The
 163        service ID is referred to in the
 164        <link linkend="command-init"><literal>init</literal></link> webservice
 165        command's <literal>service</literal> parameter.
 166       </para>
 167
 168       <variablelist> <!-- Level 2 -->
 169        <varlistentry><term>metadata</term>
 170         <listitem>
 171          <para>
 172           One of these elements is required for every data element in
 173           the internal representation of the record (see
 174           <xref linkend="data_model"/>. It governs
 175            subsequent processing as pertains to sorting, relevance
 176            ranking, merging, and display of data elements. It supports
 177            the following attributes:
 178          </para>
 179
 180          <variablelist> <!-- level 3 -->
 181           <varlistentry><term>name</term>
 182            <listitem>
 183             <para>
 184              This is the name of the data element. It is matched
 185              against the 'type' attribute of the
 186              'metadata' element
 187              in the normalized record. A warning is produced if
 188              metadata elements with an unknown name are
 189              found in the
 190              normalized record. This name is also used to
 191              represent
 192              data elements in the records returned by the
 193              webservice API, and to name sort lists and browse
 194              facets.
 195             </para>
 196            </listitem>
 197           </varlistentry>
 198
 199           <varlistentry><term>type</term>
 200            <listitem>
 201             <para>
 202              The type of data element. This value governs any
 203              normalization or special processing that might take
 204              place on an element. Possible values are 'generic'
 205              (basic string), 'year' (a range is computed if
 206              multiple years are found in the record). Note: This
 207              list is likely to increase in the future.
 208             </para>
 209            </listitem>
 210           </varlistentry>
 211
 212           <varlistentry><term>brief</term>
 213            <listitem>
 214             <para>
 215              If this is set to 'yes', then the data element is
 216              includes in brief records in the webservice API. Note
 217              that this only makes sense for metadata elements that
 218              are merged (see below). The default value is 'no'.
 219             </para>
 220            </listitem>
 221           </varlistentry>
 222
 223           <varlistentry><term>sortkey</term>
 224            <listitem>
 225             <para>
 226              Specifies that this data element is to be used for
 227              sorting. The possible values are 'numeric' (numeric
 228              value), 'skiparticle' (string; skip common, leading
 229              articles), and 'no' (no sorting). The default value is
 230              'no'.
 231             </para>
 232            </listitem>
 233           </varlistentry>
 234
 235           <varlistentry><term>rank</term>
 236            <listitem>
 237             <para>
 238              Specifies that this element is to be used to
 239              help rank
 240              records against the user's query (when ranking is
 241              requested). The value is an integer, used as a
 242              multiplier against the basic TF*IDF score. A value of
 243              1 is the base, higher values give additional
 244              weight to
 245              elements of this type. The default is '0', which
 246              excludes this element from the rank calculation.
 247             </para>
 248            </listitem>
 249           </varlistentry>
 250
 251           <varlistentry><term>termlist</term>
 252            <listitem>
 253             <para>
 254              Specifies that this element is to be used as a
 255              termlist, or browse facet. Values are tabulated from
 256              incoming records, and a highscore of values (with
 257              their associated frequency) is made available to the
 258              client through the webservice API.
 259              The possible values
 260              are 'yes' and 'no' (default).
 261             </para>
 262            </listitem>
 263           </varlistentry>
 264
 265           <varlistentry><term>merge</term>
 266            <listitem>
 267             <para>
 268              This governs whether, and how elements are extracted
 269              from individual records and merged into cluster
 270              records. The possible values are: 'unique' (include
 271              all unique elements), 'longest' (include only the
 272              longest element (strlen), 'range' (calculate a range
 273              of values across all matching records), 'all' (include
 274              all elements), or 'no' (don't merge; this is the
 275              default);
 276             </para>
 277            </listitem>
 278           </varlistentry>
 279
 280           <varlistentry><term>mergekey</term>
 281            <listitem>
 282             <para>
 283              If set to '<literal>required</literal>', the value of this
 284              metadata element is appended to the resulting mergekey if
 285              the metadata is present in a record instance.
 286              If the metadata element is not present, the a unique mergekey
 287              will be generated instead.
 288             </para>
 289             <para>
 290              If set to '<literal>optional</literal>', the value of this
 291              metadata element is appended to the resulting mergekey if the
 292              the metadata is present in a record instance. If the metadata
 293              is not present, it will be empty.
 294             </para>
 295             <para>
 296              If set to '<literal>no</literal>' or the mergekey attribute is
 297              omitted, the metadata will not be used in the creation of a
 298              mergekey.
 299             </para>
 300            </listitem>
 301           </varlistentry>
 302
 303           <varlistentry><term>setting</term>
 304            <listitem>
 305             <para>
 306              This attribute allows you to make use of static database
 307              settings in the processing of records. Three possible values
 308              are allowed. 'no' is the default and doesn't do anything.
 309              'postproc' copies the value of a setting with the same name
 310              into the output of the normalization stylesheet(s). 'parameter'
 311              makes the value of a setting with the same name available
 312              as a parameter to the normalization stylesheet, so you
 313              can further process the value inside of the stylesheet, or use
 314              the value to decide how to deal with other data values.
 315             </para>
 316             <para>
 317              The purpose of using settings in this way can either be to
 318              control the behavior of normalization stylesheet in a database-
 319              dependent way, or to easily make database-dependent values
 320              available to display-logic in your user interface, without having
 321              to implement complicated interactions between the user interface
 322              and your configuration system.
 323             </para>
 324            </listitem>
 325           </varlistentry>
 326
 327          </variablelist> <!-- attributes to metadata -->
 328
 329         </listitem>
 330        </varlistentry>
 331
 332        <varlistentry>
 333         <term>relevance</term>
 334         <listitem>
 335          <para>
 336           Specifies ICU tokenization and transformation rules
 337           for tokens that are used in Pazpar2's relevance ranking.
 338           The 'id' attribute is currently not used, and the 'locale'
 339           attribute must be set to one of the locale strings
 340           defined in ICU. The child elements listed below can be
 341           in any order, except the 'index' element which logically
 342           belongs to the end of the list. The stated tokenization,
 343           transformation and charmapping instructions are performed
 344           in order from top to bottom.
 345          </para>
 346          <variablelist> <!-- Level 2 -->
 347           <varlistentry><term>casemap</term>
 348            <listitem>
 349             <para>
 350              The attribute 'rule' defines the direction of the
 351              per-character casemapping, allowed values are "l"
 352              (lower), "u" (upper), "t" (title).
 353             </para>
 354            </listitem>
 355           </varlistentry>
 356           <varlistentry><term>transform</term>
 357            <listitem>
 358             <para>
 359              Normalization and transformation of tokens follows
 360              the rules defined in the 'rule' attribute. For
 361              possible values we refer to the extensive ICU
 362              documentation found at the
 363              <ulink url="&url.icu.transform;">ICU
 364               transformation</ulink> home page. Set filtering
 365              principles are explained at the
 366              <ulink url="&url.icu.unicode.set;">ICU set and
 367               filtering</ulink> page.
 368             </para>
 369            </listitem>
 370           </varlistentry>
 371           <varlistentry><term>tokenize</term>
 372            <listitem>
 373             <para>
 374              Tokenization is the only rule in the ICU chain
 375              which splits one token into multiple tokens. The
 376              'rule' attribute may have the following values:
 377              "s" (sentence), "l" (line-break), "w" (word), and
 378              "c" (character), the later probably not being
 379              very useful in a pruning Pazpar2 installation.
 380             </para>
 381            </listitem>
 382           </varlistentry>
 383          </variablelist>
 384          <para>
 385           From Pazpar2 version 1.1 the ICU wrapper from YAZ is used.
 386           Refer to the <ulink url="&url.yaz.yaz-icu;">yaz-icu</ulink>
 387           utility for more information.
 388          </para>
 389         </listitem>
 390        </varlistentry>
 391
 392        <varlistentry>
 393         <term>sort</term>
 394         <listitem>
 395          <para>
 396           Specifies ICU tokenization and transformation rules
 397           for tokens that are used in Pazpar2's sorting. The contents
 398           is similar to that of <literal>relevance</literal>.
 399          </para>
 400         </listitem>
 401        </varlistentry>
 402
 403        <varlistentry>
 404         <term>mergekey</term>
 405         <listitem>
 406          <para>
 407           Specifies ICU tokenization and transformation rules
 408           for tokens that are used in Pazpar2's mergekey. The contents
 409           is similar to that of <literal>relevance</literal>.
 410          </para>
 411         </listitem>
 412        </varlistentry>
 413
 414        <varlistentry>
 415         <term>settings</term>
 416         <listitem>
 417          <para>
 418           Specifies target settings for this service. Refer to
 419           <xref linkend="target_settings"/>.
 420          </para>
 421         </listitem>
 422        </varlistentry>
 423
 424        <varlistentry>
 425         <term>timeout</term>
 426         <listitem>
 427          <para>
 428           Specifies timeout parameters for this service.
 429           The <literal>timeout</literal>
 430           element supports the following attributes:
 431           <literal>session</literal>, <literal>z3950_operation</literal>,
 432           <literal>z3950_session</literal> which specifies
 433           'session timeout', 'Z39.50 operation timeout',
 434           'Z39.50 session timeout' respectively. The Z39.50 operation
 435           timeout is the time Pazpar2 will wait for an active Z39.50/SRU
 436           operation before it gives up (times out). The Z39.50 session
 437           time out is the time Pazpar2 will keep the session alive for
 438           an idle session (no operation).
 439          </para>
 440          <para>
 441           The following is recommended but not required:
 442           z3950_operation (30) &lt; session (60) &lt; z3950_session (180) .
 443           The default values are given in parantheses.
 444          </para>
 445         </listitem>
 446        </varlistentry>
 447
 448       </variablelist>     <!-- Data elements in service directive -->
 449      </listitem>
 450     </varlistentry>
 451
 452    </variablelist>           <!-- Data elements in server directive -->
 453   </refsect2>
 454
 455  </refsect1>
 456
 457  <refsect1><title>EXAMPLE</title>
 458   <para>Below is a working example configuration:
 459    <screen><![CDATA[
 460     <?xml version="1.0" encoding="UTF-8"?>
 461     <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
 462
 463       <threads number="10"/>
 464       <server>
 465         <listen port="9004"/>
 466         <service>
 467           <metadata name="title" brief="yes" sortkey="skiparticle"
 468              merge="longest" rank="6"/>
 469           <metadata name="isbn" merge="unique"/>
 470           <metadata name="date" brief="yes" sortkey="numeric"
 471              type="year" merge="range" termlist="yes"/>
 472           <metadata name="author" brief="yes" termlist="yes"
 473              merge="longest" rank="2"/>
 474           <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
 475           <metadata name="url" merge="unique"/>
 476           <relevance>
 477             <icu_chain id="relevance" locale="el">
 478               <transform rule="[:Control:] Any-Remove"/>
 479               <tokenize rule="l"/>
 480               <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
 481               <casemap rule="l"/>
 482              </icu_chain>
 483            </relevance>
 484            <settings src="mysettings"/>
 485            <timeout session="60"/>
 486         <service>
 487      </server>
 488    </pazpar2>
 489     ]]></screen>
 490   </para>
 491  </refsect1>
 492
 493  <refsect1 id="config-include"><title>INCLUDE FACILITY</title>
 494   <para>
 495    The XML configuration may be partitioned into multiple files by using
 496    the <literal>include</literal> element which takes a single attribute,
 497    <literal>src</literal>. The of the <literal>src</literal> attribute is
 498    regular Shell like glob-pattern. For example,
 499    <screen><![CDATA[
 500     <include src="/etc/pazpar2/conf.d/*.xml"/>
 501     ]]></screen>
 502   </para>
 503   <para>
 504    The include facility requires Pazpar2 version 1.2.
 505   </para>
 506  </refsect1>
 507
 508  <refsect1 id="target_settings"><title>TARGET SETTINGS</title>
 509   <para>
 510    Pazpar2 features a cunning scheme by which you can associate various
 511    kinds of attributes, or settings with search targets. This can be done
 512    through XML files which are read at startup; each file can associate
 513    one or more settings with one or more targets. The file format is generic
 514    in nature, designed to support a wide range of application requirements. The
 515    settings can be purely technical things, like, how to perform a title
 516    search against a given target, or it can associate arbitrary name=value
 517    pairs with groups of targets -- for instance, if you would like to
 518    place all commercial full-text bases in one group for selection
 519    purposes, or you would like to control what targets are accessible
 520    to users by default. Per-database settings values can even be used
 521    to drive sorting, facet/termlist generation, or end-user interface display
 522    logic.
 523   </para>
 524
 525   <para>
 526    During startup, Pazpar2 will recursively read a specified directory
 527    (can be identified in the pazpar2.cfg file or on the command line), and
 528    process any settings files found therein.
 529   </para>
 530
 531   <para>
 532    Clients of the Pazpar2 webservice interface can selectively override
 533    settings for individual targets within the scope of one session. This
 534    can be used in conjunction with an external authentication system to
 535    determine which resources are to be accessible to which users. Pazpar2
 536    itself has no notion of end-users, and so can be used in conjunction
 537    with any type of authentication system. Similarly, the authentication
 538    tokens submitted to access-controlled search targets can similarly be
 539    overridden, to allow use of Pazpar2 in a consortial or multi-library
 540    environment, where different end-users may need to be represented to
 541    some search targets in different ways. This, again, can be managed
 542    using an external database or other lookup mechanism. Setting overrides
 543    can be performed either using the
 544    <link linkend="command-init">init</link> or the
 545    <link linkend="command-settings">settings</link> webservice
 546    command.
 547   </para>
 548
 549   <para>
 550    In fact, every setting that applies to a database (except pz:id, which
 551    can only be used for filtering targets to use for a search) can be overridden
 552    on a per-session basis. This allows the client to override specific CCL fields
 553    for searching, etc., to meet the needs of a session or user.
 554   </para>
 555
 556   <para>
 557    Finally, as an extreme case of this, the webservice client can
 558    introduce entirely new targets, on the fly, as part of the
 559    <link linkend="command-init">init</link> or
 560    <link linkend="command-settings">settings</link> command.
 561    This is useful if you desire to manage information
 562    about your search targets in a separate application such as a database.
 563    You do not need any static settings file whatsoever to run Pazpar2 -- as
 564    long as the webservice client is prepared to supply the necessary
 565    information at the beginning of every session.
 566   </para>
 567
 568   <note>
 569    <para>
 570     The following discussion of practical issues related to session and settings
 571     management are cast in terms of a user interface based on Ajax/Javascript
 572     technology. It would apply equally well to many other kinds of browser-based logic.
 573    </para>
 574   </note>
 575
 576   <para>
 577    Typically, a Javascript client is not allowed to  directly alter the parameters
 578    of a session. There are two reasons for this. One has to do with access
 579    to information; typically, information about a user will be stored in a
 580    system on the server side, or it will be accessible in some way from the server.
 581    However, since the Javascript client cannot be entirely trusted (some hostile
 582    agent might in fact 'pretend' to be a regular ws client), it is more robust
 583    to control session settings from scripting that you run as part of your
 584    webserver. Typically, this can be handled during the session initialization,
 585    as follows:
 586   </para>
 587
 588   <para>
 589    Step 1: The Javascript client loads, and asks the webserver for a new Pazpar2
 590    session ID. This can be done using a Javascript call, for instance. Note that
 591    it is possible to submit Ajax HTTPXmlRequest calls either to Pazpar2 or to the
 592    webserver that Pazpar2 is proxying for. See (XXX Insert link to Pazpar2 protocol).
 593     </para>
 594
 595   <para>
 596    Step 2: Code on the webserver authenticates the user, by database lookup,
 597    LDAP access, NCIP, etc. Determines which resources the user has access to,
 598    and any user-specific parameters that are to be applied during this session.
 599   </para>
 600
 601   <para>
 602    Step 3: The webserver initializes a new Pazpar2 settings, and sets user-specific
 603    parameters as necessary, using the init webservice command. A new session ID is
 604    returned.
 605   </para>
 606
 607   <para>
 608    Step 4: The webserver returns this session ID to the Javascript client, which then
 609    uses the session ID to submit searches, show results, etc.
 610   </para>
 611
 612   <para>
 613    Step 5: When the Javascript client ceases to use the session, Pazpar2 destroys
 614    any session-specific information.
 615   </para>
 616
 617   <refsect2><title>SETTINGS FILE FORMAT</title>
 618    <para>
 619     Each file contains a root element named &lt;settings&gt;. It may
 620     contain one or more &lt;set&gt; elements. The settings and set
 621     elements may contain the following attributes. Attributes in the set node
 622     overrides those in the setting root element. Each set node must
 623     specify (directly, or inherited from the parent node) at least a
 624     target, name, and value.
 625    </para>
 626
 627    <variablelist>
 628     <varlistentry>
 629      <term>target</term>
 630      <listitem>
 631       <para>
 632        This specifies the search target to which this setting should be
 633        applied. Targets are identified by their Z39.50 URL, generally
 634        including the host, port, and database name, (e.g.
 635        <literal>bagel.indexdata.com:210/marc</literal>).
 636        Two wildcard forms are accepted:
 637        * (asterisk) matches all known targets;
 638        <literal>bagel.indexdata.com:210/*</literal> matches all
 639        known databases on the given host.
 640       </para>
 641       <para>
 642        A precedence system determines what happens if there are
 643        overlapping values for the same setting name for the same
 644        target. A setting for a specific target name overrides a
 645        setting which specifies target using a wildcard. This makes it
 646        easy to set defaults for all targets, and then override them
 647        for specific targets or hosts. If there are
 648        multiple overlapping settings with the same name and target
 649        value, the 'precedence' attribute determines what happens.
 650       </para>
 651      </listitem>
 652     </varlistentry>
 653     <varlistentry>
 654      <term>name</term>
 655      <listitem>
 656       <para>
 657        The name of the setting. This can be anything you like.
 658        However, Pazpar2 reserves a number of setting names for
 659        specific purposes, all starting with 'pz:', and it is a good
 660        idea to avoid that prefix if you make up your own setting
 661        names. See below for a list of reserved variables.
 662       </para>
 663      </listitem>
 664     </varlistentry>
 665     <varlistentry>
 666      <term>value</term>
 667      <listitem>
 668       <para>
 669        The value of the setting. Generally, this can be anything you
 670        want -- however, some of the reserved settings may expect
 671        specific kinds of values.
 672       </para>
 673      </listitem>
 674     </varlistentry>
 675     <varlistentry>
 676      <term>precedence</term>
 677      <listitem>
 678       <para>
 679        This should be an integer. If not provided, the default value
 680        is 0. If two (or more) settings have the same content for
 681        target and name, the precedence value determines the outcome.
 682        If both settings have the same precedence value, they are both
 683        applied to the target(s). If one has a higher value, then the
 684        value of that setting is applied, and the other one is ignored.
 685       </para>
 686      </listitem>
 687     </varlistentry>
 688    </variablelist>
 689
 690    <para>
 691     By setting defaults for target, name, or value in the root
 692     settings node, you can use the settings files in many different
 693     ways. For instance, you can use a single file to set defaults for
 694     many different settings, like search fields, retrieval syntaxes,
 695     etc. You can have one file per server, which groups settings for
 696     that server or target. You could also have one file which associates
 697     a number of targets with a given setting, for instance, to associate
 698     many databases with a given category or class that makes sense
 699     within your application.
 700    </para>
 701
 702    <para>
 703     The following examples illustrate uses of the settings system to
 704     associate settings with targets to meet different requirements.
 705    </para>
 706
 707    <para>
 708     The example below associates a set of default values that can be
 709     used across many targets. Note the wildcard for targets.
 710     This associates the given settings with all targets for which no
 711     other information is provided.
 712     <screen><![CDATA[
 713 <settings target="*">
 714
 715   <!-- This file introduces default settings for pazpar2 -->
 716
 717   <!-- mapping for unqualified search -->
 718   <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
 719
 720   <!-- field-specific mappings -->
 721   <set name="pz:cclmap:ti" value="u=4 s=al"/>
 722   <set name="pz:cclmap:su" value="u=21 s=al"/>
 723   <set name="pz:cclmap:isbn" value="u=7"/>
 724   <set name="pz:cclmap:issn" value="u=8"/>
 725   <set name="pz:cclmap:date" value="u=30 r=r"/>
 726
 727   <!-- Retrieval settings -->
 728
 729   <set name="pz:requestsyntax" value="marc21"/>
 730   <set name="pz:elements" value="F"/>
 731
 732   <!-- Query encoding -->
 733   <set name="pz:queryencoding" value="iso-8859-1"/>
 734
 735   <!-- Result normalization settings -->
 736
 737   <set name="pz:nativesyntax" value="iso2709"/>
 738   <set name="pz:xslt" value="../etc/marc21.xsl"/>
 739
 740 </settings>
 741
 742         ]]></screen>
 743    </para>
 744
 745    <para>
 746     The next example shows certain settings overridden for one target,
 747     one which returns XML records containing DublinCore elements, and
 748     which furthermore requires a username/password.
 749     <screen><![CDATA[
 750 <settings target="funkytarget.com:210/db1">
 751   <set name="pz:requestsyntax" value="xml"/>
 752   <set name="pz:nativesyntax" value="xml"/>
 753   <set name="pz:xslt" value="../etc/dublincore.xsl"/>
 754
 755   <set name="pz:authentication" value="myuser/password"/>
 756 </settings>
 757         ]]></screen>
 758    </para>
 759
 760    <para>
 761     The following example associates a specific name/value combination
 762     with a number of targets. The targets below are access-restricted,
 763     and can only be used by users with special credentials.
 764     <screen><![CDATA[
 765 <settings name="pz:allow" value="0">
 766   <set target="funkytarget.com:210/*"/>
 767   <set target="commercial.com:2100/expensiveDb"/>
 768 </settings>
 769         ]]></screen>
 770    </para>
 771
 772   </refsect2>
 773
 774   <refsect2><title>RESERVED SETTING NAMES</title>
 775    <para>
 776     The following setting names are reserved by Pazpar2 to control the
 777     behavior of the client function.
 778    </para>
 779
 780    <variablelist>
 781     <varlistentry>
 782      <term>pz:cclmap:xxx</term>
 783      <listitem>
 784       <para>
 785        This establishes a CCL field definition or other setting, for
 786        the purpose of mapping end-user queries. XXX is the field or
 787        setting name, and the value of the setting provides parameters
 788        (e.g. parameters to send to the server, etc.). Please consult
 789        the YAZ manual for a full overview of the many capabilities of
 790        the powerful and flexible CCL parser.
 791       </para>
 792       <para>
 793        Note that it is easy to establish a set of default parameters,
 794        and then override them individually for a given target.
 795       </para>
 796      </listitem>
 797     </varlistentry>
 798     <varlistentry id="requestsyntax">
 799      <term>pz:requestsyntax</term>
 800      <listitem>
 801       <para>
 802        This specifies the record syntax to use when requesting
 803        records from a given server. The value can be a symbolic name like
 804        marc21 or xml, or it can be a Z39.50-style dot-separated OID.
 805       </para>
 806      </listitem>
 807     </varlistentry>
 808     <varlistentry>
 809      <term>pz:elements</term>
 810      <listitem>
 811       <para>
 812        The element set name to be used when retrieving records from a
 813        server.
 814       </para>
 815      </listitem>
 816     </varlistentry>
 817     <varlistentry>
 818      <term>pz:piggyback</term>
 819      <listitem>
 820       <para>
 821        Piggybacking enables the server to retrieve records from the
 822        server as part of the search response in Z39.50. Almost all
 823        servers support this (or fail it gracefully), but a few
 824        servers will produce undesirable results.
 825        Set to '1' to enable piggybacking, '0' to disable it. Default
 826        is 1 (piggybacking enabled).
 827       </para>
 828      </listitem>
 829     </varlistentry>
 830     <varlistentry>
 831      <term>pz:nativesyntax</term>
 832      <listitem>
 833       <para>
 834        Specifies how Pazpar2 shoule map retrieved records to XML. Currently
 835        supported values are <literal>xml</literal>,
 836        <literal>iso2709</literal> and <literal>txml</literal>.
 837       </para>
 838       <para>
 839        The value <literal>iso2709</literal> makes Pazpar2 convert retrieved
 840        MARC records to MARCXML. In order to convert to XML, the exact
 841        chacater set of the MARC must be known (if not, the resulting
 842        XML is probably not well-formed). The character set may be
 843        specified by adding:
 844        <literal>;charset=</literal><replaceable>charset</replaceable> to
 845        <literal>iso2709</literal>. If omitted, a charset of
 846        MARC-8 is assumed. This is correct for most MARC21/USMARC records.
 847       </para>
 848       <para>
 849        The value <literal>txml</literal> is like <literal>iso2709</literal>
 850        except that records are converted to TurboMARC instead of MARCXML.
 851       </para>
 852       <para>
 853        The value <literal>xml</literal> is used if Pazpar2 retrieves
 854        records that are already XML (no conversion takes place).
 855       </para>
 856      </listitem>
 857     </varlistentry>
 858
 859     <varlistentry>
 860      <term>pz:queryencoding</term>
 861      <listitem>
 862       <para>
 863         The encoding of the search terms that a target accepts. Most
 864         targets do not honor UTF-8 in which case this needs to be specified.
 865         Each term in a query will be converted if this setting is given.
 866       </para>
 867      </listitem>
 868     </varlistentry>
 869
 870     <varlistentry>
 871      <term>pz:negotiation_charset</term>
 872      <listitem>
 873       <para>
 874        Sets character set for Z39.50 negotiation. Most targets do not support
 875        this, and some will even close connection if set (crash on server
 876        side or similar). If set, you probably want to set it to
 877        <literal>UTF-8</literal>.
 878       </para>
 879      </listitem>
 880     </varlistentry>
 881
 882     <varlistentry>
 883      <term>pz:xslt</term>
 884      <listitem>
 885       <para>
 886        Is a comma separated list of of files that specifies
 887        how to convert incoming records to the internal representation.
 888       </para>
 889       <para>
 890        The suffix of each file specifies the kind of tranformation.
 891        Suffix "<literal>.xsl</literal>" makes an XSL transform. Suffix
 892        "<literal>.mmap</literal>" will use the MMAP transform (described below).
 893       </para>
 894       <para>
 895        The special value "<literal>auto</literal>" will use a file
 896        which is the <link linkend="requestsyntax">pz:requestsyntax's</link>
 897        value followed by
 898        <literal>'.xsl'</literal>.
 899       </para>
 900       <para>
 901        When mapping MARC records, XSLT can be bypassed for increased
 902        performance with the alternate "MARC map" format.  Provide the
 903        path of a file with extension ".mmap" containing on each line:
 904        <programlisting>
 905         &lt;field&gt; &lt;subfield&gt; &lt;metadata element&gt;</programlisting>
 906        For example:
 907        <programlisting>
 908         245 a title
 909         500 $ description
 910         773 * citation</programlisting>
 911        To map the field value specify a subfield of '$'.  To store a
 912        concatenation of all subfields, specify a subfield of '*'.
 913       </para>
 914      </listitem>
 915     </varlistentry>
 916     <varlistentry>
 917      <term>pz:authentication</term>
 918      <listitem>
 919       <para>
 920        Sets an authentication string for a given server. See the section on
 921        authorization and authentication for discussion.
 922       </para>
 923      </listitem>
 924     </varlistentry>
 925     <varlistentry>
 926      <term>pz:allow</term>
 927      <listitem>
 928       <para>
 929        Allows or denies access to the resources it is applied to. Possible
 930        values are '0' and '1'. The default is '1' (allow access to this resource).
 931        See the manual section on authorization and authentication for discussion
 932        about how to use this setting.
 933       </para>
 934      </listitem>
 935     </varlistentry>
 936     <varlistentry>
 937      <term>pz:maxrecs</term>
 938      <listitem>
 939       <para>
 940        Controls the maximum number of records to be retrieved from a
 941        server. The default is 100.
 942       </para>
 943      </listitem>
 944     </varlistentry>
 945     <varlistentry>
 946      <term>pz:id</term>
 947      <listitem>
 948       <para>
 949        This setting can't be 'set' -- it contains the ID (normally
 950        ZURL) for a given target, and is useful for filtering --
 951        specifically when you want to select one or more specific
 952        targets in the search command.
 953       </para>
 954      </listitem>
 955     </varlistentry>
 956     <varlistentry>
 957      <term>pz:zproxy</term>
 958      <listitem>
 959       <para>
 960        The 'pz:zproxy' setting has the value syntax
 961        'host.internet.adress:port', it is used to tunnel Z39.50
 962        requests through the named Z39.50 proxy.
 963       </para>
 964      </listitem>
 965     </varlistentry>
 966
 967     <varlistentry>
 968      <term>pz:apdulog</term>
 969      <listitem>
 970       <para>
 971        If the 'pz:apdulog' setting is defined and has other value than 0,
 972        then Z39.50 APDUs are written to the log.
 973       </para>
 974      </listitem>
 975     </varlistentry>
 976
 977     <varlistentry>
 978      <term>pz:sru</term>
 979      <listitem>
 980       <para>
 981        This setting enables SRU/SRW support. It has three possible settings.
 982        'get', enables SRU access through GET requests. 'post' enables SRU/POST
 983        support, less commonly supported, but useful if very large requests are
 984        to be submitted. 'srw' enables the SRW variation of the protocol.
 985       </para>
 986      </listitem>
 987     </varlistentry>
 988
 989     <varlistentry>
 990      <term>pz:sru_version</term>
 991      <listitem>
 992       <para>
 993        This allows SRU version to be specified. If unset Pazpar2
 994        will the default of YAZ (currently 1.2). Should be set
 995        to 1.1 or 1.2.
 996       </para>
 997      </listitem>
 998     </varlistentry>
 999
1000     <varlistentry>
1001      <term>pz:pqf_prefix</term>
1002      <listitem>
1003       <para>
1004        Allows you to specify an arbitrary PQF query language substring.
1005        The provided string is prefixed the user's query after it has been
1006        normalized to PQF internally in pazpar2.
1007        This allows you to attach complex 'filters' to queries for a given
1008        target, sometimes necessary to select sub-catalogs
1009        in union catalog systems, etc.
1010       </para>
1011      </listitem>
1012     </varlistentry>
1013
1014     <varlistentry>
1015      <term>pz:pqf_strftime</term>
1016      <listitem>
1017       <para>
1018        Allows you to extend a query with dates and operators.
1019        The provided string allows certain substitutions and serves as a
1020        format string.
1021        The special two character sequence '%%' gets converted to the
1022        original query. Other characters leading with the percent sign are
1023        conversions supported by strftime.
1024        All other characters are copied verbatim. For example, the string
1025        <literal>@and @attr 1=30 @attr 2=3 %Y %%</literal>
1026        would search for current year combined with the original PQF (%%).
1027       </para>
1028      </listitem>
1029     </varlistentry>
1030
1031     <varlistentry>
1032      <term>pz:sort</term>
1033      <listitem>
1034       <para>
1035        Specifies sort criteria to be applied to the result set.
1036        Only works for targets which support the sort service.
1037       </para>
1038      </listitem>
1039     </varlistentry>
1040
1041     <varlistentry>
1042      <term>pz:recordfilter</term>
1043      <listitem>
1044       <para>
1045        Specifies a filter which allows Pazpar2 to only include
1046        records that meet a certain criteria in a result. Unmatched records
1047        will be ignored. The filter takes the form name[~value] , which
1048        will include only records with metadata element (name) that has the
1049        substring (value) given. If value is omitted all records with the
1050        metadata present will be included.
1051       </para>
1052      </listitem>
1053     </varlistentry>
1054    </variablelist>
1055
1056   </refsect2>
1057
1058  </refsect1>
1059  <refsect1><title>SEE ALSO</title>
1060   <para>
1061    <citerefentry>
1062     <refentrytitle>pazpar2</refentrytitle>
1063     <manvolnum>8</manvolnum>
1064    </citerefentry>
1065    <citerefentry>
1066     <refentrytitle>yaz-icu</refentrytitle>
1067     <manvolnum>1</manvolnum>
1068    </citerefentry>
1069    <citerefentry>
1070     <refentrytitle>pazpar2_protocol</refentrytitle>
1071     <manvolnum>7</manvolnum>
1072    </citerefentry>
1073   </para>
1074  </refsect1>
1075 </refentry>
1076 <!-- Keep this comment at the end of the file
1077 Local variables:
1078 mode: sgml
1079 sgml-omittag:t
1080 sgml-shorttag:t
1081 sgml-minimize-attributes:nil
1082 sgml-always-quote-attributes:t
1083 sgml-indent-step:1
1084 sgml-indent-data:t
1085 sgml-parent-document:nil
1086 sgml-local-catalogs: nil
1087 sgml-namecase-general:t
1088 End:
1089 -->