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' and
 277         'position'.
 278        </para>
 279        <para>
 280         If not specified here or as
 281         <link linkend="sort-default">sort-default"</link>
 282         in pazpar2.cfg, Pazpar2 will default to the built-in
 283         'relevance' ranking.
 284        </para>
 285        <para>
 286         Having sort criteria at search is important for targets that
 287         supports native sorting in order to get best results. Pazpar2
 288         will trigger a new search if search criteria changes from Pazpar2
 289         to target-based sorting or visa-versa.
 290         </para>
 291       </listitem>
 292      </varlistentry>
 293
 294      <varlistentry>
 295       <term>mergekey</term>
 296       <listitem>
 297        <para>
 298         Sets mergekey for this search and rest of session, or until
 299         another mergekey is given for show/search. The mergekey value is a
 300         comma separated list with one or more names as they appear
 301         in the service description  equivalent to
 302         <literal>mergekey="optional"</literal> inside a metadata element.
 303         If the empty string is given for mergekey it is disabled
 304         and rest of session will use the default mergekey from service
 305         or stylesheet.
 306        </para>
 307        <para>
 308         This facility, "dynamic mergekey", appeared in Pazpar2 version
 309         1.6.31.
 310        </para>
 311       </listitem>
 312      </varlistentry>
 313
 314      <varlistentry>
 315       <term>rank</term>
 316       <listitem>
 317        <para>
 318         Sets rank method this search and rest of session, or until
 319         another rank is given for show/search. The rank value is a
 320         comma separated list of pairs field=value pairs. The
 321         format is the same as
 322         <xref linkend="metadata-rank">rank</xref> for a metadata element.
 323         If the empty string is given for rank it is disabled
 324         and rest of session will use the default rank from metadata or
 325         stylesheet.
 326        </para>
 327        <para>
 328         This facility, "dynamic ranking", appeared in Pazpar2 version
 329         1.6.31.
 330        </para>
 331       </listitem>
 332      </varlistentry>
 333
 334     </variablelist>
 335
 336    </para>
 337    <para>
 338     Example:
 339     <screen><![CDATA[
 340 search.pz2?session=2044502273&command=search&query=computer+science
 341 ]]>
 342      </screen>
 343     Response:
 344    <screen><![CDATA[
 345 <search>
 346   <status>OK</status>
 347 </search>
 348      ]]></screen>
 349    </para>
 350   </refsect2>
 351
 352   <refsect2 id="command-stat">
 353    <title>stat</title>
 354    <para>
 355     Provides status information about an ongoing search. Parameters:
 356
 357     <variablelist>
 358      <varlistentry>
 359       <term>session</term>
 360       <listitem>
 361        <para>
 362         Session ID
 363         </para>
 364       </listitem>
 365      </varlistentry>
 366     </variablelist>
 367
 368    </para>
 369    <para>
 370     Example:
 371    <screen><![CDATA[
 372 search.pz2?session=2044502273&command=stat
 373     ]]></screen>
 374     Output
 375     <screen><![CDATA[
 376 <stat>
 377   <activeclients>3</activeclients>
 378   <hits>7</hits>                   -- Total hitcount
 379   <records>7</records>             -- Total number of records fetched in last query
 380   <clients>1</clients>             -- Total number of associated clients
 381   <unconnected>0</unconnected>     -- Number of disconnected clients
 382   <connecting>0</connecting>       -- Number of clients in connecting state
 383   <initializing>0</initializing>   -- Number of clients initializing
 384   <searching>0</searching>         -- ... searching
 385   <presenting>0</presenting>       -- ... presenting
 386   <idle>1</idle>                   -- ... idle (not doing anything)
 387   <failed>0</failed>               -- ... Connection failed
 388   <error>0</error>                 -- ... Error was produced somewhere
 389 </stat>
 390      ]]></screen>
 391   </para>
 392   </refsect2>
 393
 394   <refsect2 id="command-show">
 395    <title>show</title>
 396    <para>
 397     Shows records retrieved. Parameters:
 398     <variablelist>
 399      <varlistentry>
 400       <term>session</term>
 401       <listitem>
 402        <para>
 403         Session ID
 404        </para>
 405       </listitem>
 406      </varlistentry>
 407
 408      <varlistentry>
 409       <term>start</term>
 410       <listitem>
 411        <para>First record to show - 0-indexed.</para>
 412       </listitem>
 413      </varlistentry>
 414
 415      <varlistentry>
 416       <term>num</term>
 417       <listitem>
 418        <para>
 419         Number of records to show If omitted, 20 is used.
 420        </para>
 421       </listitem>
 422      </varlistentry>
 423
 424      <varlistentry>
 425       <term>block</term>
 426       <listitem>
 427        <para>
 428         If block is set to 1, the command will hang until there are records
 429         ready to display. Use this to show first records rapidly without
 430         requiring rapid polling.
 431        </para>
 432        <para>
 433         If block is set to <literal>preferred</literal>, the command will
 434         wait until records have been received from all databases with preferred
 435         setting
 436        </para>
 437       </listitem>
 438      </varlistentry>
 439
 440      <varlistentry>
 441       <term>sort</term>
 442       <listitem>
 443        <para>
 444         Specifies sort criteria. The argument is a comma-separated list
 445         (no whitespace allowed) of sort fields, with the highest-priority
 446         field first. A sort field may be followed by a colon followed by
 447         the number '0' (decreasing) or '1' (increasing).  Default
 448         sort order is decreasing.
 449         Sort field names can be any field name designated as a sort field
 450         in the pazpar2.cfg file, or the special names 'relevance' and
 451         'position'.
 452        </para>
 453        <para>
 454         If not specified here or as
 455         <link linkend="sort-default">sort-default"</link>
 456         in pazpar2.cfg, pazpar2 will default to the built-in
 457         'relevance' ranking.
 458        </para>
 459        <para>
 460         Having sort criteria at search is important for targets that
 461         supports native sorting in order to get best results. pazpar2
 462         will trigger a new search if search criteria changes from pazpar2
 463         to target-based sorting.
 464        </para>
 465        <para>
 466         For targets where If <link linkend="pzsortmap">pz:sortmap</link>
 467         is defined, a sort operation will be executed (possibly including
 468         extending the search).
 469        </para>
 470       </listitem>
 471      </varlistentry>
 472
 473      <varlistentry>
 474       <term>mergekey</term>
 475       <listitem>
 476        <para>
 477         Sets mergekey for this show and rest of session, or until
 478         another mergekey is given for show/search. The mergekey value is a
 479         comma separated list with one or more names as they appear
 480         in the service description  equivalent to
 481         <literal>mergekey="optional"</literal> inside a metadata element.
 482         If the empty string is given for mergekey it is disabled
 483         and rest of session will use the default mergekey from service
 484         or stylesheet.
 485        </para>
 486        <para>
 487         This facility, "dynamic mergekey", appeared in Pazpar2 version
 488         1.6.31.
 489        </para>
 490       </listitem>
 491      </varlistentry>
 492
 493      <varlistentry>
 494       <term>rank</term>
 495       <listitem>
 496        <para>
 497         Sets rank method this show and rest of session, or until
 498         another rank is given for show/search. The rank value is a
 499         comma separated list of pairs field=value pairs. The
 500         format is the same as
 501         <xref linkend="metadata-rank">rank</xref> for a metadata element.
 502         If the empty string is given for rank it is disabled
 503         and rest of session will use the default rank from metadata or
 504         stylesheet.
 505        </para>
 506        <para>
 507         This facility, "dynamic ranking", appeared in Pazpar2 version
 508         1.6.31.
 509        </para>
 510       </listitem>
 511      </varlistentry>
 512
 513      <varlistentry>
 514       <term>snippets</term>
 515       <listitem>
 516        <para>
 517         If specified and set to 1 data will include snippets marked
 518         with &lt;match&gt; tags. Otherwise snippets will not be included.
 519        </para>
 520        <para>
 521         This facility, "snippets", appeared in Pazpar2 version
 522         1.6.32.
 523        </para>
 524       </listitem>
 525      </varlistentry>
 526
 527     </variablelist>
 528    </para>
 529    <para>
 530     Example:
 531     <screen><![CDATA[
 532 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 533 ]]></screen>
 534     Output:
 535     <screen><![CDATA[
 536 <show>
 537   <status>OK</status>
 538   <activeclients>3</activeclients>     -- How many clients are still working
 539   <merged>6</merged>                   -- Number of merged records
 540   <total>7</total>                     -- Total of all hitcounts
 541   <start>0</start>                     -- The start number you requested
 542   <num>2</num>                         -- Number of records retrieved
 543   <hit>
 544     <md-title>How to program a computer, by Jack Collins</md-title>
 545     <count>2</count>                   -- Number of merged records
 546     <recid>6</recid>                   -- Record ID for this record
 547   </hit>
 548   <hit>
 549     <md-title>
 550   Computer processing of dynamic images from an Anger scintillation camera :
 551   the proceedings of a workshop /
 552     </md-title>
 553     <recid>2</recid>
 554   </hit>
 555 </show>
 556      ]]></screen>
 557    </para>
 558   </refsect2>
 559
 560   <refsect2 id="command-record">
 561    <title>record</title>
 562    <para>
 563     Retrieves a detailed record. Unlike the
 564     <link linkend="command-show">show</link> command, this command
 565     returns metadata records before merging takes place. Parameters:
 566
 567     <variablelist>
 568      <varlistentry>
 569       <term>session</term>
 570       <listitem>
 571        <para>
 572         Session ID
 573        </para>
 574       </listitem>
 575      </varlistentry>
 576
 577      <varlistentry>
 578       <term>id</term>
 579       <listitem>
 580        <para>
 581         record ID as provided by the
 582         <link linkend="command-show">show</link> command.
 583         </para>
 584       </listitem>
 585      </varlistentry>
 586
 587      <varlistentry>
 588       <term>offset</term>
 589       <listitem>
 590        <para>
 591         This optional parameter is an integer which, when given, makes
 592         Pazpar2 return the original record for a specific target.
 593         The record set from first target is numbered 0,
 594         second record set is numbered 1, etc.
 595         The nativesyntax setting, as usual, is used to determine how to
 596         create XML from the original record - unless parameter
 597         <literal>binary</literal> is given in which the record is
 598         fetched as "raw" from ZOOM C (raw, original record).
 599        </para>
 600        <para>
 601         When offset/checksum is not given, the Pazpar2 metadata for the record
 602         is returned and with metadata for each targets' data specified
 603         in a 'location' list.
 604        </para>
 605       </listitem>
 606      </varlistentry>
 607
 608      <varlistentry>
 609       <term>checksum</term>
 610       <listitem>
 611        <para>
 612         This optional parameter is a string which, when given, makes
 613         Pazpar2 return the original record for a specific target. The
 614         checksum is returned as attribtue 'checksum' in element
 615         'location' for show command and record command (when checksum
 616         and offset is NOT given).
 617         The nativesyntax setting, as usual, is used to determine how to
 618         create XML from the original record - unless parameter
 619         <literal>binary</literal> is given in which the record is
 620         fetched as "raw" from ZOOM C (raw, original record).
 621        </para>
 622        <para>
 623         When offset/checksum is not given, the Pazpar2 metadata for the record
 624         is returned and with metadata for each targets' data specified
 625         in a 'location' list.
 626        </para>
 627       </listitem>
 628      </varlistentry>
 629
 630
 631      <varlistentry>
 632       <term>nativesyntax</term>
 633       <listitem>
 634        <para>
 635         This optional parameter can be used to override pz:nativesyntax
 636         as given for the target. This allow an alternative nativesyntax
 637         to be used for original records (see parameteroffset above).
 638        </para>
 639       </listitem>
 640      </varlistentry>
 641
 642      <varlistentry>
 643       <term>syntax</term>
 644       <listitem>
 645        <para>
 646         This optional parameter is the record syntax used for raw
 647         transfer (i.e. when offset is specified). If syntax is not given,
 648         but offset is used, the value of pz:requestsyntax is used.
 649        </para>
 650       </listitem>
 651      </varlistentry>
 652
 653      <varlistentry>
 654       <term>esn</term>
 655       <listitem>
 656        <para>
 657         This optional parameter is the element set name used to retrieval
 658         of a raw record (i.e. when offset is specified).
 659         If esn is not given, but offset is used, the value of pz:elements
 660         is used.
 661        </para>
 662       </listitem>
 663      </varlistentry>
 664
 665      <varlistentry>
 666       <term>binary</term>
 667       <listitem>
 668        <para>
 669         This optional parameter enables "binary" response for retrieval
 670         of a original record (i.e. when offset is specified). For binary
 671         response the record by default is fetched from ZOOM C using
 672         the "raw" option or by parameter nativesyntax if given.
 673        </para>
 674       </listitem>
 675      </varlistentry>
 676
 677      <varlistentry>
 678       <term>snippets</term>
 679       <listitem>
 680        <para>
 681         If specified and set to 1 data will include snippets marked
 682         with &lt;match&gt; tags. Otherwise snippets will not be included.
 683        </para>
 684        <para>
 685         This facility, "snippets", appeared in Pazpar2 version
 686         1.6.32.
 687        </para>
 688       </listitem>
 689      </varlistentry>
 690
 691     </variablelist>
 692    </para>
 693    <para>
 694     Example:
 695     <screen><![CDATA[
 696 search.pz2?session=605047297&command=record&id=3
 697 ]]></screen>
 698
 699     Example output:
 700
 701     <screen><![CDATA[
 702 <record>
 703   <md-title>
 704         The Puget Sound Region : a portfolio of thematic computer maps /
 705   </md-title>
 706   <md-date>1974</md-date>
 707   <md-author>Mairs, John W.</md-author>
 708   <md-subject>Cartography</md-subject>
 709 </record>
 710 ]]></screen>
 711    </para>
 712   </refsect2>
 713
 714   <refsect2 id="command-stop">
 715    <title>stop</title>
 716    <para>
 717     Makes Pazpar2 stop further search &amp; retrieval for busy databases.
 718    </para>
 719   </refsect2>
 720
 721   <refsect2 id="command-termlist">
 722    <title>termlist</title>
 723    <para>
 724     Retrieves term list(s). Parameters:
 725
 726     <variablelist>
 727      <varlistentry>
 728       <term>session</term>
 729       <listitem>
 730        <para>
 731         Session Id.
 732        </para>
 733       </listitem>
 734      </varlistentry>
 735      <varlistentry>
 736       <term>name</term>
 737       <listitem>
 738        <para>
 739         comma-separated list of termlist names. If omitted,
 740         all termlists are returned.
 741        </para>
 742       </listitem>
 743      </varlistentry>
 744      <varlistentry>
 745       <term>num</term>
 746       <listitem>
 747        <para>
 748         maximum number of entries to return - default is 15.
 749        </para>
 750       </listitem>
 751      </varlistentry>
 752     </variablelist>
 753    </para>
 754    <para>
 755     Example:
 756     <screen><![CDATA[
 757 search.pz2?session=2044502273&command=termlist&name=author,subject
 758 ]]></screen>
 759     Output:
 760     <screen><![CDATA[
 761 <termlist>
 762   <activeclients>3</activeclients>
 763   <list name="author">
 764     <term>
 765       <name>Donald Knuth</name>
 766       <frequency>10</frequency>
 767     </term>
 768       <term>
 769       <name>Robert Pirsig</name>
 770       <frequency>2</frequency>
 771     </term>
 772   </list>
 773   <list name="subject">
 774     <term>
 775       <name>Computer programming</name>
 776       <frequency>10</frequency>
 777     </term>
 778   </list>
 779 </termlist>
 780 ]]></screen>
 781    </para>
 782
 783    <para>
 784     For the special termlist name "xtargets", results
 785     are returned about the targets which have returned the most hits.
 786     The 'term' subtree has additional elements,
 787     specifically a state and diagnostic field (in the example below, a
 788     target ID is returned in place of 'name'.
 789     This may or may not change later.
 790    </para>
 791    <para>
 792     Example
 793     <screen><![CDATA[
 794 <term>
 795   <name>library2.mcmaster.ca</name>
 796   <frequency>11734</frequency>         -- Number of hits
 797   <state>Client_Idle</state>           -- See the description of 'bytarget' below
 798   <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
 799 </term>
 800 ]]></screen>
 801    </para>
 802   </refsect2>
 803
 804
 805   <refsect2 id="command-bytarget">
 806    <title>bytarget</title>
 807    <para>
 808     Returns information about the status of each active client. Parameters:
 809
 810     <variablelist>
 811      <varlistentry>
 812       <term>session</term>
 813       <listitem>
 814        <para>
 815         Session Id.
 816         </para>
 817       </listitem>
 818      </varlistentry>
 819     </variablelist>
 820    </para>
 821    <para>
 822     Example:
 823     <screen><![CDATA[
 824 search.pz2?session=605047297&command=bytarget&id=3
 825 ]]></screen>
 826
 827     Example output:
 828
 829     <screen><![CDATA[
 830 <bytarget>
 831   <status>OK</status>
 832   <target>
 833     <id>z3950.loc.gov/voyager/</id>
 834     <hits>10000</hits>
 835     <diagnostic>0</diagnostic>
 836     <records>65</records>
 837     <state>Client_Presenting</state>
 838   </target>
 839   <!-- ... more target nodes below as necessary -->
 840 </bytarget>
 841 ]]></screen>
 842
 843     The following client states are defined: Client_Connecting,
 844     Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
 845     Client_Searching, Client_Presenting, Client_Error, Client_Failed,
 846     Client_Disconnected, Client_Stopped, Client_Continue.
 847    </para>
 848   </refsect2>
 849
 850   <refsect2 id="command-service">
 851    <title>service</title>
 852    <para>
 853     Returns service definition (XML). Parameters:
 854     <variablelist>
 855      <varlistentry>
 856       <term>session</term>
 857       <listitem>
 858        <para>
 859         Session ID
 860         </para>
 861       </listitem>
 862      </varlistentry>
 863     </variablelist>
 864    </para>
 865    <para>
 866     The service command appeared in Pazpar2 version 1.6.32
 867    </para>
 868   </refsect2>
 869  </refsect1>
 870  <refsect1>
 871   <title>SEE ALSO</title>
 872   <para>
 873    Pazpar2:
 874    <citerefentry>
 875     <refentrytitle>pazpar2</refentrytitle>
 876     <manvolnum>8</manvolnum>
 877    </citerefentry>
 878   </para>
 879   <para>
 880    Pazpar2 Configuration:
 881    <citerefentry>
 882     <refentrytitle>pazpar2_conf</refentrytitle>
 883     <manvolnum>5</manvolnum>
 884    </citerefentry>
 885   </para>
 886  </refsect1>
 887 </refentry>
 888
 889 <!-- Keep this comment at the end of the file
 890 Local variables:
 891 mode: nxml
 892 nxml-child-indent: 1
 893 End:
 894 -->