-<!-- $Id: client.xml,v 1.1 2001-08-08 19:33:21 adam Exp $ -->
- <chapter><title>The YAZ client</title>
- <sect1><title>Introduction</title>
+<!-- $Id: client.xml,v 1.13 2002-08-17 07:55:51 adam Exp $ -->
+ <chapter id="client"><title>The YAZ client</title>
+ <sect1 id="client.introduction"><title>Introduction</title>
<para>
- yaz-client is a linemode Z39.50 client. It supports a fair amount
- of the functionality of the Z39.50-1995 standard, but some things you
- need to enable or disable by recompilation.
- Its primary purpose is to exercise the
- package, and verify that the protocol works OK.
+ yaz-client is a line-mode Z39.50 client. It supports a fair amount
+ of the functionality of the Z39.50-1995 standard
+ Its primary purpose is to exercise the package, and verify that
+ the protocol works OK.
For the same reason some commands offers more functionality than others.
- Commands that exercies common Z39.50 services such as search and present
+ Commands that exercises common Z39.50 services such as search and present
have more features than less common supported services, such as Extended
Services (ItemOrder, ItemUpdate,..).
</para>
</sect1>
- <sect1><title>Invoking the YAZ client</title>
+ <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
<para>
It can be started by typing
</para>
- <screen>
- yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
- </screen>
+ <cmdsynopsis>
+ <command>yaz-client</command>
+ <arg>-m <replaceable>fname</replaceable></arg>
+ <arg>-a <replaceable>fname</replaceable></arg>
+ <arg>-c <replaceable>fname</replaceable></arg>
+ <arg>-v <replaceable>level</replaceable></arg>
+ <arg>-p <replaceable>target</replaceable></arg>
+ <arg>-u <replaceable>auth</replaceable></arg>
+ <arg>-k <replaceable>size</replaceable></arg>
+ <arg>zurl</arg>
+ </cmdsynopsis>
+
<simpara>
in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
specifies a Z39.50 host and, if specified, the client first tries to
establish connection with the Z39.50 target on the host.
- Options are, as usual, are prefixed by <literal>-</literal> followed
- by a particular letter.
+ Options are prefixed by <literal>-</literal> followed by a
+ particular letter.
</simpara>
<simpara>
The following options are supported:
<varlistentry><term>
<literal>-m</literal> <replaceable>fname</replaceable>
</term><listitem>
- <simpara>ISO2709 records are appended to file
- <replaceable>fname</replaceable>. All records as returned by a target(s)
- in Search Responses and Present Responses are appended verbatim to
- the file.
+ <simpara>All retrieved transfer records are appended to file
+ <replaceable>fname</replaceable>. All records as returned by a
+ target(s) in Search Responses and Present Responses are appended
+ verbatim to the file.
</simpara></listitem>
</varlistentry>
<varlistentry><term>
<literal>-v</literal> <replaceable>level</replaceable>
</term><listitem>
<simpara>Sets the LOG level to <replaceable>level</replaceable>.
- Level is a sequence of tokens separated by comman. Each token
+ Level is a sequence of tokens separated by comma. Each token
is a integer or a named LOG item - one of
<literal>fatal</literal>,
<literal>debug</literal>,
<literal>warn</literal>,
<literal>log</literal>,
+ <literal>malloc</literal>,
<literal>all</literal>,
<literal>none</literal>.
</simpara></listitem>
</varlistentry>
+ <varlistentry><term>
+ <literal>-p</literal> <replaceable>target</replaceable>
+ </term><listitem>
+ <simpara>Specifies proxy address. When set YAZ client will
+ connect to a proxy on the address and port given.
+ The actual target will be specified as part of the InitRequest
+ to inform the proxy about actual target.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry><term>
+ <literal>-u</literal> <replaceable>auth</replaceable>
+ </term><listitem>
+ <simpara>Specifies authentication. Usually the form
+ <replaceable>user</replaceable>/<replaceable>password</replaceable>
+ is used. This option does the same thing as the
+ <literal>auth</literal> command.
+ </simpara></listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>-k</literal> <replaceable>size</replaceable>
+ </term><listitem>
+ <simpara>Specifies the maximum messages size in kilobytes.
+ The default maximum messages for the YAZ client is 1024
+ (1 MB).
+ </simpara></listitem>
+ </varlistentry>
+
</variablelist>
<para>
In order to connect to Index Data's test Z39.50 server on
<screen>
yaz-client -a - localhost
</screen>
+ <para>
+ The following command connects to a local server via UNIX
+ socket <filename>/tmp/yaz</filename> and sets maximum message size to
+ 5 MB.
+ </para>
+ <screen>
+ yaz-client -k 5120 unix:/tmp/yaz
+ </screen>
</sect1>
- <sect1><title>YAZ client commands</title>
+ <sect1 id="client.commands"><title>Commands</title>
<para>
When the YAZ client has read options and connected to a target, if given,
- it will display <literal>Z ></literal> and away your command.
+ it will display <literal>Z></literal> and await your command.
Commands are executed by hitting the return key.
You can always issue the command <literal>?</literal> to see the list
of available commands.
<varlistentry><term>
<literal>open </literal><replaceable>zurl</replaceable>
</term>
- <term><literal>o</literal></term>
<listitem>
<para>Opens a connection to a server. The syntax for
<replaceable>zurl</replaceable> is the same as described
Syntax:
</para>
<para>
- [<literal>(tcp|osi)':'</literal><[<replaceable>tsel/</replaceable>]]<replaceable>host</replaceable>[:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
+ [<literal>(tcp|ssl|unix)':'</literal>]<replaceable>host</replaceable>
+ [:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
</para>
</listitem>
</varlistentry>
<varlistentry><term>
<literal>quit</literal>
</term>
- <term><literal>q</literal></term>
<listitem>
<para>Ends YAZ client</para>
</listitem>
</varlistentry>
<varlistentry><term>
<literal>f </literal><replaceable>query</replaceable></term>
- <term><literal>f</literal></term>
<listitem>
- <para>Sends Search Request using the <replaceable>query</replaceable>
+ <para>Sends a Search Request using the <replaceable>query</replaceable>
given.
</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry><term>
- <literal>show </literal> [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
+ <literal>show </literal>
+ [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
</term>
<term><literal>s</literal></term>
<listitem>
position given by
<replaceable>start</replaceable>
a number of records given by <replaceable>number</replaceable>. If
- <replaceable>start</replaceable> is not given the client will
- fetch from position of the last retrieved record plus 1. If
- <replaceable>number</replaceable> is not given one record will be
- fetched at a time.
+ <replaceable>start</replaceable> is not given, then the client
+ will fetch from position of the last retrieved record plus 1. If
+ <replaceable>number</replaceable> is not given, then one record will
+ be fetched at a time.
</para>
</listitem>
</varlistentry>
</screen>
</listitem>
</varlistentry>
- <varlistentry><term>
+ <varlistentry id="sortspec"><term>
<literal>sort</literal> <replaceable>sortspecs</replaceable>
</term>
<listitem>
- <para>Sorts a result set. The sort command takes a sequence of
- sort specifications. A sort
+ <para>Sorts a result set. The sort command takes a
+ sequence of sort specifications. A sort
specification holds a field (sort criteria) and is followed by flags.
If the sort criteria includes <literal>=</literal> it is assumed
that the sort SortKey is of type sortAttributes using Bib-1.
sent to the server when the <literal>open</literal> command is
issued and the Z39.50 Initialize Request is sent, so this command
must be used before <literal>open</literal> in order to be effective.
+ A common convention for the <replaceable>authopen</replaceable> string
+ is that the username - and password is separated by a slash, e.g.
+ <literal>myusername/mysecret</literal>.
</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>Sends an Item Order Request using the ILL External.
- <replaceable>type</replaceable> is either 1 or 2 which correponds to
+ <replaceable>type</replaceable> is either 1 or 2 which corresponds to
ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
is the Result Set position of the record to be ordered.
</para>
</term>
<listitem>
<para>Sends Item Update Request. This command sends a "minimal"
- PDU to the target supplying the last received record from the target.
+ PDU Update to the target supplying the last received record from
+ the target.
If no record has been received from the target this command is ignored
and nothing is sent to the target.
</para>
</listitem>
</varlistentry>
+
+ <varlistentry><term>
+ <literal>.</literal>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>Executes list of commands from
+ file <replaceable>filename</replaceable>, just like source on
+ most UNIX shells.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>!</literal>
+ <replaceable>args</replaceable>
+ </term>
+ <listitem>
+ <para>Executes command <replaceable>args</replaceable> in subshell
+ using the <literal>system</literal> call.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>push_commande</literal>
+ <replaceable>command</replaceable>
+ </term>
+ <listitem>
+ <para>The push_command takes another command as its argument.
+ That command is then added to the history information (so
+ you can retrieve it later). The command itself is not
+ executed. This command only works if you have GNU readline/history
+ enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>set_apdufile</literal>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>Sets that APDU should be logged to file
+ <replaceable>filename</replaceable>. This command does the
+ thing as option <literal>-a</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>set_marcdump</literal>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>Specifies that all retrieved records should be appended ot
+ file <replaceable>filename</replaceable>. This command does the
+ thing as option <literal>-m</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>set_cclfields</literal>
+ <replaceable>filename</replaceable>
+ </term>
+ <listitem>
+ <para>Specifies that CCL fields should be read from file
+ file <replaceable>filename</replaceable>. This command does the
+ thing as option <literal>-c</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>register_oid</literal>
+ <replaceable>name</replaceable>
+ <replaceable>class</replaceable>
+ <replaceable>OID</replaceable>
+ </term>
+ <listitem>
+ <para>This command allows you to register your own object
+ identifier - so that instead of entering a long dot-notation
+ you can use a short name instead.
+ The <replaceable>name</replaceable> is your
+ name for the OID, <replaceable>class</replaceable> is the
+ class, and <replaceable>OID</replaceable> is the raw OID in
+ dot notation. Class is one <literal>appctx</literal>,
+ <literal>absyn</literal>, <literal>attet</literal>,
+ <literal>transyn</literal>, <literal>diagset</literal>,
+ <literal>recsyn</literal>, <literal>resform</literal>,
+ <literal>accform</literal>, <literal>extserv</literal>,
+ <literal>userinfo</literal>, <literal>elemspec</literal>,
+ <literal>varset</literal>, <literal>schema</literal>,
+ <literal>tagset</literal>, <literal>general</literal>.
+ If you're in doubt use the <literal>general</literal>
+ class.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect1>
- <sect1><title>Searching</title>
+ <sect1 id="client.searching"><title>Searching</title>
<para>
The simplest example of a Prefix Query would be something like
<screen>
<screen>
f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
</screen>
- For the full specifiction of the Prefix Query see the section
+ For the full specification of the Prefix Query see the section
<link linkend="PQF">Prefix Query Format</link>.
</para>
</sect1>
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->