X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=549e16d17abb5ac6bb9484c470302c33c9acb67e;hp=d2c561ca153f66e6e7d12a1e38dd5788ec4d88ba;hb=85fcb12fe992e4dc0fa91e95fc320943c1c26cc5;hpb=c5634aa19153b7b36e6de5a8e5b4536d69b2b7a1 diff --git a/doc/zoom.xml b/doc/zoom.xml index d2c561c..549e16d 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,6 +1,5 @@ - + Building clients with ZOOM - &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which @@ -14,24 +13,24 @@ became available, an implementation for &yaz; was quickly developed. For the first time, it is now as easy (or easier!) to develop clients than servers with &yaz;. This - chapter describes the &zoom; C binding. Before going futher, please + chapter describes the &zoom; C binding. Before going further, please reconsider whether C is the right programming language for the job. There are other language bindings available for &yaz;, and still more are in active development. See the - ZOOM website for + ZOOM web-site for more information. - + In order to fully understand this chapter you should read and try the example programs zoomtst1.c, zoomtst2.c, .. in the zoom directory. - + - The C language misses many features found in object oriented languages + The C language misses features found in object oriented languages such as C++, Java, etc. For example, you'll have to manually, destroy all objects you create, even though you may think of them as temporary. Most objects has a _create - and a @@ -42,7 +41,7 @@ In each of the sections below you'll find a sub section called - protocol behavior, that descries how the API maps to the Z39.50 + protocol behavior, that describes how the API maps to the Z39.50 protocol. Connections @@ -50,15 +49,15 @@ The Connection object is a session with a target. - #include <yaz/zoom.h> + #include <yaz/zoom.h> - ZOOM_connection ZOOM_connection_new (const char *host, int portnum); + ZOOM_connection ZOOM_connection_new (const char *host, int portnum); - ZOOM_connection ZOOM_connection_create (ZOOM_options options); - - void ZOOM_connection_connect(ZOOM_connection c, const char *host, + ZOOM_connection ZOOM_connection_create (ZOOM_options options); + + void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); - void ZOOM_connection_destroy (ZOOM_connection c); + void ZOOM_connection_destroy (ZOOM_connection c); Connection objects are created with either function @@ -69,7 +68,7 @@ a connection immediately, thus allowing you to specify options before establishing network connection using the function ZOOM_connection_connect. - If the portnumber, portnum, is zero, the + If the port number, portnum, is zero, the host is consulted for a port specification. If no port is given, 210 is used. A colon denotes the beginning of a port number in the host string. If the host string includes a @@ -91,10 +90,10 @@ The ZOOM_connection_option_set allows you to set an option given by key to the value value for the connection. - Function ZOOM_connection_option_get returns + Function ZOOM_connection_option_get returns the value for an option given by key. - ZOOM Connection Options +
ZOOM Connection Options @@ -118,7 +117,7 @@ none passAuthentication password - none + none hostTarget host. This setting is "read-only". It's automatically set internally when connecting to a target. @@ -138,25 +137,52 @@ preferredMessageSize Maximum size of multiple records. 1 MB + + lang Language for negotiation. + none + + charset Character set for negotiation. + none + + targetImplementationId Implementation ID of target. + none + + targetImplementationName Implementation Name of target. + none + + targetImplementationVersion Implementation Version + of target. + none
+ + If either option lang or charset + is set, then + + Character Set and Language Negotiation is in effect. + int ZOOM_connection_error (ZOOM_connection c, const char **cp, - const char **addinfo); + const char **addinfo); + int ZOOM_connection_error_x (ZOOM_connection c, const char **cp, + const char **addinfo, const char **dset); - Use ZOOM_connection_error to check for + Function ZOOM_connection_error checks for errors for the last operation(s) performed. The function returns zero if no errors occurred; non-zero otherwise indicating the error. Pointers cp and addinfo holds messages for the error and additional-info if passed as - non-NULL. + non-NULL. Function + ZOOM_connection_error_x is an extended version + of ZOOM_connection_error that is capable of + returning name of diagnostic set in dset. Protocol behavior The calls ZOOM_connection_new and - ZOOM_connection_connect establises a TCP/IP + ZOOM_connection_connect establishes a TCP/IP connection and sends an Initialize Request to the target if possible. In addition, the calls waits for an Initialize Response from the target and the result is inspected (OK or rejected). @@ -304,18 +330,22 @@ USMARC, SUTRS, etc. none + schemaSchema for retrieval, such as + 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 greator than this + 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 greator than small set upper bound. + is greater than small set upper bound. 0 smallSetElementSetName @@ -342,11 +372,11 @@ The creation of a result set involves at least a SearchRequest - SearchResponse protocol handshake. Following that, if a sort - critieria was specified as part of the query, a sortRequest - + criteria was specified as part of the query, a SortRequest - SortResponse handshake takes place. Note that it is necessary to 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 critieria + 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 transferred. @@ -372,7 +402,7 @@ because of a record size limit, etc. the client will repeat sending present requests. As an example, if option start is 0 (default) and count is 4, and - piggyback is 1 (default) and no sorting critieria + piggyback is 1 (default) and no sorting criteria is specified, then the client will attempt to retrieve the 4 records as part the search response (using piggyback). On the other hand, if either start is positive or if @@ -391,7 +421,7 @@ Records - A record object is a retrival record on the client side - + A record object is a retrieval record on the client side - created from result sets. @@ -400,8 +430,8 @@ size_t start, size_t count); ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos); - void *ZOOM_record_get (ZOOM_record rec, const char *type, - size_t *len); + const char *ZOOM_record_get (ZOOM_record rec, const char *type, + size_t *len); ZOOM_record ZOOM_record_clone (ZOOM_record rec); @@ -448,27 +478,32 @@ database Database of record is returned - as a C null-terminated string. Return type char *. + 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 char *. + as a C null-terminated string. Return type is + const char *. render The record is returned in a display friendly format. Upon completion buffer is returned - (type char *) and length is stored in + (type const char *) and length is stored in *len. raw The record is returned in the internal - YAZ specific format. The raw data is returned as type + YAZ specific format. For GRS-1, Explain, and others, the + raw data is returned as type Z_External * which is just the type for the member retrievalRecord in type NamePlusRecord. + For SUTRS and octet aligned record (including all MARCs) the + octet buffer is returned and the length of the buffer. @@ -493,6 +528,85 @@ + Scan + + This section describes an interface for Scan. Scan is not an + official part of the ZOOM model yet. The result of a scan operation + is the ZOOM_scanset which is a set of terms + returned by a target. + + + ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c, + const char *startterm); + + size_t ZOOM_scanset_size(ZOOM_scanset scan); + + const char * ZOOM_scanset_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 *key); + + 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. + 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. + If present, the occ and len + are set to the number of occurrences and the length + of the actual term respectively. + 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. + + + ZOOM Scan Set Options + + + + + + + Option + Description + Default + + + + + numberNumber of Scan Terms requested in next scan. + After scan it holds the actual number of terms returned. + 10 + + positionPreferred Position of term in response + in next scan; actual position after completion of scan. + 1 + + stepSizeStep Size + 0 + + scanStatusAn integer indicating the Scan Status + of last scan. + 0 + + +
+ + Options Most &zoom; objects provide a way to specify options to change behavior. @@ -537,7 +651,7 @@ cs (cs[0] ... cs[no-1]). A pending event could be a sending a search, receiving a response, etc. - When an event has occured for one of the connections, this function + When an event has occurred for one of the connections, this function returns a positive integer n denoting that an event occurred for connection cs[n-1]. When no events are pending for the connections, a value of zero is