X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=78b5d723bf02bf91c8142c0b9a1689c891c5b595;hp=1a0aa9eba6987c446df0ae59e14ac0d59de38242;hb=191c5db0e914f9774413da50bb1963ecf22b2f5c;hpb=69bcd68523a9a8da083faef16887100369152673 diff --git a/doc/zoom.xml b/doc/zoom.xml index 1a0aa9e..78b5d72 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,22 +1,64 @@ - - ZOOM - + + ZOOM - &zoom; is an acronym for Z39.50 Object Oriented Model and is - an initiative started by Mike Taylor. The goal of &zoom; is to + &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is + an initiative started by Mike Taylor (Mike is from the UK, which + explains the peculiar name of the model). The goal of &zoom; is to 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; was more apparanet - than ever. So, when the first ZOOM specification was available - an implementation for &yaz; was developed. For the first time, it is - now easier to develop clients than servers with &yaz;. This - chapter describes the ZOOM C binding. Before going futher - reconsider whether C is still the programming language of your - choice. There are other language bindings available and others - are in active development. See the ZOOM website at - zoom.z3950.org for + 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 + 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 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 web-site for more information. @@ -28,8 +70,8 @@ - The C language misses many features found in object oriented languages - such as C++, Java, etc. For example, you'll have to, manually, + 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 _destroy variant. @@ -37,205 +79,1606 @@ that because of typedefs. All destroy methods should gracefully ignore a NULL pointer. - Connections - - The connection object Z3950_connection describes - the connection between your client and a server. + + In each of the sections below you'll find a sub section called + protocol behavior, that describes how the API maps to the Z39.50 + protocol. + + Connections + + The Connection object is a session with a target. - #include <yaz/zoom.h> + #include <yaz/zoom.h> - Z3950_connection Z3950_connection_new (const char *host, int portnum); + ZOOM_connection ZOOM_connection_new(const char *host, int portnum); - Z3950_connection Z3950_connection_create (Z3950_options options); + ZOOM_connection ZOOM_connection_create(ZOOM_options options); - void Z3950_connection_connect(Z3950_connection c, const char *host, + 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. - The former both creates and attempts to establishes a network - connection with the target. The latter doesn't establishes - a connection immediately, thus allowing you to set specify options - before establishing network connection using function - Z3950_connection_connect. - If the portnumber, portnum, is zero, the + 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. + 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 that specifies a database for the connection. + slash, the following part specifies a database for the connection. - Connection objects should be destroyed using function - Z3950_connection_destroy. + 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 - - const char *Z3950_connection_option (Z3950_connection c, - const char *key, - const char *val); - - 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. + Connection objects should be destroyed using the function + ZOOM_connection_destroy. - 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); - Function Z3950_connection_host returns - the host for the connection as specified in either a call to - Z3950_connection_new or - Z3950_connection_connect. - This function returns NULL if host isn't - set for the connection. + 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 + + + + + + + Option + Description + Default + + + + + implementationNameName of Your client + none + + userAuthentication user name + none + + groupAuthentication group name + none + + passwordAuthentication password. + none + + hostTarget host. This setting is "read-only". + It's automatically set internally when connecting to a target. + none + + 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 + asynchronous operation which means that all calls are non-blocking + except + ZOOM_event. + 0 + + maximumRecordSize Maximum size of single record. + 1 MB + + 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 + 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 + + 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 - 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. + 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. Function + ZOOM_connection_error_x is an extended version + of ZOOM_connection_error that is capable of + returning name of diagnostic set in dset. + + Z39.50 Protocol behavior + + 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). + + + If proxy is set then the client will establish + a TCP/IP connection with the peer as specified by the + proxy host and the hostname as part of the + connect calls will be set as part of the Initialize Request. + The proxy server will then "forward" the PDU's transparently + to the target behind the proxy. + + + For the authentication parameters, if option user + is set and both options group and + pass are unset, then Open style + authentication is used (Version 2/3) in which case the username + is usually followed by a slash, then by a password. + If either group + or pass is set then idPass authentication + (Version 3 only) is used. If none of the options are set, no + authentication parameters are set as part of the Initialize Request + (obviously). + + + When option async is 1, it really means that + all network operations are postponed (and queued) until the + function ZOOM_event is invoked. When doing so + it doesn't make sense to check for errors after + 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 SOAP service. + + 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. + + - Search objects + Queries - Search objects defines how result sets are obtained. They - act like queries. + Query objects represents queries. - Z3950_search Z3950_search_create(void); + ZOOM_query ZOOM_query_create(void); + + void ZOOM_query_destroy(ZOOM_query q); - void Z3950_search_destroy(Z3950_search s); + int ZOOM_query_prefix(ZOOM_query q, const char *str); - int Z3950_search_prefix(Z3950_search s, const char *str); + int ZOOM_query_cql(ZOOM_query s, const char *str); - int Z3950_search_sortby(Z3950_search s, const char *criteria); + int ZOOM_query_sortby(ZOOM_query q, const char *criteria); + + int ZOOM_query_sortby2(ZOOM_query q, const char *strategy, + const char *criteria); - Create search objects using Z3950_search_create - and destroy them by calling Z3950_search_destroy. - RPN-queries can be specified in PQF notation by using the - function Z3950_search_prefix. More - query types will be added later, such as CCL to RPN-mapping, CCL - query, etc. - In addition to a search a sort critieria may be set. Function - Z3950_search_sortby specifies a sort - criteria using the same string notation for sort as offered by - the YAZ client. + 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 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 + ZOOM_query_sortby enables Z39.50 sorting and + it takes sort criteria using the same string notation as + yaz-client's sort command. + + + 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 + Result sets - The result set describes a collection of records obtained from - search. + The result set object is a container for records returned from + a target. - Z3950_resultset Z3950_connection_search(Z3950_connection, - Z3950_search q); + ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q); - Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c, - const char *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. + Destroy a result set by calling + ZOOM_resultset_destroy. + Simple clients may using PQF only may use function + ZOOM_connection_search_pqf in which case + creating query objects is not necessary. + + + 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); - void Z3950_resultset_destroy(Z3950_resultset r); + size_t ZOOM_resultset_size(ZOOM_resultset r); - Function Z3950_connection_search creates - a result set given a connection - and search object. - Destroy a result set by calling - Z3950_resultset_destroy. - Simple clients using YAZ' prefix query format may use - function Z3950_connection_search_pqf - instead. + 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 ZOOM_resultset_size. + + ZOOM Result set Options + + + + + + + Option + Description + Default + + + + + 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. + Most targets should honor element set name B + and F for brief and full respectively. + none + + preferredRecordSyntaxPreferred Syntax, such as + USMARC, SUTRS, etc. + none + + schemaSchema for retrieval, such as + Gils-schema, Geo-schema, etc. + 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 + - SearchResponse protocol handshake. Following that, if a sort + 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 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 searching on a Connection object + for which the settings + smallSetUpperBound, + mediumSetPresentNumber and + largeSetLowerBound are set. The low level mode + thus allows you to precisely set how records are returned as part + of a search response as offered by the Z39.50 protocol. + Since the client may be retrieving records as part of the + search response, this mode doesn't work well if sorting is used. + + + The high-level mode allows you to fetch a range of records from + the result set with a given start offset. When you use this mode + the client will automatically use piggyback if that is possible + with the target and perform one or more present requests as needed. + Even if the target returns fewer records as part of a present response + 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 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 + a sorting criteria is set, or if piggyback + is 0, then the client will not perform piggyback but send Present + Requests instead. + + + If either of the options mediumSetElementSetName and + smallSetElementSetName are unset, the value + of option elementSetName is used for piggyback + searches. This means that for the high-level mode you only have + 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 retrieval record on the client side - + created from result sets. - const char *Z3950_resultset_option (Z3950_resultset r, - const char *key, - const char *val); + 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); - int Z3950_resultset_size (Z3950_resultset r); + ZOOM_record ZOOM_record_clone(ZOOM_record rec); - void *Z3950_resultset_get (Z3950_resultset s, int pos, - const char *type, int *len); - void Z3950_resultset_records (Z3950_resultset r, - Z3950_record *recs, - size_t *cnt); + void ZOOM_record_destroy(ZOOM_record rec); - Description of result sets here. + 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 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. + + + 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 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, + 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. + + 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 *. + + + syntax + 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 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 + 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. + + + + + + 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 + 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. + + - Records + Facets - A record object is a retrival record on the client side - - created from result sets. + 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. - Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos); + ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r); + + const char ** ZOOM_resultset_facets_names(ZOOM_resultset r); - Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s, - int pos); + ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r, + const char *facet_name); - void *Z3950_record_get (Z3950_record rec, const char *type, - int *len); + ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r, + int pos); - void Z3950_record_destroy (Z3950_record rec); + 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 + 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 + + +
- Options + + 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 . + + + + - Most objects in &zoom; allows you to specify options to change - behaviour. From an implementation point of view a set of options - is just like an associate array / hash array, etc. + 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. - Z3950_options Z3950_options_create (void); + ZOOM_package ZOOM_connection_package(ZOOM_connection c, + ZOOM_options options); - Z3950_options Z3950_options_create_with_parent (Z3950_options parent); + 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 Z3950_options_destroy (Z3950_options opt); + 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. + - const char *Z3950_options_get (Z3950_options opt, const char *name); + ZOOM_options ZOOM_options_create(void); + + ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent); - void Z3950_options_set (Z3950_options opt, const char *name, - const char *v); + void ZOOM_options_destroy(ZOOM_options opt); - typedef const char *(*Z3950_options_callback) - (void *handle, const char *name); + const char *ZOOM_options_get(ZOOM_options opt, const char *name); - Z3950_options_callback - Z3950_options_set_callback (Z3950_options opt, - Z3950_options_callback c, - void *handle); + void ZOOM_options_set(ZOOM_options opt, const char *name, + const char *v); + + + typedef const char *(*ZOOM_options_callback) + (void *handle, const char *name); + + ZOOM_options_callback + ZOOM_options_set_callback(ZOOM_options opt, + ZOOM_options_callback c, + void *handle); - Events + Events - If you're developing non-blocking applications you have to deal - with events. + 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 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 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 + returned. + 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 + + + +
- + - +