X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=fa22ad0ea66f33d16bcd78441a9aa8c1027640a6;hp=d625e580c7f74c8e5733bfcc1f22e6add6e3107a;hb=b77f4b5c2b191b83cf3f213faa8b6b263e36fea4;hpb=1b74d7ac0e734e7740dae73ea340d24334960bc5 diff --git a/doc/zoom.xml b/doc/zoom.xml index d625e58..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. @@ -428,7 +475,7 @@ are prefixed by SearchResult.no where no presents the item number (0=first, 1=second). - Read SearchResult.size to determine the + Read searchresult.size to determine the number of items.
Search Info Report options @@ -443,33 +490,33 @@ - SearchResult.size + searchresult.size number of search result entries. This option is-nonexistant if no entries are returned by the server. - SearchResult.no.subqueryId + searchresult.no.id sub query ID - SearchResult.no.subqueryCount + searchresult.no.count result count for item (number of hits) - SearchResult.no.subquery.term + searchresult.no.subquery.term subquery term - SearchResult.no.interpretation.term + searchresult.no.interpretation.term interpretation term - SearchResult.no.recommendation.term + searchresult.no.recommendation.term recommendation term @@ -684,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). @@ -702,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 @@ -756,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); @@ -769,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. @@ -804,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 @@ -836,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);