X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=63c1c1db44c9698bdf5d36b649db2112eef296dc;hp=7d043d2e1bbdfe58786d80437d4ef8906d103bde;hb=a0b43ae242eb940fb511c1d91742e61e442ca191;hpb=5b2fe23e1cffff1c658bdfe26fddc3f84256e7f4 diff --git a/doc/zoom.xml b/doc/zoom.xml index 7d043d2..63c1c1d 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -43,8 +43,11 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 +62,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 +86,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); - + 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 +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 @@ -150,7 +154,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 @@ -203,7 +207,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) of a client. Is used of ZOOM is used in a gateway of some sort. none - asyncIf true (1) the connection operates in + asyncIf true (1) the connection operates in asynchronous operation which means that all calls are non-blocking except ZOOM_event. @@ -274,12 +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 transport type. Must be either soap, + + sru + SRU/SOLR transport type. Must be either soap, get, post, or solr. - soap + soap sru_version SRU/SRW version. Should be 1.1, or @@ -292,16 +296,40 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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. + (a Term and a frequency). On request the terms is missing. On response the the list contains the terms that the target - could collect. + 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. @@ -362,14 +390,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. @@ -405,7 +433,7 @@ 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. @@ -456,7 +484,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 @@ -471,7 +499,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 @@ -481,7 +509,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. @@ -494,7 +522,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 @@ -529,14 +557,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 @@ -649,13 +677,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. @@ -667,9 +695,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). @@ -698,7 +729,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. @@ -710,7 +741,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. @@ -743,28 +774,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=v] + 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 + 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. @@ -772,7 +814,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 @@ -780,13 +822,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 @@ -799,7 +841,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. @@ -809,13 +851,13 @@ 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). - OPAC records are also converted to XML and the + 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 @@ -835,7 +877,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 @@ -847,7 +889,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 @@ -876,9 +918,9 @@ 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. @@ -886,8 +928,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Facets - 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 + 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. @@ -902,7 +946,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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. @@ -912,28 +956,28 @@ 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 + 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. + 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 @@ -945,7 +989,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?). @@ -984,7 +1028,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 @@ -1016,7 +1060,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 @@ -1130,7 +1174,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. @@ -1260,7 +1304,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, @@ -1291,7 +1335,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. @@ -1330,9 +1374,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). @@ -1341,7 +1385,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Database Create @@ -1349,7 +1393,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 @@ -1373,13 +1417,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 @@ -1403,7 +1447,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Commit Operation For Commit, type must be set to commit in @@ -1458,7 +1502,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. @@ -1548,7 +1592,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - + - +