From: Adam Dickmeiss Date: Wed, 8 Aug 2001 19:33:21 +0000 (+0000) Subject: Added chapter about YAZ client. X-Git-Tag: YAZ.1.8~60 X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=commitdiff_plain;h=fe4182bf1ca7bebcb3172cde916d4467c2154e7b Added chapter about YAZ client. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index f43dad3..1efb114 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.13 2001-07-20 21:34:36 adam Exp $ +## $Id: Makefile.am,v 1.14 2001-08-08 19:33:21 adam Exp $ docdir=$(pkgdatadir)/doc @@ -36,7 +36,8 @@ yaz.html: $(srcdir)/yaz.sgml XMLFILES=$(srcdir)/yaz.xml $(srcdir)/introduction.xml \ $(srcdir)/installation.xml $(srcdir)/indexdata.xml $(srcdir)/asn.xml \ $(srcdir)/tools.xml $(srcdir)/odr.xml $(srcdir)/comstack.xml \ - $(srcdir)/frontend.xml $(srcdir)/license.xml $(srcdir)/future.xml + $(srcdir)/frontend.xml $(srcdir)/license.xml $(srcdir)/future.xml \ + $(srcdir)/client.xml $(srcdir)/book1.html: $(XMLFILES) $(srcdir)/yazhtml.dsl cd $(srcdir); jade -E14 -d yazhtml.dsl -t sgml xml.dcl yaz.xml diff --git a/doc/asn.xml b/doc/asn.xml index 36da812..453e856 100644 --- a/doc/asn.xml +++ b/doc/asn.xml @@ -1,140 +1,140 @@ - -The ASN Module - Introduction - - The &asn; module provides you with a set of C struct definitions for the - various PDUs of the protocol, as well as for the complex types - appearing within the PDUs. For the primitive data types, the C - representation often takes the form of an ordinary C language type, - such as int. For ASN.1 constructs that have no direct - representation in C, such as general octet strings and bit strings, - the &odr; module (see section The ODR Module) - provides auxiliary definitions. - - - Preparing PDUs - - - A structure representing a complex ASN.1 type doesn't in itself contain the - members of that type. Instead, the structure contains - pointers to the members of the type. - This is necessary, in part, to allow a mechanism for specifying which - of the optional structure (SEQUENCE) members are present, and which - are not. It follows that you will need to somehow provide space for - the individual members of the structure, and set the pointers to - refer to the members. - - - The conversion routines don't care how you allocate and maintain your - C structures - they just follow the pointers that you provide. - Depending on the complexity of your application, and your personal - taste, there are at least three different approaches that you may take - when you allocate the structures. - - - - You can use static or automatic local variables in the function that - prepares the PDU. This is a simple approach, and it provides the most - efficient form of memory management. While it works well for flat - PDUs like the InitReqest, it will generally not be sufficient for say, - the generation of an arbitrarily complex RPN query structure. - - - You can individually create the structure and its members using the - malloc(2) function. If you want to ensure that - the data is freed when it is no longer needed, you will have to - define a function that individually releases each member of a - structure before freeing the structure itself. - - - You can use the odr_malloc() function (see section - Using ODR for details). When you use - odr_malloc(), you can release all of the - allocated data in a single operation, independent of any pointers and - relations between the data. odr_malloc() is based on a - "nibble-memory" - scheme, in which large portions of memory are allocated, and then - gradually handed out with each call to odr_malloc(). - The next time you call odr_reset(), all of the - memory allocated since the last call is recycled for future use (actually, - it is placed on a free-list). - - - You can combine all of the methods described here. This will often be - the most practical approach. For instance, you might use - odr_malloc() to allocate an entire structure and - some of its elements, while you leave other elements pointing to global - or per-session default variables. - - - - The &asn; module provides an important aid in creating new PDUs. For - each of the PDU types (say, Z_InitRequest), a - function is provided that allocates and initializes an instance of - that PDU type for you. In the case of the InitRequest, the function is - simply named zget_InitRequest(), and it sets up - reasonable default value for all of the mandatory members. The optional - members are generally initialized to null pointers. This last aspect - is very important: it ensures that if the PDU definitions are - extended after you finish your implementation (to accommodate - new versions of the protocol, say), you won't get into trouble with - uninitialized pointers in your structures. The functions use - odr_malloc() to - allocate the PDUs and its members, so you can free everything again with a - single call to odr_reset(). We strongly recommend - that you use the zget_* - functions whenever you are preparing a PDU (in a C++ API, the - zget_ - functions would probably be promoted to constructors for the - individual types). - - + + The ASN Module + Introduction + + The &asn; module provides you with a set of C struct definitions for the + various PDUs of the protocol, as well as for the complex types + appearing within the PDUs. For the primitive data types, the C + representation often takes the form of an ordinary C language type, + such as int. For ASN.1 constructs that have no direct + representation in C, such as general octet strings and bit strings, + the &odr; module (see section The ODR Module) + provides auxiliary definitions. + + + Preparing PDUs + + + A structure representing a complex ASN.1 type doesn't in itself contain the + members of that type. Instead, the structure contains + pointers to the members of the type. + This is necessary, in part, to allow a mechanism for specifying which + of the optional structure (SEQUENCE) members are present, and which + are not. It follows that you will need to somehow provide space for + the individual members of the structure, and set the pointers to + refer to the members. + + + The conversion routines don't care how you allocate and maintain your + C structures - they just follow the pointers that you provide. + Depending on the complexity of your application, and your personal + taste, there are at least three different approaches that you may take + when you allocate the structures. + + + + You can use static or automatic local variables in the function that + prepares the PDU. This is a simple approach, and it provides the most + efficient form of memory management. While it works well for flat + PDUs like the InitReqest, it will generally not be sufficient for say, + the generation of an arbitrarily complex RPN query structure. + + + You can individually create the structure and its members using the + malloc(2) function. If you want to ensure that + the data is freed when it is no longer needed, you will have to + define a function that individually releases each member of a + structure before freeing the structure itself. + + + You can use the odr_malloc() function (see section + Using ODR for details). When you use + odr_malloc(), you can release all of the + allocated data in a single operation, independent of any pointers and + relations between the data. odr_malloc() is based on a + "nibble-memory" + scheme, in which large portions of memory are allocated, and then + gradually handed out with each call to odr_malloc(). + The next time you call odr_reset(), all of the + memory allocated since the last call is recycled for future use (actually, + it is placed on a free-list). + + + You can combine all of the methods described here. This will often be + the most practical approach. For instance, you might use + odr_malloc() to allocate an entire structure and + some of its elements, while you leave other elements pointing to global + or per-session default variables. + + + + The &asn; module provides an important aid in creating new PDUs. For + each of the PDU types (say, Z_InitRequest), a + function is provided that allocates and initializes an instance of + that PDU type for you. In the case of the InitRequest, the function is + simply named zget_InitRequest(), and it sets up + reasonable default value for all of the mandatory members. The optional + members are generally initialized to null pointers. This last aspect + is very important: it ensures that if the PDU definitions are + extended after you finish your implementation (to accommodate + new versions of the protocol, say), you won't get into trouble with + uninitialized pointers in your structures. The functions use + odr_malloc() to + allocate the PDUs and its members, so you can free everything again with a + single call to odr_reset(). We strongly recommend + that you use the zget_* + functions whenever you are preparing a PDU (in a C++ API, the + zget_ + functions would probably be promoted to constructors for the + individual types). + + The prototype for the individual PDU types generally look like this: - - + + Z_<type> *zget_<type>(ODR o); - - - + + + eg.: - - - + + + Z_InitRequest *zget_InitRequest(ODR o); - + - + The &odr; handle should generally be your encoding stream, but it - needn't be. - - + needn't be. + + As well as the individual PDU functions, a function - zget_APDU() is provided, which allocates - a toplevel Z-APDU of the type requested: - - - + zget_APDU() is provided, which allocates + a toplevel Z-APDU of the type requested: + + + Z_APDU *zget_APDU(ODR o, int which); - - - - The which parameter is (of course) the discriminator - belonging to the Z_APDU CHOICE type. - All of the interface described here is provided by the &asn; module, and - you access it through the proto.h header file. - - - - Object Identifiers + + + + The which parameter is (of course) the discriminator + belonging to the Z_APDU CHOICE type. + All of the interface described here is provided by the &asn; module, and + you access it through the proto.h header file. + + + + Object Identifiers - When you refer to object identifiers in your application, you need to - be aware that SR and Z39.50 use two different set of OIDs to refer to - the same objects. To handle this easily, &yaz; provides a utility module - to &asn; which provides an internal representation of the OIDs used in - both protocols. Each oid is described by a structure: - - - + When you refer to object identifiers in your application, you need to + be aware that SR and Z39.50 use two different set of OIDs to refer to + the same objects. To handle this easily, &yaz; provides a utility module + to &asn; which provides an internal representation of the OIDs used in + both protocols. Each oid is described by a structure: + + + typedef struct oident { enum oid_proto proto; @@ -143,63 +143,63 @@ typedef struct oident int oidsuffix[OID_SIZE]; char *desc; } oident; - - - - The proto field can be set to either - PROTO_SR or PROTO_Z3950. - The class might be, say, - CLASS_RECSYN, and the value might be + + + + The proto field can be set to either + PROTO_SR or PROTO_Z3950. + The class might be, say, + CLASS_RECSYN, and the value might be VAL_USMARC for the USMARC record format. Functions - - - + + + int *oid_ent_to_oid(struct oident *ent, int *dst); struct oident *oid_getentbyoid(int *o); - - - - are provided to map between object identifiers and database entries. - If you store a member of the oid_proto type in - your association state information, it's a simple matter, at runtime, - to generate the correct OID when you need it. For decoding, you can - simply ignore the proto field, or if you're strict, you can verify - that your peer is using the OID family from the correct protocol. - The desc field is a short, human-readable name - for the PDU, useful mainly for diagnostic output. - - - + + - The old function oid_getoidbyent still exists but - is not thread safe. Use oid_ent_to_oid instead - and pass an array of size OID_SIZE. + are provided to map between object identifiers and database entries. + If you store a member of the oid_proto type in + your association state information, it's a simple matter, at runtime, + to generate the correct OID when you need it. For decoding, you can + simply ignore the proto field, or if you're strict, you can verify + that your peer is using the OID family from the correct protocol. + The desc field is a short, human-readable name + for the PDU, useful mainly for diagnostic output. - + + + + The old function oid_getoidbyent still exists but + is not thread safe. Use oid_ent_to_oid instead + and pass an array of size OID_SIZE. + + + + + + Plans are underway to merge the two protocols into a single + definition, with one set of object identifiers. When this happens, the + oid module will no longer be required to support protocol + independence, but it should still be useful as a simple OID database. + + - + + EXTERNAL Data + - Plans are underway to merge the two protocols into a single - definition, with one set of object identifiers. When this happens, the - oid module will no longer be required to support protocol - independence, but it should still be useful as a simple OID database. + In order to achieve extensibility and adaptability to different + application domains, the new version of the protocol defines many + structures outside of the main ASN.1 specification, referencing them + through ASN.1 EXTERNAL constructs. To simplify the construction and + access to the externally referenced data, the &asn; module defines a + specialized version of the EXTERNAL construct, called + Z_External.It is defined thus: - - - - EXTERNAL Data - - - In order to achieve extensibility and adaptability to different - application domains, the new version of the protocol defines many - structures outside of the main ASN.1 specification, referencing them - through ASN.1 EXTERNAL constructs. To simplify the construction and - access to the externally referenced data, the &asn; module defines a - specialized version of the EXTERNAL construct, called - Z_External.It is defined thus: - - - + + typedef struct Z_External { Odr_oid *direct_reference; @@ -238,112 +238,112 @@ typedef struct Z_External } u; } Z_External; - - - - When decoding, the &asn; module will attempt to determine which - syntax describes the data by looking at the reference fields - (currently only the direct-reference). For ASN.1 structured data, you - need only consult the which field to determine the - type of data. You can the access the data directly through the union. - When constructing data for encoding, you set the union pointer to point - to the data, and set the which field accordingly. + + + + When decoding, the &asn; module will attempt to determine which + syntax describes the data by looking at the reference fields + (currently only the direct-reference). For ASN.1 structured data, you + need only consult the which field to determine the + type of data. You can the access the data directly through the union. + When constructing data for encoding, you set the union pointer to point + to the data, and set the which field accordingly. Remember also to set the direct (or indirect) reference to the correct - OID for the data type. - For non-ASN.1 data such as MARC records, use the - octet_aligned arm of the union. - - - - Some servers return ASN.1 structured data values (eg. database - records) as BER-encoded records placed in the - octet-aligned branch of the EXTERNAL CHOICE. - The ASN-module will not automatically decode - these records. To help you decode the records in the application, the - function - - - + OID for the data type. + For non-ASN.1 data such as MARC records, use the + octet_aligned arm of the union. + + + + Some servers return ASN.1 structured data values (eg. database + records) as BER-encoded records placed in the + octet-aligned branch of the EXTERNAL CHOICE. + The ASN-module will not automatically decode + these records. To help you decode the records in the application, the + function + + + Z_ext_typeent *z_ext_gettypebyref(oid_value ref); - + - - Can be used to retrieve information about the known, external data - types. The function return a pointer to a static area, or NULL, if no - match for the given direct reference is found. The - Z_ext_typeent - is defined as: - + + Can be used to retrieve information about the known, external data + types. The function return a pointer to a static area, or NULL, if no + match for the given direct reference is found. The + Z_ext_typeent + is defined as: + - + typedef struct Z_ext_typeent { oid_value dref; /* the direct-reference OID value. */ int what; /* discriminator value for the external CHOICE */ Odr_fun fun; /* decoder function */ } Z_ext_typeent; - - - - The what member contains the - Z_External union discriminator value for the - given type: For the SUTRS record syntax, the value would be - Z_External_sutrs. - The fun member contains a pointer to the - function which encodes/decodes the given type. Again, for the SUTRS - record syntax, the value of fun would be - z_SUTRS (a function pointer). + + + + The what member contains the + Z_External union discriminator value for the + given type: For the SUTRS record syntax, the value would be + Z_External_sutrs. + The fun member contains a pointer to the + function which encodes/decodes the given type. Again, for the SUTRS + record syntax, the value of fun would be + z_SUTRS (a function pointer). - - - If you receive an EXTERNAL which contains an octet-string value that - you suspect of being an ASN.1-structured data value, you can use - z_ext_gettypebyref to look for the provided - direct-reference. - If the return value is different from NULL, you can use the provided - function to decode the BER string (see section - Using ODR). - - - - If you want to send EXTERNALs containing - ASN.1-structured values in the occtet-aligned branch of the CHOICE, this - is possible too. However, on the encoding phase, it requires a somewhat - involved juggling around of the various buffers involved. - - - If you need to add new, externally defined data types, you must update - the struct above, in the source file prt-ext.h, as - well as the encoder/decoder in the file prt-ext.c. - When changing the latter, remember to update both the - arm arrary and the list - type_table, which drives the CHOICE biasing that - is necessary to tell the different, structured types apart - on decoding. - - - + - Eventually, the EXTERNAL processing will most likely - automatically insert the correct OIDs or indirect-refs. First, - however, we need to determine how application-context management - (specifically the presentation-context-list) should fit into the - various modules. + If you receive an EXTERNAL which contains an octet-string value that + you suspect of being an ASN.1-structured data value, you can use + z_ext_gettypebyref to look for the provided + direct-reference. + If the return value is different from NULL, you can use the provided + function to decode the BER string (see section + Using ODR). - - - - PDU Contents Table + + + If you want to send EXTERNALs containing + ASN.1-structured values in the occtet-aligned branch of the CHOICE, this + is possible too. However, on the encoding phase, it requires a somewhat + involved juggling around of the various buffers involved. + + + If you need to add new, externally defined data types, you must update + the struct above, in the source file prt-ext.h, as + well as the encoder/decoder in the file prt-ext.c. + When changing the latter, remember to update both the + arm arrary and the list + type_table, which drives the CHOICE biasing that + is necessary to tell the different, structured types apart + on decoding. + + + + + Eventually, the EXTERNAL processing will most likely + automatically insert the correct OIDs or indirect-refs. First, + however, we need to determine how application-context management + (specifically the presentation-context-list) should fit into the + various modules. + + + + PDU Contents Table + - We include, for reference, a listing of the fields of each top-level - PDU, as well as their default settings. - - - Default settings for PDU Initialize Request - - - + We include, for reference, a listing of the fields of each top-level + PDU, as well as their default settings. + + +
Default settings for PDU Initialize Request + + + @@ -397,658 +397,658 @@ typedef struct Z_ext_typeent - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - protocolVersionOdr_bitmaskEmpty bitmask - - - optionsOdr_bitmaskEmpty bitmask - - - preferredMessageSizeint30*1024 - - - maximumRecordSizeint30*1024 - - - resultbool_tTRUE - - - implementationIdchar*"YAZ (id=81)" - - - implementationNamechar*"Index Data/YAZ" - - - implementationVersionchar*YAZ_VERSION - - - userInformationFieldZ_UserInformationNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + protocolVersionOdr_bitmaskEmpty bitmask + + + optionsOdr_bitmaskEmpty bitmask + + + preferredMessageSizeint30*1024 + + + maximumRecordSizeint30*1024 + + + resultbool_tTRUE + + + implementationIdchar*"YAZ (id=81)" + + + implementationNamechar*"Index Data/YAZ" + + + implementationVersionchar*YAZ_VERSION + + + userInformationFieldZ_UserInformationNULL + + + otherInfoZ_OtherInformationNULL + + + + - Default settings for PDU Search Request - - - - - - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - smallSetUpperBoundint0 - - - largeSetLowerBoundint1 - - - mediumSetPresentNumberint0 - - - replaceIndicatorbool_tTRUE - - - resultSetNamechar *"default" - - - num_databaseNamesint0 - - - databaseNameschar **NULL - - - smallSetElementSetNamesZ_ElementSetNames - NULL - - - mediumSetElementSetNamesZ_ElementSetNames - NULL - - - preferredRecordSyntaxOdr_oidNULL - - - queryZ_QueryNULL - - - additionalSearchInfoZ_OtherInformation - NULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for PDU Search Request + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + smallSetUpperBoundint0 + + + largeSetLowerBoundint1 + + + mediumSetPresentNumberint0 + + + replaceIndicatorbool_tTRUE + + + resultSetNamechar *"default" + + + num_databaseNamesint0 + + + databaseNameschar **NULL + + + smallSetElementSetNamesZ_ElementSetNames + NULL + + + mediumSetElementSetNamesZ_ElementSetNames + NULL + + + preferredRecordSyntaxOdr_oidNULL + + + queryZ_QueryNULL + + + additionalSearchInfoZ_OtherInformation + NULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for PDU Search Response - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - resultCountint0 - - - numberOfRecordsReturnedint0 - - - nextResultSetPositionint0 - - - searchStatusbool_tTRUE - - - resultSetStatusintNULL - - - presentStatusintNULL - - - recordsZ_RecordsNULL - - - additionalSearchInfo - Z_OtherInformationNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for PDU Search Response + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + resultCountint0 + + + numberOfRecordsReturnedint0 + + + nextResultSetPositionint0 + + + searchStatusbool_tTRUE + + + resultSetStatusintNULL + + + presentStatusintNULL + + + recordsZ_RecordsNULL + + + additionalSearchInfo + Z_OtherInformationNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for PDU Present Request - - - - - - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - resultSetIdchar*"default" - - - resultSetStartPointint1 - - - numberOfRecordsRequestedint10 - - - num_rangesint0 - - - additionalRangesZ_RangeNULL - - - recordCompositionZ_RecordCompositionNULL - - - preferredRecordSyntaxOdr_oidNULL - - - maxSegmentCountintNULL - - - maxRecordSizeintNULL - - - maxSegmentSizeintNULL - - - otherInfoZ_OtherInformationNULL - - - -
- - Default settings for PDU Present Response - - - - - - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - numberOfRecordsReturnedint0 - - - nextResultSetPositionint0 - - - presentStatusintZ_PRES_SUCCESS - - - recordsZ_RecordsNULL - - - otherInfoZ_OtherInformationNULL - - - -
- - Default settings for Delete Result Set Request - - - - - - - - Field - Type - Default Value - - - - referenceId - Z_ReferenceIdNULL - - - deleteFunctionintZ_DeleteRequest_list - - - num_idsint0 - - - resultSetListchar**NULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for PDU Present Request + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + resultSetIdchar*"default" + + + resultSetStartPointint1 + + + numberOfRecordsRequestedint10 + + + num_rangesint0 + + + additionalRangesZ_RangeNULL + + + recordCompositionZ_RecordCompositionNULL + + + preferredRecordSyntaxOdr_oidNULL + + + maxSegmentCountintNULL + + + maxRecordSizeintNULL + + + maxSegmentSizeintNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + Default settings for PDU Present Response + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedint0 + + + nextResultSetPositionint0 + + + presentStatusintZ_PRES_SUCCESS + + + recordsZ_RecordsNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + Default settings for Delete Result Set Request + + + + + + + + Field + Type + Default Value + + + + referenceId + Z_ReferenceIdNULL + + + deleteFunctionintZ_DeleteRequest_list + + + num_idsint0 + + + resultSetListchar**NULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Delete Result Set Response - - - - - - - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - deleteOperationStatusint - Z_DeleteStatus_success - - num_statusesint0 - - - deleteListStatusesZ_ListStatus**NULL - - - numberNotDeletedintNULL - - - num_bulkStatusesint0 - - - bulkStatusesZ_ListStatusNUL - L - - deleteMessagechar*NULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Delete Result Set Response + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + deleteOperationStatusint + Z_DeleteStatus_success + + num_statusesint0 + + + deleteListStatusesZ_ListStatus**NULL + + + numberNotDeletedintNULL + + + num_bulkStatusesint0 + + + bulkStatusesZ_ListStatusNUL + L + + deleteMessagechar*NULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Scan Request - - - - - - - - Field - Type - Default Value - - - - - referenceIdZ_ReferenceIdNULL - - - num_databaseNamesint0 - - - databaseNameschar**NULL - - - attributeSetOdr_oidNULL - - - termListAndStartPointZ_AttributesPlus... - NULL - - stepSizeintNULL - - - numberOfTermsRequestedint20 - - - preferredPositionInResponseintNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Scan Request + + + + + + + + Field + Type + Default Value + + + + + referenceIdZ_ReferenceIdNULL + + + num_databaseNamesint0 + + + databaseNameschar**NULL + + + attributeSetOdr_oidNULL + + + termListAndStartPointZ_AttributesPlus... + NULL + + stepSizeintNULL + + + numberOfTermsRequestedint20 + + + preferredPositionInResponseintNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Scan Response - - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - stepSizeintNULL - - - scanStatusintZ_Scan_success - - - numberOfEntriesReturnedint0 - - - positionOfTermintNULL - - - entriesZ_ListEntrisNULL - - - attributeSetOdr_oidNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Scan Response + + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + stepSizeintNULL + + + scanStatusintZ_Scan_success + + + numberOfEntriesReturnedint0 + + + positionOfTermintNULL + + + entriesZ_ListEntrisNULL + + + attributeSetOdr_oidNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Trigger Resource - Control Request - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - requestedActionint - Z_TriggerResourceCtrl_resou.. - - - prefResourceReportFormatOdr_oidNULL - - - resultSetWantedbool_tNULL - - - otherInfoZ_OtherInformationNULL - - - - -
+ Default settings for Trigger Resource + Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + requestedActionint + Z_TriggerResourceCtrl_resou.. + + + prefResourceReportFormatOdr_oidNULL + + + resultSetWantedbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + + +
- Default settings for Resource - Control Request - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - suspendedFlagbool_tNULL - - - resourceReportZ_ExternalNULL - - - partialResultsAvailableintNULL - - - responseRequiredbool_tFALSE - - - triggeredRequestFlagbool_tNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Resource + Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + suspendedFlagbool_tNULL + + + resourceReportZ_ExternalNULL + + + partialResultsAvailableintNULL + + + responseRequiredbool_tFALSE + + + triggeredRequestFlagbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Resource - Control Response - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - continueFlagbool_tTRUE - - - resultSetWantedbool_tNULL - - - otherInfoZ_OtherInformationNULL - - - -
- - Default settings for Access - Control Request - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - whichenumZ_AccessRequest_simpleForm; - - - uunionNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Resource + Control Response + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + continueFlagbool_tTRUE + + + resultSetWantedbool_tNULL + + + otherInfoZ_OtherInformationNULL + + + +
+ + Default settings for Access + Control Request + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessRequest_simpleForm; + + + uunionNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Access - Control Response - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - whichenumZ_AccessResponse_simpleForm - - - uunionNULL - - - diagnosticZ_DiagRecNULL - - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Access + Control Response + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + whichenumZ_AccessResponse_simpleForm + + + uunionNULL + + + diagnosticZ_DiagRecNULL + + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Segment - - - - - - - Field - Type - Default Value - - - - - - referenceIdZ_ReferenceIdNULL - - - numberOfRecordsReturnedintvalue=0 - - - num_segmentRecordsint0 - - - segmentRecordsZ_NamePlusRecordNULL - - otherInfoZ_OtherInformationNULL - - - -
+ Default settings for Segment + + + + + + + Field + Type + Default Value + + + + + + referenceIdZ_ReferenceIdNULL + + + numberOfRecordsReturnedintvalue=0 + + + num_segmentRecordsint0 + + + segmentRecordsZ_NamePlusRecordNULL + + otherInfoZ_OtherInformationNULL + + + +
- Default settings for Close - - - - - - - Field - Type - Default Value - - - +
Default settings for Close + + + + + + + Field + Type + Default Value + + + - - referenceIdZ_ReferenceIdNULL - - - closeReasonintZ_Close_finished - - - diagnosticInformationchar*NULL - - - resourceReportFormatOdr_oidNULL - - - resourceFormatZ_ExternalNULL - - - otherInfoZ_OtherInformationNULL - - - - -
+ + referenceIdZ_ReferenceIdNULL + + + closeReasonintZ_Close_finished + + + diagnosticInformationchar*NULL + + + resourceReportFormatOdr_oidNULL + + + resourceFormatZ_ExternalNULL + + + otherInfoZ_OtherInformationNULL + + + + + - - + + + The YAZ client + Introduction + + yaz-client is a linemode Z39.50 client. It supports a fair amount + of the functionality of the Z39.50-1995 standard, but some things you + need to enable or disable by recompilation. + Its primary purpose is to exercise the + package, and verify that the protocol works OK. + For the same reason some commands offers more functionality than others. + Commands that exercies common Z39.50 services such as search and present + have more features than less common supported services, such as Extended + Services (ItemOrder, ItemUpdate,..). + + + Invoking the YAZ client + + It can be started by typing + + + yaz-client [options] [zurl] + + + in a UNIX shell / WIN32 console. The zurl, + specifies a Z39.50 host and, if specified, the client first tries to + establish connection with the Z39.50 target on the host. + Options are, as usual, are prefixed by - followed + by a particular letter. + + + The following options are supported: + + + + -m fname + + ISO2709 records are appended to file + fname. All records as returned by a target(s) + in Search Responses and Present Responses are appended verbatim to + the file. + + + + -a fname + + Pretty-print log of APDUs sent and received is appended + to the file fname. + If fname is - (minus) + the APDU log is written to stderr. + + + + -c fname + + Sets the filename for CCL fields to + fname. If this option is not given the + YAZ client reads CCL fields from file default.bib. + + + + -v level + + Sets the LOG level to level. + Level is a sequence of tokens separated by comman. Each token + is a integer or a named LOG item - one of + fatal, + debug, + warn, + log, + all, + none. + + + + + In order to connect to Index Data's test Z39.50 server on + bagel.indexdata.dk, port 210 and with the + database name marc, one would have to type + + + yaz-client bagel.indexdata.dk:210/marc + + + In order to enable APDU log and connect to localhost, port 210 (default) + and database Default (default) you'd write: + + + yaz-client -a - localhost + + + YAZ client commands + + When the YAZ client has read options and connected to a target, if given, + it will display Z > and away your command. + Commands are executed by hitting the return key. + You can always issue the command ? to see the list + of available commands. + + + The commands are (the letters in parenthesis are short + names for the commands): + + + + open zurl + + o + + Opens a connection to a server. The syntax for + zurl is the same as described + above for connecting from the command line. + + + Syntax: + + + [(tcp|osi)':'<[tsel/]]host[:port][/base>] + + + + + quit + + q + + Ends YAZ client + + + + f query + f + + Sends Search Request using the query + given. + + + + + delete setname + + Deletes result set with name setname + on the server. + + + + base base1 + base2 ... + + + Sets the name(s) of the database(s) to search. One or more + databases may be specified separated by blanks. This commands overrides + the database given in zurl. + + + + + show [start[+number]] + + s + + Fetches records by sending a Present Request from the start + position given by + start + a number of records given by number. If + start is not given the client will + fetch from position of the last retrieved record plus 1. If + number is not given one record will be + fetched at a time. + + + + + scan term + + + Scans + database index for a term. The syntax resembles the syntax + for find. + If you want to scan for the word water you could + write + + + scan water + + + but if you want to scan only in, say the title field, you would write + + + scan @attr 1=4 water + + + + + sort sortspecs + + + Sorts a result set. The sort command takes a sequence of + sort specifications. A sort + specification holds a field (sort criteria) and is followed by flags. + If the sort criteria includes = it is assumed + that the sort SortKey is of type sortAttributes using Bib-1. + The integer before = is + the attribute type and the integer following = + is the attribute value. + If no = is in the SortKey it is treated as a + sortfield-type of type InternationalString. + Flags observed are: s + for case sensitive, i for case insensitive, + < for sort ascending and > + for sort descending. + + + + + sort+ + + + Same as sort but stores the sorted + result set in a new result set. + + + + + authentication openauth + + + Sets up a authentication string if a server requires + authentication (v2 OpenStyle). The authentication string is first + sent to the server when the open command is + issued and the Z39.50 Initialize Request is sent, so this command + must be used before open in order to be effective. + + + + + lslb n + + + Sets the limit for when no records should be returned + together with the search result. + See the + + Z39.50 standard + + for more details. + + + + + + ssub n + + + Sets the limit for when all records should be returned with + the search result. + See the + + Z39.50 standard + for more details. + + + + + + mspn n + + + Sets the number of records should be returned if the + number of records in the result set is between the values of + lslb and ssub. + See the + + Z39.50 standard + + for more details. + + + + + status + + + Displays the values of lslb, + ssub and mspn. + + + + + setname + + + Switches named result sets on and off. Default is on. + + + + + cancel + + + Sends a Trigger Resource Control Request to the target. + + + + + format oid + + + Sets the preferred transfer syntax for retrieved records. + yaz-client supports all the record syntaxes that currently + are registered. See + + Z39.50 Standard + + for more details. Commonly used records syntaxes include usmarc, + sutrs, grs1 and xml. + + + + + elements e + + + Sets the element set name for the records. Many targets support + element sets are B (for brief) and F (for full). + + + + + close + + + Sends a Z39.50 Close APDU and closes connection with the peer + + + + + querytype type + + + Sets the query type as used by command find. + The following is supported: prefix for + Prefix Query Notation (Type-1 Query); + ccl for CCL search (Type-2 + Query) or ccl2rpn for + CCL to RPN conversion (Type-1 Query). + + + + + attributeset set + + + + Sets attribute set OID for prefix queries (RPN, Type-1). + + + + + refid id + + + Sets reference ID for Z39.50 Request(s). + + + + + itemorder + type no + + + Sends an Item Order Request using the ILL External. + type is either 1 or 2 which correponds to + ILL-Profile 1 and 2 respectively. The no + is the Result Set position of the record to be ordered. + + + + + update + + + Sends Item Update Request. This command sends a "minimal" + PDU to the target supplying the last received record from the target. + If no record has been received from the target this command is ignored + and nothing is sent to the target. + + + + + + Searching + + The simplest example of a Prefix Query would be something like + + f knuth + + or + + f "donald knuth" + + In those queries no attributes was specified. + This leaves it up to the server what fields to search but + most servers will search in all fields. Some servers does not + support this feature though, and require that some attributes + are defined. To add one attribute you could do: + + f @attr 1=4 computer + + where we search in the title field, since the use(1) is title(4). + If we want to search in the author field and + in the title field, and in the title field using right truncation + it could look something like this: + + f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer + + Finally using a mix of Bib-1 and GILS attributes could look + something like this: + + f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather + + For the full specifiction of the Prefix Query see the section + Prefix Query Format. + + + + + diff --git a/doc/tools.xml b/doc/tools.xml index 4d47a1b..33de66e 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,9 +1,9 @@ - + Supporting Tools - + In support of the service API - primarily the ASN module, which - provides the programmatic interface to the Z39.50 APDUs, YAZ contains + provides the programmatic interface to the Z39.50 APDUs, &yaz; contains a collection of tools that support the development of applications. @@ -51,9 +51,8 @@ int p_query_attset (const char *arg); to provide a memory source (the structure created is released on the next call to odr_reset() on the stream), a protocol identifier (one of the constants PROTO_Z3950 and - PROTO_SR), an attribute set - reference, and finally a null-terminated string holding the query - string. + PROTO_SR), an attribute set reference, and + finally a null-terminated string holding the query string. If the parse went well, p_query_rpn() returns a @@ -74,13 +73,13 @@ int p_query_attset (const char *arg); - Query ::= [ AttSet ] QueryStruct. + Query ::= [ '@attrset' AttSet ] QueryStruct. AttSet ::= string. - QueryStruct ::= { Attribute } Simple | Complex. + QueryStruct ::= [ Attribute ] Simple | Complex. - Attribute ::= '@attr' AttributeType '=' AttributeValue. + Attribute ::= '@attr' [ AttSet ] AttributeType '=' AttributeValue. AttributeType ::= integer. @@ -139,6 +138,8 @@ int p_query_attset (const char *arg); @attr 4=1 @attr 1=4 "self portrait" @prox 0 3 1 2 k 2 dylan zimmerman + + @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109 @@ -686,7 +687,7 @@ typedef struct oident - + + YAZ User's Guide and Reference @@ -46,6 +47,7 @@ &chap-introduction; &chap-installation; + &chap-client; &chap-asn; &chap-tools; &chap-odr;