From ab0fd2f75e554d1c9c0e722abf073f9840f7739b Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Wed, 24 Oct 2001 20:12:36 +0000 Subject: [PATCH] Typos. Better introduction, really. Other, minor, updates. --- doc/asn.xml | 14 ++--- doc/client.xml | 4 +- doc/frontend.xml | 24 ++++---- doc/future.xml | 16 +++--- doc/installation.xml | 156 ++++++++++++++++++++++++++++++++++---------------- doc/introduction.xml | 44 +++++++++----- doc/odr.xml | 27 ++++----- doc/tools.xml | 13 +++-- doc/yaz.xml | 13 +++-- doc/zoom.xml | 20 +++---- 10 files changed, 203 insertions(+), 128 deletions(-) diff --git a/doc/asn.xml b/doc/asn.xml index 3f378c4..85bdc94 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,9 +1,9 @@ - - The ASN Module + + The ASN.1 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 + various PDUs of the Z39.50 protocol, as well as for the complex types appearing within the PDUs. For the primitive data types, the C representation often takes the form of an ordinary C language type, such as int. For ASN.1 constructs that have no direct @@ -372,10 +372,10 @@ typedef struct Z_ext_typeent idAuthenticationZ_IdAuthenticationNULL - implementationIdchar*"YAZ (id=81)" + implementationIdchar*"81" - implementationNamechar*"Index Data/YAZ" + implementationNamechar*"YAZ" implementationVersionchar*YAZ_VERSION @@ -423,10 +423,10 @@ typedef struct Z_ext_typeent resultbool_tTRUE - implementationIdchar*"YAZ (id=81)" + implementationIdchar*"id)" - implementationNamechar*"Index Data/YAZ" + implementationNamechar*"YAZ" implementationVersionchar*YAZ_VERSION diff --git a/doc/client.xml b/doc/client.xml index 2995c50..1c8df1c 100644 --- a/doc/client.xml +++ b/doc/client.xml @@ -1,4 +1,4 @@ - + The YAZ client Introduction @@ -88,7 +88,7 @@ yaz-client -a - localhost - YAZ client commands + Commands When the YAZ client has read options and connected to a target, if given, it will display Z > and away your command. diff --git a/doc/frontend.xml b/doc/frontend.xml index 0673c3d..7dd7058 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,14 +1,12 @@ - - Making an IR Server for Your Database + + Generic server Introduction If you aren't into documentation, a good way to learn how the back end interface works is to look at the backend.h file. Then, look at the small dummy-server in - ztest/ztest.c. Finally, you can have a look at - the seshigh.c file, which is where most of the - logic of the frontend server is located. The backend.h + ztest/ztest.c. The backend.h file also makes a good reference, once you've chewed your way through the prose of this file. @@ -105,15 +103,15 @@ The Backend API - The headers files that you need to use the interface are in the - include/yaz directory. They are called - statserv.h and backend.h. They - will include other files from the include/yaz - directory, so you'll probably want to use the -I option of your - compiler to tell it where to find the files. When you run + The header file that you need to use the interface are in the + include/yaz directory. It's called + backend.h. It will include other files from + the include/yaz directory, so you'll + probably want to use the -I option of your compiler to tell it + where to find the files. When you run make in the top-level &yaz; directory, - everything you need to create your server is put the - lib/libyaz.a library. + everything you need to create your server is to link with the + lib/libyaz.la library. diff --git a/doc/future.xml b/doc/future.xml index 937c7f3..52be2dd 100644 --- a/doc/future.xml +++ b/doc/future.xml @@ -1,4 +1,4 @@ - + Future Directions @@ -10,12 +10,6 @@ - We now support all PDUs of Z39.50-1995. If there is one of the - supporting structures that you need but can't find in the prt*.h - files, send us a note; it may be on its way. - - - The 'retrieval' module needs to be finalized and documented. We think it can form a useful resource for people dealing with complex record structures, but for now, you'll mostly have to chew through the code @@ -23,6 +17,14 @@ + &yaz; is a BER toolkit and as such should support all protocols + out there based on that. We'd like to see running ILL applications. + It shouldn't be that hard. Another thing that would be intersting is + LDAP. Maybe a generic framework for doing IR using both LDAP and + Z39.50 transparently. + + + Other than that, YAZ generally moves in the directions which appear to make the most people happy (including ourselves, as prime users of the software). If there's something you'd like to see in here, then drop diff --git a/doc/installation.xml b/doc/installation.xml index 448bed4..aebcd55 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,8 +1,9 @@ - + Compilation and Installation + Introduction - The latest version of the software will generally be found at + The latest version of the software will generally be found at: @@ -21,6 +22,7 @@ HP/UX SunOS/Solaris DEC Unix + OpenBSD/FreeBSD Linux IBM AIX Data General DG/UX (with some CFLAGS tinkering) @@ -59,15 +61,24 @@ , or the address given at the top of this document. + UNIX Note that if your system doesn't have a native ANSI C compiler, you may - have to acquire one separately. We recommend gcc. + have to acquire one separately. We recommend + GCC. - For UNIX we use GNU configure to create Makefiles for &yaz;. - Generally it should be sufficient to run configure without options: + For UNIX, the GNU tools + Autoconf, + Automake and + Libtool + is used to generate Makefiles and configure &yaz; for the system. + You do not these tools unless you're using the + CVS version of &yaz;. + Generally it should be sufficient to run configure without options, + like this: @@ -125,27 +136,54 @@ The following files are generated by the make process: - lib/libyaz.a + lib/libyaz.la + + The main &yaz; library. This is no ordinary library. It's + a Libtool archive. + By default, &yaz; creates a static library in + lib/.libs/libyaz.a. + + + lib/libyazthread.la - The &yaz; programmers' library. + When threading is supported/enabled by configure this GNU libtool + library is created. It include functions that allows &yaz; + to use threads. ztest/yaz-ztest - A test Z39.50 server. + A test Z39.50 server. client/yaz-client - A command mode Z39.50 client. + A YAZ Z39.50 client. See chapter + YAZ client for more information. yaz-config - A Bourne-shell script that holds build - settings for &yaz;. + A Bourne-shell script, generate by configure, that + specifies how external applications should compile - and link with + &yaz;. yaz-comp The ASN.1 compiler for &yaz;. Requires the - Tcl Shell, tclsh, in current path to work. + Tcl Shell, tclsh, in + PATH to operate. + + + zoom/zoomsh + + A simple shell implemented on top of the + ZOOM functions. + The shell is a command line application that allows you to enter + simple commands perform to perform ZOOM operations. + + + zoom/zoomtst1, + zoom/zoomtst2, .. + + Several small applications that demonstrates the use of ZOOM. @@ -188,50 +226,55 @@ &yaz; is shipped with "makefiles" for the NMAKE tool that comes - with Visual C++. - - Start an MS-DOS prompt and switch the sub directory + with Microsoft Visual C++. Version 6 has been tested. We expect that + &yaz; should compile with version 5 as well. + + + Start a command prompt and switch the sub directory WIN where the file makefile is located. Customize the installation by editing the makefile file (for example by using notepad). The following summarises the most important settings in that file: - - WIN32 makefile settings - - - - Setting - Description - - - - - DEBUG - If set to 1, the software is - compiled with debugging libraries. If set to 0, the software - is compiled with release (non-debugging) libraries. - - - - - TCL - Specifies the name of the Tcl shell (EXE-file). + + + DEBUG + + If set to 1, the software is + compiled with debugging libraries (code generation is + multi-threaded debug DLL). + If set to 0, the software is compiled with release libraries + (code generation is multi-threaded DLL). + + + TCL + + Specifies the name of the Tcl shell (EXE-file). You do not need setting this or installing Tcl unless you wish to change or add ASN.1 for &yaz;. - - - - - -
- + + + When satisfied with the settings in the makefile type nmake + If command nmake is not found on your system + you probably haven't defined the environment variables required to + use that tool. To fix that, find and run the batch file + vcvars32.bat. You need to run it from within + the command prompt or set the environment variables "globally"; + otherwise it doesn't work. + + + If you wish to recompile &yaz; - for example if you modify + settings in the makefile you can delete + object files, etc by running. + + nmake clean + The following files are generated upon successful compilation: @@ -239,19 +282,36 @@ bin/yaz.dll - the multi-threaded &yaz; DLL. + The multi-threaded &yaz; Dynamic Link Library. - bin/yaz-ztest.exe + bin/yaz-client.exe - A console Z39.50 client application. + The &yaz; Z39.50 client application. It's a WIN32 console application. + See chapter YAZ client for more + information. bin/yaz-ztest.exe - A console Z39.50 multi threaded server. + The example/test Z39.50 multi threaded server. It's a WIN32 + console application. - + + bin/zoomsh.exe + + A simple console application implemented on top of the + ZOOM functions. + The application is a command line shell that allows you to enter + simple commands perform to perform ZOOM operations. + + + bin/zoomtst1.exe, + bin/zoomtst2.exe, .. + + Several small applications that demonstrates the use of ZOOM. + + diff --git a/doc/introduction.xml b/doc/introduction.xml index 470344b..4ddb58f 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,17 +1,33 @@ - + Introduction - The &yaz; toolkit offers several different levels of access to the - Z39.50 and SR protocols. The level that you need to use depends on - your requirements, and the role (server or client) that you - want to implement. - - The basic level, which is independent of the role, consists of three - primary interfaces: + The &yaz; + toolkit offers several different levels of access to the + ISO23950/Z39.50 + and ILL protocols. + The level that you need to use depends on your requirements, and + the role (server or client) that you want to implement. + If you're developing a client application you should consider the + ZOOM API. + It is, by far, the easiest way to develop clients in C. + Server implementers should consider the + generic frontend server. + None of those high-level API's support the whole protocol, but + they support most facilities used in existing Z39.50 + applications. + + + If you're developing non-standard extensions to Z39.50 or you're + going to develop an ILL application you'll have to learn the lower + level API's of &yaz;. + + + The basic low level modules, which is independent of the role, + consists of three primary interfaces: - &asn;, which provides a C representation of the Z39.50/SR + &asn;, which provides a C representation of the Z39.50 protocol packages (PDUs). &odr;, which encodes and decodes the packages according @@ -23,7 +39,7 @@ The &asn; module represents the ASN.1 definition of - the SR/Z39.50 protocol. It establishes a set of type and + the Z39.50 protocol. It establishes a set of type and structure definitions, with one structure for each of the top-level PDUs, and one structure or type for each of the contained ASN.1 types. For primitive types, or other types that are defined by the ASN.1 @@ -31,7 +47,7 @@ provided by the &odr; (Open Data Representation) subsystem. - &odr; is a basic mechanism for representing an + &odr; is a basic mechanism for representing an ASN.1 type in the C programming language, and for implementing BER encoders and decoders for values of that type. The types defined in the &asn; module generally have the prefix Z_, and @@ -68,14 +84,14 @@ (passively or actively, depending on the role of your application), and for exchanging BER-encoded PDUs over that connection. When you create a connection endpoint, you need to specify what transport to - use (OSI or TCP/IP), and which protocol you want to use (SR or - Z39.50). For the remainder of the connection's lifetime, you don't have + use (TCP/IP or SSL). + For the remainder of the connection's lifetime, you don't have to worry about the underlying transport protocol at all - the &comstack; will ensure that the correct mechanism is used. We call the combined interfaces to &odr;, &asn;, and &comstack; the service - level API. It's the API that most closely models the Z39.50/SR + level API. It's the API that most closely models the Z39.50 service/protocol definition, and it provides unlimited access to all fields and facilities of the protocol definitions. diff --git a/doc/odr.xml b/doc/odr.xml index dbba5dd..4f0451b 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,4 @@ - + The ODR Module Introduction @@ -23,9 +23,9 @@ - This is important, so we'll repeat it for emphasis: You do not - need to read section Programming with ODR to - implement Z39.50 with &yaz;. + This is important, so we'll repeat it for emphasis: You do + not need to read section Programming with + ODR to implement Z39.50 with &yaz;. @@ -489,21 +489,18 @@ void do_nothing_useful(int value) - The interface is based loosely on that of the Sun Microsystems XDR routines. + The interface is based loosely on that of the Sun Microsystems XDR + routines. Specifically, each function which corresponds to an ASN.1 primitive type has a dual function. Depending on the settings of the ODR stream which is supplied as a parameter, the function may be used either to encode or decode data. The functions that can be built - using these primitive functions, to represent more complex data types, share - this quality. The result is that you only have to enter the definition - for a type once - and you have the functionality of encoding, decoding - (and pretty-printing) all in one unit. The resulting C source code is - quite compact, and is a pretty straightforward representation of the - source ASN.1 specification. Although no ASN.1 compiler is supplied - with &odr; at this time, it shouldn't be too difficult to write one, or - perhaps even to adapt an existing compiler to output &odr; routines - (not surprisingly, writing encoders/decoders using &odr; turns out - to be boring work). + using these primitive functions, to represent more complex data types, + share this quality. The result is that you only have to enter the + definition for a type once - and you have the functionality of encoding, + decoding (and pretty-printing) all in one unit. + The resulting C source code is quite compact, and is a pretty + straightforward representation of the source ASN.1 specification. diff --git a/doc/tools.xml b/doc/tools.xml index 850a6fc..7f6de9d 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -83,7 +83,7 @@ int p_query_attset (const char *arg); AttributeType ::= integer. - AttributeValue ::= integer. + AttributeValue ::= integer || string. Complex ::= Operator QueryStruct QueryStruct. @@ -156,14 +156,15 @@ int p_query_attset (const char *arg); - The EUROPAGATE research project working under the Libraries programme + The EUROPAGATE + research project working under the Libraries programme of the European Commission's DG XIII has, amongst other useful tools, implemented a general-purpose CCL parser which produces an output structure that can be trivially converted to the internal RPN - representation of YAZ (The Z_RPNQuery structure). + representation of &yaz; (The Z_RPNQuery structure). Since the CCL utility - along with the rest of the software - produced by EUROPAGATE - is made freely available on a liberal license, it - is included as a supplement to YAZ. + produced by EUROPAGATE - is made freely available on a liberal + license, it is included as a supplement to &yaz;. CCL Syntax diff --git a/doc/yaz.xml b/doc/yaz.xml index bc2450b..9d50640 100644 --- a/doc/yaz.xml +++ b/doc/yaz.xml @@ -1,6 +1,6 @@ @@ -21,7 +21,7 @@ COMSTACK"> ZOOM"> ]> - + YAZ User's Guide and Reference @@ -42,25 +42,26 @@ package. &yaz; is a compact toolkit that provides access to the Z39.50 protocol, as well as a set of higher-level tools for implementing the server and client roles, respectively. - The documentation can be used on its own, or as a reference when looking - at the example applications provided with the package. + The documentation can be used on its own, or as a reference when + looking at the example applications provided with the package. &chap-introduction; &chap-installation; &chap-zoom; + &chap-frontend; &chap-client; &chap-asn; &chap-tools; &chap-odr; &chap-comstack; - &chap-frontend; &chap-future; &app-license; &app-indexdata; + diff --git a/doc/zoom.xml b/doc/zoom.xml index ff34527..a069b1d 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,5 +1,5 @@ - - ZOOM + + Building clients with ZOOM &zoom; is an acronym for Z39.50 Object Oriented Model and is @@ -8,7 +8,7 @@ programming language or toolkit. - The lack of a simple Z39.50 client API for &yaz; was more apparanet + The lack of a simple Z39.50 client API for &yaz; was more apparent than ever. So, when the first ZOOM specification was available an implementation for &yaz; was developed. For the first time, it is now easier to develop clients than servers with &yaz;. This @@ -217,8 +217,8 @@ Z3950_connection_option. - The number of hits also called result-set is returned by - function 3950_resultset_size. + The number of hits also called result-count is returned by + function Z3950_resultset_size. Function Z3950_resultset_get is similar to @@ -259,7 +259,7 @@ and F for brief and full respectively. none - preferredRecordSyntaxPreferred Syntax, like + preferredRecordSyntaxPreferred Syntax, such as USMARC, SUTRS, etc. none @@ -290,16 +290,16 @@ Records are created by functions Z3950_resultset_records or Z3950_resultset_record - and destroyed by Z3950_resultset_destroy. + and destroyed by Z3950_record_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. + If no record could be obtained NULL is returned. - Function Z39_resultset_recordsretrieves + Function Z39_resultset_records retrieves 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] @@ -370,7 +370,7 @@ 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 + To make sure all outstanding requests are performed call this function repeatedly until zero is returned. -- 1.7.10.4