doc/yaz-client-commands.xml

   1 <!--
   2    $Id: yaz-client-commands.xml,v 1.4 2003-05-23 00:24:04 mike 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 id="sortspec"><term>
  95    <literal>sort</literal> <replaceable>sortspecs</replaceable>
  96   </term>
  97   <listitem>
  98    <para>Sorts a result set. The sort command takes a
  99     sequence of sort specifications. A sort
 100     specification holds a field (sort criteria) and is followed by flags.
 101     If the sort criteria includes <literal>=</literal> it is assumed
 102     that the sort SortKey is of type sortAttributes using Bib-1.
 103     The integer before <literal>=</literal> is
 104     the attribute type and the integer following <literal>=</literal>
 105     is the attribute value.
 106     If no <literal>=</literal> is in the SortKey it is treated as a
 107     sortfield-type of type InternationalString.
 108     Flags observed are: <literal>s</literal>
 109     for case sensitive, <literal>i</literal> for case insensitive,
 110     <literal>&lt;</literal> for sort ascending and <literal>&gt;</literal>
 111     for sort descending.
 112    </para>
 113   </listitem>
 114  </varlistentry>
 115  <varlistentry><term>
 116    <literal>sort+</literal>
 117   </term>
 118   <listitem>
 119    <para>Same as <literal>sort</literal> but stores the sorted
 120     result set in a new result set.
 121    </para>
 122   </listitem>
 123  </varlistentry>
 124  <varlistentry><term>
 125    <literal>authentication</literal> <replaceable>openauth</replaceable>
 126   </term>
 127   <listitem>
 128    <para>Sets up a authentication string if a server requires
 129     authentication (v2 OpenStyle). The authentication string is first
 130     sent to the server when the <literal>open</literal> command is
 131     issued and the Z39.50 Initialize Request is sent, so this command
 132     must be used before <literal>open</literal> in order to be effective.
 133     A common convention for the <replaceable>authopen</replaceable> string
 134     is that the username - and password is separated by a slash, e.g.
 135     <literal>myusername/mysecret</literal>.
 136    </para>
 137   </listitem>
 138  </varlistentry>
 139  <varlistentry><term>
 140    <literal>lslb</literal> <replaceable>n</replaceable>
 141   </term>
 142   <listitem>
 143    <para>Sets the limit for when no records should be returned
 144     together with the search result.
 145     See the
 146     <ulink
 147            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 148      Z39.50 standard
 149     </ulink>
 150     for more details.
 151    </para>
 152   </listitem>
 153  </varlistentry>
 154
 155  <varlistentry><term>
 156    <literal>ssub</literal> <replaceable>n</replaceable>
 157   </term>
 158   <listitem>
 159    <para>Sets the limit for when all records should be returned with
 160     the search result.
 161     See the
 162     <ulink
 163            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 164      Z39.50 standard
 165     </ulink> for more details.
 166    </para>
 167   </listitem>
 168  </varlistentry>
 169
 170  <varlistentry><term>
 171    <literal>mspn</literal> <replaceable>n</replaceable>
 172   </term>
 173   <listitem>
 174    <para>Sets the number of records should be returned if the
 175     number of records in the result set is between the values of
 176     <literal>lslb</literal> and <literal>ssub</literal>.
 177     See the
 178     <ulink
 179            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 180      Z39.50 standard
 181     </ulink>
 182     for more details.
 183    </para>
 184   </listitem>
 185  </varlistentry>
 186  <varlistentry><term>
 187    <literal>status</literal>
 188   </term>
 189   <listitem>
 190    <para>Displays the values of <literal>lslb</literal>,
 191     <literal>ssub</literal> and <literal>mspn</literal>.
 192    </para>
 193   </listitem>
 194  </varlistentry>
 195  <varlistentry><term>
 196    <literal>setname</literal>
 197   </term>
 198   <listitem>
 199    <para>Switches named result sets on and off. Default is on.
 200    </para>
 201   </listitem>
 202  </varlistentry>
 203  <varlistentry><term>
 204    <literal>cancel</literal>
 205   </term>
 206   <listitem>
 207    <para>Sends a Trigger Resource Control Request to the target.
 208    </para>
 209   </listitem>
 210  </varlistentry>
 211  <varlistentry><term>
 212    <literal>format</literal> <replaceable>oid</replaceable>
 213   </term>
 214   <listitem>
 215    <para>Sets the preferred transfer syntax for retrieved records.
 216     yaz-client supports all the record syntaxes that currently
 217     are registered. See
 218     <ulink
 219            url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
 220      Z39.50 Standard
 221     </ulink>
 222     for more details. Commonly used records syntaxes include usmarc,
 223     sutrs, grs1 and xml.
 224    </para>
 225   </listitem>
 226  </varlistentry>
 227  <varlistentry><term>
 228    <literal>elements</literal> <replaceable>e</replaceable>
 229   </term>
 230   <listitem>
 231    <para>Sets the element set name for the records. Many targets support
 232     element sets are B (for brief) and F (for full).
 233    </para>
 234   </listitem>
 235  </varlistentry>
 236  <varlistentry><term>
 237    <literal>close</literal>
 238   </term>
 239   <listitem>
 240    <para>Sends a Z39.50 Close APDU and closes connection with the peer
 241    </para>
 242   </listitem>
 243  </varlistentry>
 244  <varlistentry><term>
 245    <literal>querytype</literal> <replaceable>type</replaceable>
 246   </term>
 247   <listitem>
 248    <para>Sets the query type as used by command <literal>find</literal>.
 249     The following is supported:
 250     <literal>prefix</literal> for
 251         <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
 252     <literal>ccl</literal> for CCL search (Type-2 Query),
 253     <literal>cql</literal> for CQL (Type-104 search with CQL OID),
 254     <literal>ccl2rpn</literal> for
 255         <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
 256     <literal>cql2rpn</literal> for
 257         CQL to RPN conversion (Type-1 Query).
 258    </para>
 259   </listitem>
 260  </varlistentry>
 261  <varlistentry><term>
 262    <literal>attributeset</literal> <replaceable>set</replaceable>
 263   </term>
 264   <listitem>
 265    <para>
 266     Sets attribute set OID for prefix queries (RPN, Type-1).
 267    </para>
 268   </listitem>
 269  </varlistentry>
 270  <varlistentry><term>
 271    <literal>refid</literal> <replaceable>id</replaceable>
 272   </term>
 273   <listitem>
 274    <para>Sets reference ID for Z39.50 Request(s).
 275    </para>
 276   </listitem>
 277  </varlistentry>
 278  <varlistentry><term>
 279    <literal>itemorder</literal>
 280    <replaceable>type</replaceable> <replaceable>no</replaceable>
 281   </term>
 282   <listitem>
 283    <para>Sends an Item Order Request using the ILL External.
 284     <replaceable>type</replaceable> is either 1 or 2 which corresponds to
 285     ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
 286     is the Result Set position of the record to be ordered.
 287    </para>
 288   </listitem>
 289  </varlistentry>
 290  <varlistentry><term>
 291    <literal>update</literal>
 292   </term>
 293   <listitem>
 294    <para>Sends Item Update Request. This command sends a "minimal"
 295     PDU Update to the target supplying the last received record from
 296     the target.
 297     If no record has been received from the target this command is ignored
 298     and nothing is sent to the target.
 299    </para>
 300   </listitem>
 301  </varlistentry>
 302
 303  <varlistentry><term>
 304    <literal>.</literal>
 305    <replaceable>filename</replaceable>
 306   </term>
 307   <listitem>
 308    <para>Executes list of commands from
 309     file <replaceable>filename</replaceable>, just like source on
 310     most UNIX shells.
 311    </para>
 312   </listitem>
 313  </varlistentry>
 314
 315  <varlistentry><term>
 316    <literal>!</literal>
 317    <replaceable>args</replaceable>
 318   </term>
 319   <listitem>
 320    <para>Executes command <replaceable>args</replaceable> in subshell
 321     using the <literal>system</literal> call.
 322    </para>
 323   </listitem>
 324  </varlistentry>
 325
 326  <varlistentry><term>
 327    <literal>push_commande</literal>
 328    <replaceable>command</replaceable>
 329   </term>
 330   <listitem>
 331    <para>The push_command takes another command as its argument.
 332     That command is then added to the history information (so
 333     you can retrieve it later). The command itself is not
 334     executed. This command only works if you have GNU readline/history
 335     enabled.
 336    </para>
 337   </listitem>
 338  </varlistentry>
 339
 340  <varlistentry><term>
 341    <literal>set_apdufile</literal>
 342    <replaceable>filename</replaceable>
 343   </term>
 344   <listitem>
 345    <para>Sets that APDU should be logged to file
 346     <replaceable>filename</replaceable>. This command does the
 347     thing as option <literal>-a</literal>.
 348    </para>
 349   </listitem>
 350  </varlistentry>
 351
 352  <varlistentry><term>
 353    <literal>set_marcdump</literal>
 354    <replaceable>filename</replaceable>
 355   </term>
 356   <listitem>
 357    <para>Specifies that all retrieved records should be appended ot
 358     file <replaceable>filename</replaceable>. This command does the
 359     thing as option <literal>-m</literal>.
 360    </para>
 361   </listitem>
 362  </varlistentry>
 363
 364  <varlistentry><term>
 365    <literal>schema</literal>
 366    <replaceable>schemaid</replaceable>
 367   </term>
 368   <listitem>
 369    <para>Specifies schema for retrieval.
 370     Schema may be specified as an OID for Z39.50.
 371     For SRW, schema is a simple string URI.
 372    </para>
 373   </listitem>
 374  </varlistentry>
 375
 376  <varlistentry><term>
 377    <literal>charset</literal>
 378    <replaceable>negotiationcharset</replaceable>
 379    [<replaceable>outputcharset</replaceable>]
 380   </term>
 381   <listitem>
 382    <para>Specifies character set (encoding) for Z39.50
 383     negotiation / SRW encoding and/or character set for output (terminal).
 384    </para>
 385    <para>
 386     <replaceable>negotiationcharset</replaceable> is the name
 387     of the character set to be negotiated by the server. The special name
 388     <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
 389     specifies <emphasis>no</emphasis> character set to be negotiated.
 390    </para>
 391    <para>
 392     If <replaceable>outputcharset</replaceable> is given, it specifies name
 393     of the character set of the output (on the terminal on which
 394     YAZ client is running). To disable conversion of characters
 395     to the output encoding, the special name <literal>-</literal> (dash)
 396     can be used.
 397     If the special name <literal>auto</literal> is given, YAZ client will
 398     convert strings to the encoding of the
 399     terminal as returned by <function>nl_langinfo</function> call.
 400    </para>
 401    <note>
 402     <para>
 403      Since character set negotation takes effect in the Z39.50
 404      Initialize Request you should issue this command before
 405      command <literal>open</literal> is used.
 406     </para>
 407    </note>
 408    <note>
 409     <para>
 410      MARC records are not covered by Z39.50 character set negotiation.
 411      See <literal>marccharset</literal>.
 412     </para>
 413    </note>
 414   </listitem>
 415  </varlistentry>
 416
 417  <varlistentry><term>
 418    <literal>marccharset</literal>
 419    <replaceable>charset</replaceable>
 420   </term>
 421   <listitem>
 422    <para>Specifies character set for retrieved MARC records so
 423     that YAZ client can display them in a character suitable
 424     for your display. See <literal>charset</literal> command.
 425     If <literal>auto</literal> is given, YAZ will assume
 426     that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
 427     for all other MARC variants.
 428    </para>
 429   </listitem>
 430  </varlistentry>
 431
 432  <varlistentry><term>
 433    <literal>set_cclfields</literal>
 434    <replaceable>filename</replaceable>
 435   </term>
 436   <listitem>
 437    <para>Specifies that CCL fields should be read from file
 438     file <replaceable>filename</replaceable>. This command does the
 439     thing as option <literal>-c</literal>.
 440    </para>
 441   </listitem>
 442  </varlistentry>
 443
 444  <varlistentry><term>
 445    <literal>set_cqlfields</literal>
 446    <replaceable>filename</replaceable>
 447   </term>
 448   <listitem>
 449    <para>Specifies that CQL fields should be read from file
 450     file <replaceable>filename</replaceable>. This command does the
 451     thing as option <literal>-q</literal>.
 452    </para>
 453   </listitem>
 454  </varlistentry>
 455
 456  <varlistentry><term>
 457    <literal>register_oid</literal>
 458    <replaceable>name</replaceable>
 459    <replaceable>class</replaceable>
 460    <replaceable>OID</replaceable>
 461   </term>
 462   <listitem>
 463    <para>This command allows you to register your own object
 464     identifier - so that instead of entering a long dot-notation
 465     you can use a short name instead.
 466     The <replaceable>name</replaceable> is your
 467     name for the OID, <replaceable>class</replaceable> is the
 468     class, and <replaceable>OID</replaceable> is the raw OID in
 469     dot notation. Class is one <literal>appctx</literal>,
 470     <literal>absyn</literal>, <literal>attet</literal>,
 471     <literal>transyn</literal>, <literal>diagset</literal>,
 472     <literal>recsyn</literal>, <literal>resform</literal>,
 473     <literal>accform</literal>, <literal>extserv</literal>,
 474     <literal>userinfo</literal>, <literal>elemspec</literal>,
 475     <literal>varset</literal>, <literal>schema</literal>,
 476     <literal>tagset</literal>, <literal>general</literal>.
 477     If you're in doubt use the <literal>general</literal>
 478     class.
 479    </para>
 480   </listitem>
 481  </varlistentry>
 482
 483 </variablelist>
 484 <!-- Keep this comment at the end of the file
 485 Local variables:
 486 mode: sgml
 487 sgml-omittag:t
 488 sgml-shorttag:t
 489 sgml-minimize-attributes:nil
 490 sgml-always-quote-attributes:t
 491 sgml-indent-step:1
 492 sgml-indent-data:t
 493 sgml-parent-document: "yaz.xml"
 494 sgml-local-catalogs: nil
 495 sgml-namecase-general:t
 496 End:
 497 -->