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