X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=29f95147462815dcf1320b4b8b4ab0b64b80412e;hp=ccad2b0b966d2f359fe14a6519c271898d39ab47;hb=21f7c16c6b1b694405dbc1760d3d6cb3caac38f6;hpb=f17b1db33f969f735f308aa639c17488f82793d0 diff --git a/doc/zoom.xml b/doc/zoom.xml index ccad2b0..29f9514 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,4 +1,26 @@ - + + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -10,9 +32,9 @@ - A recent addition to &yaz; is SRW support. You can now make - SRW ZOOM connections by specifying another scheme for the - hostname for a connection. + A recent addition to &yaz; is SRU support. You can now make + SRU ZOOM connections by specifying scheme http:// + for the hostname for a connection. @@ -27,7 +49,7 @@ There are other language bindings available for &yaz;, and still more are in active development. See the - ZOOM web-site for + ZOOM web-site for more information. @@ -86,25 +108,50 @@ You can prefix the host with a scheme followed by colon. The default scheme is tcp (Z39.50 protocol). - The scheme http selects SRW over HTTP. + The scheme http selects SRU over HTTP. + + + 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 initialisation + handshake takes place. This facility can be used to provide + authentication credentials, as in host-strings such as: + user=admin,password=halfAm4n,tcp:localhost:8017/db Connection objects should be destroyed using the function ZOOM_connection_destroy. - void ZOOM_connection_option_set (ZOOM_connection c, + void ZOOM_connection_option_set(ZOOM_connection c, + const char *key, const char *val); + + void ZOOM_connection_option_setl(ZOOM_connection c, const char *key, - const char *val); + const char *val, int len); - const char *ZOOM_connection_option_get (ZOOM_connection c, - const char *key); + const char *ZOOM_connection_option_get(ZOOM_connection c, + const char *key); + const char *ZOOM_connection_option_getl(ZOOM_connection c, + const char *key, + int *lenp); - The ZOOM_connection_option_set allows you to + The functions ZOOM_connection_option_set and + ZOOM_connection_option_setl allows you to set an option given by key to the value - value for the connection. - Function ZOOM_connection_option_get returns + 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 @@ -130,7 +177,7 @@ groupAuthentication group name none - passAuthentication password + passwordAuthentication password. none hostTarget host. This setting is "read-only". @@ -158,27 +205,60 @@ charset Character set for negotiation. none - targetImplementationId Implementation ID of target. + serverImplementationId + Implementation ID of server. (The old targetImplementationId + option is also supported for the benefit of old applications.) none - targetImplementationName Implementation Name of target. + targetImplementationName + Implementation Name of server. (The old + targetImplementationName option is also supported for the + benefit of old applications.) none - targetImplementationVersion Implementation Version - of target. + serverImplementationVersion + Implementation Version of server. (the old + targetImplementationVersion option is also supported for the + benefit of old applications.) none databaseNameOne or more database names separated by character plus (+), which to be used by subsequent search requests on this Connection. Default + + piggybackTrue (1) if piggyback should be + used in searches; false (0) if not. + 1 + + smallSetUpperBoundIf hits is less than or equal to this + value, then target will return all records using small element set name + 0 + + largeSetLowerBoundIf hits is greater than this + value, the target will return no records. + 1 + + mediumSetPresentNumberThis value represents + the number of records to be returned as part of a search when when + hits is less than or equal to large set lower bound and if hits + is greater than small set upper bound. + 0 + + smallSetElementSetName + The element set name to be used for small result sets. + none + + mediumSetElementSetName + The element set name to be for medium-sized result sets. + none
If either option lang or charset is set, then - + Character Set and Language Negotiation is in effect. @@ -236,18 +316,20 @@ API cannot tell the outcome (yet). - SRW Protocol behavior + SRU Protocol behavior - The SRW protocol doesn't feature an Init Request, so + The SRU protocol doesn't feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the SOAP service. - None of the ZOOM connection options - affect SRW and they are ignored. However, future versions + Most of the ZOOM connection options do not + affect SRU 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, and lang - might also affect HTTP headers in future releases. + + + The charset is used in the Content-Type header + of HTTP requests. @@ -346,10 +428,6 @@ - piggybackTrue (1) if piggyback should be - used in searches; false (0) if not. - 1 - startOffset of first record to be retrieved from target. First record has offset 0 unlike the protocol specifications where first record has position 1. @@ -358,6 +436,13 @@ countNumber of records to be retrieved. 0 + presentChunkThe number of records to be + requested from the server in each chunk (present requst). 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. @@ -371,28 +456,6 @@ Gils-schema, Geo-schema, etc. none - smallSetUpperBoundIf hits is less than or equal to this - value, then target will return all records using small element set name - 0 - - largeSetLowerBoundIf hits is greater than this - value, the target will return no records. - 1 - - mediumSetPresentNumberThis value represents - the number of records to be returned as part of a search when when - hits is less than or equal to large set lower bound and if hits - is greater than small set upper bound. - 0 - - smallSetElementSetName - The element set name to be used for small result sets. - none - - mediumSetElementSetName - The element set name to be for medium-sized result sets. - none - setnameName of Result Set (Result Set ID). If this option isn't set, the ZOOM module will automatically allocate a result set name. @@ -400,6 +463,66 @@ + + 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 Protocol behavior @@ -410,14 +533,15 @@ perform sorting before any retrieval takes place, so no records will be returned from the target as part of the SearchResponse because these would be unsorted. Hence, piggyback is disabled when sort criteria - is set. Following Search - and a Possible sort, Retrieval takes - place - as one or more Present Requests - Present Response being + are set. Following Search - and a possible sort - Retrieval takes + place - as one or more Present Requests/Response pairs being transferred. The API allows for two different modes for retrieval. A high level mode which is somewhat more powerful and a low level one. - The low level is "enabled" when the settings + The low level is enabled when searching on a Connection object + for which the settings smallSetUpperBound, mediumSetPresentNumber and largeSetLowerBound are set. The low level mode @@ -452,22 +576,22 @@ - SRW Protocol behavior + SRU Protocol behavior Current version of &yaz; does not take advantage of a result set id - returned by the SRW server. Future versions might do, however. + returned by the SRU server. Future versions might do, however. Since, the ZOOM driver does not save result set IDs any - present (retrieval) is transformed to a SRW SearchRetrieveRequest + present (retrieval) is transformed to a SRU SearchRetrieveRequest with same query but, possibly, different offsets. - Option schema specifies SRW schema + Option schema specifies SRU schema for retrieval. However, options elementSetName and preferredRecordSyntax are ignored. Options start and count - are supported by SRW. + are supported by SRU. The remaining options piggyback, smallSetUpperBound, @@ -478,18 +602,18 @@ unsupported. - SRW supports CQL queries, not PQF. + SRU supports CQL queries, not PQF. If PQF is used, however, the PQF query is transferred anyway using non-standard element pQuery in - SRW SearchRetrieveRequest. + SRU SearchRetrieveRequest. - Unfortunately, SRW does not define a database setting. Hence, + Unfortunately, SRU 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; SRW server). + database (at least for the &yaz; SRU server). @@ -545,30 +669,53 @@ ZOOM_record_get is provided. The function returns a pointer to certain record information. The nature (type) of the pointer depends on the parameter, - type. + type. + + + The type is a string of the format: + + + form[; charset=from[,to]] + + + where form specifies the format of the + returned record, from + specifies the character set of the record in its original form + (as returned by the server), to specifies + the output (returned) + character set encoding. + If charset is not given, then no character set conversion takes place. + If to is omitted UTF-8 is assumed. + + In addition, for certain types, the length len passed will be set to the size in bytes of - the returned information. + the returned information. + + + The following are the supported values for form. database 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 null-terminated string. Return type is + 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 *. - + 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 @@ -579,9 +726,38 @@ 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 and Z39.50 records with transfer syntax XML are + returned verbatim. MARC records are returned in + + MARCXML + + (converted from ISO2709 to MARCXML by YAZ). + GRS-1 and OPAC records are not supported for this form. + Upon completion, the XML buffer is returned + (type const char *) and length is stored in + *len. + + + opac + OPAC for record is returned in XML. + + + + 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 @@ -595,15 +771,15 @@ There is a trick, however, in the usage of function ZOOM_resultset_records that allows for - delayed retrieval (and makes it non-blocking). By passing + delayed retrieval (and makes it non-blocking). By using a null pointer for recs you're indicating you're not interested in getting records objects now. - SRW Protocol behavior + SRU Protocol behavior - The ZOOM driver for SRW treats records returned by a SRW server + The ZOOM driver for SRU treats records returned by a SRU server as if they where Z39.50 records with transfer syntax XML and no element set name or database name. @@ -623,43 +799,64 @@ - ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c, - const char *startterm); + ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c, + const char *startpqf); size_t ZOOM_scanset_size(ZOOM_scanset scan); const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos, int *occ, size_t *len); + const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos, + int *occ, size_t *len); void ZOOM_scanset_destroy (ZOOM_scanset scan); - const char *ZOOM_scanset_option_get (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); + void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key, + const char *val); The scan set is created by function ZOOM_connection_scan which performs a scan - operation on the connection and start term given. + operation on the connection using the specified + startpqf. If the operation was successful, the size of the scan set can be retrieved by a call to ZOOM_scanset_size. Like result sets, the items are numbered 0,..size-1. To obtain information about a particular scan term, call function ZOOM_scanset_term. This function takes a scan set offset pos and returns a pointer - to an actual term or NULL if non-present. + 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" + + ZOOM Scan Set Options @@ -692,13 +889,325 @@
+ + + 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 + + + targetReference + + Target Reference. This is part of the response as returned + by the server. Read it after a succesful 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 + + + recordIdOpaque + Opaque Record ID + none + + + recordIdNumber + Record ID number + none + + + record + The record itself + none + + + syntax + The record syntax (transfer syntax). Is a string that + is a known record syntax. + + no syntax + + + databaseName + Database from connection object + Default + + + +
+ + + + 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 Create Options + + + + + + + Option + Description + Default + + + + + databaseName + Database from connection object + Default + + + +
+ + Commit Operation + + For Commit, type must be set to commit in + ZOOM_package_send. + + + + Protocol behavior + + All the extended services are Z39.50-only. + + + + The database create, drop and commit services are privately defined + operations. + Refer to esadmin.asn in YAZ for the ASN.1 + definitions. + + + + Options Most &zoom; objects provide a way to specify options to change behavior. From an implementation point of view a set of options is just like - an associative array / hash array, etc. + an associative array / hash. ZOOM_options ZOOM_options_create (void); @@ -746,6 +1255,72 @@ 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 + + + +