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