doc/yaz-client-commands.xml

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