2. Object Identifiers

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.

2.1. OID database

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.

2.2. Standard OIDs

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);