From c20830c3e36706390cc7a15c2a3a4ffa071dc36a Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Tue, 8 Nov 2005 21:53:01 +0000 Subject: [PATCH] Clarify start term in ZOOM_connection_scan. Document ZOOM_package functions (extended service facilities). --- doc/zoom.xml | 374 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 351 insertions(+), 23 deletions(-) diff --git a/doc/zoom.xml b/doc/zoom.xml index 476b44e..3bd7080 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,18 +1,11 @@ - + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -119,18 +111,32 @@ ZOOM_event(no, cs) 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 @@ -782,8 +788,8 @@ ZOOM_event(no, cs) - 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); @@ -795,16 +801,17 @@ ZOOM_event(no, cs) 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. @@ -830,6 +837,15 @@ ZOOM_event(no, cs) 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 @@ -862,13 +878,325 @@ ZOOM_event(no, cs)
+ + + 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); -- 1.7.10.4