/usr/share/doc/yaz-doc/tools.oid.html is in yaz-doc 4.2.30-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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.78.1"><link rel="home" 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"><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"><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"><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>
|