From 5411affe4d00fc2d7bb4e8c907c53d4c085a44ce Mon Sep 17 00:00:00 2001 From: "Per M. Hansen" Date: Thu, 31 Aug 2000 14:20:34 +0000 Subject: [PATCH] A chapter about the yaz-client was added to the documentation. --- doc/yaz.sgml | 299 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 280 insertions(+), 19 deletions(-) diff --git a/doc/yaz.sgml b/doc/yaz.sgml index 050344e..12497a1 100644 --- a/doc/yaz.sgml +++ b/doc/yaz.sgml @@ -2,7 +2,7 @@
YAZ User's Guide and Reference <author><htmlurl url="http://www.indexdata.dk/" name="Index Data">, <tt><htmlurl url="mailto:info@indexdata.dk" name="info@indexdata.dk"></> -<date>$Revision: 1.6 $ +<date>$Revision: 1.7 $ <abstract> This document is the programmer's guide and reference to the YAZ package. YAZ is a compact toolkit that provides access to the @@ -102,7 +102,7 @@ is incompatible with the <bf/COMSTACK/ interface or some other part of <bf/YAZ/. The latest version of the software will generally be found at <tscreen><verb> -http://ftp.indexdata.dk/pub/yaz/ +<htmlurl url="http://ftp.indexdata.dk/pub/yaz/" name="http://ftp.indexdata.dk/pub/yaz/"> </verb></tscreen> We have tried our best to keep the software portable, and on many @@ -202,7 +202,7 @@ The following files are generated by the make process: settings for <bf/YAZ/. <tag><tt>yaz-comp</tt></tag> The ASN.1 compiler for YAZ. Requires the -Tcl Shell, tclsh, in current path to work. +Tcl Shell, tclsh, in current path to work. </descrip> @@ -265,6 +265,267 @@ except the frontend server library. <tag><tt>bin/yaz-client.exe</tt></tag> A command mode Z39.50 client. </descrip> +<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">. + <sect>The ASN Module <sect1>Introduction @@ -524,7 +785,7 @@ you suspect of being an ASN.1-structured data value, you can use <tt/z_ext_gettypebyref/ to look for the provided direct-reference. If the return value is different from NULL, you can use the provided function to decode the BER string (see section <ref id="odr-use" -name="Using ODR">). +name="Using ODR">). If you want to <it/send/ EXTERNALs containing ASN.1-structured values in the occtet-aligned branch of the CHOICE, this is possible too. @@ -788,7 +1049,7 @@ the query manually, perhaps using <tt/odr_malloc()/ to simplify memory management. The YAZ distribution includes two separate, query-generating tools that may be of use to you. -<sect2>Prefix Query Format +<sect2>Prefix Query Format<label id="PQF"> <p> Since RPN or reverse polish notation is really just a fancy way of @@ -895,7 +1156,7 @@ dylan @prox 0 3 1 2 k 2 dylan zimmerman </verb></tscreen> -<sect2>Common Command Language +<sect2>Common Command Language<label id="CCL"> <p> Not all users enjoy typing in prefix query structures and numerical @@ -975,7 +1236,7 @@ set=1 (dylan and bob) or set=1 </verb></tscreen> -Assuming that the qualifiers <tt/ti/, <tt/au/ and <tt/date/ +Assuming that the qualifiers <tt/ti/, <tt/au/ and <tt/date/ are defined we may use: <tscreen><verb> ti=self portrait @@ -1232,7 +1493,7 @@ int *oid_ent_to_oid(struct oident *ent, int *dst); Takes as argument an <tt/oident/ structure - in which the <it/proto/, <it/oclass/, and <it/value/ fields are assumed to be set correctly - -and returns a pointer to a the buffer as given by <it/dst/ +and returns a pointer to a the buffer as given by <it/dst/ containing the base representation of the corresponding OID. The function returns NULL and the array dst is unchanged if a mapping couldn't place. @@ -2228,7 +2489,7 @@ int myChoice(ODR o, MyChoice **p, int optional, const char *name) static Odr_arm arm[] = { {-1, -1, -1, MyChoice_untagged, odr_integer, "untagged"}, - {ODR_IMPLICIT, ODR_CONTEXT, 99, MyChoice_tagged, odr_integer, + {ODR_IMPLICIT, ODR_CONTEXT, 99, MyChoice_tagged, odr_integer, "tagged"}, {-1, -1, -1, MyChoice_other, odr_boolean, "other"}, {-1, -1, -1, -1, 0} @@ -2310,7 +2571,7 @@ of losing generality, and it may prove that the interface will need extension later on. The interface is implemented in such a fashion that only the -sub-layers constructed to the transport methods that you wish to +sub-layers constructed to the transport methods that you wish to use in your application are linked in. You will note that even though simplicity was a goal in the design, @@ -2424,14 +2685,14 @@ to check if there's a full protocol package already read. If <tt/cs_more()/ returns 1, <tt/cs_get()/ -can be used to immediately fetch the new package. For the +can be used to immediately fetch the new package. For the mOSI subsystem, the function should always return 0, but if you want your stuff to be protocol independent, you should use it. <it> NOTE: The <tt/cs_more()/ -function is required because the +function is required because the RFC1729-method does not provide a way of separating individual PDUs, short of partially decoding the BER. Some other implementations will carefully @@ -3113,7 +3374,7 @@ are required to establish a mapping between the set name and whatever your backend database likes to use. Similarly, the <tt/replace_set/ is a boolean value corresponding to the resultSetIndicator field in the protocol. <tt>Num_bases/basenames</tt> is a length of/array of character -pointers to the database names provided by the client. The <tt/query/ is the +pointers to the database names provided by the client. The <tt/query/ is the full query structure as defined in the protocol ASN.1 specification. It can be either of the possible query types, and it's up to you to determine if you can handle the provided query type. Rather than @@ -3524,15 +3785,15 @@ We'll be happy to answer questions about the software, and about ourselves in general. <tscreen><verb> -Index Data -Ryesgade 3 -DK-2200 Copenhagen N +Index Data Aps +Købmagergade 43 +DK-1150 Copenhagen K </verb></tscreen> <p> <tscreen><verb> -Phone: +45 3536 3672 -Fax : +45 3536 0449 +Phone: +45 3341 0100 +Fax : +45 3341 0101 Email: info@indexdata.dk </verb></tscreen> @@ -3547,7 +3808,7 @@ topic is not original, though the content is. As in &dquot;Yet Another AI Group&dquot; or &dquot;Yet Another Simulated Annealing Algorithm&dquot;. 2. Of others' work: Describes something of which there are already far -too many. +too many. </it> </article> -- 1.7.10.4