The basic YAZ representation of an OID is an array of integers,
terminated with the value -1. This integer is of type
Odr_oid
.
Fundamental OID operations and the type Odr_oid
are defined in yaz/oid_util.h
.
An OID can either be declared as a automatic variable or it can
be allocated using the memory utilities or ODR/NMEM. It's
guaranteed that an OID can fit in OID_SIZE
integers.
Example 7.13. Create OID on stack
We can create an OID for the Bib-1 attribute set with:
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;
And OID may also be filled from a string-based representation using dots (.). This is achieved by the function
int oid_dotstring_to_oid(const char *name, Odr_oid *oid);
This functions returns 0 if name could be converted; -1 otherwise.
Example 7.14. Using oid_oiddotstring_to_oid
We can fill the Bib-1 attribute set OID more easily with:
Odr_oid bib1[OID_SIZE]; oid_oiddotstring_to_oid("1.2.840.10003.3.1", bib1);
We can also allocate an OID dynamically on an ODR stream with:
Odr_oid *odr_getoidbystr(ODR o, const char *str);
This creates an OID from a string-based representation using dots.
This function take an ODR stream as parameter. This stream is used to
allocate memory for the data elements, which is released on a
subsequent call to odr_reset()
on that stream.
Example 7.15. Using odr_getoidbystr
We can create an OID for the Bib-1 attribute set with:
Odr_oid *bib1 = odr_getoidbystr(odr, "1.2.840.10003.3.1");
The function
char *oid_oid_to_dotstring(const Odr_oid *oid, char *oidbuf)
does the reverse of oid_oiddotstring_to_oid
. It
converts an OID to the string-based representation using dots.
The supplied char buffer oidbuf
holds the resulting
string and must be at least OID_STR_MAX
in size.
OIDs can be copied with oid_oidcpy
which takes
two OID lists as arguments. Alternatively, an OID copy can be allocated
on an ODR stream with:
Odr_oid *odr_oiddup(ODR odr, const Odr_oid *o);
OIDs can be compared with oid_oidcmp
which returns
zero if the two OIDs provided are identical; non-zero otherwise.
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.
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.
Unfortunately, whenever we supply a string we must also specify the
OID class. The class is necessary because some
strings correspond to multiple OIDs. An example of such a string is
Bib-1
which may either be an attribute-set
or a diagnostic-set.
Applications using the YAZ database should include
yaz/oid_db.h
.
A YAZ database handle is of type yaz_oid_db_t
.
Actually that's a pointer. You need not deal with that.
YAZ has a built-in database which can be considered "constant" for
most purposes.
We can get hold of that by using function yaz_oid_std
.
All functions with prefix yaz_string_to_oid
converts from class + string to OID. We have variants of this
operation due to different memory allocation strategies.
All functions with prefix
yaz_oid_to_string
converts from OID to string
+ class.
Example 7.16. Create OID with YAZ DB
We can create an OID for the Bib-1 attribute set on the ODR stream odr with:
Odr_oid *bib1 = yaz_string_to_oid_odr(yaz_oid_std(), CLASS_ATTSET, "Bib-1", odr);
This is more complex than using odr_getoidbystr
.
You would only use yaz_string_to_oid_odr
when the
string (here Bib-1) is supplied by a user or configuration.
All the object identifiers in the standard OID database as returned
by yaz_oid_std
can be referenced directly in a
program as a constant OID.
Each constant OID is prefixed with yaz_oid_
-
followed by OID class (lowercase) - then by OID name (normalized and
lowercase).
See Appendix A, List of Object Identifiers for list of all object identifiers
built into YAZ.
These are declared in yaz/oid_std.h
but are
included by yaz/oid_db.h
as well.
Example 7.17. Use a built-in OID
We can allocate our own OID filled with the constant OID for Bib-1 with:
Odr_oid *bib1 = odr_oiddup(o, yaz_oid_attset_bib1);