X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=ff34527b52891c9b51cd17316bc4f01340658e85;hp=1a0aa9eba6987c446df0ae59e14ac0d59de38242;hb=33c05384cfbca55da4ff97e5b2047b16596c72f7;hpb=e1f879d00e75be3b5b9f3ecc22b34cc0c1c61aec 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. +