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