X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=da8f0a9a5132616ab15c00612d6d228e1790240b;hp=87089ee31bee2d3171537f80dc62620fda268453;hb=bf522cd3aa2173ec426ae99f4b103a4bbaa04fca;hpb=f9747584f933039d25a9ba450f362d61733d14ea diff --git a/doc/zoom.xml b/doc/zoom.xml index 87089ee..da8f0a9 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -17,10 +17,9 @@ 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_connection_scan1(ZOOM_connection c, ZOOM_query startterm) ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) --> - ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -30,22 +29,25 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) programming language or toolkit. - - - A recent addition to &yaz; is SRU support. You can now make - SRU ZOOM connections by specifying scheme http:// - for the hostname for a connection. The dialect of SRU used is - specified by the value of the connection's sru - option, which may be SRU over HTTP GET (get), - SRU over HTTP POST (post) or SRW (SRU over - SOAP) (soap). 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: + + From YAZ version 2.1.12, SRU is supported. + You can make SRU ZOOM connections by specifying scheme + http:// for the hostname for a connection. + The dialect of SRU used is specified by the value of the + 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). + 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. + 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 @@ -96,7 +98,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); - void ZOOM_connection_destroy (ZOOM_connection c); + void ZOOM_connection_destroy(ZOOM_connection c); Connection objects are created with either function @@ -116,7 +118,8 @@ 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 over HTTP. + The scheme http selects SRU/get over HTTP by default, + but can overridded to use SRU/post, SRW and the SOLR protocol. You can prefix the scheme-qualified host-string with one or more @@ -193,7 +196,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) It's automatically set internally when connecting to a target. none - proxyProxy host + proxyProxy host. If set, the logical host + is encoded in the otherInfo area of the Z39.50 Init PDU + with OID 1.2.840.10003.10.1000.81.1. + none + + clientIPClient IP. If set, is + encoded in the otherInfo area of a Z39.50 PDU with OID + 1.2.840.10003.10.1000.81.3. Holds the original IP addreses + of a client. Is used of ZOOM is used in a gateway of some sort. none asyncIf true (1) the connection operates in @@ -267,6 +278,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) discover whether the server claims to support the specified operations. none + + sru + SRU/SOLR transport type. Must be either soap, + get, post, or + solr. + soap sru_version SRU/SRW version. Should be 1.1, or @@ -274,7 +291,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) to offer (highest version). And following connect (in fact first operation), holds the negotiated version with the server (same or lower version). - 1.1 + 1.2 + + facets + A FacetList is comma-separated list of facet, which is defined + as AttributeList and a optional FacetTerm + (a Term and a frequency). On request the terms is missing. + On response the the list contains the terms that the target + could collect. + none @@ -285,10 +310,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Character Set and Language Negotiation is in effect. - int ZOOM_connection_error (ZOOM_connection c, const char **cp, - const char **addinfo); - int ZOOM_connection_error_x (ZOOM_connection c, const char **cp, - const char **addinfo, const char **dset); + int ZOOM_connection_error(ZOOM_connection c, const char **cp, + const char **addinfo); + int ZOOM_connection_error_x(ZOOM_connection c, const char **cp, + const char **addinfo, const char **dset); Function ZOOM_connection_error checks for @@ -341,14 +366,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU Protocol behavior + SRU/SOLR Protocol behavior - The SRU protocol doesn't feature an Inititialize Request, so + 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. Most of the ZOOM connection options do not - affect SRU 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. @@ -402,17 +427,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) a target. - ZOOM_resultset ZOOM_connection_search(ZOOM_connection, - ZOOM_query q); + ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q); ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c, const char *q); - void ZOOM_resultset_destroy(ZOOM_resultset r); Function ZOOM_connection_search creates - a result set given a connection and query. + a result set given a connection and query. Destroy a result set by calling ZOOM_resultset_destroy. Simple clients may using PQF only may use function @@ -420,14 +443,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) creating query objects is not necessary. - void ZOOM_resultset_option_set (ZOOM_resultset r, - const char *key, - const char *val); + void ZOOM_resultset_option_set(ZOOM_resultset r, + const char *key, const char *val); - const char *ZOOM_resultset_option_get (ZOOM_resultset r, - const char *key); + const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key); - size_t ZOOM_resultset_size (ZOOM_resultset r); + size_t ZOOM_resultset_size(ZOOM_resultset r); Functions ZOOM_resultset_options_set and @@ -457,13 +478,21 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) startOffset of first record to be retrieved from target. First record has offset 0 unlike the protocol specifications where first record has position 1. + This option affects ZOOM_resultset_search and + ZOOM_resultset_search_pqf and must be set before any of + these functions are invoked. If a range of + records must be fetched manually after search, + function ZOOM_resultset_records should be used. 0 - countNumber of records to be retrieved. + countNumber of records to be retrieved. + This option affects ZOOM_resultset_search and + ZOOM_resultset_search_pqf and must be set before any of + these functions are invoked. 0 presentChunkThe number of records to be - requested from the server in each chunk (present requst). The + requested from the server in each chunk (present request). The value 0 means to request all the records in a single chunk. (The old step option is also supported for the benefit of old applications.) @@ -642,7 +671,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) SRU SearchRetrieveRequest. - Unfortunately, SRU does not define a database setting. Hence, + SOLR queries has to be done in SOLR query format. + + + 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 @@ -668,9 +700,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) int ZOOM_record_error(ZOOM_record rec, const char **msg, const char **addinfo, const char **diagset); - ZOOM_record ZOOM_record_clone (ZOOM_record rec); + ZOOM_record ZOOM_record_clone(ZOOM_record rec); - void ZOOM_record_destroy (ZOOM_record rec); + void ZOOM_record_destroy(ZOOM_record rec); References to temporary records are returned by functions @@ -718,7 +750,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) The type is a string of the format: - form[; charset=from[,to]] + form[;charset=from[,to]][;format=v] where form specifies the format of the @@ -731,6 +763,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) If to is omitted UTF-8 is assumed. + The format argument controls whether record data should be XML + pretty-printed (post process operation). + It is enabled only if format value v is + 1 and the record content is XML well-formed. + + In addition, for certain types, the length len passed will be set to the size in bytes of the returned information. @@ -778,20 +816,37 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) xml The record is returned in XML if possible. - SRU 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 (converted from ISO2709 to MARCXML by YAZ). - GRS-1 and OPAC records are not supported for this form. + OPAC records are also converted to XML and the + bibliographic record is converted to MARCXML (when possible). + GRS-1 records are not supported for this form. Upon completion, the XML buffer is returned (type const char *) and length is stored in *len. opac - OPAC for record is returned in XML. + OPAC information for record is returned in XML + if an OPAC record is present at the position given. If no + OPAC record is present, a NULL pointer is returned. + + + txml + The record is returned in TurboMARC if possible. + SRU and Z39.50 records with transfer syntax XML are + returned verbatim. MARC records are returned in + + TurboMARC + + (converted from ISO2709 to TurboMARC by YAZ). + Upon completion, the XML buffer is returned + (type const char *) and length is stored in + *len. @@ -828,14 +883,68 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU Protocol behavior + SRU/SOLR Protocol behavior - The ZOOM driver for SRU treats records returned by a SRU 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. + 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. + + + 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); + 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); + + + 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. + ZOOM_resultset_facets_names. + ZOOM_facet_field_name. + ZOOM_facet_field_get_term. + + + 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. + + + 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. + + + 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. + + Scan This section describes an interface for Scan. Scan is not an @@ -845,7 +954,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - The Scan interface is supported for both Z39.50 and SRU. + The Scan interface is supported for both Z39.50, SRU (and SOLR?). @@ -857,16 +966,16 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) size_t ZOOM_scanset_size(ZOOM_scanset scan); - const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos, - int *occ, size_t *len); + const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos, + size_t *occ, size_t *len); - const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos, - int *occ, size_t *len); + const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos, + size_t *occ, size_t *len); - void ZOOM_scanset_destroy (ZOOM_scanset scan); + void ZOOM_scanset_destroy(ZOOM_scanset scan); const char *ZOOM_scanset_option_get(ZOOM_scanset scan, - const char *key); + const char *key); void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key, const char *val); @@ -934,7 +1043,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) numberNumber of Scan Terms requested in next scan. After scan it holds the actual number of terms returned. - 10 + 20 positionPreferred Position of term in response in next scan; actual position after completion of scan. @@ -1185,6 +1294,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) none + recordOpaque + Specifies an opaque record which is + encoded as an ASN.1 ANY type with the OID as tiven by option + syntax (see below). + Option recordOpaque is an alternative + to record - and record option (above) is + ignored if recordOpaque is set. This option is only available in + YAZ 3.0.35 and later and is meant to facilitate Updates with + servers from OCLC. + + none + + syntax The record syntax (transfer syntax). Is a string that is a known record syntax. @@ -1321,26 +1443,26 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) an associative array / hash. - ZOOM_options ZOOM_options_create (void); + ZOOM_options ZOOM_options_create(void); - ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent); + ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent); - void ZOOM_options_destroy (ZOOM_options opt); + void ZOOM_options_destroy(ZOOM_options opt); - const char *ZOOM_options_get (ZOOM_options opt, const char *name); + const char *ZOOM_options_get(ZOOM_options opt, const char *name); - void ZOOM_options_set (ZOOM_options opt, const char *name, - const char *v); + void ZOOM_options_set(ZOOM_options opt, const char *name, + const char *v); typedef const char *(*ZOOM_options_callback) - (void *handle, const char *name); + (void *handle, const char *name); ZOOM_options_callback - ZOOM_options_set_callback (ZOOM_options opt, - ZOOM_options_callback c, - void *handle); + ZOOM_options_set_callback(ZOOM_options opt, + ZOOM_options_callback c, + void *handle); Events @@ -1349,7 +1471,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) with events. - int ZOOM_event (int no, ZOOM_connection *cs); + int ZOOM_event(int no, ZOOM_connection *cs); The ZOOM_event executes pending events for