yaz-client - Man Page

yaz-client [-a apdulog] [-b berdump] [-c cclfile] [-C certfname] [-d dump] [-e | --check-cert] [-f cmdfile] [-k size] [-m marclog] [-p proxy-addr] [-q cqlfile] [-t dispcharset] [-u auth] [-v loglevel] [-V] [-x] [server-addr]

yaz-client is a Z39​.50​^[1]/SRU​^[2] client (origin) with a simple command line interface that allows you to test behavior and performance of Z39​.50 targets and SRU servers​.

From YAZ version 4​.1​.0 yaz-client may also operate as a Solr​^[3] Web Service client​.

If the server-addr is specified, the client creates a connection to the Z39​.50/SRU target at the address given​.

When yaz-client is started it tries to read commands from one of the following files:

• Command file if it is given by option -f​.
• ​.yazclientrc in current working directory​.
• ​.yazclientrc in the user's home directory​. The value of the $HOME environment variable is used to determine the home directory​. Normally, $HOME is only set on POSIX systems such as Linux, FreeBSD, Solaris​.

-a filename

If specified, logging of protocol packages will be appended to the file given​. If filename is specified as -, the output is written to stdout​.

-b filename

If specified, YAZ will dump BER data in readable notation to the file specified​. If filename is specified as - the output is written to stdout​.

-c filename

If specified, CCL configuration will be read from the file given​.

-C certfname

Specifies a PEM file containing the client certificate and private key​. Alternatively, specify certificate-file,key-file when they are separate​.

-d dump

If specified, YAZ will dump BER data for all PDUs sent and received to individual files, named dump​.DDD​.raw, where DDD is 001, 002, 003, ​.​.​.

-e | --check-cert

Makes yaz-client verify the server certificate and hostname when using HTTPS or SSL over Z39​.50​.

-f cmdfile

Reads commands from cmdfile​. When this option is used, YAZ client does not read ​.yazclientrc from current directory or home directory​.

-k size

Sets preferred messages and maximum record size for Initialize Request in kilobytes​. Default value is 65536 (64 MB)​.

-m filename

If specified, retrieved records will be appended to the file given​.

-p proxy-addr

If specified, the client will use the proxy at the address given​. YAZ client will connect to a proxy on the address and port given​. The actual target will be specified as part of the InitRequest to inform the proxy about the actual target​.

-q filename

If specified, CQL configuration will be read from the file given​.

-t displaycharset

If displaycharset is given, it specifies name of the character set of the output (on the terminal on which YAZ client is running)​.

-u auth

If specified, the auth string will be used for authentication​.

-v level

Sets the LOG level to level​. Level is a sequence of tokens separated by comma​. Each token is a integer or a named LOG item - one of fatal, debug, warn, log, malloc, all, none​.

-V

Prints YAZ version​.

-x

Makes the YAZ client print hex dumps of packages sent and received on standard output​.

The YAZ client accepts the following commands​.

open zurl

Opens a connection to a server​. The syntax for zurl is the same as described above for connecting from the command line​.

Syntax:

[(tcp|ssl|unix|http)':']host [:port][/base]

quit

Quits YAZ client

find query

Sends a Search Request using the query given​. By default the query is assumed to be PQF​. See command querytype for more information​.

delete setname

Deletes result set with name setname on the server​.

base base1 base2 ​.​.​.

Sets the name(s) of the database(s) to search​. One or more databases may be specified, separated by blanks​. This command overrides the database given in zurl​.

show [start[+number [+resultset]]]

Fetches records by sending a Present Request from the start position given by start and a number of records given by number, from the result set resultset​. If start is not given, then the client will fetch from the position of the last retrieved record plus 1​. If number is not given, then one record will be fetched at a time​. If resultset is not given, the most recently retrieved result set is used​.

scan term

Scans database index for a term​. The syntax resembles the syntax for find​. If you want to scan for the word water you could write

      scan water

but if you want to scan only in, say the title field, you would write

      scan @attr 1=4 water

setscan set term

Scans database index for a term within a result set​. This is similar to the scan command but has a result set as its first argument​.

scanpos pos

Sets preferred position for scan​. This value is used in the next scan​. By default, position is 1​.

scansize size

Sets number of entries to be returned by scan​. Default number of entries is 20​.

scanstep step

Set step-size for scan​. This value is used in the next scan sent to the target​. By default step-size is 0​.

sort sortspecs

Sorts a result set​. The sort command takes a sequence of space-separated sort specifications, with each sort specification consisting of two space-separated words (so that the whole specification list is made up of an even number of words)​. The first word of each specification holds a field (sort criterion) and the second holds flags​. If the sort criterion includes = it is assumed that the SortKey is of type sortAttributes using Bib-1: in this case the integer before = is the attribute type and the integer following = is the attribute value​. If no = character is in the criterion, it is treated as a sortfield of type InternationalString​. The flags word of each sort specification must consist of s for case sensitive or i for case insensitive, and < for ascending order or > for descending order​.

Example using sort criterion with attributes use=local-number and structure=numeric and ascending flag: 1=12,4=109 <

Another example with "Title" sort field and descending flag: Title >

sort+

Same as sort but stores the sorted result set in a new result set​.

authentication [auth1 [auth2 [auth3]]]

Configures authentication strings to be sent to server​. Zero, 1, 2 or 3 arguments may follow the auth command​.

If no (0) arguments are given, no authentication string is sent​.

If one argument is given, the Z39​.50 v2 OpenStyle authentication is used​. A common convention for the auth1 string is that the username and password is separated by a slash, e​.g​. myusername/mysecret​.

If two or more arguments is given Z39​.50 v3 authentication is used, in which cased the first argument is used, second argument is group and third argument is password​. If only two arguments are given the group is assumed to be empty​.

As for other commands in yaz-client, the arguments are separated by whitespace​. A backslash character can be used to include a character verbatim​. For example, auth myuser a\ b is a two argument auth command where user is myuser and password is a b​.

The authentication string is first sent to the server when the open command is issued and the Z39​.50 Initialize Request is sent, so this command must be used before open in order to be effective​.

sru method version

Selects Web Service method and version​. Must be one of post, get, soap (default) or solr​. Version should be either 1​.1, 1​.2 or 2​.0 for SRU​. Other versions are allowed - for testing purposes (version negotiation with SRU server)​. The version is currently not used for Solr Web Services

list_all

This command displays status and values for many settings​.

lslb n

Sets the limit for when no records should be returned together with the search result​. See the Z39​.50 standard on set bounds​^[4] for more details​.

ssub n

Sets the limit for when all records should be returned with the search result​. See the Z39​.50 standard on set bounds​^[4] for more details​.

mspn n

Sets the number of records that should be returned if the number of records in the result set is between the values of lslb and ssub​. See the Z39​.50 standard on set bounds​^[4] for more details​.

status

Displays the values of lslb, ssub and mspn​.

setname

Switches named result sets on and off​. Default is on​.

cancel

Sends a Trigger Resource Control Request to the target​.

facets spec

Specifies requested facets to be used in search​. The notation is specified in ???​.

format oid

Sets the preferred transfer syntax for retrieved records​. yaz-client supports all the record syntaxes that currently are registered​. See Z39​.50 Record Syntax Identifiers​^[5] for more details​. Commonly used records syntaxes include usmarc, sutrs and xml​.

elements e

Sets the element set name for the records​. Many targets support element sets B (for brief) and F (for full)​.

close

Sends a Z39​.50 Close APDU and closes connection with the peer

querytype type

Sets the query type as used by command find​. The following is supported: prefix for Prefix Query Notation (Type-1 Query); ccl for CCL search (Type-2 Query), cql for CQL (Type-104 search with CQL OID), ccl2rpn for CCL to RPN conversion (Type-1 Query), cql2rpn for CQL to RPN conversion (Type-1 Query)​.

attributeset set

Sets attribute set OID for prefix queries (RPN, Type-1)​.

refid id

Sets reference ID for Z39​.50 Request(s)​.

itemorder type no

Sends an Item Order Request using the ILL External​. type is either 1 or 2 which corresponds to ILL-Profile 1 and 2 respectively​. The no is the Result Set position of the record to be ordered​.

update action recid doc

Sends Item Update Request​. The action argument must be the action type: one of insert, replace, delete and update​. The second argument, recid, is the record identifier (any string)​. Third argument which is optional is the record document for the request​. If doc is preceded with "<", then the following characters are treated as a filename with the records to be updated​. Otherwise doc is treated as a document itself​. The doc may also be quoted in double quotes​. If doc is omitted, the last received record (as part of present response or piggybacked search response) is used for the update​.

source filename

Executes list of commands from file filename, just like 'source' on most UNIX shells​. A single dot (​.) can be used as an alternative​.

! args

Executes command args in subshell using the system call​.

push_command command

The push_command takes another command as its argument​. That command is then added to the history information (so you can retrieve it later)​. The command itself is not executed​. This command only works if you have GNU readline/history enabled​.

set_apdufile filename

Sets that APDU should be logged to file filename​. Another way to achieve APDU log is by using command-line option -a​.

set_auto_reconnect flag

Specifies whether YAZ client automatically reconnects if the target closes connection (Z39​.50 only)​.

flag must be either on or off​.

set_auto_wait flag

Specifies whether YAZ client should wait for response protocol packages after a request​. By default YAZ client waits (on) for response packages immediately after a command (find, show) has been issued​. If off is used, YAZ client does not attempt to receive packages automatically​. These will have to be manually received when command wait_response is used​.

flag must be either on or off​.

set_marcdump filename

Specifies that all retrieved records should be appended to file filename​. This command does the same thing as option -m​.

schema schemaid

Specifies schema for retrieval​. Schema may be specified as an OID for Z39​.50​. For SRU, schema is a simple string URI​.

charset negotiationcharset [displaycharset] [[marccharset]]

Specifies character set (encoding) for Z39​.50 negotiation / SRU encoding and/or character set for output (terminal)​.

negotiationcharset is the name of the character set to be negotiated by the server​. The special name - for negotiationcharset specifies no character set to be negotiated​.

If displaycharset is given, it specifies name of the character set of the output (on the terminal on which YAZ client is running)​. To disable conversion of characters to the output encoding, the special name - (dash) can be used​. If the special name auto is given, YAZ client will convert strings to the encoding of the terminal as returned by nl_langinfo call​.

If marccharset is given, it specifies name of the character set of retrieved MARC records from server​. See also marccharset command​.

Note
Since character set negotiation takes effect in the Z39​.50 Initialize Request you should issue this command before command open is used​.

Note
MARC records are not covered by Z39​.50 character set negotiation, so that's why there is a separate character that must be known in order to do meaningful conversion(s)​.

negcharset charset

Specifies character set for negotiation (Z39​.50)​. The argument is the same as second argument for command charset​.

displaycharset charset

Specifies character set for output (display)​. The argument is the same as second argument for command charset​.

marccharset charset

Specifies character set for retrieved MARC records so that YAZ client can display them in a character suitable for your display​. See charset command​. If auto is given, YAZ will assume that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1 for all other MARC variants​. The charset argument is the same as third argument for command charset​.

querycharset charset

Specifies character set for query terms for Z39​.50 RPN queries and Z39​.50 Scan Requests (termListAndStartPoint)​. This is a pure client-side conversion which converts from displayCharset to queryCharset​.

set_cclfile filename

Specifies that CCL fields should be read from file file filename​. This command does the same thing as option -c​.

set_cqlfile filename

Specifies that CQL fields should be read from file file filename​. This command does the same thing as option -q​.

register_oid name class OID

This command allows you to register your own object identifier - so that instead of entering a long dot-notation you can use a short name instead​. The name is your name for the OID, class is the class, and OID is the raw OID in dot notation​. Class is one of: appctx, absyn, attet, transyn, diagset, recsyn, resform, accform, extserv, userinfo, elemspec, varset, schema, tagset, general​. If you're in doubt use the general class​.

register_tab command string

This command registers a TAB completion string for the command given​.

sleep seconds

This command makes YAZ client sleep (be idle) for the number of seconds given​.

wait_response [ number]

This command makes YAZ client wait for a number of response packages from target​. If number is omitted, 1 is assumed​.

This command is rarely used and is only useful if command set_auto_wait is set to off​.

xmles OID doc

Sends XML Extended Services request using the OID and doc given​.

zversion ver

This command sets Z39​.50 version for negotiation​. Should be used before open​. By default 3 (version 3) is used​.

options op1 op2​.​.

This command sets Z39​.50 options for negotiation​. Should be used before open​.

The following options are supported: search, present, delSet, resourceReport, triggerResourceCtrl, resourceCtrl, accessCtrl, scan, sort, extendedServices, level_1Segmentation, level_2Segmentation, concurrentOperations, namedResultSets, encapsulation, resultCount, negotiationModel, duplicationDetection, queryType104, pQESCorrection, stringSchema​.

The simplest example of a Prefix Query would be something like

    f knuth

or

    f "donald knuth"

In those queries, no attributes were specified​. This leaves it up to the server what fields to search but most servers will search in all fields​. Some servers do not support this feature though, and require that some attributes are defined​. To add one attribute you could do:

    f @attr 1=4 computer

where we search in the title field, since the use(1) is title(4)​. If we want to search in the author field and in the title field, and in the title field using right truncation it could look something like this:

    f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer

Finally using a mix of Bib-1 and GILS attributes could look something like this:

    f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather

yaz-<version>/client/client​.c

$HOME/​.yazclientrc

$HOME/​.yazclient​.history

yaz(7) bib1-attr(7)

Index Data

1. Z39.50
   https://loc.gov/standards/z3950/agency/
2. SRU
   https://loc.gov/standards/sru/
3. Solr
   https://solr.apache.org
4. Z39.50 standard on set bounds
   https://loc.gov/standards/z3950/agency/markup/04.html#3.2.2.1.6
5. Z39.50 Record Syntax Identifiers
   https://loc.gov/standards/z3950/agency/defns/oids.html#5

yaz(7), yaz-log(7).