From: Adam Dickmeiss Date: Wed, 23 Oct 2002 10:14:11 +0000 (+0000) Subject: Man page for yaz-proxy. Section on encoding details for otherinfo. X-Git-Tag: YAZPP.0.5~32 X-Git-Url: http://git.indexdata.com/?p=yazpp-moved-to-github.git;a=commitdiff_plain;h=09b40382c41a29b7e3de2fa1a0362f25422a4367 Man page for yaz-proxy. Section on encoding details for otherinfo. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index eb1be21..790b9cd 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.2 2002-10-09 16:17:26 adam Exp $ +## $Id: Makefile.am,v 1.3 2002-10-23 10:14:11 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ SUPPORTFILES = \ @@ -10,19 +10,26 @@ XMLFILES = \ installation.xml \ zoom.xml \ proxy.xml \ + yaz-proxy-ref.xml \ + yaz-proxy-man.sgml \ yaz++.xml.in TOP=yaz++.xml - +MANFILES=yaz-proxy.8 HTMLFILES = yazpp.html installation.html zoom.html proxy.html doc_DATA = $(HTMLFILES) yaz++.pdf -EXTRA_DIST = $(SUPPORTFILES) $(XMLFILES) yaz++.pdf +man_MANS = $(MANFILES) + +EXTRA_DIST = $(SUPPORTFILES) $(XMLFILES) yaz++.pdf yaz-proxy.8 $(HTMLFILES): $(XMLFILES) jade -E14 -D $(srcdir) -d yazhtml.dsl -t sgml $(srcdir)/xml.dcl $(TOP) +yaz-proxy.8: yaz-proxy-man.sgml yaz-proxy-ref.xml + docbook2man $(srcdir)/yaz-proxy-man.sgml + yaz++.php: $(XMLFILES) jade -E14 -D $(srcdir) -d yazphp.dsl -t sgml $(srcdir)/xml.dcl $(TOP) diff --git a/doc/proxy.xml b/doc/proxy.xml index cf76fe6..b7ae0d3 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -130,7 +130,9 @@ If the InitializeRequest PDU from the - client includes an otherInfo element with OID + client includes an + otherInfo + element with OID 1.2.840.10003.10.1000.81.1, then the contents of that element specify the target to be used, in the usual YAZ address format (typically @@ -170,14 +172,14 @@ guarantee that the Z39.50 connection to the backend target is kept forever: the proxy will shut it down after certain idle time. - So in effect, the connection from the client's point of view should be considered stateless, and the keep-alive facility should be treated only as a performance booster. - Cookies may be passed in an otherInfo element - with OID 1.2.840.10003.10.1000.81.2. + Cookies may be passed in an + otherInfo + element with OID 1.2.840.10003.10.1000.81.2. @@ -196,15 +198,15 @@ backend target, so that if an identical query is received next, it is turned into Present Requests rather than new Search Requests. - + + + In a future we release will will probably allows for + an arbitrary-sized cache for targets supporting named result sets. + + - This optimization should work for any Z39.50 client and/or - target. The target does not have to support named result sets. + You can enable/disable query caching using option -o. -
@@ -220,143 +222,37 @@ - - yaz-proxy - 8 - - - yaz-proxy - The YAZ toolkit's transparent Z39.50 proxy - - - - yaz-proxy - -a filename - -c num - -v level - -t target - -u auth - -o level - host:port - - - - DESCRIPTION - - The proxy runs stand-alone (not from - inetd). The - host:port - argument specifies host address to listen to, and the port to - listen on. Use the host @ - to listen for connections coming from any address. - - - OPTIONS - - -a filename - - Specifies the name of a file to which to write a log of the - APDUs (protocol packets) that pass through the proxy. The - special filename - may be used to indicate - standard output. - - - -c num - - Specifies the maximum number of connections to be cached - [default 50]. - - - -v level - - Sets the logging level. level is - a comma-separated list of members of the set - {fatal,debug,warn,log,malloc,all,none}. - - - -t target - - Specifies the default backend target to use when a client - connects that does not explicitly specify a target in its - initRequest. - - - -u auth - - Specifies authentication info to be sent to the backend target. - This is useful if you happen to have an internal target that - requires authentication, or if the client software does not allow - you to set it. - - - -o level - - Sets level for optimization. Use zero to disable; non-zero - to enable. Handling for this is not fully implemented; - we will probably use a bit mask to enable/disable specific - features. - - - - - - EXAMPLES - - The following command starts the proxy, listening on port - 9000, with its default backend target set to the Library of - Congress bibliographic server: - - - $ yaz-proxy -t z3950.loc.gov:7090 @:9000 - - - The LOC target is sometimes very slow. You can connect to - it using yaz-client as follows: - - - $ yaz-client localhost:9000/voyager - Connecting...Ok. - Sent initrequest. - Connection accepted by target. - ID : 34 - Name : Voyager LMS - Z39.50 Server - Version: 1.13 - Options: search present - Elapsed: 7.131197 - Z> f computer - Sent searchRequest. - Received SearchResponse. - Search was a success. - Number of hits: 10000 - records returned: 0 - Elapsed: 6.695174 - Z> f computer - Sent searchRequest. - Received SearchResponse. - Search was a success. - Number of hits: 10000 - records returned: 0 - Elapsed: 0.001417 - - - In this test, the second search was more than 4000 times faster - than the first, because the proxy cached the result of the first - search and noticed that the second was the same. - - - The YAZ command-line client, - yaz-client, - allows you to set the backend target in - the initRequest using the - -p option. For example, to connect to - Index Data's target you could use: - - - yaz-client -p indexdata.dk localhost:9000/gils - - + &yaz-proxy-ref;
+
Otherinformation Encoding + + The proxy uses the OtherInformation definition to carry + information about the target address and cookie. + + + OtherInformation ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{ + category [1] IMPLICIT InfoCategory OPTIONAL, + information CHOICE{ + characterInfo [2] IMPLICIT InternationalString, + binaryInfo [3] IMPLICIT OCTET STRING, + externallyDefinedInfo [4] IMPLICIT EXTERNAL, + oid [5] IMPLICIT OBJECT IDENTIFIER}} +-- + InfoCategory ::= SEQUENCE{ + categoryTypeId [1] IMPLICIT OBJECT IDENTIFIER OPTIONAL, + categoryValue [2] IMPLICIT INTEGER} + + + The categoryTypeId is either + OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2 + for proxy target and proxy cookie respectively. The + integer element category is set to 0. + The value proxy and cookie is stored in element + characterInfo of the information + choice. + +
+ YAZ++ diff --git a/doc/yaz-proxy-man.sgml b/doc/yaz-proxy-man.sgml new file mode 100644 index 0000000..d55c148 --- /dev/null +++ b/doc/yaz-proxy-man.sgml @@ -0,0 +1,33 @@ + +]> + + + &yaz-proxy-ref; + SEE ALSO + + + yaz + 7 + + + yaz-client + 1 + + + + + diff --git a/doc/yaz-proxy-ref.xml b/doc/yaz-proxy-ref.xml new file mode 100644 index 0000000..c643b57 --- /dev/null +++ b/doc/yaz-proxy-ref.xml @@ -0,0 +1,156 @@ + + yaz-proxy + 8 + + + yaz-proxy + The YAZ toolkit's transparent Z39.50 proxy + + + + yaz-proxy + -a filename + -c num + -v level + -t target + -u auth + -o level + -i seconds + host:port + + + +DESCRIPTION + + The proxy runs stand-alone (not from + inetd). The + host:port + argument specifies host address to listen to, and the port to + listen on. Use the host @ + to listen for connections coming from any address. + + +OPTIONS + + -a filename + + Specifies the name of a file to which to write a log of the + APDUs (protocol packets) that pass through the proxy. The + special filename - may be used to indicate + standard output. + + + -c num + + Specifies the maximum number of connections to be cached + [default 50]. + + + -v level + + Sets the logging level. level is + a comma-separated list of members of the set + {fatal,debug,warn,log,malloc,all,none}. + + + -t target + + Specifies the default backend target to use when a client + connects that does not explicitly specify a target in its + initRequest. + + + -u auth + + Specifies authentication info to be sent to the backend target. + This is useful if you happen to have an internal target that + requires authentication, or if the client software does not allow + you to set it. + + + -o level + + Sets level for optimization. Use zero to disable; non-zero + to enable. Handling for this is not fully implemented; + we will probably use a bit mask to enable/disable specific + features. By default optimization is enabled (value 1). + + + -i seconds + + Specifies in seconds the idle time for communication + for proxy. If a connection is inactive for this long + it willl be closed. Default: 600 seconds (10 minutes). + + + + + + EXAMPLES + + The following command starts the proxy, listening on port + 9000, with its default backend target set to the Library of + Congress bibliographic server: + + + $ yaz-proxy -t z3950.loc.gov:7090 @:9000 + + + The LOC target is sometimes very slow. You can connect to + it using yaz-client as follows: + + + $ yaz-client localhost:9000/voyager + Connecting...Ok. + Sent initrequest. + Connection accepted by target. + ID : 34 + Name : Voyager LMS - Z39.50 Server + Version: 1.13 + Options: search present + Elapsed: 7.131197 + Z> f computer + Sent searchRequest. + Received SearchResponse. + Search was a success. + Number of hits: 10000 + records returned: 0 + Elapsed: 6.695174 + Z> f computer + Sent searchRequest. + Received SearchResponse. + Search was a success. + Number of hits: 10000 + records returned: 0 + Elapsed: 0.001417 + + + In this test, the second search was more than 4000 times faster + than the first, because the proxy cached the result of the first + search and noticed that the second was the same. + + + The YAZ command-line client, + yaz-client, + allows you to set the proxy target as part of the Initialize + Request using option -p. + For example, to connect to Index Data's target you could use: + + + yaz-client -p indexdata.dk localhost:9000/gils + + +