Change "to" type for MARC-8 -> UTF-8 conversion from 16-bit unsigned
[yaz-moved-to-github.git] / doc / client.xml
1 <!-- $Id: client.xml,v 1.16 2003-05-23 00:24:04 mike 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/SRW client. It supports a fair amount
6     of the functionality of the Z39.50v3 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>-q <replaceable>fname</replaceable></arg>
25     <arg>-v <replaceable>level</replaceable></arg>
26     <arg>-p <replaceable>target</replaceable></arg>
27     <arg>-u <replaceable>auth</replaceable></arg>
28     <arg>-k <replaceable>size</replaceable></arg>
29     <arg>zurl</arg>
30    </cmdsynopsis>
31    
32    <simpara>
33     in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
34     specifies a Z39.50/SRW host and, if specified, the client first tries to
35     establish connection with the Z39.50/SRW target.
36    </simpara>
37    <simpara>
38     Options are prefixed by <literal>-</literal> followed by a
39     particular letter.
40     </simpara>
41    <simpara>
42     The following options are supported:
43    </simpara>
44    <variablelist>
45     <varlistentry><term>
46       <literal>-m</literal> <replaceable>fname</replaceable>
47      </term><listitem>
48       <simpara>All retrieved transfer records are appended to file
49        <replaceable>fname</replaceable>. All records as returned by a
50        target(s) in Search Responses and Present Responses are appended
51        verbatim to the file.
52       </simpara></listitem>
53     </varlistentry>
54     <varlistentry><term>
55       <literal>-a</literal> <replaceable>fname</replaceable>
56      </term><listitem>
57       <simpara>Pretty-print log of APDUs sent and received is appended
58        to the file <replaceable>fname</replaceable>.
59        If <replaceable>fname</replaceable> is <literal>-</literal> (minus)
60        the APDU log is written to <literal>stderr</literal>.
61       </simpara></listitem>
62     </varlistentry>
63     <varlistentry><term>
64       <literal>-c</literal> <replaceable>fname</replaceable>
65      </term><listitem>
66       <simpara>Sets the filename for CCL fields to
67        <replaceable>fname</replaceable>. If this option is not given the
68        YAZ client reads CCL fields from file <literal>default.bib</literal>.
69       </simpara></listitem>
70     </varlistentry>
71     <varlistentry><term>
72       <literal>-q</literal> <replaceable>fname</replaceable>
73      </term><listitem>
74       <simpara>Sets the filename for CQL fields to
75        <replaceable>fname</replaceable>. If this option is not given the
76        YAZ client reads CQL fields from file
77        <literal>/usr/local/share/yaz/etc/pqf.properties</literal>.
78       </simpara></listitem>
79     </varlistentry>
80     <varlistentry><term>
81       <literal>-v</literal> <replaceable>level</replaceable>
82      </term><listitem>
83       <simpara>Sets the LOG level to <replaceable>level</replaceable>.
84        Level is a sequence of tokens separated by comma. Each token
85        is a integer or a named LOG item - one of 
86        <literal>fatal</literal>,
87        <literal>debug</literal>,
88        <literal>warn</literal>,
89        <literal>log</literal>,
90        <literal>malloc</literal>,
91        <literal>all</literal>,
92        <literal>none</literal>.
93       </simpara></listitem>
94     </varlistentry>
95     <varlistentry><term>
96       <literal>-p</literal> <replaceable>target</replaceable>
97      </term><listitem>
98       <simpara>Specifies proxy address. When set YAZ client will
99        connect to a proxy on the address and port given. 
100        The actual target will be specified as part of the InitRequest
101        to inform the proxy about actual target.
102       </simpara></listitem>
103     </varlistentry>
104     <varlistentry><term>
105       <literal>-u</literal> <replaceable>auth</replaceable>
106      </term><listitem>
107       <simpara>Specifies authentication. Usually the form
108        <replaceable>user</replaceable>/<replaceable>password</replaceable>
109        is used. This option does the same thing as the
110        <literal>auth</literal> command.
111       </simpara></listitem>
112     </varlistentry>
113
114     <varlistentry><term>
115       <literal>-k</literal> <replaceable>size</replaceable>
116      </term><listitem>
117       <simpara>Specifies the maximum messages size in kilobytes.
118        The default maximum message size for the YAZ client is 1024
119        (1 MB).
120       </simpara></listitem>
121     </varlistentry>
122
123    </variablelist>
124    <para>
125     In order to connect to Index Data's test Z39.50 server on
126     <literal>bagel.indexdata.dk</literal>, port 210 and with the
127     database name <literal>marc</literal>, one could type
128     <screen>
129      yaz-client bagel.indexdata.dk:210/marc
130     </screen>
131    </para>
132    <para>
133     The same server is also a SOAP SRW service. Connect to it via HTTP
134     as follows:
135     <screen>
136      yaz-client http://bagel.indexdata.dk:210/marc
137     </screen>
138    </para>
139    <para>
140     In order to enable APDU log and connect to localhost, port 210 (default)
141     and database Default (default) you'd write:
142     <screen>
143      yaz-client -a - localhost
144     </screen>
145    </para> 
146    <para>
147     The following command connects to a local server via UNIX
148     socket <filename>/tmp/yaz</filename> and sets maximum message size to
149     5 MB.
150    <screen>
151     yaz-client -k 5120 unix:/tmp/yaz
152    </screen> 
153    </para>
154   </sect1>
155   <sect1 id="client.commands"><title>Commands</title>
156    <para>
157     When the YAZ client has read options and connected to a target, if given,
158     it will display <literal>Z&gt;</literal> and await your command.
159     Commands are executed by hitting the return key.
160     You can always issue the command <literal>?</literal> to see the list
161     of available commands.
162     </para>
163    <para>
164     The commands are (the letters in parenthesis are short
165     names for the commands):
166    </para>
167
168    &yaz-client-commands;
169
170   </sect1>
171   <sect1 id="client.searching"><title>Searching</title>
172    <para>
173     The simplest example of a Prefix Query would be something like
174     <screen>
175      f knuth
176     </screen>
177     or
178     <screen>
179      f "donald knuth"
180     </screen>
181     In those queries no attributes was specified.
182     This leaves it up to the server what fields to search but
183     most servers will search in all fields. Some servers does not
184     support this feature though, and require that some attributes
185     are defined. To add one attribute you could do:
186     <screen>
187      f @attr 1=4 computer
188     </screen>
189     where we search in the title field, since the use(1) is title(4).
190     If we want to search in the author field <emphasis>and</emphasis>
191     in the title field, and in the title field using right truncation
192     it could look something like this:
193     <screen>
194      f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
195     </screen>
196     Finally using a mix of Bib-1 and GILS attributes could look
197     something like this:
198     <screen>
199      f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
200     </screen>
201     For the full specification of the Prefix Query see the section
202      <link linkend="PQF">Prefix Query Format</link>.
203    </para>
204   </sect1>
205  </chapter>
206  
207  <!-- Keep this comment at the end of the file
208  Local variables:
209  mode: sgml
210  sgml-omittag:t
211  sgml-shorttag:t
212  sgml-minimize-attributes:nil
213  sgml-always-quote-attributes:t
214  sgml-indent-step:1
215  sgml-indent-data:t
216  sgml-parent-document: "yaz.xml"
217  sgml-local-catalogs: nil
218  sgml-namecase-general:t
219  End:
220  -->