dependencies/yaz-2.1.28/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.70.1"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="tools.html" title="Chapter 8. Supporting Tools"><link rel="prev" href="tools.html" title="Chapter 8. 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 8. 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. The <acronym class="acronym">ODR</acronym> module provides two
   4     utility-functions to create and copy this type of data elements:
   5    </p><pre class="screen">
   6     Odr_oid *odr_getoidbystr(ODR o, char *str);
   7    </pre><p>
   8     Creates an OID based on a string-based representation using dots (.)
   9     to separate elements in the OID.
  10    </p><pre class="screen">
  11     Odr_oid *odr_oiddup(ODR odr, Odr_oid *o);
  12    </pre><p>
  13     Creates a copy of the OID referenced by the <span class="emphasis"><em>o</em></span>
  14     parameter.
  15     Both functions take an <acronym class="acronym">ODR</acronym> stream as parameter. This stream is used to
  16     allocate memory for the data elements, which is released on a
  17     subsequent call to <code class="function">odr_reset()</code> on that stream.
  18    </p><p>
  19     The OID module provides a higher-level representation of the
  20     family of object identifiers which describe the Z39.50 protocol and its
  21     related objects. The definition of the module interface is given in
  22     the <code class="filename">oid.h</code> file.
  23    </p><p>
  24     The interface is mainly based on the <code class="literal">oident</code> structure.
  25     The definition of this structure looks like this:
  26    </p><pre class="screen">
  27 typedef struct oident
  28 {
  29     oid_proto proto;
  30     oid_class oclass;
  31     oid_value value;
  32     int oidsuffix[OID_SIZE];
  33     char *desc;
  34 } oident;
  35    </pre><p>
  36     The proto field takes one of the values
  37    </p><pre class="screen">
  38     PROTO_Z3950
  39     PROTO_GENERAL
  40    </pre><p>
  41     Use <code class="literal">PROTO_Z3950</code> for Z39.50 Object Identifers,
  42     <code class="literal">PROTO_GENERAL</code> for other types (such as
  43     those associated with ILL).
  44    </p><p>
  45
  46     The oclass field takes one of the values
  47    </p><pre class="screen">
  48     CLASS_APPCTX
  49     CLASS_ABSYN
  50     CLASS_ATTSET
  51     CLASS_TRANSYN
  52     CLASS_DIAGSET
  53     CLASS_RECSYN
  54     CLASS_RESFORM
  55     CLASS_ACCFORM
  56     CLASS_EXTSERV
  57     CLASS_USERINFO
  58     CLASS_ELEMSPEC
  59     CLASS_VARSET
  60     CLASS_SCHEMA
  61     CLASS_TAGSET
  62     CLASS_GENERAL
  63    </pre><p>
  64     corresponding to the OID classes defined by the Z39.50 standard.
  65
  66     Finally, the value field takes one of the values
  67    </p><pre class="screen">
  68     VAL_APDU
  69     VAL_BER
  70     VAL_BASIC_CTX
  71     VAL_BIB1
  72     VAL_EXP1
  73     VAL_EXT1
  74     VAL_CCL1
  75     VAL_GILS
  76     VAL_WAIS
  77     VAL_STAS
  78     VAL_DIAG1
  79     VAL_ISO2709
  80     VAL_UNIMARC
  81     VAL_INTERMARC
  82     VAL_CCF
  83     VAL_USMARC
  84     VAL_UKMARC
  85     VAL_NORMARC
  86     VAL_LIBRISMARC
  87     VAL_DANMARC
  88     VAL_FINMARC
  89     VAL_MAB
  90     VAL_CANMARC
  91     VAL_SBN
  92     VAL_PICAMARC
  93     VAL_AUSMARC
  94     VAL_IBERMARC
  95     VAL_EXPLAIN
  96     VAL_SUTRS
  97     VAL_OPAC
  98     VAL_SUMMARY
  99     VAL_GRS0
 100     VAL_GRS1
 101     VAL_EXTENDED
 102     VAL_RESOURCE1
 103     VAL_RESOURCE2
 104     VAL_PROMPT1
 105     VAL_DES1
 106     VAL_KRB1
 107     VAL_PRESSET
 108     VAL_PQUERY
 109     VAL_PCQUERY
 110     VAL_ITEMORDER
 111     VAL_DBUPDATE
 112     VAL_EXPORTSPEC
 113     VAL_EXPORTINV
 114     VAL_NONE
 115     VAL_SETM
 116     VAL_SETG
 117     VAL_VAR1
 118     VAL_ESPEC1
 119    </pre><p>
 120     again, corresponding to the specific OIDs defined by the standard.
 121     Refer to the
 122     <a href="http://www.loc.gov/z3950/agency/defns/oids.html" target="_top">
 123      Registry of Z39.50 Object Identifiers</a> for the
 124      whole list.
 125    </p><p>
 126     The desc field contains a brief, mnemonic name for the OID in question.
 127    </p><p>
 128     The function
 129    </p><pre class="screen">
 130     struct oident *oid_getentbyoid(int *o);
 131    </pre><p>
 132     takes as argument an OID, and returns a pointer to a static area
 133     containing an <code class="literal">oident</code> structure. You typically use
 134     this function when you receive a PDU containing an OID, and you wish
 135     to branch out depending on the specific OID value.
 136    </p><p>
 137     The function
 138    </p><pre class="screen">
 139     int *oid_ent_to_oid(struct oident *ent, int *dst);
 140    </pre><p>
 141     Takes as argument an <code class="literal">oident</code> structure - in which
 142     the <code class="literal">proto</code>, <code class="literal">oclass</code>/, and
 143     <code class="literal">value</code> fields are assumed to be set correctly -
 144     and returns a pointer to a the buffer as given by <code class="literal">dst</code>
 145     containing the base
 146     representation of the corresponding OID. The function returns
 147     NULL and the array dst is unchanged if a mapping couldn't place.
 148     The array <code class="literal">dst</code> should be at least of size
 149     <code class="literal">OID_SIZE</code>.
 150    </p><p>
 151
 152     The <code class="function">oid_ent_to_oid()</code> function can be used whenever
 153     you need to prepare a PDU containing one or more OIDs. The separation of
 154     the <code class="literal">protocol</code> element from the remainder of the
 155     OID-description makes it simple to write applications that can
 156     communicate with either Z39.50 or OSI SR-based applications.
 157    </p><p>
 158     The function
 159    </p><pre class="screen">
 160     oid_value oid_getvalbyname(const char *name);
 161    </pre><p>
 162     takes as argument a mnemonic OID name, and returns the
 163     <code class="literal">/value</code> field of the first entry in the database that
 164     contains the given name in its <code class="literal">desc</code> field.
 165    </p><p>
 166     Three utility functions are provided for translating OIDs'
 167     symbolic names (e.g. <code class="literal">Usmarc</code> into OID structures
 168     (int arrays) and strings containing the OID in dotted notation
 169     (e.g. <code class="literal">1.2.840.10003.9.5.1</code>).  They are:
 170    </p><pre class="screen">
 171     int *oid_name_to_oid(oid_class oclass, const char *name, int *oid);
 172     char *oid_to_dotstring(const int *oid, char *oidbuf);
 173     char *oid_name_to_dotstring(oid_class oclass, const char *name, char *oidbuf);
 174    </pre><p>
 175     <code class="literal">oid_name_to_oid()</code>
 176      translates the specified symbolic <code class="literal">name</code>,
 177      interpreted as being of class <code class="literal">oclass</code>.  (The
 178      class must be specified as many symbolic names exist within
 179      multiple classes - for example, <code class="literal">Zthes</code> is the
 180      symbolic name of an attribute set, a schema and a tag-set.)  The
 181      sequence of integers representing the OID is written into the
 182      area <code class="literal">oid</code> provided by the caller; it is the
 183      caller's responsibility to ensure that this area is large enough
 184      to contain the translated OID.  As a convenience, the address of
 185      the buffer (i.e. the value of <code class="literal">oid</code>) is
 186      returned.
 187    </p><p>
 188     <code class="literal">oid_to_dotstring()</code>
 189     Translates the int-array <code class="literal">oid</code> into a dotted
 190     string which is written into the area <code class="literal">oidbuf</code>
 191     supplied by the caller; it is the caller's responsibility to
 192     ensure that this area is large enough.  The address of the buffer
 193     is returned.
 194    </p><p>
 195     <code class="literal">oid_name_to_dotstring()</code>
 196     combines the previous two functions to derive a dotted string
 197     representing the OID specified by <code class="literal">oclass</code> and
 198     <code class="literal">name</code>, writing it into the buffer passed as
 199     <code class="literal">oidbuf</code> and returning its address.
 200    </p><p>
 201     Finally, the module provides the following utility functions, whose
 202     meaning should be obvious:
 203    </p><pre class="screen">
 204     void oid_oidcpy(int *t, int *s);
 205     void oid_oidcat(int *t, int *s);
 206     int oid_oidcmp(int *o1, int *o2);
 207     int oid_oidlen(int *o);
 208    </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 209      The OID module has been criticized - and perhaps rightly so
 210      - for needlessly abstracting the
 211      representation of OIDs. Other toolkits use a simple
 212      string-representation of OIDs with good results. In practice, we have
 213      found the interface comfortable and quick to work with, and it is a
 214      simple matter (for what it's worth) to create applications compatible
 215      with both ISO SR and Z39.50. Finally, the use of the
 216      <code class="literal">/oident</code> database is by no means mandatory.
 217      You can easily create your own system for representing OIDs, as long
 218      as it is compatible with the low-level integer-array representation
 219      of the ODR module.
 220     </p></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 8. 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>