V4 Design: dbdClass

EPICS: C++ class definitions for Database Definition

May 11 2005

UNDER CONSTRUCTION - DO NOT COMMENT

Overview

This document describes the C++ class definitions for code that implements the semantics for records created from Database Definitions. The classes can be separated into two classes:

• dbdTypes.h - Classes that described fields in header files generated from dbd definitions. Header files are generated from the following dbd definitions:
  • record
  • struct
  • menu
• dbdIntrospect.h - Classes intended for introspection, i.e. for code that does not include the generated header files.

---

Example Database Definition Files

Database Definition Files

menuAlarmSevr.dbd contains:

    menu(menuAlarmSevr) { 
         choice("NO_ALARM") 
         choice("MINOR")
         choice("MAJOR")
         choice("INVALID")
    }

displayLimit.dbd contains:

    struct(displayLimit) {
        field(low,float64)
        field(high,float64)
    }

exampleRecord.dbd contains:

    record(example) extends iocRecord {
        field(value,float64)
        field(displayLimit,struct(displayLimit))
    }

alltypesRecord.dbd contains:

    record(allTypes) extends iocRecord {
        field(fbool,bool)
        field(foctet,octet)
        field(fint16,int16)
        field(fuint16,uint16)
        field(fint32,int32)
        field(fuint32,uint32)
        field(fint64,int64)
        field(fuint64,uint64)
        field(ffloat32,float32)
        field(ffloat64,float64)
        field(fstring,string)
        field(fmenu,menu(menuName))
        field(fenum,enum)
        field(fstruct,struct(displayLimit))
        field(flink,link(dir))
        field(fdevice,device(dir,interfaceName))
    }

Generated Header Files

menuAlarmSevr.h is generated from menuAlarmSevr.dbd

    enum menuAlarmSevr {
           menuAlarmSevrNO_ALARM,
           menuAlarmSevrMINOR,
           menuAlarmSevrMAJOR,
           menuAlarmSevrINVALID
    };

displayLimit.h is generated from displayLimit.dbd

    class displayLimit {
        dbdFloat64 low;
        dbdFloat64 high;
    };
    const dbdInt16 displayLimit_firstIndex = 1
    const dbdInt16 displayLimit_low        = 1
    const dbdInt16 displayLimit_high       = 2
    const dbdInt16 displayLimit_lastIndex =displayLimit_high

exampleRecord.h is generated from exampleRecord.dbd

    class exampleRecord {
    public:
        ...    All the fields from iocRecord.dbd
        dbdFloat64 value;
        dbdStruct  displayLimit;
    };
   
    const dbdInt16 example_firstIndex = 1001001
    const dbdInt16 example_low = 1001001;
    const dbdInt16 example_high = 1001002;
    const dbdInt16 example_lastIndex = example_high;

alltypesRecord.h is generated from alltypesRecord.dbd

    class allTypesRecord {
    public:
        ...    All the fields from iocRecord.dbd
        dbdRecord  common;
        dbdBoolean fbool;
        dbdOctet   foctet;
        dbdInt16   fint16;
        dbdUInt16  fuint16;
        dbdInt32   fint32;
        dbdUInt32  fuint32;
        dbdInt64   fint32;
        dbdUInt64  fuint32;
        dbdFloat32 ffloat32;
        dbdFloat64 ffloat64;
        dbdString  fstring;
        dbdMenu    fmenu;
        dbdEnum    fenum
        dbdStruct  fstruct;
        dbdLink    flink;
        dbdDevice  fdevice;
    };
   
    const dbdInt16 allTypes_firstIndex = 1001001
    const dbdInt16 allTypes_fbool = 1001001;
    const dbdInt16 allTypes_foctet = 1001002;
    const dbdInt16 allTypes_fint16 = 1001003;
    const dbdInt16 allTypes_fuint16 = 1001004;
    const dbdInt16 allTypes_fint32 = 1001005;
    const dbdInt16 allTypes_fuint32 = 1001006;
    const dbdInt16 allTypes_fint64 = 1001007;
    const dbdInt16 allTypes_fuint64 = 1001008;
    const dbdInt16 allTypes_ffloat32 = 1001009;
    const dbdInt16 allTypes_ffloatn64 = 10010010;
    const dbdInt16 allTypes_ffstring = 10010011;
    const dbdInt16 allTypes_fmenu = 10010012;
    const dbdInt16 allTypes_fenum = 10010013;
    const dbdInt16 allTypes_fstruct = 10010014;
    const dbdInt16 allTypes_flink = 10010015
    const dbdInt16 allTypes_fdevice = 10010016
    const dbdInt16 allTypes_lastIndex = allTypes_fdevice;

---

dbdTypes.h

File dbdTypes.h describes the datatypes used by V4 databases:

/* TBD dbdNdimArrayT*/
enum dbdType {
    dbdUnknownT,dbdBooleanT,dbdOctetT,
    dbdInt16T,dbdUInt16T,dbdInt32T,dbdUInt32T,dbdInt64T,dbdUInt64T,
    dbdFloat32T,dbdFloat64T,
    dbdStringT,
    dbdStructT,
    dbdMenuT,dbdEnumT,
    dbdLinkT,dbdDeviceT,
    dbdArrayT
};

/* some of the following may require OSD definitions*/
typedef bool               dbdBoolean;
typedef char               dbdOctet;
typedef short              dbdInt16;
typedef unsigned short     dbdUInt16;
typedef int                dbdInt32;
typedef unsigned int       dbdUInt32;
typedef long long          dbdInt64;
typedef unsigned long long dbdUInt64;
typedef float              dbdFloat32;
typedef double             dbdFloat64;

class dbdRecord;

// dbdStructPtr always references a class generated from a struct dbd
typedef void * dbdStructPtr;

// dbdInterfacePtr always references a class that contains only methods
typedef void *dbdInterfacePtr;

class dbdInterface {
public:
    const char      *interfaceType;
    dbdInterfacePtr *pinterface;
};

/*dbdString holds UTF-8 characters*/
class dbdString {
public:
    dbdInt32  capacity;  /*capacity in bytes*/
    dbdOctet  *pstorage;
};

class dbdStructMember {
    dbdString name;
    dbdType   type;
};

class dbdStructDef{
    dbdString       name;
    dbdInt16        nmembers;
    dbdStructMember *pmember[];
    dbdInterface    interface;
};

class dbdStruct{ // for a field referencing a struct
    dbdStructDef *pdbdStructDef;
    dbdStructPtr ptr;
};

class dbdMenuDef{
public:
    dbdString name;
    dbdInt16  nchoices;
    dbdString *pchoice[];
};

class dbdMenu{ // for a struct or record field
public:
    dbdInt16    index;
    dbdMenuDef  *pdbdMenuDef[];
};

class dbdEnum{
public:
    dbdInt16  index;
    dbdInt16  nchoices;
    dbdString *pchoice[];
};

class dbdInterfaceDef {
public:
    dbdString interfaceName;
    dbdString choiceName;
    dbdString dataStructName;
    dbdInterface *pdbdInterface;
};

enum dbdLinkDir {
    dbdLinkDirNone,
    dbdLinkDirForward,
    dbdLinkDirIn,
    dbdLinkDirOut,
    dbdLinkDirInOut
};
class dbdLinkDef{
public:
    dbdLinkDir    dir;
    dbdString     choiceName;
    dbdInterface *pdbdInterface;
    dbdString     dataStructName;
};
class dbdLink{ // for a struct or record field
public:
    dbdLinkDir  dir;
    dbdString   choiceName;
    dbdLinkDef  *plinkDef;
    dbdStruct   dataStruct;
};

class dbdDeviceDef {
public:
    dbdLinkDir  dir;
    dbdString interfaceName;
    dbdString choiceName;
    dbdString dataStructName;
    dbdInterface *pdbdInterface;
};

class dbdDevice{ // for a struct or record field
public:
    dbdLinkDir   dir;
    dbdString    choiceName;
    dbdDeviceDef *pdeviceDef;
    dbdStruct    dataStruct;
};

template< class ARR_T > class dbdArray {
public:
    dbdInt32  capacity;  /*capacity in number of elements*/
    dbdInt32  size;      /*current number of elements*/
    dbdType   type;
    ARR_T     *pstorage;
};

/*  The following array types are supported by dbdCore
 *  dbdArray<void>;
 *  dbdArray<dbdOctet>;
 *  dbdArray<dbdInt16>;
 *  dbdArray<dbdUInt16>;
 *  dbdArray<dbdInt32>;
 *  dbdArray<dbdUInt32>;
 *  dbdArray<dbdInt64>;
 *  dbdArray<dbdUInt64>;
 *  dbdArray<dbdFloat32>;
 *  dbdArray<dbdFloat64>;
 *  dbdArray<dbdString>;
 *  dbdArray<dbdLinkField>;
**/

/* every struct and every record support module implements the following*/
class dbdStructMetaSupport {
    virtual dbdStructPtr create() = 0;
    virtual dbdBoolean initialize(dbdString *errorMessage, dbdStructPtr ptr) = 0;
    virtual dbdBoolean finalize(dbdString *errorMessage, dbdStructPtr ptr) = 0;
    virtual void destroy(dbdStructPtr ptr) = 0;
    virtual void *indexToAddr(dbdString *errorMessage,
            dbdStructPtr ptr, dbdInt16 index) = 0;
    // ???? is anything else needed
};

/* record support implements the following*/
class dbdRecordSupport {
    virtual void special(dbdRecord *pdbdRecord,
            dbdBoolean  after,
            dbdInt16 nlevels, // number of elements in fieldIndex
            dbdInt16 fieldIndex[] // array of field indices
            ) = 0;
};

---