X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Ftools.xml;h=5b09ab305811d81f111927be7cb4b24edbf3e70f;hp=b8ff153b5358c63ad17260b823533bc8f9bf4d13;hb=aee1a87eeda33b4b049e9fc0a0a826b9c14018cc;hpb=38ce2c71a8aa497a5c445dd36d12d0d535dea79a diff --git a/doc/tools.xml b/doc/tools.xml index b8ff153..5b09ab3 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,3 @@ - Supporting Tools @@ -435,17 +434,6 @@ symbolic language for expressing boolean query structures. - - The EUROPAGATE research project working under the Libraries programme - of the European Commission's DG XIII has, amongst other useful tools, - implemented a general-purpose CCL parser which produces an output - structure that can be trivially converted to the internal RPN - representation of &yaz; (The Z_RPNQuery structure). - Since the CCL utility - along with the rest of the software - produced by EUROPAGATE - is made freely available on a liberal - license, it is included as a supplement to &yaz;. - - CCL Syntax @@ -652,7 +640,7 @@ - Refer to the complete + Refer to or the complete list of Bib-1 attributes @@ -1541,27 +1529,30 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); The basic YAZ representation of an OID is an array of integers, - terminated with the value -1. There is a typedef - of this integer to Odr_oid but this is not consistenly - used everywhere. + terminated with the value -1. This integer is of type + Odr_oid. - An OID can either be declared as a automatic variable or we can - allocated using the ODR/NMEM memory utilities. It's + Fundamental OID operations and the type Odr_oid + are defined in yaz/oid_util.h. + + + An OID can either be declared as a automatic variable or it can + allocated using the memory utilities or ODR/NMEM. It's guaranteed that an OID can fit in OID_SIZE integers. Create OID on stack We can create an OID for the Bib-1 attribute set with: - int bib1[OID_SIZE]; - myoid[0] = 1; - myoid[1] = 2; - myoid[2] = 840; - myoid[3] = 10003; - myoid[4] = 3; - myoid[5] = 1; - myoid[6] = -1; + Odr_oid bib1[OID_SIZE]; + bib1[0] = 1; + bib1[1] = 2; + bib1[2] = 840; + bib1[3] = 10003; + bib1[4] = 3; + bib1[5] = 1; + bib1[6] = -1; @@ -1569,14 +1560,15 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); And OID may also be filled from a string-based representation using dots (.). This is achieved by function - int oid_dotstring_to_oid(const char *name, int *oid); + int oid_dotstring_to_oid(const char *name, Odr_oid *oid); + This functions returns 0 if name could be converted; -1 otherwise. Using oid_oiddotstring_to_oid - We can create the Bib-1 attribute set OID easier with: + We can fill the Bib-1 attribute set OID easier with: - int bib1[OID_SIZE]; + Odr_oid bib1[OID_SIZE]; oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1); @@ -1604,7 +1596,7 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); The function - char *oid_oid_to_dotstring(const int *oid, char *oidbuf) + char *oid_oid_to_dotstring(const Odr_oid *oid, char *oidbuf) does the reverse of oid_oiddotstring_to_oid. It converts an OID to the string-based representation using dots. @@ -1630,7 +1622,7 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); From YAZ version 3 and later, the oident system has been replaced by an OID database. OID database is a misnomer .. the old odient - was a database system too. + system was also a database. The OID database is really just a map between named Object Identifiers @@ -1708,265 +1700,6 @@ void cql_to_xml_stdio(struct cql_node *cn, FILE *f); - - OID oident - - - - The oident utility has been removed from YAZ version 3. This - sub section only applies to YAZ version 2. - - - - - The OID module provides a higher-level representation of the - family of object identifiers which describe the Z39.50 protocol and its - related objects. The definition of the module interface is given in - the oid.h file. - - - - The interface is mainly based on the oident structure. - The definition of this structure looks like this: - - - -typedef struct oident -{ - oid_proto proto; - oid_class oclass; - oid_value value; - int oidsuffix[OID_SIZE]; - char *desc; -} oident; - - - - The proto field takes one of the values - - - - PROTO_Z3950 - PROTO_GENERAL - - - - Use PROTO_Z3950 for Z39.50 Object Identifers, - PROTO_GENERAL for other types (such as - those associated with ILL). - - - - The oclass field takes one of the values - - - - CLASS_APPCTX - CLASS_ABSYN - CLASS_ATTSET - CLASS_TRANSYN - CLASS_DIAGSET - CLASS_RECSYN - CLASS_RESFORM - CLASS_ACCFORM - CLASS_EXTSERV - CLASS_USERINFO - CLASS_ELEMSPEC - CLASS_VARSET - CLASS_SCHEMA - CLASS_TAGSET - CLASS_GENERAL - - - - corresponding to the OID classes defined by the Z39.50 standard. - - Finally, the value field takes one of the values - - - - VAL_APDU - VAL_BER - VAL_BASIC_CTX - VAL_BIB1 - VAL_EXP1 - VAL_EXT1 - VAL_CCL1 - VAL_GILS - VAL_WAIS - VAL_STAS - VAL_DIAG1 - VAL_ISO2709 - VAL_UNIMARC - VAL_INTERMARC - VAL_CCF - VAL_USMARC - VAL_UKMARC - VAL_NORMARC - VAL_LIBRISMARC - VAL_DANMARC - VAL_FINMARC - VAL_MAB - VAL_CANMARC - VAL_SBN - VAL_PICAMARC - VAL_AUSMARC - VAL_IBERMARC - VAL_EXPLAIN - VAL_SUTRS - VAL_OPAC - VAL_SUMMARY - VAL_GRS0 - VAL_GRS1 - VAL_EXTENDED - VAL_RESOURCE1 - VAL_RESOURCE2 - VAL_PROMPT1 - VAL_DES1 - VAL_KRB1 - VAL_PRESSET - VAL_PQUERY - VAL_PCQUERY - VAL_ITEMORDER - VAL_DBUPDATE - VAL_EXPORTSPEC - VAL_EXPORTINV - VAL_NONE - VAL_SETM - VAL_SETG - VAL_VAR1 - VAL_ESPEC1 - - - - again, corresponding to the specific OIDs defined by the standard. - Refer to the - - Registry of Z39.50 Object Identifiers for the - whole list. - - - - The desc field contains a brief, mnemonic name for the OID in question. - - - - The function - - - - struct oident *oid_getentbyoid(int *o); - - - - takes as argument an OID, and returns a pointer to a static area - containing an oident structure. You typically use - this function when you receive a PDU containing an OID, and you wish - to branch out depending on the specific OID value. - - - - The function - - - - int *oid_ent_to_oid(struct oident *ent, int *dst); - - - - Takes as argument an oident structure - in which - the proto, oclass/, and - value fields are assumed to be set correctly - - and returns a pointer to a the buffer as given by dst - containing the base - representation of the corresponding OID. The function returns - NULL and the array dst is unchanged if a mapping couldn't place. - The array dst should be at least of size - OID_SIZE. - - - - The oid_ent_to_oid() function can be used whenever - you need to prepare a PDU containing one or more OIDs. The separation of - the protocol element from the remainder of the - OID-description makes it simple to write applications that can - communicate with either Z39.50 or OSI SR-based applications. - - - - The function - - - - oid_value oid_getvalbyname(const char *name); - - - - takes as argument a mnemonic OID name, and returns the - /value field of the first entry in the database that - contains the given name in its desc field. - - - - Three utility functions are provided for translating OIDs' - symbolic names (e.g. Usmarc into OID structures - (int arrays) and strings containing the OID in dotted notation - (e.g. 1.2.840.10003.9.5.1). They are: - - - - int *oid_name_to_oid(oid_class oclass, const char *name, int *oid); - char *oid_to_dotstring(const int *oid, char *oidbuf); - char *oid_name_to_dotstring(oid_class oclass, const char *name, char *oidbuf); - - - - oid_name_to_oid() - translates the specified symbolic name, - interpreted as being of class oclass. (The - class must be specified as many symbolic names exist within - multiple classes - for example, Zthes is the - symbolic name of an attribute set, a schema and a tag-set.) The - sequence of integers representing the OID is written into the - area oid provided by the caller; it is the - caller's responsibility to ensure that this area is large enough - to contain the translated OID. As a convenience, the address of - the buffer (i.e. the value of oid) is - returned. - - - oid_to_dotstring() - Translates the int-array oid into a dotted - string which is written into the area oidbuf - supplied by the caller; it is the caller's responsibility to - ensure that this area is large enough. The address of the buffer - is returned. - - - oid_name_to_dotstring() - combines the previous two functions to derive a dotted string - representing the OID specified by oclass and - name, writing it into the buffer passed as - oidbuf and returning its address. - - - - - The OID module has been criticized - and perhaps rightly so - - for needlessly abstracting the - representation of OIDs. Other toolkits use a simple - string-representation of OIDs with good results. In practice, we have - found the interface comfortable and quick to work with, and it is a - simple matter (for what it's worth) to create applications compatible - with both ISO SR and Z39.50. Finally, the use of the - /oident database is by no means mandatory. - You can easily create your own system for representing OIDs, as long - as it is compatible with the low-level integer-array representation - of the ODR module. - - - - Nibble Memory @@ -2369,7 +2102,10 @@ typedef struct oident Defines the name of the retrieval format. This can be any string. For SRU, the value, is equivalent to schema (short-hand); - for Z39.50 it's equivalent to simple element set name. + for Z39.50 it's equivalent to simple element set name. + For YAZ 3.0.24 and later this name may be specified as a glob + expression with operators + * and ?. @@ -2408,7 +2144,7 @@ typedef struct oident The marc element specifies a conversion to - and from ISO2709 encoded MARC and - &marcxml;/MarcXchange. + &acro.marcxml;/MarcXchange. The following attributes may be specified: @@ -2462,7 +2198,7 @@ typedef struct oident The xslt element specifies a conversion - via &xslt;. The following attributes may be specified: + via &acro.xslt;. The following attributes may be specified: stylesheet (REQUIRED)