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>
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,..).
16 <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
18 It can be started by typing
21 yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
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.
31 The following options are supported:
35 <literal>-m</literal> <replaceable>fname</replaceable>
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
44 <literal>-a</literal> <replaceable>fname</replaceable>
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>.
53 <literal>-c</literal> <replaceable>fname</replaceable>
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>.
61 <literal>-v</literal> <replaceable>level</replaceable>
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>.
76 <literal>-p</literal> <replaceable>target</replaceable>
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.
86 <literal>-u</literal> <replaceable>authentication</replaceable>
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.
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
102 yaz-client bagel.indexdata.dk:210/marc
105 In order to enable APDU log and connect to localhost, port 210 (default)
106 and database Default (default) you'd write:
109 yaz-client -a - localhost
112 <sect1 id="client.commands"><title>Commands</title>
114 When the YAZ client has read options and connected to a target, if given,
115 it will display <literal>Z ></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.
121 The commands are (the letters in parenthesis are short
122 names for the commands):
126 <literal>open </literal><replaceable>zurl</replaceable>
128 <term><literal>o</literal></term>
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.
138 [<literal>(tcp|ssl)':'</literal>]<replaceable>host</replaceable>
139 [:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
144 <literal>quit</literal>
146 <term><literal>q</literal></term>
148 <para>Ends YAZ client</para>
152 <literal>f </literal><replaceable>query</replaceable></term>
154 <para>Sends a Search Request using the <replaceable>query</replaceable>
160 <literal>delete</literal> <replaceable>setname</replaceable></term>
162 <para>Deletes result set with name <replaceable>setname</replaceable>
163 on the server.</para>
167 <literal>base </literal><replaceable>base1</replaceable>
168 <replaceable>base2</replaceable> ...
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>.
178 <literal>show </literal>
179 [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
181 <term><literal>s</literal></term>
183 <para>Fetches records by sending a Present Request from the start
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.
195 <literal>scan</literal> <replaceable>term</replaceable>
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
208 but if you want to scan only in, say the title field, you would write
215 <varlistentry id="sortspec"><term>
216 <literal>sort</literal> <replaceable>sortspecs</replaceable>
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><</literal> for sort ascending and <literal>></literal>
237 <literal>sort+</literal>
240 <para>Same as <literal>sort</literal> but stores the sorted
241 result set in a new result set.
246 <literal>authentication</literal> <replaceable>openauth</replaceable>
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>.
261 <literal>lslb</literal> <replaceable>n</replaceable>
264 <para>Sets the limit for when no records should be returned
265 together with the search result.
268 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
277 <literal>ssub</literal> <replaceable>n</replaceable>
280 <para>Sets the limit for when all records should be returned with
284 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
286 </ulink> for more details.
292 <literal>mspn</literal> <replaceable>n</replaceable>
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>.
300 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
308 <literal>status</literal>
311 <para>Displays the values of <literal>lslb</literal>,
312 <literal>ssub</literal> and <literal>mspn</literal>.
317 <literal>setname</literal>
320 <para>Switches named result sets on and off. Default is on.
325 <literal>cancel</literal>
328 <para>Sends a Trigger Resource Control Request to the target.
333 <literal>format</literal> <replaceable>oid</replaceable>
336 <para>Sets the preferred transfer syntax for retrieved records.
337 yaz-client supports all the record syntaxes that currently
340 url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
343 for more details. Commonly used records syntaxes include usmarc,
349 <literal>elements</literal> <replaceable>e</replaceable>
352 <para>Sets the element set name for the records. Many targets support
353 element sets are B (for brief) and F (for full).
358 <literal>close</literal>
361 <para>Sends a Z39.50 Close APDU and closes connection with the peer
366 <literal>querytype</literal> <replaceable>type</replaceable>
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).
379 <literal>attributeset</literal> <replaceable>set</replaceable>
383 Sets attribute set OID for prefix queries (RPN, Type-1).
388 <literal>refid</literal> <replaceable>id</replaceable>
391 <para>Sets reference ID for Z39.50 Request(s).
396 <literal>itemorder</literal>
397 <replaceable>type</replaceable> <replaceable>no</replaceable>
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.
408 <literal>update</literal>
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.
420 <sect1 id="client.searching"><title>Searching</title>
422 The simplest example of a Prefix Query would be something like
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:
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:
443 f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
445 Finally using a mix of Bib-1 and GILS attributes could look
448 f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
450 For the full specification of the Prefix Query see the section
451 <link linkend="PQF">Prefix Query Format</link>.
456 <!-- Keep this comment at the end of the file
461 sgml-minimize-attributes:nil
462 sgml-always-quote-attributes:t
465 sgml-parent-document: "yaz.xml"
466 sgml-local-catalogs: nil
467 sgml-namecase-general:t