X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=2ae3e08cb4737435865e38373dbeb6e3b29b1853;hp=8a6bb92af30e2cdd1e9eb7a410dd30b9ae2901e7;hb=7376ec7d3d905accea9593f80da3c11b650e743b;hpb=275390c6f75f5f1adf39a0bae4893168b95f7695 diff --git a/doc/zoom.xml b/doc/zoom.xml index 8a6bb92..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 @@ -45,8 +45,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 @@ -62,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, @@ -86,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 @@ -118,8 +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/get over HTTP by default, - but can overridded to use SRU/post, SRW and the SOLR protocol. + 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 @@ -154,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 @@ -207,7 +208,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. @@ -296,16 +297,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. @@ -397,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 @@ -409,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 @@ -460,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 @@ -475,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 @@ -485,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. @@ -498,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 @@ -533,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 @@ -653,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. @@ -676,7 +742,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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). @@ -705,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. @@ -717,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. @@ -762,7 +828,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 @@ -776,13 +842,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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. @@ -790,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 @@ -798,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 @@ -817,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. @@ -831,9 +897,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 @@ -853,7 +919,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 @@ -865,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 @@ -904,25 +970,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. @@ -932,28 +1010,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 - 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 @@ -1004,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 @@ -1036,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 @@ -1150,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. @@ -1280,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, @@ -1311,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. @@ -1350,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). @@ -1361,7 +1448,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- + Database Create @@ -1369,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 @@ -1393,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 @@ -1423,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 @@ -1478,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. @@ -1568,7 +1655,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - + - +