X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=29f95147462815dcf1320b4b8b4ab0b64b80412e;hp=570eea2ddceb838b856d9b720d79073379d31e5a;hb=21f7c16c6b1b694405dbc1760d3d6cb3caac38f6;hpb=a77e44dfd845725c768c8c60c1c01ba04209316d diff --git a/doc/zoom.xml b/doc/zoom.xml index 570eea2..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,8 +32,8 @@ - A recent addition to &yaz; is SRW support. You can now make - SRW ZOOM connections by specifying scheme http:// + 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 @@ -211,7 +258,7 @@ If either option lang or charset is set, then - + Character Set and Language Negotiation is in effect. @@ -269,14 +316,14 @@ API cannot tell the outcome (yet). - SRW Protocol behavior + SRU Protocol behavior - The SRW protocol doesn't feature an Inititialize 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. Most of the ZOOM connection options do not - affect SRW and they are ignored. However, future versions + 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. @@ -529,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, @@ -555,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). @@ -682,9 +729,9 @@ xml The record is returned in XML if possible. - SRW/SRU and Z39.50 records with transfer syntax XML are + 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 @@ -734,9 +777,9 @@ 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. @@ -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);