PROTOCOL

   1
   2 Webservice requests are any that refer to filename "search.pz2". Arguments
   3 are GET-style parameters. Argument 'command' is required and specifies
   4 command. Any request not recognized as a webservice request as described,
   5 are forwarded to the HTTP server specified in option -p.
   6
   7 Commands:
   8
   9 init
  10
  11 Initializes a session. Returns session ID to be used in subsequent requests. Example:
  12
  13 search.pz2?command=init
  14
  15 Response example:
  16
  17 <init>
  18   <status>OK</status>
  19   <session>2044502273</session>
  20 </init>
  21
  22 ping
  23
  24 Keeps a session alive. An idle session will time out after one minute. The
  25 ping command can be used to keep the session alive absent other activity. It
  26 is suggested that any browser client have a simple alarm handler which
  27 sends a ping every 50 seconds or so once a session has been initialized.
  28
  29 Example:
  30
  31 search.pz?command=ping&session=2044502273
  32
  33 Response example:
  34
  35 <ping>
  36   <status>OK</status>
  37 </ping>
  38
  39 search
  40
  41 Launches a search, parameters:
  42
  43 session
  44 query
  45
  46 Example:
  47
  48 search.pz2?session=2044502273&command=search&query=computer
  49
  50 Response example:
  51
  52 <search>
  53   <status>OK</status>
  54 </search>
  55
  56 stat
  57
  58 Provides status of ongoing search. Parameters:
  59
  60 session
  61
  62 Example:
  63
  64 search.pz2?session=2044502273&command=stat
  65
  66 Output:
  67
  68 <stat>
  69   <activeclients>3</activeclients>
  70   <hits>7</hits>                   -- Total hitcount
  71   <records>7</records>             -- Total number of records fetched
  72   <clients>1</clients>             -- Total number of associated clients
  73   <unconnected>0</unconnected>     -- Number of disconnected clients
  74   <connecting>0</connecting>       -- Number of clients in connecting state
  75   <initializing>0</initializing>   -- Number of clients initializing
  76   <searching>0</searching>         -- ... searching
  77   <presenting>0</presenting>       -- ... presenting
  78   <idle>1</idle>                   -- ... idle (not doing anything)
  79   <failed>0</failed>               -- ... Connection failed
  80   <error>0</error>                 -- ... Error was produced somewhere
  81 </stat>
  82
  83 show
  84
  85 Shows records retrieved
  86
  87 parameters:
  88
  89 session
  90 start      -- 0-indexed!!
  91 num        -- default=20
  92 block      -- 0 or 1
  93
  94 If block is set, the command will hang until there are records ready
  95 to display. Use this to show first records rapidly without requiring rapid
  96 polling.
  97
  98 Example:
  99
 100 search.pz2?session=2044502273&command=show&start=0&num=2
 101
 102 Output:
 103
 104 <show>
 105   <status>OK</status>
 106   <activeclients>3</activeclients>
 107   <merged>6</merged>
 108   <total>7</total>
 109   <start>0</start>
 110   <num>2</num>
 111   <hit>
 112     <title>How to program a computer, by Jack Collins</title>
 113     <count>2</count> <!-- Number of merged records -->
 114   </hit>
 115   <hit>
 116     <title>
 117   Computer processing of dynamic images from an Anger scintillation camera :
 118   the proceedings of a workshop /
 119     </title>
 120   </hit>
 121 </show>
 122
 123 termlist
 124
 125 Retrieves term list(s)
 126
 127 parameters:
 128
 129 session
 130 name       -- comma-separated list of termlist names (default "subject")
 131
 132 Example:
 133
 134 search.pz2?session=2044502273&command=termlist&name=author,subject
 135
 136 Output:
 137
 138 <termlist>
 139   <activeclients>3</activeclients>
 140   <list name="author">
 141     <term>
 142       <name>Donald Knuth</name>
 143       <frequency>10</frequency>
 144     </term>
 145       <term>
 146       <name>Robert Pirsig</name>
 147       <frequency>2</frequency>
 148     </term>
 149   </list>
 150   <list name="subject">
 151     <term>
 152       <name>Computer programming</name>
 153       <frequency>10</frequency>
 154     </term>
 155   </list>
 156 </termlist>
 157
 158 For the special termlist name "xtargets", results are returned about the targets
 159 which have returned the most hits. The 'term' subtree has additional elements,
 160 specifically a state and diagnostic field (in the example below, a target ID is
 161 returned in place of 'name'. This may or may not change later.
 162
 163 <term>
 164   <name>library2.mcmaster.ca</name>
 165   <frequency>11734</frequency>
 166   <state>Client_Idle</state>
 167   <diagnostic>0</diagnostic>
 168 </term>