X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=2ae3e08cb4737435865e38373dbeb6e3b29b1853;hp=ac9eadb45350089317b2270e8f3f60a3035f2b04;hb=7376ec7d3d905accea9593f80da3c11b650e743b;hpb=19411dcc2419807b0b81e7ad05f63880eba58d22 diff --git a/doc/zoom.xml b/doc/zoom.xml index ac9eadb..2ae3e08 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -5,6 +5,7 @@ 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) @@ -17,7 +18,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 @@ -29,22 +29,26 @@ 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 @@ -59,14 +63,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) ZOOM web-site for more information. - + In order to fully understand this chapter you should read and try the example programs zoomtst1.c, zoomtst2.c, .. in the zoom directory. - + The C language misses features found in object oriented languages such as C++, Java, etc. For example, you'll have to manually, @@ -83,29 +87,29 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) protocol. Connections - + The Connection object is a session with a target. #include <yaz/zoom.h> - - ZOOM_connection ZOOM_connection_new (const char *host, int portnum); - - ZOOM_connection ZOOM_connection_create (ZOOM_options options); - + + ZOOM_connection ZOOM_connection_new(const char *host, int portnum); + + ZOOM_connection ZOOM_connection_create(ZOOM_options options); + void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); void ZOOM_connection_destroy(ZOOM_connection c); Connection objects are created with either function - ZOOM_connection_new or + ZOOM_connection_new or ZOOM_connection_create. 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 - ZOOM_connection_connect. + ZOOM_connection_connect. If the port number, 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 @@ -115,7 +119,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 @@ -150,7 +155,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) The functions ZOOM_connection_option_set and ZOOM_connection_option_setl allows you to set an option given by key to the value - value for the connection. + value for the connection. For ZOOM_connection_option_set, the value is assumed to be a 0-terminated string. Function ZOOM_connection_option_setl specifies a @@ -192,10 +197,18 @@ 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 - asyncIf true (1) the connection operates in + 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 asynchronous operation which means that all calls are non-blocking except ZOOM_event. @@ -266,11 +279,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 transport type. Must be either soap, - get or post. - soap + + sru + SRU/SOLR transport type. Must be either soap, + get, post, or + solr. + soap sru_version SRU/SRW version. Should be 1.1, or @@ -279,12 +293,44 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) first operation), holds the negotiated version with the server (same or lower version). 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 + + apdulog + If set to a true value such as "1", a log of low-level + 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. + If either option lang or charset - is set, then + is set, then Character Set and Language Negotiation is in effect. @@ -345,14 +391,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. @@ -376,6 +422,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 @@ -388,17 +437,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 + ZOOM_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. - - + + 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 element + + + solrSolr sort + + + embedtype7 for Z39.50, cql for SRU, + solr for Solr protocol + + + +
Result sets @@ -439,7 +526,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) The number of hits also called result-count is returned by function ZOOM_resultset_size. - ZOOM Result set Options @@ -454,7 +541,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - startOffset of first record to be + 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 @@ -464,7 +551,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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. @@ -477,7 +564,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) option is also supported for the benefit of old applications.) 0 - elementSetNameElement-Set name of records. + elementSetNameElement-Set name of records. Most targets should honor element set name B and F for brief and full respectively. none @@ -512,14 +599,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) This information is a list of of items, where each item is - information about a term or subquery. All items in the list - are prefixed by + information about a term or subquery. All items in the list + are prefixed by SearchResult.no - where no presents the item number (0=first, 1=second). + where no presents the item number (0=first, 1=second). Read searchresult.size to determine the number of items. -
Search Info Report Options @@ -632,13 +719,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) preferredRecordSyntax are ignored. - Options start and count + Options start and count are supported by SRU. The remaining options - piggyback, - smallSetUpperBound, - largeSetLowerBound, - mediumSetPresentNumber, + piggyback, + smallSetUpperBound, + largeSetLowerBound, + mediumSetPresentNumber, mediumSetElementSetName, smallSetElementSetName are unsupported. @@ -650,9 +737,12 @@ 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 + However, the path part in host parameter for functions ZOOM_connecton_new and ZOOM_connection_connect acts as a database (at least for the &yaz; SRU server). @@ -681,7 +771,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) void ZOOM_record_destroy(ZOOM_record rec); - References to temporary records are returned by functions + References to temporary records are returned by functions ZOOM_resultset_records or ZOOM_resultset_record. @@ -693,7 +783,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) A single record is returned by function - ZOOM_resultset_record that takes a + ZOOM_resultset_record that takes a position as argument. First record has position zero. If no record could be obtained NULL is returned. @@ -726,22 +816,39 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) The type is a string of the format: - form[; charset=from[,to]] + format[;charset=from[/opacfrom][,to]][;format=v] - where form specifies the format of the + where format specifies the format of the returned record, from specifies the character set of the record in its original form (as returned by the server), to specifies the output (returned) character set encoding. - If charset is not given, then no character set conversion takes place. If to is omitted UTF-8 is assumed. + If charset is not given, then no character set conversion takes place. + + + OPAC records may be returned in a different + set from the bibliographic MARC record. If this is this the case, + opacfrom should be set to the character set + of the OPAC record part. + + + + Specifying the OPAC record character set requires YAZ 4.1.5 or later. + + + + 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. + the returned information. The following are the supported values for form. @@ -749,7 +856,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) database Database of record is returned as a C null-terminated string. Return type - const char *. + const char *. syntax @@ -757,13 +864,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) as a C null-terminated string containing the symbolic name of the record syntax, e.g. Usmarc. Return type is - const char *. + const char *. schema The schema of the record is returned as a C null-terminated string. Return type is - const char *. + const char *. render @@ -776,7 +883,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) raw The record is returned in the internal YAZ specific format. For GRS-1, Explain, and others, the - raw data is returned as type + raw data is returned as type Z_External * which is just the type for the member retrievalRecord in type NamePlusRecord. @@ -786,20 +893,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. @@ -807,7 +931,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Most MARC21 - records uses the + records uses the MARC-8 character set encoding. An application that wishes to display in Latin-1 would use @@ -836,14 +960,89 @@ 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 @@ -853,7 +1052,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?). @@ -865,11 +1064,11 @@ 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); @@ -892,7 +1091,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) a scan set offset pos and returns a pointer to a raw term or NULL if non-present. - If present, the occ and len + If present, the occ and len are set to the number of occurrences and the length of the actual term respectively. ZOOM_scanset_display_term is similar to @@ -924,7 +1123,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) more generic alternative to ZOOM_connection_scan which allows to use both CQL and PQF for Scan. - +
ZOOM Scan Set Options @@ -942,7 +1141,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. @@ -1038,7 +1237,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) ZOOM_package_send sends - the package the via connection specified in + the package the via connection specified in ZOOM_connection_package. The type specifies the actual extended service package type to be sent. @@ -1168,7 +1367,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) action - The update action. One of + The update action. One of specialUpdate, recordInsert, recordReplace, @@ -1199,7 +1398,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 + 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. @@ -1238,9 +1437,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 1, 2 or 3. Each version has a distinct OID: 1.2.840.10003.9.5 (first version) , - 1.2.840.10003.9.5.1 - (second version) and - 1.2.840.10003.9.5.1.1 + 1.2.840.10003.9.5.1 + (second version) and + 1.2.840.10003.9.5.1.1 (third and newest version). @@ -1249,7 +1448,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Database Create @@ -1257,7 +1456,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) For Database Create, type must be set to create in ZOOM_package_send. - + Database Create Options @@ -1281,13 +1480,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Database Drop For Database Drop, type must be set to drop in ZOOM_package_send. - + Database Drop Options @@ -1311,7 +1510,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Commit Operation For Commit, type must be set to commit in @@ -1366,7 +1565,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Events - If you're developing non-blocking applications, you have to deal + If you're developing non-blocking applications, you have to deal with events. @@ -1456,7 +1655,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - + - +