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   <hits>7</hits>                   -- Total hitcount
  70   <records>7</records>             -- Total number of records fetched
  71   <clients>1</clients>             -- Total number of associated clients
  72   <unconnected>0</unconnected>     -- Number of disconnected clients
  73   <connecting>0</connecting>       -- Number of clients in connecting state
  74   <initializing>0</initializing>   -- Number of clients initializing
  75   <searching>0</searching>         -- ... searching
  76   <presenting>0</presenting>       -- ... presenting
  77   <idle>1</idle>                   -- ... idle (not doing anything)
  78   <failed>0</failed>               -- ... Connection failed
  79   <error>0</error>                 -- ... Error was produced somewhere
  80 </stat>
  81
  82 show
  83
  84 Shows records retrieved
  85
  86 parameters:
  87
  88 session
  89 start      -- 0-indexed!!
  90 num        -- default=20
  91 block      -- 0 or 1
  92
  93 If block is set, the command will hang until there are records ready
  94 to display. Use this to show first records rapidly without requiring rapid
  95 polling.
  96
  97 Example:
  98
  99 search.pz2?session=2044502273&command=show&start=0&num=2
 100
 101 Output:
 102
 103 <show>
 104   <status>OK</status>
 105   <activeclients>3</activeclients>
 106   <merged>6</merged>
 107   <total>7</total>
 108   <start>0</start>
 109   <num>2</num>
 110   <hit>
 111     <title>How to program a computer, by Jack Collins</title>
 112     <count>2</count> <!-- Number of merged records -->
 113   </hit>
 114   <hit>
 115     <title>
 116   Computer processing of dynamic images from an Anger scintillation camera :
 117   the proceedings of a workshop /
 118     </title>
 119   </hit>
 120 </show>
 121
 122 termlist
 123
 124 Retrieves term list(s)
 125
 126 parameters:
 127
 128 session
 129 name       -- comma-separated list of termlist names (default "subject")
 130
 131 Example:
 132
 133 search.pz2?session=2044502273&command=termlist&name=author,subject
 134
 135 Output:
 136
 137 <termlist>
 138   <activeclients>3</activeclients>
 139   <list name="author">
 140     <term>
 141       <name>Donald Knuth</name>
 142       <frequency>10</frequency>
 143     </term>
 144     <term>
 145       <name>Robert Pirsig</name>
 146       <frequency>2</frequency>
 147     </term>
 148   </list>
 149   <list name="subject">
 150     <term>
 151       <name>Computer programming</name>
 152       <frequency>10</frequency>
 153     </term>
 154   </list>
 155 </termlist>