2 $Id: yaz-client-commands.xml,v 1.11 2005-11-04 17:15:30 mike 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>scanpos</literal> <replaceable>pos</replaceable>
100 Sets preferred position for scan. This value
101 is used in next scan. By default position is 1.
106 <literal>scansize</literal> <replaceable>size</replaceable>
110 Sets number of entries to be returned by scan. Default
111 number of entries is 20.
116 <literal>scanstep</literal> <replaceable>step</replaceable>
120 Set step-size for scan. This value is used in next scan
121 sent to the target. By default step-size is 0.
125 <varlistentry id="sortspec"><term>
126 <literal>sort</literal> <replaceable>sortspecs</replaceable>
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
145 for case sensitive or <literal>i</literal> for case insensitive, and
146 <literal><</literal> for ascending order or <literal>></literal>
147 for descending order.
152 <literal>sort+</literal>
155 <para>Same as <literal>sort</literal> but stores the sorted
156 result set in a new result set.
161 <literal>authentication</literal> <replaceable>openauth</replaceable>
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>.
178 <literal>list_all</literal>
181 <para>This command displays status and values for many settings.
187 <literal>lslb</literal> <replaceable>n</replaceable>
190 <para>Sets the limit for when no records should be returned
191 together with the search result.
194 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
203 <literal>ssub</literal> <replaceable>n</replaceable>
206 <para>Sets the limit for when all records should be returned with
210 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
212 </ulink> for more details.
218 <literal>mspn</literal> <replaceable>n</replaceable>
221 <para>Sets the number of records should be returned if the
222 number of records in the result set is between the values of
223 <literal>lslb</literal> and <literal>ssub</literal>.
226 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
234 <literal>status</literal>
237 <para>Displays the values of <literal>lslb</literal>,
238 <literal>ssub</literal> and <literal>mspn</literal>.
243 <literal>setname</literal>
246 <para>Switches named result sets on and off. Default is on.
251 <literal>cancel</literal>
254 <para>Sends a Trigger Resource Control Request to the target.
259 <literal>format</literal> <replaceable>oid</replaceable>
262 <para>Sets the preferred transfer syntax for retrieved records.
263 yaz-client supports all the record syntaxes that currently
266 url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
269 for more details. Commonly used records syntaxes include usmarc,
275 <literal>elements</literal> <replaceable>e</replaceable>
278 <para>Sets the element set name for the records. Many targets support
279 element sets are B (for brief) and F (for full).
284 <literal>close</literal>
287 <para>Sends a Z39.50 Close APDU and closes connection with the peer
291 <varlistentry id="command-querytype"><term>
292 <literal>querytype</literal> <replaceable>type</replaceable>
295 <para>Sets the query type as used by command
296 <link linkend="command-find"><literal>find</literal></link>.
297 The following is supported:
298 <literal>prefix</literal> for
299 <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
300 <literal>ccl</literal> for CCL search (Type-2 Query),
301 <literal>cql</literal> for CQL (Type-104 search with CQL OID),
302 <literal>ccl2rpn</literal> for
303 <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
304 <literal>cql2rpn</literal> for
305 CQL to RPN conversion (Type-1 Query).
310 <literal>attributeset</literal> <replaceable>set</replaceable>
314 Sets attribute set OID for prefix queries (RPN, Type-1).
319 <literal>refid</literal> <replaceable>id</replaceable>
322 <para>Sets reference ID for Z39.50 Request(s).
327 <literal>itemorder</literal>
328 <replaceable>type</replaceable> <replaceable>no</replaceable>
331 <para>Sends an Item Order Request using the ILL External.
332 <replaceable>type</replaceable> is either 1 or 2 which corresponds to
333 ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
334 is the Result Set position of the record to be ordered.
339 <literal>update</literal>
340 <replaceable>action</replaceable>
341 <replaceable>recid</replaceable>
342 <replaceable>doc</replaceable>
345 <para>Sends Item Update Request. The <replaceable>action</replaceable>
346 argument must be the action type: one of <literal>insert</literal>,
347 <literal>replace</literal>, <literal>delete</literal> and
348 <literal>update</literal>. The second argument,
349 <replaceable>recid</replaceable>, is the
350 record identifier (any string). Third argument which is optional is
351 the record document for the request. If doc is a quoted string
352 (double quotes) the string content is used verbatim. If doc is not
353 a quoted string, it is assumed to be a filename which is read, then
354 sent as the docuemnt content. If doc is omitted, the last received
355 record (as parf of present response or piggybacked search response)
356 is used for the update.
363 <replaceable>filename</replaceable>
366 <para>Executes list of commands from
367 file <replaceable>filename</replaceable>, just like source on
375 <replaceable>args</replaceable>
378 <para>Executes command <replaceable>args</replaceable> in subshell
379 using the <literal>system</literal> call.
385 <literal>push_command</literal>
386 <replaceable>command</replaceable>
389 <para>The push_command takes another command as its argument.
390 That command is then added to the history information (so
391 you can retrieve it later). The command itself is not
392 executed. This command only works if you have GNU readline/history
399 <literal>set_apdufile</literal>
400 <replaceable>filename</replaceable>
403 <para>Sets that APDU should be logged to file
404 <replaceable>filename</replaceable>. Another way to achieve
405 APDU log is by using command-line option <literal>-a</literal>.
411 <literal>set_auto_reconnect</literal>
412 <replaceable>flag</replaceable>
415 <para>Specifies whether YAZ client automatically reconnect if
416 target closes connection (Z39.50 only).
419 <replaceable>flag</replaceable> must be either
420 <literal>on</literal> or <literal>off</literal>.
425 <varlistentry id="command-set-auto-wait"><term>
426 <literal>set_auto_wait</literal>
427 <replaceable>flag</replaceable>
430 <para>Specifies whether YAZ client should wait for
431 response protocol packages after a request.
432 By default YAZ client waits (on) for response packages immediately
433 after a command (find, show) has been issued. If <literal>off</literal>
434 is used, YAZ client does not attempt to receive packages automatically.
435 These will have to be manually received when command
436 <link linkend="command-wait-response">
437 <literal>wait_response</literal>
441 <replaceable>flag</replaceable> must be either
442 <literal>on</literal> or <literal>off</literal>.
448 <literal>set_marcdump</literal>
449 <replaceable>filename</replaceable>
452 <para>Specifies that all retrieved records should be appended to
453 file <replaceable>filename</replaceable>. This command does the
454 thing as option <literal>-m</literal>.
460 <literal>schema</literal>
461 <replaceable>schemaid</replaceable>
464 <para>Specifies schema for retrieval.
465 Schema may be specified as an OID for Z39.50.
466 For SRW, schema is a simple string URI.
471 <varlistentry id="command-charset"><term>
472 <literal>charset</literal>
473 <replaceable>negotiationcharset</replaceable>
474 [<replaceable>displaycharset</replaceable>]
475 [[<replaceable>marccharset</replaceable>]]
478 <para>Specifies character set (encoding) for Z39.50
479 negotiation / SRW encoding and/or character set for output (terminal).
482 <replaceable>negotiationcharset</replaceable> is the name
483 of the character set to be negotiated by the server. The special name
484 <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
485 specifies <emphasis>no</emphasis> character set to be negotiated.
488 If <replaceable>displaycharset</replaceable> is given, it specifies name
489 of the character set of the output (on the terminal on which
490 YAZ client is running). To disable conversion of characters
491 to the output encoding, the special name <literal>-</literal> (dash)
493 If the special name <literal>auto</literal> is given, YAZ client will
494 convert strings to the encoding of the
495 terminal as returned by <function>nl_langinfo</function> call.
498 If <replaceable>marcharset</replaceable> is given, it specifies name
499 of the character set of retrieved MARC records from server. See
500 also <literal>marcharset</literal> command.
504 Since character set negotation takes effect in the Z39.50
505 Initialize Request you should issue this command before
506 command <link linkend="command-open"><literal>open</literal></link>
512 MARC records are not covered by Z39.50 character set negotiation,
513 so that's why there is a separate character that must be known
514 in order to do meaningful converson(s).
521 <literal>negcharset</literal>
522 <replaceable>charset</replaceable>
525 <para>Specifies character set for negotiation (Z39.50). The
526 argument is the same as second argument for command
527 <link linkend="command-charset"><literal>charset</literal></link>.
533 <literal>displaycharset</literal>
534 <replaceable>charset</replaceable>
537 <para>Specifies character set for output (display). The
538 argument is the same as second argument for command
539 <link linkend="command-charset"><literal>charset</literal></link>.
545 <literal>marccharset</literal>
546 <replaceable>charset</replaceable>
549 <para>Specifies character set for retrieved MARC records so
550 that YAZ client can display them in a character suitable
551 for your display. See <literal>charset</literal> command.
552 If <literal>auto</literal> is given, YAZ will assume
553 that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
554 for all other MARC variants. The charset argument is the
555 same as third argument for command
556 <link linkend="command-charset"><literal>charset</literal></link>.
562 <literal>set_cclfile</literal>
563 <replaceable>filename</replaceable>
566 <para>Specifies that CCL fields should be read from file
567 file <replaceable>filename</replaceable>. This command does the
568 thing as option <literal>-c</literal>.
574 <literal>set_cqlfile</literal>
575 <replaceable>filename</replaceable>
578 <para>Specifies that CQL fields should be read from file
579 file <replaceable>filename</replaceable>. This command does the
580 thing as option <literal>-q</literal>.
586 <literal>register_oid</literal>
587 <replaceable>name</replaceable>
588 <replaceable>class</replaceable>
589 <replaceable>OID</replaceable>
592 <para>This command allows you to register your own object
593 identifier - so that instead of entering a long dot-notation
594 you can use a short name instead.
595 The <replaceable>name</replaceable> is your
596 name for the OID, <replaceable>class</replaceable> is the
597 class, and <replaceable>OID</replaceable> is the raw OID in
598 dot notation. Class is one <literal>appctx</literal>,
599 <literal>absyn</literal>, <literal>attet</literal>,
600 <literal>transyn</literal>, <literal>diagset</literal>,
601 <literal>recsyn</literal>, <literal>resform</literal>,
602 <literal>accform</literal>, <literal>extserv</literal>,
603 <literal>userinfo</literal>, <literal>elemspec</literal>,
604 <literal>varset</literal>, <literal>schema</literal>,
605 <literal>tagset</literal>, <literal>general</literal>.
606 If you're in doubt use the <literal>general</literal>
613 <literal>register_tab</literal>
614 <replaceable>command</replaceable>
615 <replaceable>string</replaceable>
618 <para>This command registers a TAB completion string for
625 <literal>sleep</literal>
626 <replaceable>seconds</replaceable>
629 <para>This command makes YAZ client sleep (be idle) for
630 the number of seconds given.
635 <varlistentry id="command-wait-response"><term>
636 <literal>wait_response</literal>
637 [ <replaceable>number</replaceable>]
640 <para>This command makes YAZ client wait for a number of
641 response packages from target. If <replaceable>number</replaceable> is
642 omitted, 1 is assumed.
644 <para>This command is rarely used and is only useful if command
645 <link linkend="command-set-auto-wait">
646 <literal>set_auto_wait</literal>
647 </link> is set to off.
652 <varlistentry id="command-xmles"><term>
653 <literal>xmles</literal>
654 <replaceable>OID</replaceable>
655 <replaceable>doc</replaceable>
658 <para>Sends XML Extended Services request using the OID and doc given.
664 <literal>zversion</literal>
665 <replaceable>ver</replaceable>
668 <para>This command sets Z39.50 version for negotiation.
669 Should be used before
670 <link linkend="command-open"><literal>open</literal></link>.
671 By default 3 (version 3) is used.
677 <literal>options</literal>
678 <replaceable>op1 op2..</replaceable>
681 <para>This command sets Z39.50 options for negotiation.
682 Should be used before
683 <link linkend="command-open"><literal>open</literal></link>.
686 The following options are supported:
687 <literal>search</literal>,
688 <literal>present</literal>,
689 <literal>delSet</literal>,
690 <literal>resourceReport</literal>,
691 <literal>triggerResourceCtrl</literal>,
692 <literal>resourceCtrl</literal>,
693 <literal>accessCtrl</literal>,
694 <literal>scan</literal>,
695 <literal>sort</literal>,
696 <literal>extendedServices</literal>,
697 <literal>level_1Segmentation</literal>,
698 <literal>level_2Segmentation</literal>,
699 <literal>concurrentOperations</literal>,
700 <literal>namedResultSets</literal>,
701 <literal>encapsulation</literal>,
702 <literal>resultCount</literal>,
703 <literal>negotiationModel</literal>,
704 <literal>duplicationDetection</literal>,
705 <literal>queryType104</literal>,
706 <literal>pQESCorrection</literal>,
707 <literal>stringSchema</literal>.
713 <!-- Keep this comment at the end of the file
718 sgml-minimize-attributes:nil
719 sgml-always-quote-attributes:t
722 sgml-parent-document: "yaz.xml"
723 sgml-local-catalogs: nil
724 sgml-namecase-general:t