File: tools.oid.html

package info (click to toggle)
yaz 3.0.34-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,404 kB
  • ctags: 12,108
  • sloc: xml: 116,075; ansic: 52,205; sh: 9,746; tcl: 2,043; makefile: 1,141; yacc: 347
file content (129 lines) | stat: -rw-r--r-- 8,837 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
<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�7.�Supporting Tools"><link rel="prev" href="tools.html" title="Chapter�7.�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�7.�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>
    The basic YAZ representation of an OID is an array of integers,
    terminated with the value -1. This integer is of type 
    <code class="literal">Odr_oid</code>.
   </p><p>
    Fundamental OID operations and the type <code class="literal">Odr_oid</code>
    are defined in <code class="filename">yaz/oid_util.h</code>.
   </p><p>
    An OID can either be declared as a automatic variable or it can
    allocated using the memory utilities or ODR/NMEM. It's
    guaranteed that an OID can fit in <code class="literal">OID_SIZE</code> integers.
   </p><div class="example"><a name="tools.oid.bib1.1"></a><p class="title"><b>Example�7.13.�Create OID on stack</b></p><div class="example-contents"><p>
     We can create an OID for the Bib-1 attribute set with:
     </p><pre class="screen">
      Odr_oid bib1[OID_SIZE];
      bib1[0] = 1;
      bib1[1] = 2;
      bib1[2] = 840;
      bib1[3] = 10003;
      bib1[4] = 3;
      bib1[5] = 1;
      bib1[6] = -1;
     </pre><p>
    </p></div></div><br class="example-break"><p>
    And OID may also be filled from a string-based representation using
    dots (.). This is achieved by function
    </p><pre class="screen">
     int oid_dotstring_to_oid(const char *name, Odr_oid *oid);
    </pre><p>
    This functions returns 0 if name could be converted; -1 otherwise.
   </p><div class="example"><a name="tools.oid.bib1.2"></a><p class="title"><b>Example�7.14.�Using oid_oiddotstring_to_oid</b></p><div class="example-contents"><p>
     We can fill the Bib-1 attribute set OID easier with:
     </p><pre class="screen">
      Odr_oid bib1[OID_SIZE];
      oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1);
     </pre><p>
   </p></div></div><br class="example-break"><p>
    We can also allocate an OID dynamically on a ODR stream with:
   </p><pre class="screen">
    Odr_oid *odr_getoidbystr(ODR o, const char *str);
   </pre><p>
    This creates an OID from string-based representation using dots.
    This function take an <acronym class="acronym">ODR</acronym> stream as parameter. This stream is used to
    allocate memory for the data elements, which is released on a
    subsequent call to <code class="function">odr_reset()</code> on that stream.
   </p><div class="example"><a name="tools.oid.bib1.3"></a><p class="title"><b>Example�7.15.�Using odr_getoidbystr</b></p><div class="example-contents"><p>
     We can create a OID for the Bib-1 attribute set with:
     </p><pre class="screen">
      Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1");
     </pre><p>
    </p></div></div><br class="example-break"><p>
    The function
    </p><pre class="screen">
     char *oid_oid_to_dotstring(const Odr_oid *oid, char *oidbuf)
    </pre><p>
    does the reverse of <code class="function">oid_oiddotstring_to_oid</code>. It
    converts an OID to the string-based representation using dots.
    The supplied char buffer <code class="literal">oidbuf</code> holds the resulting
    string and must be at least <code class="literal">OID_STR_MAX</code> in size.
   </p><p>
    OIDs can be copied with <code class="function">oid_oidcpy</code> which takes
    two OID lists as arguments. Alternativly, an OID copy can be allocated
    on a ODR stream with:
    </p><pre class="screen">
     Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
    </pre><p>
   </p><p>
    OIDs can be compared with <code class="function">oid_oidcmp</code> which returns
    zero if the two OIDs provided are identical; non-zero otherwise.
   </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>
     From YAZ version 3 and later, the oident system has been replaced
     by an OID database. OID database is a misnomer .. the old odient
     system was also a database.
    </p><p>
     The OID database is really just a map between named Object Identifiers
     (string) and their OID raw equivalents. Most operations either
     convert from string to OID or other way around.
    </p><p>
     Unfortunately, whenever we supply a string we must also specify the 
     <span class="emphasis"><em>OID class</em></span>. The class is necessary because some
     strings correspond to multiple OIDs. An example of such a string is
     <code class="literal">Bib-1</code> which may either be an attribute-set 
     or a diagnostic-set.
    </p><p>
     Applications using the YAZ database should include 
     <code class="filename">yaz/oid_db.h</code>.
    </p><p>
     A YAZ database handle is of type <code class="literal">yaz_oid_db_t</code>.
     Actually that's a pointer. You need not think deal with that.
     YAZ has a built-in database which can be considered "constant" for
     most purposes. 
     We can get hold that by using function <code class="function">yaz_oid_std</code>.
    </p><p>
     All functions with prefix <code class="function">yaz_string_to_oid</code>
     converts from class + string to OID. We have variants of this
     operation due to different memory allocation strategies.
    </p><p>
     All functions with prefix
     <code class="function">yaz_oid_to_string</code> converts from OID to string
     + class.
    </p><div class="example"><a name="tools.oid.bib1.4"></a><p class="title"><b>Example�7.16.�Create OID with YAZ DB</b></p><div class="example-contents"><p>
      We can create an OID for the Bib-1 attribute set on the ODR stream
      odr with:
     </p><pre class="screen">
        Odr_oid *bib1 = 
         yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr);
      </pre><p>
      This is more complex than using <code class="function">odr_getoidbystr</code>.
      You would only use <code class="function">yaz_string_to_oid_odr</code> when the
      string (here Bib-1) is supplied by a user or configuration.
     </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>
     All the object identifers in the standard OID database as returned
     by <code class="function">yaz_oid_std</code> can referenced directly in a
     program as a constant OID.
     Each constant OID is prefixed with <code class="literal">yaz_oid_</code> -
     followed by OID class (lowercase) - then by OID name (normalized and
     lowercase).
    </p><p>
     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
     built into YAZ.
     These are declared in <code class="filename">yaz/oid_std.h</code> but are
     included by <code class="filename">yaz/oid_db.h</code> as well.
    </p><div class="example"><a name="tools.oid.bib1.5"></a><p class="title"><b>Example�7.17.�Use a built-in OID</b></p><div class="example-contents"><p>
      We can allocate our own OID filled with the constant OID for
      Bib-1 with:
      </p><pre class="screen">
        Odr_oid *bib1 = odr_oiddup(o, yaz_oid_attset_bib1);
      </pre><p>
     </p></div></div><br class="example-break"></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�7.�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>