doc/pazpar2_conf.xml

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