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     <md-title>How to program a computer, by Jack Collins</md-title>
 113     <count>2</count> <!-- Number of merged records -->
 114     <recid>6</recid>
 115   </hit>
 116   <hit>
 117     <md-title>
 118   Computer processing of dynamic images from an Anger scintillation camera :
 119   the proceedings of a workshop /
 120     </md-title>
 121     <recid>2</recid>
 122   </hit>
 123 </show>
 124
 125 record
 126
 127 Retrieves a detailed record.
 128
 129 Parameters: id -- record ID as provided by the show command
 130
 131 Example:
 132
 133 search.pz2?session=605047297&command=record&id=3
 134
 135 Example output:
 136
 137 <record>
 138   <md-title>
 139         The Puget Sound Region : a portfolio of thematic computer maps /
 140   </md-title>
 141   <md-date>1974</md-date>
 142   <md-author>Mairs, John W.</md-author>
 143   <md-subject>Cartography</md-subject>
 144 </record>
 145
 146 termlist
 147
 148 Retrieves term list(s)
 149
 150 parameters:
 151
 152 session
 153 name       -- comma-separated list of termlist names (default "subject")
 154
 155 Example:
 156
 157 search.pz2?session=2044502273&command=termlist&name=author,subject
 158
 159 Output:
 160
 161 <termlist>
 162   <activeclients>3</activeclients>
 163   <list name="author">
 164     <term>
 165       <name>Donald Knuth</name>
 166       <frequency>10</frequency>
 167     </term>
 168       <term>
 169       <name>Robert Pirsig</name>
 170       <frequency>2</frequency>
 171     </term>
 172   </list>
 173   <list name="subject">
 174     <term>
 175       <name>Computer programming</name>
 176       <frequency>10</frequency>
 177     </term>
 178   </list>
 179 </termlist>
 180
 181 For the special termlist name "xtargets", results are returned about the targets
 182 which have returned the most hits. The 'term' subtree has additional elements,
 183 specifically a state and diagnostic field (in the example below, a target ID is
 184 returned in place of 'name'. This may or may not change later.
 185
 186 <term>
 187   <name>library2.mcmaster.ca</name>
 188   <frequency>11734</frequency>
 189   <state>Client_Idle</state>
 190   <diagnostic>0</diagnostic>
 191 </term>
 192