-<!-- $Id: tools.xml,v 1.26 2003-06-20 10:18:05 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.30 2003-11-03 09:49:58 mike Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
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
<para>
The @attr operator is followed by an attribute specification
(<literal>attr-spec</literal> 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:
+ <literal>@attr 1=1003</literal>.
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.
</para>
<para>
<screen>
@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
</screen>
</para>
<para>
+ Three utility functions are provided for translating OIDs'
+ symbolic names (e.g. <literal>Usmarc</literal> into OID structures
+ (int arrays) and strings containing the OID in dotted notation
+ (e.g. <literal>1.2.840.10003.9.5.1</literal>). They are:
+ </para>
+
+ <screen>
+ 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);
+ </screen>
+
+ <para>
+ <literal>oid_name_to_oid()</literal>
+ translates the specified symbolic <literal>name</literal>,
+ interpreted as being of class <literal>oclass</literal>. (The
+ class must be specified as many symbolic names exist within
+ multiple classes - for example, <literal>Zthes</literal> 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 <literal>oid</literal> 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 <literal>oid</literal>) is
+ returned.
+ </para>
+ <para>
+ <literal>oid_to_dotstring()</literal>
+ Translates the int-array <literal>oid</literal> into a dotted
+ string which is written into the area <literal>oidbuf</literal>
+ 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.
+ </para>
+ <para>
+ <literal>oid_name_to_dotstring()</literal>
+ combines the previous two functions to derive a dotted string
+ representing the OID specified by <literal>oclass</literal> and
+ <literal>name</literal>, writing it into the buffer passed as
+ <literal>oidbuf</literal> and returning its address.
+ </para>
+
+ <para>
Finally, the module provides the following utility functions, whose
meaning should be obvious:
</para>