Difference between revisions of "V4 Design: dbdClass"

From EPICSWIKI
Line 1: Line 1:
= EPICS: dbdClasses - IOC record =
= EPICS: dbdClasses - IOC record =
June 10 2005  
June 17 2005  


----
----
Line 6: Line 6:


== Overview ==
== Overview ==
UNDER CONSTRUCTION


  </center>
  </center>
Line 134: Line 136:
<tt>DbfArray</tt> is:
<tt>DbfArray</tt> is:


     class DbfArray {
     class DbfArray : protected EpicsArray {
     public:
     public:
         DbfArray(dbfType type = dbfTypeOctet);
         DbfArray(dbfType type = dbfTypeOctet);
         DbfArray(const char *bufferType, epicsInt32 capacity,
         DbfArray(const char *bufferType,
                    dbfType type = 0);
                  dbfType type = dbfTypeOctet, epicsInt32 capacity = 0);
         DbfArray(DbfBufferCreator *creator, epicsInt32 capacity,
         DbfArray(DbfBufferCreator *creator,
                    dbfType type = 0);
                  dbfType type = dbfTypeOctet, epicsInt32 capacity = 0);
         ~DbfArray();
         ~DbfArray();
         epicsOctet setType(dbfType type);
         void setType(dbfType type);
         dbfType getType() const;
         dbfType getType() const;
         void useBuffer(const char *bufferType, epicsInt32 capacity = 0);
         void createBuffer(const char *bufferType, epicsInt32 capacity = 0);
         void useBuffer(DbfBufferCreator *creator, epicsInt32 capacity = 0);
         void createBuffer(DbfBufferCreator *creator, epicsInt32 capacity = 0);
         void destroy();
        DbfBufferCreator *creator() const;
         void destroyBuffer();
         epicsOctet *element(epicsInt32 index);
         epicsOctet *element(epicsInt32 index);
         const epicsOctet *element(epicsInt32 index) const;
         const epicsOctet *element(epicsInt32 index) const;
Line 153: Line 156:
         epicsInt32 put(epicsInt32 offset, epicsInt32 len,
         epicsInt32 put(epicsInt32 offset, epicsInt32 len,
                         const epicsOctet *pfrom);
                         const epicsOctet *pfrom);
 
        bool mutable() const;
         // These are similar to DbfBuffer, measured in elements not octets
         // These are similar to DbfBuffer, measured in elements not octets
        DbfBufferCreator *creator() const;
         void reserve(epicsInt32 capacity);
         void reserve(epicsInt32 capacity);
         epicsInt32 capacity() const;
         epicsInt32 capacity() const;
Line 161: Line 163:
         epicsInt32 size() const;
         epicsInt32 size() const;
         epicsInt32 maxSize() const;
         epicsInt32 maxSize() const;
        bool mutable() const;
         void expose(epicsInt32 offset, epicsInt32 &len,
         void expose(epicsInt32 offset, epicsInt32 &len,
                     epicsOctet *&pdata);
                     epicsOctet *&pdata);
Line 168: Line 169:
     protected:
     protected:
         dbfType type;
         dbfType type;
        EpicsArray *parray;
     private:
     private:
         DbfArray(const DbfArray &);            // No copy constructor
         DbfArray(const DbfArray &);            // No copy constructor
Line 175: Line 175:




In addition the following convenience classes are available .
QUESTIONS:
# should operator = be allowed?
# should EpicsArray provide convience wrappers for basic types
 
In addition convenience classes are available for each dbfType.
They provide a type safe wrapper the has a reference to a DbfArray.
The convience classes are:


     class Int16Array {
     class Int16Array {
     public:
     public:
         Int16Array(DbfArray *parray);
         Int16Array(DbfArray &array);
         Int16Array(DbfArray *parray,
         Int16Array(DbfArray &array,
                     const char *bufferType, epicsInt32 capacity);
                     const char *bufferType, epicsInt32 capacity = 0);
         Int16Array(DbfArray *parray
         Int16Array(DbfArray &array
                     EpicsBufferCreator *creator, epicsInt32 capacity);
                     EpicsBufferCreator *creator, epicsInt32 capacity = 0);
         ~Int16Array();
         ~Int16Array();
         epicsInt16 * element(epicsInt32 index);
        void createBuffer(const char *bufferType, epicsInt32 capacity = 0);
         const epicsInt16 * element(epicsInt32 index) const;
        void createBuffer(DbfBufferCreator *creator, epicsInt32 capacity = 0);
        DbfBufferCreator *creator() const;
         epicsInt16 *element(epicsInt32 index);
         const epicsInt16 *element(epicsInt32 index) const;
         epicsInt32 get(epicsInt32 offset, epicsInt32 len,
         epicsInt32 get(epicsInt32 offset, epicsInt32 len,
                         epicsInt16 *pto) const;
                         epicsInt16 *pto) const;
         epicsInt32 put(epicsInt32 offset, epicsInt32 len,
         epicsInt32 put(epicsInt32 offset, epicsInt32 len,
                         const epicsInt16 *pfrom);
                         const epicsInt16 *pfrom);
 
         bool mutable() const;
         // These are similar to Buffer, measured in elements not octets
         void reserve(epicsInt32 capacity);
         void reserve(epicsInt32 capacity);
         epicsInt32 capacity() const;
         epicsInt32 capacity() const;
Line 203: Line 211:
                     const epicsInt16 *&pdata) const;
                     const epicsInt16 *&pdata) const;
     private:
     private:
         DbfArray *parray;
         DbfArray &array;
         Int16Array(const EpicsInt16Array &);           // No copy constructor
        Int16Array(); // No default constructor
         Int16Array(const EpicsInt16Array &); // No copy constructor
         Int16Array& operator=(const EpicsInt16Array &); // No assignment operator
         Int16Array& operator=(const EpicsInt16Array &); // No assignment operator
     };
     };
Line 219: Line 228:
As an example of how the convience classes are used is:
As an example of how the convience classes are used is:


     Float64Array dbfArray;
    DbfArray  dbfArray;
    ...
     Float64Array floatArray(dbfArray);
 
     epicsFloat64 *pdata = new epicsFloat64[10];
     epicsFloat64 *pdata = new epicsFloat64[10];
     ...
     ...
     dbfArray.put(0,10,pdata);
     floatArray.put(0,10,pdata);
          
          
----
----
Line 247: Line 259:
  </center>
  </center>
<tt>DbfMenu</tt> is described as:
<tt>DbfMenu</tt> is described as:
     struct DbfMenu{
     class DbfMenu{
    public:
        DbfMenu(DbdMenu &menu);
        epicsInt16 nChoices();
        EpicsString &choice() const;
        EpicsString &choice(epicsInt16 index) const;
        epicsInt16 getIndex() const;
        void setIndex(epicsInt16 index) const;
        EpicsEnumChoices &choices() const;
        DbdMenu &menu() const;
    private:
         epicsInt16    index;
         epicsInt16    index;
         DbdMenu  *pmenuDef;
         DbdMenu  &menuDef;
        DbfMenu(); // no default constructor
     };
     };


<tt>DbfMenu</tt> provides the current menu index and also the menu definition.
<tt>DbfMenu</tt> provides the current menu index and also a reference to the associated DbDMenu.
 
Questions
# Is this how we want to do this?


A field of type DbfMenu is automatically initialized by dbLoadRecords.
The constructor for the record type must also construct a DbfMenu.


----
----
Line 262: Line 288:
  </center>
  </center>
<tt>DbfEnum</tt> is described as:
<tt>DbfEnum</tt> is described as:
     struct DbfEnum{
     class DbfEnum{
         epicsInt16 index;
    public:
         DbfArray  *pfield; //EpicsArray of epicsTypeString
        DbfEnum(DbfArray &field);
        epicsInt16 nChoices();
        EpicsString &choice() const;
        EpicsString &choice(epicsInt16 index) const;
        epicsInt16 getIndex() const;
        void setIndex(epicsInt16 index) const;
        EpicsEnumChoices &choices() const;
    private:
         epicsInt16   index;
         EpicsEnumChoices *pEpicsEnumChoices;
        DbfEnum(); // no default constructor
     };
     };


<tt>pfield</tt> is the address of a field in the same record that is a
The only way to create a DbfEnum is to pass it a reference to a field that is
DbfArray of type EpicsString. It contains the choices.
a DbfArray with type EpicsString.
 
A field of type DbfEnum is automatically initialized by dbLoadRecords.


----
----
Line 347: Line 381:
     class Interface {}; // Must be an interface, i.e. pure abstract class
     class Interface {}; // Must be an interface, i.e. pure abstract class


     struct DbdMenu{
     class DbdMenu{
    public:
        DbdMenu(EpicsEnumChoices &choices);
        epicsInt16 nChoices();
        EpicsString &choice(epicsInt16 index);
        EpicsEnumChoices &choices() const { return choices;}
    private:
        ~DbdMenu(); // Who can call this?
         NODE        node; // for DbdBase:menuList
         NODE        node; // for DbdBase:menuList
         EpicsString name;
         EpicsEnumChoices &choices;
         epicsInt16  nchoices;
         DbdMenu(); // No default constructor
        EpicsString *pchoice[];
     };
     };
      
      
     struct DbdLink{ //describes dbd link statement
     class DbdLink{ //describes dbd link statement
    public:
          DbdLink(LinkDir,EpicsString &choice,EpicsString &dataStruct);
          static registerInterface(const EpicsString &choice,LinkDir dir,
                              DbdLinkSupport &support);
          LinkDir dir();
          EpicsString &choiceName();
          EpicsString &dataStructName();
          DbdLinkSupport *pinterface();
    private:
         NODE            node; // For DbdBase:linkList
         NODE            node; // For DbdBase:linkList
         LinkDir        dir;
         LinkDir        dir;
Line 475: Line 524:
=== Discussion of dbdStatements ===
=== Discussion of dbdStatements ===


GENERIC QUESTIONS:
# NODE - how should we handle lists?
==== Menu ====
==== Menu ====


A dbd <tt>menu</tt> is described by <tt>DbdMenu</tt>
A dbd <tt>menu</tt> is described by <tt>DbdMenu</tt>


The fields of DbdMenu are:
The methods of DbdMenu are:
; <tt>node</tt>
; <tt>DbdMenu</tt>
: node for DbdBase:menuList
: The only way to create a DbdMenu is via a reference to the EpicsEnumChoices for the menu. Thus the choices must be created first.
; <tt>name</tt>
; <tt>~DbdMenu</tt>
: The menu name.
: destructor. Who can call this?
; <tt>nchoices</tt>
; <tt>nchoices</tt>
: The number of menu choices.
: returns the number of choices.
; <tt>pchoice</tt>
; <tt>choice</tt>
: The address of an array of pointers to EpicsString. Each EpicsString is a choice.
: returns a reference to the choice.
; <tt>choices</tt>
: returns a reference to the EpicsEnumChoices


QUESTIONS about DbdMenu
# The current definition does not allow the choices to be modified. Is it required that we can change them? Can they be changed AFTER a database is loaded and initialized?
# Who can call destructor?
==== Link ====
==== Link ====



Revision as of 16:04, 17 June 2005

EPICS: dbdClasses - IOC record

June 17 2005


Overview

UNDER CONSTRUCTION

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:

C++ struct vs class
A C++ class is used for a class that has methods and struct is used for a class that has only data.
Dbf
any class starting with Dbf describes a field in a generated header file. For example DbfString describes a field generated from field(name,string).
Dbd
A class name starting with Dbd describes something related to dbd definitions. For example DbdLinkSupport describes a dbd link definition.

dbfTypes.h

Every field in the header files generated from DBD struct and record definitions has one on the following types:


    enum dbfType {
        dbfTypeBoolean,     // epicsBoolean
        dbfTypeOctet,       // epicsOctet
        dbfTypeInt16,       // epicsInt16
        dbfTypeInt32,       // epicsInt32
        dbfTypeInt64,       // epicsInt64
        dbfTypeFloat32,     // epicsFloat32
        dbfTypeFloat64,     // epicsFloat64
        dbfTypeString,      // EpicsString
        dbfTypeArray,       // DbfArray
        dbfTypeMDArray      // DbfMDArray
        dbfMenuT,           // DbfMenu
        dbfEnumT,           // DbfEnum
        dbfLinkT,           // DbfLink
        dbfDeviceT          // DbfDevice
        dbfTypeStruct,      // DbfStruct
    };

Discussion of dbfTypes

DBD type

  • bool,...,string all become an epicsType , i.e. epicsBoolean,...EpicsString
  • array becomes a DbfArray or DbfMDArray.
  • struct becomes a DbfStruct
  • menu becomes DbfMenu
  • enum becomes DbfEnum
  • link becomes DbfLink
  • device becomes DbfDevice


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(fint,int16)
        ...
        field(ffloat,float64)
        field(fstring,string)
        field(array,array(double[])
        field(mdarray,array(double[,])
        field(fmenu,menu(name))
        field(fenum,enum)
        field(flink,link(in))
        field(fdevice,link(in,analogIO))
        field(displayLimits,struct(displayLimits))
    }

Then the generated header file will be

    class xxxRecord : public iocRecord {
    public:
        epicsBoolean fbool;
        epicsOctet   foctet;
        epicsInt16   fint;
        ...
        epicsFloat64 ffloat;
        EpicsString  fstring;
        DbfArray     array;
        DbfMDArray   mdarray;
        DbfMenu      fmenu;
        DbfEnum      fenum;
        DbfLink      flink;
        DbfDevice    fdevice;
        DbfStruct    displayLimits;
   };

epicsTypes

Fields of type epicsBoolean, epicsOctet, epicsInt16, epicsInt32, epicsInt64, epicsFloat32, or epicsFloat64 are all a C++ fundamental type. When a record instance is created these are all initialized to 0.

A field of type EpicsString is initialized via the default constructor for EpicsString, which means that no EpicsBuffer is created. Record support must call createBuffer.


DbfArray

DbfArray is:

    class DbfArray : protected EpicsArray {
    public:
        DbfArray(dbfType type = dbfTypeOctet);
        DbfArray(const char *bufferType,
                  dbfType type = dbfTypeOctet, epicsInt32 capacity = 0);
        DbfArray(DbfBufferCreator *creator,
                  dbfType type = dbfTypeOctet, epicsInt32 capacity = 0);
        ~DbfArray();
        void setType(dbfType type);
        dbfType getType() const;
        void createBuffer(const char *bufferType, epicsInt32 capacity = 0);
        void createBuffer(DbfBufferCreator *creator, epicsInt32 capacity = 0);
        DbfBufferCreator *creator() const;
        void destroyBuffer();
        epicsOctet *element(epicsInt32 index);
        const epicsOctet *element(epicsInt32 index) const;
        epicsInt32 get(epicsInt32 offset, epicsInt32 len,
                       epicsOctet *pto) const;
        epicsInt32 put(epicsInt32 offset, epicsInt32 len,
                       const epicsOctet *pfrom);
        bool mutable() const;
        // These are similar to DbfBuffer, measured in elements not octets
        void reserve(epicsInt32 capacity);
        epicsInt32 capacity() const;
        void resize(epicsInt32 newsize);
        epicsInt32 size() const;
        epicsInt32 maxSize() const;
        void expose(epicsInt32 offset, epicsInt32 &len,
                    epicsOctet *&pdata);
        void expose(epicsInt32 offset, epicsInt32 &len,
                    const epicsOctet *&pdata) const;
    protected:
        dbfType type;
    private:
        DbfArray(const DbfArray &);            // No copy constructor
        DbfArray& operator=(const DbfArray &); // No assignment operator
    };


QUESTIONS:

# should operator = be allowed?
# should EpicsArray provide convience wrappers for basic types

In addition convenience classes are available for each dbfType. They provide a type safe wrapper the has a reference to a DbfArray. The convience classes are:

    class Int16Array {
    public:
        Int16Array(DbfArray &array);
        Int16Array(DbfArray &array,
                   const char *bufferType, epicsInt32 capacity = 0);
        Int16Array(DbfArray &array
                   EpicsBufferCreator *creator, epicsInt32 capacity = 0);
        ~Int16Array();
        void createBuffer(const char *bufferType, epicsInt32 capacity = 0);
        void createBuffer(DbfBufferCreator *creator, epicsInt32 capacity = 0);
        DbfBufferCreator *creator() const;
        epicsInt16 *element(epicsInt32 index);
        const epicsInt16 *element(epicsInt32 index) const;
        epicsInt32 get(epicsInt32 offset, epicsInt32 len,
                       epicsInt16 *pto) const;
        epicsInt32 put(epicsInt32 offset, epicsInt32 len,
                       const epicsInt16 *pfrom);
        bool mutable() const;
        void reserve(epicsInt32 capacity);
        epicsInt32 capacity() const;
        void resize(epicsInt32 newsize);
        epicsInt32 size() const;
        epicsInt32 maxSize() const;
        void expose(epicsInt32 offset, epicsInt32 &len,
                    epicsInt16 *&pdata);
        void expose(epicsInt32 offset, epicsInt32 &len,
                    const epicsInt16 *&pdata) const;
    private:
        DbfArray &array;
        Int16Array(); // No default constructor
        Int16Array(const EpicsInt16Array &); // No copy constructor
        Int16Array& operator=(const EpicsInt16Array &); // No assignment operator
    };
    // The following are like Int16Array except for type
    class OctetArray ;
    class Int32Array ;
    class Int64Array ;
    class Float32Array ;
    class Float64Array ;
    class StringArray ;
    class StructArray ;

As an example of how the convience classes are used is:

    DbfArray  dbfArray;
    ...
    Float64Array floatArray(dbfArray);
    epicsFloat64 *pdata = new epicsFloat64[10];
    ...
    floatArray.put(0,10,pdata);
       

DbfMDArray

DbfMDArray is:

Need something like for DbfArray except that convenience classes will be

    class BasicTypeMDArray;
    class OctetMDArray ;
    class Int32MDArray ;
    class Int64MDArray ;
    class Float32MDArray ;
    class Float64MDArray ;
    

DbfMenu

DbfMenu is described as:

    class DbfMenu{
    public:
        DbfMenu(DbdMenu &menu);
        epicsInt16 nChoices();
        EpicsString &choice() const;
        EpicsString &choice(epicsInt16 index) const;
        epicsInt16 getIndex() const;
        void setIndex(epicsInt16 index) const;
        EpicsEnumChoices &choices() const;
        DbdMenu &menu() const;
    private:
        epicsInt16    index;
        DbdMenu  &menuDef;
        DbfMenu(); // no default constructor
    };

DbfMenu provides the current menu index and also a reference to the associated DbDMenu.

Questions

  1. Is this how we want to do this?

The constructor for the record type must also construct a DbfMenu.


DbfEnum

DbfEnum is described as:

    class DbfEnum{
    public:
        DbfEnum(DbfArray &field);
        epicsInt16 nChoices();
        EpicsString &choice() const;
        EpicsString &choice(epicsInt16 index) const;
        epicsInt16 getIndex() const;
        void setIndex(epicsInt16 index) const;
        EpicsEnumChoices &choices() const;
    private:
        epicsInt16    index;
        EpicsEnumChoices *pEpicsEnumChoices;
        DbfEnum(); // no default constructor
    };

The only way to create a DbfEnum is to pass it a reference to a field that is a DbfArray with type EpicsString.


DbfLink and DbdDevice


DbfLink is described as

    enum LinkDir {
        LinkDirNone,
        LinkDirForward,
        LinkDirIn,
        LinkDirOut,
        LinkDirInOut
    };
   
    struct DbfLink{ 
        LinkDir   dir;
        DbdLink   *plinkDef;
        DbfStruct dataStruct;
    };
   
    struct DbfDevice{
        LinkDir   dir;
        DbdDevice *pDbdDevice;
        DbfStruct dataStruct;
    };

The fields of DbfLink are initialized by dbLoadRecords as follows:

dir
This is taken from either the field definition or from the DbdLink 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 DbdLink.
dataStruct
The describes the data structure specified in the dbd link definition. It contains data used by the link support.

Link support always implements interface DbdLinkSupport

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 DbdLinkSupport, the device support implements an interface that both record support and device support understand.



DbfStruct

DbfStruct is described as

    struct DbfStruct {
        DbdStruct *pdescription;
        void      *pstorage;
    };

The fields of DbfStruct are initialized by dbLoadRecords as follows:

pdescription
This is initialized via the structure name specified in field definition.
pstorage
This is initialized by calling DbdStructLifetime:allocate

dbdStatements

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

NODE and LIST specify a doubly linked list. An implementation is not specified.

dbdStatements.h

    class Interface {}; // Must be an interface, i.e. pure abstract class
    class DbdMenu{
    public:
        DbdMenu(EpicsEnumChoices &choices);
        epicsInt16 nChoices();
        EpicsString &choice(epicsInt16 index);
        EpicsEnumChoices &choices() const { return choices;}
    private:
        ~DbdMenu(); // Who can call this?
        NODE        node; // for DbdBase:menuList
        EpicsEnumChoices &choices;
        DbdMenu(); // No default constructor
    };
   
    class DbdLink{ //describes dbd link statement
    public:
         DbdLink(LinkDir,EpicsString &choice,EpicsString &dataStruct);
         static registerInterface(const EpicsString &choice,LinkDir dir,
                             DbdLinkSupport &support);
         LinkDir dir();
         EpicsString &choiceName();
         EpicsString &dataStructName();
         DbdLinkSupport *pinterface();
    private:
        NODE            node; // For DbdBase:linkList
        LinkDir         dir;
        EpicsString     choiceName;
        EpicsString     dataStructName;
        DbdLinkSupport  *pinterface;
    };
   
    struct DbdDevice { //describes dbd device statement
        NODE        node; // For DbdBase:deviceList
        LinkDir     dir;
        EpicsString choiceName;
        EpicsString dataStructName;
        EpicsString interfaceName;
        Interface   *pinterface;
    };


    // Beginning of definitions for DbdStruct
    struct DbdAttribute {
        EpicsString  default;
        epicsBoolean readonly;
        epicsBoolean design;
        epicsBoolean special;
        epicsBoolean dynamic;
        epicsInt16   asl;
    };
    struct DbdStringDefaults { // defaults for string
        const char *bufferType;
        epicsInt32 capacity;
    };
    struct DbdArrayDefaults { // defaults for array
        dbfType    type;
        const char *bufferType;
        epicsInt32 capacity;
        epicsInt32 nelements;
    };
    struct DbdMDArrayDefaults { // defaults for mdarray
        dbfType    type;
        epicsInt16 ndim
        const char *bufferType;
        epicsInt32 capacity;
    };
    struct DbdStructDefaults { // defaults for struct
        DbdStruct *pdescription;
    };
    struct DbdField {
        const char *name;
        dbfType   type;
        union {
            DbdStringDefaults  *pstring;
            DbdArrayDefaults   *parray;
            DbdMDArrayDefaults *pmdarray;
            DbdStructDefaults  *pstruct;
        } defaults;
        DbdAttribute attribute;
    };
    struct DbdStruct{ // describes a struct
        NODE             node; // for DbdBase:structList
        const char       *name;
        epicsInt16       nfields;
        DbdField         *pafield;//ptr to array of DbdField
        DbdStructLifetime *plifetime;
    };


    struct DbdRecord { // describes a record
        NODE              node; // for DbdBase:recordList
        LIST              instanceList;
        const char        *name;
        epicsInt16        nfields;
        DbdField          *pafield;//ptr to array of DbdField
        DbdRecordSupport  *psupport;
        DbdRecordLifetime *plifetime;
    };
   
    struct DbdUserField{ // describes a dbd userField statement
        NODE                node; // For DbdBase:userFieldList
        EpicsString         choiceName;
        epicsType           type;
        EpicsString         dataStructName;
        DbdUserFieldHandler *pinterface;
    };
   
    // The following describes a record instance
    struct DbdUserFieldInstance {
        NODE         node; // for DbdRecordInstance.userField
        EpicsString  name; // user field name
        dbfType      sourceType;
        void         *psource;
        DbdUserField *pDbdUserField;
        void         *pstorage; // for DbdUserField.type
        DbfStruct    dataStruct;
    };
   
    struct DbdRecordInstance {
        NODE         node; // for DbdRecord.instanceList
        DbdRecord    *pDbdRecord;
        void         *pstorage;
        EpicsString  name;
        LIST         userField; // of DbdUserFieldInstance
    };
   
    struct DbdBase {
        LIST structList;
        LIST recordList;
        LIST menuList;
        LIST linkList;
        LIST deviceList;
        LIST userFieldList;
   };


Discussion of dbdStatements

GENERIC QUESTIONS:

  1. NODE - how should we handle lists?

Menu

A dbd menu is described by DbdMenu

The methods of DbdMenu are:

DbdMenu
The only way to create a DbdMenu is via a reference to the EpicsEnumChoices for the menu. Thus the choices must be created first.
~DbdMenu
destructor. Who can call this?
nchoices
returns the number of choices.
choice
returns a reference to the choice.
choices
returns a reference to the EpicsEnumChoices

QUESTIONS about DbdMenu

  1. The current definition does not allow the choices to be modified. Is it required that we can change them? Can they be changed AFTER a database is loaded and initialized?
  2. Who can call destructor?

Link

A dbd link definition is described by DbdLink

node
This is a node for DbdLinkList
dir
The link direction
choiceName
The name that connects a DbdLink to a DbfLink instance.
dataStructName
The class name of an DbdStruct for the Interface implementation
pinterface
The address of the DbdLinkSupport Interface implementation.

Device

Each dbd device definition is described by DbdDevice

node
This is a node for DbdDeviceList
dir
The link direction
choiceName
The name that matches a DbdDevice to a DbfDevice instance.
dataStructName
The class name of an EpicsStruct for the Interface implementation
interfaceName
The name of the interface type implemented by the device support
pinterface
The address of the Interface implementation.


struct and record

The following describe the fields in a dbd struct or record definition: DbdStruct, DbdRecord, DbdField,and DbdAttribute

The fields of DbdStruct are:

node
node for DbdBase:structList
name
The name of the struct.
nfields
The number of fields, e.g. fields in the structure.
pafields
pointer to an array of DbdField.
plifetime
The address of an implementation of interface DbdStructLifetime. The implementation is automatically generated from the dbd struct. See below for a description of the Lifetime methods.

The fields of DbdRecord are;

node
node for DbdBase:recordList
instanceList
list of instances of this record type
name
The name of the record type.
nfields
The number of fields, e.g. fields in the record.
pafields
pointer to an array of DbdField.
psupport
The address of the DbdRecordSupport for this record type.
plifetime
The address of an implementation of interface DbdRecordLifetime. The implementation is automatically generated from the dbd record statement. See below for a description of the Lifetime methods.


The fields of DbdField are:

name
The name of the field
type
The dbfType of the field.
defaults
a union of default values. The default values depend on the record type definitions. Most types do not have associated default values. Note that these are defaults for the description of the field NOT for values to put in the field.
attribute
DbdAttribute for the field

The fields of DbdAttribute are:

default
An EpicsString providing a default value for the field.
readonly
Is the field readonly?
design
Is the field a design fields for DCTs?
special
Should DbdRecordSupport:special be called if the field is modified.
dynamic
Can the field change because of record processing?
asl
The access security level.

User Defined Fields

Each dbd userField definition has an associated class DbdUserField with fields:

node
This is a node for DbdUserFieldList
choiceName
The name that matches a DbdUserField to a DbdUserFieldInstance
type
The epicsType for the user field
dataStructName
The class name of an EpicsStruct for the DbdUserFieldHandler
pinterface
The address of the DbdUserFieldHandler implementation.

Record Instance

A record instance has two associated classes:DbdUserFieldInstance and DbdRecordInstance.

DbdUserFieldInstance contains information for a user defined field:

node
A node for list DbdRecordInstance.userField
name
The name of the user defined field, i.e. the psuedo field name
sourceType
the type of the field of the record that DbdUserFieldHandler accesses.
psource
The address of the field that DbdUserFieldHandler accesses.
pDbdUserField
The DbdUserField that describes the field
pstorage
Address of storage for the dbfType.
dataStruct
An DbfStruct that holds the private data for the DbdUserFieldHandler.

The fields of DbdRecordInstance are:

node
A node for list DbdRecord.instanceList
pDbdRecord
address of the DbdRecord describing the record
pstorage
address of the storage for the record instance
name
The name of the record instance
userField
DbdUserFieldInstance list for the record instance.

DbdBase

The following provide lists of various things:

structList
The list of each struct definition
recordList
The list of each record type definition
menuList
The list of each menu definition
linkList
The list of each link definition
deviceList
The list of each device definition
userFieldList
The list of each DbdUserField definition

dbdInterfaces

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

dbdInterfaces.h

dbdInterfaces.h contains the following:

// The following is implemented by database access
class DbdFieldPutString {
    virtual void primitive(EpicsString *pfrom, dbfType type,
                              void *pstorage) = 0;
    virtual void string(EpicsString *pfrom,
                              EpicsString *pEpicsString) = 0;
    virtual void array(EpicsString *pfrom,
                              DbfArray *parray) = 0;
    virtual void dbfStruct(EpicsString *pfrom,
                              DbfStruct *pstruct) = 0;
    virtual void dbfMDArray(EpicsString *pfrom,
                              DbfMDArray *parray) = 0;
}
// For struct definitions
// An DbdStructLifetime interface is automatically generated.
class DbdStructLifetime {
public:
    virtual void allocate(DbfStruct &struct) = 0;
    virtual void destroy(DbfStruct &struct) = 0;
    virtual bool initialize(DbfStruct *pDbfStruct) = 0;
    virtual bool finalize(DbfStruct *pDbfStruct) = 0;
    virtual void *exposeField(DbfStruct &struct, epicsInt16 index) = 0;
};
// For record definitions a DbdRecordLifetime is automatically generated.
class DbdRecordLifetime{
public:
    virtual void allocate(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void destroy(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool initialize(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool finalize(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void *exposeField(DbdRecordInstance *pDbdRecordInstance) = 0;
};
// link support modules implement the following interface
class DbdLinkSupport {
public:
    virtual void report(iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool initialize(iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool finalize(iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool connect(iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool disconnect(iocRecord *precord, DbffLink *pdbfLink) = 0;
    virtual bool get(iocRecord *precord, DbffLink *pdbfLink,
                    epicsType type, void *pfield) = 0;
    virtual bool put(iocRecord *precord, DbfLink *pdbfLink,
                     epicsType type, void *pfield) = 0;
};
/* record support implements the following*/
class DbdRecordSupport {
public:
    virtual bool initBuffers(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool initConnections(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool breakConnections(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool process(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void special(DbdRecordInstance *pDbdRecordInstance,
            bool  after,
            epicsInt16 nlevels, // number of elements in fieldIndex
            epicsInt16 fieldIndex[] // array of field indices
            ) = 0;
};
class DbdUserFieldHandler {
public:
    virtual bool initialize(
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
    virtual bool finalize(
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
    virtual bool process(
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
};

Discussion of dbdInterfaces

DbdFieldPutString

This is an interface, which has an implementation provided by iocCore, that convert an EpicsString to an dbfType. The methods are:

primitive
This convert a string to one of the types: epicsBoolean, ..., epicsFloat64
string
Copies an EpicsString to an EpicsString
array
Accepts a string that has the DBD array initialization syntax, locates the string value for each element and calls either DbdFieldPutString:primitive or DbdFieldPutString:string to convert the value and put it into the correct element of DbfArray
dbfStruct
Accepts a string that has the DBD struct initialialization syntax, locates the string value associated with each field and calls primitive, string, or array to convert the value and put the result of the correct field of DbfStruct
dbfMDArray
Accepts a string that has the DBD array initialization syntax, locates the string value for each element and calls either DbdFieldPutString:primitive or DbdFieldPutString:string to convert the value and put it into the correct element of DbfMDArray

DbdStructLifetime and DbdRecordLifetime

Every dbd struct and record has an associated Lifetime interface implementation. A tool is provided that automatically generates the implementation from the dbd definition.

DbdStructLifetime and DbdRecordLifetime each has the following fields:

allocate
Creates storage for the struct or record.
destroy
frees storage
exposeField
Given an index it returns the address of the storage for the field. Note the the generated header files assign an index to each field.
initialize
initializes the struct or record
finalize
cleans up but does not free storage

DbdLinkSupport

This is the interface implemented by the support associated with each DBD link.

DbdLinkSupport has the following methods:

report
generate a report about the link instance
initialize
perform initialization but do not connect
finalize
undo initialization. It is assumed that disconnect has already been called.
connect
connect to external source of data
disconnect
disconnect from external source of data
get
get a value from the external source. type specified the field type and pfield is the address of where to store the data.
put
put a value from the external source. type specified the field type and pfield is the address of where to obtain the data.

DbdRecordSupport

This is the interface implemented by each record support module. DbdRecordSupport has the following methods:

initBuffers
This is called during record initialization. It is responsible for creating the buffers associated with each string and array field. It may call associated support to do the initialization.
initConnections
This is called to connect to external sources. It may call associated support to make the connections.
breakConnections
This is called to disconnect to external sources. It may call associated support to break the connections.
process
Process the record.
special
This is called whenever an external source modifies a field with attribute special set to true.


DbdUserFieldHandler

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

DbdUserFieldHandler has the following fields:

initialize
Initialize the user field.
finalize
undo what was done during initialization
process
Called near the end of record processing just before monitors are handled.

Device Support Interfaces

Multiple interface definitions for device support will be defined. Record Support and device support must agree on which interface type is used for communication.