This way, a regular webserver can host the user interface (itself dynamic
or static HTML), and Ajax-style calls can be used from JS (or any other
client-based scripting environment) to interact with the search logic
- in Pazpar2.
+ in Pazpar2.
</para>
<para>
Each command is described in sub sections to follow.
</para>
+ <refsect2 id="command-info">
+ <title>info</title>
+ <para>
+ Returns version and statistics about the Pazpar2 instance.
+ </para>
+ </refsect2>
<refsect2 id="command-init">
<title>init</title>
<para>
Initializes a session.
Returns session ID to be used in subsequent requests. If
- a server ID is given in the Pazpar2 server section, then a
- period (.) and the server ID is appended to the session ID.
+ a server ID is given in the Pazpar2 server section, then
+ that is included in the session ID as suffix after a period (.).
+ </para>
+ <para>
+ If the init command is performed as a HTTP GET request, service
+ and settings from local files are used. The service parameter
+ may chose a particular local service.
+ </para>
+ <para>
+ If the init command is performed as a HTTP POST request and
+ the content-type is text/xml, then the content is XML parsed
+ and treated as service for the session. The root element should be
+ service. Refer to descripton of the
+ <link linkend="service_conf">service</link> format.
+ The posting of a service appeared in Pazpar2 version 1.2.1.
</para>
<para>
Example:
</variablelist>
</para>
</refsect2>
-
+
<refsect2 id="command-ping">
<title>ping</title>
<para>
The settings command applies session-specific settings to one or more
databases. A typical function of this is to enable access to
restricted resources for registered users, or to set a user- or
- library-specific username/password to use against a target. Each
- setting parameter has the form name[target]=value, where name is the
+ library-specific username/password to use against a target.
+ </para>
+ <para>
+ Each setting parameter has the form name[target]=value, where name is the
name of the setting (e.g. pz:authentication), target is a target ID,
or possibly a wildcard, and value is the desired value for the
setting.
</para>
-
+
<para>
Because the settings command manipulates potentially sensitive
information, it is possible to configure Pazpar2 to only allow access
scripting, which in turn is responsible for authenticating the user,
and possibly determining which resources he has access to, etc.
</para>
-
+
<note>
<para>
As a shortcut, it is also possible to override settings directly in
the init command.
</para>
</note>
-
+
+ <para>
+ If the settings command is performed as HTTP POST and the content-type
+ is text/xml, then the content is XML parsed and treated as settings -
+ with a format identical to local
+ <link linkend="target_settings">settings files</link>.
+ The posting of settings appeared in Pazpar version 1.2.1.
+ </para>
+
<para>
Example:
<screen><![CDATA[
</settings>
]]></screen>
</para>
-
+
</refsect2>
<refsect2 id="command-search">
<title>search</title>
<listitem>
<para>
Limits the search to a given set of targets specified by the
- filter. The filter consists a comma separated list of
+ filter. The filter consists of a comma separated list of
<emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
(such as <literal>pz:id</literal>).
<para>
Specifies the first record to retrieve from each target.
The first record in a result set for a target is numbered 0, next
- record is numbered 2. By default maxrecs is 0.
+ record is numbered 1. By default startrecs is 0.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>sort</term>
+ <listitem>
+ <para>
+ Specifies sort criteria. The argument is a comma-separated list
+ (no whitespace allowed) of sort fields, with the highest-priority
+ field first. A sort field may be followed by a colon followed by
+ the number '0' (decreasing) or '1' (increasing). Default
+ sort order is decreasing.
+ Sort field names can be any field name designated as a sort field
+ in the pazpar2.cfg file, or the special names 'relevance',
+ 'retrieval' and 'position'.
+ </para>
+ <para>
+ Sort type 'position' sorts by position/offset for each database.
+ Sort type 'retrieval' sorts by position of retrieval (first record
+ retrieved is 1, second record is 2, etc.).
+ </para>
+ <para>
+ If not specified here or as
+ <link linkend="sort-default">sort-default"</link>
+ in pazpar2.cfg, Pazpar2 will default to the built-in
+ 'relevance' ranking.
+ </para>
+ <para>
+ Having sort criteria at search is important for targets that
+ supports native sorting in order to get best results. Pazpar2
+ will trigger a new search if search criteria changes from Pazpar2
+ to target-based sorting or visa-versa.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mergekey</term>
+ <listitem>
+ <para>
+ Sets mergekey for this search and rest of session, or until
+ another mergekey is given for show/search. The mergekey value is a
+ comma separated list with one or more names as they appear
+ in the service description equivalent to
+ <literal>mergekey="optional"</literal> inside a metadata element.
+ If the empty string is given for mergekey it is disabled
+ and rest of session will use the default mergekey from service
+ or stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rank</term>
+ <listitem>
+ <para>
+ Sets rank method this search and rest of session, or until
+ another rank is given for show/search. The rank value is a
+ comma separated list of pairs field=value pairs. The
+ format is the same as
+ <xref linkend="metadata-rank">rank</xref> for a metadata element.
+ If the empty string is given for rank it is disabled
+ and rest of session will use the default rank from metadata or
+ stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
]]></screen>
</para>
</refsect2>
-
+
<refsect2 id="command-stat">
<title>stat</title>
<para>
]]></screen>
</para>
</refsect2>
-
+
<refsect2 id="command-show">
<title>show</title>
<para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>start</term>
<listitem>
<para>First record to show - 0-indexed.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>num</term>
<listitem>
ready to display. Use this to show first records rapidly without
requiring rapid polling.
</para>
+ <para>
+ If block is set to <literal>preferred</literal>, the command will
+ wait until records have been received from all databases with preferred
+ setting
+ </para>
</listitem>
</varlistentry>
Specifies sort criteria. The argument is a comma-separated list
(no whitespace allowed) of sort fields, with the highest-priority
field first. A sort field may be followed by a colon followed by
- the number '0' or '1', indicating whether results should be sorted in
- increasing or decreasing order according to that field. 0==Decreasing is
- the default.
+ the number '0' (decreasing) or '1' (increasing). Default
+ sort order is decreasing.
Sort field names can be any field name designated as a sort field
- in the pazpar2.cfg file, or the special names 'relevance' and
- 'position'.
+ in the pazpar2.cfg file, or the special names 'relevance',
+ 'retrieval' and 'position'.
+ </para>
+ <para>
+ Sort type 'position' sorts by position/offset for each database.
+ Sort type 'retrieval' sorts by position of retrieval (first record
+ retrieved is 1, second record is 2, etc.).
+ </para>
+ <para>
+ If not specified here or as
+ <link linkend="sort-default">sort-default"</link>
+ in pazpar2.cfg, pazpar2 will default to the built-in
+ 'relevance' ranking.
+ </para>
+ <para>
+ Having sort criteria at search is important for targets that
+ supports native sorting in order to get best results. pazpar2
+ will trigger a new search if search criteria changes from pazpar2
+ to target-based sorting.
</para>
<para>
- For targets where If <link linkend="pz:sortmap">pz:sortmap</link>
+ For targets where If <link linkend="pzsortmap">pz:sortmap</link>
is defined, a sort operation will be executed (possibly including
extending the search).
</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>mergekey</term>
+ <listitem>
+ <para>
+ Sets mergekey for this show and rest of session, or until
+ another mergekey is given for show/search. The mergekey value is a
+ comma separated list with one or more names as they appear
+ in the service description equivalent to
+ <literal>mergekey="optional"</literal> inside a metadata element.
+ If the empty string is given for mergekey it is disabled
+ and rest of session will use the default mergekey from service
+ or stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rank</term>
+ <listitem>
+ <para>
+ Sets rank method this show and rest of session, or until
+ another rank is given for show/search. The rank value is a
+ comma separated list of pairs field=value pairs. The
+ format is the same as
+ <xref linkend="metadata-rank">rank</xref> for a metadata element.
+ If the empty string is given for rank it is disabled
+ and rest of session will use the default rank from metadata or
+ stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>snippets</term>
+ <listitem>
+ <para>
+ If specified and set to 1 data will include snippets marked
+ with <match> tags. Otherwise snippets will not be included.
+ </para>
+ <para>
+ This facility, "snippets", appeared in Pazpar2 version
+ 1.6.32.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
<para>
<num>2</num> -- Number of records retrieved
<hit>
<md-title>How to program a computer, by Jack Collins</md-title>
- <count>2</count> -- Number of merged records
+ <count>2</count> -- Number of merged records
<recid>6</recid> -- Record ID for this record
</hit>
<hit>
<refsect2 id="command-record">
<title>record</title>
<para>
- Retrieves a detailed record. Unlike the
- <link linkend="command-show">show</link> command, this command
+ Retrieves a detailed record. Unlike the
+ <link linkend="command-show">show</link> command, this command
returns metadata records before merging takes place. Parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
<term>syntax</term>
<listitem>
<para>
- This optional parameter is the record syntax used for raw
+ This optional parameter is the record syntax used for raw
transfer (i.e. when offset is specified). If syntax is not given,
but offset is used, the value of pz:requestsyntax is used.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>snippets</term>
+ <listitem>
+ <para>
+ If specified and set to 1 data will include snippets marked
+ with <match> tags. Otherwise snippets will not be included.
+ </para>
+ <para>
+ This facility, "snippets", appeared in Pazpar2 version
+ 1.6.32.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
- <para>
+ <para>
Example:
<screen><![CDATA[
search.pz2?session=605047297&command=record&id=3
]]></screen>
Example output:
-
+
<screen><![CDATA[
<record>
<md-title>
</para>
</refsect2>
+ <refsect2 id="command-stop">
+ <title>stop</title>
+ <para>
+ Makes Pazpar2 stop further search & retrieval for busy databases.
+ </para>
+ </refsect2>
+
<refsect2 id="command-termlist">
<title>termlist</title>
<para>
Retrieves term list(s). Parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
</termlist>
]]></screen>
</para>
-
+
<para>
For the special termlist name "xtargets", results
are returned about the targets which have returned the most hits.
]]></screen>
</para>
</refsect2>
-
+
<refsect2 id="command-bytarget">
<title>bytarget</title>
</varlistentry>
</variablelist>
</para>
- <para>
+ <para>
Example:
<screen><![CDATA[
search.pz2?session=605047297&command=bytarget&id=3
]]></screen>
-
+
Example output:
-
+
<screen><![CDATA[
<bytarget>
<status>OK</status>
<!-- ... more target nodes below as necessary -->
</bytarget>
]]></screen>
-
+
The following client states are defined: Client_Connecting,
Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
Client_Searching, Client_Presenting, Client_Error, Client_Failed,
</para>
</refsect2>
+ <refsect2 id="command-service">
+ <title>service</title>
+ <para>
+ Returns service definition (XML). Parameters:
+ <variablelist>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ Session ID
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ The service command appeared in Pazpar2 version 1.6.32
+ </para>
+ </refsect2>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
projects / pazpar2-moved-to-github.git / blobdiff