YAZ User's Guide and Reference
Prev | Chapter 8. Supporting Tools | Next

# Object Identifiers

The basic YAZ representation of an OID is an array of integers, terminated with the value -1. The ODR module provides two utility-functions to create and copy this type of data elements:

        Odr_oid *odr_getoidbystr(ODR o, char *str);

Creates an OID based on a string-based representation using dots (.) to separate elements in the OID.

        Odr_oid *odr_oiddup(ODR odr, Odr_oid *o);

Creates a copy of the OID referenced by the o parameter. Both functions 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.

The OID module provides a higher-level representation of the family of object identifiers which describe the Z39.50 protocol and its related objects. The definition of the module interface is given in the `oid.h` file.

The interface is mainly based on the `oident` structure. The definition of this structure looks like this:

    typedef struct oident
    {
        oid_proto proto;
        oid_class oclass;
        oid_value value;
        int oidsuffix[OID_SIZE];
        char *desc;
    } oident;

The proto field takes one of the values

        PROTO_Z3950
        PROTO_GENERAL

Use `PROTO_Z3950` for Z39.50 Object Identifers, `PROTO_GENERAL` for other types (such as those associated with ILL).

The oclass field takes one of the values

        CLASS_APPCTX
        CLASS_ABSYN
        CLASS_ATTSET
        CLASS_TRANSYN
        CLASS_DIAGSET
        CLASS_RECSYN
        CLASS_RESFORM
        CLASS_ACCFORM
        CLASS_EXTSERV
        CLASS_USERINFO
        CLASS_ELEMSPEC
        CLASS_VARSET
        CLASS_SCHEMA
        CLASS_TAGSET
        CLASS_GENERAL

corresponding to the OID classes defined by the Z39.50 standard. Finally, the value field takes one of the values

        VAL_APDU
        VAL_BER
        VAL_BASIC_CTX
        VAL_BIB1
        VAL_EXP1
        VAL_EXT1
        VAL_CCL1
        VAL_GILS
        VAL_WAIS
        VAL_STAS
        VAL_DIAG1
        VAL_ISO2709
        VAL_UNIMARC
        VAL_INTERMARC
        VAL_CCF
        VAL_USMARC
        VAL_UKMARC
        VAL_NORMARC
        VAL_LIBRISMARC
        VAL_DANMARC
        VAL_FINMARC
        VAL_MAB
        VAL_CANMARC
        VAL_SBN
        VAL_PICAMARC
        VAL_AUSMARC
        VAL_IBERMARC
        VAL_EXPLAIN
        VAL_SUTRS
        VAL_OPAC
        VAL_SUMMARY
        VAL_GRS0
        VAL_GRS1
        VAL_EXTENDED
        VAL_RESOURCE1
        VAL_RESOURCE2
        VAL_PROMPT1
        VAL_DES1
        VAL_KRB1
        VAL_PRESSET
        VAL_PQUERY
        VAL_PCQUERY
        VAL_ITEMORDER
        VAL_DBUPDATE
        VAL_EXPORTSPEC
        VAL_EXPORTINV
        VAL_NONE
        VAL_SETM
        VAL_SETG
        VAL_VAR1
        VAL_ESPEC1

again, corresponding to the specific OIDs defined by the standard. Refer to the Registry of Z39.50 Object Identifiers for the whole list.

The desc field contains a brief, mnemonic name for the OID in question.

The function

        struct oident *oid_getentbyoid(int *o);

takes as argument an OID, and returns a pointer to a static area containing an `oident` structure. You typically use this function when you receive a PDU containing an OID, and you wish to branch out depending on the specific OID value.

The function

        int *oid_ent_to_oid(struct oident *ent, int *dst);

Takes as argument an `oident` structure - in which the `proto`, `oclass`/, and `value` fields are assumed to be set correctly - and returns a pointer to a the buffer as given by `dst` containing the base representation of the corresponding OID. The function returns NULL and the array dst is unchanged if a mapping couldn't place. The array `dst` should be at least of size `OID_SIZE`.

The `oid_ent_to_oid()` function can be used whenever you need to prepare a PDU containing one or more OIDs. The separation of the `protocol` element from the remainder of the OID-description makes it simple to write applications that can communicate with either Z39.50 or OSI SR-based applications.

The function

        oid_value oid_getvalbyname(const char *name);

takes as argument a mnemonic OID name, and returns the `/value` field of the first entry in the database that contains the given name in its `desc` field.

Three utility functions are provided for translating OIDs' symbolic names (e.g. `Usmarc` into OID structures (int arrays) and strings containing the OID in dotted notation (e.g. `1.2.840.10003.9.5.1`). They are:

        int *oid_name_to_oid(oid_class oclass, const char *name, int *oid);
        char *oid_to_dotstring(const int *oid, char *oidbuf);
        char *oid_name_to_dotstring(oid_class oclass, const char *name, char *oidbuf);

`oid_name_to_oid()` translates the specified symbolic `name`, interpreted as being of class `oclass`. (The class must be specified as many symbolic names exist within multiple classes - for example, `Zthes` is the symbolic name of an attribute set, a schema and a tag-set.) The sequence of integers representing the OID is written into the area `oid` provided by the caller; it is the caller's responsibility to ensure that this area is large enough to contain the translated OID. As a convenience, the address of the buffer (i.e. the value of `oid`) is returned.

`oid_to_dotstring()` Translates the int-array `oid` into a dotted string which is written into the area `oidbuf` supplied by the caller; it is the caller's responsibility to ensure that this area is large enough. The address of the buffer is returned.

`oid_name_to_dotstring()` combines the previous two functions to derive a dotted string representing the OID specified by `oclass` and `name`, writing it into the buffer passed as `oidbuf` and returning its address.

Finally, the module provides the following utility functions, whose meaning should be obvious:

        void oid_oidcpy(int *t, int *s);
        void oid_oidcat(int *t, int *s);
        int oid_oidcmp(int *o1, int *o2);
        int oid_oidlen(int *o);

> Note: The OID module has been criticized - and perhaps rightly so - for needlessly abstracting the representation of OIDs. Other toolkits use a simple string-representation of OIDs with good results. In practice, we have found the interface comfortable and quick to work with, and it is a simple matter (for what it's worth) to create applications compatible with both ISO SR and Z39.50. Finally, the use of the `/oident` database is by no means mandatory. You can easily create your own system for representing OIDs, as long as it is compatible with the low-level integer-array representation of the ODR module.

Prev | Home | Next
Supporting Tools | Up | Nibble Memory