X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=PROTOCOL;h=2608c380d98293c87e7d36697821479b1a23264e;hb=9794003e5c6399a34585d3765ff1defe29d8ffb0;hp=2f9c22f9558d2c66fb91d4b88640ff7d9a691311;hpb=5ca759f28d681f9c8cf954655571cc9963c27b04;p=pazpar2-moved-to-github.git

diff --git a/PROTOCOL b/PROTOCOL
index 2f9c22f..2608c38 100644
--- a/PROTOCOL
+++ b/PROTOCOL
@@ -1,7 +1,8 @@
 
 Webservice requests are any that refer to filename "search.pz2". Arguments
 are GET-style parameters. Argument 'command' is required and specifies
-command.
+command. Any request not recognized as a webservice request as described,
+are forwarded to the HTTP server specified in option -p.
 
 Commands:
 
@@ -18,6 +19,23 @@ Response example:
   <session>2044502273</session>
 </init>
 
+ping
+
+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.
+
+Example:
+
+search.pz?command=ping&session=2044502273
+
+Response example:
+
+<ping>
+  <status>OK</status>
+</ping>
+
 search
 
 Launches a search, parameters:
@@ -48,6 +66,7 @@ search.pz2?session=2044502273&command=stat
 Output:
 
 <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
@@ -70,6 +89,11 @@ parameters:
 session
 start      -- 0-indexed!!
 num        -- default=20
+block      -- 0 or 1
+
+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.
 
 Example:
 
@@ -79,18 +103,90 @@ Output:
 
 <show>
   <status>OK</status>
+  <activeclients>3</activeclients>
   <merged>6</merged>
   <total>7</total>
   <start>0</start>
   <num>2</num>
   <hit>
-    <title>How to program a computer, by Jack Collins</title>
+    <md-title>How to program a computer, by Jack Collins</md-title>
     <count>2</count> <!-- Number of merged records -->
+    <recid>6</recid>
   </hit>
   <hit>
-    <title>
+    <md-title>
   Computer processing of dynamic images from an Anger scintillation camera :
   the proceedings of a workshop /
-    </title>
+    </md-title>
+    <recid>2</recid>
   </hit>
 </show>
+
+record
+
+Retrieves a detailed record.
+
+Parameters: id -- record ID as provided by the show command
+
+Example:
+
+search.pz2?session=605047297&command=record&id=3
+
+Example output:
+
+<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>
+
+termlist
+
+Retrieves term list(s)
+
+parameters:
+
+session
+name       -- comma-separated list of termlist names (default "subject")
+
+Example:
+
+search.pz2?session=2044502273&command=termlist&name=author,subject
+
+Output:
+
+<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>
+
+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.
+
+<term>
+  <name>library2.mcmaster.ca</name>
+  <frequency>11734</frequency>
+  <state>Client_Idle</state>
+  <diagnostic>0</diagnostic>
+</term>
+