X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Ftools.xml;h=accbb5959a0de907dd38cd964a85314928cc82b4;hb=d1ad544488a515cb6ad80d1b98863baa57abb567;hp=56fe958ff30604d8c0f034e1028ea49a82ac4b59;hpb=4ab240934731700f437e2bf8cb695e4b5fc9c0dc;p=yaz-moved-to-github.git diff --git a/doc/tools.xml b/doc/tools.xml index 56fe958..accbb59 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -16,7 +16,7 @@ Z_RPNQuery structure. Some programmers will prefer to construct the query manually, perhaps using odr_malloc() to simplify memory management. - The &yaz; distribution includes two separate, query-generating tools + The &yaz; distribution includes three separate, query-generating tools that may be of use to you. @@ -131,7 +131,7 @@ top-set ::= [ '@attrset' string ] - query-struct ::= attr-spec | simple | complex | '@term' term-type + query-struct ::= attr-spec | simple | complex | '@term' term-type query attr-spec ::= '@attr' [ string ] string query-struct @@ -173,11 +173,15 @@ The @attr operator is followed by an attribute specification (attr-spec above). The specification consists - of optional an attribute set, an attribute type-value pair and - a sub query. The attribute type-value pair is packed in one string: - an attribute type, a dash, followed by an attribute value. + of an optional attribute set, an attribute type-value pair and + a sub-query. The attribute type-value pair is packed in one string: + an attribute type, an equals sign, and an attribute value, like this: + @attr 1=1003. The type is always an integer but the value may be either an integer or a string (if it doesn't start with a digit character). + A string attribute-value is encoded as a Type-1 ``complex'' + attribute with the list of values containing the single string + specified, and including no semantic indicators. @@ -322,7 +326,7 @@ @attr 1=4 computer @attr 1=4 @attr 4=1 "self portrait" - @attr exp1 @attr 1=1 CategoryList + @attrset exp1 @attr 1=1 CategoryList @attr gils 1=2008 Copenhagen @attr 1=/book/title computer @@ -394,13 +398,13 @@ - Common Command Language + CCL Not all users enjoy typing in prefix query structures and numerical attribute values, even in a minimalistic test client. In the library - world, the more intuitive Common Command Language (or ISO 8777) has - enjoyed some popularity - especially before the widespread + world, the more intuitive Common Command Language - CCL (ISO 8777) + has enjoyed some popularity - especially before the widespread availability of graphical interfaces. It is still useful in applications where you for some reason or other need to provide a symbolic language for expressing boolean query structures. @@ -510,73 +514,335 @@ suggest a few short-hand notations. You can customize the CCL parser to support a particular set of qualifiers to reflect the current target profile. Traditionally, a qualifier would map to a particular - use-attribute within the BIB-1 attribute set. However, you could also - define qualifiers that would set, for example, the - structure-attribute. + use-attribute within the BIB-1 attribute set. It is also + possible to set other attributes, such as the structure + attribute. A CCL profile is a set of predefined CCL qualifiers that may be - read from a file. + read from a file or set in the CCL API. The YAZ client reads its CCL qualifiers from a file named - default.bib. Each line in the file has the form: + default.bib. There are four types of + lines in a CCL profile: qualifier specification, + qualifier alias, comments and directives. - - - qualifier-name - [attributeset,]type=val - [attributeset,]type=val ... - - - - where qualifier-name is the name of the - qualifier to be used (eg. ti), - type is attribute type in the attribute - set (Bib-1 is used if no attribute set is given) and - val is attribute value. - The type can be specified as an - integer or as it be specified either as a single-letter: - u for use, - r for relation,p for position, - s for structure,t for truncation - or c for completeness. - The attributes for the special qualifier name term - are used when no CCL qualifier is given in a query. - - - CCL profile + Qualifier specification - Consider the following definition: + A qualifier specification is of the form: - - ti u=4 s=1 - au u=1 s=1 - term s=105 - ranked r=102 - - Three qualifiers are defined, ti, - au and ranked. - ti and au both set - structure attribute to phrase (s=1). - ti - sets the use-attribute to 4. au sets the - use-attribute to 1. - When no qualifiers are used in the query the structure-attribute is - set to free-form-text (105). + qualifier-name + [attributeset,]type=val + [attributeset,]type=val ... + + + + where qualifier-name is the name of the + qualifier to be used (eg. ti), + type is attribute type in the attribute + set (Bib-1 is used if no attribute set is given) and + val is attribute value. + The type can be specified as an + integer or as it be specified either as a single-letter: + u for use, + r for relation,p for position, + s for structure,t for truncation + or c for completeness. + The attributes for the special qualifier name term + are used when no CCL qualifier is given in a query. + Common Bib-1 attributes + + + + + + Type + Description + + + + + u=value + + Use attribute. Common use attributes are + 1 Personal-name, 4 Title, 7 ISBN, 8 ISSN, 30 Date, + 62 Subject, 1003 Author), 1016 Any. Specify value + as an integer. + + + + + r=value + + Relation attribute. Common values are + 1 <, 2 <=, 3 =, 4 >=, 5 >, 6 <>, + 100 phonetic, 101 stem, 102 relevance, 103 always matches. + + + + + p=value + + Position attribute. Values: 1 first in field, 2 + first in any subfield, 3 any position in field. + + + + + s=value + + Structure attribute. Values: 1 phrase, 2 word, + 3 key, 4 year, 5 date, 6 word list, 100 date (un), + 101 name (norm), 102 name (un), 103 structure, 104 urx, + 105 free-form-text, 106 document-text, 107 local-number, + 108 string, 109 numeric string. + + + + + t=value + + Truncation attribute. Values: 1 right, 2 left, + 3 left& right, 100 none, 101 process #, 102 regular-1, + 103 regular-2, 104 CCL. + + + + + c=value + + Completeness attribute. Values: 1 incomplete subfield, + 2 complete subfield, 3 complete field. + + + + + +
+ + + The complete list of Bib-1 attributes can be found + + here + . - You can combine attributes. To Search for "ranked title" you - can do + It is also possible to specify non-numeric attribute values, + which are used in combination with certain types. + The special combinations are: + + Special attribute combos + + + + + + Name + Description + + + + + s=pw + The structure is set to either word or phrase depending + on the number of tokens in a term (phrase-word). + + + + s=al + Each token in the term is ANDed. (and-list). + This does not set the structure at all. + + + + s=ol + Each token in the term is ORed. (or-list). + This does not set the structure at all. + + + + r=o + Allows operators greather-than, less-than, ... equals and + sets relation attribute accordingly (relation ordered). + + + + t=l + Allows term to be left-truncated. + If term is of the form ?x, the resulting + Type-1 term is x and truncation is left. + + + + t=r + Allows term to be right-truncated. + If term is of the form x?, the resulting + Type-1 term is x and truncation is right. + + + + t=n + If term is does not include ?, the + truncation attribute is set to none (100). + + + + t=b + Allows term to be both left&right truncated. + If term is of the form ?x?, the + resulting term is x and trunctation is + set to both left&right. + + + + +
+ + CCL profile + + Consider the following definition: + + - ti,ranked=knuth computer - - which will use "relation is ranked", "use is title", "structure is - phrase". + ti u=4 s=1 + au u=1 s=1 + term s=105 + ranked r=102 + date u=30 r=o + + + Four qualifiers are defined - ti, + au, ranked and + date. + + + ti and au both set + structure attribute to phrase (s=1). + ti + sets the use-attribute to 4. au sets the + use-attribute to 1. + When no qualifiers are used in the query the structure-attribute is + set to free-form-text (105) (rule for term). + The date sets the relation attribute to + the relation used in the CCL query and sets the use attribute + to 30 (Bib-1 Date). + + + You can combine attributes. To Search for "ranked title" you + can do + + ti,ranked=knuth computer + + which will set relation=ranked, use=title, structure=phrase. + + + Query + + year > 1980 + + is a valid query, while + + ti > 1980 + + is invalid. + + + + Qualifier alias + + A qualifier alias is of the form: - - + + q + q1 q2 .. + + + which declares q to + be an alias for q1, + q2... such that the CCL + query q=x is equivalent to + q1=x or w2=x or .... + + + + Comments + + Lines with white space or lines that begin with + character # are treated as comments. + + + + Directives + + Directive specifications takes the form + + @directive value + + CCL directives + + + + + + + Name + Description + Default + + + + + truncation + Truncation character + ? + + + field + Specifies how multiple fields are to be + combined. There are two modes: or: + multiple qualifier fields are ORed, + merge: attributes for the qualifier + fields are merged and assigned to one term. + + merge + + + case + Specificies if CCL operatores and qualifiers should be + compared with case sensitivity or not. Specify 0 for + case sensitive; 1 for case insensitive. + 0 + + + + and + Specifies token for CCL operator AND. + and + + + + or + Specifies token for CCL operator OR. + or + + + + not + Specifies token for CCL operator NOT. + not + + + + set + Specifies token for CCL operator SET. + set + + + +
+ CCL API @@ -718,7 +984,7 @@ int cql_parser_string(CQL_parser cp, const char *str); A CQL query is parsed by the cql_parser_string which takes a query str. If the query was valid (no syntax errors), then zero is returned; - otherwise a non-zero error code is returned. + otherwise -1 is returned to indicate a syntax error. @@ -742,7 +1008,7 @@ int cql_parser_stdio(CQL_parser cp, FILE *f); CQL tree - The the query string is validl, the CQL parser + The the query string is valid, the CQL parser generates a tree representing the structure of the CQL query. @@ -938,6 +1204,13 @@ int cql_transform_error(cql_transform_t ct, char **addinfop); index set that was not recognised. + The SRW error-codes may be translated into brief human-readable + error messages using + +const char *cql_strerror(int code); + + + If you wish to be able to produce a PQF result in a different way, there are two alternatives. @@ -1234,15 +1507,13 @@ typedef struct oident PROTO_Z3950 - PROTO_SR + PROTO_GENERAL - If you don't care about talking to SR-based implementations (few - exist, and they may become fewer still if and when the ISO SR and ANSI - Z39.50 documents are merged into a single standard), you can ignore - this field on incoming packages, and always set it to PROTO_Z3950 - for outgoing packages. + Use PROTO_Z3950 for Z39.50 Object Identifers, + PROTO_GENERAL for other types (such as + those associated with ILL). @@ -1329,6 +1600,10 @@ typedef struct oident again, corresponding to the specific OIDs defined by the standard. + Refer to the + + Registry of Z39.50 Object Identifiers for the + whole list. @@ -1393,6 +1668,49 @@ typedef struct oident + 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. + + + Finally, the module provides the following utility functions, whose meaning should be obvious: