V4 Design: dbdClass

May 24 2005

Overview

This document describes the C++ class definitions for code that implements the semantics for records created from Database Definitions. The definitions are intended for code that:

• includes header files generated from dbd definitions. Header files are generated from the following dbd definitions:
  • record - Should only be included by record support.
  • struct - Included by code that understands the struct.
  • menu - Included by code that understands the menu.
• does not include the header files.

The following headers files are described:

• dbfTypes.h - Type definitions for field definitions in struct or record> DBD definitions.
• dbdStatements.h - Type definitions for DBD statements.
• dbdInterfaces.h - Type definitions for interfaces related to DBD definitions.

---

dbfTypes

File dbfTypes.h describes types and classes that are used in header files generated from dbd struct or record field definitions.

The following naming conventions are used:

Dbf

any class starting with Dbf describes a non-primitive struct or record field. For example EpicsString describes a field(name,string).

*Dbd*

A class name that has Dbd imbeded in it describes something directly related to a dbd statement. For example LinkDbdSupport describes a dbd link definition.

dbdTypes.h

enum dbfType {
    dbfUnknownT,
    dbfEpicsT,  // an epicsType except epicsUnknownT
    dbfArrayT,
    dbfStructT,
    dbfMenuT,
    dbfEnumT,
    dbfLinkT,
    dbfDeviceT
};

class ArrayDbdDef; //describes a dbd array definition
class StructDbdDef; //describes a dbd struct definition
class MenuDbdDef; //describes a dbd menu definition
class LinkDbd;    //describes dbd link statement
class DeviceDbd;  //describes dbd device statement

// If array type is a known epicsType then EpicsArray
class DbfArray : public EpicsArray {
public:
    dbfType dbftype;
};

// If every field is a known epicsType then EpicsStruct
class DbfStruct {
public:
    StructDbdDef *pStructDbdDef;
    void         *pstorage;
};

class DbfMenu{
public:
    epicsInt16    index;
    MenuDbdDef  *pmenuDef; /* address of global menu */
};

class DbfEnum{
public:
    epicsInt16  index;
    DbfArray  *pchoiceArray; // addr of field that is DbfArray on choices
};

enum LinkDir {
    LinkDirNone,
    LinkDirForward,
    LinkDirIn,
    LinkDirOut,
    LinkDirInOut
};

class DbfLink{ 
public:
    LinkDir   dir;
    LinkDbd   *plinkDef;
    EpicsStruct dataStruct;
};

class DbfDevice{
public:
    LinkDir   dir;
    DeviceDbd *pdeviceDef;
    EpicsStruct dataStruct;
};

Discussion of dbfTypes

The classes defined in dbfTypes together with the definitions from epicsTypes is a complete list of the definitions that appear in header files generated from struct and record dbd definitions.

Epics Types

The types bool,...,string all map to an epicsType.

The type array maps to EpicsArray if the array type maps to an epicsType.

The type struct maps to EpicsStruct only if all fields in the struct map to an epicsType other than epicsUnknownT.

If a record is defined as:

    struct(displayLimits) {
        field(low,double)
        field(high,double)
    }
    record(xxx) extends iocRecord {
        ...
        field(fbool,bool)
        field(foctet,octet)
        ...
        field(ffloat64,float64)
        ...
        field(fstring,string)
        field(darray,array(double[])
        field(displayLimits,struct(displayLimits))
    }

Then the generated header file will be

    class xxxRecord : public iocRecord {
    public:
        epicsBoolean fbool;
        epicsOctet   foctet;
        ...
        epicsFloat64 ffloat64;
        ...
        EpicsString  fstring;
        EpicsArray   darray;
        EpicsStruct  displayLimits;
   };

DbfArray

This is for array fields with a type that is not a standard epicsType, i.e. the epicsType is epicsUnknownT.

If a record definition contains:

    struct(calcInpLink) {
        field(link,link(in))
        field(value,float64)
    }
    record(calc) extends iocRecord {
        ...
        field(inp,array(struct(calcInpLink)[]))
        ...
    }

Then the generated code contains:

    DbfArray inp;

DbfStruct

This is for a struct field that itself has fields that are not a standard epicsType, i.e. the epicsType is epicsUnknownT.

If a record definition contains:

    struct(calcInpLink) {
        field(link,link(in))     // NOT a standard epicsType
        field(value,float64)
    }
    record(calc) extends iocRecord {
        ...
        field(inp,struct(calcInpLink))
        ...
    }

Then the generated code contains:

    DbfArray inp;
    

DbfMenu

DbfMenu> is described as:

    class DbfMenu{
    public:
        epicsInt16    index;
        MenuDbdDef  *pmenuDef;
    };

If a record definition contains

    field(fmenu,menu(name))

Then the generated header file contains

    DbfMenu fmenu;

DbfMenu provides the current menu index and also the menu definition.

DbfEnum

DbfEnum> is described as:

    class DbfEnum{
    public:
        epicsInt16  index;
        DbfArray  *pchoiceArray; // addr of field that is DbfArray on choices
    };

If a record definition contains

    field(fenum,enum)

Then the generated header file contains

    DbfEnum fenum;

pchoiceArray is the address of a field in the same record that is a DbfArray of choices.

DbfLink

DbfLink is described as

    class DbfLink{ 
    public:
        LinkDir   dir;
        LinkDbd   *plinkDef;
        EpicsStruct dataStruct;
    };

If a record definition contains

    field(flink,link(in))

Then the generated header file contains

    DbfLink flink;

The fields of DbfLink are initialized by locating a dbd link definition that matches the dir specified in the dbd field definition.

The fields of DbfLink are initialized as follows:

dir

This is taken from either the field definition or from the LinkDbd definition and is the most restrictive. For example if one says inout and the other says in then dir will be in.

plinkDef

This is the address of the LinkDbd.

dataStruct

The describes the data structure specified in the dbd link definition. It contains data used by the link support.

Note that link support always implements interface LinkDbdSupport

DbfDevice

A DbfDevice is similar to a DbfLink except that the interface implemented by the device support is also specified, i.e. instead of implementing interface LinkDbdSupport, the device support implements an interface that both record support and device support understand.

---

dbdStatements

The classes in dbdStatements.h allow introspection of ioc records. They describe everything defined in DBD definitions.

dbdStatements.h

// Interface is base class for an interface
class Interface {};
class InterfaceLocator {
public:
    EpicsString name;
    Interface *pinterface;
};

class StructFieldAttribute {
    EpicsString  default;
    epicsBoolean readonly;
    epicsBoolean design;
    epicsBoolean special;
    epicsBoolean dynamic;
    epicsInt16 asl;
};

class StructDbdField {
public:
    EpicsString name;
    epicsType   basic;
    dbfType     type;
    StructFieldAttribute *pattribute;
};

class StructDbdDef{
public:
    EpicsString    name;
    Interface    *plifetime; // references a StructLifetime
    epicsInt16     nfields;
    StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
};

class MenuDbdDef{
public:
    EpicsString name;
    epicsInt16  nchoices;
    EpicsString *pchoice[];
};

class LinkDbd{ //describes dbd link statement
public:
    LinkDir    dir;
    EpicsString  choiceName;
    EpicsString  dataStructName;
    Interface  *pinterface;
};

class DeviceDbd { //describes dbd device statement
public:
    LinkDir   dir;
    EpicsString interfaceName;
    EpicsString choiceName;
    EpicsString dataStructName;
    Interface *pinterface;
};

// The following describes a record type
class RecordDbd { // describes a record type
    EpicsString    name;
    Interface    *plifetime; // references a RecordLifetime
    epicsInt16     nfields;
    StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
};

// The following describes a record instance
class UserDbdField {
public:
    EpicsString  name;
    epicsType    type;
    void         *pfield;
    InterfacePtr *pinterface; // userFieldHandler
};

class RecordInstance { // describes a record instance
    EpicsString  name;
    RecordDbd *pRecordDbd;
    void         *precord;     // address of record instance
    UserDbdField *puserField[];
};

Discussion of dbdStatements

StructXXX

The Struct classes describe the fields in a dbd struct or record definition. The classes are : StructDbdDef, StructDbdField,and StructFieldAttribute

The fields of StructDbdDef are:

name

The name of the struct.

plifetime

The address of an implementation of interface StructLifetime. The implementation is automatically generated from the dbd struct statement. See below for a description of the StructLifetime methods.

nfields

The number of fields, e.g. fields in the structure.

pfields

pointer to an array of pointers to StructDbdField.

The fields of StructDbdField are:

name

The name of the field

basic

The epicsType of the field. Unless this is epicsUnknownT generic code is usually provided for accessing the field.

type

The dbfType for the field. Note that unless basic is epicsUnknownT this has the value dbfEpicsT.

pattribute

The address of a StructFieldAttribute for the field

StructFieldAttribute has the attribute values for the field.

Menu

A dbd menu is described by class MenuDbdDef

The fields of MenuDbdDef are:

name

The menu name.

nchoices

The number of menu choices.

pchoice

The address of an array of pointers to EpicsString. Each EpicsString is a choice.

Link and Device

Each dbd link definition has an associated class LinkDbd with fields:

dir

The link direction

choiceName

The name that matches a LinkDbd for a DbfLink instance.

dataStructName

The class name of a DbfStruct for the Interface implementation

pinterface

The address of the Interface implementation. The interface class is LinkDbdSupport

Each dbd device definition has an associated class DeviceDbd with fields:

dir

The link direction

interfaceName

The name of the interface class implemented by the device support

choiceName

The name that matches a DeviceDbd for a DbfDevice instance.

dataStructName

The class name of a DbfStruct for the Interface implementation

pinterface

The address of the Interface implementation.

Record

A record type has an associated class: RecordDbd. The fields of RecordDbd are the same as fields in StructDbdDef except that they refer to a record instead of a structure.

name

The name of the record.

plifetime

The address of an implementation of interface RecordLifetime. The implementation is automatically generated from the dbd record statement. See below for a description of the RecordLifetime methods.

nfields

The number of fields, e.g. fields in the record.

pfields

pointer to an array of pointers to StructDbdField. Each StructDbdField contains the name and type of the fields.

puserField

Address of an array of pointers to UserDbdField.

Record Instance

A record instance has two associated classes:UserDbdField and RecordInstance.

UserDbdField contains information for a user defined field:

name

The name of the user defined field

type

The dbfType for the field.

pfield

Address of storage for field.

pinterface

The address of an implementation of interface userFieldHandler;

The fields of RecordInstance are:

name

The name of the record instance

pRecordDbd

The address of the description of the record type

precord

The address of the record itself.

puserField

The address of a array of pointers to UserDbdField

---

dbdInterfaces

dbdInterfaces describes standard interfaces implemented by code that supports runtime database access.

dbdInterfaces.h

dbdInterfaces.h contains the following:

// For struct definitions that become EpicsStruct fields
// An EpicsStructLifetime interface is automatically generated.

// For struct definitions that become DbfStruct fields
// An StructLifetime interface is automatically generated.
class StructLifetime {
public:
    virtual void allocate(DbfStruct *pDbfStruct) = 0;
    virtual bool initialize(DbfStruct *pDbfStruct) = 0;
    virtual bool finalize(DbfStruct *pDbfStruct) = 0;
    virtual void destroy(DbfStruct *pDbfStruct) = 0;
    virtual void *expose(DbfStruct *pDbfStruct, epicsInt16 index) = 0;
};

// For record definitions an RecordLifetime is automatically generated.
class RecordLifetime {
public:
    virtual void allocate(void *precord) = 0;
    virtual bool initialize(void *precord) = 0;
    virtual bool finalize(void *precord) = 0;
    virtual void destroy(void *precord) = 0;
    virtual void *expose(void *precord, epicsInt16 index) = 0;
};

// every link support module implements the following interface
class LinkDbdSupport {
public:
    virtual void report(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool initialize(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool finalize(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool connect(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool disconnect(epicsfString *errorMessage,
                     iocRecord *precord, DbffLink *pdbfLink) = 0;
    virtual bool get(EpicsString *errorMessage,
                     iocRecord *precord, DbffLink *pdbfLink,
                     dbfType type, void *pfield) = 0;
    virtual bool put(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink,
                     dbfType type, void *pfield) = 0;
};

/* record support implements the following*/
class RecordDbdSupport {
public:
    virtual iocRecord *allocate(EpicsString *errorMessage) = 0;
    virtual bool destroy(EpicsString *errorMessage, iocRecord *precord) = 0;
    virtual bool init(EpicsString *errorMessage,
                     iocRecord *precord, bool firstPass) = 0;
    virtual void special(iocRecord *precord, iocRecord *precord,
            bool  after,
            epicsInt16 nlevels, // number of elements in fieldIndex
            epicsInt16 fieldIndex[] // array of field indices
            ) = 0;
};

class UserFieldHandler {
public:
    virtual bool initialize(EpicsString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
    virtual bool finalize(EpicsString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
    virtual bool process(EpicsString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
};

Discussion of dbdInterfaces

StructLifetime

Every dbd struct and record has an associated StructLifetime interface implementation. A tool is provided that automatically generates the implementation form the dbd definition. StructLifetime has the following fields:

allocate

Creates storage for the struct or record.

initialize

initializes the struct or record

finalize

cleans up but does not free storage

destroy

frees storage

expose

Given an index it returns the address of the storage. Note the the generated header files assign an index to each field.

LinkDbdSupport

This describes the interface implemented by link support.

RecordDbdSupport

This is the interface implemented by record support.

UserFieldHandler

This is the interface implemented by code for user extensible fields.

---

Class Factories

    class DbfStructFactory {
    public:
        static DbfStructLifetime *find(const char *structName);
        static void register(const char *structName,
                             DbfStructDef, *pdef);
    };