-<!-- $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.18 2006-04-25 11:25:08 marc 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/SRW client. It supports a fair amount
+ of the functionality of the Z39.50v3 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>-q <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.
+ specifies a Z39.50/SRW host and, if specified, the client first tries to
+ establish connection with the Z39.50/SRW target.
+ </simpara>
+ <simpara>
+ 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>
</simpara></listitem>
</varlistentry>
<varlistentry><term>
+ <literal>-q</literal> <replaceable>fname</replaceable>
+ </term><listitem>
+ <simpara>Sets the filename for CQL fields to
+ <replaceable>fname</replaceable>. If this option is not given the
+ YAZ client reads CQL fields from file
+ <literal>/usr/local/share/yaz/etc/pqf.properties</literal>.
+ </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 message size 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
<literal>bagel.indexdata.dk</literal>, port 210 and with the
- database name marc, one would have to type
+ database name <literal>marc</literal>, one could type
+ <screen>
+ yaz-client bagel.indexdata.dk:210/marc
+ </screen>
+ </para>
+ <para>
+ The same server is also a SOAP SRW service. Connect to it via HTTP
+ as follows:
+ <screen>
+ yaz-client http://bagel.indexdata.dk:210/marc
+ </screen>
</para>
- <screen>
- yaz-client bagel.indexdata.dk:210/marc
- </screen>
<para>
In order to enable APDU log and connect to localhost, port 210 (default)
and database Default (default) you'd write:
- </para>
+ <screen>
+ yaz-client -a - localhost
+ </screen>
+ </para>
+ <para>
+ The following command connects to a local server via UNIX
+ socket <filename>/tmp/yaz</filename> and sets maximum message size to
+ 5 MB.
<screen>
- yaz-client -a - localhost
- </screen>
+ yaz-client -k 5120 unix:/tmp/yaz
+ </screen>
+ </para>
</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.
The commands are (the letters in parenthesis are short
names for the commands):
</para>
- <variablelist>
- <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
- above for connecting from the command line.
- </para>
- <para>
- Syntax:
- </para>
- <para>
- [<literal>(tcp|osi)':'</literal><[<replaceable>tsel/</replaceable>]]<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>
- given.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>delete</literal> <replaceable>setname</replaceable></term>
- <listitem>
- <para>Deletes result set with name <replaceable>setname</replaceable>
- on the server.</para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>base </literal><replaceable>base1</replaceable>
- <replaceable>base2</replaceable> ...
- </term>
- <listitem>
- <para>Sets the name(s) of the database(s) to search. One or more
- databases may be specified separated by blanks. This commands overrides
- the database given in <replaceable>zurl</replaceable>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>show </literal> [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
- </term>
- <term><literal>s</literal></term>
- <listitem>
- <para>Fetches records by sending a Present Request from the start
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>scan</literal> <replaceable>term</replaceable>
- </term>
- <listitem>
- <simpara>Scans
- database index for a term. The syntax resembles the syntax
- for <literal>find</literal>.
- If you want to scan for the word <literal>water</literal> you could
- write
- </simpara>
- <screen>
- scan water
- </screen>
- <simpara>
- but if you want to scan only in, say the title field, you would write
- </simpara>
- <screen>
- scan @attr 1=4 water
- </screen>
- </listitem>
- </varlistentry>
- <varlistentry><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
- 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.
- The integer before <literal>=</literal> is
- the attribute type and the integer following <literal>=</literal>
- is the attribute value.
- If no <literal>=</literal> is in the SortKey it is treated as a
- sortfield-type of type InternationalString.
- Flags observed are: <literal>s</literal>
- for case sensitive, <literal>i</literal> for case insensitive,
- <literal><</literal> for sort ascending and <literal>></literal>
- for sort descending.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>sort+</literal>
- </term>
- <listitem>
- <para>Same as <literal>sort</literal> but stores the sorted
- result set in a new result set.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>authentication</literal> <replaceable>openauth</replaceable>
- </term>
- <listitem>
- <para>Sets up a authentication string if a server requires
- authentication (v2 OpenStyle). The authentication string is first
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>lslb</literal> <replaceable>n</replaceable>
- </term>
- <listitem>
- <para>Sets the limit for when no records should be returned
- together with the search result.
- See the
- <ulink
- url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
- Z39.50 standard
- </ulink>
- for more details.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>ssub</literal> <replaceable>n</replaceable>
- </term>
- <listitem>
- <para>Sets the limit for when all records should be returned with
- the search result.
- See the
- <ulink
- url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
- Z39.50 standard
- </ulink> for more details.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>
- <literal>mspn</literal> <replaceable>n</replaceable>
- </term>
- <listitem>
- <para>Sets the number of records should be returned if the
- number of records in the result set is between the values of
- <literal>lslb</literal> and <literal>ssub</literal>.
- See the
- <ulink
- url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
- Z39.50 standard
- </ulink>
- for more details.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>status</literal>
- </term>
- <listitem>
- <para>Displays the values of <literal>lslb</literal>,
- <literal>ssub</literal> and <literal>mspn</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>setname</literal>
- </term>
- <listitem>
- <para>Switches named result sets on and off. Default is on.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>cancel</literal>
- </term>
- <listitem>
- <para>Sends a Trigger Resource Control Request to the target.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>format</literal> <replaceable>oid</replaceable>
- </term>
- <listitem>
- <para>Sets the preferred transfer syntax for retrieved records.
- yaz-client supports all the record syntaxes that currently
- are registered. See
- <ulink
- url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
- Z39.50 Standard
- </ulink>
- for more details. Commonly used records syntaxes include usmarc,
- sutrs, grs1 and xml.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>elements</literal> <replaceable>e</replaceable>
- </term>
- <listitem>
- <para>Sets the element set name for the records. Many targets support
- element sets are B (for brief) and F (for full).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>close</literal>
- </term>
- <listitem>
- <para>Sends a Z39.50 Close APDU and closes connection with the peer
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>querytype</literal> <replaceable>type</replaceable>
- </term>
- <listitem>
- <para>Sets the query type as used by command <literal>find</literal>.
- The following is supported: <literal>prefix</literal> for
- <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
- <literal>ccl</literal> for CCL search (Type-2
- Query) or <literal>ccl2rpn</literal> for
- <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>attributeset</literal> <replaceable>set</replaceable>
- </term>
- <listitem>
- <para>
- Sets attribute set OID for prefix queries (RPN, Type-1).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>refid</literal> <replaceable>id</replaceable>
- </term>
- <listitem>
- <para>Sets reference ID for Z39.50 Request(s).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>itemorder</literal>
- <replaceable>type</replaceable> <replaceable>no</replaceable>
- </term>
- <listitem>
- <para>Sends an Item Order Request using the ILL External.
- <replaceable>type</replaceable> is either 1 or 2 which correponds to
- ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
- is the Result Set position of the record to be ordered.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>update</literal>
- </term>
- <listitem>
- <para>Sends Item Update Request. This command sends a "minimal"
- PDU 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>
- </variablelist>
+ &yaz-client-commands;
+
</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:
-->
projects / yaz-moved-to-github.git / blobdiff