From 6406d7955629f3b8d4bbeae9fc93ec1bb9d5366a Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Thu, 23 Jan 2003 20:26:37 +0000 Subject: [PATCH] More CQL information --- doc/tools.xml | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 108 insertions(+), 6 deletions(-) diff --git a/doc/tools.xml b/doc/tools.xml index 841fb9a..051daf2 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -473,8 +473,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, In many ways CQL has a similar syntax to CCL. The objective of CQL is different. Where CCL aims to be an end-user language, CQL is the protocol - query language for SRW. Unlike PQF (Z39.50 Type-1), CQL is easy - to read. + query language for SRW. @@ -529,13 +528,16 @@ typedef struct cql_parser *CQL_parser; CQL_parser cql_parser_create(void); void cql_parser_destroy(CQL_parser cp); - -int cql_parser_string(CQL_parser cp, const char *str); A parser is created by cql_parser_create and is destroyed by cql_parser_destroy. + To parse a CQL query string, the following function + is provided: + +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; @@ -560,9 +562,24 @@ int cql_parser_stdio(CQL_parser cp, FILE *f); uses a FILE handle which is opened for reading. + CQL tree - We now turn to the tree representation of a valid CQL query. + The the query string is validl, the CQL parser + generates a tree representing the structure of the + CQL query. + + + +struct cql_node *cql_parser_result(CQL_parser cp); + + cql_parser_result returns the + a pointer to the root node of the resulting tree. + + + Each node in a CQL tree is represented by a + struct cql_node. + It is defined as follows: #define CQL_NODE_ST 1 #define CQL_NODE_BOOL 2 @@ -685,6 +702,91 @@ struct cql_node { + CQL to PQF conversion + + Conversion to PQF (and Z39.50 RPN) is tricky by the fact + that the resulting RPN depends on the Z39.50 target + capabilities (combinations of supported attributes). + Furthermore, the CQL and SRW operates on index prefixes + (URI or strings), whereas the RPN uses Object Identifiers + for attribute sets. + + + The CQL library of &yaz; defines a cql_transform_t + type. It represents a particular mapping between CQL and RPN. + This handle is created and destroyed by the functions: + +cql_transform_t cql_transform_open_FILE (FILE *f); +cql_transform_t cql_transform_open_fname(const char *fname); +void cql_transform_close(cql_transform_t ct); + + The first two functions create a tranformation handle from + either an already open FILE or from a filename. + + + The handle is destroyed by cql_transform_close + in which case no further reference of the handle is allowed. + + + When a cql_transform_t handle has been created + you can convert to RPN. + +int cql_transform_buf(cql_transform_t ct, + struct cql_node *cn, char *out, int max); + + This function converts the CQL tree cn + using handle ct. + For the resulting PQF, you supply a buffer out + which must be able to hold at at least max + characters. + + + If conversion failed, cql_transform_buf + returns a non-zero error code; otherwise zero is returned + (conversion successful). + + + If you wish to be able to produce a PQF result in a different + way, there are two alternatives. + +void cql_transform_pr(cql_transform_t ct, + struct cql_node *cn, + void (*pr)(const char *buf, void *client_data), + void *client_data); + +int cql_transform_FILE(cql_transform_t ct, + struct cql_node *cn, FILE *f); + + The former function produces output to a user-defined + output stream. The latter writes the result to an already + open FILE. + + + CQL to XCQL conversion + + Conversion from CQL to XCQL is trivial and does not + require a mapping to be defined. + There three functions to choose from depending on the + way you wish to store the resulting output (XML buffer + containing XCQL). + +int cql_to_xml_buf(struct cql_node *cn, char *out, int max); +void cql_to_xml(struct cql_node *cn, + void (*pr)(const char *buf, void *client_data), + void *client_data); +void cql_to_xml_stdio(struct cql_node *cn, FILE *f); + + Function cql_to_xml_buf converts + to XCQL and stores result in a user supplied buffer of a given + max size. + + + cql_to_xml writes the result in + a user defined output stream. + cql_to_xml_stdio writes to a + a file. + + Object Identifiers -- 1.7.10.4