From: Adam Dickmeiss Date: Wed, 24 Oct 2001 09:27:59 +0000 (+0000) Subject: More ZOOM documentation. XML Docbook is now part of "make dist". X-Git-Tag: YAZ.1.8~18 X-Git-Url: http://sru.miketaylor.org.uk/cgi-bin?a=commitdiff_plain;h=33c05384cfbca55da4ff97e5b2047b16596c72f7;p=yaz-moved-to-github.git More ZOOM documentation. XML Docbook is now part of "make dist". --- diff --git a/doc/Makefile.am b/doc/Makefile.am index dc42a5e..d35992d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,45 +1,33 @@ -## $Id: Makefile.am,v 1.15 2001-10-23 21:00:19 adam Exp $ +## $Id: Makefile.am,v 1.16 2001-10-24 09:27:59 adam Exp $ docdir=$(pkgdatadir)/doc -doc_DATA = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \ - yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \ - yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \ - yaz-6.html yaz-7.html yaz-8.html yaz-9.html - -EXTRA_DIST = $(srcdir)/yaz.sgml $(srcdir)/profiles.sgml \ - yaz.txt yaz.ps profiles.txt profiles.ps yaz.html \ - yaz-1.html yaz-2.html yaz-3.html yaz-4.html yaz-5.html \ - yaz-6.html yaz-7.html yaz-8.html yaz-9.html - -yaz.txt: $(srcdir)/yaz.sgml - sgml2txt -f $(srcdir)/yaz.sgml - -yaz.dvi: $(srcdir)/yaz.sgml - sgml2latex -p a4 -o dvi $(srcdir)/yaz.sgml - -yaz.ps: $(srcdir)/yaz.sgml - sgml2latex -p a4 -o ps $(srcdir)/yaz.sgml - -profiles.txt: $(srcdir)/profiles.sgml - sgml2txt -f $(srcdir)/profiles.sgml - -profiles.dvi: $(srcdir)/profiles.sgml - sgml2latex -p a4 -o dvi $(srcdir)/profiles.sgml - -profiles.ps: $(srcdir)/profiles.sgml - sgml2latex -p a4 -o ps $(srcdir)/profiles.sgml - -yaz.html: $(srcdir)/yaz.sgml - sgml2html $(srcdir)/yaz.sgml - XMLFILES=$(srcdir)/yaz.xml $(srcdir)/introduction.xml \ $(srcdir)/installation.xml $(srcdir)/indexdata.xml $(srcdir)/asn.xml \ $(srcdir)/tools.xml $(srcdir)/odr.xml $(srcdir)/comstack.xml \ $(srcdir)/frontend.xml $(srcdir)/license.xml $(srcdir)/future.xml \ $(srcdir)/client.xml $(srcdir)/zoom.xml -$(srcdir)/book1.html: $(XMLFILES) $(srcdir)/yazhtml.dsl +HTMLFILES = asn.external.html asn.html asn.oid.html asn.pdu.html \ + asn.preparing.html client.commands.html client.html client.invoking.html \ + client.searching.html comstack.addresses.html comstack.client.html \ + comstack.common.html comstack.diagnostics.html comstack.html \ + comstack.introduction.html comstack.server.html comstack.summary.html \ + future.html indexdata.html installation.html installation.win32.html \ + introduction.html license.html license.other.html odr.debugging.html \ + odr.html odr.programming.html odr.use.html server.backend.html \ + server.backendfunctions.html server.frontend.html server.html \ + server.invocation.html server.main.html tools.html tools.nmem.html \ + tools.oid.html yaz.html zoom.events.html zoom.html zoom.options.html \ + zoom.records.html zoom.resultsets.html zoom.search.html + +DOCFILES=$(XMLFILES) $(HTMLFILES) yaz.pdf + +EXTRA_DIST = $(DOCFILES) + +doc_DATA = $(DOCFILES) + +$(srcdir)/yaz.html: $(XMLFILES) $(srcdir)/yazhtml.dsl cd $(srcdir); jade -E14 -d yazhtml.dsl -t sgml xml.dcl yaz.xml $(srcdir)/book1.php: $(XMLFILES) $(srcdir)/yazphp.dsl diff --git a/doc/asn.xml b/doc/asn.xml index 2e3f836..3f378c4 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,6 +1,6 @@ - - The ASN Module - Introduction + + The ASN Module + Introduction The &asn; module provides you with a set of C struct definitions for the various PDUs of the protocol, as well as for the complex types @@ -12,7 +12,7 @@ provides auxiliary definitions. - Preparing PDUs + Preparing PDUs A structure representing a complex ASN.1 type doesn't in itself contain the @@ -125,7 +125,7 @@ - Object Identifiers + Object Identifiers When you refer to object identifiers in your application, you need to be aware that SR and Z39.50 use two different set of OIDs to refer to @@ -187,7 +187,7 @@ struct oident *oid_getentbyoid(int *o); - EXTERNAL Data + EXTERNAL Data In order to achieve extensibility and adaptability to different @@ -333,7 +333,7 @@ typedef struct Z_ext_typeent - PDU Contents Table + PDU Contents Table We include, for reference, a listing of the fields of each top-level diff --git a/doc/client.xml b/doc/client.xml index 54fdee5..2995c50 100644 --- a/doc/client.xml +++ b/doc/client.xml @@ -1,6 +1,6 @@ - - The YAZ client - Introduction + + The YAZ client + Introduction yaz-client is a line-mode Z39.50 client. It supports a fair amount of the functionality of the Z39.50-1995 standard, but some things you @@ -13,7 +13,7 @@ Services (ItemOrder, ItemUpdate,..). - Invoking the YAZ client + Invoking the YAZ client It can be started by typing @@ -88,7 +88,7 @@ yaz-client -a - localhost - YAZ client commands + YAZ client commands When the YAZ client has read options and connected to a target, if given, it will display Z > and away your command. @@ -190,12 +190,12 @@ - + sort sortspecs - Sorts a result set. The sort command takes a sequence of - sort specifications. A 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. @@ -392,7 +392,7 @@ - Searching + Searching The simplest example of a Prefix Query would be something like diff --git a/doc/comstack.xml b/doc/comstack.xml index 671788a..9ae8df0 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,7 +1,7 @@ - - The COMSTACK Module + + The COMSTACK Module - Synopsis (blocking mode) + Synopsis (blocking mode) @@ -52,7 +52,7 @@ if (buf) - Introduction + Introduction The &comstack; @@ -87,7 +87,7 @@ if (buf) - Common Functions + Common Functions Managing Endpoints @@ -277,7 +277,7 @@ if (buf) - Client Side + Client Side int cs_connect(COMSTACK handle, void *address); @@ -305,7 +305,7 @@ if (buf) - Server Side + Server Side To establish a server under the inetd server, you @@ -378,7 +378,7 @@ if (buf) - Addresses + Addresses The low-level format of the addresses are different depending on the @@ -465,7 +465,7 @@ if (buf) - Diagnostics + Diagnostics All functions return -1 if an error occurs. Typically, the functions @@ -510,169 +510,7 @@ if (buf) provided. - - Enabling OSI Communication - - Installing Xtimosi - - Although you will have to down-load Peter Furniss' XTI/mOSI - implementation for yourself, we've tried to make the integration as - simple as possible. - - - - The latest version of xtimosi will generally be under - - - - ftp://pluto.ulcc.ac.uk/ulcc/thinosi/xtimosi/ - - - - When you have down-loaded and unpacked the archive, it will (we assume) - have created a directory called xtimosi. - We suggest that you place this directory in the same - directory where you unpacked the &yaz; - distribution. This way, you shouldn't have to fiddle with the - makefiles of &yaz; beyond uncommenting a few lines. - - - - Go to xtimosi/src, and type "make libmosi.a/". - This should generally create the library, ready to use. - - - - - The currently available release of xtimosi has some inherent - problems that make it disfunction on certain platforms - eg. the - Digital OSF/1 workstations. It is supposedly primarily a - compiler problem, and we hope to see a release that is generally - portable. While we can't guarantee that it can be brought to work - on your platform, we'll be happy to talk to you about problems - that you might see, and relay information to the author of the - software. There are some signs that the gcc - compiler is more likely to produce a fully functional library, but this - hasn't been verified (we think that the problem is limited to the use - of hexadecimal escape-codes used in strings, which are silently - ignored by some compilers). - - - A problem has been encountered in the communication with - ISODE-based applications. If the ISODE presentation-user calls - PReadRequest() with a timeout value different - from OK or NOTOK, - he will get an immediate TIMEOUT abort when receiving large (>2041 - bytes, which is the SPDU-size that the ISODE likes to work with) packages - from an xtimosi-based implementation (probably most - other implementations as well, in fact). It seems to be a flaw in the - ISODE API, and the workaround (for ISODE users) is to either not - use an explicit timeout (switching to either blocking or - nonblocking mode), or to check that the timer really has expired - before closing the connection. - - - - - The next step in the installation is to modify the makefile in the toplevel - &yaz; - directory. The place to change is in the top of the file, and is - clearly marked with a comment. - - - - Now run make in the &yaz; toplevel directory (do a - make clean first, if the system has been previously - made without OSI support). Use the &yaz; - yaz-ztest and yaz-client - demo programs to verify that OSI communication works OK. Then, you can go - ahead and try to talk to other implementations. - - - - - Our interoperability experience is limited to version - 7 of the Nordic SR-Nett package, which has had several - protocol errors fixed from the earlier releases. If you have - problems or successes in interoperating with other - implementations, we'd be glad to hear about it, or to help - you make things work, as our resources allow. - - - - - If you write your own applications based on &yaz;, and you wish to - include OSI support, the procedure is equally simple. You should - include the xmosi.h header file in addition to - comstack.h. xmosi.h - will define the manifest constant mosi_type, which you - should pass to the cs_create() function. In - addition, you should use the function mosi_strtoaddr() - rather than tcpip_strtoaddr() when you need to - prepare an address. - - - - When you link your application, you should include (after the - libyaz.a library) the libmosi.a - library, and the librfc.a library provided with - &yaz; (for OSI transport). - - - As always, it can be very useful, if not essential, to have a look at the - example applications to see how things are done. - - - - OSI Transport - - - Xtimosi requires an implementation of the OSI transport service under - the X/OPEN XTI API. We provide an implementation of the RFC1006 - encapsulation of OSI/TP0 in TCP/IP (through the Berkeley Sockets API), - as an independent part of &yaz; (it's found under the - rfc1006 directory). - If you have access to an OSI transport provider under XTI, - you should be able to make that work too, although it may require - tinkering with the mosi_strtoaddr() function. - - - - Presentation Context Management - - - To simplify the implementation, we use Peter Furniss' alternative (PRF) - option format - for the Control of the presentation negotiation phase. This format - is enabled by default when you - compile xtimosi. - - - - The current version of &yaz; does not support - presentation-layer negotiation of response record formats. The primary - reason is that we have had access to no other SR or Z39.50 - implementations over OSI that used this - method. Secondarily, we believe that the EXPLAIN facility is a superior - mechanism for relaying target capabilities in this respect. This is not to - say that we have no intentions of supporting presentation context - negotiation - we have just hitherto given it a lower priority than other - aspects of the protocol. - - - One thing is certain: The addition of this capability to &yaz; should - have only a minimal impact on existing applications, and on the - interface to the software in general. Most likely, we will add an extra - layer of interface to the processing of EXPLAIN records, which will - convert back and forth between oident records (see - section Object Identifiers) and direct or - indirect references, given the current association setup. Implementations - based on any of the higher-level interfaces will most likely not have to - be changed at all. - - - - Summary and Synopsis + Summary and Synopsis #include <comstack.h> diff --git a/doc/frontend.xml b/doc/frontend.xml index 391ca9d..0673c3d 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,5 +1,5 @@ - - Making an IR Server for Your Database + + Making an IR Server for Your Database Introduction @@ -45,7 +45,7 @@ - The Database Frontend + The Database Frontend We refer to this software as a generic database frontend. Your @@ -102,7 +102,7 @@ - The Backend API + The Backend API The headers files that you need to use the interface are in the @@ -117,7 +117,7 @@ - Your main() Routine + Your main() Routine As mentioned, your main() routine can be quite brief. @@ -304,7 +304,7 @@ void statserv_setcontrol(statserv_options_block *block); - The Backend Functions + The Backend Functions For each service of the protocol, the backend interface declares one or @@ -672,7 +672,7 @@ typedef struct bend_scan_rr { - Application Invocation + Application Invocation The finished application has the following diff --git a/doc/future.xml b/doc/future.xml index 7278081..937c7f3 100644 --- a/doc/future.xml +++ b/doc/future.xml @@ -1,5 +1,5 @@ - - Future Directions + + Future Directions We have a new and better version of the front-end server on the drawing diff --git a/doc/indexdata.xml b/doc/indexdata.xml index 4dc2b4e..bc18a62 100644 --- a/doc/indexdata.xml +++ b/doc/indexdata.xml @@ -1,5 +1,5 @@ - - About Index Data + + About Index Data Index Data is a consulting and software-development enterprise that diff --git a/doc/installation.xml b/doc/installation.xml index 6d5c09f..7c9c6e3 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,5 +1,5 @@ - - Compilation and Installation + + Compilation and Installation The latest version of the software will generally be found at @@ -59,7 +59,7 @@ , or the address given at the top of this document. - UNIX + UNIX Note that if your system doesn't have a native ANSI C compiler, you may @@ -185,7 +185,7 @@ - WIN32 + WIN32 &yaz; is shipped with "makefiles" for the NMAKE tool that comes @@ -283,4 +283,4 @@ sgml-namecase-general:t End: --> - \ No newline at end of file + diff --git a/doc/introduction.xml b/doc/introduction.xml index 5222a2d..470344b 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,5 +1,5 @@ - - Introduction + + Introduction The &yaz; toolkit offers several different levels of access to the diff --git a/doc/license.xml b/doc/license.xml index e07567d..0762b36 100644 --- a/doc/license.xml +++ b/doc/license.xml @@ -1,16 +1,16 @@ - - License + + License - Index Data Copyright + Index Data Copyright Copyright © 1995-2001 Index Data. - Permission to use, copy, modify, distribute, and sell this software and - its documentation, in whole or in part, for any purpose, is hereby granted, - provided that: + Permission to use, copy, modify, distribute, and sell this + software and its documentation, in whole or in part, for any + purpose, is hereby granted, provided that: @@ -37,7 +37,7 @@ OF THIS SOFTWARE. - Additional Copyright Statements + Additional Copyright Statements The optional CCL query language interpreter is covered by the following diff --git a/doc/odr.xml b/doc/odr.xml index 2623c1f..dbba5dd 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,7 +1,7 @@ - - The ODR Module + + The ODR Module - Introduction + Introduction &odr; is the BER-encoding/decoding subsystem of &yaz;. Care as been taken @@ -37,7 +37,7 @@ - Using ODR + Using ODR ODR Streams @@ -480,7 +480,7 @@ void do_nothing_useful(int value) - Programming with ODR + Programming with ODR The API of &odr; is designed to reflect the structure of ASN.1, rather @@ -1219,7 +1219,7 @@ void odr_choice_bias(ODR o, int what); - Debugging + Debugging The protocol modules are suffering somewhat from a lack of diagnostic diff --git a/doc/tools.xml b/doc/tools.xml index a17b902..47af988 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,5 +1,5 @@ - - Supporting Tools + + Supporting Tools In support of the service API - primarily the ASN module, which @@ -7,7 +7,7 @@ a collection of tools that support the development of applications. - Query Syntax Parsers + Query Syntax Parsers Since the type-1 (RPN) query structure has no direct, useful string @@ -386,7 +386,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, - Object Identifiers + Object Identifiers The basic YAZ representation of an OID is an array of integers, @@ -632,7 +632,7 @@ typedef struct oident - Nibble Memory + Nibble Memory Sometimes when you need to allocate and construct a large, diff --git a/doc/yaz.xml b/doc/yaz.xml index 0ee6c82..bc2450b 100644 --- a/doc/yaz.xml +++ b/doc/yaz.xml @@ -21,8 +21,8 @@ COMSTACK"> ZOOM"> ]> - - + + YAZ User's Guide and Reference SebastianHammer diff --git a/doc/yazhtml.dsl b/doc/yazhtml.dsl index 8e71d9e..3342606 100644 --- a/doc/yazhtml.dsl +++ b/doc/yazhtml.dsl @@ -3,12 +3,14 @@ CDATA DSSSL> ]> +(define %use-id-as-filename% #t) +(define %output-dir% "html") (define %html-ext% ".html") (define %shade-verbatim% #t) diff --git a/doc/yazphp.dsl b/doc/yazphp.dsl index ad25e61..e621b42 100644 --- a/doc/yazphp.dsl +++ b/doc/yazphp.dsl @@ -3,12 +3,14 @@ CDATA DSSSL> ]> +(define %use-id-as-filename% #t) +(define %output-dir% "php") (define %html-ext% ".php") (define %shade-verbatim% #t) diff --git a/doc/zoom.xml b/doc/zoom.xml index 1a0aa9e..ff34527 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,5 +1,5 @@ - - ZOOM + + ZOOM &zoom; is an acronym for Z39.50 Object Oriented Model and is @@ -37,10 +37,9 @@ that because of typedefs. All destroy methods should gracefully ignore a NULL pointer. - Connections + Connections - The connection object Z3950_connection describes - the connection between your client and a server. + The Connection object is a session with a target. #include <yaz/zoom.h> @@ -76,6 +75,7 @@ const char *Z3950_connection_option (Z3950_connection c, const char *key, const char *val); + const char *Z3950_connection_host (Z3950_connection c); The Z3950_connection_option allows you to @@ -87,13 +87,51 @@ the option is unchanged. The function returns the previous value of the option. - - const char *Z3950_connection_host (Z3950_connection c); - - + ZOOM Connection Options + + + + + + + Option + Description + Default + + + + + implementationNameName of Your client + none + + userAuthentication user name + none + + groupAuthentication group name + none + + passAuthentication password + none + + proxyProxy host + none + + asyncIf true (1) the connection operates in + asynchronous operatio which means that all calls are non-blocking + except Z3950_event. + 0 + + maximumRecordSize Maximum size of single record. + 1 MB + + preferredMessageSize Maximum size of multiple records. + 1 MB + + +
Function Z3950_connection_host returns - the host for the connection as specified in either a call to + the host for the connection as specified in a call to Z3950_connection_new or Z3950_connection_connect. This function returns NULL if host isn't @@ -112,7 +150,7 @@ non-NULL. - Search objects + Search objects Search objects defines how result sets are obtained. They act like queries. @@ -129,19 +167,21 @@ Create search objects using Z3950_search_create and destroy them by calling Z3950_search_destroy. - RPN-queries can be specified in PQF notation by using the + RPN-queries can be specified in PQF + notation by using the function Z3950_search_prefix. More - query types will be added later, such as CCL to RPN-mapping, CCL - query, etc. - In addition to a search a sort critieria may be set. Function - Z3950_search_sortby specifies a sort - criteria using the same string notation for sort as offered by - the YAZ client. + query types will be added later, such as + CCL to RPN-mapping, native CCL query, + etc. In addition to a search, a sort critieria may be set. Function + Z3950_search_sortby specifies a + sort criteria using the same string notation for sort as offered by + the YAZ client. - Result sets + Result sets - The result set describes a collection of records obtained from + The result set object is a container for records returned from + a target. search. @@ -158,9 +198,8 @@ a result set given a connection - and search object. Destroy a result set by calling Z3950_resultset_destroy. - Simple clients using YAZ' prefix query format may use - function Z3950_connection_search_pqf - instead. + Simple clients using PQF only may use function + Z3950_connection_search_pqf instead. const char *Z3950_resultset_option (Z3950_resultset r, @@ -171,32 +210,118 @@ void *Z3950_resultset_get (Z3950_resultset s, int pos, const char *type, int *len); - void Z3950_resultset_records (Z3950_resultset r, - Z3950_record *recs, - size_t *cnt); - Description of result sets here. + Function X3950_resultset_options sets or + modifies an option for a result set similar to + Z3950_connection_option. + + The number of hits also called result-set is returned by + function 3950_resultset_size. + + + Function Z3950_resultset_get is similar to + + Z3950_record_get but + instead of operating on a record object it operates on a record on + a given offset within a result set. + + ZOOM Result set Options + + + + + + + Option + Description + Default + + + + + piggybackTrue (1) if piggyback should be + used in searches; false (0) if not. + 1 + + startOffset of first record we wish to + retrieve from the target. Note first record has offset 0 + unlike the protocol specifications where first record has position + 1. + 0 + + countNumber of records to be retrieved. + 0 + + elementSetNameElement-Set name of records. + Most targets should honor element set name B + and F for brief and full respectively. + none + + preferredRecordSyntaxPreferred Syntax, like + USMARC, SUTRS, etc. + none + + databaseNameOne or more database names + separated by character plus (+). + Default + + +
- Records + Records A record object is a retrival record on the client side - created from result sets. + void Z3950_resultset_records (Z3950_resultset r, + Z3950_record *recs, + size_t *cnt); Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos); - Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, - int pos); - void *Z3950_record_get (Z3950_record rec, const char *type, int *len); void Z3950_record_destroy (Z3950_record rec); + + Records are created by functions + Z3950_resultset_records or + Z3950_resultset_record + and destroyed by Z3950_resultset_destroy. + + + A single record is created and returned by function + Z3950_resultset_record that takes a + position as argument. First record has position zero. + If no record could be obtained NULL. + + + Function Z39_resultset_recordsretrieves + a number of records from a result set. Options start + and count specifies the range of records to + be returned. Upon completion recs[0], ..recs[*cnt] + holds record objects for the records. These array of records + recs should be allocate prior to calling + Z3950_resultset_records. Note that for + records that couldn't be retrieved from the target + recs[ ..] is NULL. + + + In order to extract information about a single record, + Z3950_record_get is provided. The + function returns a pointer to certain record information. The + nature (type) of the pointer depends on the type + given. In addition for certain types, the length + len passed will be set to the size in bytes of + the returned information. The types database, + syntax and render are + supported. More will be added later. + - Options + Options Most objects in &zoom; allows you to specify options to change behaviour. From an implementation point of view a set of options @@ -225,7 +350,7 @@ void *handle); - Events + Events If you're developing non-blocking applications you have to deal with events. @@ -233,6 +358,21 @@ int Z3950_event (int no, Z3950_connection *cs); + + The Z3950_event executes pending events for + a number of connections. Supply the number of connections in + no and an array of connections in + cs (cs[0] ... cs[no-1]). + A pending event could be a sending a search, receiving a response, + etc. + When an event has a occured for one of the connections this function + returns a positive integer n denoting that an event + occurred for connection cs[n-1]. + When no events are pending for the connections a value of zero is + returned. + To make sure all outstanding requests are performed call is function + repeatedly until zero is returned. +