X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=d1ccf8ea0424acab2bfa9187387a3276778d8a55;hp=b12e8f6f7f5a1d9019e48b2a878a587a9f7d2222;hb=8bcd70cb460d7a11175e82487f498102ead66472;hpb=c91efbe35fe8ff53aeafedf0ffb8f1b90841ecdc diff --git a/doc/zoom.xml b/doc/zoom.xml index b12e8f6..d1ccf8e 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -5,11 +5,10 @@ ZOOM_connection_errmsg(c) ZOOM_connection_addinfo(c) ZOOM_connection_addinfo(c) ZOOM_connection_diagset(c); +ZOOM_connection_save_apdu_wrbuf ZOOM_diag_str(error) ZOOM_resultset_record_immediate(s, pos) ZOOM_resultset_cache_reset(r) -ZOOM_resultset_sort(r, sort_type, sort_spec) -ZOOM_resultset_sort1(r, sort_type, sort_spec) ZOOM_options_set_callback(opt, function, handle) ZOOM_options_create_with_parent2(parent1, parent2) ZOOM_options_getl(opt, name, len) @@ -17,8 +16,6 @@ ZOOM_options_setl(opt, name, value, len) ZOOM_options_get_bool(opt, name, defa) ZOOM_options_get_int(opt, name, defa) ZOOM_options_set_int(opt, name, value) -ZOOM_connection_scan1(ZOOM_connection c, ZOOM_query startterm) -ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) --> ZOOM @@ -37,16 +34,17 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) connection's sru option, which may be SRU over HTTP GET (get), SRU over HTTP POST (post), (SRU over - SOAP) (soap) or SOLR - (SOLR Web Service). + SOAP) (soap) or solr + (Solr Web Service). Using the facility for embedding options in target strings, a connection can be forced to use SRU rather the SRW (the default) by prefixing the target string with sru=get,, like this: sru=get,http://sru.miketaylor.org.uk:80/sru.pl - SOLR protocol support was added to YAZ in version 4.1.0, - as a dialect of a SRU protocol, since both are HTTP based protocols. + Solr protocol support was added to + YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are + HTTP based protocols. The lack of a simple Z39.50 client API for &yaz; has become more @@ -92,9 +90,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) #include <yaz/zoom.h> - ZOOM_connection ZOOM_connection_new (const char *host, int portnum); + ZOOM_connection ZOOM_connection_new(const char *host, int portnum); - ZOOM_connection ZOOM_connection_create (ZOOM_options options); + ZOOM_connection ZOOM_connection_create(ZOOM_options options); void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); @@ -119,7 +117,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) You can prefix the host with a scheme followed by colon. The default scheme is tcp (Z39.50 protocol). The scheme http selects SRU/get over HTTP by default, - but can overridded to use SRU/post, SRW and the SOLR protocol. + but can overridded to use SRU/post, SRW and the Solr protocol. You can prefix the scheme-qualified host-string with one or more @@ -192,6 +190,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) passwordAuthentication password. none + authenticationModeHow authentication is encoded. + basic + hostTarget host. This setting is "read-only". It's automatically set internally when connecting to a target. none @@ -280,7 +281,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) none sru - SRU/SOLR transport type. Must be either soap, + SRU/Solr transport type. Must be either soap, get, post, or solr. soap @@ -306,6 +307,24 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) protocol packets is emitted on standard error stream. This can be very useful for debugging. 0 + + saveAPDU + If set to a true value such as "1", a log of low-level + protocol packets is saved. The log can be retrieved by reading + option APDU. Setting saveAPDU always has the side effect of + resetting the currently saved log. This setting is + write-only. If read, NULL will be returned. + It is only recognized in + ZOOM_connection_option_set. + 0 + + APDU + Returns the log of protocol packets. Will be empty if logging + is not enabled (see saveAPDU above). This setting is + read-only. It is only recognized if used + in call to ZOOM_connection_option_get or + ZOOM_connection_option_getl. + @@ -372,14 +391,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU/SOLR Protocol behavior + SRU/Solr Protocol behavior - The HTTP based protocols (SRU, SRW, SOLR) doesn't feature an Inititialize Request, so - the connection phase merely establishes a TCP/IP connection - with the SOAP service. + The HTTP based protocols (SRU, SRW, Solr) doesn't feature an + Inititialize Request, so the connection phase merely establishes a + TCP/IP connection with the HTTP server. Most of the ZOOM connection options do not - affect SRU/SOLR and they are ignored. However, future versions + affect SRU/Solr and they are ignored. However, future versions of &yaz; might honor implementationName and put that as part of User-Agent header for HTTP requests. @@ -387,6 +406,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) The charset is used in the Content-Type header of HTTP requests. + + Setting authentcationMode specifies how + authentication parameters are encoded for HTTP. The default is + "basic" where user and + password are encoded by using HTTP basic + authentication. + + + If authentcationMode is "url", then + user and password are encoded in the URL by parameters + x-username and x-password as + given by the SRU standard. + Queries @@ -403,6 +435,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) int ZOOM_query_cql(ZOOM_query s, const char *str); int ZOOM_query_sortby(ZOOM_query q, const char *criteria); + + int ZOOM_query_sortby2(ZOOM_query q, const char *strategy, + const char *criteria); Create query objects using ZOOM_query_create @@ -415,17 +450,55 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) More query types will be added in future versions of &yaz;, such as CCL to RPN-mapping, native CCL query, etc. In addition to a search, a sort criteria may be set. Function - ZOOM_query_sortby specifies a - sort criteria using the same string notation for sort as offered by - the YAZ client. + ZOOM_query_sortby enables Z39.50 sorting and + it takes sort criteria using the same string notation as + yaz-client's sort command. - 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. - - + + ZOOM_query_sortby2 is similar to + ZOOM_query_sortby but allows a strategy for + sorting. The reason for the strategy parameter is that some + protocols offers multiple ways of performing sorting. + For example, Z39.50 has the standard sort, which is performed after + search on an existing result set. + It's also possible to use CQL in Z39.50 as the query type and use + CQL's SORTBY keyword. Finally, Index Data's + Zebra server also allows sorting to be specified as part of RPN (Type 7). + + + ZOOM sort strategy + + + + + + Name + Description + + + + + z39.50Z39.50 resultset sort + + + type7Sorting embedded in RPN(Type-7) + + + cqlCQL SORTBY + + + sru11SRU sortKeys parameter + + + solrSolr sort + + + embedtype7 for Z39.50, cql for SRU, + solr for Solr protocol + + + +
Result sets @@ -592,6 +665,31 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) + + + Z39.50 Result-set Sort + + void ZOOM_resultset_sort(ZOOM_resultset r, + const char *sort_type, const char *sort_spec); + + int ZOOM_resultset_sort1(ZOOM_resultset r, + const char *sort_type, const char *sort_spec); + + + ZOOM_resultset_sort and + ZOOM_resultset_sort1 both sort an existing + result-set. The sort_type parameter is not use. Set it to "yaz". + The sort_spec is same notation as ZOOM_query_sortby and identical + to that offered by yaz-client's + sort command. + + + These functions only work for Z39.50. Use the more generic utility + + ZOOM_query_sortby2 + for other protocols (and even Z39.50). + + Z39.50 Protocol behavior @@ -677,10 +775,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) SRU SearchRetrieveRequest. - SOLR queries has to be done in SOLR query format. + Solr queries has to be done in Solr query format. - Unfortunately, SRU or SOLR does not define a database setting. Hence, + Unfortunately, SRU or Solr does not define a database setting. Hence, databaseName is unsupported and ignored. However, the path part in host parameter for functions ZOOM_connecton_new and @@ -833,7 +931,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) xml The record is returned in XML if possible. - SRU, SOLR and Z39.50 records with transfer syntax XML are + SRU, Solr and Z39.50 records with transfer syntax XML are returned verbatim. MARC records are returned in MARCXML @@ -866,6 +964,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) *len. + json + Like xml, but MARC records are converted to + MARC-in-JSON. + + + @@ -900,9 +1004,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU/SOLR Protocol behavior + SRU/Solr Protocol behavior - The ZOOM driver for SRU/SOLR treats records returned by a SRU/SOLR server + The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server as if they where Z39.50 records with transfer syntax XML and no element set name or database name. @@ -910,25 +1014,37 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Facets - Facets operations is not part of the official ZOOM specification, but is an Index Data extension - for YAZ-based Z39.50 targets or SOLR targets. - In case the target can and is requested to return facets, using a result set the ZOOM client - can request one or all facet fields. Using a facet field the client can request the term count and - then interate over the terms. + Facets operations is not part of the official ZOOM specification, but + is an Index Data extension for YAZ-based Z39.50 targets or + Solr targets. + In case the target can and is requested to return facets, using a + result set the ZOOM client can request one or all facet fields. + Using a facet field the client can request the term count and then + interate over the terms. ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r); + const char ** ZOOM_resultset_facets_names(ZOOM_resultset r); - ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r, const char *facet_name); - ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r, int pos); + + ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r, + const char *facet_name); + + ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r, + int pos); + size_t ZOOM_resultset_facets_size(ZOOM_resultset r); const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field); + size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field); - const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field, size_t idx, int *freq); + + const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field, + size_t idx, int *freq); - References to temporary structures are returned by all functions. They are only valid as long the Result set is valid. + References to temporary structures are returned by all functions. + They are only valid as long the Result set is valid. ZOOM_resultset_get_facet_field or ZOOM_resultset_get_facet_field_by_index. ZOOM_resultset_facets. @@ -938,28 +1054,37 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) A single Facet field is returned by function - ZOOM_resultset_get_facet_field or ZOOM_resultset_get_facet_field_by_index that takes a - result set and facet name or positive index respectively. First facet has position zero. - If no facet could be obtained (invalid name or index out of bounds) NULL is returned. + ZOOM_resultset_get_facet_field or + ZOOM_resultset_get_facet_field_by_index that takes + a result set and facet name or positive index respectively. First + facet has position zero. If no facet could be obtained (invalid name + or index out of bounds) NULL is returned. - An array of facets field can be returned by ZOOM_resultset_facets. The length of the array is - given by ZOOM_resultset_facets_size. The array is zero-based and last entry will be at + An array of facets field can be returned by + ZOOM_resultset_facets. The length of the array is + given by ZOOM_resultset_facets_size. The array is + zero-based and last entry will be at ZOOM_resultset_facets_size(result_set)-1. - It is possible to interate over facets by name, by calling ZOOM_resultset_facets_names. - This will return an const array of char * where each string can be used as parameter for - ZOOM_resultset_get_facet_field. + It is possible to interate over facets by name, by calling + ZOOM_resultset_facets_names. + This will return an const array of char * where each string can be used + as parameter for ZOOM_resultset_get_facet_field. - Function ZOOM_facet_field_name gets the request facet name from a returned facet field. + Function ZOOM_facet_field_name gets the request + facet name from a returned facet field. - Function ZOOM_facet_field_get_term returns the idx'th term and term count for a facet field. - Idx must between 0 and ZOOM_facet_field_term_count-1, otherwise the returned reference will be - NULL. On a valid idx, the value of the freq reference will be the term count. - The *freq parameter must be valid pointer to integer. + Function ZOOM_facet_field_get_term returns the + idx'th term and term count for a facet field. + Idx must between 0 and + ZOOM_facet_field_term_count-1, otherwise the + returned reference will be NULL. On a valid idx, the + value of the freq reference will be the term count. + The freq parameter must be valid pointer to integer. Scan @@ -971,7 +1096,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - The Scan interface is supported for both Z39.50, SRU (and SOLR?). + The Scan interface is supported for both Z39.50, SRU and Solr. @@ -1482,6 +1607,38 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) void *handle); + + Query conversions + + int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str, + ZOOM_connection conn); + + int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str, + const char *config, + int *ccl_error, const char **error_string, + int *error_pos); + + + ZOOM_query_cql2rpn translates the CQL string, + client-side, into RPN which may be passed to the server. + This is useful for server's that don't themselves + support CQL, for which ZOOM_query_cql is useless. + `conn' is used only as a place to stash diagnostics if compilation + fails; if this information is not needed, a null pointer may be used. + The CQL conversion is driven by option cqlfile from + connection conn. This specifies a conversion file (eg pqf.properties) + which must be present. + + + ZOOM_query_ccl2rpn translates the CCL string, + client-side, into RPN which may be passed to the server. + The conversion is driven by the specification given by + config. Upon completion 0 is returned on success; -1 + is returned on on failure. Om failure error_string and + error_pos holds error message and position of + first error in original CCL string. + + Events If you're developing non-blocking applications, you have to deal