2 $Id: yaz-client-commands.xml,v 1.19 2007-05-30 08:40:26 adam Exp $
3 Commands for YAZ client.
4 Included in both manual and man page for yaz-client.
7 <varlistentry id="command-open"><term>
8 <literal>open </literal><replaceable>zurl</replaceable>
11 <para>Opens a connection to a server. The syntax for
12 <replaceable>zurl</replaceable> is the same as described
13 above for connecting from the command line.
19 [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
20 [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
25 <literal>quit</literal>
28 <para>Quits YAZ client</para>
31 <varlistentry id="command-find"><term>
32 <literal>find </literal><replaceable>query</replaceable></term>
34 <para>Sends a Search Request using the <replaceable>query</replaceable>
35 given. By default the query is assumed to be PQF. See command
36 <link linkend="command-querytype"><literal>querytype</literal></link>.
41 <literal>delete</literal> <replaceable>setname</replaceable></term>
43 <para>Deletes result set with name <replaceable>setname</replaceable>
48 <literal>base </literal><replaceable>base1</replaceable>
49 <replaceable>base2</replaceable> ...
52 <para>Sets the name(s) of the database(s) to search. One or more
53 databases may be specified separated by blanks. This commands overrides
54 the database given in <replaceable>zurl</replaceable>.
59 <literal>show </literal>
60 [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
63 <para>Fetches records by sending a Present Request from the start
65 <replaceable>start</replaceable>
66 a number of records given by <replaceable>number</replaceable>. If
67 <replaceable>start</replaceable> is not given, then the client
68 will fetch from position of the last retrieved record plus 1. If
69 <replaceable>number</replaceable> is not given, then one record will
75 <literal>scan</literal> <replaceable>term</replaceable>
79 database index for a term. The syntax resembles the syntax
80 for <link linkend="command-find"><literal>find</literal></link>.
81 If you want to scan for the word <literal>water</literal> you could
88 but if you want to scan only in, say the title field, you would write
96 <literal>setscan</literal> <replaceable>set</replaceable> <replaceable>term</replaceable>
99 <simpara>Scans database index for a term within a result set. This
100 is similar to the scan command but has a result set as its first argument.
105 <literal>scanpos</literal> <replaceable>pos</replaceable>
109 Sets preferred position for scan. This value
110 is used in next scan. By default position is 1.
115 <literal>scansize</literal> <replaceable>size</replaceable>
119 Sets number of entries to be returned by scan. Default
120 number of entries is 20.
125 <literal>scanstep</literal> <replaceable>step</replaceable>
129 Set step-size for scan. This value is used in next scan
130 sent to the target. By default step-size is 0.
134 <varlistentry id="sortspec"><term>
135 <literal>sort</literal> <replaceable>sortspecs</replaceable>
138 <para>Sorts a result set. The sort command takes a
139 sequence of space-separated sort specifications, with each sort
140 specification consisting of two space-separated words (so that the
141 whole specification list is made up of an even number of words).
142 The first word of each specification
143 holds a field (sort criterion) and the second holds flags.
144 If the sort criterion includes <literal>=</literal> it is assumed
145 that the <literal>SortKey</literal> is of type
146 <literal>sortAttributes</literal> using Bib-1: in this case
147 the integer before <literal>=</literal> is
148 the attribute type and the integer following <literal>=</literal>
149 is the attribute value.
150 If no <literal>=</literal> is in the criterion it is treated as a
151 sortfield of type InternationalString.
152 The flags word of each sort specification must consist of
154 for case sensitive or <literal>i</literal> for case insensitive, and
155 <literal><</literal> for ascending order or <literal>></literal>
156 for descending order.
161 <literal>sort+</literal>
164 <para>Same as <literal>sort</literal> but stores the sorted
165 result set in a new result set.
170 <literal>authentication</literal> <replaceable>openauth</replaceable>
173 <para>Sets up a authentication string if a server requires
174 authentication (v2 OpenStyle). The authentication string is first
175 sent to the server when the
176 <link linkend="command-open"><literal>open</literal></link> command is
177 issued and the Z39.50 Initialize Request is sent, so this command
178 must be used before <literal>open</literal> in order to be effective.
179 A common convention for the <replaceable>authopen</replaceable> string
180 is that the username - and password is separated by a slash, e.g.
181 <literal>myusername/mysecret</literal>.
187 <literal>sru</literal> <replaceable>method</replaceable>
190 <para>Selects SRU method. Must be one of <literal>POST</literal>,
191 <literal>GET</literal>, <literal>SOAP</literal> (default).
197 <literal>list_all</literal>
200 <para>This command displays status and values for many settings.
206 <literal>lslb</literal> <replaceable>n</replaceable>
209 <para>Sets the limit for when no records should be returned
210 together with the search result.
213 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
222 <literal>ssub</literal> <replaceable>n</replaceable>
225 <para>Sets the limit for when all records should be returned with
229 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
231 </ulink> for more details.
237 <literal>mspn</literal> <replaceable>n</replaceable>
240 <para>Sets the number of records should be returned if the
241 number of records in the result set is between the values of
242 <literal>lslb</literal> and <literal>ssub</literal>.
245 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
253 <literal>status</literal>
256 <para>Displays the values of <literal>lslb</literal>,
257 <literal>ssub</literal> and <literal>mspn</literal>.
262 <literal>setname</literal>
265 <para>Switches named result sets on and off. Default is on.
270 <literal>cancel</literal>
273 <para>Sends a Trigger Resource Control Request to the target.
278 <literal>format</literal> <replaceable>oid</replaceable>
281 <para>Sets the preferred transfer syntax for retrieved records.
282 yaz-client supports all the record syntaxes that currently
285 url="http://www.loc.gov/z3950/agency/defns/oids.html#5">
288 for more details. Commonly used records syntaxes include usmarc,
294 <literal>elements</literal> <replaceable>e</replaceable>
297 <para>Sets the element set name for the records. Many targets support
298 element sets are B (for brief) and F (for full).
303 <literal>close</literal>
306 <para>Sends a Z39.50 Close APDU and closes connection with the peer
310 <varlistentry id="command-querytype"><term>
311 <literal>querytype</literal> <replaceable>type</replaceable>
314 <para>Sets the query type as used by command
315 <link linkend="command-find"><literal>find</literal></link>.
316 The following is supported:
317 <literal>prefix</literal> for
318 <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
319 <literal>ccl</literal> for CCL search (Type-2 Query),
320 <literal>cql</literal> for CQL (Type-104 search with CQL OID),
321 <literal>ccl2rpn</literal> for
322 <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
323 <literal>cql2rpn</literal> for
324 CQL to RPN conversion (Type-1 Query).
329 <literal>attributeset</literal> <replaceable>set</replaceable>
333 Sets attribute set OID for prefix queries (RPN, Type-1).
338 <literal>refid</literal> <replaceable>id</replaceable>
341 <para>Sets reference ID for Z39.50 Request(s).
346 <literal>itemorder</literal>
347 <replaceable>type</replaceable> <replaceable>no</replaceable>
350 <para>Sends an Item Order Request using the ILL External.
351 <replaceable>type</replaceable> is either 1 or 2 which corresponds to
352 ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
353 is the Result Set position of the record to be ordered.
358 <literal>update</literal>
359 <replaceable>action</replaceable>
360 <replaceable>recid</replaceable>
361 <replaceable>doc</replaceable>
364 <para>Sends Item Update Request. The <replaceable>action</replaceable>
365 argument must be the action type: one of <literal>insert</literal>,
366 <literal>replace</literal>, <literal>delete</literal> and
367 <literal>update</literal>. The second argument,
368 <replaceable>recid</replaceable>, is the
369 record identifier (any string). Third argument which is optional is
370 the record document for the request. If doc is a quoted string
371 (double quotes) the string content is used verbatim. If doc is not
372 a quoted string, it is assumed to be a filename which is read, then
373 sent as the docuemnt content. If doc is omitted, the last received
374 record (as parf of present response or piggybacked search response)
375 is used for the update.
381 <literal>source</literal>
382 <replaceable>filename</replaceable>
385 <para>Executes list of commands from
386 file <replaceable>filename</replaceable>, just like source on
387 most UNIX shells. A single dot (<literal>.</literal>) can be used
395 <replaceable>args</replaceable>
398 <para>Executes command <replaceable>args</replaceable> in subshell
399 using the <literal>system</literal> call.
405 <literal>push_command</literal>
406 <replaceable>command</replaceable>
409 <para>The push_command takes another command as its argument.
410 That command is then added to the history information (so
411 you can retrieve it later). The command itself is not
412 executed. This command only works if you have GNU readline/history
419 <literal>set_apdufile</literal>
420 <replaceable>filename</replaceable>
423 <para>Sets that APDU should be logged to file
424 <replaceable>filename</replaceable>. Another way to achieve
425 APDU log is by using command-line option <literal>-a</literal>.
431 <literal>set_auto_reconnect</literal>
432 <replaceable>flag</replaceable>
435 <para>Specifies whether YAZ client automatically reconnect if
436 target closes connection (Z39.50 only).
439 <replaceable>flag</replaceable> must be either
440 <literal>on</literal> or <literal>off</literal>.
445 <varlistentry id="command-set-auto-wait"><term>
446 <literal>set_auto_wait</literal>
447 <replaceable>flag</replaceable>
450 <para>Specifies whether YAZ client should wait for
451 response protocol packages after a request.
452 By default YAZ client waits (on) for response packages immediately
453 after a command (find, show) has been issued. If <literal>off</literal>
454 is used, YAZ client does not attempt to receive packages automatically.
455 These will have to be manually received when command
456 <link linkend="command-wait-response">
457 <literal>wait_response</literal>
461 <replaceable>flag</replaceable> must be either
462 <literal>on</literal> or <literal>off</literal>.
468 <literal>set_marcdump</literal>
469 <replaceable>filename</replaceable>
472 <para>Specifies that all retrieved records should be appended to
473 file <replaceable>filename</replaceable>. This command does the
474 thing as option <literal>-m</literal>.
480 <literal>schema</literal>
481 <replaceable>schemaid</replaceable>
484 <para>Specifies schema for retrieval.
485 Schema may be specified as an OID for Z39.50.
486 For SRU, schema is a simple string URI.
491 <varlistentry id="command-charset"><term>
492 <literal>charset</literal>
493 <replaceable>negotiationcharset</replaceable>
494 [<replaceable>displaycharset</replaceable>]
495 [[<replaceable>marccharset</replaceable>]]
498 <para>Specifies character set (encoding) for Z39.50
499 negotiation / SRU encoding and/or character set for output (terminal).
502 <replaceable>negotiationcharset</replaceable> is the name
503 of the character set to be negotiated by the server. The special name
504 <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
505 specifies <emphasis>no</emphasis> character set to be negotiated.
508 If <replaceable>displaycharset</replaceable> is given, it specifies name
509 of the character set of the output (on the terminal on which
510 YAZ client is running). To disable conversion of characters
511 to the output encoding, the special name <literal>-</literal> (dash)
513 If the special name <literal>auto</literal> is given, YAZ client will
514 convert strings to the encoding of the
515 terminal as returned by <function>nl_langinfo</function> call.
518 If <replaceable>marcharset</replaceable> is given, it specifies name
519 of the character set of retrieved MARC records from server. See
520 also <literal>marcharset</literal> command.
524 Since character set negotation takes effect in the Z39.50
525 Initialize Request you should issue this command before
526 command <link linkend="command-open"><literal>open</literal></link>
532 MARC records are not covered by Z39.50 character set negotiation,
533 so that's why there is a separate character that must be known
534 in order to do meaningful converson(s).
541 <literal>negcharset</literal>
542 <replaceable>charset</replaceable>
545 <para>Specifies character set for negotiation (Z39.50). The
546 argument is the same as second argument for command
547 <link linkend="command-charset"><literal>charset</literal></link>.
553 <literal>displaycharset</literal>
554 <replaceable>charset</replaceable>
557 <para>Specifies character set for output (display). The
558 argument is the same as second argument for command
559 <link linkend="command-charset"><literal>charset</literal></link>.
565 <literal>marccharset</literal>
566 <replaceable>charset</replaceable>
569 <para>Specifies character set for retrieved MARC records so
570 that YAZ client can display them in a character suitable
571 for your display. See <literal>charset</literal> command.
572 If <literal>auto</literal> is given, YAZ will assume
573 that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
574 for all other MARC variants. The charset argument is the
575 same as third argument for command
576 <link linkend="command-charset"><literal>charset</literal></link>.
582 <literal>querycharset</literal>
583 <replaceable>charset</replaceable>
586 <para>Specifies character set for query terms for Z39.50 RPN
587 queries and Z39.50 Scan Requests (termListAndStartPoint).
588 This is a pure client-side conversion which converts from
589 displayCharset to queryCharset.
595 <literal>set_cclfile</literal>
596 <replaceable>filename</replaceable>
599 <para>Specifies that CCL fields should be read from file
600 file <replaceable>filename</replaceable>. This command does the
601 thing as option <literal>-c</literal>.
607 <literal>set_cqlfile</literal>
608 <replaceable>filename</replaceable>
611 <para>Specifies that CQL fields should be read from file
612 file <replaceable>filename</replaceable>. This command does the
613 thing as option <literal>-q</literal>.
619 <literal>register_oid</literal>
620 <replaceable>name</replaceable>
621 <replaceable>class</replaceable>
622 <replaceable>OID</replaceable>
625 <para>This command allows you to register your own object
626 identifier - so that instead of entering a long dot-notation
627 you can use a short name instead.
628 The <replaceable>name</replaceable> is your
629 name for the OID, <replaceable>class</replaceable> is the
630 class, and <replaceable>OID</replaceable> is the raw OID in
631 dot notation. Class is one <literal>appctx</literal>,
632 <literal>absyn</literal>, <literal>attet</literal>,
633 <literal>transyn</literal>, <literal>diagset</literal>,
634 <literal>recsyn</literal>, <literal>resform</literal>,
635 <literal>accform</literal>, <literal>extserv</literal>,
636 <literal>userinfo</literal>, <literal>elemspec</literal>,
637 <literal>varset</literal>, <literal>schema</literal>,
638 <literal>tagset</literal>, <literal>general</literal>.
639 If you're in doubt use the <literal>general</literal>
646 <literal>register_tab</literal>
647 <replaceable>command</replaceable>
648 <replaceable>string</replaceable>
651 <para>This command registers a TAB completion string for
658 <literal>sleep</literal>
659 <replaceable>seconds</replaceable>
662 <para>This command makes YAZ client sleep (be idle) for
663 the number of seconds given.
668 <varlistentry id="command-wait-response"><term>
669 <literal>wait_response</literal>
670 [ <replaceable>number</replaceable>]
673 <para>This command makes YAZ client wait for a number of
674 response packages from target. If <replaceable>number</replaceable> is
675 omitted, 1 is assumed.
677 <para>This command is rarely used and is only useful if command
678 <link linkend="command-set-auto-wait">
679 <literal>set_auto_wait</literal>
680 </link> is set to off.
685 <varlistentry id="command-xmles"><term>
686 <literal>xmles</literal>
687 <replaceable>OID</replaceable>
688 <replaceable>doc</replaceable>
691 <para>Sends XML Extended Services request using the OID and doc given.
697 <literal>zversion</literal>
698 <replaceable>ver</replaceable>
701 <para>This command sets Z39.50 version for negotiation.
702 Should be used before
703 <link linkend="command-open"><literal>open</literal></link>.
704 By default 3 (version 3) is used.
710 <literal>options</literal>
711 <replaceable>op1 op2..</replaceable>
714 <para>This command sets Z39.50 options for negotiation.
715 Should be used before
716 <link linkend="command-open"><literal>open</literal></link>.
719 The following options are supported:
720 <literal>search</literal>,
721 <literal>present</literal>,
722 <literal>delSet</literal>,
723 <literal>resourceReport</literal>,
724 <literal>triggerResourceCtrl</literal>,
725 <literal>resourceCtrl</literal>,
726 <literal>accessCtrl</literal>,
727 <literal>scan</literal>,
728 <literal>sort</literal>,
729 <literal>extendedServices</literal>,
730 <literal>level_1Segmentation</literal>,
731 <literal>level_2Segmentation</literal>,
732 <literal>concurrentOperations</literal>,
733 <literal>namedResultSets</literal>,
734 <literal>encapsulation</literal>,
735 <literal>resultCount</literal>,
736 <literal>negotiationModel</literal>,
737 <literal>duplicationDetection</literal>,
738 <literal>queryType104</literal>,
739 <literal>pQESCorrection</literal>,
740 <literal>stringSchema</literal>.
746 <!-- Keep this comment at the end of the file
751 sgml-minimize-attributes:nil
752 sgml-always-quote-attributes:t
755 sgml-parent-document: "yaz.xml"
756 sgml-local-catalogs: nil
757 sgml-namecase-general:t