From: Sebastian Hammer Date: Wed, 24 Oct 2001 21:24:38 +0000 (+0000) Subject: Various changes X-Git-Tag: YAZ.1.8~10 X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=commitdiff_plain;h=f7471d960fb2671c714bdfcd74dae39ce8112652 Various changes --- diff --git a/doc/introduction.xml b/doc/introduction.xml index 4ddb58f..b8f136b 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,4 +1,4 @@ - + Introduction @@ -13,18 +13,19 @@ 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 + None of those high-level APIs support the whole protocol, but + they do include most facilities used in existing Z39.50 applications. - If you're developing non-standard extensions to Z39.50 or you're + If you're using 'exotic' functionality (meaning anything not included in + the high-level APIs), 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;. + level APIs of &yaz;. - The basic low level modules, which is independent of the role, - consists of three primary interfaces: + The basic low level modules, which are independent of the role (client or server), + consist of three primary interfaces: &asn;, which provides a C representation of the Z39.50 diff --git a/doc/zoom.xml b/doc/zoom.xml index a069b1d..c748e96 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,20 +1,23 @@ - + Building clients with ZOOM - &zoom; is an acronym for Z39.50 Object Oriented Model and is - an initiative started by Mike Taylor. The goal of &zoom; is to + &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is + an initiative started by Mike Taylor (Mike is from the UK, which + explains the peculiar name of the model). The goal of &zoom; is to provide a common Z39.50 client API not bound to a particular programming language or toolkit. - 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 - chapter describes the ZOOM C binding. Before going futher - reconsider whether C is still the programming language of your - choice. There are other language bindings available and others + The lack of a simple Z39.50 client API for &yaz; has become more + and more apparent over time. So when the first ZOOM specification + became available, + an implementation for &yaz; was quickly developed. For the first time, it is + now as easy (or easier!) to develop clients than servers with &yaz;. This + chapter describes the ZOOM C binding. Before going futher, please + reconsider whether C is the right programming language for the job. + There are other language bindings available for &yaz;, and still + more are in active development. See the ZOOM website at zoom.z3950.org for more information. @@ -29,7 +32,7 @@ The C language misses many features found in object oriented languages - such as C++, Java, etc. For example, you'll have to, manually, + such as C++, Java, etc. For example, you'll have to manually, destroy all objects you create, even though you may think of them as temporary. Most objects has a _create - and a _destroy variant. @@ -56,19 +59,19 @@ Connection objects are created with either function Z3950_connection_new or Z3950_connection_create. - The former both creates and attempts to establishes a network - connection with the target. The latter doesn't establishes - a connection immediately, thus allowing you to set specify options - before establishing network connection using function + The former creates and automatically attempts to establish a network + connection with the target. The latter doesn't establish + a connection immediately, thus allowing you to specify options + before establishing network connection using the function Z3950_connection_connect. If the portnumber, portnum, is zero, the host is consulted for a port specification. If no port is given, 210 is used. A colon denotes the beginning of a port number in the host string. If the host string includes a - slash that specifies a database for the connection. + slash, the following part specifies a database for the connection. - Connection objects should be destroyed using function + Connection objects should be destroyed using the function Z3950_connection_destroy. @@ -83,7 +86,8 @@ for the connection. If val is non-NULL that holds the new value for option. - Otherwise, if val is NULL + Otherwise, if val is + NULL, the option is unchanged. The function returns the previous value of the option. @@ -117,7 +121,7 @@ none asyncIf true (1) the connection operates in - asynchronous operatio which means that all calls are non-blocking + asynchronous operation which means that all calls are non-blocking except Z3950_event. 0 @@ -172,7 +176,7 @@ function Z3950_search_prefix. More 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 + etc. In addition to a search, a sort criteria may be set. Function Z3950_search_sortby specifies a sort criteria using the same string notation for sort as offered by the YAZ client. @@ -212,7 +216,7 @@ const char *type, int *len); - Function X3950_resultset_options sets or + Function Z3950_resultset_options sets or modifies an option for a result set similar to Z3950_connection_option. @@ -224,7 +228,7 @@ Function Z3950_resultset_get is similar to Z3950_record_get but - instead of operating on a record object it operates on a record on + instead of operating on a record object, it operates on a record on a given offset within a result set. ZOOM Result set Options @@ -299,7 +303,7 @@ If no record could be obtained NULL is returned. - Function Z39_resultset_records retrieves + Function Z3950_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] @@ -323,8 +327,8 @@ Options - Most objects in &zoom; allows you to specify options to change - behaviour. From an implementation point of view a set of options + Most objects in &zoom; allow you to specify options to change + default behaviour. From an implementation point of view a set of options is just like an associate array / hash array, etc. @@ -352,7 +356,7 @@ Events - If you're developing non-blocking applications you have to deal + If you're developing non-blocking applications, you have to deal with events. @@ -365,10 +369,10 @@ 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 + 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 + When no events are pending for the connections, a value of zero is returned. To make sure all outstanding requests are performed call this function repeatedly until zero is returned.