+<sect>Using the Yaz-client
+
+<p>
+yaz-client is a linemode Z39.50 client. It supports a fair amount of the
+functionality of Z39.50-1995 standard, but some things you need to enable or
+disable by recompilation. Its primary purpose is to exercise the
+package, and verify that the protocol works OK.
+
+It can be started by typing
+<tscreen><verb>
+ yaz-client [-m <marclog>] [ -a <apdulog>] tcp:<hostname>:<port>[/<database>]
+</verb></tscreen>
+at the UNIX prompt, to connect to a Z39.50 server.
+
+The options are
+<itemize>
+<item><bf/-m/ Turns dumping of the raw MARC records on in ISO 2709 format.
+Marclog is the filename to write to.
+<item><bf/-a/ Turns dumping of the APDU on. Apdulog is the filename to
+write to. If apdulog is "-" the APDU is written to the screen.
+</itemize>
+
+In order to connect to Index Data's test Z39.50 server on
+bagel.indexdata.dk, port 210 and with the database name marc, one would
+have to type
+<tscreen><verb>
+ yaz-client tcp:bagel.indexdata.dk:210/marc
+</verb></tscreen>
+In order to also dump the APDU to the screen you would have to write
+<tscreen><verb>
+ yaz-client -a - tcp:bagel.indexdata.dk:210/marc
+</verb></tscreen>
+Use '?' to get a list of the available commands.
+
+The commands are (the letters in parenthesis are short names for the commands):
+<descrip>
+<tag/open (o)/Opens a connection to a server. The syntax is the same as described above for connecting from the command line.
+<p>Syntax:
+<tscreen><verb>
+open ('tcp'|'osi')':'[<tsel>'/']<host>[':'<port>]
+</verb></tscreen>
+<tag/quit (q)/
+Ends yaz-client
+<p>Syntax:
+<tscreen><verb>
+quit
+</verb></tscreen>
+<tag/find (f)/
+Sends the RPN query to the server.
+<p>Syntax:
+<tscreen><verb>
+find <query>
+</verb></tscreen>
+<tag/delete/
+Deletes a result set on the server.
+<p>Syntax:
+<tscreen><verb>
+delete <setname>
+</verb></tscreen>
+<tag/base/
+Sets the name of the database to search in if it wasn't already set in the
+connect string. More than one database can be searched in parallel by writing
+several databases (hosted on the same server) separated by white space.
+<p>Syntax:
+<tscreen><verb>
+base <base-name>
+</verb></tscreen>
+<tag/show (s)/
+Shows a record. If no record number is specified the next record in the result set is shown.
+<p>Syntax:
+<tscreen><verb>
+show <rec#>['+'<#recs>['+'<setname>]]
+</verb></tscreen>
+<tag/scan/
+Scans the database index for a term. The syntax resembles the syntax for <bf/find/.
+If you want to scan for the word <it/water/ you would write
+<tscreen><verb>
+scan water
+</verb></tscreen>
+but if you want to scan only in, say the title field, you would write
+<tscreen><verb>
+scan @attr 1=4 water
+</verb></tscreen>
+<p>Syntax:
+<tscreen><verb>
+scan <term>
+</verb></tscreen>
+<tag/sort/
+Sorts a result set. The sort command takes a sequence of sort specifications. A sort
+specification holds a field (sort criteria) and is followed by flags.
+If the sort criteria includes = it is assumed that the sort SortKey
+is of type sortAttributes using Bib-1. The integer before the = is
+the attribute type and the integer following the = is the attribute
+value. If no = is in the SortKey it is treated as a sortfield-type
+of type InternationalString. Flags observed are
+<itemize>
+ <item><bf/s/ (sort case sensitive)
+ <item><bf/i/ (sort case insensitive), < (ascending), > (descending).
+</itemize>
+Eg.:
+<verb>
+ 1=4 i< (use is title, insensitive, ascending).
+ Title s> (String Title, sensitive, descending).
+</verb>
+<p>Syntax:
+<tscreen><verb>
+sort <sortkey> <flag> <sortkey> <flag> ...
+</verb></tscreen>
+<tag/sort+/
+Same as <bf/sort/ but stores the sorted result set in a new result set.
+<p>Syntax:
+<tscreen><verb>
+sort+ <sortkey> <flag> <sortkey> <flag> ...
+</verb></tscreen>
+<tag/authentication/
+Sets up a authentication string if a server requires authentication. The authentication string is first
+sent to the server when the <bf/open/ command is issued.
+<p>Syntax:
+<tscreen><verb>
+authentication <acctstring>
+</verb></tscreen>
+<tag/lslb/
+Sets the limit for when no records should be returned together with the search result.
+See the <htmlurl url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6" name="Z39.50 standard">
+for more details.
+<p>Syntax:
+<tscreen><verb>
+lslb <largeSetLowerBound>
+</verb></tscreen>
+<tag/ssub/
+Sets the limit for when all records should be returned with the search result.
+See the <htmlurl url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6" name="Z39.50 standard">
+for more details.
+<p>Syntax:
+<tscreen><verb>
+ssub <smallSetUpperBound>
+</verb></tscreen>
+<tag/mspn/
+Sets the number of records should be returned if the number of records in the
+result set is between the values of <bf/lslb/ and <bf/ssub/.
+See the <htmlurl url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6" name="Z39.50 standard">
+for more details.
+<p>Syntax:
+<tscreen><verb>
+mspn <mediumSetPresentNumber>
+</verb></tscreen>
+<tag/status/
+Displays the values of <bf/lslb/, <bf/ssub/ and <bf/mspn/.
+<p>Syntax:
+<tscreen><verb>
+status
+</verb></tscreen>
+<tag/setname/
+Switches named result sets on and off. Default is on.
+<p>Syntax:
+<tscreen><verb>
+setnames
+</verb></tscreen>
+<tag/cancel/
+Sends a trigger resource ctrl cancel to the server.
+<p>Syntax:
+<tscreen><verb>
+cancel
+</verb></tscreen>
+<tag/format/
+Sets the preferred transfer syntax the records should be returned in.
+yaz-client supports all the record syntaxes that corrently are registered
+with the (see the <htmlurl url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5" name="Z39.50 Agency"> for more details) including usmarc, sutrs, GRS1 and XML
+<p>Syntax:
+<tscreen><verb>
+format <recordsyntax>
+</verb></tscreen>
+<tag/schema/
+Sets the preferred schema the records should be returned in.
+<p>Syntax:
+<tscreen><verb>schema <schema>
+</verb></tscreen>
+<tag/elements/
+Sets the element set name for the records.
+<itemize>
+<item><bf/b/ Brief
+<item><bf/f/ Full
+<item>Any other element set name the server may support
+</itemize>
+<p>Syntax:
+<tscreen><verb>
+elements <elementSetName>
+</verb></tscreen>
+<tag/close/
+Sends a close request.
+<p>Syntax:
+<tscreen><verb>close
+</verb></tscreen>
+<tag/querytype/
+Sets the query type. Default is prefix.
+<itemize>
+<item><bf/prefix/ RPN query.
+<item><bf/CCL/ CCL (Common Command Language) query.
+<item><bf/ CCL2RPN/A CCL variant that is interpreted on the client side
+which allows you to specify field names. See section <ref id="CCL" name="Common Command Language"> for more details.
+</itemize>
+<p>Syntax:
+<tscreen><verb>
+querytype <type>
+</verb></tscreen>
+<tag/attributeset/
+Specifies the default attribute set in the query. Default is Bib1
+(see the <htmlurl url="http://lcweb.loc.gov/z3950/agency/defns/bib1.html" name="Z39.50 Agency">). This command applies only to the prefix querytype. Note that
+you can also specify the attribute set directly in the RPN query.
+<p>Syntax:
+<tscreen><verb>
+attributeset <attrset>
+</verb></tscreen>
+<tag/refid/
+Sets a reference id for a request to be send to the server.
+See the <htmlurl url="http://lcweb.loc.gov/z3950/agency/markup/08.html#3.4" name="Z39.50 standard">
+for more details.
+<p>Syntax:
+<tscreen><verb>
+refid <id>
+</verb></tscreen>
+<tag/itemorder/
+Sends an itemorder to the server. Only the required fields are implemented.
+<p>Syntax:
+<tscreen><verb>
+itemorder 1|2 <item>
+</verb></tscreen>
+<tag/update/
+Sends an item update to the server. This feature is not fully implemented yet.
+<p>Syntax:
+<tscreen><verb>
+update <item>
+</verb></tscreen>
+</descrip>
+<sect1>Searching with yaz-client
+<p>
+The simplest form of a RPM query in yaz-client would be something like
+<tscreen><verb>
+ f knuth
+</verb></tscreen>
+or
+<tscreen><verb>
+ f "donald knuth"
+</verb></tscreen>
+This leaves it up to the server what fields to search but most servers will search
+in all fields. Some servers does not support this feature though, and require that
+a search attribute is defined. This would look something like this in yaz-client:
+<tscreen><verb>
+ f @attr 1=4 computer
+</verb></tscreen>
+where we search in the title field. If we want to search in the author field <bf/and/
+in the title field, and in the title field using right truncation it could look something like this:
+<tscreen><verb>
+ f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
+</verb></tscreen>
+Finally using a mix of Bib-1 and GILS attributes could look something like this:
+<tscreen><verb>
+ f @attrset Bib-1 @and @attr GILS 2=2008 Washington @attr 1=21 weather
+</verb></tscreen>
+For the full spacifiction of the RPN query language please see the section <ref id="PQF" name="Prefix Query Format">.
+