X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=d1ccf8ea0424acab2bfa9187387a3276778d8a55;hp=ff97c7840edf4a2d3d4524b6882ccab7f073f9e1;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=efda1a40ecc4cb16b0073a2b8a895ad28d5bfe4e diff --git a/doc/zoom.xml b/doc/zoom.xml index ff97c78..d1ccf8e 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,4 +1,22 @@ - + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -8,14 +26,26 @@ programming language or toolkit. - - - A recent addition to &yaz; is SRW support. You can now make - SRW ZOOM connections by specifying scheme http:// - for the hostname for a connection. - - - + + 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 @@ -27,17 +57,17 @@ There are other language bindings available for &yaz;, and still more are in active development. See the - ZOOM web-site for + 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, @@ -53,30 +83,30 @@ protocol behavior, that describes how the API maps to the Z39.50 protocol. - Connections - + 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); + 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 @@ -86,28 +116,55 @@ You can prefix the host with a scheme followed by colon. The default scheme is tcp (Z39.50 protocol). - The scheme http selects SRW 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 + comma-separated + key=value + sequences, each of which represents an option to be set into the + connection structure before the + protocol-level connection is forged and the initialization + handshake takes place. This facility can be used to provide + authentication credentials, as in host-strings such as: + user=admin,password=halfAm4n,tcp:localhost:8017/db Connection objects should be destroyed using the function ZOOM_connection_destroy. - void ZOOM_connection_option_set (ZOOM_connection c, + void ZOOM_connection_option_set(ZOOM_connection c, + const char *key, const char *val); + + void ZOOM_connection_option_setl(ZOOM_connection c, const char *key, - const char *val); + const char *val, int len); - const char *ZOOM_connection_option_get (ZOOM_connection c, - const char *key); + const char *ZOOM_connection_option_get(ZOOM_connection c, + const char *key); + const char *ZOOM_connection_option_getl(ZOOM_connection c, + const char *key, + int *lenp); - The ZOOM_connection_option_set allows you to + 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. - Function ZOOM_connection_option_get returns + For ZOOM_connection_option_set, the + value is assumed to be a 0-terminated string. Function + ZOOM_connection_option_setl specifies a + value of a certain size (len). + + + Functions ZOOM_connection_option_get and + ZOOM_connection_option_getl returns the value for an option given by key. - ZOOM Connection Options +
+ ZOOM Connection Options @@ -130,17 +187,28 @@ groupAuthentication group name none - passAuthentication password + 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 - 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. @@ -158,34 +226,119 @@ charset Character set for negotiation. none - targetImplementationId Implementation ID of target. + serverImplementationId + Implementation ID of server. (The old targetImplementationId + option is also supported for the benefit of old applications.) none - targetImplementationName Implementation Name of target. + targetImplementationName + Implementation Name of server. (The old + targetImplementationName option is also supported for the + benefit of old applications.) none - targetImplementationVersion Implementation Version - of target. + serverImplementationVersion + Implementation Version of server. (the old + targetImplementationVersion option is also supported for the + benefit of old applications.) none databaseNameOne or more database names separated by character plus (+), which to be used by subsequent search requests on this Connection. Default + + piggybackTrue (1) if piggyback should be + used in searches; false (0) if not. + 1 + + smallSetUpperBoundIf hits is less than or equal to this + value, then target will return all records using small element set name + 0 + + largeSetLowerBoundIf hits is greater than this + value, the target will return no records. + 1 + + mediumSetPresentNumberThis value represents + the number of records to be returned as part of a search when when + hits is less than or equal to large set lower bound and if hits + is greater than small set upper bound. + 0 + + smallSetElementSetName + The element set name to be used for small result sets. + none + + mediumSetElementSetName + The element set name to be for medium-sized result sets. + none + + init_opt_search, init_opt_present, init_opt_delSet, etc. + After a successful Init, these options may be interrogated to + 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 + 1.2. This is , prior to connect, the version + to offer (highest version). And following connect (in fact + 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. - 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 @@ -198,7 +351,8 @@ of ZOOM_connection_error that is capable of returning name of diagnostic set in dset. - Z39.50 Protocol behavior + + Z39.50 Protocol behavior The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP/IP @@ -236,14 +390,15 @@ API cannot tell the outcome (yet). - SRW Protocol behavior + + SRU/Solr Protocol behavior - The SRW protocol 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 SRW 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. @@ -251,6 +406,19 @@ 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 @@ -267,6 +435,9 @@ 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 @@ -279,17 +450,55 @@ 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 @@ -297,17 +506,15 @@ 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 @@ -315,14 +522,12 @@ 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 @@ -334,7 +539,8 @@ The number of hits also called result-count is returned by function ZOOM_resultset_size. - ZOOM Result set Options +
ZOOM Result set Options @@ -348,19 +554,30 @@ - piggybackTrue (1) if piggyback should be - used in searches; false (0) if not. - 1 - - 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 + 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. + 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 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.) 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 @@ -373,36 +590,107 @@ Gils-schema, Geo-schema, etc. none - smallSetUpperBoundIf hits is less than or equal to this - value, then target will return all records using small element set name - 0 - - largeSetLowerBoundIf hits is greater than this - value, the target will return no records. - 1 - - mediumSetPresentNumberThis value represents - the number of records to be returned as part of a search when when - hits is less than or equal to large set lower bound and if hits - is greater than small set upper bound. - 0 - - smallSetElementSetName - The element set name to be used for small result sets. - none - - mediumSetElementSetName - The element set name to be for medium-sized result sets. - none - setnameName of Result Set (Result Set ID). If this option isn't set, the ZOOM module will automatically allocate a result set name. default + + rpnCharsetCharacter set for RPN terms. + If this is set, ZOOM C will assume that the ZOOM application is + running UTF-8. Terms in RPN queries are then converted to the + rpnCharset. If this is unset, ZOOM C will not assume any encoding + of RPN terms and no conversion is performed. + none
- + + For servers that support Search Info report, the following + options may be read using ZOOM_resultset_get. + This detailed information is read after a successful search has + completed. + + + 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 + SearchResult.no + where no presents the item number (0=first, 1=second). + Read searchresult.size to determine the + number of items. + + Search Info Report Options + + + + + + Option + Description + + + + + searchresult.size + + number of search result entries. This option is-nonexistant + if no entries are returned by the server. + + + + searchresult.no.id + sub query ID + + + searchresult.no.count + result count for item (number of hits) + + + searchresult.no.subquery.term + subquery term + + + + searchresult.no.interpretation.term + + interpretation term + + + + searchresult.no.recommendation.term + + recommendation term + + + +
+ + + 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 The creation of a result set involves at least a SearchRequest @@ -412,14 +700,15 @@ perform sorting before any retrieval takes place, so no records will be returned from the target as part of the SearchResponse because these would be unsorted. Hence, piggyback is disabled when sort criteria - is set. Following Search - and a Possible sort, Retrieval takes - place - as one or more Present Requests - Present Response being + are set. Following Search - and a possible sort - Retrieval takes + place - as one or more Present Requests/Response pairs being transferred. The API allows for two different modes for retrieval. A high level mode which is somewhat more powerful and a low level one. - The low level is "enabled" when the settings + The low level is enabled when searching on a Connection object + for which the settings smallSetUpperBound, mediumSetPresentNumber and largeSetLowerBound are set. The low level mode @@ -453,45 +742,48 @@ to specify one elementSetName option rather than three. - - SRW Protocol behavior + + SRU Protocol behavior Current version of &yaz; does not take advantage of a result set id - returned by the SRW server. Future versions might do, however. + returned by the SRU server. Future versions might do, however. Since, the ZOOM driver does not save result set IDs any - present (retrieval) is transformed to a SRW SearchRetrieveRequest + present (retrieval) is transformed to a SRU SearchRetrieveRequest with same query but, possibly, different offsets. - Option schema specifies SRW schema + Option schema specifies SRU schema for retrieval. However, options elementSetName and preferredRecordSyntax are ignored. - Options start and count - are supported by SRW. + Options start and count + are supported by SRU. The remaining options - piggyback, - smallSetUpperBound, - largeSetLowerBound, - mediumSetPresentNumber, + piggyback, + smallSetUpperBound, + largeSetLowerBound, + mediumSetPresentNumber, mediumSetElementSetName, smallSetElementSetName are unsupported. - SRW supports CQL queries, not PQF. + SRU supports CQL queries, not PQF. If PQF is used, however, the PQF query is transferred anyway using non-standard element pQuery in - SRW SearchRetrieveRequest. + SRU SearchRetrieveRequest. + + + Solr queries has to be done in Solr query format. - Unfortunately, SRW 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 + 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; SRW server). + database (at least for the &yaz; SRU server). @@ -501,20 +793,23 @@ created from result sets. - void ZOOM_resultset_records (ZOOM_resultset r, - ZOOM_record *recs, - size_t start, size_t count); - ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos); + void ZOOM_resultset_records(ZOOM_resultset r, + ZOOM_record *recs, + size_t start, size_t count); + ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos); - const char *ZOOM_record_get (ZOOM_record rec, const char *type, - size_t *len); + const char *ZOOM_record_get(ZOOM_record rec, const char *type, + size_t *len); - ZOOM_record ZOOM_record_clone (ZOOM_record rec); + int ZOOM_record_error(ZOOM_record rec, const char **msg, + const char **addinfo, const char **diagset); - void ZOOM_record_destroy (ZOOM_record rec); + ZOOM_record ZOOM_record_clone(ZOOM_record rec); + + 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. @@ -526,11 +821,17 @@ 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. + Error information for a record can be checked with + ZOOM_record_error which returns non-zero + (error code) if record is in error, called Surrogate + Diagnostics in Z39.50. + + Function ZOOM_resultset_records retrieves a number of records from a result set. Parameter start and count specifies the range of records to @@ -547,44 +848,143 @@ ZOOM_record_get is provided. The function returns a pointer to certain record information. The nature (type) of the pointer depends on the parameter, - type. + type. + + + The type is a string of the format: + + + format[;charset=from[/opacfrom][,to]][;format=v] + + + 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 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 following are the supported values for form. database Database of record is returned as a C null-terminated string. Return type - const char *. + const char *. - + syntax - The transfer syntax (OID) of the record is returned + The transfer syntax of the record is returned + as a C null-terminated string containing the symbolic name of + the record syntax, e.g. Usmarc. Return type + is + const char *. + + + schema + The schema of the record is returned as a C null-terminated string. Return type is - const char *. + const char *. - + render The record is returned in a display friendly format. Upon completion buffer is returned (type const char *) and length is stored in *len. - + 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. For SUTRS and octet aligned record (including all MARCs) the octet buffer is returned and the length of the buffer. - + + xml + The record is returned in XML if possible. + 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 + 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 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. + + + json + Like xml, but MARC records are converted to + MARC-in-JSON. + + + - Z39.50 Protocol behavior + + Most + MARC21 + records uses the + MARC-8 + character set encoding. + An application that wishes to display in Latin-1 would use + + render; charset=marc8,iso-8859-1 + + + + Z39.50 Protocol behavior The functions ZOOM_resultset_record and ZOOM_resultset_records inspects the client-side @@ -597,20 +997,96 @@ There is a trick, however, in the usage of function ZOOM_resultset_records that allows for - delayed retrieval (and makes it non-blocking). By passing + delayed retrieval (and makes it non-blocking). By using a null pointer for recs you're indicating you're not interested in getting records objects now. - SRW Protocol behavior + + SRU/Solr Protocol behavior - The ZOOM driver for SRW treats records returned by a SRW 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 @@ -620,50 +1096,80 @@ - The Scan interface is Z39.50 only. SRW version 1.0 does not - support this. + The Scan interface is supported for both Z39.50, SRU and Solr. - ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c, - const char *startterm); + ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c, + const char *startpqf); + + ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c, + ZOOM_query q); 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, + 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 *ZOOM_scanset_option_get(ZOOM_scanset scan, + const char *key); - void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key, - const char *val); + void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key, + const char *val); The scan set is created by function ZOOM_connection_scan which performs a scan - operation on the connection and start term given. + operation on the connection using the specified + startpqf. If the operation was successful, the size of the scan set can be retrieved by a call to ZOOM_scanset_size. Like result sets, the items are numbered 0,..size-1. To obtain information about a particular scan term, call function ZOOM_scanset_term. This function takes a scan set offset pos and returns a pointer - to an actual term or NULL if non-present. - If present, the occ and len + to a raw term or NULL if + non-present. + 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 + ZOOM_scanset_term except that it returns + the display term rather than the raw term. + In a few cases, the term is different from display term. Always + use the display term for display and the raw term for subsequent + scan operations (to get more terms, next scan result, etc). + + A scan set may be freed by a call to function ZOOM_scanset_destroy. Functions ZOOM_scanset_option_get and ZOOM_scanset_option_set retrieves and sets an option respectively. - - ZOOM Scan Set Options + + + The startpqf is a subset of PQF, namely + the Attributes+Term part. Multiple @attr can + be used. For example to scan in title (complete) phrases: + + @attr 1=4 @attr 6=2 "science o" + + + + + The ZOOM_connecton_scan1 is a newer and + more generic alternative to ZOOM_connection_scan + which allows to use both CQL and PQF for Scan. + + +
+ ZOOM Scan Set Options @@ -679,7 +1185,7 @@ 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. @@ -691,47 +1197,455 @@ scanStatusAn integer indicating the Scan Status of last scan. 0 + + rpnCharsetCharacter set for RPN terms. + If this is set, ZOOM C will assume that the ZOOM application is + running UTF-8. Terms in RPN queries are then converted to the + rpnCharset. If this is unset, ZOOM C will not assume any encoding + of RPN terms and no conversion is performed. + none + + +
+ + + Extended Services + + ZOOM offers an interface to a subset of the Z39.50 extended services + as well as a few privately defined ones: + + + + + Z39.50 Item Order (ILL). + See . + + + + + Record Update. This allows a client to insert, modify or delete + records. + See . + + + + + Database Create. This a non-standard feature. Allows a client + to create a database. + See . + + + + + Database Drop. This a non-standard feature. Allows a client + to delete/drop a database. + See . + + + + + Commit operation. This a non-standard feature. Allows a client + to commit operations. + See . + + + + + + To create an extended service operation a ZOOM_package + must be created. The operation is a five step operation. The + package is created, package is configured by means of options, + the package is send, result is inspected (by means of options), + the package is destroyed. + + + ZOOM_package ZOOM_connection_package(ZOOM_connection c, + ZOOM_options options); + + const char *ZOOM_package_option_get(ZOOM_package p, + const char *key); + void ZOOM_package_option_set(ZOOM_package p, const char *key, + const char *val); + void ZOOM_package_send(ZOOM_package p, const char *type); + + void ZOOM_package_destroy(ZOOM_package p); + + + The ZOOM_connection_package creates a + package for the connection given using the options specified. + + + Functions ZOOM_package_option_get and + ZOOM_package_option_set gets and sets + options. + + + ZOOM_package_send sends + the package the via connection specified in + ZOOM_connection_package. + The type specifies the actual extended service + package type to be sent. + + + + Extended Service Common Options + + + + + + + Option + Description + Default + + + + + package-name + Extended Service Request package name. Must be specified + as part of a request + none + + + user-id + User ID of Extended Service Package. Is a request option + none + + + function + + Function of package - one of create, + delete, modify. Is + a request option. + + create + + + waitAction + + Wait action for package. Possible values: + wait, waitIfPossible, + dontWait or dontReturnPackage. + + waitIfPossible + + + targetReference + + Target Reference. This is part of the response as returned + by the server. Read it after a successful operation. + + none +
- + + Item Order + + For Item Order, type must be set to itemorder in + ZOOM_package_send. + + + + Item Order Options + + + + + + + Option + Description + Default + + + + + contact-name + ILL contact name + none + + + contact-phone + ILL contact phone + none + + + contact-email + ILL contact email + none + + + itemorder-item + Position for item (record) requested. An integer + 1 + + + +
+ + + + Record Update + + For Record Update, type must be set to update in + ZOOM_package_send. + + + + Record Update Options + + + + + + + Option + Description + Default + + + + + action + + The update action. One of + specialUpdate, + recordInsert, + recordReplace, + recordDelete, + elementUpdate. + + specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate) + + + recordIdOpaque + Opaque Record ID + none + + + recordIdNumber + Record ID number + none + + + record + The record itself + 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. + + no syntax + + + databaseName + Database from connection object + Default + + + correlationInfo.note + Correlation Info Note (string) + none + + + correlationInfo.id + Correlation Info ID (integer) + none + + + elementSetName + Element Set for Record + none + + + updateVersion + Record Update version which holds one of the values + 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 + (third and + newest version). + + 3 + + + +
+ + + + Database Create + + For Database Create, type must be set to create in + ZOOM_package_send. + + + + Database Create Options + + + + + + + Option + Description + Default + + + + + databaseName + Database from connection object + Default + + + +
+ + + Database Drop + + For Database Drop, type must be set to drop in + ZOOM_package_send. + + + + Database Drop Options + + + + + + + Option + Description + Default + + + + + databaseName + Database from connection object + Default + + + +
+ + + Commit Operation + + For Commit, type must be set to commit in + ZOOM_package_send. + + + + + Protocol behavior + + All the extended services are Z39.50-only. + + + + The database create, drop and commit services are privately defined + operations. + Refer to esadmin.asn in YAZ for the ASN.1 + definitions. + + + + Options Most &zoom; objects provide a way to specify options to change behavior. From an implementation point of view a set of options is just like - an associative array / hash array, etc. + 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); + + 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 + If you're developing non-blocking applications, you have to deal 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 @@ -748,9 +1662,76 @@ To ensure that all outstanding requests are performed call this function repeatedly until zero is returned. + + If ZOOM_event returns and returns non-zero, the + last event that occurred can be expected. + + + int ZOOM_connection_last_event(ZOOM_connection cs); + + + ZOOM_connection_last_event returns an event type + (integer) for the last event. + + + + ZOOM Event IDs + + + + + + Event + Description + + + + + ZOOM_EVENT_NONE + No event has occurred + + + ZOOM_EVENT_CONNECT + TCP/IP connect has initiated + + + ZOOM_EVENT_SEND_DATA + Data has been transmitted (sending) + + + ZOOM_EVENT_RECV_DATA + Data has been received) + + + ZOOM_EVENT_TIMEOUT + Timeout + + + ZOOM_EVENT_UNKNOWN + Unknown event + + + ZOOM_EVENT_SEND_APDU + An APDU has been transmitted (sending) + + + ZOOM_EVENT_RECV_APDU + An APDU has been received + + + ZOOM_EVENT_RECV_RECORD + A result-set record has been received + + + ZOOM_EVENT_RECV_SEARCH + A search result been received + + + +
- + - +