X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fzoom.xml;h=5049709bc2c41aabb92a11c6a4fc82f9e81373cf;hb=fd4adcc80d442f84c6a1894e890b1b6ccd02615e;hp=cc03dbc8aba9755dca7bc88342ec86c09514115b;hpb=bd7e251dac1b07c54884d26295f66b90cfb23131;p=yaz-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index cc03dbc..5049709 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,4 +1,4 @@ - + Building clients with ZOOM @@ -40,6 +40,11 @@ that because of typedefs. All destroy methods should gracefully ignore a NULL pointer. + + In each of the sections below you'll find a sub section called + protocol behavior, that descries how the API maps to the Z39.50 + protocol. + Connections The Connection object is a session with a target. @@ -89,7 +94,7 @@ Otherwise, if val is NULL, the option is unchanged. - The function returns the previous value of the option. + The function returns the (new) value of the option. ZOOM Connection Options @@ -122,7 +127,8 @@ asyncIf true (1) the connection operates in asynchronous operation which means that all calls are non-blocking - except Z3950_event. + except + Z3950_event. 0 maximumRecordSize Maximum size of single record. @@ -153,34 +159,78 @@ holds messages for the error and additional-info if passed as non-NULL. + Protocol behavior + + The calls Z3950_connection_new and + Z3950_connection_connect establises a TCP/IP + connection and sends an Initialize Request to the target if + possible. In addition, the calls waits for an Initialize Response + from the target and the result is inspected (OK or rejected). + + + If proxy is set then the client will establish + a TCP/IP connection with the peer as specified by the + proxy host and the hostname as part of the + connect calls will be set as part of the Initialize Request. + The proxy server will then "forward" the PDU's transparently + to the target behind the proxy. + + + For the authentication parameters, if option user + is set and both options group and + pass are unset, then Open style + authentication is used (Version 2/3) in which case the username + is usually followed by a slash, then by a password. + If either group + or pass is set then idPass authentication + (Version 3 only) is used. If none of the options are set, no + authentication parameters are set as part of the Initialize Request + (obviously). + + + When option async is 1, it really means that + all network operations are postponed (and queued) until the + function Z3950_event is invoked. When doing so + it doesn't make sense to check for errors after + Z3950_connection_new is called since that + operation "connecting - and init" is still incomplete and the + API cannot tell the outcome (yet). + + - Search objects + Queries - Search objects defines how result sets are obtained. They - act like queries. + Query objects represents queries. - Z3950_search Z3950_search_create(void); + Z3950_query Z3950_query_create(void); - void Z3950_search_destroy(Z3950_search s); + void Z3950_query_destroy(Z3950_query q); - int Z3950_search_prefix(Z3950_search s, const char *str); + int Z3950_query_prefix(Z3950_query q, const char *str); - int Z3950_search_sortby(Z3950_search s, const char *criteria); + int Z3950_query_sortby(Z3950_query q, const char *criteria); - Create search objects using Z3950_search_create - and destroy them by calling Z3950_search_destroy. + Create query objects using Z3950_query_create + and destroy them by calling Z3950_query_destroy. RPN-queries can be specified in PQF notation by using the - function Z3950_search_prefix. More + function Z3950_query_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 + Z3950_query_sortby specifies a sort criteria using the same string notation for sort as offered by the YAZ client. + Protocol behavior + + The query object is just an interface for the member Query + in the SearchRequest. The sortby-function is an interface to the + sortSequence member of the SortRequest. + + Result sets @@ -189,7 +239,7 @@ Z3950_resultset Z3950_connection_search(Z3950_connection, - Z3950_search q); + Z3950_query q); Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, const char *q); @@ -198,11 +248,12 @@ Function Z3950_connection_search creates - a result set given a connection - and search object. + a result set given a connection and query. Destroy a result set by calling Z3950_resultset_destroy. - Simple clients using PQF only may use function - Z3950_connection_search_pqf instead. + Simple clients may using PQF only may use function + Z3950_connection_search_pqf in which case + creating query objects is not necessary. const char *Z3950_resultset_option (Z3950_resultset r, @@ -211,8 +262,8 @@ int Z3950_resultset_size (Z3950_resultset r); - void *Z3950_resultset_get (Z3950_resultset s, int pos, - const char *type, int *len); + void *Z3950_resultset_get (Z3950_resultset s, size_t pos, + const char *type, size_t *len); Function Z3950_resultset_options sets or @@ -248,10 +299,9 @@ 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. + startOffset of first record to be + retrieved from target. First record has offset 0 unlike the + protocol specifications where first record has position 1. 0 countNumber of records to be retrieved. @@ -266,12 +316,85 @@ USMARC, SUTRS, etc. none + smallSetUpperBoundIf hits is less than or equal to this + value, then target will return all records using small element set name + 0 + + largeSetLowerBoundIf hits is greator than this + value, the target will return no records. + 1 + + mediumSetPresentNumberThis value represents + the number of records to be returned as part of a search when when + hits is less than or equal to large set lower bound and if hits + is greator than small set upper bound. + 0 + + smallSetElementSetName + The element set name to be used for small result sets. + none + + mediumSetElementSetName + The element set name to be for medium-sized result sets. + none + databaseNameOne or more database names separated by character plus (+). Default
+ + Protocol behavior + + The creation of a result set involves at least a SearchRequest + - SearchResponse protocol handshake. Following that, if a sort + critieria was specified as part of the query, a sortRequest - + SortResponse handshake takes place. Note that it is necessary to + perform sorting before any retrieval takes place, so no records will + be returned from the target as part of the SearchResponse because these + would be unsorted. Hence, piggyback is disabled when sort critieria + is set. Following Search - and a Possible sort, Retrieval takes + place - as one or more Present Requests - Present Response being + transferred. + + + The API allows for two different modes for retrieval. A high level + mode which is somewhat more powerful and a low level one. + The low level is "enabled" when the settings + smallSetUpperBound, + mediumSetPresentNumber and + largeSetLowerBound are set. The low level mode + thus allows you to precisely set how records are returned as part + of a search response as offered by the Z39.50 protocol. + Since the client may be retrieving records as part of the + search response, this mode doesn't work well if sorting is used. + + + The high-level mode allows you to fetch a range of records from + the result set with a given start offset. When you use this mode + the client will automatically use piggyback if that is possible + with the target and perform one or more present requests as needed. + Even if the target returns fewer records as part of a present response + because of a record size limit, etc. the client will repeat sending + present requests. As an example, if option start + is 0 (default) and count is 4, and + piggyback is 1 (default) and no sorting critieria + is specified, then the client will attempt to retrieve the 4 + records as part the search response (using piggyback). On the other + hand, if either start is positive or if + a sorting criteria is set, or if piggyback + is 0, then the client will not perform piggyback but send Present + Requests instead. + + + If either of the options mediumSetElementSetName and + smallSetElementSetName are unset, the value + of option elementSetName is used for piggyback + searches. This means that for the high-level mode you only have + to specify one elementSetName option rather than three. + + Records @@ -281,11 +404,11 @@ void Z3950_resultset_records (Z3950_resultset r, Z3950_record *recs, - size_t *cnt); - Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos); + size_t start, size_t count); + Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos); void *Z3950_record_get (Z3950_record rec, const char *type, - int *len); + size_t *len); void Z3950_record_destroy (Z3950_record rec); @@ -303,14 +426,15 @@ Function Z3950_resultset_records retrieves - a number of records from a result set. Options start + a number of records from a result set. Parameter 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 + be returned. Upon completion array + recs[0], ..recs[count-1] + holds record objects for the records. The array of records recs should be allocate prior to calling - Z3950_resultset_records. Note that for + Z3950_resultset_records. Note that for those records that couldn't be retrieved from the target - recs[ ..] is NULL. + recs[ ..] is set to NULL. In order to extract information about a single record, @@ -319,16 +443,49 @@ 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. + the returned information. + + database + The database that holds the record is returned + as a C string. Return type char *. + + + syntax + The transfer syntax (OID) of the record is returned + as a C string. Return type char *. + + + render + The record is returned in a display friendly + format. Upon completion buffer is returned + (type char *) and length is stored in + *len. + + + raw + The record is returned in the internal + YAZ specific format. The raw data is returned as type + Z_External * is just the type for + the member retrievalRecord in + type NamePlusRecord. + + + + Protocol behavior + + The functions Z3950_resultset_record and + Z3950_resultset_records inspects the client-side + record cache. If the records(s) were not found, i.e. not yet retrieved + from, they are fetched using Present Requests. + + 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. + Most &zoom; objects provide a way to specify options to default behavior. + 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); @@ -373,7 +530,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 this function + To ensure that all outstanding requests are performed call this function repeatedly until zero is returned.