Embedded XSLT stylesheets for service
[pazpar2-moved-to-github.git] / 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="icuchain"/> 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="servicexslt" xreflabel="xslt">xslt</term>
373         <listitem>
374          <para>
375           Defines a XSLT stylesheet. The <literal>xslt</literal>
376           element takes exactly one attribute <literal>id</literal>
377           which names the stylesheet. This can be referred to in target
378           settings <xref linkend="pzxslt"/>.
379          </para>
380          <para>
381           The content of the xslt element is the embedded stylesheet XML
382          </para>
383         </listitem>
384        </varlistentry>
385        <varlistentry>
386         <term id="icuchain" xreflabel="icu_chain">icu_chain</term>
387         <listitem>
388          <para>
389           Specifies a named ICU rule set. The icu_chain element must include
390           attribute 'id' which specifies the identifier (name) for the ICU
391           rule set.
392           Pazpar2 uses the particular rule sets for particular purposes.
393           Rule set 'relevance' is used to normalize
394           terms for relevance ranking. Rule set 'sort' is used to 
395           normalize terms for sorting. Rule set 'mergekey' is used to
396           normalize terms for making a mergekey and, finally. Rule set 'facet'
397           is normally used to normalize facet terms, unless
398           <xref linkend="facetrule">facetrule</xref> is given for a
399           metadata field.
400          </para>
401          <para>
402           The icu_chain element must also include a 'locale'
403           attribute which must be set to one of the locale strings
404           defined in ICU. The child elements listed below can be
405           in any order, except the 'index' element which logically
406           belongs to the end of the list. The stated tokenization,
407           transformation and charmapping instructions are performed
408           in order from top to bottom. 
409          </para>
410          <variablelist> <!-- Level 2 -->
411           <varlistentry>
412            <term>casemap</term>
413            <listitem>
414             <para>
415              The attribute 'rule' defines the direction of the
416              per-character casemapping, allowed values are "l"
417              (lower), "u" (upper), "t" (title).  
418             </para>
419            </listitem>
420           </varlistentry>
421           <varlistentry>
422            <term>transform</term>
423            <listitem>
424             <para>
425              Normalization and transformation of tokens follows
426              the rules defined in the 'rule' attribute. For
427              possible values we refer to the extensive ICU
428              documentation found at the 
429              <ulink url="&url.icu.transform;">ICU
430              transformation</ulink> home page. Set filtering
431              principles are explained at the 
432              <ulink url="&url.icu.unicode.set;">ICU set and
433              filtering</ulink> page.
434             </para>
435            </listitem>
436           </varlistentry>
437           <varlistentry>
438            <term>tokenize</term>
439            <listitem>
440             <para>
441              Tokenization is the only rule in the ICU chain
442              which splits one token into multiple tokens. The
443              'rule' attribute may have the following values:
444              "s" (sentence), "l" (line-break), "w" (word), and
445              "c" (character), the later probably not being
446              very useful in a pruning Pazpar2 installation. 
447             </para>
448            </listitem>
449           </varlistentry>
450          </variablelist>
451          <para>
452           From Pazpar2 version 1.1 the ICU wrapper from YAZ is used.
453           Refer to the <ulink url="&url.yaz.yaz-icu;">yaz-icu</ulink>
454           utility for more information.
455          </para>
456         </listitem>
457        </varlistentry>
458        
459        <varlistentry>
460         <term>relevance</term>
461         <listitem>
462          <para>
463           Specifies the ICU rule set used for relevance ranking.
464           The child element of 'relevance' must be 'icu_chain' and the
465           'id' attribute of the icu_chain is ignored. This
466           definition is obsolete and should be replaced by the equivalent
467           construct:
468           <screen>
469            &lt;icu_chain id="relevance" locale="en">..&lt;icu_chain>
470           </screen>
471          </para>
472         </listitem>
473        </varlistentry>
474        
475        <varlistentry>
476         <term>sort</term>
477         <listitem>
478          <para>
479           Specifies the ICU rule set used for sorting.
480           The child element of 'sort' must be 'icu_chain' and the
481           'id' attribute of the icu_chain is ignored. This
482           definition is obsolete and should be replaced by the equivalent
483           construct:
484           <screen>
485            &lt;icu_chain id="sort" locale="en">..&lt;icu_chain>
486           </screen>
487          </para>
488         </listitem>
489        </varlistentry>
490        
491        <varlistentry>
492         <term>mergekey</term>
493         <listitem>
494          <para>
495           Specifies ICU tokenization and transformation rules
496           for tokens that are used in Pazpar2's mergekey. 
497           The child element of 'mergekey' must be 'icu_chain' and the
498           'id' attribute of the icu_chain is ignored. This
499           definition is obsolete and should be replaced by the equivalent
500           construct:
501           <screen>
502            &lt;icu_chain id="mergekey" locale="en">..&lt;icu_chain>
503           </screen>
504          </para>
505         </listitem>
506        </varlistentry>
507
508        <varlistentry>
509         <term>facet</term>
510         <listitem>
511          <para>
512           Specifies ICU tokenization and transformation rules
513           for tokens that are used in Pazpar2's facets.
514           The child element of 'facet' must be 'icu_chain' and the
515           'id' attribute of the icu_chain is ignored. This
516           definition is obsolete and should be replaced by the equivalent
517           construct:
518           <screen>
519            &lt;icu_chain id="facet" locale="en">..&lt;icu_chain>
520           </screen>
521          </para>
522         </listitem>
523        </varlistentry>
524        
525        <varlistentry>
526         <term>settings</term>
527         <listitem>
528          <para>
529           Specifies target settings for this service. Refer to
530           <xref linkend="target_settings"/>.
531          </para>
532         </listitem>
533        </varlistentry>
534
535        <varlistentry>
536         <term>timeout</term>
537         <listitem>
538          <para>
539           Specifies timeout parameters for this service.
540           The <literal>timeout</literal>
541           element supports the following attributes: 
542           <literal>session</literal>, <literal>z3950_operation</literal>,
543           <literal>z3950_session</literal> which specifies
544           'session timeout', 'Z39.50 operation timeout',
545           'Z39.50 session timeout' respectively. The Z39.50 operation
546           timeout is the time Pazpar2 will wait for an active Z39.50/SRU
547           operation before it gives up (times out). The Z39.50 session
548           time out is the time Pazpar2 will keep the session alive for
549           an idle session (no operation).
550          </para>
551          <para>
552           The following is recommended but not required:
553           z3950_operation (30) &lt; session (60) &lt; z3950_session (180) .
554           The default values are given in parantheses.
555          </para>
556         </listitem>
557        </varlistentry>
558       </variablelist>     <!-- Data elements in service directive -->
559      </listitem>
560     </varlistentry>
561    </variablelist>           <!-- Data elements in server directive -->
562   </refsect2>
563  </refsect1>
564
565  <refsect1>
566   <title>EXAMPLE</title>
567   <para>
568    Below is a working example configuration:
569   </para>
570   <screen>
571    <![CDATA[
572 <?xml version="1.0" encoding="UTF-8"?>
573 <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
574
575  <threads number="10"/>
576  <server>
577   <listen port="9004"/>
578   <service>
579    <metadata name="title" brief="yes" sortkey="skiparticle"
580              merge="longest" rank="6"/>
581    <metadata name="isbn" merge="unique"/>
582    <metadata name="date" brief="yes" sortkey="numeric"
583              type="year" merge="range" termlist="yes"/>
584    <metadata name="author" brief="yes" termlist="yes"
585              merge="longest" rank="2"/>
586    <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
587    <metadata name="url" merge="unique"/>
588    <icu_chain id="relevance" locale="el">
589     <transform rule="[:Control:] Any-Remove"/>
590     <tokenize rule="l"/>
591     <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
592     <casemap rule="l"/>
593    </icu_chain>
594    <settings src="mysettings"/>
595    <timeout session="60"/>
596   <service>
597  </server>
598 </pazpar2>
599    ]]>
600   </screen>
601  </refsect1> 
602
603  <refsect1 id="config-include">
604   <title>INCLUDE FACILITY</title>
605   <para>
606    The XML configuration may be partitioned into multiple files by using
607    the <literal>include</literal> element which takes a single attribute,
608    <literal>src</literal>. The of the <literal>src</literal> attribute is
609    regular Shell like glob-pattern. For example,
610    <screen><![CDATA[
611    <include src="/etc/pazpar2/conf.d/*.xml"/>
612    ]]></screen>
613   </para>
614   <para>
615    The include facility requires Pazpar2 version 1.2.
616   </para>
617  </refsect1>
618
619  <refsect1 id="target_settings">
620   <title>TARGET SETTINGS</title>
621   <para>
622    Pazpar2 features a cunning scheme by which you can associate various
623    kinds of attributes, or settings with search targets. This can be done
624    through XML files which are read at startup; each file can associate
625    one or more settings with one or more targets. The file format is generic
626    in nature, designed to support a wide range of application requirements. The
627    settings can be purely technical things, like, how to perform a title
628    search against a given target, or it can associate arbitrary name=value
629    pairs with groups of targets -- for instance, if you would like to
630    place all commercial full-text bases in one group for selection
631    purposes, or you would like to control what targets are accessible
632    to users by default. Per-database settings values can even be used
633    to drive sorting, facet/termlist generation, or end-user interface display
634    logic.
635   </para>
636   
637   <para>
638    During startup, Pazpar2 will recursively read a specified directory
639    (can be identified in the pazpar2.cfg file or on the command line), and
640    process any settings files found therein.
641   </para>
642   
643   <para>
644    Clients of the Pazpar2 webservice interface can selectively override
645    settings for individual targets within the scope of one session. This
646    can be used in conjunction with an external authentication system to
647    determine which resources are to be accessible to which users. Pazpar2
648    itself has no notion of end-users, and so can be used in conjunction
649    with any type of authentication system. Similarly, the authentication
650    tokens submitted to access-controlled search targets can similarly be
651    overridden, to allow use of Pazpar2 in a consortial or multi-library
652    environment, where different end-users may need to be represented to
653    some search targets in different ways. This, again, can be managed
654    using an external database or other lookup mechanism. Setting overrides
655    can be performed either using the
656    <link linkend="command-init">init</link> or the 
657    <link linkend="command-settings">settings</link> webservice
658    command.
659   </para>
660   
661   <para>
662    In fact, every setting that applies to a database (except pz:id, which
663    can only be used for filtering targets to use for a search) can be overridden
664    on a per-session basis. This allows the client to override specific CCL fields
665    for searching, etc., to meet the needs of a session or user.
666   </para>
667
668   <para>
669    Finally, as an extreme case of this, the webservice client can
670    introduce entirely new targets, on the fly, as part of the
671    <link linkend="command-init">init</link> or
672    <link linkend="command-settings">settings</link> command.
673    This is useful if you desire to manage information
674    about your search targets in a separate application such as a database.
675    You do not need any static settings file whatsoever to run Pazpar2 -- as
676    long as the webservice client is prepared to supply the necessary
677    information at the beginning of every session.
678   </para>
679
680   <note>
681    <para>
682     The following discussion of practical issues related to session
683     and settings management are cast in terms of a user interface based on
684     Ajax/Javascript technology. It would apply equally well to many other
685     kinds of browser-based logic.
686    </para>
687   </note>
688
689   <para>
690    Typically, a Javascript client is not allowed to directly alter the
691    parameters of a session. There are two reasons for this. One has to do
692    with access to information; typically, information about a user will
693    be stored in a system on the server side, or it will be accessible in
694    some way from the server.  However, since the Javascript client cannot
695    be entirely trusted (some hostile agent might in fact 'pretend' to be
696    a regular ws client), it is more robust to control session settings
697    from scripting that you run as part of your webserver. Typically, this
698    can be handled during the session initialization, as follows:
699   </para>
700
701   <para>
702    Step 1: The Javascript client loads, and asks the webserver for a
703    new Pazpar2 session ID. This can be done using a Javascript call, for
704    instance. Note that it is possible to submit Ajax HTTPXmlRequest calls
705    either to Pazpar2 or to the webserver that Pazpar2 is proxying
706    for. See (XXX Insert link to Pazpar2 protocol).
707   </para>
708
709   <para>
710    Step 2: Code on the webserver authenticates the user, by database lookup,
711    LDAP access, NCIP, etc. Determines which resources the user has access to,
712    and any user-specific parameters that are to be applied during this session.
713   </para>
714
715   <para>
716    Step 3: The webserver initializes a new Pazpar2 settings, and sets
717    user-specific parameters as necessary, using the init webservice
718    command. A new session ID is returned.
719   </para>
720
721   <para>
722    Step 4: The webserver returns this session ID to the Javascript
723    client, which then uses the session ID to submit searches, show
724    results, etc.
725   </para>
726
727   <para>
728    Step 5: When the Javascript client ceases to use the session,
729    Pazpar2 destroys any session-specific information.
730   </para>
731
732   <refsect2>
733    <title>SETTINGS FILE FORMAT</title>
734    <para>
735     Each file contains a root element named &lt;settings&gt;. It may
736     contain one or more &lt;set&gt; elements. The settings and set
737     elements may contain the following attributes. Attributes in the set
738     node overrides those in the setting root element. Each set node must
739     specify (directly, or inherited from the parent node) at least a
740     target, name, and value.
741    </para>
742
743    <variablelist> 
744     <varlistentry>
745      <term>target</term>
746      <listitem>
747       <para>
748        This specifies the search target to which this setting should be
749        applied. Targets are identified by their Z39.50 URL, generally
750        including the host, port, and database name, (e.g.
751        <literal>bagel.indexdata.com:210/marc</literal>).
752        Two wildcard forms are accepted:
753        * (asterisk) matches all known targets;
754        <literal>bagel.indexdata.com:210/*</literal> matches all
755        known databases on the given host.
756       </para>
757       <para>
758        A precedence system determines what happens if there are
759        overlapping values for the same setting name for the same
760        target. A setting for a specific target name overrides a
761        setting which specifies target using a wildcard. This makes it
762        easy to set defaults for all targets, and then override them
763        for specific targets or hosts. If there are
764        multiple overlapping settings with the same name and target
765        value, the 'precedence' attribute determines what happens.
766       </para>
767       <para>
768        For Pazpar2 1.6.4 or later, the target ID may be user-defined, in
769        which case, the actual host, port, etc is given by setting
770        <xref linkend="pzurl"/>.
771       </para>
772      </listitem>
773     </varlistentry>
774     <varlistentry>
775      <term>name</term>
776      <listitem>
777       <para>
778        The name of the setting. This can be anything you like.
779        However, Pazpar2 reserves a number of setting names for
780        specific purposes, all starting with 'pz:', and it is a good
781        idea to avoid that prefix if you make up your own setting
782        names. See below for a list of reserved variables.
783       </para>
784      </listitem>
785     </varlistentry>
786     <varlistentry>
787      <term>value</term>
788      <listitem>
789       <para>
790        The value of the setting. Generally, this can be anything you
791        want -- however, some of the reserved settings may expect
792        specific kinds of values.
793       </para>
794      </listitem>
795     </varlistentry>
796     <varlistentry>
797      <term>precedence</term>
798      <listitem>
799       <para>
800        This should be an integer. If not provided, the default value
801        is 0. If two (or more) settings have the same content for
802        target and name, the precedence value determines the outcome.
803        If both settings have the same precedence value, they are both
804        applied to the target(s). If one has a higher value, then the
805        value of that setting is applied, and the other one is ignored.
806       </para>
807      </listitem>
808     </varlistentry>
809    </variablelist>
810
811    <para>
812     By setting defaults for target, name, or value in the root
813     settings node, you can use the settings files in many different
814     ways. For instance, you can use a single file to set defaults for
815     many different settings, like search fields, retrieval syntaxes,
816     etc. You can have one file per server, which groups settings for
817     that server or target. You could also have one file which associates
818     a number of targets with a given setting, for instance, to associate
819     many databases with a given category or class that makes sense
820     within your application.
821    </para>
822
823    <para>
824     The following examples illustrate uses of the settings system to
825     associate settings with targets to meet different requirements.
826    </para>
827
828    <para>
829     The example below associates a set of default values that can be
830     used across many targets. Note the wildcard for targets.
831     This associates the given settings with all targets for which no
832     other information is provided.
833     <screen><![CDATA[
834     <settings target="*">
835
836     <!-- This file introduces default settings for pazpar2 -->
837
838     <!-- mapping for unqualified search -->
839     <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
840
841     <!-- field-specific mappings -->
842     <set name="pz:cclmap:ti" value="u=4 s=al"/>
843     <set name="pz:cclmap:su" value="u=21 s=al"/>
844     <set name="pz:cclmap:isbn" value="u=7"/>
845     <set name="pz:cclmap:issn" value="u=8"/>
846     <set name="pz:cclmap:date" value="u=30 r=r"/>
847     
848     <set name="pz:limitmap:title" value="rpn:@attr 1=4 @attr 6=3"/>
849     <set name="pz:limitmap:date" value="ccl:date"/>
850
851     <!-- Retrieval settings -->
852
853     <set name="pz:requestsyntax" value="marc21"/>
854     <set name="pz:elements" value="F"/>
855
856     <!-- Query encoding -->
857     <set name="pz:queryencoding" value="iso-8859-1"/>
858
859     <!-- Result normalization settings -->
860
861     <set name="pz:nativesyntax" value="iso2709"/>
862     <set name="pz:xslt" value="../etc/marc21.xsl"/>
863
864     </settings>
865
866     ]]></screen>
867    </para>
868
869    <para>
870     The next example shows certain settings overridden for one target,
871     one which returns XML records containing DublinCore elements, and
872     which furthermore requires a username/password.
873     <screen><![CDATA[
874     <settings target="funkytarget.com:210/db1">
875     <set name="pz:requestsyntax" value="xml"/>
876     <set name="pz:nativesyntax" value="xml"/>
877     <set name="pz:xslt" value="../etc/dublincore.xsl"/>
878
879     <set name="pz:authentication" value="myuser/password"/>
880     </settings>
881     ]]></screen>
882    </para>
883
884    <para>
885     The following example associates a specific name/value combination
886     with a number of targets. The targets below are access-restricted,
887     and can only be used by users with special credentials.
888     <screen><![CDATA[
889     <settings name="pz:allow" value="0">
890     <set target="funkytarget.com:210/*"/>
891     <set target="commercial.com:2100/expensiveDb"/>
892     </settings>
893     ]]></screen>
894    </para>
895
896   </refsect2>
897
898   <refsect2>
899    <title>RESERVED SETTING NAMES</title>
900    <para>
901     The following setting names are reserved by Pazpar2 to control the
902     behavior of the client function.
903    </para>
904    
905    <variablelist>
906     <varlistentry>
907      <term>pz:cclmap:xxx</term>
908      <listitem>
909       <para>
910        This establishes a CCL field definition or other setting, for
911        the purpose of mapping end-user queries. XXX is the field or
912        setting name, and the value of the setting provides parameters
913        (e.g. parameters to send to the server, etc.). Please consult
914        the YAZ manual for a full overview of the many capabilities of
915        the powerful and flexible CCL parser.
916       </para>
917       <para>
918        Note that it is easy to establish a set of default parameters,
919        and then override them individually for a given target.
920       </para>
921      </listitem>
922     </varlistentry>
923     <varlistentry id="requestsyntax">
924      <term>pz:requestsyntax</term>
925      <listitem>
926       <para>
927        This specifies the record syntax to use when requesting
928        records from a given server. The value can be a symbolic name like
929        marc21 or xml, or it can be a Z39.50-style dot-separated OID.
930       </para>
931      </listitem>
932     </varlistentry>
933     <varlistentry>
934      <term>pz:elements</term>
935      <listitem>
936       <para>
937        The element set name to be used when retrieving records from a
938        server.
939       </para>
940      </listitem>
941     </varlistentry>
942     <varlistentry>
943      <term>pz:piggyback</term>
944      <listitem>
945       <para>
946        Piggybacking enables the server to retrieve records from the
947        server as part of the search response in Z39.50. Almost all
948        servers support this (or fail it gracefully), but a few
949        servers will produce undesirable results.
950        Set to '1' to enable piggybacking, '0' to disable it. Default
951        is 1 (piggybacking enabled).
952       </para>
953      </listitem>
954     </varlistentry>
955     <varlistentry>
956      <term>pz:nativesyntax</term>
957      <listitem>
958       <para>
959        Specifies how Pazpar2 shoule map retrieved records to XML. Currently
960        supported values are <literal>xml</literal>,
961        <literal>iso2709</literal> and <literal>txml</literal>.
962       </para>
963       <para>
964        The value <literal>iso2709</literal> makes Pazpar2 convert retrieved
965        MARC records to MARCXML. In order to convert to XML, the exact
966        chacater set of the MARC must be known (if not, the resulting
967        XML is probably not well-formed). The character set may be 
968        specified by adding:
969        <literal>;charset=</literal><replaceable>charset</replaceable> to
970        <literal>iso2709</literal>. If omitted, a charset of
971        MARC-8 is assumed. This is correct for most MARC21/USMARC records.
972       </para>
973       <para>
974        The value <literal>txml</literal> is like <literal>iso2709</literal>
975        except that records are converted to TurboMARC instead of MARCXML.
976       </para>
977       <para>
978        The value <literal>xml</literal> is used if Pazpar2 retrieves
979        records that are already XML (no conversion takes place).
980       </para>
981      </listitem>
982     </varlistentry>
983
984     <varlistentry>
985      <term>pz:queryencoding</term>
986      <listitem>
987       <para>
988        The encoding of the search terms that a target accepts. Most
989        targets do not honor UTF-8 in which case this needs to be specified.
990        Each term in a query will be converted if this setting is given.
991       </para>
992      </listitem>
993     </varlistentry>
994
995     <varlistentry>
996      <term>pz:negotiation_charset</term>
997      <listitem>
998       <para>
999        Sets character set for Z39.50 negotiation. Most targets do not support
1000        this, and some will even close connection if set (crash on server
1001        side or similar). If set, you probably want to set it to
1002        <literal>UTF-8</literal>.
1003       </para>
1004      </listitem>
1005     </varlistentry>
1006
1007     <varlistentry>
1008      <term id="pzxslt" xreflabel="pz:xslt">pz:xslt</term>
1009      <listitem>
1010       <para>
1011        Is a comma separated list of of stylesheet names that specifies
1012        how to convert incoming records to the internal representation.
1013       </para>
1014       <para>
1015        For each name, the embedded stylesheets (XSL) that comes with the
1016        service definition are consulted first and takes precedence over
1017        external files; see <xref linkend="servicexslt"/>
1018        of service definition).
1019        If the name does not match an embedded stylesheet it is
1020        considered a filename.
1021       </para>
1022       <para>
1023        The suffix of each file specifies the kind of tranformation.
1024        Suffix "<literal>.xsl</literal>" makes an XSL transform. Suffix
1025        "<literal>.mmap</literal>" will use the MMAP transform (described below).
1026       </para>
1027       <para>
1028        The special value "<literal>auto</literal>" will use a file
1029        which is the <link linkend="requestsyntax">pz:requestsyntax's</link>
1030        value followed by
1031        <literal>'.xsl'</literal>.
1032       </para>
1033       <para>
1034        When mapping MARC records, XSLT can be bypassed for increased 
1035        performance with the alternate "MARC map" format.  Provide the
1036        path of a file with extension ".mmap" containing on each line:
1037        <programlisting>
1038        &lt;field&gt; &lt;subfield&gt; &lt;metadata element&gt;</programlisting>
1039        For example:
1040        <programlisting>
1041         245 a title
1042         500 $ description
1043         773 * citation
1044        </programlisting>
1045        To map the field value specify a subfield of '$'.  To store a 
1046        concatenation of all subfields, specify a subfield of '*'.
1047       </para>
1048      </listitem>
1049     </varlistentry>
1050     <varlistentry>
1051      <term>pz:authentication</term>
1052      <listitem>
1053       <para>
1054        Sets an authentication string for a given server. See the section on
1055        authorization and authentication for discussion.
1056       </para>
1057      </listitem>
1058     </varlistentry>
1059     <varlistentry>
1060      <term>pz:allow</term>
1061      <listitem>
1062       <para>
1063        Allows or denies access to the resources it is applied to. Possible
1064        values are '0' and '1'.
1065        The default is '1' (allow access to this resource).
1066        See the manual section on authorization and authentication for
1067        discussion about how to use this setting.
1068       </para>
1069      </listitem>
1070     </varlistentry>
1071     <varlistentry>
1072      <term>pz:maxrecs</term>
1073      <listitem>
1074       <para>
1075        Controls the maximum number of records to be retrieved from a
1076        server. The default is 100.
1077       </para>
1078      </listitem>
1079     </varlistentry>
1080     <varlistentry>
1081      <term>pz:id</term>
1082      <listitem>
1083       <para>
1084        This setting can't be 'set' -- it contains the ID (normally
1085        ZURL) for a given target, and is useful for filtering --
1086        specifically when you want to select one or more specific
1087        targets in the search command.
1088       </para>
1089      </listitem>
1090     </varlistentry>
1091     <varlistentry>
1092      <term>pz:zproxy</term>
1093      <listitem>
1094       <para>
1095        The 'pz:zproxy' setting has the value syntax 
1096        'host.internet.adress:port', it is used to tunnel Z39.50
1097        requests through the named Z39.50 proxy.
1098       </para>
1099      </listitem>
1100     </varlistentry>
1101     
1102     <varlistentry>
1103      <term>pz:apdulog</term>
1104      <listitem>
1105       <para>
1106        If the 'pz:apdulog' setting is defined and has other value than 0,
1107        then Z39.50 APDUs are written to the log.
1108       </para>
1109      </listitem>
1110     </varlistentry>
1111     
1112     <varlistentry>
1113      <term>pz:sru</term>
1114      <listitem>
1115       <para>
1116        This setting enables
1117        <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">SOLR</ulink>
1118        support.
1119        It has four possible settings.
1120        'get', enables SRU access through GET requests. 'post' enables SRU/POST
1121        support, less commonly supported, but useful if very large requests are
1122        to be submitted. 'srw' enables the SRW (SRU over SOAP) variation of
1123        the protocol.
1124       </para>
1125       <para>
1126        A value of 'solr' anables SOLR client support. This is supported
1127        for Pazpar version 1.5.0 and later.
1128       </para>
1129      </listitem>
1130     </varlistentry>
1131     
1132     <varlistentry>
1133      <term>pz:sru_version</term>
1134      <listitem>
1135       <para>
1136        This allows SRU version to be specified. If unset Pazpar2
1137        will the default of YAZ (currently 1.2). Should be set
1138        to 1.1 or 1.2. For SOLR, the current supported/tested version is 1.4
1139       </para>
1140      </listitem>
1141     </varlistentry>
1142     
1143     <varlistentry>
1144      <term>pz:pqf_prefix</term>
1145      <listitem>
1146       <para>
1147        Allows you to specify an arbitrary PQF query language substring.
1148        The provided string is prefixed the user's query after it has been
1149        normalized to PQF internally in pazpar2.
1150        This allows you to attach complex 'filters' to queries for a given
1151        target, sometimes necessary to select sub-catalogs
1152        in union catalog systems, etc.
1153       </para>
1154      </listitem>
1155     </varlistentry>
1156     
1157     <varlistentry>
1158      <term>pz:pqf_strftime</term>
1159      <listitem>
1160       <para>
1161        Allows you to extend a query with dates and operators.
1162        The provided string allows certain substitutions and serves as a
1163        format string.
1164        The special two character sequence '%%' gets converted to the
1165        original query. Other characters leading with the percent sign are
1166        conversions supported by strftime.
1167        All other characters are copied verbatim. For example, the string
1168        <literal>@and @attr 1=30 @attr 2=3 %Y %%</literal>
1169        would search for current year combined with the original PQF (%%).
1170       </para>
1171      </listitem>
1172     </varlistentry>
1173     
1174     <varlistentry>
1175      <term>pz:sort</term>
1176      <listitem>
1177       <para>
1178        Specifies sort criteria to be applied to the result set.
1179        Only works for targets which support the sort service.
1180       </para>
1181      </listitem>
1182     </varlistentry>
1183
1184     <varlistentry>
1185      <term>pz:recordfilter</term>
1186      <listitem>
1187       <para>
1188        Specifies a filter which allows Pazpar2 to only include
1189        records that meet a certain criteria in a result.
1190        Unmatched records  will be ignored.
1191        The filter takes the form name, name~value, or name=value, which
1192        will include only records with metadata element (name) that has the
1193        substring (~value) given, or matches exactly (=value).
1194        If value is omitted all records with the named metadata element
1195        present will be included.
1196       </para>
1197      </listitem>
1198     </varlistentry>
1199     
1200     <varlistentry>
1201      <term>pz:preferred</term>
1202      <listitem>
1203       <para>
1204        Specifies that a target is preferred, e.g. possible local, faster
1205        target. Using block=pref on show command will wait for all these
1206        targets to return records before releasing the block.
1207        If no target is preferred, the block=pref will identical to block=1,
1208        which release when one target has returned records.     
1209       </para>
1210      </listitem>
1211     </varlistentry>
1212
1213     <varlistentry>
1214      <term>pz:block_timeout</term>
1215      <listitem>
1216       <para>
1217        (Not yet implemented).
1218        Specifies the time for which a block should be released anyway.      
1219       </para>
1220      </listitem>
1221     </varlistentry>
1222
1223     <varlistentry>
1224      <term>pz:facetmap:<replaceable>name</replaceable></term>
1225      <listitem>
1226       <para>
1227        Specifies that for field <replaceable>name</replaceable>, the target
1228        supports (native) facets. The value is the name of the
1229        field on the target.
1230       </para>
1231       <note>
1232        <para>
1233         At this point only SOLR targets have been tested with this
1234         facility.
1235        </para>
1236       </note>
1237      </listitem>
1238     </varlistentry>
1239
1240     <varlistentry id="limitmap">
1241      <term>pz:limitmap:<replaceable>name</replaceable></term>
1242      <listitem>
1243       <para>
1244        Specifies attributes for limiting a search to a field - using
1245        the limit parameter for search. In some cases the mapping of 
1246        a field to a value is identical to an existing cclmap field; in
1247        other cases the field must be specified in a different way - for
1248        example to match a complete field (rather than parts of a subfield).
1249       </para>
1250       <para>
1251        The value of limitmap may have one of two forms: referral to
1252        an exisiting CCL field or a raw PQF string. Leading string
1253        determines type; either <literal>ccl:</literal> for CCL field or
1254        <literal>rpn:</literal> for PQF/RPN.
1255       </para>
1256       <note>
1257        <para>
1258         The limitmap facility is supported for Pazpar2 version 1.6.0.
1259        </para>
1260       </note>
1261      </listitem>
1262     </varlistentry>
1263
1264     <varlistentry id="pzurl">
1265      <term>pz:url</term>
1266      <listitem>
1267       <para>
1268        Specifies URL for the target and overrides the target ID.
1269       </para>
1270       <note>
1271        <para>
1272         <literal>pz:url</literal> is only recognized for
1273         Pazpar2 1.6.4 and later.
1274        </para>
1275       </note>
1276      </listitem>
1277     </varlistentry>
1278
1279     <varlistentry id="pzsortmap">
1280      <term>pz:sortmap:<replaceable>field</replaceable></term>
1281      <listitem>
1282       <para>
1283        Specifies native sorting for a target where
1284        <replaceable>field</replaceable> is a sort criteria (see command
1285        show). The value has to components separated by colon: strategy and
1286        native-field. Strategy is one of <literal>z3950</literal>,
1287        <literal>type7</literal>, <literal>cql</literal>,
1288        <literal>sru11</literal>, or <literal>embed</literal>.
1289        The second component, native-field, is the field that is recognized
1290        by the target.
1291       </para>
1292       <note>
1293        <para>
1294         Only supported for Pazpar2 1.6.4 and later.
1295        </para>
1296       </note>
1297      </listitem>
1298     </varlistentry>
1299     
1300    </variablelist>
1301    
1302   </refsect2>
1303
1304  </refsect1>
1305  <refsect1>
1306   <title>SEE ALSO</title>
1307   <para>
1308    <citerefentry>
1309     <refentrytitle>pazpar2</refentrytitle>
1310     <manvolnum>8</manvolnum>
1311    </citerefentry>
1312    <citerefentry>
1313     <refentrytitle>yaz-icu</refentrytitle>
1314     <manvolnum>1</manvolnum>
1315    </citerefentry>
1316    <citerefentry>
1317     <refentrytitle>pazpar2_protocol</refentrytitle>
1318     <manvolnum>7</manvolnum>
1319    </citerefentry>
1320   </para>
1321  </refsect1>
1322 </refentry>
1323 <!-- Keep this comment at the end of the file
1324 Local variables:
1325 mode: nxml
1326 nxml-child-indent: 1
1327 End:
1328 -->