Updates to pz:authentication documentation
[pazpar2-moved-to-github.git] / doc / pazpar2_protocol.xml
index e227354..968a799 100644 (file)
   <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
+    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>
     </variablelist>
    </para>
   </refsect2>
-  
+
   <refsect2 id="command-ping">
    <title>ping</title>
    <para>
     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
@@ -181,7 +187,7 @@ search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
 </settings>
 ]]></screen>
    </para>
-   
+
   </refsect2>
   <refsect2 id="command-search">
    <title>search</title>
@@ -210,7 +216,7 @@ search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
       <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>).
@@ -248,7 +254,7 @@ search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
        <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>
@@ -273,21 +279,69 @@ search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
        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. 
+       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 
+       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>
+       </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>
@@ -305,7 +359,7 @@ search.pz2?session=2044502273&command=search&query=computer+science
      ]]></screen>
    </para>
   </refsect2>
+
   <refsect2 id="command-stat">
    <title>stat</title>
    <para>
@@ -347,7 +401,7 @@ search.pz2?session=2044502273&command=stat
      ]]></screen>
   </para>
   </refsect2>
-  
+
   <refsect2 id="command-show">
    <title>show</title>
    <para>
@@ -361,14 +415,14 @@ search.pz2?session=2044502273&command=stat
        </para>
       </listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term>start</term>
       <listitem>
        <para>First record to show - 0-indexed.</para>
       </listitem>
      </varlistentry>
-     
+
      <varlistentry>
       <term>num</term>
       <listitem>
@@ -386,25 +440,10 @@ search.pz2?session=2044502273&command=stat
        ready to display. Use this to show first records rapidly without
        requiring rapid polling.
        </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.
+       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>
@@ -419,17 +458,25 @@ search.pz2?session=2044502273&command=stat
        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'.
-
-       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. 
-
-       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 
+        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="pzsortmap">pz:sortmap</link>
@@ -459,6 +506,40 @@ search.pz2?session=2044502273&command=stat
       </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 &lt;match&gt; 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>
@@ -477,7 +558,7 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
   <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>
@@ -495,10 +576,10 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
   <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>
@@ -578,7 +659,7 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
       <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>
@@ -609,16 +690,30 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>snippets</term>
+      <listitem>
+       <para>
+       If specified and set to 1 data will include snippets marked
+       with &lt;match&gt; 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>
@@ -632,11 +727,18 @@ search.pz2?session=605047297&command=record&id=3
    </para>
   </refsect2>
 
+  <refsect2 id="command-stop">
+   <title>stop</title>
+   <para>
+    Makes Pazpar2 stop further search &amp; retrieval for busy databases.
+   </para>
+  </refsect2>
+
   <refsect2 id="command-termlist">
    <title>termlist</title>
    <para>
     Retrieves term list(s). Parameters:
-    
+
     <variablelist>
      <varlistentry>
       <term>session</term>
@@ -693,7 +795,7 @@ search.pz2?session=2044502273&command=termlist&name=author,subject
 </termlist>
 ]]></screen>
    </para>
-   
+
    <para>
     For the special termlist name "xtargets", results
     are returned about the targets which have returned the most hits.
@@ -714,7 +816,7 @@ search.pz2?session=2044502273&command=termlist&name=author,subject
 ]]></screen>
    </para>
   </refsect2>
-  
+
 
   <refsect2 id="command-bytarget">
    <title>bytarget</title>
@@ -732,14 +834,14 @@ search.pz2?session=2044502273&command=termlist&name=author,subject
      </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>
@@ -753,7 +855,7 @@ search.pz2?session=605047297&command=bytarget&id=3
   <!-- ... 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,
@@ -761,6 +863,25 @@ search.pz2?session=605047297&command=bytarget&id=3
    </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>