X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=fa22ad0ea66f33d16bcd78441a9aa8c1027640a6;hb=60f5103f542e3f6dd2e22b6df7015f7bc4b3a937;hp=f4ccd1c40fad1bfbc7847f1b0e475bf6e8b8338e;hpb=4fb9818b0657f561397b29e55d87cc8d4f194436;p=yaz-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index f4ccd1c..fa22ad0 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 @@ -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. @@ -89,22 +111,47 @@ The scheme http selects SRW 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 @@ -211,7 +258,7 @@ If either option lang or charset is set, then - + Character Set and Language Negotiation is in effect. @@ -416,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 @@ -624,7 +731,7 @@ The record is returned in XML if possible. SRW/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). @@ -642,13 +749,9 @@ Most - - MARC21 - + MARC21 records uses the - - MARC-8 - + MARC-8 character set encoding. An application that wishes to display in Latin-1 would use @@ -696,8 +799,8 @@ - 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); @@ -709,16 +812,17 @@ 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 using the specified startterm. + 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. @@ -744,6 +848,15 @@ 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 @@ -776,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); @@ -830,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 + + + +