Fixed bug #831: New yaz-client command: 'source'.
[yaz-moved-to-github.git] / doc / yaz-client-commands.xml
1 <!-- 
2    $Id: yaz-client-commands.xml,v 1.17 2007-01-24 09:54:04 adam Exp $
3    Commands for YAZ client.
4    Included in both manual and man page for yaz-client.
5 -->
6 <variablelist>
7  <varlistentry id="command-open"><term>
8    <literal>open </literal><replaceable>zurl</replaceable>
9   </term>
10   <listitem>
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.
14    </para>
15    <para>
16     Syntax:
17    </para>
18    <para>
19     [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
20     [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
21    </para>
22   </listitem>
23  </varlistentry>
24  <varlistentry><term>
25    <literal>quit</literal>
26   </term>
27   <listitem>
28    <para>Quits YAZ client</para>
29   </listitem>
30  </varlistentry>
31  <varlistentry id="command-find"><term>
32    <literal>find </literal><replaceable>query</replaceable></term>
33   <listitem>
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>.
37    </para>
38   </listitem>
39  </varlistentry>
40  <varlistentry><term>
41    <literal>delete</literal> <replaceable>setname</replaceable></term>
42   <listitem>
43    <para>Deletes result set with name <replaceable>setname</replaceable>
44     on the server.</para>
45   </listitem>
46  </varlistentry>
47  <varlistentry><term>
48    <literal>base </literal><replaceable>base1</replaceable>
49    <replaceable>base2</replaceable> ...
50   </term>
51   <listitem>
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>.
55    </para>
56   </listitem>
57  </varlistentry>
58  <varlistentry><term>
59    <literal>show </literal>
60    [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
61   </term>
62   <listitem>
63    <para>Fetches records by sending a Present Request from the start
64     position given by
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
70     be fetched at a time.
71    </para>
72   </listitem>
73  </varlistentry>
74  <varlistentry><term>
75    <literal>scan</literal> <replaceable>term</replaceable>
76   </term>
77   <listitem>
78    <simpara>Scans
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
82     write
83    </simpara>
84    <screen>
85     scan water
86    </screen>
87    <simpara>
88     but if you want to scan only in, say the title field, you would write
89    </simpara>
90    <screen>
91     scan @attr 1=4 water
92    </screen>
93   </listitem>
94  </varlistentry>
95  <varlistentry><term>
96    <literal>scanpos</literal> <replaceable>pos</replaceable>
97   </term>
98   <listitem>
99    <simpara>
100     Sets preferred position for scan. This value
101     is used in next scan. By default position is 1.
102    </simpara>
103   </listitem>
104  </varlistentry>
105  <varlistentry><term>
106    <literal>scansize</literal> <replaceable>size</replaceable>
107   </term>
108   <listitem>
109    <simpara>
110     Sets number of entries to be returned by scan. Default
111     number of entries is 20.
112    </simpara>
113   </listitem>
114  </varlistentry>
115  <varlistentry><term>
116    <literal>scanstep</literal> <replaceable>step</replaceable>
117   </term>
118   <listitem>
119    <simpara>
120     Set step-size for scan. This value is used in next scan
121     sent to the target. By default step-size is 0.
122    </simpara>
123   </listitem>
124  </varlistentry>
125  <varlistentry id="sortspec"><term>
126    <literal>sort</literal> <replaceable>sortspecs</replaceable>
127   </term>
128   <listitem>
129    <para>Sorts a result set. The sort command takes a
130     sequence of space-separated sort specifications, with each sort
131     specification consisting of two space-separated words (so that the
132     whole specification list is made up of an even number of words).
133     The first word of each specification
134     holds a field (sort criterion) and the second holds flags.
135     If the sort criterion includes <literal>=</literal> it is assumed
136     that the <literal>SortKey</literal> is of type
137     <literal>sortAttributes</literal> using Bib-1: in this case
138     the integer before <literal>=</literal> is
139     the attribute type and the integer following <literal>=</literal>
140     is the attribute value.
141     If no <literal>=</literal> is in the criterion it is treated as a
142     sortfield of type InternationalString.
143     The flags word of each sort specification must consist of
144     <literal>s</literal> 
145     for case sensitive or <literal>i</literal> for case insensitive, and
146     <literal>&lt;</literal> for ascending order or <literal>&gt;</literal>
147     for descending order.
148    </para>
149   </listitem>
150  </varlistentry>
151  <varlistentry><term>
152    <literal>sort+</literal>
153   </term>
154   <listitem>
155    <para>Same as <literal>sort</literal> but stores the sorted
156     result set in a new result set.
157    </para>
158   </listitem>
159  </varlistentry>
160  <varlistentry><term>
161    <literal>authentication</literal> <replaceable>openauth</replaceable>
162   </term>
163   <listitem>
164    <para>Sets up a authentication string if a server requires
165     authentication (v2 OpenStyle). The authentication string is first
166     sent to the server when the 
167     <link linkend="command-open"><literal>open</literal></link> command is
168     issued and the Z39.50 Initialize Request is sent, so this command
169     must be used before <literal>open</literal> in order to be effective.
170     A common convention for the <replaceable>authopen</replaceable> string
171     is that the username - and password is separated by a slash, e.g.
172     <literal>myusername/mysecret</literal>.
173    </para>
174   </listitem>
175  </varlistentry>
176
177  <varlistentry><term>
178    <literal>sru</literal> <replaceable>method</replaceable>
179   </term>
180   <listitem>
181    <para>Selects SRU method. Must be one of <literal>POST</literal>,
182     <literal>GET</literal>, <literal>SOAP</literal> (default).
183    </para>
184   </listitem>
185  </varlistentry>
186
187  <varlistentry><term>
188    <literal>list_all</literal>
189   </term>
190   <listitem>
191    <para>This command displays status and values for many settings.
192    </para>
193   </listitem>
194  </varlistentry>
195  
196  <varlistentry><term>
197    <literal>lslb</literal> <replaceable>n</replaceable>
198   </term>
199   <listitem>
200    <para>Sets the limit for when no records should be returned
201     together with the search result.
202     See the
203     <ulink
204      url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
205      Z39.50 standard
206     </ulink>
207     for more details.
208    </para>
209   </listitem>
210  </varlistentry>
211
212  <varlistentry><term>
213    <literal>ssub</literal> <replaceable>n</replaceable>
214   </term>
215   <listitem>
216    <para>Sets the limit for when all records should be returned with
217     the search result.
218     See the
219     <ulink
220      url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
221      Z39.50 standard
222     </ulink> for more details.
223    </para>
224   </listitem>
225  </varlistentry>
226  
227  <varlistentry><term>
228    <literal>mspn</literal> <replaceable>n</replaceable>
229   </term>
230   <listitem>
231    <para>Sets the number of records should be returned if the
232     number of records in the result set is between the values of
233     <literal>lslb</literal> and <literal>ssub</literal>.
234     See the
235     <ulink
236      url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
237      Z39.50 standard
238     </ulink>
239     for more details.
240    </para>
241   </listitem>
242  </varlistentry>
243  <varlistentry><term>
244    <literal>status</literal>
245   </term>
246   <listitem>
247    <para>Displays the values of <literal>lslb</literal>,
248     <literal>ssub</literal> and <literal>mspn</literal>.
249    </para>
250   </listitem>
251  </varlistentry>
252  <varlistentry><term>
253    <literal>setname</literal>
254   </term>
255   <listitem>
256    <para>Switches named result sets on and off. Default is on.
257    </para>
258   </listitem>
259  </varlistentry>
260  <varlistentry><term>
261    <literal>cancel</literal>
262   </term>
263   <listitem>
264    <para>Sends a Trigger Resource Control Request to the target.
265    </para>
266   </listitem>
267  </varlistentry>
268  <varlistentry><term>
269    <literal>format</literal> <replaceable>oid</replaceable>
270   </term>
271   <listitem>
272    <para>Sets the preferred transfer syntax for retrieved records.
273     yaz-client supports all the record syntaxes that currently
274     are registered. See
275     <ulink
276      url="http://www.loc.gov/z3950/agency/defns/oids.html#5">
277      Z39.50 Standard
278     </ulink>
279     for more details. Commonly used records syntaxes include usmarc,
280     sutrs, grs1 and xml.
281    </para>
282   </listitem>
283  </varlistentry>
284  <varlistentry><term>
285    <literal>elements</literal> <replaceable>e</replaceable>
286   </term>
287   <listitem>
288    <para>Sets the element set name for the records. Many targets support
289     element sets are B (for brief) and F (for full).
290    </para>
291   </listitem>
292  </varlistentry>
293  <varlistentry><term>
294    <literal>close</literal>
295   </term>
296   <listitem>
297    <para>Sends a Z39.50 Close APDU and closes connection with the peer
298    </para>
299   </listitem>
300  </varlistentry>
301  <varlistentry id="command-querytype"><term>
302    <literal>querytype</literal> <replaceable>type</replaceable>
303   </term>
304   <listitem>
305    <para>Sets the query type as used by command 
306    <link linkend="command-find"><literal>find</literal></link>.
307     The following is supported:
308     <literal>prefix</literal> for
309         <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
310     <literal>ccl</literal> for CCL search (Type-2 Query),
311     <literal>cql</literal> for CQL (Type-104 search with CQL OID),
312     <literal>ccl2rpn</literal> for
313         <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
314     <literal>cql2rpn</literal> for
315         CQL to RPN conversion (Type-1 Query).
316    </para>
317   </listitem>
318  </varlistentry>
319  <varlistentry><term>
320    <literal>attributeset</literal> <replaceable>set</replaceable>
321   </term>
322   <listitem>
323    <para>
324     Sets attribute set OID for prefix queries (RPN, Type-1).
325    </para>
326   </listitem>
327  </varlistentry>
328  <varlistentry><term>
329    <literal>refid</literal> <replaceable>id</replaceable>
330   </term>
331   <listitem>
332    <para>Sets reference ID for Z39.50 Request(s).
333    </para>
334   </listitem>
335  </varlistentry>
336  <varlistentry><term>
337    <literal>itemorder</literal>
338    <replaceable>type</replaceable> <replaceable>no</replaceable>
339   </term>
340   <listitem>
341    <para>Sends an Item Order Request using the ILL External. 
342     <replaceable>type</replaceable> is either 1 or 2 which corresponds to
343     ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
344     is the Result Set position of the record to be ordered.
345    </para>
346   </listitem>
347  </varlistentry>
348  <varlistentry><term>
349    <literal>update</literal>
350    <replaceable>action</replaceable>
351    <replaceable>recid</replaceable>
352    <replaceable>doc</replaceable>
353   </term>
354   <listitem>
355    <para>Sends Item Update Request. The <replaceable>action</replaceable>
356     argument must be the action type: one of <literal>insert</literal>,
357     <literal>replace</literal>, <literal>delete</literal> and
358     <literal>update</literal>. The second argument, 
359     <replaceable>recid</replaceable>, is the
360     record identifier (any string). Third argument which is optional is
361     the record document for the request. If doc is a quoted string
362     (double quotes) the string content is used verbatim. If doc is not
363     a quoted string, it is assumed to be a filename which is read, then
364     sent as the docuemnt content. If doc is omitted, the last received
365     record (as parf of present response or piggybacked search response) 
366     is used for the update.
367    </para>
368   </listitem>
369  </varlistentry>
370
371  <varlistentry><term>
372    <literal>source</literal>
373    <replaceable>filename</replaceable>
374   </term>
375   <listitem>
376    <para>Executes list of commands from
377     file <replaceable>filename</replaceable>, just like source on
378     most UNIX shells. A single dot (<literal>.</literal>) can be used
379     as an alternative.
380    </para>
381   </listitem>
382  </varlistentry>
383
384  <varlistentry><term>
385    <literal>!</literal>
386    <replaceable>args</replaceable>
387   </term>
388   <listitem>
389    <para>Executes command <replaceable>args</replaceable> in subshell
390     using the <literal>system</literal> call.
391    </para>
392   </listitem>
393  </varlistentry>
394
395  <varlistentry><term>
396    <literal>push_command</literal>
397    <replaceable>command</replaceable>
398   </term>
399   <listitem>
400    <para>The push_command takes another command as its argument.
401     That command is then added to the history information (so
402     you can retrieve it later). The command itself is not
403     executed. This command only works if you have GNU readline/history
404     enabled.
405    </para>
406   </listitem>
407  </varlistentry>
408
409  <varlistentry><term>
410    <literal>set_apdufile</literal>
411    <replaceable>filename</replaceable>
412   </term>
413   <listitem>
414    <para>Sets that APDU should be logged to file
415     <replaceable>filename</replaceable>. Another way to achieve
416     APDU log is by using command-line option <literal>-a</literal>.
417    </para>
418   </listitem>
419  </varlistentry>
420
421  <varlistentry><term>
422    <literal>set_auto_reconnect</literal>
423    <replaceable>flag</replaceable>
424   </term>
425   <listitem>
426    <para>Specifies whether YAZ client automatically reconnect if
427     target closes connection (Z39.50 only).
428    </para>
429    <para>
430     <replaceable>flag</replaceable> must be either
431     <literal>on</literal> or <literal>off</literal>.
432    </para>
433   </listitem>
434  </varlistentry>
435
436  <varlistentry id="command-set-auto-wait"><term>
437    <literal>set_auto_wait</literal>
438    <replaceable>flag</replaceable>
439   </term>
440   <listitem>
441    <para>Specifies whether YAZ client should wait for
442    response protocol packages after a request.
443    By default YAZ client waits (on) for response packages immediately
444    after a command (find, show) has been issued. If <literal>off</literal>
445    is used, YAZ client does not attempt to receive packages automatically.
446    These will have to be manually received when command 
447    <link linkend="command-wait-response">
448     <literal>wait_response</literal>
449    </link> is used.
450    </para>
451    <para>
452    <replaceable>flag</replaceable> must be either
453    <literal>on</literal> or <literal>off</literal>.
454    </para>
455   </listitem>
456  </varlistentry>
457
458  <varlistentry><term>
459    <literal>set_marcdump</literal>
460    <replaceable>filename</replaceable>
461   </term>
462   <listitem>
463    <para>Specifies that all retrieved records should be appended to
464     file <replaceable>filename</replaceable>. This command does the
465     thing as option <literal>-m</literal>.
466    </para>
467   </listitem>
468  </varlistentry>
469
470  <varlistentry><term>
471    <literal>schema</literal>
472    <replaceable>schemaid</replaceable>
473   </term>
474   <listitem>
475    <para>Specifies schema for retrieval.
476     Schema may be specified as an OID for Z39.50.
477     For SRU, schema is a simple string URI.
478    </para>
479   </listitem>
480  </varlistentry>
481
482  <varlistentry id="command-charset"><term>
483    <literal>charset</literal>
484    <replaceable>negotiationcharset</replaceable>
485    [<replaceable>displaycharset</replaceable>]
486    [[<replaceable>marccharset</replaceable>]]
487   </term>
488   <listitem>
489    <para>Specifies character set (encoding) for Z39.50
490     negotiation / SRU encoding and/or character set for output (terminal).
491    </para>
492    <para>
493     <replaceable>negotiationcharset</replaceable> is the name
494     of the character set to be negotiated by the server. The special name
495     <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
496     specifies <emphasis>no</emphasis> character set to be negotiated.
497    </para>
498    <para>
499     If <replaceable>displaycharset</replaceable> is given, it specifies name
500     of the character set of the output (on the terminal on which
501     YAZ client is running). To disable conversion of characters
502     to the output encoding, the special name <literal>-</literal> (dash)
503     can be used.
504     If the special name <literal>auto</literal> is given, YAZ client will
505     convert strings to the encoding of the
506     terminal as returned by <function>nl_langinfo</function> call.
507    </para>
508    <para>
509     If <replaceable>marcharset</replaceable> is given, it specifies name
510     of the character set of retrieved MARC records from server. See
511     also <literal>marcharset</literal> command.
512    </para>
513    <note>
514     <para>
515      Since character set negotation takes effect in the Z39.50
516      Initialize Request you should issue this command before
517      command <link linkend="command-open"><literal>open</literal></link>
518      is used.
519     </para>
520    </note>
521    <note>
522     <para>
523      MARC records are not covered by Z39.50 character set negotiation,
524      so that's why there is a separate character that must be known
525      in order to do meaningful converson(s).
526     </para>
527    </note>
528   </listitem>
529  </varlistentry>
530
531  <varlistentry><term>
532    <literal>negcharset</literal>
533    <replaceable>charset</replaceable>
534   </term>
535   <listitem>
536    <para>Specifies character set for negotiation (Z39.50). The
537     argument is the same as second argument for command
538     <link linkend="command-charset"><literal>charset</literal></link>.
539    </para>
540   </listitem>
541  </varlistentry>
542
543  <varlistentry><term>
544    <literal>displaycharset</literal>
545    <replaceable>charset</replaceable>
546   </term>
547   <listitem>
548    <para>Specifies character set for output (display). The
549     argument is the same as second argument for command 
550     <link linkend="command-charset"><literal>charset</literal></link>.
551    </para>
552   </listitem>
553  </varlistentry>
554
555  <varlistentry><term>
556    <literal>marccharset</literal>
557    <replaceable>charset</replaceable>
558   </term>
559   <listitem>
560    <para>Specifies character set for retrieved MARC records so
561     that YAZ client can display them in a character suitable
562     for your display. See <literal>charset</literal> command.
563     If <literal>auto</literal> is given, YAZ will assume
564     that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
565     for all other MARC variants. The charset argument is the
566     same as third argument for command
567     <link linkend="command-charset"><literal>charset</literal></link>.
568    </para>
569   </listitem>
570  </varlistentry>
571
572  <varlistentry><term>
573    <literal>set_cclfile</literal>
574    <replaceable>filename</replaceable>
575   </term>
576   <listitem>
577    <para>Specifies that CCL fields should be read from file
578     file <replaceable>filename</replaceable>. This command does the
579     thing as option <literal>-c</literal>.
580    </para>
581   </listitem>
582  </varlistentry>
583
584  <varlistentry><term>
585    <literal>set_cqlfile</literal>
586    <replaceable>filename</replaceable>
587   </term>
588   <listitem>
589    <para>Specifies that CQL fields should be read from file
590     file <replaceable>filename</replaceable>. This command does the
591     thing as option <literal>-q</literal>.
592    </para>
593   </listitem>
594  </varlistentry>
595
596  <varlistentry><term>
597    <literal>register_oid</literal>
598    <replaceable>name</replaceable>
599    <replaceable>class</replaceable>
600    <replaceable>OID</replaceable>
601   </term>
602   <listitem>
603    <para>This command allows you to register your own object
604     identifier - so that instead of entering a long dot-notation
605     you can use a short name instead.
606     The <replaceable>name</replaceable> is your
607     name for the OID, <replaceable>class</replaceable> is the
608     class, and <replaceable>OID</replaceable> is the raw OID in
609     dot notation. Class is one <literal>appctx</literal>,
610     <literal>absyn</literal>, <literal>attet</literal>,
611     <literal>transyn</literal>, <literal>diagset</literal>,
612     <literal>recsyn</literal>, <literal>resform</literal>,
613     <literal>accform</literal>, <literal>extserv</literal>,
614     <literal>userinfo</literal>, <literal>elemspec</literal>,
615     <literal>varset</literal>, <literal>schema</literal>,
616     <literal>tagset</literal>, <literal>general</literal>.
617     If you're in doubt use the <literal>general</literal>
618     class.
619    </para>
620   </listitem>
621  </varlistentry>
622
623  <varlistentry><term>
624    <literal>register_tab</literal>
625    <replaceable>command</replaceable>
626    <replaceable>string</replaceable>
627   </term>
628   <listitem>
629    <para>This command registers a TAB completion string for
630     the command given.
631    </para>
632   </listitem>
633  </varlistentry>
634
635  <varlistentry><term>
636    <literal>sleep</literal>
637    <replaceable>seconds</replaceable>
638   </term>
639   <listitem>
640    <para>This command makes YAZ client sleep (be idle) for
641     the number of seconds given.
642    </para>
643   </listitem>
644  </varlistentry>
645
646  <varlistentry id="command-wait-response"><term>
647    <literal>wait_response</literal>
648    [ <replaceable>number</replaceable>]
649   </term>
650   <listitem>
651    <para>This command makes YAZ client wait for a number of
652     response packages from target. If <replaceable>number</replaceable> is
653     omitted, 1 is assumed. 
654    </para>
655    <para>This command is rarely used and is only useful if command
656     <link linkend="command-set-auto-wait">
657      <literal>set_auto_wait</literal>
658     </link> is set to off.
659    </para>
660   </listitem>
661  </varlistentry>
662
663  <varlistentry id="command-xmles"><term>
664    <literal>xmles</literal>
665    <replaceable>OID</replaceable>
666    <replaceable>doc</replaceable>
667   </term>
668   <listitem>
669    <para>Sends XML Extended Services request using the OID and doc given.
670    </para>
671   </listitem>
672  </varlistentry>
673
674  <varlistentry><term>
675    <literal>zversion</literal>
676    <replaceable>ver</replaceable>
677   </term>
678   <listitem>
679    <para>This command sets Z39.50 version for negotiation. 
680     Should be used before 
681     <link linkend="command-open"><literal>open</literal></link>.
682     By default 3 (version 3) is used.
683    </para>
684   </listitem>
685  </varlistentry>
686
687  <varlistentry><term>
688    <literal>options</literal>
689    <replaceable>op1 op2..</replaceable>
690   </term>
691   <listitem>
692    <para>This command sets Z39.50 options for negotiation. 
693     Should be used before 
694    <link linkend="command-open"><literal>open</literal></link>.
695    </para>
696    <para>
697     The following options are supported:
698     <literal>search</literal>,  
699     <literal>present</literal>,  
700     <literal>delSet</literal>,  
701     <literal>resourceReport</literal>,  
702     <literal>triggerResourceCtrl</literal>,  
703     <literal>resourceCtrl</literal>,  
704     <literal>accessCtrl</literal>,  
705     <literal>scan</literal>,  
706     <literal>sort</literal>,  
707     <literal>extendedServices</literal>,  
708     <literal>level_1Segmentation</literal>,  
709     <literal>level_2Segmentation</literal>,  
710     <literal>concurrentOperations</literal>,  
711     <literal>namedResultSets</literal>,  
712     <literal>encapsulation</literal>,  
713     <literal>resultCount</literal>,  
714     <literal>negotiationModel</literal>,  
715     <literal>duplicationDetection</literal>,  
716     <literal>queryType104</literal>,  
717     <literal>pQESCorrection</literal>,  
718     <literal>stringSchema</literal>.
719    </para>
720   </listitem>
721  </varlistentry>
722  
723 </variablelist>
724 <!-- Keep this comment at the end of the file
725 Local variables:
726 mode: sgml
727 sgml-omittag:t
728 sgml-shorttag:t
729 sgml-minimize-attributes:nil
730 sgml-always-quote-attributes:t
731 sgml-indent-step:1
732 sgml-indent-data:t
733 sgml-parent-document: "yaz.xml"
734 sgml-local-catalogs: nil
735 sgml-namecase-general:t
736 End:
737 -->