doc/yaz-client-commands.xml

   1 <!--
   2    $Id: yaz-client-commands.xml,v 1.7 2005-02-02 17:11:05 adam Exp $
   3    Commands for YAZ client.
   4    Included in both manual and man page for yaz-client.
   5 -->
   6 <variablelist>
   7  <varlistentry><term>
   8    <literal>open </literal><replaceable>zurl</replaceable>
   9   </term>
  10   <listitem>
  11    <para>Opens a connection to a server. The syntax for
  12     <replaceable>zurl</replaceable> is the same as described
  13     above for connecting from the command line.
  14    </para>
  15    <para>
  16     Syntax:
  17    </para>
  18    <para>
  19     [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
  20     [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
  21    </para>
  22   </listitem>
  23  </varlistentry>
  24  <varlistentry><term>
  25    <literal>quit</literal>
  26   </term>
  27   <listitem>
  28    <para>Quits YAZ client</para>
  29   </listitem>
  30  </varlistentry>
  31  <varlistentry><term>
  32    <literal>f </literal><replaceable>query</replaceable></term>
  33   <listitem>
  34    <para>Sends a Search Request using the <replaceable>query</replaceable>
  35     given.
  36    </para>
  37   </listitem>
  38  </varlistentry>
  39  <varlistentry><term>
  40    <literal>delete</literal> <replaceable>setname</replaceable></term>
  41   <listitem>
  42    <para>Deletes result set with name <replaceable>setname</replaceable>
  43     on the server.</para>
  44   </listitem>
  45  </varlistentry>
  46  <varlistentry><term>
  47    <literal>base </literal><replaceable>base1</replaceable>
  48    <replaceable>base2</replaceable> ...
  49   </term>
  50   <listitem>
  51    <para>Sets the name(s) of the database(s) to search. One or more
  52     databases may be specified separated by blanks. This commands overrides
  53     the database given in <replaceable>zurl</replaceable>.
  54    </para>
  55   </listitem>
  56  </varlistentry>
  57  <varlistentry><term>
  58    <literal>show </literal>
  59    [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
  60   </term>
  61   <listitem>
  62    <para>Fetches records by sending a Present Request from the start
  63     position given by
  64     <replaceable>start</replaceable>
  65     a number of records given by <replaceable>number</replaceable>. If
  66     <replaceable>start</replaceable> is not given, then the client
  67     will fetch from position of the last retrieved record plus 1. If
  68     <replaceable>number</replaceable> is not given, then one record will
  69     be fetched at a time.
  70    </para>
  71   </listitem>
  72  </varlistentry>
  73  <varlistentry><term>
  74    <literal>scan</literal> <replaceable>term</replaceable>
  75   </term>
  76   <listitem>
  77    <simpara>Scans
  78     database index for a term. The syntax resembles the syntax
  79     for <literal>find</literal>.
  80     If you want to scan for the word <literal>water</literal> you could
  81     write
  82    </simpara>
  83    <screen>
  84     scan water
  85    </screen>
  86    <simpara>
  87     but if you want to scan only in, say the title field, you would write
  88    </simpara>
  89    <screen>
  90     scan @attr 1=4 water
  91    </screen>
  92   </listitem>
  93  </varlistentry>
  94  <varlistentry><term>
  95    <literal>scanpos</literal> <replaceable>pos</replaceable>
  96   </term>
  97   <listitem>
  98    <simpara>
  99     Sets preferred position for scan. This value
 100     is used in next scan. By default position is 1.
 101    </simpara>
 102   </listitem>
 103  </varlistentry>
 104  <varlistentry><term>
 105    <literal>scansize</literal> <replaceable>size</replaceable>
 106   </term>
 107   <listitem>
 108    <simpara>
 109     Sets number of entries to be returned by scan. Default
 110     number of entries is 20.
 111    </simpara>
 112   </listitem>
 113  </varlistentry>
 114  <varlistentry><term>
 115    <literal>scanstep</literal> <replaceable>step</replaceable>
 116   </term>
 117   <listitem>
 118    <simpara>
 119     Set step-size for scan. This value is used in next scan
 120     sent to the target. By default step-size is 0.
 121    </simpara>
 122   </listitem>
 123  </varlistentry>
 124  <varlistentry id="sortspec"><term>
 125    <literal>sort</literal> <replaceable>sortspecs</replaceable>
 126   </term>
 127   <listitem>
 128    <para>Sorts a result set. The sort command takes a
 129     sequence of sort specifications. A sort
 130     specification holds a field (sort criteria) and is followed by flags.
 131     If the sort criteria includes <literal>=</literal> it is assumed
 132     that the sort SortKey is of type sortAttributes using Bib-1.
 133     The integer before <literal>=</literal> is
 134     the attribute type and the integer following <literal>=</literal>
 135     is the attribute value.
 136     If no <literal>=</literal> is in the SortKey it is treated as a
 137     sortfield-type of type InternationalString.
 138     Flags observed are: <literal>s</literal>
 139     for case sensitive, <literal>i</literal> for case insensitive,
 140     <literal>&lt;</literal> for sort ascending and <literal>&gt;</literal>
 141     for sort descending.
 142    </para>
 143   </listitem>
 144  </varlistentry>
 145  <varlistentry><term>
 146    <literal>sort+</literal>
 147   </term>
 148   <listitem>
 149    <para>Same as <literal>sort</literal> but stores the sorted
 150     result set in a new result set.
 151    </para>
 152   </listitem>
 153  </varlistentry>
 154  <varlistentry><term>
 155    <literal>authentication</literal> <replaceable>openauth</replaceable>
 156   </term>
 157   <listitem>
 158    <para>Sets up a authentication string if a server requires
 159     authentication (v2 OpenStyle). The authentication string is first
 160     sent to the server when the <literal>open</literal> command is
 161     issued and the Z39.50 Initialize Request is sent, so this command
 162     must be used before <literal>open</literal> in order to be effective.
 163     A common convention for the <replaceable>authopen</replaceable> string
 164     is that the username - and password is separated by a slash, e.g.
 165     <literal>myusername/mysecret</literal>.
 166    </para>
 167   </listitem>
 168  </varlistentry>
 169
 170  <varlistentry><term>
 171    <literal>list_all</literal>
 172   </term>
 173   <listitem>
 174    <para>This command displays status and values for many settings.
 175    </para>
 176   </listitem>
 177  </varlistentry>
 178
 179  <varlistentry><term>
 180    <literal>lslb</literal> <replaceable>n</replaceable>
 181   </term>
 182   <listitem>
 183    <para>Sets the limit for when no records should be returned
 184     together with the search result.
 185     See the
 186     <ulink
 187            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 188      Z39.50 standard
 189     </ulink>
 190     for more details.
 191    </para>
 192   </listitem>
 193  </varlistentry>
 194
 195  <varlistentry><term>
 196    <literal>ssub</literal> <replaceable>n</replaceable>
 197   </term>
 198   <listitem>
 199    <para>Sets the limit for when all records should be returned with
 200     the search result.
 201     See the
 202     <ulink
 203            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 204      Z39.50 standard
 205     </ulink> for more details.
 206    </para>
 207   </listitem>
 208  </varlistentry>
 209
 210  <varlistentry><term>
 211    <literal>mspn</literal> <replaceable>n</replaceable>
 212   </term>
 213   <listitem>
 214    <para>Sets the number of records should be returned if the
 215     number of records in the result set is between the values of
 216     <literal>lslb</literal> and <literal>ssub</literal>.
 217     See the
 218     <ulink
 219            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 220      Z39.50 standard
 221     </ulink>
 222     for more details.
 223    </para>
 224   </listitem>
 225  </varlistentry>
 226  <varlistentry><term>
 227    <literal>status</literal>
 228   </term>
 229   <listitem>
 230    <para>Displays the values of <literal>lslb</literal>,
 231     <literal>ssub</literal> and <literal>mspn</literal>.
 232    </para>
 233   </listitem>
 234  </varlistentry>
 235  <varlistentry><term>
 236    <literal>setname</literal>
 237   </term>
 238   <listitem>
 239    <para>Switches named result sets on and off. Default is on.
 240    </para>
 241   </listitem>
 242  </varlistentry>
 243  <varlistentry><term>
 244    <literal>cancel</literal>
 245   </term>
 246   <listitem>
 247    <para>Sends a Trigger Resource Control Request to the target.
 248    </para>
 249   </listitem>
 250  </varlistentry>
 251  <varlistentry><term>
 252    <literal>format</literal> <replaceable>oid</replaceable>
 253   </term>
 254   <listitem>
 255    <para>Sets the preferred transfer syntax for retrieved records.
 256     yaz-client supports all the record syntaxes that currently
 257     are registered. See
 258     <ulink
 259            url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
 260      Z39.50 Standard
 261     </ulink>
 262     for more details. Commonly used records syntaxes include usmarc,
 263     sutrs, grs1 and xml.
 264    </para>
 265   </listitem>
 266  </varlistentry>
 267  <varlistentry><term>
 268    <literal>elements</literal> <replaceable>e</replaceable>
 269   </term>
 270   <listitem>
 271    <para>Sets the element set name for the records. Many targets support
 272     element sets are B (for brief) and F (for full).
 273    </para>
 274   </listitem>
 275  </varlistentry>
 276  <varlistentry><term>
 277    <literal>close</literal>
 278   </term>
 279   <listitem>
 280    <para>Sends a Z39.50 Close APDU and closes connection with the peer
 281    </para>
 282   </listitem>
 283  </varlistentry>
 284  <varlistentry><term>
 285    <literal>querytype</literal> <replaceable>type</replaceable>
 286   </term>
 287   <listitem>
 288    <para>Sets the query type as used by command <literal>find</literal>.
 289     The following is supported:
 290     <literal>prefix</literal> for
 291         <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
 292     <literal>ccl</literal> for CCL search (Type-2 Query),
 293     <literal>cql</literal> for CQL (Type-104 search with CQL OID),
 294     <literal>ccl2rpn</literal> for
 295         <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
 296     <literal>cql2rpn</literal> for
 297         CQL to RPN conversion (Type-1 Query).
 298    </para>
 299   </listitem>
 300  </varlistentry>
 301  <varlistentry><term>
 302    <literal>attributeset</literal> <replaceable>set</replaceable>
 303   </term>
 304   <listitem>
 305    <para>
 306     Sets attribute set OID for prefix queries (RPN, Type-1).
 307    </para>
 308   </listitem>
 309  </varlistentry>
 310  <varlistentry><term>
 311    <literal>refid</literal> <replaceable>id</replaceable>
 312   </term>
 313   <listitem>
 314    <para>Sets reference ID for Z39.50 Request(s).
 315    </para>
 316   </listitem>
 317  </varlistentry>
 318  <varlistentry><term>
 319    <literal>itemorder</literal>
 320    <replaceable>type</replaceable> <replaceable>no</replaceable>
 321   </term>
 322   <listitem>
 323    <para>Sends an Item Order Request using the ILL External.
 324     <replaceable>type</replaceable> is either 1 or 2 which corresponds to
 325     ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
 326     is the Result Set position of the record to be ordered.
 327    </para>
 328   </listitem>
 329  </varlistentry>
 330  <varlistentry><term>
 331    <literal>update</literal>
 332   </term>
 333   <listitem>
 334    <para>Sends Item Update Request. This command sends a "minimal"
 335     PDU Update to the target supplying the last received record from
 336     the target.
 337     If no record has been received from the target this command is ignored
 338     and nothing is sent to the target.
 339    </para>
 340   </listitem>
 341  </varlistentry>
 342
 343  <varlistentry><term>
 344    <literal>.</literal>
 345    <replaceable>filename</replaceable>
 346   </term>
 347   <listitem>
 348    <para>Executes list of commands from
 349     file <replaceable>filename</replaceable>, just like source on
 350     most UNIX shells.
 351    </para>
 352   </listitem>
 353  </varlistentry>
 354
 355  <varlistentry><term>
 356    <literal>!</literal>
 357    <replaceable>args</replaceable>
 358   </term>
 359   <listitem>
 360    <para>Executes command <replaceable>args</replaceable> in subshell
 361     using the <literal>system</literal> call.
 362    </para>
 363   </listitem>
 364  </varlistentry>
 365
 366  <varlistentry><term>
 367    <literal>push_commande</literal>
 368    <replaceable>command</replaceable>
 369   </term>
 370   <listitem>
 371    <para>The push_command takes another command as its argument.
 372     That command is then added to the history information (so
 373     you can retrieve it later). The command itself is not
 374     executed. This command only works if you have GNU readline/history
 375     enabled.
 376    </para>
 377   </listitem>
 378  </varlistentry>
 379
 380  <varlistentry><term>
 381    <literal>set_apdufile</literal>
 382    <replaceable>filename</replaceable>
 383   </term>
 384   <listitem>
 385    <para>Sets that APDU should be logged to file
 386     <replaceable>filename</replaceable>. This command does the
 387     thing as option <literal>-a</literal>.
 388    </para>
 389   </listitem>
 390  </varlistentry>
 391
 392  <varlistentry><term>
 393    <literal>set_auto_reconnect</literal>
 394    <replaceable>flag</replaceable>
 395   </term>
 396   <listitem>
 397    <para>Specifies whether YAZ client automatically reconnect if
 398     target closes connection (Z39.50 only).
 399     <replaceable>flag</replaceable> must be either
 400     <literal>on</literal> or <literal>off</literal>.
 401    </para>
 402   </listitem>
 403  </varlistentry>
 404
 405  <varlistentry><term>
 406    <literal>set_marcdump</literal>
 407    <replaceable>filename</replaceable>
 408   </term>
 409   <listitem>
 410    <para>Specifies that all retrieved records should be appended ot
 411     file <replaceable>filename</replaceable>. This command does the
 412     thing as option <literal>-m</literal>.
 413    </para>
 414   </listitem>
 415  </varlistentry>
 416
 417  <varlistentry><term>
 418    <literal>schema</literal>
 419    <replaceable>schemaid</replaceable>
 420   </term>
 421   <listitem>
 422    <para>Specifies schema for retrieval.
 423     Schema may be specified as an OID for Z39.50.
 424     For SRW, schema is a simple string URI.
 425    </para>
 426   </listitem>
 427  </varlistentry>
 428
 429  <varlistentry><term>
 430    <literal>charset</literal>
 431    <replaceable>negotiationcharset</replaceable>
 432    [<replaceable>displaycharset</replaceable>]
 433    [[<replaceable>marccharset</replaceable>]]
 434   </term>
 435   <listitem>
 436    <para>Specifies character set (encoding) for Z39.50
 437     negotiation / SRW encoding and/or character set for output (terminal).
 438    </para>
 439    <para>
 440     <replaceable>negotiationcharset</replaceable> is the name
 441     of the character set to be negotiated by the server. The special name
 442     <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
 443     specifies <emphasis>no</emphasis> character set to be negotiated.
 444    </para>
 445    <para>
 446     If <replaceable>displaycharset</replaceable> is given, it specifies name
 447     of the character set of the output (on the terminal on which
 448     YAZ client is running). To disable conversion of characters
 449     to the output encoding, the special name <literal>-</literal> (dash)
 450     can be used.
 451     If the special name <literal>auto</literal> is given, YAZ client will
 452     convert strings to the encoding of the
 453     terminal as returned by <function>nl_langinfo</function> call.
 454    </para>
 455    <para>
 456     If <replaceable>marcharset</replaceable> is given, it specifies name
 457     of the character set of retrieved MARC records from server. See
 458     also <literal>marcharset</literal> command.
 459    </para>
 460    <note>
 461     <para>
 462      Since character set negotation takes effect in the Z39.50
 463      Initialize Request you should issue this command before
 464      command <literal>open</literal> is used.
 465     </para>
 466    </note>
 467    <note>
 468     <para>
 469      MARC records are not covered by Z39.50 character set negotiation,
 470      so that's why there is a separate character that must be known
 471      in order to do meaningful converson(s).
 472     </para>
 473    </note>
 474   </listitem>
 475  </varlistentry>
 476
 477  <varlistentry><term>
 478    <literal>negcharset</literal>
 479    <replaceable>charset</replaceable>
 480   </term>
 481   <listitem>
 482    <para>Specifies character set for negotiation (Z39.50). The
 483     argument is the same as second argument for command
 484     <literal>charset</literal>.
 485    </para>
 486   </listitem>
 487  </varlistentry>
 488
 489  <varlistentry><term>
 490    <literal>displaycharset</literal>
 491    <replaceable>charset</replaceable>
 492   </term>
 493   <listitem>
 494    <para>Specifies character set for output (display). The
 495     argument is the same as second argument for
 496     command <literal>charset</literal>.
 497    </para>
 498   </listitem>
 499  </varlistentry>
 500
 501  <varlistentry><term>
 502    <literal>marccharset</literal>
 503    <replaceable>charset</replaceable>
 504   </term>
 505   <listitem>
 506    <para>Specifies character set for retrieved MARC records so
 507     that YAZ client can display them in a character suitable
 508     for your display. See <literal>charset</literal> command.
 509     If <literal>auto</literal> is given, YAZ will assume
 510     that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
 511     for all other MARC variants. The charset argument is the
 512     same as third argument for <literal>charset</literal> command.
 513    </para>
 514   </listitem>
 515  </varlistentry>
 516
 517  <varlistentry><term>
 518    <literal>set_cclfile</literal>
 519    <replaceable>filename</replaceable>
 520   </term>
 521   <listitem>
 522    <para>Specifies that CCL fields should be read from file
 523     file <replaceable>filename</replaceable>. This command does the
 524     thing as option <literal>-c</literal>.
 525    </para>
 526   </listitem>
 527  </varlistentry>
 528
 529  <varlistentry><term>
 530    <literal>set_cqlfile</literal>
 531    <replaceable>filename</replaceable>
 532   </term>
 533   <listitem>
 534    <para>Specifies that CQL fields should be read from file
 535     file <replaceable>filename</replaceable>. This command does the
 536     thing as option <literal>-q</literal>.
 537    </para>
 538   </listitem>
 539  </varlistentry>
 540
 541  <varlistentry><term>
 542    <literal>register_oid</literal>
 543    <replaceable>name</replaceable>
 544    <replaceable>class</replaceable>
 545    <replaceable>OID</replaceable>
 546   </term>
 547   <listitem>
 548    <para>This command allows you to register your own object
 549     identifier - so that instead of entering a long dot-notation
 550     you can use a short name instead.
 551     The <replaceable>name</replaceable> is your
 552     name for the OID, <replaceable>class</replaceable> is the
 553     class, and <replaceable>OID</replaceable> is the raw OID in
 554     dot notation. Class is one <literal>appctx</literal>,
 555     <literal>absyn</literal>, <literal>attet</literal>,
 556     <literal>transyn</literal>, <literal>diagset</literal>,
 557     <literal>recsyn</literal>, <literal>resform</literal>,
 558     <literal>accform</literal>, <literal>extserv</literal>,
 559     <literal>userinfo</literal>, <literal>elemspec</literal>,
 560     <literal>varset</literal>, <literal>schema</literal>,
 561     <literal>tagset</literal>, <literal>general</literal>.
 562     If you're in doubt use the <literal>general</literal>
 563     class.
 564    </para>
 565   </listitem>
 566  </varlistentry>
 567
 568  <varlistentry><term>
 569    <literal>register_tab</literal>
 570    <replaceable>command</replaceable>
 571    <replaceable>string</replaceable>
 572   </term>
 573   <listitem>
 574    <para>This command registers a TAB completion string for
 575     the command given.
 576    </para>
 577   </listitem>
 578  </varlistentry>
 579
 580  <varlistentry><term>
 581    <literal>sleep</literal>
 582    <replaceable>seconds</replaceable>
 583   </term>
 584   <listitem>
 585    <para>This command makes YAZ client sleep (be idle) for
 586     the number of seconds given.
 587    </para>
 588   </listitem>
 589  </varlistentry>
 590
 591  <varlistentry><term>
 592    <literal>zversion</literal>
 593    <replaceable>ver</replaceable>
 594   </term>
 595   <listitem>
 596    <para>This command sets Z39.50 version for negotiation.
 597     Should be used before <literal>open</literal>.
 598     By default, 3 (version 3) is used.
 599    </para>
 600   </listitem>
 601  </varlistentry>
 602
 603  <varlistentry><term>
 604    <literal>options</literal>
 605    <replaceable>op1 op2..</replaceable>
 606   </term>
 607   <listitem>
 608    <para>This command sets Z39.50 options for negotiation.
 609     Should be used before <literal>open</literal>.
 610    </para>
 611    <para>
 612     The following options are supported:
 613     <literal>search</literal>,
 614     <literal>present</literal>,
 615     <literal>delSet</literal>,
 616     <literal>resourceReport</literal>,
 617     <literal>triggerResourceCtrl</literal>,
 618     <literal>resourceCtrl</literal>,
 619     <literal>accessCtrl</literal>,
 620     <literal>scan</literal>,
 621     <literal>sort</literal>,
 622     <literal>extendedServices</literal>,
 623     <literal>level_1Segmentation</literal>,
 624     <literal>level_2Segmentation</literal>,
 625     <literal>concurrentOperations</literal>,
 626     <literal>namedResultSets</literal>,
 627     <literal>encapsulation</literal>,
 628     <literal>resultCount</literal>,
 629     <literal>negotiationModel</literal>,
 630     <literal>duplicationDetection</literal>,
 631     <literal>queryType104</literal>,
 632     <literal>pQESCorrection</literal>,
 633     <literal>stringSchema</literal>.
 634    </para>
 635   </listitem>
 636  </varlistentry>
 637
 638 </variablelist>
 639 <!-- Keep this comment at the end of the file
 640 Local variables:
 641 mode: sgml
 642 sgml-omittag:t
 643 sgml-shorttag:t
 644 sgml-minimize-attributes:nil
 645 sgml-always-quote-attributes:t
 646 sgml-indent-step:1
 647 sgml-indent-data:t
 648 sgml-parent-document: "yaz.xml"
 649 sgml-local-catalogs: nil
 650 sgml-namecase-general:t
 651 End:
 652 -->