doc/client.xml

   1 <!-- $Id: client.xml,v 1.11 2002-02-24 12:23:43 adam Exp $ -->
   2  <chapter id="client"><title>The YAZ client</title>
   3   <sect1 id="client.introduction"><title>Introduction</title>
   4    <para>
   5     yaz-client is a line-mode Z39.50 client. It supports a fair amount
   6     of the functionality of the Z39.50-1995 standard
   7     Its primary purpose is to exercise the package, and verify that
   8     the protocol works OK.
   9     For the same reason some commands offers more functionality than others.
  10     Commands that exercises common Z39.50 services such as search and present
  11     have more features than less common supported services, such as Extended
  12     Services (ItemOrder, ItemUpdate,..).
  13    </para>
  14   </sect1>
  15   <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
  16    <para>
  17     It can be started by typing
  18    </para>
  19    <screen>
  20      yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
  21    </screen>
  22    <simpara>
  23     in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
  24     specifies a Z39.50 host and, if specified, the client first tries to
  25     establish connection with the Z39.50 target on the host.
  26     Options are, as usual, are prefixed by
  27     <literal>-</literal> followed by a particular letter.
  28     </simpara>
  29    <simpara>
  30     The following options are supported:
  31    </simpara>
  32    <variablelist>
  33     <varlistentry><term>
  34       <literal>-m</literal> <replaceable>fname</replaceable>
  35      </term><listitem>
  36       <simpara>All retrieved transfer records are appended to file
  37        <replaceable>fname</replaceable>. All records as returned by a
  38        target(s) in Search Responses and Present Responses are appended
  39        verbatim to the file.
  40       </simpara></listitem>
  41     </varlistentry>
  42     <varlistentry><term>
  43       <literal>-a</literal> <replaceable>fname</replaceable>
  44      </term><listitem>
  45       <simpara>Pretty-print log of APDUs sent and received is appended
  46        to the file <replaceable>fname</replaceable>.
  47        If <replaceable>fname</replaceable> is <literal>-</literal> (minus)
  48        the APDU log is written to <literal>stderr</literal>.
  49       </simpara></listitem>
  50     </varlistentry>
  51     <varlistentry><term>
  52       <literal>-c</literal> <replaceable>fname</replaceable>
  53      </term><listitem>
  54       <simpara>Sets the filename for CCL fields to
  55        <replaceable>fname</replaceable>. If this option is not given the
  56        YAZ client reads CCL fields from file <literal>default.bib</literal>.
  57       </simpara></listitem>
  58     </varlistentry>
  59     <varlistentry><term>
  60       <literal>-v</literal> <replaceable>level</replaceable>
  61      </term><listitem>
  62       <simpara>Sets the LOG level to <replaceable>level</replaceable>.
  63        Level is a sequence of tokens separated by comma. Each token
  64        is a integer or a named LOG item - one of
  65        <literal>fatal</literal>,
  66        <literal>debug</literal>,
  67        <literal>warn</literal>,
  68        <literal>log</literal>,
  69        <literal>all</literal>,
  70        <literal>none</literal>.
  71       </simpara></listitem>
  72     </varlistentry>
  73     <varlistentry><term>
  74       <literal>-p</literal> <replaceable>target</replaceable>
  75      </term><listitem>
  76       <simpara>Specifies proxy address. When set YAZ client will
  77        connect to a proxy on the address and port given.
  78        The actual target will be specifed as part of the InitRequest
  79        to inform the proxy about actual target.
  80       </simpara></listitem>
  81     </varlistentry>
  82     <varlistentry><term>
  83       <literal>-u</literal> <replaceable>authentication</replaceable>
  84      </term><listitem>
  85       <simpara>Specifies authentication. Usually the form
  86        <replaceable>user</replaceable>/<replaceable>password</replaceable>
  87        is used. This option does the same thing as the
  88        <literal>auth</literal> command.
  89       </simpara></listitem>
  90     </varlistentry>
  91
  92     <varlistentry><term>
  93       <literal>-k</literal> <replaceable>kilobytes</replaceable>
  94      </term><listitem>
  95       <simpara>Specifies the maximum messages size in kilobytes.
  96        The default maxium messages for the YAZ client is 1024
  97        (1 MB).
  98       </simpara></listitem>
  99     </varlistentry>
 100
 101    </variablelist>
 102    <para>
 103     In order to connect to Index Data's test Z39.50 server on
 104     <literal>bagel.indexdata.dk</literal>, port 210 and with the
 105     database name marc, one would have to type
 106    </para>
 107    <screen>
 108     yaz-client bagel.indexdata.dk:210/marc
 109    </screen>
 110    <para>
 111     In order to enable APDU log and connect to localhost, port 210 (default)
 112     and database Default (default) you'd write:
 113    </para>
 114    <screen>
 115     yaz-client -a - localhost
 116    </screen>
 117   </sect1>
 118   <sect1 id="client.commands"><title>Commands</title>
 119    <para>
 120     When the YAZ client has read options and connected to a target, if given,
 121     it will display <literal>Z&gt;</literal> and await your command.
 122     Commands are executed by hitting the return key.
 123     You can always issue the command <literal>?</literal> to see the list
 124     of available commands.
 125     </para>
 126    <para>
 127     The commands are (the letters in parenthesis are short
 128     names for the commands):
 129    </para>
 130    <variablelist>
 131     <varlistentry><term>
 132       <literal>open </literal><replaceable>zurl</replaceable>
 133      </term>
 134      <listitem>
 135       <para>Opens a connection to a server. The syntax for
 136        <replaceable>zurl</replaceable> is the same as described
 137        above for connecting from the command line.
 138       </para>
 139       <para>
 140        Syntax:
 141       </para>
 142       <para>
 143        [<literal>(tcp|ssl)':'</literal>]<replaceable>host</replaceable>
 144        [:<replaceable>port</replaceable>][/<replaceable>base&gt;</replaceable>]
 145       </para>
 146      </listitem>
 147     </varlistentry>
 148     <varlistentry><term>
 149       <literal>quit</literal>
 150      </term>
 151      <listitem>
 152       <para>Ends YAZ client</para>
 153      </listitem>
 154     </varlistentry>
 155     <varlistentry><term>
 156       <literal>f </literal><replaceable>query</replaceable></term>
 157      <listitem>
 158       <para>Sends a Search Request using the <replaceable>query</replaceable>
 159        given.
 160       </para>
 161      </listitem>
 162     </varlistentry>
 163     <varlistentry><term>
 164       <literal>delete</literal> <replaceable>setname</replaceable></term>
 165      <listitem>
 166       <para>Deletes result set with name <replaceable>setname</replaceable>
 167        on the server.</para>
 168      </listitem>
 169     </varlistentry>
 170     <varlistentry><term>
 171       <literal>base </literal><replaceable>base1</replaceable>
 172       <replaceable>base2</replaceable> ...
 173       </term>
 174      <listitem>
 175       <para>Sets the name(s) of the database(s) to search. One or more
 176        databases may be specified separated by blanks. This commands overrides
 177        the database given in <replaceable>zurl</replaceable>.
 178        </para>
 179      </listitem>
 180     </varlistentry>
 181     <varlistentry><term>
 182       <literal>show </literal>
 183       [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
 184       </term>
 185      <term><literal>s</literal></term>
 186      <listitem>
 187       <para>Fetches records by sending a Present Request from the start
 188        position given by
 189        <replaceable>start</replaceable>
 190        a number of records given by <replaceable>number</replaceable>. If
 191        <replaceable>start</replaceable> is not given, then the client
 192        will fetch from position of the last retrieved record plus 1. If
 193        <replaceable>number</replaceable> is not given, then one record will
 194        be fetched at a time.
 195       </para>
 196       </listitem>
 197     </varlistentry>
 198     <varlistentry><term>
 199       <literal>scan</literal> <replaceable>term</replaceable>
 200      </term>
 201      <listitem>
 202       <simpara>Scans
 203        database index for a term. The syntax resembles the syntax
 204        for <literal>find</literal>.
 205        If you want to scan for the word <literal>water</literal> you could
 206        write
 207        </simpara>
 208       <screen>
 209        scan water
 210       </screen>
 211       <simpara>
 212        but if you want to scan only in, say the title field, you would write
 213        </simpara>
 214       <screen>
 215        scan @attr 1=4 water
 216       </screen>
 217      </listitem>
 218     </varlistentry>
 219     <varlistentry id="sortspec"><term>
 220       <literal>sort</literal> <replaceable>sortspecs</replaceable>
 221      </term>
 222      <listitem>
 223       <para>Sorts a result set. The sort command takes a
 224        sequence of sort specifications. A sort
 225        specification holds a field (sort criteria) and is followed by flags.
 226        If the sort criteria includes <literal>=</literal> it is assumed
 227        that the sort SortKey is of type sortAttributes using Bib-1.
 228        The integer before <literal>=</literal> is
 229        the attribute type and the integer following <literal>=</literal>
 230        is the attribute value.
 231        If no <literal>=</literal> is in the SortKey it is treated as a
 232        sortfield-type of type InternationalString.
 233        Flags observed are: <literal>s</literal>
 234        for case sensitive, <literal>i</literal> for case insensitive,
 235        <literal>&lt;</literal> for sort ascending and <literal>&gt;</literal>
 236        for sort descending.
 237       </para>
 238      </listitem>
 239     </varlistentry>
 240     <varlistentry><term>
 241       <literal>sort+</literal>
 242      </term>
 243      <listitem>
 244       <para>Same as <literal>sort</literal> but stores the sorted
 245        result set in a new result set.
 246       </para>
 247      </listitem>
 248     </varlistentry>
 249     <varlistentry><term>
 250       <literal>authentication</literal> <replaceable>openauth</replaceable>
 251       </term>
 252      <listitem>
 253       <para>Sets up a authentication string if a server requires
 254        authentication (v2 OpenStyle). The authentication string is first
 255        sent to the server when the <literal>open</literal> command is
 256        issued and the Z39.50 Initialize Request is sent, so this command
 257        must be used before <literal>open</literal> in order to be effective.
 258        A common convention for the <replaceable>authopen</replaceable> string
 259        is that the username - and password is separated by a slash, e.g.
 260        <literal>myusername/mysecret</literal>.
 261       </para>
 262      </listitem>
 263     </varlistentry>
 264     <varlistentry><term>
 265       <literal>lslb</literal> <replaceable>n</replaceable>
 266      </term>
 267      <listitem>
 268       <para>Sets the limit for when no records should be returned
 269        together with the search result.
 270        See the
 271        <ulink
 272         url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 273         Z39.50 standard
 274        </ulink>
 275        for more details.
 276       </para>
 277      </listitem>
 278     </varlistentry>
 279
 280     <varlistentry><term>
 281       <literal>ssub</literal> <replaceable>n</replaceable>
 282      </term>
 283      <listitem>
 284       <para>Sets the limit for when all records should be returned with
 285        the search result.
 286        See the
 287        <ulink
 288         url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 289         Z39.50 standard
 290        </ulink> for more details.
 291       </para>
 292      </listitem>
 293     </varlistentry>
 294
 295     <varlistentry><term>
 296       <literal>mspn</literal> <replaceable>n</replaceable>
 297      </term>
 298      <listitem>
 299       <para>Sets the number of records should be returned if the
 300        number of records in the result set is between the values of
 301        <literal>lslb</literal> and <literal>ssub</literal>.
 302        See the
 303        <ulink
 304         url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
 305         Z39.50 standard
 306        </ulink>
 307        for more details.
 308       </para>
 309      </listitem>
 310     </varlistentry>
 311     <varlistentry><term>
 312       <literal>status</literal>
 313      </term>
 314      <listitem>
 315       <para>Displays the values of <literal>lslb</literal>,
 316        <literal>ssub</literal> and <literal>mspn</literal>.
 317       </para>
 318      </listitem>
 319     </varlistentry>
 320     <varlistentry><term>
 321       <literal>setname</literal>
 322      </term>
 323      <listitem>
 324       <para>Switches named result sets on and off. Default is on.
 325       </para>
 326      </listitem>
 327     </varlistentry>
 328     <varlistentry><term>
 329       <literal>cancel</literal>
 330      </term>
 331      <listitem>
 332       <para>Sends a Trigger Resource Control Request to the target.
 333       </para>
 334      </listitem>
 335     </varlistentry>
 336     <varlistentry><term>
 337       <literal>format</literal> <replaceable>oid</replaceable>
 338      </term>
 339      <listitem>
 340       <para>Sets the preferred transfer syntax for retrieved records.
 341        yaz-client supports all the record syntaxes that currently
 342        are registered. See
 343        <ulink
 344         url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
 345         Z39.50 Standard
 346        </ulink>
 347        for more details. Commonly used records syntaxes include usmarc,
 348        sutrs, grs1 and xml.
 349       </para>
 350      </listitem>
 351     </varlistentry>
 352     <varlistentry><term>
 353       <literal>elements</literal> <replaceable>e</replaceable>
 354      </term>
 355      <listitem>
 356       <para>Sets the element set name for the records. Many targets support
 357        element sets are B (for brief) and F (for full).
 358       </para>
 359      </listitem>
 360     </varlistentry>
 361     <varlistentry><term>
 362       <literal>close</literal>
 363      </term>
 364      <listitem>
 365       <para>Sends a Z39.50 Close APDU and closes connection with the peer
 366       </para>
 367      </listitem>
 368     </varlistentry>
 369     <varlistentry><term>
 370       <literal>querytype</literal> <replaceable>type</replaceable>
 371      </term>
 372      <listitem>
 373       <para>Sets the query type as used by command <literal>find</literal>.
 374        The following is supported: <literal>prefix</literal> for
 375        <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
 376        <literal>ccl</literal> for CCL search (Type-2
 377        Query) or <literal>ccl2rpn</literal> for
 378        <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
 379       </para>
 380      </listitem>
 381     </varlistentry>
 382     <varlistentry><term>
 383       <literal>attributeset</literal> <replaceable>set</replaceable>
 384      </term>
 385      <listitem>
 386       <para>
 387        Sets attribute set OID for prefix queries (RPN, Type-1).
 388       </para>
 389      </listitem>
 390     </varlistentry>
 391     <varlistentry><term>
 392       <literal>refid</literal> <replaceable>id</replaceable>
 393       </term>
 394      <listitem>
 395       <para>Sets reference ID for Z39.50 Request(s).
 396       </para>
 397      </listitem>
 398     </varlistentry>
 399     <varlistentry><term>
 400      <literal>itemorder</literal>
 401       <replaceable>type</replaceable> <replaceable>no</replaceable>
 402      </term>
 403      <listitem>
 404       <para>Sends an Item Order Request using the ILL External.
 405        <replaceable>type</replaceable> is either 1 or 2 which corresponds to
 406        ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
 407        is the Result Set position of the record to be ordered.
 408       </para>
 409      </listitem>
 410     </varlistentry>
 411     <varlistentry><term>
 412       <literal>update</literal>
 413      </term>
 414      <listitem>
 415       <para>Sends Item Update Request. This command sends a "minimal"
 416        PDU Update to the target supplying the last received record from
 417        the target.
 418        If no record has been received from the target this command is ignored
 419        and nothing is sent to the target.
 420       </para>
 421      </listitem>
 422     </varlistentry>
 423
 424     <varlistentry><term>
 425       <literal>.</literal>
 426       <replaceable>filename</replaceable>
 427      </term>
 428      <listitem>
 429       <para>Executes list of commands from
 430        file <replaceable>filename</replaceable>, just like source on
 431        most UNIX shells.
 432       </para>
 433      </listitem>
 434     </varlistentry>
 435
 436     <varlistentry><term>
 437       <literal>!</literal>
 438       <replaceable>args</replaceable>
 439      </term>
 440      <listitem>
 441       <para>Executes command <replaceable>args</replaceable> in subshell
 442        using the <literal>system</literal> call.
 443       </para>
 444      </listitem>
 445     </varlistentry>
 446
 447     <varlistentry><term>
 448       <literal>push_commande</literal>
 449       <replaceable>command</replaceable>
 450      </term>
 451      <listitem>
 452       <para>The push_command takes another command as its argument.
 453        That command is then added to the history information (so
 454        you can retrieve it later). The command itself is not
 455        executed. This command only works if you have GNU readline/history
 456        enabled.
 457       </para>
 458      </listitem>
 459     </varlistentry>
 460
 461     <varlistentry><term>
 462       <literal>set_apdufile</literal>
 463       <replaceable>filename</replaceable>
 464      </term>
 465      <listitem>
 466       <para>Sets that APDU should be logged to file
 467        <replaceable>filename</replaceable>. This command does the
 468        thing as option <literal>-a</literal>.
 469       </para>
 470      </listitem>
 471     </varlistentry>
 472
 473     <varlistentry><term>
 474       <literal>set_marcdump</literal>
 475       <replaceable>filename</replaceable>
 476      </term>
 477      <listitem>
 478       <para>Specifies that all retrieved records should be appended ot
 479        file <replaceable>filename</replaceable>. This command does the
 480        thing as option <literal>-m</literal>.
 481       </para>
 482      </listitem>
 483     </varlistentry>
 484
 485     <varlistentry><term>
 486       <literal>set_cclfields</literal>
 487       <replaceable>filename</replaceable>
 488      </term>
 489      <listitem>
 490       <para>Specifies that CCL fields should be read from file
 491        file <replaceable>filename</replaceable>. This command does the
 492        thing as option <literal>-c</literal>.
 493       </para>
 494      </listitem>
 495     </varlistentry>
 496
 497     <varlistentry><term>
 498       <literal>register_oid</literal>
 499       <replaceable>name</replaceable>
 500       <replaceable>class</replaceable>
 501       <replaceable>OID</replaceable>
 502      </term>
 503      <listitem>
 504       <para>This command allows you to register your own object
 505        identifier - so that instead of entering a long dot-notation
 506        you can use a short name instead.
 507        The <replaceable>name</replaceable> is your
 508        name for the OID, <replaceable>class</replaceable> is the
 509        class, and <replaceable>OID</replaceable> is the raw OID in
 510        dot notation. Class is one <literal>appctx</literal>,
 511        <literal>absyn</literal>, <literal>attet</literal>,
 512        <literal>transyn</literal>, <literal>diagset</literal>,
 513        <literal>recsyn</literal>, <literal>resform</literal>,
 514        <literal>accform</literal>, <literal>extserv</literal>,
 515        <literal>userinfo</literal>, <literal>elemspec</literal>,
 516        <literal>varset</literal>, <literal>schema</literal>,
 517        <literal>tagset</literal>, <literal>general</literal>.
 518        If you're in doubt use the <literal>general</literal>
 519         class.
 520       </para>
 521      </listitem>
 522     </varlistentry>
 523
 524    </variablelist>
 525   </sect1>
 526   <sect1 id="client.searching"><title>Searching</title>
 527    <para>
 528     The simplest example of a Prefix Query would be something like
 529     <screen>
 530      f knuth
 531     </screen>
 532     or
 533     <screen>
 534      f "donald knuth"
 535     </screen>
 536     In those queries no attributes was specified.
 537     This leaves it up to the server what fields to search but
 538     most servers will search in all fields. Some servers does not
 539     support this feature though, and require that some attributes
 540     are defined. To add one attribute you could do:
 541     <screen>
 542      f @attr 1=4 computer
 543     </screen>
 544     where we search in the title field, since the use(1) is title(4).
 545     If we want to search in the author field <emphasis>and</emphasis>
 546     in the title field, and in the title field using right truncation
 547     it could look something like this:
 548     <screen>
 549      f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
 550     </screen>
 551     Finally using a mix of Bib-1 and GILS attributes could look
 552     something like this:
 553     <screen>
 554      f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
 555     </screen>
 556     For the full specification of the Prefix Query see the section
 557      <link linkend="PQF">Prefix Query Format</link>.
 558    </para>
 559   </sect1>
 560  </chapter>
 561
 562  <!-- Keep this comment at the end of the file
 563  Local variables:
 564  mode: sgml
 565  sgml-omittag:t
 566  sgml-shorttag:t
 567  sgml-minimize-attributes:nil
 568  sgml-always-quote-attributes:t
 569  sgml-indent-step:1
 570  sgml-indent-data:t
 571  sgml-parent-document: "yaz.xml"
 572  sgml-local-catalogs: nil
 573  sgml-namecase-general:t
 574  End:
 575  -->