+
+ <refsect1 id="target_settings"><title>TARGET SETTINGS</title>
+ <para>
+ Pazpar2 features a cunning scheme by which you can associate various
+ kinds of attributes, or settings with search targets. This is done
+ through XML files; each file can associate one or more settings
+ with one or more targets. The file format is generic in nature,
+ designed to support a wide range of application requirements. The
+ settings can be purely technical things, like, how to perform a title
+ search against a given target, or it can associate arbitrary name=value
+ pairs with groups of targets -- for instance, if you would like to
+ place all commercial full-text bases in one group for selection
+ purposes, or you would like to control what targets are accessible
+ to users by default.
+ </para>
+
+ <para>
+ During startup, pazpar2 will recursively read a specified directory
+ (can be identified in the pazpar2.cfg file or on the command line), and
+ process any settings files found therein.
+ </para>
+
+ <para>
+ Clients of the pazpar2 webservice interface can selectively override
+ settings for individual targets within the scope of one session. This
+ can be used in conjunction with an external authentication system to
+ determine which resources are to be accessible to which users. Pazpar2
+ itself has no notion of end-users, and so can be used in conjunction
+ with any type of authentication system. Similarly, the authentication
+ tokens submitted to access-controlled search targets can similarly be
+ overriden, to allow use of pazpar2 in a consortial or multi-library
+ environment, where different end-users may need to be represented to
+ some search targets in different ways. This, again, can be managed
+ using an external database or other lookup mechanism.
+ </para>
+
+ <refsect2><title>SETTINGS FILE FORMAT</title>
+ <para>
+ Each file contains a root element named <settings>. It may
+ contain one or more <set> elements. The settings and set
+ elements may contain the following attributes. Attributes in the set node
+ overrides those in the setting root element. Each set node must
+ specify (directly, or inherited from the parent node) at least a
+ target, name, and value.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>target</term>
+ <listitem>
+ <para>
+ This specifies the search target to which this setting should be
+ applied. Targets are identified by their Z39.50 URL, generally
+ including the host, port, and database name, (e.g.
+ bagel.indexdata.com:210/marc). Two wildcard forms are accepted:
+ * (asterisk) matches all known targets;
+ bagel.indexdata.com:210/* matches all known databases on the given
+ host.
+ </para>
+ <para>
+ A precedence system determines what happens if there are
+ overlapping values for the same setting name for the same
+ target. A setting for a specific target name overrides a
+ setting whch specifies target using a wildcard. This makes it
+ easy to set defaults for all targets, and then override them
+ for specific targets or hosts. If there are
+ multiple overlapping settings with the same name and target
+ value, the 'precedence' attribute determines what happens.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>name</term>
+ <listitem>
+ <para>
+ The name of the setting. This can be anything you like.
+ However, pazpar2 reserves a number of setting names for
+ specific purposes, all starting with 'pz:', and it is a good
+ idea to avoid that prefix if you make up your own setting
+ names. See below for a list of reserved variables.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>value</term>
+ <listitem>
+ <para>
+ The value of the setting. Generally, this can be anything you
+ want -- however, some of the reserved settings may expect
+ specific kinds of values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>precedence</term>
+ <listitem>
+ <para>
+ This should be an integer. If not provided, the default value
+ is 0. If two (or more) settings have the same content for
+ target and name, the precedence value determines the outcome.
+ If both settings have the same precedence value, they are both
+ applied to the target(s). If one has a higher value, then the
+ value of that setting is applied, and the other one is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ By setting defaults for target, name, or value in the root
+ settings node, you can use the settings files in many different
+ ways. For instance, you can use a single file to set defaults for
+ many different settings, like search fields, retrieval syntaxes,
+ etc. You can have one file per server, which groups settings for
+ that server or target. You could also have one file which associates
+ a number of targets with a given setting, for instance, to associate
+ many databases with a given category or class that makes sense
+ within your application.
+ </para>
+
+ <para>
+ The following examples illustrate uses of the settings system to
+ associate settings with targets to meet different requirements.
+ </para>
+
+ <para>
+ The example below associates a set of default values that can be
+ used across many targets. Note the wildcard for targets.
+ This associates the given settings with all targets for which no
+ other information is provided.
+ <screen><![CDATA[
+<settings target="*">
+
+ <!-- This file introduces default settings for pazpar2 -->
+ <!-- $Id: pazpar2_conf.xml,v 1.20 2007-04-11 03:34:11 quinn Exp $ -->
+
+ <!-- mapping for unqualified search -->
+ <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
+
+ <!-- field-specific mappings -->
+ <set name="pz:cclmap:ti" value="u=4 s=al"/>
+ <set name="pz:cclmap:su" value="u=21 s=al"/>
+ <set name="pz:cclmap:isbn" value="u=7"/>
+ <set name="pz:cclmap:issn" value="u=8"/>
+ <set name="pz:cclmap:date" value="u=30 r=r"/>
+
+ <!-- Retrieval settings -->
+
+ <set name="pz:requestsyntax" value="marc21"/>
+ <!-- <set name="pz:elements" value="F"/> NOT YET IMPLEMENTED -->
+
+ <!-- Result normalization settings -->
+
+ <set name="pz:nativesyntax" value="iso2709"/>
+ <set name="pz:xslt" value="../etc/marc21.xsl"/>
+
+</settings>
+
+ ]]></screen>
+ </para>
+
+ <para>
+ The next example shows certain settings overriden for one target,
+ one which returns XML records containing DublinCore elements, and
+ which furthermore requires a username/password.
+ <screen><![CDATA[
+<settings target="funkytarget.com:210/db1">
+ <set name="pz:requestsyntax" value="xml"/>
+ <set name="pz:nativesyntax" value="xml"/>
+ <set name="pz:xslt" value="../etc/dublincore.xsl"/>
+
+ <set name="pz:authentication" value="myuser/password"/>
+</settings>
+ ]]></screen>
+ </para>
+
+ <para>
+ The following example associates a specific name/value combination
+ with a number of targets. The targets below are access-restricted,
+ and can only be used by users with special credentials.
+ <screen><![CDATA[
+<settings name="pz:allow" value="0">
+ <set target="funkytarget.com:210/*"/>
+ <set target="commercial.com:2100/expensiveDb"/>
+</settings>
+ ]]></screen>
+ </para>
+
+ </refsect2>
+
+ <refsect2><title>RESERVED SETTING NAMES</title>
+ <para>
+ The following setting names are reserved by pazpar2 to control the
+ behavior of the client function.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>pz:cclmap:xxx</term>
+ <listitem>
+ <para>
+ This establishes a CCL field definition or other setting, for
+ the purpose of mapping end-user queries. XXX is the field or
+ setting name, and the value of the setting provides parameters
+ (e.g. parameters to send to the server, etc.). Please consult
+ the YAZ manual for a full overview of the many capabilities of
+ the powerful and flexible CCL parser.
+ </para>
+ <para>
+ Note that it is easy to etablish a set of default parameters,
+ and then override them individually for a given target.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:requestsyntax</term>
+ <listitem>
+ <para>
+ This specifies the record syntax to use when requesting
+ records from a given server. The value can be a symbolic name like
+ marc21 or xml, or it can be a Z39.50-style dot-separated OID.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:elements</term>
+ <listitem>
+ <para>
+ The element set name to be used when retrieving records from a
+ server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:piggyback</term>
+ <listitem>
+ <para>
+ Piggybacking enables the server to retrieve records from the
+ server as part of the search response in Z39.50. Almost all
+ servers support this (or fail it gracefully), but a few
+ servers will produce undesirable results.
+ Set to '1' to enable piggybacking, '0' to disable it. Default
+ is 1 (piggybacking enabled).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:nativesyntax</term>
+ <listitem>
+ <para>
+ The representation (syntax) of the retrieval records. Currently
+ recognized values are iso2709 and xml.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:encoding</term>
+ <listitem>
+ <para>
+ The native encoding (character set) of retrieval records. Can be anything
+ recognized by conv, but typical values are marc8 and latin1.
+ The default is UTF-8.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:xslt</term>
+ <listitem>
+ <para>
+ Provides the path of an XSLT stylesheet which will be used to
+ map incoming records to the internal representation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:authentication</term>
+ <listitem>
+ <para>
+ Sets an authentication string for a given server. See the section on
+ authorization and authentication for discussion.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:allow</term>
+ <listitem>
+ <para>
+ Allows or denies access to the resources it is applied to. Possible
+ values are '0' and '1'. The default is '1' (allow access to this resource).
+ See the manual section on authorization and authentication for discussion
+ about how to use this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:maxrecs</term>
+ <listitem>
+ <para>
+ Controls the maximum number of records to be retrieved from a
+ server. The default is 100.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pz:id</term>
+ <listitem>
+ <para>
+ This setting can't be 'set' -- it contains the ID (normally
+ ZURL) for a given target, and is useful for filtering --
+ specifically when you want to select one or more specific
+ targets in the search command.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ </refsect1>
projects / pazpar2-moved-to-github.git / blobdiff