>Object Identifiers

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_SR
   

If you don't care about talking to SR-based implementations (few exist, and they may become fewer still if and when the ISO SR and ANSI Z39.50 documents are merged into a single standard), you can ignore this field on incoming packages, and always set it to PROTO_Z3950 for outgoing packages.

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.

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.

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.