X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=8a6bb92af30e2cdd1e9eb7a410dd30b9ae2901e7;hp=0d0bac22e8eed7f713924c01375a8159adb74f37;hb=554423d357ed2bcf4ece977f85de3bc1307d6536;hpb=f6379872ace49628473c47d23b29e9f46b5afbe4 diff --git a/doc/zoom.xml b/doc/zoom.xml index 0d0bac2..8a6bb92 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -17,10 +17,9 @@ ZOOM_options_setl(opt, name, value, len) ZOOM_options_get_bool(opt, name, defa) ZOOM_options_get_int(opt, name, defa) ZOOM_options_set_int(opt, name, value) -ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm) +ZOOM_connection_scan1(ZOOM_connection c, ZOOM_query startterm) ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) --> - ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -30,18 +29,25 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) programming language or toolkit. - - - A recent addition to &yaz; is SRU support. You can now make - SRU ZOOM connections by specifying scheme http:// - for the hostname for a connection. The dialect of SRU used is - specified by the value of the connection's sru - option, which may be SRU over HTTP GET (get), - SRU over HTTP POST (post) or SRW (SRU over - SOAP) (soap). - - - + + 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 @@ -92,7 +98,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); - void ZOOM_connection_destroy (ZOOM_connection c); + void ZOOM_connection_destroy(ZOOM_connection c); Connection objects are created with either function @@ -112,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 @@ -120,7 +127,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 initialisation + 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 @@ -189,7 +196,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) It's automatically set internally when connecting to a target. none - proxyProxy host + proxyProxy host. If set, the logical host + is encoded in the otherInfo area of the Z39.50 Init PDU + with OID 1.2.840.10003.10.1000.81.1. + none + + clientIPClient IP. If set, is + encoded in the otherInfo area of a Z39.50 PDU with OID + 1.2.840.10003.10.1000.81.3. Holds the original IP addreses + of a client. Is used of ZOOM is used in a gateway of some sort. none asyncIf true (1) the connection operates in @@ -263,6 +278,28 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) discover whether the server claims to support the specified operations. none + + sru + SRU/SOLR transport type. Must be either soap, + get, post, or + solr. + soap + + sru_version + SRU/SRW version. Should be 1.1, or + 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 @@ -273,10 +310,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) Character Set and Language Negotiation is in effect. - int ZOOM_connection_error (ZOOM_connection c, const char **cp, - const char **addinfo); - int ZOOM_connection_error_x (ZOOM_connection c, const char **cp, - const char **addinfo, const char **dset); + int ZOOM_connection_error(ZOOM_connection c, const char **cp, + const char **addinfo); + int ZOOM_connection_error_x(ZOOM_connection c, const char **cp, + const char **addinfo, const char **dset); Function ZOOM_connection_error checks for @@ -329,14 +366,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU Protocol behavior + SRU/SOLR Protocol behavior - The SRU protocol doesn't feature an Inititialize Request, so + The HTTP based protocols (SRU, SRW, SOLR) doesn't feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the SOAP service. Most of the ZOOM connection options do not - affect SRU and they are ignored. However, future versions + affect SRU/SOLR and they are ignored. However, future versions of &yaz; might honor implementationName and put that as part of User-Agent header for HTTP requests. @@ -390,17 +427,15 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) a target. - ZOOM_resultset ZOOM_connection_search(ZOOM_connection, - ZOOM_query q); + ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q); ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c, const char *q); - void ZOOM_resultset_destroy(ZOOM_resultset r); Function ZOOM_connection_search creates - a result set given a connection and query. + a result set given a connection and query. Destroy a result set by calling ZOOM_resultset_destroy. Simple clients may using PQF only may use function @@ -408,14 +443,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) creating query objects is not necessary. - void ZOOM_resultset_option_set (ZOOM_resultset r, - const char *key, - const char *val); + void ZOOM_resultset_option_set(ZOOM_resultset r, + const char *key, const char *val); - const char *ZOOM_resultset_option_get (ZOOM_resultset r, - const char *key); + const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key); - size_t ZOOM_resultset_size (ZOOM_resultset r); + size_t ZOOM_resultset_size(ZOOM_resultset r); Functions ZOOM_resultset_options_set and @@ -445,13 +478,21 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) startOffset of first record to be retrieved from target. First record has offset 0 unlike the protocol specifications where first record has position 1. + This option affects ZOOM_resultset_search and + ZOOM_resultset_search_pqf and must be set before any of + these functions are invoked. If a range of + records must be fetched manually after search, + function ZOOM_resultset_records should be used. 0 - countNumber of records to be retrieved. + countNumber of records to be retrieved. + This option affects ZOOM_resultset_search and + ZOOM_resultset_search_pqf and must be set before any of + these functions are invoked. 0 presentChunkThe number of records to be - requested from the server in each chunk (present requst). The + requested from the server in each chunk (present request). The value 0 means to request all the records in a single chunk. (The old step option is also supported for the benefit of old applications.) @@ -474,6 +515,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 @@ -623,7 +671,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) SRU SearchRetrieveRequest. - Unfortunately, SRU does not define a database setting. Hence, + SOLR queries has to be done in SOLR query format. + + + Unfortunately, SRU or SOLR does not define a database setting. Hence, databaseName is unsupported and ignored. However, the path part in host parameter for functions ZOOM_connecton_new and @@ -649,9 +700,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) int ZOOM_record_error(ZOOM_record rec, const char **msg, const char **addinfo, const char **diagset); - ZOOM_record ZOOM_record_clone (ZOOM_record rec); + ZOOM_record ZOOM_record_clone(ZOOM_record rec); - void ZOOM_record_destroy (ZOOM_record rec); + void ZOOM_record_destroy(ZOOM_record rec); References to temporary records are returned by functions @@ -699,17 +750,34 @@ 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 @@ -733,6 +801,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) const char *. + schema + The schema of the record is returned + as a C null-terminated string. Return type is + const char *. + + render The record is returned in a display friendly format. Upon completion buffer is returned @@ -753,20 +827,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. @@ -803,14 +894,68 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - SRU Protocol behavior + SRU/SOLR Protocol behavior - The ZOOM driver for SRU treats records returned by a SRU server + The ZOOM driver for SRU/SOLR treats records returned by a SRU/SOLR server as if they where Z39.50 records with transfer syntax XML and no element set name or database name. + Facets + + Facets operations is not part of the official ZOOM specification, but is an Index Data extension + for YAZ-based Z39.50 targets or SOLR targets. + In case the target can and is requested to return facets, using a result set the ZOOM client + can request one or all facet fields. Using a facet field the client can request the term count and + then interate over the terms. + + + ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r); + const char ** ZOOM_resultset_facets_names(ZOOM_resultset r); + ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r, const char *facet_name); + ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r, int pos); + size_t ZOOM_resultset_facets_size(ZOOM_resultset r); + + const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field); + size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field); + const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field, size_t idx, int *freq); + + + References to temporary structures are returned by all functions. They are only valid as long the Result set is valid. + ZOOM_resultset_get_facet_field or + ZOOM_resultset_get_facet_field_by_index. + ZOOM_resultset_facets. + ZOOM_resultset_facets_names. + ZOOM_facet_field_name. + ZOOM_facet_field_get_term. + + + A single Facet field is returned by function + ZOOM_resultset_get_facet_field or ZOOM_resultset_get_facet_field_by_index that takes a + result set and facet name or positive index respectively. First facet has position zero. + If no facet could be obtained (invalid name or index out of bounds) NULL is returned. + + + An array of facets field can be returned by ZOOM_resultset_facets. The length of the array is + given by ZOOM_resultset_facets_size. The array is zero-based and last entry will be at + ZOOM_resultset_facets_size(result_set)-1. + + + It is possible to interate over facets by name, by calling ZOOM_resultset_facets_names. + This will return an const array of char * where each string can be used as parameter for + ZOOM_resultset_get_facet_field. + + + Function ZOOM_facet_field_name gets the request facet name from a returned facet field. + + + Function ZOOM_facet_field_get_term returns the idx'th term and term count for a facet field. + Idx must between 0 and ZOOM_facet_field_term_count-1, otherwise the returned reference will be + NULL. On a valid idx, the value of the freq reference will be the term count. + The *freq parameter must be valid pointer to integer. + + Scan This section describes an interface for Scan. Scan is not an @@ -820,26 +965,28 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) - 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 *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, - int *occ, size_t *len); + const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos, + size_t *occ, size_t *len); - void ZOOM_scanset_destroy (ZOOM_scanset scan); + void ZOOM_scanset_destroy(ZOOM_scanset scan); const char *ZOOM_scanset_option_get(ZOOM_scanset scan, - const char *key); + const char *key); void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key, const char *val); @@ -883,6 +1030,12 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) @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 @@ -901,7 +1054,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. @@ -913,6 +1066,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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
@@ -1031,10 +1191,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 succesful operation. + by the server. Read it after a successful operation. none @@ -1118,7 +1287,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) recordDelete, elementUpdate. - specialUpdate + specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate) recordIdOpaque @@ -1136,6 +1305,19 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) none + recordOpaque + Specifies an opaque record which is + encoded as an ASN.1 ANY type with the OID as tiven by option + syntax (see below). + Option recordOpaque is an alternative + to record - and record option (above) is + ignored if recordOpaque is set. This option is only available in + YAZ 3.0.35 and later and is meant to facilitate Updates with + servers from OCLC. + + none + + syntax The record syntax (transfer syntax). Is a string that is a known record syntax. @@ -1147,6 +1329,35 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) 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 + @@ -1243,26 +1454,26 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) an associative array / hash. - ZOOM_options ZOOM_options_create (void); + ZOOM_options ZOOM_options_create(void); - ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent); + ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent); - void ZOOM_options_destroy (ZOOM_options opt); + void ZOOM_options_destroy(ZOOM_options opt); - const char *ZOOM_options_get (ZOOM_options opt, const char *name); + const char *ZOOM_options_get(ZOOM_options opt, const char *name); - void ZOOM_options_set (ZOOM_options opt, const char *name, - const char *v); + void ZOOM_options_set(ZOOM_options opt, const char *name, + const char *v); typedef const char *(*ZOOM_options_callback) - (void *handle, const char *name); + (void *handle, const char *name); ZOOM_options_callback - ZOOM_options_set_callback (ZOOM_options opt, - ZOOM_options_callback c, - void *handle); + ZOOM_options_set_callback(ZOOM_options opt, + ZOOM_options_callback c, + void *handle); Events @@ -1271,7 +1482,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) with events. - int ZOOM_event (int no, ZOOM_connection *cs); + int ZOOM_event(int no, ZOOM_connection *cs); The ZOOM_event executes pending events for