+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+[
+ <!ENTITY % local SYSTEM "local.ent">
+ %local;
+ <!ENTITY % entities SYSTEM "entities.ent">
+ %entities;
+ <!ENTITY % common SYSTEM "common/common.ent">
+ %common;
+]>
+<!-- $Id: pazpar2_protocol.xml,v 1.1 2007-01-12 14:54:58 adam Exp $ -->
+<refentry id="pazpar2_protocol">
+ <refentryinfo>
+ <productname>Pazpar2</productname>
+ <productnumber>&version;</productnumber>
+ </refentryinfo>
+ <refmeta>
+ <refentrytitle>Pazpar2 protocol</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pazpar2_protocol</refname>
+ <refpurpose>The webservice protocol of Pazpar2</refpurpose>
+ </refnamediv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ Webservice requests are any that refer to filename "search.pz2". Arguments
+ are GET-style parameters. Argument 'command' is required and specifies
+ command. Any request not recognized as a webservice request as described,
+ are forwarded to the HTTP server specified in option -p.
+ </para>
+ <para>
+ Each command is described in sub sections to follow.
+ </para>
+ <refsect2 id="command-init"><title>init</title>
+ <para>
+ Initializes a session.
+ Returns session ID to be used in subsequent requests.
+ </para>
+ <para>
+ Example:
+ <screen>
+ search.pz2?command=init
+ </screen>
+ </para>
+ <para>
+ Response:
+ </para>
+ <screen><![CDATA[
+ <init>
+ <status>OK</status>
+ <session>2044502273</session>
+ </init>
+]]></screen>
+ </refsect2>
+
+ <refsect2 id="command-ping"><title>ping</title>
+ <para>
+ Keeps a session alive. An idle session will time out after one minute.
+ The ping command can be used to keep the session alive absent other
+ activity.
+ It is suggested that any browser client have a simple alarm handler which
+ sends a ping every 50 seconds or so once a session has been initialized.
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+ search.pz?command=ping&session=2044502273
+]]>
+ </screen>
+ Response:
+ <screen><![CDATA[
+<ping>
+ <status>OK</status>
+</ping>
+]]></screen>
+ </para>
+ </refsect2>
+ <refsect2 id="command-search"><title>search</title>
+ <para>
+ Launches a search, parameters:
+
+ <variablelist>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ Session ID
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>query</term>
+ <listitem>
+ <para>
+ CCL query
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+search.pz2?session=2044502273&command=search&query=computer
+]]>
+ </screen>
+ Response:
+ <screen><![CDATA[
+<search>
+ <status>OK</status>
+</search>
+ ]]></screen>
+ </para>
+ </refsect2>
+
+ <refsect2 id="command-stat">
+ <title>stat</title>
+ <para>
+ Provides status of ongoing search. Parameters:
+
+ <variablelist>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ Session ID
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+search.pz2?session=2044502273&command=stat
+ ]]></screen>
+ Output
+ <screen><![CDATA[
+<stat>
+ <activeclients>3</activeclients>
+ <hits>7</hits> -- Total hitcount
+ <records>7</records> -- Total number of records fetched
+ <clients>1</clients> -- Total number of associated clients
+ <unconnected>0</unconnected> -- Number of disconnected clients
+ <connecting>0</connecting> -- Number of clients in connecting state
+ <initializing>0</initializing> -- Number of clients initializing
+ <searching>0</searching> -- ... searching
+ <presenting>0</presenting> -- ... presenting
+ <idle>1</idle> -- ... idle (not doing anything)
+ <failed>0</failed> -- ... Connection failed
+ <error>0</error> -- ... Error was produced somewhere
+</stat>
+ ]]></screen>
+ </para>
+ </refsect2>
+
+ <refsect2 id="command-show">
+ <title>show</title>
+ <para>
+ Shows records retrieved. Parameters:
+ <variablelist>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ Session ID
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>start</term>
+ <listitem>
+ <para>First record to show - 0-indexed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>num</term>
+ <listitem>
+ <para>
+ Number of records to show If omitted, 20 is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>block</term>
+ <listitem>
+ <para>
+ If block is set, the command will hang until there are records ready
+ to display. Use this to show first records rapidly without
+ requiring rapid polling.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+search.pz2?session=2044502273&command=show&start=0&num=2
+]]></screen>
+ Output:
+ <screen><![CDATA[
+<show>
+ <status>OK</status>
+ <activeclients>3</activeclients>
+ <merged>6</merged>
+ <total>7</total>
+ <start>0</start>
+ <num>2</num>
+ <hit>
+ <md-title>How to program a computer, by Jack Collins</md-title>
+ <count>2</count> <!-- Number of merged records -->
+ <recid>6</recid>
+ </hit>
+ <hit>
+ <md-title>
+ Computer processing of dynamic images from an Anger scintillation camera :
+ the proceedings of a workshop /
+ </md-title>
+ <recid>2</recid>
+ </hit>
+</show>
+ ]]></screen>
+ </para>
+ </refsect2>
+
+ <refsect2 id="command-record">
+ <title>record</title>
+ <para>
+ Retrieves a detailed record. Parameters:
+
+ <variablelist>
+ <varlistentry>
+ <term>id</term>
+ <listitem>
+ <para>
+ record ID as provided by the
+ <link linkend="command-show">show</link> command.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+search.pz2?session=605047297&command=record&id=3
+]]></screen>
+
+ Example output:
+
+ <screen><![CDATA[
+<record>
+ <md-title>
+ The Puget Sound Region : a portfolio of thematic computer maps /
+ </md-title>
+ <md-date>1974</md-date>
+ <md-author>Mairs, John W.</md-author>
+ <md-subject>Cartography</md-subject>
+</record>
+ <screen><![CDATA[
+]]></screen>
+ </para>
+ </refsect2>
+
+ <refsect2 id="command-termlist">
+ <title>termlist</title>
+ <para>
+ Retrieves term list(s). Parameters:
+
+session
+name -- comma-separated list of termlist names (default "subject")
+
+ </para>
+ <para>
+ Example:
+ <screen><![CDATA[
+search.pz2?session=2044502273&command=termlist&name=author,subject
+]]></screen>
+Output:
+ <screen><![CDATA[
+<termlist>
+ <activeclients>3</activeclients>
+ <list name="author">
+ <term>
+ <name>Donald Knuth</name>
+ <frequency>10</frequency>
+ </term>
+ <term>
+ <name>Robert Pirsig</name>
+ <frequency>2</frequency>
+ </term>
+ </list>
+ <list name="subject">
+ <term>
+ <name>Computer programming</name>
+ <frequency>10</frequency>
+ </term>
+ </list>
+</termlist>
+]]></screen>
+ </para>
+
+ <para>
+ For the special termlist name "xtargets", results
+ are returned about the targets which have returned the most hits.
+ The 'term' subtree has additional elements,
+ specifically a state and diagnostic field (in the example below, a
+ target ID is returned in place of 'name'.
+ This may or may not change later.
+ </para>
+ <para>
+ Example
+ <screen><![CDATA[
+<term>
+ <name>library2.mcmaster.ca</name>
+ <frequency>11734</frequency>
+ <state>Client_Idle</state>
+ <diagnostic>0</diagnostic>
+</term>
+]]></screen>
+ </para>
+ </refsect2>
+
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t
+End:
+-->