doc/client.xml

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