doc/pazpar2_protocol.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY % entities SYSTEM "entities.ent">
   8      %entities;
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <refentry id="pazpar2_protocol">
  13  <refentryinfo>
  14   <productname>Pazpar2</productname>
  15   <productnumber>&version;</productnumber>
  16   <info><orgname>Index Data</orgname></info>
  17  </refentryinfo>
  18  <refmeta>
  19   <refentrytitle>Pazpar2 protocol</refentrytitle>
  20   <manvolnum>7</manvolnum>
  21   <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
  22  </refmeta>
  23
  24  <refnamediv>
  25   <refname>pazpar2_protocol</refname>
  26   <refpurpose>The webservice protocol of Pazpar2</refpurpose>
  27  </refnamediv>
  28
  29  <refsect1>
  30   <title>DESCRIPTION</title>
  31   <para>
  32    Webservice requests are any that refer to filename "search.pz2". Arguments
  33    are GET-style parameters. Argument 'command' is always required and specifies
  34    the operation to perform. Any request not recognized as a webservice
  35    request is forwarded to the HTTP server specified in the configuration
  36    using the proxy setting.
  37    This way, a regular webserver can host the user interface (itself dynamic
  38    or static HTML), and Ajax-style calls can be used from JS (or any other
  39    client-based scripting environment) to interact with the search logic
  40    in Pazpar2.
  41   </para>
  42   <para>
  43    Each command is described in sub sections to follow.
  44   </para>
  45   <refsect2 id="command-init">
  46    <title>init</title>
  47    <para>
  48     Initializes a session.
  49     Returns session ID to be used in subsequent requests. If
  50     a server ID is given in the Pazpar2 server section, then
  51     that is included in the session ID as suffix after a period (.).
  52    </para>
  53    <para>
  54     If the init command is performed as a HTTP GET request, service
  55     and settings from local files are used. The service parameter
  56     may chose a particular local service.
  57    </para>
  58    <para>
  59     If the init command is performed as a HTTP POST request and
  60     the content-type is text/xml, then the content is XML parsed
  61     and treated as service for the session. The root element should be
  62     service. Refer to descripton of the
  63     <link linkend="service_conf">service</link> format.
  64     The posting of a service appeared in Pazpar2 version 1.2.1.
  65    </para>
  66    <para>
  67     Example:
  68     <screen>
  69      search.pz2?command=init
  70     </screen>
  71    </para>
  72    <para>
  73     Response:
  74    </para>
  75    <screen><![CDATA[
  76     <init>
  77      <status>OK</status>
  78      <session>2044502273</session>
  79     </init>
  80 ]]></screen>
  81    <para>
  82     The init command may take a number of setting parameters, similar to
  83     the 'settings' command described below. These settings are immediately
  84     applied to the new session. Other parameters for init are:
  85     <variablelist>
  86      <varlistentry>
  87       <term>clear</term>
  88       <listitem>
  89        <para>
  90         If this is defined and the value is non-zero, the session will
  91         not use the predefined databases in the configuration; only those
  92         specified in the settings parameters (per session databases).
  93         </para>
  94       </listitem>
  95      </varlistentry>
  96
  97      <varlistentry>
  98       <term>service</term>
  99       <listitem>
 100        <para>
 101         If this is defined it specifies a service ID. Makes the session use
 102         the service with this ID. If this is setting is omitted, the
 103         session will use the unnamed service in the Pazpar2 configuration.
 104         </para>
 105       </listitem>
 106      </varlistentry>
 107     </variablelist>
 108    </para>
 109   </refsect2>
 110
 111   <refsect2 id="command-ping">
 112    <title>ping</title>
 113    <para>
 114     Keeps a session alive. An idle session will time out after one minute.
 115     The ping command can be used to keep the session alive absent other
 116     activity.
 117     It is suggested that any browser client have a simple alarm handler which
 118     sends a ping every 50 seconds or so once a session has been initialized.
 119    </para>
 120    <para>
 121     Example:
 122     <screen><![CDATA[
 123      search.pz?command=ping&session=2044502273
 124 ]]>
 125     </screen>
 126     Response:
 127    <screen><![CDATA[
 128 <ping>
 129   <status>OK</status>
 130 </ping>
 131 ]]></screen>
 132    </para>
 133   </refsect2>
 134   <refsect2 id="command-settings">
 135    <title>settings</title>
 136    <para>
 137     The settings command applies session-specific settings to one or more
 138     databases. A typical function of this is to enable access to
 139     restricted resources for registered users, or to set a user- or
 140     library-specific username/password to use against a target.
 141    </para>
 142    <para>
 143     Each setting parameter has the form name[target]=value, where name is the
 144     name of the setting (e.g. pz:authentication), target is a target ID,
 145     or possibly a wildcard, and value is the desired value for the
 146     setting.
 147    </para>
 148
 149    <para>
 150     Because the settings command manipulates potentially sensitive
 151     information, it is possible to configure Pazpar2 to only allow access
 152     to this command from a trusted site -- usually from server-side
 153     scripting, which in turn is responsible for authenticating the user,
 154     and possibly determining which resources he has access to, etc.
 155    </para>
 156
 157    <note>
 158     <para>
 159      As a shortcut, it is also possible to override settings directly in
 160      the init command.
 161     </para>
 162    </note>
 163
 164    <para>
 165     If the settings command is performed as HTTP POST and the content-type
 166     is text/xml, then the content is XML parsed and treated as settings -
 167     with a format identical to local
 168     <link linkend="target_settings">settings files</link>.
 169     The posting of settings appeared in Pazpar version 1.2.1.
 170    </para>
 171
 172    <para>
 173     Example:
 174     <screen><![CDATA[
 175 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
 176       ]]></screen>
 177     Response:
 178    <screen><![CDATA[
 179 <settings>
 180   <status>OK</status>
 181 </settings>
 182 ]]></screen>
 183    </para>
 184
 185   </refsect2>
 186   <refsect2 id="command-search">
 187    <title>search</title>
 188    <para>
 189     Launches a search, parameters:
 190
 191     <variablelist>
 192      <varlistentry>
 193       <term>session</term>
 194       <listitem>
 195        <para>
 196         Session ID
 197         </para>
 198       </listitem>
 199      </varlistentry>
 200      <varlistentry>
 201       <term>query</term>
 202       <listitem>
 203        <para>
 204         CCL query
 205         </para>
 206       </listitem>
 207      </varlistentry>
 208      <varlistentry>
 209       <term>filter</term>
 210       <listitem>
 211        <para>
 212         Limits the search to a given set of targets specified by the
 213         filter. The filter consists of a comma separated list of
 214         <emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
 215         pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
 216         (such as <literal>pz:id</literal>).
 217         The <emphasis>operator</emphasis> is either
 218         <literal>=</literal> (string match)
 219         or <literal>~</literal> (substring match).
 220         The <emphasis>args</emphasis> is a list of values separated
 221         by <literal>|</literal> (or , one of the values).
 222         The idea is that only targets with a setting matching one of
 223         the values given will be included in the search.
 224        </para>
 225       </listitem>
 226      </varlistentry>
 227      <varlistentry>
 228       <term>limit</term>
 229       <listitem>
 230        <para>
 231         Narrows the search by one or more fields (typically facets).
 232         The limit is sequence of one or more
 233         <emphasis>name</emphasis>=<emphasis>args</emphasis> pairs separated
 234         by comma. The <emphasis>args</emphasis> is a list of values
 235         separated by vertical bar (<literal>|</literal>).
 236         The meaning of <literal>|</literal> is alternative, ie OR .
 237         A value that contains a comma (<literal>,</literal>),
 238         a vertical bar (<literal>|</literal>) or
 239         backslash itself must be preceded by backslash (<literal>\</literal>).
 240         The <link linkend="limitmap">pz:limitmap</link> configuration
 241         item defines how the searches are mapped to a database.
 242        </para>
 243       </listitem>
 244      </varlistentry>
 245      <varlistentry>
 246       <term>startrecs</term>
 247       <listitem>
 248        <para>
 249         Specifies the first record to retrieve from each target.
 250         The first record in a result set for a target is numbered 0, next
 251         record is numbered 1. By default startrecs is 0.
 252         </para>
 253       </listitem>
 254      </varlistentry>
 255      <varlistentry>
 256       <term>maxrecs</term>
 257       <listitem>
 258        <para>
 259         Specifies the maximum number of records to retrieve from each
 260         target. The default value is 100. This setting has same meaning
 261         as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
 262         precedence over argument maxrecs.
 263         </para>
 264       </listitem>
 265      </varlistentry>
 266      <varlistentry>
 267       <term>sort</term>
 268       <listitem>
 269        <para>
 270         Specifies sort criteria. The argument is a comma-separated list
 271         (no whitespace allowed) of sort fields, with the highest-priority
 272         field first. A sort field may be followed by a colon followed by
 273         the number '0' (decreasing) or '1' (increasing).  Default
 274         sort order is decreasing.
 275         Sort field names can be any field name designated as a sort field
 276         in the pazpar2.cfg file, or the special names 'relevance',
 277         'retrieval' and 'position'.
 278        </para>
 279        <para>
 280         Sort type 'position' sorts by position/offset for each database.
 281         Sort type 'retrieval' sorts by position of retrieval (first record
 282         retrieved is 1, second record is 2, etc.).
 283        </para>
 284        <para>
 285         If not specified here or as
 286         <link linkend="sort-default">sort-default"</link>
 287         in pazpar2.cfg, Pazpar2 will default to the built-in
 288         'relevance' ranking.
 289        </para>
 290        <para>
 291         Having sort criteria at search is important for targets that
 292         supports native sorting in order to get best results. Pazpar2
 293         will trigger a new search if search criteria changes from Pazpar2
 294         to target-based sorting or visa-versa.
 295        </para>
 296       </listitem>
 297      </varlistentry>
 298
 299      <varlistentry>
 300       <term>mergekey</term>
 301       <listitem>
 302        <para>
 303         Sets mergekey for this search and rest of session, or until
 304         another mergekey is given for show/search. The mergekey value is a
 305         comma separated list with one or more names as they appear
 306         in the service description  equivalent to
 307         <literal>mergekey="optional"</literal> inside a metadata element.
 308         If the empty string is given for mergekey it is disabled
 309         and rest of session will use the default mergekey from service
 310         or stylesheet.
 311        </para>
 312        <para>
 313         This facility, "dynamic mergekey", appeared in Pazpar2 version
 314         1.6.31.
 315        </para>
 316       </listitem>
 317      </varlistentry>
 318
 319      <varlistentry>
 320       <term>rank</term>
 321       <listitem>
 322        <para>
 323         Sets rank method this search and rest of session, or until
 324         another rank is given for show/search. The rank value is a
 325         comma separated list of pairs field=value pairs. The
 326         format is the same as
 327         <xref linkend="metadata-rank">rank</xref> for a metadata element.
 328         If the empty string is given for rank it is disabled
 329         and rest of session will use the default rank from metadata or
 330         stylesheet.
 331        </para>
 332        <para>
 333         This facility, "dynamic ranking", appeared in Pazpar2 version
 334         1.6.31.
 335        </para>
 336       </listitem>
 337      </varlistentry>
 338
 339     </variablelist>
 340
 341    </para>
 342    <para>
 343     Example:
 344     <screen><![CDATA[
 345 search.pz2?session=2044502273&command=search&query=computer+science
 346 ]]>
 347      </screen>
 348     Response:
 349    <screen><![CDATA[
 350 <search>
 351   <status>OK</status>
 352 </search>
 353      ]]></screen>
 354    </para>
 355   </refsect2>
 356
 357   <refsect2 id="command-stat">
 358    <title>stat</title>
 359    <para>
 360     Provides status information about an ongoing search. Parameters:
 361
 362     <variablelist>
 363      <varlistentry>
 364       <term>session</term>
 365       <listitem>
 366        <para>
 367         Session ID
 368         </para>
 369       </listitem>
 370      </varlistentry>
 371     </variablelist>
 372
 373    </para>
 374    <para>
 375     Example:
 376    <screen><![CDATA[
 377 search.pz2?session=2044502273&command=stat
 378     ]]></screen>
 379     Output
 380     <screen><![CDATA[
 381 <stat>
 382   <activeclients>3</activeclients>
 383   <hits>7</hits>                   -- Total hitcount
 384   <records>7</records>             -- Total number of records fetched in last query
 385   <clients>1</clients>             -- Total number of associated clients
 386   <unconnected>0</unconnected>     -- Number of disconnected clients
 387   <connecting>0</connecting>       -- Number of clients in connecting state
 388   <initializing>0</initializing>   -- Number of clients initializing
 389   <searching>0</searching>         -- ... searching
 390   <presenting>0</presenting>       -- ... presenting
 391   <idle>1</idle>                   -- ... idle (not doing anything)
 392   <failed>0</failed>               -- ... Connection failed
 393   <error>0</error>                 -- ... Error was produced somewhere
 394 </stat>
 395      ]]></screen>
 396   </para>
 397   </refsect2>
 398
 399   <refsect2 id="command-show">
 400    <title>show</title>
 401    <para>
 402     Shows records retrieved. Parameters:
 403     <variablelist>
 404      <varlistentry>
 405       <term>session</term>
 406       <listitem>
 407        <para>
 408         Session ID
 409        </para>
 410       </listitem>
 411      </varlistentry>
 412
 413      <varlistentry>
 414       <term>start</term>
 415       <listitem>
 416        <para>First record to show - 0-indexed.</para>
 417       </listitem>
 418      </varlistentry>
 419
 420      <varlistentry>
 421       <term>num</term>
 422       <listitem>
 423        <para>
 424         Number of records to show If omitted, 20 is used.
 425        </para>
 426       </listitem>
 427      </varlistentry>
 428
 429      <varlistentry>
 430       <term>block</term>
 431       <listitem>
 432        <para>
 433         If block is set to 1, the command will hang until there are records
 434         ready to display. Use this to show first records rapidly without
 435         requiring rapid polling.
 436        </para>
 437        <para>
 438         If block is set to <literal>preferred</literal>, the command will
 439         wait until records have been received from all databases with preferred
 440         setting
 441        </para>
 442       </listitem>
 443      </varlistentry>
 444
 445      <varlistentry>
 446       <term>sort</term>
 447       <listitem>
 448        <para>
 449         Specifies sort criteria. The argument is a comma-separated list
 450         (no whitespace allowed) of sort fields, with the highest-priority
 451         field first. A sort field may be followed by a colon followed by
 452         the number '0' (decreasing) or '1' (increasing).  Default
 453         sort order is decreasing.
 454         Sort field names can be any field name designated as a sort field
 455         in the pazpar2.cfg file, or the special names 'relevance',
 456         'retrieval' and 'position'.
 457        </para>
 458        <para>
 459         Sort type 'position' sorts by position/offset for each database.
 460         Sort type 'retrieval' sorts by position of retrieval (first record
 461         retrieved is 1, second record is 2, etc.).
 462        </para>
 463        <para>
 464         If not specified here or as
 465         <link linkend="sort-default">sort-default"</link>
 466         in pazpar2.cfg, pazpar2 will default to the built-in
 467         'relevance' ranking.
 468        </para>
 469        <para>
 470         Having sort criteria at search is important for targets that
 471         supports native sorting in order to get best results. pazpar2
 472         will trigger a new search if search criteria changes from pazpar2
 473         to target-based sorting.
 474        </para>
 475        <para>
 476         For targets where If <link linkend="pzsortmap">pz:sortmap</link>
 477         is defined, a sort operation will be executed (possibly including
 478         extending the search).
 479        </para>
 480       </listitem>
 481      </varlistentry>
 482
 483      <varlistentry>
 484       <term>mergekey</term>
 485       <listitem>
 486        <para>
 487         Sets mergekey for this show and rest of session, or until
 488         another mergekey is given for show/search. The mergekey value is a
 489         comma separated list with one or more names as they appear
 490         in the service description  equivalent to
 491         <literal>mergekey="optional"</literal> inside a metadata element.
 492         If the empty string is given for mergekey it is disabled
 493         and rest of session will use the default mergekey from service
 494         or stylesheet.
 495        </para>
 496        <para>
 497         This facility, "dynamic mergekey", appeared in Pazpar2 version
 498         1.6.31.
 499        </para>
 500       </listitem>
 501      </varlistentry>
 502
 503      <varlistentry>
 504       <term>rank</term>
 505       <listitem>
 506        <para>
 507         Sets rank method this show and rest of session, or until
 508         another rank is given for show/search. The rank value is a
 509         comma separated list of pairs field=value pairs. The
 510         format is the same as
 511         <xref linkend="metadata-rank">rank</xref> for a metadata element.
 512         If the empty string is given for rank it is disabled
 513         and rest of session will use the default rank from metadata or
 514         stylesheet.
 515        </para>
 516        <para>
 517         This facility, "dynamic ranking", appeared in Pazpar2 version
 518         1.6.31.
 519        </para>
 520       </listitem>
 521      </varlistentry>
 522
 523      <varlistentry>
 524       <term>snippets</term>
 525       <listitem>
 526        <para>
 527         If specified and set to 1 data will include snippets marked
 528         with &lt;match&gt; tags. Otherwise snippets will not be included.
 529        </para>
 530        <para>
 531         This facility, "snippets", appeared in Pazpar2 version
 532         1.6.32.
 533        </para>
 534       </listitem>
 535      </varlistentry>
 536
 537     </variablelist>
 538    </para>
 539    <para>
 540     Example:
 541     <screen><![CDATA[
 542 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 543 ]]></screen>
 544     Output:
 545     <screen><![CDATA[
 546 <show>
 547   <status>OK</status>
 548   <activeclients>3</activeclients>     -- How many clients are still working
 549   <merged>6</merged>                   -- Number of merged records
 550   <total>7</total>                     -- Total of all hitcounts
 551   <start>0</start>                     -- The start number you requested
 552   <num>2</num>                         -- Number of records retrieved
 553   <hit>
 554     <md-title>How to program a computer, by Jack Collins</md-title>
 555     <count>2</count>                   -- Number of merged records
 556     <recid>6</recid>                   -- Record ID for this record
 557   </hit>
 558   <hit>
 559     <md-title>
 560   Computer processing of dynamic images from an Anger scintillation camera :
 561   the proceedings of a workshop /
 562     </md-title>
 563     <recid>2</recid>
 564   </hit>
 565 </show>
 566      ]]></screen>
 567    </para>
 568   </refsect2>
 569
 570   <refsect2 id="command-record">
 571    <title>record</title>
 572    <para>
 573     Retrieves a detailed record. Unlike the
 574     <link linkend="command-show">show</link> command, this command
 575     returns metadata records before merging takes place. Parameters:
 576
 577     <variablelist>
 578      <varlistentry>
 579       <term>session</term>
 580       <listitem>
 581        <para>
 582         Session ID
 583        </para>
 584       </listitem>
 585      </varlistentry>
 586
 587      <varlistentry>
 588       <term>id</term>
 589       <listitem>
 590        <para>
 591         record ID as provided by the
 592         <link linkend="command-show">show</link> command.
 593         </para>
 594       </listitem>
 595      </varlistentry>
 596
 597      <varlistentry>
 598       <term>offset</term>
 599       <listitem>
 600        <para>
 601         This optional parameter is an integer which, when given, makes
 602         Pazpar2 return the original record for a specific target.
 603         The record set from first target is numbered 0,
 604         second record set is numbered 1, etc.
 605         The nativesyntax setting, as usual, is used to determine how to
 606         create XML from the original record - unless parameter
 607         <literal>binary</literal> is given in which the record is
 608         fetched as "raw" from ZOOM C (raw, original record).
 609        </para>
 610        <para>
 611         When offset/checksum is not given, the Pazpar2 metadata for the record
 612         is returned and with metadata for each targets' data specified
 613         in a 'location' list.
 614        </para>
 615       </listitem>
 616      </varlistentry>
 617
 618      <varlistentry>
 619       <term>checksum</term>
 620       <listitem>
 621        <para>
 622         This optional parameter is a string which, when given, makes
 623         Pazpar2 return the original record for a specific target. The
 624         checksum is returned as attribtue 'checksum' in element
 625         'location' for show command and record command (when checksum
 626         and offset is NOT given).
 627         The nativesyntax setting, as usual, is used to determine how to
 628         create XML from the original record - unless parameter
 629         <literal>binary</literal> is given in which the record is
 630         fetched as "raw" from ZOOM C (raw, original record).
 631        </para>
 632        <para>
 633         When offset/checksum is not given, the Pazpar2 metadata for the record
 634         is returned and with metadata for each targets' data specified
 635         in a 'location' list.
 636        </para>
 637       </listitem>
 638      </varlistentry>
 639
 640
 641      <varlistentry>
 642       <term>nativesyntax</term>
 643       <listitem>
 644        <para>
 645         This optional parameter can be used to override pz:nativesyntax
 646         as given for the target. This allow an alternative nativesyntax
 647         to be used for original records (see parameteroffset above).
 648        </para>
 649       </listitem>
 650      </varlistentry>
 651
 652      <varlistentry>
 653       <term>syntax</term>
 654       <listitem>
 655        <para>
 656         This optional parameter is the record syntax used for raw
 657         transfer (i.e. when offset is specified). If syntax is not given,
 658         but offset is used, the value of pz:requestsyntax is used.
 659        </para>
 660       </listitem>
 661      </varlistentry>
 662
 663      <varlistentry>
 664       <term>esn</term>
 665       <listitem>
 666        <para>
 667         This optional parameter is the element set name used to retrieval
 668         of a raw record (i.e. when offset is specified).
 669         If esn is not given, but offset is used, the value of pz:elements
 670         is used.
 671        </para>
 672       </listitem>
 673      </varlistentry>
 674
 675      <varlistentry>
 676       <term>binary</term>
 677       <listitem>
 678        <para>
 679         This optional parameter enables "binary" response for retrieval
 680         of a original record (i.e. when offset is specified). For binary
 681         response the record by default is fetched from ZOOM C using
 682         the "raw" option or by parameter nativesyntax if given.
 683        </para>
 684       </listitem>
 685      </varlistentry>
 686
 687      <varlistentry>
 688       <term>snippets</term>
 689       <listitem>
 690        <para>
 691         If specified and set to 1 data will include snippets marked
 692         with &lt;match&gt; tags. Otherwise snippets will not be included.
 693        </para>
 694        <para>
 695         This facility, "snippets", appeared in Pazpar2 version
 696         1.6.32.
 697        </para>
 698       </listitem>
 699      </varlistentry>
 700
 701     </variablelist>
 702    </para>
 703    <para>
 704     Example:
 705     <screen><![CDATA[
 706 search.pz2?session=605047297&command=record&id=3
 707 ]]></screen>
 708
 709     Example output:
 710
 711     <screen><![CDATA[
 712 <record>
 713   <md-title>
 714         The Puget Sound Region : a portfolio of thematic computer maps /
 715   </md-title>
 716   <md-date>1974</md-date>
 717   <md-author>Mairs, John W.</md-author>
 718   <md-subject>Cartography</md-subject>
 719 </record>
 720 ]]></screen>
 721    </para>
 722   </refsect2>
 723
 724   <refsect2 id="command-stop">
 725    <title>stop</title>
 726    <para>
 727     Makes Pazpar2 stop further search &amp; retrieval for busy databases.
 728    </para>
 729   </refsect2>
 730
 731   <refsect2 id="command-termlist">
 732    <title>termlist</title>
 733    <para>
 734     Retrieves term list(s). Parameters:
 735
 736     <variablelist>
 737      <varlistentry>
 738       <term>session</term>
 739       <listitem>
 740        <para>
 741         Session Id.
 742        </para>
 743       </listitem>
 744      </varlistentry>
 745      <varlistentry>
 746       <term>name</term>
 747       <listitem>
 748        <para>
 749         comma-separated list of termlist names. If omitted,
 750         all termlists are returned.
 751        </para>
 752       </listitem>
 753      </varlistentry>
 754      <varlistentry>
 755       <term>num</term>
 756       <listitem>
 757        <para>
 758         maximum number of entries to return - default is 15.
 759        </para>
 760       </listitem>
 761      </varlistentry>
 762     </variablelist>
 763    </para>
 764    <para>
 765     Example:
 766     <screen><![CDATA[
 767 search.pz2?session=2044502273&command=termlist&name=author,subject
 768 ]]></screen>
 769     Output:
 770     <screen><![CDATA[
 771 <termlist>
 772   <activeclients>3</activeclients>
 773   <list name="author">
 774     <term>
 775       <name>Donald Knuth</name>
 776       <frequency>10</frequency>
 777     </term>
 778       <term>
 779       <name>Robert Pirsig</name>
 780       <frequency>2</frequency>
 781     </term>
 782   </list>
 783   <list name="subject">
 784     <term>
 785       <name>Computer programming</name>
 786       <frequency>10</frequency>
 787     </term>
 788   </list>
 789 </termlist>
 790 ]]></screen>
 791    </para>
 792
 793    <para>
 794     For the special termlist name "xtargets", results
 795     are returned about the targets which have returned the most hits.
 796     The 'term' subtree has additional elements,
 797     specifically a state and diagnostic field (in the example below, a
 798     target ID is returned in place of 'name'.
 799     This may or may not change later.
 800    </para>
 801    <para>
 802     Example
 803     <screen><![CDATA[
 804 <term>
 805   <name>library2.mcmaster.ca</name>
 806   <frequency>11734</frequency>         -- Number of hits
 807   <state>Client_Idle</state>           -- See the description of 'bytarget' below
 808   <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
 809 </term>
 810 ]]></screen>
 811    </para>
 812   </refsect2>
 813
 814
 815   <refsect2 id="command-bytarget">
 816    <title>bytarget</title>
 817    <para>
 818     Returns information about the status of each active client. Parameters:
 819
 820     <variablelist>
 821      <varlistentry>
 822       <term>session</term>
 823       <listitem>
 824        <para>
 825         Session Id.
 826         </para>
 827       </listitem>
 828      </varlistentry>
 829     </variablelist>
 830    </para>
 831    <para>
 832     Example:
 833     <screen><![CDATA[
 834 search.pz2?session=605047297&command=bytarget&id=3
 835 ]]></screen>
 836
 837     Example output:
 838
 839     <screen><![CDATA[
 840 <bytarget>
 841   <status>OK</status>
 842   <target>
 843     <id>z3950.loc.gov/voyager/</id>
 844     <hits>10000</hits>
 845     <diagnostic>0</diagnostic>
 846     <records>65</records>
 847     <state>Client_Presenting</state>
 848   </target>
 849   <!-- ... more target nodes below as necessary -->
 850 </bytarget>
 851 ]]></screen>
 852
 853     The following client states are defined: Client_Connecting,
 854     Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
 855     Client_Searching, Client_Presenting, Client_Error, Client_Failed,
 856     Client_Disconnected, Client_Stopped, Client_Continue.
 857    </para>
 858   </refsect2>
 859
 860   <refsect2 id="command-service">
 861    <title>service</title>
 862    <para>
 863     Returns service definition (XML). Parameters:
 864     <variablelist>
 865      <varlistentry>
 866       <term>session</term>
 867       <listitem>
 868        <para>
 869         Session ID
 870         </para>
 871       </listitem>
 872      </varlistentry>
 873     </variablelist>
 874    </para>
 875    <para>
 876     The service command appeared in Pazpar2 version 1.6.32
 877    </para>
 878   </refsect2>
 879  </refsect1>
 880  <refsect1>
 881   <title>SEE ALSO</title>
 882   <para>
 883    Pazpar2:
 884    <citerefentry>
 885     <refentrytitle>pazpar2</refentrytitle>
 886     <manvolnum>8</manvolnum>
 887    </citerefentry>
 888   </para>
 889   <para>
 890    Pazpar2 Configuration:
 891    <citerefentry>
 892     <refentrytitle>pazpar2_conf</refentrytitle>
 893     <manvolnum>5</manvolnum>
 894    </citerefentry>
 895   </para>
 896  </refsect1>
 897 </refentry>
 898
 899 <!-- Keep this comment at the end of the file
 900 Local variables:
 901 mode: nxml
 902 nxml-child-indent: 1
 903 End:
 904 -->