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