YAZ-CLIENT(1)

📦
version 5.38.1 · 13 versions
, in arch rolling, fedora 44

💖 YAZ-CLIENT(1) 💖

okay bestie, gather round, because this is the manual page for yaz-client in the Commands section and it is lowkey iconic. it's giving "tool for people who actually build this stuff." let's go 🫶

✨ NAME ✨

yaz-client — the Z39.50/SRU client for implementors 💅

🌸 SYNOPSIS 🌸

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]

🦋 DESCRIPTION 🦋

so yaz-client is a Z39.50[1]/SRU[2] client (an origin, in the ✨technical✨ sense) and it has this whole simple command line interface whose entire job is letting you test how Z39.50 targets and SRU servers behave and perform. it's a vibe check for servers, no cap.

and starting from YAZ version 4.1.0, yaz-client can also serve as a Solr[3] Web Service client. versatility!! we love her 👑

if you pass the server-addr, the client goes ahead and creates a connection to the Z39.50/SRU target at that address. instant bestie connection.

when yaz-client starts up, it tries to read commands from one of these files, in this order:

  • The command file, if you gave it with the option -f.
  • .yazclientrc in the current working directory.
  • .yazclientrc in the user's home directory. the value of the $HOME environment variable is what decides the home directory. and ngl, $HOME is normally only set on POSIX systems such as Linux, FreeBSD, Solaris. so on other systems? that last one just isn't happening, sorry babe 😭

🎀 OPTIONS 🎀

  • -a filename — if you set this, logging of protocol packages gets appended to the file you named. and if filename is literally -, the output goes to stdout instead. cute!
  • -b filename — if you set this, YAZ will dump BER data in readable notation to the file specified. and again, if filename is -, output goes to stdout 🌈
  • -c filename — if you set this, CCL configuration is read from the file you gave.
  • -C certfname — specifies a PEM file with the client certificate and private key living together in one file. OR, alternatively, specify certificate-file,key-file when they're separate little individuals 🫶
  • -d dump — if you set this, YAZ dumps BER data for all PDUs sent and received into individual files named dump.DDD.raw, where DDD is 001, 002, 003, ... and on and on ✨
  • -e | --check-cert — makes yaz-client verify the server certificate and hostname when it's using HTTPS or SSL over Z39.50. security!! we stan 🔒
  • -f cmdfile — reads commands from cmdfile. and heads up: when you use this option, YAZ client does not read .yazclientrc from the current directory or from the home directory. it's her world now.
  • -k size — sets the preferred messages and maximum record size for the Initialize Request, measured in kilobytes. default value is 65536 (that's 64 MB, bestie).
  • -m filename — if you set this, retrieved records get appended to the file you gave.
  • -p proxy-addr — if you set this, the client uses the proxy at the address you gave. YAZ client connects to a proxy on the address and port given. the actual target gets specified as part of the InitRequest, so the proxy knows who we're actually talking to. sneaky but honest 💅
  • -q filename — if you set this, CQL configuration gets read from the file you gave.
  • -t displaycharset — if displaycharset is given, it specifies the name of the character set of the output — i.e. on the terminal where YAZ client is running.
  • -u auth — if you set this, the auth string is used for authentication.
  • -v level — sets the LOG level to level. level is a sequence of tokens separated by commas. each token is either an integer or a named LOG item, and those named items are: fatal, debug, warn, log, malloc, all, none.
  • -V — prints the YAZ version. that's it. that's the whole job. ✨
  • -x — makes the YAZ client print hex dumps of the packages sent and received on standard output. full transparency, babes.

💜 COMMANDS 💜

the YAZ client accepts the following commands. buckle up, there's a whole roster 👑

  • open zurl — opens a connection to a server. the syntax for zurl is exactly the same as described above for connecting from the command line.

Syntax:

[(tcp|ssl|unix|http)':']host [:port][/base]
  • quit — quits YAZ client. goodbye bestie 😭
  • find query — sends a Search Request using the query you gave. by default the query is assumed to be PQF. for more info, go look at the command querytype.
  • delete setname — deletes the result set with the name setname over on the server.
  • base base1 base2 ... — sets the name(s) of the database(s) to search. you can give one or more databases, 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 isn't given, the client fetches from the position of the last retrieved record plus 1. if number isn't given, then one record gets fetched at a time. if resultset isn't given, the most recently retrieved result set is the one used. defaults on defaults, she contains multitudes 💅
  • scan term — scans the database index for a term. the syntax basically matches the syntax for find. so if you wanna scan for the word water, you'd write:
scan water

but if you want to scan only in, say, the title field, you'd write:

scan @attr 1=4 water
  • setscan set term — scans the database index for a term within a result set. it's like scan but its first argument is a result set instead. glow-up 🌟
  • scanpos pos — sets the preferred position for scan. this value is used in the next scan. by default, position is 1.
  • scansize size — sets the number of entries to be returned by scan. the default number of entries is 20.
  • scanstep step — sets the 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, and each sort specification is made of two space-separated words (so the whole specification list ends up being an even number of words, no cap). the first word of each specification holds a field (the sort criterion) and the second holds flags. if the sort criterion includes =, it's assumed that the SortKey is of type sortAttributes using Bib-1: in that case the integer before = is the attribute type and the integer after = is the attribute value. if there's no = character in the criterion, it's 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, plus < for ascending order or > for descending order.

example using a sort criterion with attributes use=local-number and structure=numeric and the ascending flag:

1=12,4=109 <

another example, this time with the "Title" sort field and the descending flag:

Title >
  • sort+ — same as sort, except it stores the sorted result set in a new result set. it's giving "keep both, babe" 🎀
  • authentication [auth1 [auth2 [auth3]]] — configures authentication strings to be sent to the server. zero, one, two or three 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 are separated by a slash, e.g. myusername/mysecret.

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

and just like the other commands in yaz-client, the arguments are separated by whitespace — but a backslash character can be used to include a character verbatim. for example, auth myuser a\ b is a two argument auth command where the user is myuser and the password is a b. iconic escape behaviour 💅

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. order matters, bestie.

  • sru method version — selects the Web Service method and version. method must be one of post, get, soap (that's the default) or solr. version should be either 1.1, 1.2 or 2.0 for SRU. other versions are allowed too — for testing purposes (version negotiation with an SRU server, iykyk). the version is currently not used for Solr Web Services.
  • list_all — this command displays status and values for many settings. a whole lil dashboard ✨
  • 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 ???. (yes, genuinely ???, we're all just living in it 🙈)
  • format oid — sets the preferred transfer syntax for retrieved records. yaz-client supports all the record syntaxes that are currently registered. see Z39.50 Record Syntax Identifiers[5] for more details. commonly used record syntaxes include usmarc, sutrs and xml.
  • elements e — sets the element set name for the records. many targets support the element sets B (for brief) and F (for full).
  • close — sends a Z39.50 Close APDU and closes the connection with the peer. so polite about it too 🫶
  • querytype type — sets the query type as used by the command find. this is what's 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 the attribute set OID for prefix queries (RPN, Type-1).
  • refid id — sets the 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 correspond to ILL-Profile 1 and 2 respectively. no is the Result Set position of the record to be ordered. 📦

🐚 update action recid doc

okay so this one sends an Item Update Request ✨ and it's giving very main-character energy. Here's the breakdown:

  • action — the action type. Has to be one of insert, replace, delete and update. No off-menu orders bestie.
  • recid — the record identifier. Any string you want, fr fr, it's that chill.
  • doc — optional third argument, the record document for the request. But here's the plot twist 🙈: if doc is preceded with <, then the characters that follow are treated as a filename holding the records to be updated. Otherwise doc is treated as the document itself. You can also wrap doc in double quotes 💅
  • if doc gets omitted entirely? No worries — the last received record (as part of a present response or a piggybacked search response) is used for the update. recycling era ♻️

📜 source filename

Executes a whole list of commands from the file filename, just like source on most UNIX shells. And a single dot (.) can be used as an alternative, because typing less is self-care. 🎀

💥 ! args

Executes command args in a subshell using the system call. Yes bestie, that's your little escape hatch to the shell. 🫶

🕰️ 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 — it's just getting tucked in for later 💤 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. two paths, one destiny ✨

🔌 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. That's it, that's the whole vibe. 🦋

⏳ 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 — those 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. Like, do it BEFORE, bestie, or it simply will not count 😭
⚠️ 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. (yes they really wrote "file file", iconic tbh 🎀) 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. tiny convenience, huge slay 🔥

😴 sleep seconds

This command makes YAZ client sleep (be idle) for the number of seconds given. me too honestly 💀

👀 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. the niche-est of the niche 🦋

📨 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.

🌸 EXAMPLE 🌸

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

📁 FILES 📁

  • yaz-<version>/client/client.c
  • $HOME/.yazclientrc
  • $HOME/.yazclient.history

👀 SEE ALSO 👀

👑 AUTHORS 👑

Index Data

📌 NOTES 📌

  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

and that's the whole page bestie, you made it to the end 🫶💖 this is YAZ 5.38.1, dated 10/16/2026, and it lives in the manual as YAZ-CLIENT(1). go forth and query, you gorgeous icon ✨

📦 where this page comes from