doc/yaz-client-commands.xml

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