X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=cc03dbc8aba9755dca7bc88342ec86c09514115b;hb=bd7e251dac1b07c54884d26295f66b90cfb23131;hp=a069b1d3b3b33aca21fb5b6be4cf844988e11b28;hpb=ab0fd2f75e554d1c9c0e722abf073f9840f7739b;p=yaz-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index a069b1d..cc03dbc 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. @@ -38,14 +41,14 @@ NULL pointer. Connections - + The Connection object is a session with a target. #include <yaz/zoom.h> - + Z3950_connection Z3950_connection_new (const char *host, int portnum); - + Z3950_connection Z3950_connection_create (Z3950_options options); void Z3950_connection_connect(Z3950_connection c, const char *host, @@ -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. @@ -92,68 +96,68 @@ - - - Option - Description - Default - - - - - implementationNameName of Your client - none - - userAuthentication user name - none - - groupAuthentication group name + + + Option + Description + Default + + + + + implementationNameName of Your client + none + + userAuthentication user name + none + + groupAuthentication group name + none + + passAuthentication password 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 - - + + proxyProxy host + none + + asyncIf true (1) the connection operates in + asynchronous operation 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 + Function Z3950_connection_host returns 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 - set for the connection. + Z3950_connection_new or + Z3950_connection_connect. + This function returns NULL if host isn't + set for the connection. int Z3950_connection_error (Z3950_connection c, const char **cp, const char **addinfo); - Use Z3950_connection_error to check for - errors for the last operation(s) performed. The function returns - zero if no errors occurred; non-zero otherwise indicating the error. - Pointers cp and addinfo - holds messages for the error and additional-info if passed as - non-NULL. + Use Z3950_connection_error to check for + errors for the last operation(s) performed. The function returns + zero if no errors occurred; non-zero otherwise indicating the error. + Pointers cp and addinfo + holds messages for the error and additional-info if passed as + non-NULL. Search objects - Search objects defines how result sets are obtained. They - act like queries. + Search objects defines how result sets are obtained. They + act like queries. Z3950_search Z3950_search_create(void); @@ -165,24 +169,23 @@ int Z3950_search_sortby(Z3950_search s, const char *criteria); - 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 - 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 - Z3950_search_sortby specifies a - sort criteria using the same string notation for sort as offered by - the YAZ client. + 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 + 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 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. Result sets - The result set object is a container for records returned from - a target. - search. + The result set object is a container for records returned from + a target. Z3950_resultset Z3950_connection_search(Z3950_connection, @@ -194,12 +197,12 @@ void Z3950_resultset_destroy(Z3950_resultset r); - Function Z3950_connection_search creates + Function Z3950_connection_search creates a result set given a connection - and search object. - Destroy a result set by calling - Z3950_resultset_destroy. - Simple clients using PQF only may use function - Z3950_connection_search_pqf instead. + Destroy a result set by calling + Z3950_resultset_destroy. + Simple clients using PQF only may use function + Z3950_connection_search_pqf instead. const char *Z3950_resultset_option (Z3950_resultset r, @@ -212,68 +215,68 @@ const char *type, int *len); - Function X3950_resultset_options sets or - modifies an option for a result set similar to + Function Z3950_resultset_options sets or + modifies an option for a result set similar to Z3950_connection_option. - The number of hits also called result-count is returned by - function Z3950_resultset_size. + The number of hits also called result-count is returned by + function Z3950_resultset_size. - Function Z3950_resultset_get is similar to - + 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. + 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, such as - USMARC, SUTRS, etc. - none - - databaseNameOne or more database names - separated by character plus (+). - Default - - + + + 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, such as + USMARC, SUTRS, etc. + none + + databaseNameOne or more database names + separated by character plus (+). + Default + +
Records - A record object is a retrival record on the client side - - created from result sets. + A record object is a retrival record on the client side - + created from result sets. void Z3950_resultset_records (Z3950_resultset r, @@ -287,45 +290,45 @@ void Z3950_record_destroy (Z3950_record rec); - Records are created by functions - Z3950_resultset_records or - Z3950_resultset_record - and destroyed by Z3950_record_destroy. + Records are created by functions + Z3950_resultset_records or + Z3950_resultset_record + 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 is returned. + 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 is returned. - 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] - holds record objects for the records. These array of records + 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] + 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. + 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. + 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 - Most objects in &zoom; allows you to specify options to change - behaviour. From an implementation point of view a set of options - is just like an associate array / hash array, etc. + 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. Z3950_options Z3950_options_create (void); @@ -352,26 +355,26 @@ Events - If you're developing non-blocking applications you have to deal - with events. + If you're developing non-blocking applications, you have to deal + with events. - int Z3950_event (int no, Z3950_connection *cs); + 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 this function - repeatedly until zero is returned. + 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 this function + repeatedly until zero is returned. @@ -386,7 +389,7 @@ sgml-indent-step:1 sgml-indent-data:t sgml-parent-document: "yaz.xml" - sgml-local-catalogs: "../../docbook/docbook.cat" + sgml-local-catalogs: nil sgml-namecase-general:t End: -->