doc/client.xml

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