doc/client.xml

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