dependencies/yaz_3.0.14/doc/tools.oid.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2. Object Identifiers</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="tools.html" title="Chapter 9. Supporting Tools"><link rel="prev" href="tools.html" title="Chapter 9. Supporting Tools"><link rel="next" href="tools.nmem.html" title="3. Nibble Memory"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. Object Identifiers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="tools.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Supporting Tools</th><td width="20%" align="right"> <a accesskey="n" href="tools.nmem.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tools.oid"></a>2. Object Identifiers</h2></div></div></div><p>
   2     The basic YAZ representation of an OID is an array of integers,
   3     terminated with the value -1. This integer is of type
   4     <code class="literal">Odr_oid</code>.
   5    </p><p>
   6     Fundamental OID operations and the type <code class="literal">Odr_oid</code>
   7     are defined in <code class="filename">yaz/oid_util.h</code>.
   8    </p><p>
   9     An OID can either be declared as a automatic variable or it can
  10     allocated using the memory utilities or ODR/NMEM. It's
  11     guaranteed that an OID can fit in <code class="literal">OID_SIZE</code> integers.
  12    </p><div class="example"><a name="tools.oid.bib1.1"></a><p class="title"><b>Example 9.13. Create OID on stack</b></p><div class="example-contents"><p>
  13      We can create an OID for the Bib-1 attribute set with:
  14      </p><pre class="screen">
  15       Odr_oid bib1[OID_SIZE];
  16       bib1[0] = 1;
  17       bib1[1] = 2;
  18       bib1[2] = 840;
  19       bib1[3] = 10003;
  20       bib1[4] = 3;
  21       bib1[5] = 1;
  22       bib1[6] = -1;
  23      </pre><p>
  24     </p></div></div><br class="example-break"><p>
  25     And OID may also be filled from a string-based representation using
  26     dots (.). This is achieved by function
  27     </p><pre class="screen">
  28      int oid_dotstring_to_oid(const char *name, Odr_oid *oid);
  29     </pre><p>
  30     This functions returns 0 if name could be converted; -1 otherwise.
  31    </p><div class="example"><a name="tools.oid.bib1.2"></a><p class="title"><b>Example 9.14. Using oid_oiddotstring_to_oid</b></p><div class="example-contents"><p>
  32      We can fill the Bib-1 attribute set OID easier with:
  33      </p><pre class="screen">
  34       Odr_oid bib1[OID_SIZE];
  35       oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1);
  36      </pre><p>
  37    </p></div></div><br class="example-break"><p>
  38     We can also allocate an OID dynamically on a ODR stream with:
  39    </p><pre class="screen">
  40     Odr_oid *odr_getoidbystr(ODR o, const char *str);
  41    </pre><p>
  42     This creates an OID from string-based representation using dots.
  43     This function take an <acronym class="acronym">ODR</acronym> stream as parameter. This stream is used to
  44     allocate memory for the data elements, which is released on a
  45     subsequent call to <code class="function">odr_reset()</code> on that stream.
  46    </p><div class="example"><a name="tools.oid.bib1.3"></a><p class="title"><b>Example 9.15. Using odr_getoidbystr</b></p><div class="example-contents"><p>
  47      We can create a OID for the Bib-1 attribute set with:
  48      </p><pre class="screen">
  49       Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1");
  50      </pre><p>
  51     </p></div></div><br class="example-break"><p>
  52     The function
  53     </p><pre class="screen">
  54      char *oid_oid_to_dotstring(const Odr_oid *oid, char *oidbuf)
  55     </pre><p>
  56     does the reverse of <code class="function">oid_oiddotstring_to_oid</code>. It
  57     converts an OID to the string-based representation using dots.
  58     The supplied char buffer <code class="literal">oidbuf</code> holds the resulting
  59     string and must be at least <code class="literal">OID_STR_MAX</code> in size.
  60    </p><p>
  61     OIDs can be copied with <code class="function">oid_oidcpy</code> which takes
  62     two OID lists as arguments. Alternativly, an OID copy can be allocated
  63     on a ODR stream with:
  64     </p><pre class="screen">
  65      Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
  66     </pre><p>
  67    </p><p>
  68     OIDs can be compared with <code class="function">oid_oidcmp</code> which returns
  69     zero if the two OIDs provided are identical; non-zero otherwise.
  70    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.oid.database"></a>2.1. OID database</h3></div></div></div><p>
  71      From YAZ version 3 and later, the oident system has been replaced
  72      by an OID database. OID database is a misnomer .. the old odient
  73      system was also a database.
  74     </p><p>
  75      The OID database is really just a map between named Object Identifiers
  76      (string) and their OID raw equivalents. Most operations either
  77      convert from string to OID or other way around.
  78     </p><p>
  79      Unfortunately, whenever we supply a string we must also specify the
  80      <span class="emphasis"><em>OID class</em></span>. The class is necessary because some
  81      strings correspond to multiple OIDs. An example of such a string is
  82      <code class="literal">Bib-1</code> which may either be an attribute-set
  83      or a diagnostic-set.
  84     </p><p>
  85      Applications using the YAZ database should include
  86      <code class="filename">yaz/oid_db.h</code>.
  87     </p><p>
  88      A YAZ database handle is of type <code class="literal">yaz_oid_db_t</code>.
  89      Actually that's a pointer. You need not think deal with that.
  90      YAZ has a built-in database which can be considered "constant" for
  91      most purposes.
  92      We can get hold that by using function <code class="function">yaz_oid_std</code>.
  93     </p><p>
  94      All functions with prefix <code class="function">yaz_string_to_oid</code>
  95      converts from class + string to OID. We have variants of this
  96      operation due to different memory allocation strategies.
  97     </p><p>
  98      All functions with prefix
  99      <code class="function">yaz_oid_to_string</code> converts from OID to string
 100      + class.
 101     </p><div class="example"><a name="tools.oid.bib1.4"></a><p class="title"><b>Example 9.16. Create OID with YAZ DB</b></p><div class="example-contents"><p>
 102       We can create an OID for the Bib-1 attribute set on the ODR stream
 103       odr with:
 104      </p><pre class="screen">
 105         Odr_oid *bib1 =
 106          yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr);
 107       </pre><p>
 108       This is more complex than using <code class="function">odr_getoidbystr</code>.
 109       You would only use <code class="function">yaz_string_to_oid_odr</code> when the
 110       string (here Bib-1) is supplied by a user or configuration.
 111      </p></div></div><br class="example-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.oid.std"></a>2.2. Standard OIDs</h3></div></div></div><p>
 112      All the object identifers in the standard OID database as returned
 113      by <code class="function">yaz_oid_std</code> can referenced directly in a
 114      program as a constant OID.
 115      Each constant OID is prefixed with <code class="literal">yaz_oid_</code> -
 116      followed by OID class (lowercase) - then by OID name (normalized and
 117      lowercase).
 118     </p><p>
 119      See <a class="xref" href="list-oids.html" title="Appendix A. List of Object Identifiers">Appendix A, <i>List of Object Identifiers</i></a> for list of all object identifiers
 120      built into YAZ.
 121      These are declared in <code class="filename">yaz/oid_std.h</code> but are
 122      included by <code class="filename">yaz/oid_db.h</code> as well.
 123     </p><div class="example"><a name="tools.oid.bib1.5"></a><p class="title"><b>Example 9.17. Use a built-in OID</b></p><div class="example-contents"><p>
 124       We can allocate our own OID filled with the constant OID for
 125       Bib-1 with:
 126       </p><pre class="screen">
 127         Odr_oid *bib1 = odr_oiddup(o, yaz_oid_attset_bib1);
 128       </pre><p>
 129      </p></div></div><br class="example-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="tools.oid.oident"></a>2.3. OID oident</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 130      The oident utility has been removed from YAZ version 3. This
 131      sub section only applies to YAZ version 2.
 132     </p></div><p>
 133     The OID module provides a higher-level representation of the
 134     family of object identifiers which describe the Z39.50 protocol and its
 135     related objects. The definition of the module interface is given in
 136     the <code class="filename">oid.h</code> file.
 137    </p><p>
 138     The interface is mainly based on the <code class="literal">oident</code> structure.
 139     The definition of this structure looks like this:
 140    </p><pre class="screen">
 141 typedef struct oident
 142 {
 143     oid_proto proto;
 144     oid_class oclass;
 145     oid_value value;
 146     int oidsuffix[OID_SIZE];
 147     char *desc;
 148 } oident;
 149    </pre><p>
 150     The proto field takes one of the values
 151    </p><pre class="screen">
 152     PROTO_Z3950
 153     PROTO_GENERAL
 154    </pre><p>
 155     Use <code class="literal">PROTO_Z3950</code> for Z39.50 Object Identifers,
 156     <code class="literal">PROTO_GENERAL</code> for other types (such as
 157     those associated with ILL).
 158    </p><p>
 159
 160     The oclass field takes one of the values
 161    </p><pre class="screen">
 162     CLASS_APPCTX
 163     CLASS_ABSYN
 164     CLASS_ATTSET
 165     CLASS_TRANSYN
 166     CLASS_DIAGSET
 167     CLASS_RECSYN
 168     CLASS_RESFORM
 169     CLASS_ACCFORM
 170     CLASS_EXTSERV
 171     CLASS_USERINFO
 172     CLASS_ELEMSPEC
 173     CLASS_VARSET
 174     CLASS_SCHEMA
 175     CLASS_TAGSET
 176     CLASS_GENERAL
 177    </pre><p>
 178     corresponding to the OID classes defined by the Z39.50 standard.
 179
 180     Finally, the value field takes one of the values
 181    </p><pre class="screen">
 182     VAL_APDU
 183     VAL_BER
 184     VAL_BASIC_CTX
 185     VAL_BIB1
 186     VAL_EXP1
 187     VAL_EXT1
 188     VAL_CCL1
 189     VAL_GILS
 190     VAL_WAIS
 191     VAL_STAS
 192     VAL_DIAG1
 193     VAL_ISO2709
 194     VAL_UNIMARC
 195     VAL_INTERMARC
 196     VAL_CCF
 197     VAL_USMARC
 198     VAL_UKMARC
 199     VAL_NORMARC
 200     VAL_LIBRISMARC
 201     VAL_DANMARC
 202     VAL_FINMARC
 203     VAL_MAB
 204     VAL_CANMARC
 205     VAL_SBN
 206     VAL_PICAMARC
 207     VAL_AUSMARC
 208     VAL_IBERMARC
 209     VAL_EXPLAIN
 210     VAL_SUTRS
 211     VAL_OPAC
 212     VAL_SUMMARY
 213     VAL_GRS0
 214     VAL_GRS1
 215     VAL_EXTENDED
 216     VAL_RESOURCE1
 217     VAL_RESOURCE2
 218     VAL_PROMPT1
 219     VAL_DES1
 220     VAL_KRB1
 221     VAL_PRESSET
 222     VAL_PQUERY
 223     VAL_PCQUERY
 224     VAL_ITEMORDER
 225     VAL_DBUPDATE
 226     VAL_EXPORTSPEC
 227     VAL_EXPORTINV
 228     VAL_NONE
 229     VAL_SETM
 230     VAL_SETG
 231     VAL_VAR1
 232     VAL_ESPEC1
 233    </pre><p>
 234     again, corresponding to the specific OIDs defined by the standard.
 235     Refer to the
 236     <a class="ulink" href="http://www.loc.gov/z3950/agency/defns/oids.html" target="_top">
 237      Registry of Z39.50 Object Identifiers</a> for the
 238      whole list.
 239    </p><p>
 240     The desc field contains a brief, mnemonic name for the OID in question.
 241    </p><p>
 242     The function
 243    </p><pre class="screen">
 244     struct oident *oid_getentbyoid(int *o);
 245    </pre><p>
 246     takes as argument an OID, and returns a pointer to a static area
 247     containing an <code class="literal">oident</code> structure. You typically use
 248     this function when you receive a PDU containing an OID, and you wish
 249     to branch out depending on the specific OID value.
 250    </p><p>
 251     The function
 252    </p><pre class="screen">
 253     int *oid_ent_to_oid(struct oident *ent, int *dst);
 254    </pre><p>
 255     Takes as argument an <code class="literal">oident</code> structure - in which
 256     the <code class="literal">proto</code>, <code class="literal">oclass</code>/, and
 257     <code class="literal">value</code> fields are assumed to be set correctly -
 258     and returns a pointer to a the buffer as given by <code class="literal">dst</code>
 259     containing the base
 260     representation of the corresponding OID. The function returns
 261     NULL and the array dst is unchanged if a mapping couldn't place.
 262     The array <code class="literal">dst</code> should be at least of size
 263     <code class="literal">OID_SIZE</code>.
 264    </p><p>
 265
 266     The <code class="function">oid_ent_to_oid()</code> function can be used whenever
 267     you need to prepare a PDU containing one or more OIDs. The separation of
 268     the <code class="literal">protocol</code> element from the remainder of the
 269     OID-description makes it simple to write applications that can
 270     communicate with either Z39.50 or OSI SR-based applications.
 271    </p><p>
 272     The function
 273    </p><pre class="screen">
 274     oid_value oid_getvalbyname(const char *name);
 275    </pre><p>
 276     takes as argument a mnemonic OID name, and returns the
 277     <code class="literal">/value</code> field of the first entry in the database that
 278     contains the given name in its <code class="literal">desc</code> field.
 279    </p><p>
 280     Three utility functions are provided for translating OIDs'
 281     symbolic names (e.g. <code class="literal">Usmarc</code> into OID structures
 282     (int arrays) and strings containing the OID in dotted notation
 283     (e.g. <code class="literal">1.2.840.10003.9.5.1</code>).  They are:
 284    </p><pre class="screen">
 285     int *oid_name_to_oid(oid_class oclass, const char *name, int *oid);
 286     char *oid_to_dotstring(const int *oid, char *oidbuf);
 287     char *oid_name_to_dotstring(oid_class oclass, const char *name, char *oidbuf);
 288    </pre><p>
 289     <code class="literal">oid_name_to_oid()</code>
 290      translates the specified symbolic <code class="literal">name</code>,
 291      interpreted as being of class <code class="literal">oclass</code>.  (The
 292      class must be specified as many symbolic names exist within
 293      multiple classes - for example, <code class="literal">Zthes</code> is the
 294      symbolic name of an attribute set, a schema and a tag-set.)  The
 295      sequence of integers representing the OID is written into the
 296      area <code class="literal">oid</code> provided by the caller; it is the
 297      caller's responsibility to ensure that this area is large enough
 298      to contain the translated OID.  As a convenience, the address of
 299      the buffer (i.e. the value of <code class="literal">oid</code>) is
 300      returned.
 301    </p><p>
 302     <code class="literal">oid_to_dotstring()</code>
 303     Translates the int-array <code class="literal">oid</code> into a dotted
 304     string which is written into the area <code class="literal">oidbuf</code>
 305     supplied by the caller; it is the caller's responsibility to
 306     ensure that this area is large enough.  The address of the buffer
 307     is returned.
 308    </p><p>
 309     <code class="literal">oid_name_to_dotstring()</code>
 310     combines the previous two functions to derive a dotted string
 311     representing the OID specified by <code class="literal">oclass</code> and
 312     <code class="literal">name</code>, writing it into the buffer passed as
 313     <code class="literal">oidbuf</code> and returning its address.
 314    </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 315      The OID module has been criticized - and perhaps rightly so
 316      - for needlessly abstracting the
 317      representation of OIDs. Other toolkits use a simple
 318      string-representation of OIDs with good results. In practice, we have
 319      found the interface comfortable and quick to work with, and it is a
 320      simple matter (for what it's worth) to create applications compatible
 321      with both ISO SR and Z39.50. Finally, the use of the
 322      <code class="literal">/oident</code> database is by no means mandatory.
 323      You can easily create your own system for representing OIDs, as long
 324      as it is compatible with the low-level integer-array representation
 325      of the ODR module.
 326     </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tools.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tools.nmem.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Supporting Tools </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3. Nibble Memory</td></tr></table></div></body></html>