X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=74c95f36fade78fe9344626f42a699e3921b34bb;hp=2937474acbd5f6cd68b16bd5334c7100a234317f;hb=6e32d36c608fe4c1e345e07ba0bf93b1129f58f1;hpb=49218d3cab22778f7460f1099d0534e057be629f diff --git a/doc/zoom.xml b/doc/zoom.xml index 2937474..74c95f3 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,6 +1,23 @@ - - Building clients with ZOOM - + + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which @@ -8,18 +25,39 @@ provide a common Z39.50 client API not bound to a particular programming language or toolkit. + + + 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 + and more apparent over time. So when the first &zoom; specification became available, an implementation for &yaz; was quickly developed. For the first time, it is now as easy (or easier!) to develop clients than servers with &yaz;. This - chapter describes the ZOOM C binding. Before going futher, please + chapter describes the &zoom; C binding. Before going further, please reconsider whether C is the right programming language for the job. There are other language bindings available for &yaz;, and still more - are in active development. See the ZOOM website at - zoom.z3950.org for + are in active development. See the + ZOOM web-site for more information. @@ -31,7 +69,7 @@ - The C language misses many features found in object oriented languages + The C language misses features found in object oriented languages such as C++, Java, etc. For example, you'll have to manually, destroy all objects you create, even though you may think of them as temporary. Most objects has a _create - and a @@ -42,61 +80,91 @@ In each of the sections below you'll find a sub section called - protocol behavior, that descries how the API maps to the Z39.50 + 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> - - Z3950_connection Z3950_connection_new (const char *host, int portnum); - - Z3950_connection Z3950_connection_create (Z3950_options options); + #include <yaz/zoom.h> + + ZOOM_connection ZOOM_connection_new(const char *host, int portnum); - void Z3950_connection_connect(Z3950_connection c, const char *host, + ZOOM_connection ZOOM_connection_create(ZOOM_options options); + + void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); - void Z3950_connection_destroy (Z3950_connection c); + void ZOOM_connection_destroy(ZOOM_connection c); Connection objects are created with either function - Z3950_connection_new or - Z3950_connection_create. + 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 - Z3950_connection_connect. - If the portnumber, portnum, is zero, the + 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 a port number in the host string. If the host string includes a slash, the following part specifies a database for the connection. + 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. + + + 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 - Z3950_connection_destroy. + ZOOM_connection_destroy. - const char *Z3950_connection_option (Z3950_connection c, - const char *key, - const char *val); - const char *Z3950_connection_host (Z3950_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, int len); + + 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 Z3950_connection_option allows you to - inspect or set an option given by key - for the connection. - If val is non-NULL that - holds the new value for option. - Otherwise, if val is - NULL, - the option is unchanged. - The function returns the previous value of the option. - - ZOOM Connection Options + 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. + 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 @@ -119,16 +187,31 @@ groupAuthentication group name none - passAuthentication password - none + 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 - Z3950_event. + ZOOM_event. 0 maximumRecordSize Maximum size of single record. @@ -136,33 +219,163 @@ preferredMessageSize Maximum size of multiple records. 1 MB + + lang Language for negotiation. + none + + charset Character set for negotiation. + none + + serverImplementationId + Implementation ID of server. (The old targetImplementationId + option is also supported for the benefit of old applications.) + none + + targetImplementationName + Implementation Name of server. (The old + targetImplementationName option is also supported for the + benefit of old applications.) + none + + 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 + Requested or recommend facets may be given before a search is sent. + The value of this setting is described in + For inspection of the facets returned, refer to the functions + described in . + 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. + + + memcached + If given and non-empty, + libMemcached + will be configured for the connection. + This option is inspected by ZOOM when a connection is established. + If the memcached option is given + and YAZ is compiled without libMemcached support, an internal + diagnostic (10018) will be thrown. + libMemcached support is available for YAZ 5.0.13 or later. If this + option is supplied for an earlier version of YAZ, it is + ignored. + The value of this option is a string passed verbatim to + the memcached function part of libMemcached. + Refer to man page + memcached(3). + Earlier versions of libMemcached + do not offer this function. In this case only the option + --server=host may + be given (YAZ emulates that part of libMemcached). + none
- Function Z3950_connection_host returns - the host for the connection as specified in a call to - Z3950_connection_new or - Z3950_connection_connect. - This function returns NULL if host isn't - set for the connection. + If either option lang or charset + is set, then + + Character Set and Language Negotiation is in effect. - int Z3950_connection_error (Z3950_connection c, const char **cp, - const char **addinfo); + 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); - Use Z3950_connection_error to check for + Function ZOOM_connection_error checks for errors for the last operation(s) performed. The function returns zero if no errors occurred; non-zero otherwise indicating the error. Pointers cp and addinfo holds messages for the error and additional-info if passed as - non-NULL. + non-NULL. Function + ZOOM_connection_error_x is an extended version + of ZOOM_connection_error that is capable of + returning name of diagnostic set in dset. - Protocol behavior + + Z39.50 Protocol behavior - The calls Z3950_connection_new and - Z3950_connection_connect establises a TCP/IP + The calls ZOOM_connection_new and + ZOOM_connection_connect establishes a TCP/IP connection and sends an Initialize Request to the target if possible. In addition, the calls waits for an Initialize Response from the target and the result is inspected (OK or rejected). @@ -190,47 +403,122 @@ When option async is 1, it really means that all network operations are postponed (and queued) until the - function Z3950_event is invoked. When doing so + function ZOOM_event is invoked. When doing so it doesn't make sense to check for errors after - Z3950_connection_new is called since that + ZOOM_connection_new is called since that operation "connecting - and init" is still incomplete and the API cannot tell the outcome (yet). + + SRU/Solr Protocol behavior + + 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 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. + + + 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 Query objects represents queries. - Z3950_query Z3950_query_create(void); + ZOOM_query ZOOM_query_create(void); + + void ZOOM_query_destroy(ZOOM_query q); + + int ZOOM_query_prefix(ZOOM_query q, const char *str); - void Z3950_query_destroy(Z3950_query q); + int ZOOM_query_cql(ZOOM_query s, const char *str); - int Z3950_query_prefix(Z3950_query q, const char *str); + int ZOOM_query_sortby(ZOOM_query q, const char *criteria); - int Z3950_query_sortby(Z3950_query q, const char *criteria); + int ZOOM_query_sortby2(ZOOM_query q, const char *strategy, + const char *criteria); - Create query objects using Z3950_query_create - and destroy them by calling Z3950_query_destroy. + Create query objects using ZOOM_query_create + and destroy them by calling ZOOM_query_destroy. RPN-queries can be specified in PQF notation by using the - function Z3950_query_prefix. More - query types will be added later, such as + function ZOOM_query_prefix. + The ZOOM_query_cql specifies a CQL + query to be sent to the server/target. + 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 - Z3950_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 @@ -238,50 +526,41 @@ a target. - Z3950_resultset Z3950_connection_search(Z3950_connection, - Z3950_query q); - - Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, - const char *q); + ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q); - void Z3950_resultset_destroy(Z3950_resultset r); + ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c, + const char *q); + void ZOOM_resultset_destroy(ZOOM_resultset r); - Function Z3950_connection_search creates - a result set given a connection and query. + Function ZOOM_connection_search creates + a result set given a connection and query. Destroy a result set by calling - Z3950_resultset_destroy. + ZOOM_resultset_destroy. Simple clients may using PQF only may use function - Z3950_connection_search_pqf in which case + ZOOM_connection_search_pqf in which case creating query objects is not necessary. - const char *Z3950_resultset_option (Z3950_resultset r, - const char *key, - const char *val); + void ZOOM_resultset_option_set(ZOOM_resultset r, + const char *key, const char *val); - int Z3950_resultset_size (Z3950_resultset r); + const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key); - void *Z3950_resultset_get (Z3950_resultset s, size_t pos, - const char *type, size_t *len); + size_t ZOOM_resultset_size(ZOOM_resultset r); - Function Z3950_resultset_options sets or - modifies an option for a result set similar to - Z3950_connection_option. + Functions ZOOM_resultset_options_set and + ZOOM_resultset_get sets and gets an option + for a result set similar to ZOOM_connection_option_get + and ZOOM_connection_option_set. The number of hits also called result-count is returned by - function Z3950_resultset_size. + function ZOOM_resultset_size. - - Function Z3950_resultset_get is similar to - - Z3950_record_get but - instead of operating on a record object, it operates on a record on - a given offset within a result set. - - ZOOM Result set Options +
ZOOM Result set Options @@ -295,19 +574,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 - elementSetNameElement-Set name of records. + 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. Most targets should honor element set name B and F for brief and full respectively. none @@ -316,52 +606,129 @@ USMARC, SUTRS, 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 greator 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 greator than small set upper bound. - 0 - - smallSetElementSetName - The element set name to be used for small result sets. + schemaSchema for retrieval, such as + Gils-schema, Geo-schema, etc. 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 - databaseNameOne or more database names - separated by character plus (+). - 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
- - Protocol behavior + + 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 - SearchResponse protocol handshake. Following that, if a sort - critieria was specified as part of the query, a sortRequest - + criteria was specified as part of the query, a SortRequest - SortResponse handshake takes place. Note that it is necessary to 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 critieria - is set. Following Search - and a Possible sort, Retrieval takes - place - as one or more Present Requests - Present Response being + would be unsorted. Hence, piggyback is disabled when sort criteria + 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 @@ -379,7 +746,7 @@ because of a record size limit, etc. the client will repeat sending present requests. As an example, if option start is 0 (default) and count is 4, and - piggyback is 1 (default) and no sorting critieria + piggyback is 1 (default) and no sorting criteria is specified, then the client will attempt to retrieve the 4 records as part the search response (using piggyback). On the other hand, if either start is positive or if @@ -395,137 +762,918 @@ to specify one elementSetName option rather than three. + + SRU Protocol behavior + + Current version of &yaz; does not take advantage of a result set id + 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 SRU SearchRetrieveRequest + with same query but, possibly, different offsets. + + + Option schema specifies SRU schema + for retrieval. However, options elementSetName and + preferredRecordSyntax are ignored. + + + Options start and count + are supported by SRU. + The remaining options + piggyback, + smallSetUpperBound, + largeSetLowerBound, + mediumSetPresentNumber, + mediumSetElementSetName, + smallSetElementSetName are + unsupported. + + + SRU supports CQL queries, not PQF. + If PQF is used, however, the PQF query is transferred anyway + using non-standard element pQuery in + SRU SearchRetrieveRequest. + + + 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 + ZOOM_connection_connect acts as a + database (at least for the &yaz; SRU server). + + Records - A record object is a retrival record on the client side - + A record object is a retrieval record on the client side - created from result sets. - void Z3950_resultset_records (Z3950_resultset r, - Z3950_record *recs, - size_t start, size_t count); - Z3950_record Z3950_resultset_record (Z3950_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); + + int ZOOM_record_error(ZOOM_record rec, const char **msg, + const char **addinfo, const char **diagset); - void *Z3950_record_get (Z3950_record rec, const char *type, - size_t *len); + ZOOM_record ZOOM_record_clone(ZOOM_record rec); - void Z3950_record_destroy (Z3950_record rec); + void ZOOM_record_destroy(ZOOM_record rec); - Records are created by functions - Z3950_resultset_records or - Z3950_resultset_record - and destroyed by Z3950_record_destroy. + References to temporary records are returned by functions + ZOOM_resultset_records or + ZOOM_resultset_record. + + + If a persistent reference to a record is desired + ZOOM_record_clone should be used. + It returns a record reference that should be destroyed + by a call to ZOOM_record_destroy. - A single record is created and returned by function - Z3950_resultset_record that takes a + A single record is returned by function + ZOOM_resultset_record that takes a position as argument. First record has position zero. If no record could be obtained NULL is returned. - Function Z3950_resultset_records retrieves + 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 be returned. Upon completion array recs[0], ..recs[count-1] holds record objects for the records. The array of records - recs should be allocate prior to calling - Z3950_resultset_records. Note that for those + recs should be allocated prior the call + ZOOM_resultset_records. Note that for those records that couldn't be retrieved from the target recs[ ..] is set to NULL. In order to extract information about a single record, - Z3950_record_get is provided. The + ZOOM_record_get is provided. The function returns a pointer to certain record information. The - nature (type) of the pointer depends on the type - given. In addition for certain types, the length + nature (type) of the pointer depends on the parameter, + 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 - The database that holds the record is returned - as a C string. Return type char *. + Database of record is returned + as a C null-terminated string. Return type + const char *. - + syntax - The transfer syntax (OID) of the record is returned - as a C string. Return type char *. + 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 *. + + render The record is returned in a display friendly format. Upon completion buffer is returned - (type char *) and length is stored in + (type const char *) and length is stored in *len. - + raw The record is returned in the internal - YAZ specific format. The raw data is returned as type - Z_External * is just the type for + YAZ specific format. For GRS-1, Explain, and others, the + 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. + + + - 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 Z3950_resultset_record and - Z3950_resultset_records inspects the client-side - record cache. If the records(s) were not found, i.e. not yet retrieved - from, they are fetched using Present Requests. + The functions ZOOM_resultset_record and + ZOOM_resultset_records inspects the client-side + record cache. Records not found in cache are fetched using + Present. + The functions may block (and perform network I/O) - even though option + async is 1, because they return records objects. + (and there's no way to return records objects without retrieving them!). + + + There is a trick, however, in the usage of function + ZOOM_resultset_records that allows for + 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. + + SRU/Solr Protocol behavior + + 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 + + Facet operations is not part of the official ZOOM specification, but + is an Index Data extension for YAZ-based Z39.50 targets, + Solr and SRU 2.0 targets. + + Facets may be requestd by the + facets option before a + search is sent. + For inspection of the returned facets, the following functions are + available: + + + ZOOM_facet_field *ZOOM_resultset_facets(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_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 + official part of the ZOOM model yet. The result of a scan operation + is the ZOOM_scanset which is a set of terms + returned by a target. + + + + 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, + 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); + + 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); + + + The scan set is created by function + ZOOM_connection_scan which performs a scan + 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 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. + + + + 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 + + + + + + + Option + Description + Default + + + + + numberNumber of Scan Terms requested in next scan. + After scan it holds the actual number of terms returned. + 20 + + positionPreferred Position of term in response + in next scan; actual position after completion of scan. + 1 + + stepSizeStep Size + 0 + + 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 default behavior. + 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 associate array / hash array, etc. + an associative array / hash. - Z3950_options Z3950_options_create (void); + ZOOM_options ZOOM_options_create(void); - Z3950_options Z3950_options_create_with_parent (Z3950_options parent); + ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent); - void Z3950_options_destroy (Z3950_options opt); + void ZOOM_options_destroy(ZOOM_options opt); - const char *Z3950_options_get (Z3950_options opt, const char *name); + const char *ZOOM_options_get(ZOOM_options opt, const char *name); - void Z3950_options_set (Z3950_options opt, const char *name, - const char *v); + void ZOOM_options_set(ZOOM_options opt, const char *name, + const char *v); - typedef const char *(*Z3950_options_callback) - (void *handle, const char *name); + typedef const char *(*ZOOM_options_callback) + (void *handle, const char *name); - Z3950_options_callback - Z3950_options_set_callback (Z3950_options opt, - Z3950_options_callback c, - void *handle); + ZOOM_options_callback + 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 Z3950_event (int no, Z3950_connection *cs); + int ZOOM_event(int no, ZOOM_connection *cs); - The Z3950_event executes pending events for + The ZOOM_event executes pending events for a number of connections. Supply the number of connections in no and an array of connections in cs (cs[0] ... cs[no-1]). A pending event could be a sending a search, receiving a response, etc. - When an event has a occured for one of the connections, this function + When an event has occurred for one of the connections, this function returns a positive integer n denoting that an event occurred for connection cs[n-1]. When no events are pending for the connections, a value of zero is @@ -533,9 +1681,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 + + + +
- + - +