2. Object Identifiers
Prev | Chapter 7. Supporting Tools | Next

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

Prev | Up | Next
Chapter 7. Supporting Tools | Home | 3. Nibble Memory