|
|
| (20 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| == EPICS: C++ class definitions for Database Definition ==
| | This page is obsolete. It is replaced by dbdInterfaces. |
| | |
| May 18 2005
| |
| | |
| <center>
| |
| | |
| == Overview ==
| |
| | |
| </center>
| |
| | |
| 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:
| |
| ** <tt>record</tt> - Should only be included by record support.
| |
| ** <tt>struct</tt> - Included by code that understands the struct.
| |
| ** <tt>menu</tt> - Included by code that understands the menu.
| |
| * does not include the header files.
| |
| | |
| The following headers files are described:
| |
| * <tt>epicsTypes.h</tt> - A set of primitive types that are part of <tt>base/src/libCom</tt>
| |
| * <tt>dbdTypes.h</tt> - Type definitions for <tt>field</tt> definitions in <tt>struct</tt> or <tt>record></tt> DBD definitions.
| |
| * <tt>dbdStatements.h</tt> - Type definitions for DBD statements.
| |
| * <tt>dbdInterfaces.h</tt> - Type definitions for interfaces related to DBD definitions.
| |
| | |
| ----
| |
| <center>
| |
| | |
| == epicsTypes ==
| |
| | |
| </center>
| |
| === <tt>epicsTypes.h</tt> ===
| |
| <tt>epicsTypes.h</tt> defines a set of primitive tupes. It is used because the <tt>C99</tt> standard does not define the exact number of bits for the primitive data types. It only defines the minimum number of bits.
| |
| | |
| In addition two extra types are defined:
| |
| * <tt>epicsUnknownT</tt> - Unknown
| |
| * <tt>epicsOctetT</tt> - An 8 bit byte.
| |
| | |
| <tt>epicsTypes.h</tt> contains the following:
| |
| | |
| enum epicsType {
| |
| epicsUnknownT,
| |
| epicsBooleanT,
| |
| epicsOctetT,
| |
| epicsInt16T,
| |
| epicsUInt16T,
| |
| epicsInt32T,
| |
| epicsUInt32T,
| |
| epicsInt64T,
| |
| epicsUInt64T,
| |
| epicsFloat32T,
| |
| epicsFloat64T,
| |
| };
| |
| | |
| /* some of the following may require OSD definitions*/
| |
| typedef bool epicsBoolean;
| |
| typedef char epicsOctet;
| |
| typedef short epicsInt16;
| |
| typedef unsigned short epicsUInt16;
| |
| typedef int epicsInt32;
| |
| typedef unsigned int epicsUInt32;
| |
| typedef long long epicsInt64;
| |
| typedef unsigned long long epicsUInt64;
| |
| typedef float epicsFloat32;
| |
| typedef double epicsFloat64;
| |
| | |
| === Discussion of epicsTypes ===
| |
| | |
| | |
| Each epicsType maps to a C++ primitive type.
| |
| It may be necessary to provide operating system dependent definitions for some of the types. For example on some architectures a epicsInt64 may have to be defined as a <tt>long</tt> rather than a <tt>long long</tt>.
| |
| | |
| <tt>epicsTypeUnknownT</tt> is reserved for unknown types and will normally be caused by a configuration error.
| |
| | |
| ----
| |
| <center>
| |
| | |
| == dbdTypes ==
| |
| </center>
| |
| | |
| File <tt>dbdTypes.h</tt> describes types and classes related to
| |
| dbd <tt>struct</tt> or <tt>record</tt> field definitions.
| |
| The following naming conventions are used:
| |
| ; dbf
| |
| : A primitive field type
| |
| ; Dbf
| |
| : any class starting with Dbf describes a non-primitive struct or record field. For example DbfString 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.
| |
| | |
| === <tt>dbdTypes.h</tt> ===
| |
| enum dbfType {
| |
| dbfUnknownT = epicsUnknownT,
| |
| dbfBooleanT = epicsBooleanT,
| |
| dbfOctetT = epicsOctetT,
| |
| dbfInt16T = epicsInt16T,
| |
| dbfUInt16T = epicsUInt16T,
| |
| dbfInt32T = epicsInt32T,
| |
| dbfUInt32T = epicsUInt32T,
| |
| dbfInt64T = epicsInt64T,
| |
| dbfUInt64T = epicsUInt64T,
| |
| dbfFloat32T = epicsFloat32T,
| |
| dbfFloat64T = epicsFloat64T,
| |
| dbfStringT,
| |
| dbfStructT,
| |
| dbfArrayT,
| |
| dbfEnumT,
| |
| dbfMenuT,
| |
| dbfLinkT,
| |
| dbfDeviceT
| |
| };
| |
| | |
| typedef epicsBoolean dbfBoolean;
| |
| typedef epicsOctet dbfOctet;
| |
| typedef epicsInt16 dbfInt16;
| |
| typedef epicsUInt16 dbfUInt16;
| |
| typedef epicsInt32 dbfInt32;
| |
| typedef epicsUInt32 dbfUInt32;
| |
| typedef epicsInt64 dbfInt64;
| |
| typedef epicsUInt64 dbfUInt64;
| |
| typedef epicsFloat32 dbfFloat32;
| |
| typedef epicsFloat64 dbfFloat64;
| |
| | |
| // StructDbd is base class for classes implementing struct
| |
| class StructDbd {};
| |
| // The following are described in dbdStatements.h
| |
| 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
| |
| | |
| /*DbfString holds UTF-8 characters*/
| |
| class DbfString {
| |
| public:
| |
| dbfInt32 capacity; /*capacity in bytes*/
| |
| dbfBoolean isCharString;
| |
| dbfOctet *pstorage;
| |
| };
| |
| | |
| class DbfStruct{
| |
| public:
| |
| StructDbdDef *pstructDef;
| |
| StructDbd *pstorage;
| |
| };
| |
| | |
| class DbfArray {
| |
| public:
| |
| dbfInt32 capacity; /*capacity in number of elements*/
| |
| dbfInt32 size; /*current number of elements*/
| |
| dbfType type; // can be dbfBooleanT, ..., dbfArrayT
| |
| void *pstorage; // aligned on natural boundary
| |
| };
| |
| | |
| class DbfMenu{
| |
| public:
| |
| dbfInt16 index;
| |
| MenuDbdDef *pmenuDef; /* address of global menu */
| |
| };
| |
| | |
| class DbfEnum{
| |
| public:
| |
| dbfInt16 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;
| |
| DbfStruct dataStruct;
| |
| };
| |
| | |
| class DbfDevice{
| |
| public:
| |
| LinkDir dir;
| |
| DeviceDbd *pdeviceDef;
| |
| DbfStruct dataStruct;
| |
| };
| |
| | |
| === Discussion of dbdTypes ===
| |
| | |
| ==== Primitive Types ====
| |
| The primitive types, all map directly to an epicsType.
| |
| | |
| If a record is defined as:
| |
| record(xxx) extends iocRecord {
| |
| ...
| |
| field(fbool,bool)
| |
| field(foctet,octet)
| |
| ...
| |
| field(ffloat64,float64)
| |
| ...
| |
| }
| |
| Then the generated header file will be
| |
| class xxxRecord : public iocRecord {
| |
| public:
| |
| dbfBoolean fbool;
| |
| dbfOctet foctet;
| |
| ...
| |
| dbfFloat64 ffloat64;
| |
| ...
| |
| };
| |
| | |
| ==== DbfString ====
| |
| <tt>DbfString</tt> is described as:
| |
| class DbfString {
| |
| public:
| |
| dbfInt32 capacity; /*capacity in bytes*/
| |
| dbfBoolean isCharString;
| |
| dbfOctet *pstorage;
| |
| };
| |
| If a record definition contains
| |
| field(sfield,string)
| |
| Then the generated header file contains
| |
| DbfString sfield;
| |
| | |
| ; <tt>capacity</tt>
| |
| : the the number of bytes referenced by <tt>pstorage</tt> NOT the number of characters.
| |
| ; <tt>isCharString</tt>
| |
| : <tt>false</tt> if the current string can not be converted to a <tt>char</tt>
| |
| array, i.e. it can only be converted to a <tt>wchar_t</tt> array.
| |
| ; <tt>pstorage</tt>
| |
| : the address of a UTF-8 null terminated character string.
| |
| | |
| An interface DbfStringSupport is defined to support DbfString.
| |
| | |
| ==== DbfStruct ====
| |
| | |
| <tt>DbfStruct></tt> is described as:
| |
| class DbfStruct{
| |
| public:
| |
| StructDbdDef *pstructDef;
| |
| StructDbd *pstorage;
| |
| };
| |
| | |
| If a record definition contains
| |
| field(sstruct,struct(name))
| |
| Then the generated header file contains
| |
| DbfStruct sfield;
| |
| <tt>pstorage</tt> is the address of storage for the structure and <tt>pstructDef</tt> is the address of a description of the structure. StructDbdDef is described in <tt>dbdStatatements.h</tt>
| |
| | |
| Note that given a dbdStruct it is possible to locate both the address and description of the associated structure.
| |
| | |
| ==== DbfArray ====
| |
| | |
| A DbfArray describes a 1-dim array of a single dbfType. Multi dimensional
| |
| array can be constructed since a DbfArray can be a 1 dim array of DbfArray.
| |
| | |
| <tt>pstorage</tt> is guaranteed to be allocated on a natural boundary for dbfType.
| |
|
| |
| | |
| ==== DbfMenu ====
| |
| <tt>DbfMenu></tt> is described as:
| |
| class DbfMenu{
| |
| public:
| |
| dbfInt16 index;
| |
| MenuDbfDef *pmenuDef;
| |
| };
| |
| | |
| If a record definition contains
| |
| field(fmenu,menu(name))
| |
| Then the generated header file contains
| |
| DbfMenu fmenu;
| |
| <tt>DbfMenu</tt> provides the current menu index and also the menu definition.
| |
| | |
| ==== DbfEnum ====
| |
| <tt>DbfEnum></tt> is described as:
| |
| class DbfEnum{
| |
| public:
| |
| dbfInt16 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;
| |
| <tt>pchoiceArray</tt> is the address of a field in the same record that is a
| |
| DbfArray of choices.
| |
| ==== DbfLink ====
| |
| <tt>DbfLink</tt> is described as
| |
| class DbfLink{
| |
| public:
| |
| LinkDir dir;
| |
| LinkDbd *plinkDef;
| |
| DbfStruct 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 <tt>link</tt> definition that matches the <tt>dir</tt> specified in the dbd <tt>field</tt> definition.
| |
| | |
| The fields of <tt>DbfLink</tt> are initialized as follows:
| |
| ; <tt>dir</tt>
| |
| : This is taken from either the <tt>field</tt> definition or from the <tt>LinkDbd</tt> definition and is the most restrictive. For example if one says inout and the other says in then <tt>dir</tt> will be in.
| |
| ; <tt>plinkDef</tt>
| |
| : This is the address of the <tt>LinkDbd</tt>.
| |
| ; <tt>dataStruct</tt>
| |
| : The describes the data structure specified in the dbd <tt>link</tt> definition. It contains data used by the link support.
| |
| | |
| Note that link support always implements interface <tt>LinkDbdSupport</tt>
| |
| ==== DbfDevice ====
| |
| | |
| A <tt>DbfDevice</tt> is similar to a <tt>DbfLink</tt> except that the interface implemented by the device support is also specified, i.e. instead of implementing interface <tt>LinkDbdSupport</tt>, the device support implements an interface that both record support and device support understand.
| |
| | |
| | |
| ----
| |
| <center>
| |
| | |
| == dbdStatements ==
| |
| | |
| </center>
| |
| The classes in <tt>dbdStatements.h</tt> allow introspection of ioc records. They describe everything defined in DBD definitions.
| |
| | |
| === <tt>dbdStatements.h</tt> ===
| |
| | |
| | |
| // FieldDbdPtr is the address of storage for a dbfType
| |
| typedef void *FieldDbdPtr;
| |
| | |
| // Interface is base class for an interface
| |
| class Interface {};
| |
| class InterfaceLocator {
| |
| public:
| |
| DbfString name;
| |
| Interface *pinterface;
| |
| };
| |
| | |
| class StructFieldAttribute {
| |
| DbfString default;
| |
| dbfBoolean readonly;
| |
| dbfBoolean design;
| |
| dbfBoolean special;
| |
| dbfBoolean dynamic;
| |
| epicsInt16 asl;
| |
| };
| |
| | |
| class StructDbdField {
| |
| public:
| |
| DbfString name;
| |
| dbfType type;
| |
| StructFieldAttribute *pattribute;
| |
| };
| |
| | |
| class StructDbdDef{
| |
| public:
| |
| DbfString name;
| |
| Interface *plifetime; // references a StructDbdLifetime
| |
| dbfInt16 nfields;
| |
| StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
| |
| };
| |
| | |
| class MenuDbdDef{
| |
| public:
| |
| DbfString name;
| |
| dbfInt16 nchoices;
| |
| DbfString *pchoice[];
| |
| };
| |
| | |
| class LinkDbd{ //describes dbd link statement
| |
| public:
| |
| LinkDir dir;
| |
| DbfString choiceName;
| |
| DbfString dataStructName;
| |
| Interface *pinterface;
| |
| };
| |
| | |
| class DeviceDbd { //describes dbd device statement
| |
| public:
| |
| LinkDir dir;
| |
| DbfString interfaceName;
| |
| DbfString choiceName;
| |
| DbfString dataStructName;
| |
| Interface *pinterface;
| |
| };
| |
| | |
| // The following describes a record type
| |
| class RecordDbdDef { // describes a record type
| |
| DbfString name;
| |
| Interface *plifetime; // references a StructDbdLifetime
| |
| dbfInt16 nfields;
| |
| StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
| |
| };
| |
| | |
| // The following describes a record instance
| |
| class UserDbdField {
| |
| public:
| |
| dbfString name;
| |
| dbfType type;
| |
| FieldDbdPtr pfield;
| |
| InterfacePtr *pinterface; // references userFieldHandler
| |
| };
| |
| | |
| class RecordInstanceDef { // describes a record instance
| |
| DbfString name;
| |
| RecordDbdDef *pRecordDbdDef;
| |
| FieldDbdPtr *precord; // address of record instance
| |
| UserDbdField *puserField[];
| |
| };
| |
| | |
| | |
| === Discussion of dbdStatements ===
| |
| ==== Struct ====
| |
| The Struct classes describe the fields in a dbd <tt>struct</tt> or <tt>record</tt> definition. The classes are : <tt>StructDbdDef</tt>, <tt>StructDbdField</tt>,and <tt>StructFieldAttribute</tt>
| |
| | |
| The fields of <tt>StructDbdDef</tt> are:
| |
| ; <tt>name</tt>
| |
| : The name of the struct.
| |
| ; <tt>plifetime</tt>
| |
| : The address of an implementation of interface <tt>StructDbdLifetime</tt>. The implementation is automatically generated from the dbd <tt>struct</tt> statement. See below for a description of the <tt>StructDbdLifetime</tt> methods.
| |
| ; <tt>nfields</tt>
| |
| : The number of fields, e.g. fields in the structure.
| |
| ; <tt>pfields</tt>
| |
| : pointer to an array of pointers to <tt>StructDbdField</tt>. Each StructDbdField contains the name and type of the fields.
| |
| | |
| The fields of <tt>StructDbdField</tt> are:
| |
| ; <tt>name</tt>
| |
| : The name of the field
| |
| ; <tt>type</tt>
| |
| : The dbfType for the field.
| |
| ; <tt>pattribute</tt>
| |
| : The address of a StructFieldAttribute for the field
| |
| | |
| <tt>StructFieldAttribute</tt> has the attribute values for the field.
| |
| | |
| ==== Menu ====
| |
| | |
| A dbd <tt>menu</tt> is described by class MenuDbdDef
| |
| | |
| The fields of MenuDbdDef are:
| |
| ; <tt>name</tt>
| |
| : The menu name.
| |
| ; <tt>nchoices</tt>
| |
| : The number of menu choices.
| |
| ; <tt>pchoice</tt>
| |
| : The address of an array of pointers to DbfString. Each DbfString is a choice.
| |
| | |
| ==== Link and Device ====
| |
| | |
| Each dbd <tt>link</tt> definition has an associated class <tt>LinkDbd</tt> with fields:
| |
| ; <tt>dir</tt>
| |
| : The link direction
| |
| ; <tt>choiceName</tt>
| |
| : The name that matches a LinkDbd for a DbfLink instance.
| |
| ; <tt>dataStructName</tt>
| |
| : The class name of a DbfStruct for the Interface implementation
| |
| ; <tt>pinterface</tt>
| |
| : The address of the Interface implementation. The interface class is LinkDbdSupport
| |
| | |
| Each dbd <tt>device</tt> definition has an associated class <tt>DeviceDbd</tt> with fields:
| |
| ; <tt>dir</tt>
| |
| : The link direction
| |
| ; <tt>interfaceName</tt>
| |
| : The name of the interface class implemented by the device support
| |
| ; <tt>choiceName</tt>
| |
| : The name that matches a DeviceDbd for a DbfDevice instance.
| |
| ; <tt>dataStructName</tt>
| |
| : The class name of a DbfStruct for the Interface implementation
| |
| ; <tt>pinterface</tt>
| |
| : The address of the Interface implementation.
| |
| | |
| ==== Record ====
| |
| A record type has an associated class: <tt>RecordDbdDef</tt>.
| |
| The fields of <tt>RecordDbdDef</tt> are the same as fields in <tt>StructDbdDef</tt> except that they refer to a record instead of a structure.
| |
| ; <tt>name</tt>
| |
| : The name of the record.
| |
| ; <tt>plifetime</tt>
| |
| : The address of an implementation of interface <tt>StructDbdLifetime</tt>. The implementation is automatically generated from the dbd <tt>record</tt> statement. See below for a description of the <tt>StructDbdLifetime</tt> methods.
| |
| ; <tt>nfields</tt>
| |
| : The number of fields, e.g. fields in the record.
| |
| ; <tt>pfields</tt>
| |
| : pointer to an array of pointers to <tt>StructDbdField</tt>. Each StructDbdField contains the name and type of the fields.
| |
| ; <tt>puserField</tt>
| |
| : Address of an array of pointers to <tt>UserDbdField</tt>.
| |
| | |
| Question? Is RecordDbdDef necessary? Might be good to keep it in case a difference between struct and record becomes necessary.
| |
| | |
| ==== Record Instance ====
| |
| | |
| A record instance has two associated classes:<tt>UserDbdField</tt> and <tt>RecordInstanceDef</tt>.
| |
| | |
| <tt>UserDbdField</tt> contains information for a user defined field:
| |
| ; <tt>name</tt>
| |
| : The name of the user defined field
| |
| ; <tt>type</tt>
| |
| : The dbfType for the field.
| |
| ; <tt>pfield</tt>
| |
| : Address of storage for field.
| |
| ; <tt>pinterface</tt>
| |
| : The address of an implementation of interface userFieldHandler;
| |
| | |
| The fields of <tt>RecordInstanceDef</tt> are:
| |
| | |
| ; <tt>name</tt>
| |
| : The name of the record instance
| |
| ; <tt>pRecordDbdDef</tt>
| |
| : The address of the description of the record type
| |
| ; <tt>precord</tt>
| |
| : The address of the record itself.
| |
| ; <tt>puserField</tt>
| |
| : The address of a array of pointers to UserDbdField
| |
| | |
| ----
| |
| <center>
| |
| | |
| == dbdInterfaces ==
| |
| | |
| dbdInterfaces describes standard interfaces implemented by code that
| |
| supports runtime database access. For some the code is automatically generated from the dbd definitions.
| |
| | |
| </center>
| |
| | |
| === <tt>dbdInterfaces.h</tt> ===
| |
| <tt>dbdInterfaces.h</tt> contains the following:
| |
| | |
| // every struct and every record support module implements the following
| |
| // The implementation is generated from the dbd definition
| |
| class StructDbdLifetime {
| |
| public:
| |
| virtual StructDbdPtr create() = 0;
| |
| virtual bool initialize(dbfString *errorMessage,
| |
| StructDbdPtr ptr) = 0;
| |
| virtual bool finalize(dbfString *errorMessage,
| |
| StructDbdPtr ptr) = 0;
| |
| virtual void destroy(StructDbdPtr ptr) = 0;
| |
| virtual void *indexToAddr(dbfString *errorMessage,
| |
| StructDbdPtr ptr, dbfInt16 index) = 0;
| |
| // ???? is anything else needed
| |
| };
| |
| | |
| // every link support module implements the following interface
| |
| class LinkDbdSupport {
| |
| public:
| |
| virtual void report(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink) = 0;
| |
| virtual bool initialize(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink) = 0;
| |
| virtual bool finalize(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink) = 0;
| |
| virtual bool connect(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink) = 0;
| |
| virtual bool disconnect(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink) = 0;
| |
| virtual bool get(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink,
| |
| dbfType type, FieldDbdPtr pfield) = 0;
| |
| virtual bool put(dbfString *errorMessage,
| |
| iocRecord *precord, dbfLink *pdbfLink,
| |
| dbfType type, FieldDbdPtr pfield) = 0;
| |
| };
| |
| | |
| /* record support implements the following*/
| |
| class RecordDbdSupport {
| |
| public:
| |
| virtual iocRecord *create(dbfString *errorMessage) = 0;
| |
| virtual bool destroy(dbfString *errorMessage, iocRecord *precord) = 0;
| |
| virtual bool init(dbfString *errorMessage,
| |
| iocRecord *precord, bool firstPass) = 0;
| |
| virtual void special(iocRecord *precord, iocRecord *precord,
| |
| bool after,
| |
| dbfInt16 nlevels, // number of elements in fieldIndex
| |
| dbfInt16 fieldIndex[] // array of field indices
| |
| ) = 0;
| |
| };
| |
| | |
| class UserFieldHandler {
| |
| public:
| |
| virtual bool initialize(dbfString *errorMessage,
| |
| iocRecord *precord,UserDbdField *puserField) = 0;
| |
| virtual bool finalize(dbfString *errorMessage,
| |
| iocRecord *precord,UserDbdField *puserField) = 0;
| |
| virtual bool process(dbfString *errorMessage,
| |
| iocRecord *precord,UserDbdField *puserField) = 0;
| |
| };
| |
| | |
| === Discussion of dbdInterfaces ===
| |
| ==== <tt>StructDbdLifetime</tt> ====
| |
| Every dbd <tt>struct</tt> and <tt>record</tt> has an associated <tt>StructDbdLifetime</tt> interface implementation. A tool is provided that automatically generates the implementation form the dbd definition.
| |
| <tt>StructDbdLifetime</tt> has the following fields:
| |
| ; <tt>create</tt>
| |
| : Creates storage for the struct or record.
| |
| ; <tt>initialize</tt>
| |
| : initializes the struct or record
| |
| ; <tt>finalize</tt>
| |
| : cleans up but does not free storage
| |
| ; <tt>destroy</tt>
| |
| : frees storage
| |
| ; <tt>indexToAddr</tt>
| |
| : Given an index it returns the address of the storage. Note the the generated header files assign an index to each field.
| |
| | |
| ==== <tt>LinkDbdSupport</tt> ====
| |
| This describes the interface implemented by link support.
| |
| ==== <tt>RecordDbdSupport</tt> ====
| |
| This is the interface implemented by record support.
| |
| ==== <tt>UserFieldHandler</tt> ====
| |
| This is the interface implemented by code for user extensible fields.
| |
| | |
| ----
| |
| | |
| | |
| <center>
| |
| | |
| == DbfStringSupport Interface ==
| |
| | |
| </center>
| |
| | |
| This describes a proposed interface to support DbfString.
| |
| | |
| The interface is "minimal" in that it provides only a basic set of methods.
| |
| If code needs to do serious character manipulation it must:
| |
| * Use toChar or toWcar to convert a DbfString to an array of char or wchar_t
| |
| * Use standard library support to do character manipulation
| |
| * Use fromChar or fromWchar to convert the result to a DbfString,
| |
| | |
| <tt>DbfString</tt> is defined as:
| |
| class DbfString {
| |
| public:
| |
| dbfInt32 capacity; /*capacity in bytes*/
| |
| dbfBoolean isCharString;
| |
| dbfOctet *pstorage;
| |
| };
| |
| | |
| ; <tt>capacity</tt>
| |
| : is the amount of storage in bytes allocated for pstorage
| |
| ; <tt>isCharString</tt>
| |
| : Is <tt>true</tt> if the UTF_8 null terminated string can be converted
| |
| to a char array. It is false if a wchar_t is required.
| |
| ; <tt>pstorage</tt>
| |
| : Is a null terminated UTF_8 encoded character string.
| |
| | |
| <tt>DbfStringSupport.h</tt> contains:
| |
| | |
| class DbfStringSupport {
| |
| virtual bool allocate(DbfString *pstring, epicsInt32 capacity) = 0;
| |
| virtual null free(DbfString *pstring) = 0;
| |
| virtual bool isCharString(DbfString *pstring) = 0;
| |
| virtual epicsInt32 length(DbfString *p) = 0;
| |
| virtual epicsInt32 length(char *p,epicsInt32 maxsize) = 0;
| |
| virtual epicsInt32 length(wchar_t *p,epicsInt32 maxsize) = 0;
| |
| virtual bool isEqual(DbfString *p1st,DbfString *p2nd) = 0;
| |
| virtual bool toChar(DbfString *pstring,DbfString error,
| |
| char *pcharstring, epicsInt32 maxsize) = 0;
| |
| virtual bool toWChar(DbfString *pstring,DbfString error,
| |
| wchar_t *pcharstring, epicsInt32 maxsize) = 0;
| |
| virtual bool fromChar(DbfString *pstring,
| |
| const char *pcharstring, epicsInt32 maxsize) = 0;
| |
| virtual bool fromWChar(DbfString *pstring,
| |
| wchar_t *pcharstring) = 0;
| |
| };
| |
| | |
| ; <tt>allocate</tt>
| |
| : pstring.pstorage is set equal to the address of capacity bytes of memory.
| |
| pstring.capacity is set equal to the number of bytes.
| |
| pstorage MUST NEVER be allocated by any means other than calling allocate.
| |
| ; <tt>free</tt>
| |
| : The storage referenced by pstring.pstorage is freed.
| |
| pstring.capacity and pstring.pstorage are set to 0.
| |
| ; <tt>length(DbfString *p)</tt>
| |
| : Returns the number of characters in the string.
| |
| ; <tt>length(char *p,epicsInt32 maxsize)</tt>
| |
| : Returns the number of bytes required for a UTF_8 encoded string.
| |
| ; <tt>length(wchar_t *p,epicsInt32 maxsize)</tt>
| |
| : Returns the number of bytes required for a UTF_8 encoded string.
| |
| ; <tt>isEqual</tt>
| |
| : Performs a byte by byte comparison until a null byte is detected or
| |
| capacity of either string is reached. It returns (false,true) if the
| |
| strings (are not, are) equal.
| |
| ; <tt>toChar</tt>
| |
| : Converts a DbfString to a null terminated C char array.
| |
| A return of <tt>true</tt> means success.
| |
| A return of <tt>false</tt> means failure
| |
| and the reason is returned in <tt>error</tt>.
| |
| ; <tt>toWChar</tt>
| |
| : Converts a DbfString to a null terminated C wchar_t array.
| |
| A return of <tt>true</tt> means success.
| |
| A return of <tt>false</tt> means failure
| |
| and the reason is returned in <tt>error</tt>.
| |
| ; <tt>fromChar</tt>
| |
| : Converts a null terminated C char array to a DbfString.
| |
| If the current capacity of pstring is not sufficent, free and allocate
| |
| are called automatically.
| |
| A return of <tt>true</tt> means success.
| |
| A return of <tt>false</tt> means failure
| |
| and the reason is returned in <tt>error</tt>.
| |
| ; <tt>fromWChar</tt>
| |
| : Converts a null terminated C wchar_t array to a DbfString.
| |
| The result is a UTF_8 encode string.
| |
| If the current capacity of pstring is not sufficent, free and allocate
| |
| are called automatically.
| |
| A return of <tt>true</tt> means success.
| |
| A return of <tt>false</tt> means failure
| |
| and the reason is returned in <tt>error</tt>.
| |
| | |
| | |
| Questions:
| |
| * Is one implementation of DbfStringSupport sufficient or is a separate implementation required for each locale?
| |
| * Hopefully only one implementation is required. But then are the above arguments sufficient.
| |
| | |
| ----
| |
| <center>
| |
| | |
| == Example of Generated Header Files ==
| |
| | |
| </center>
| |
| | |
| === Database Definition Files ===
| |
| | |
| <tt>menuAlarmSevr.dbd</tt> contains:
| |
| menu(menuAlarmSevr) {
| |
| choice(menuAlarmSevrNO_ALARM,"NO_ALARM")
| |
| choice(menuAlarmSevrMINOR,"MINOR")
| |
| choice(menuAlarmSevrMAJOR,"MAJOR")
| |
| choice(menuAlarmSevrINVALID,"INVALID")
| |
| }
| |
| | |
| <tt>displayLimit.dbd</tt> contains:
| |
| struct(displayLimit) {
| |
| field(low,float64)
| |
| field(high,float64)
| |
| }
| |
| <tt>exampleRecord.dbd</tt> contains:
| |
| record(example) extends iocRecord {
| |
| field(value,float64)
| |
| field(displayLimit,struct(displayLimit))
| |
| }
| |
| <tt>alltypesRecord.dbd</tt> 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 ===
| |
| Tools are provided to generate header files from the following dbd definitions:
| |
| *menu
| |
| *struct
| |
| *record
| |
| <tt>menuAlarmSevr.h</tt> is generated from <tt>menuAlarmSevr.dbd</tt>
| |
| enum menuAlarmSevr {
| |
| menuAlarmSevrNO_ALARM,
| |
| menuAlarmSevrMINOR,
| |
| menuAlarmSevrMAJOR,
| |
| menuAlarmSevrINVALID
| |
| };
| |
| <tt>displayLimit.h</tt> is generated from <tt>displayLimit.dbd</tt>
| |
| class displayLimit : public StructDbd {
| |
| public:
| |
| dbfFloat64 low;
| |
| dbfFloat64 high;
| |
| };
| |
| const dbfInt16 displayLimit_firstIndex = 1
| |
| const dbfInt16 displayLimit_low = 1
| |
| const dbfInt16 displayLimit_high = 2
| |
| const dbfInt16 displayLimit_lastIndex =displayLimit_high
| |
| <tt>exampleRecord.h</tt> is generated from <tt>exampleRecord.dbd</tt>
| |
| class exampleRecord : public iocRecord{
| |
| public:
| |
| dbfFloat64 value;
| |
| dbfStruct displayLimit;
| |
| };
| |
|
| |
| const dbfInt16 example_firstIndex = 1001001
| |
| const dbfInt16 example_low = 1001001;
| |
| const dbfInt16 example_high = 1001002;
| |
| const dbfInt16 example_lastIndex = example_high;
| |
| <tt>alltypesRecord.h</tt> is generated from <tt>alltypesRecord.dbd</tt>
| |
| class allTypesRecord : public iocRecord{
| |
| public:
| |
| dbfBoolean fbool;
| |
| dbfOctet foctet;
| |
| dbfInt16 fint16;
| |
| dbfUInt16 fuint16;
| |
| dbfInt32 fint32;
| |
| dbfUInt32 fuint32;
| |
| dbfInt64 fint32;
| |
| dbfUInt64 fuint32;
| |
| dbfFloat32 ffloat32;
| |
| dbfFloat64 ffloat64;
| |
| dbfString fstring;
| |
| dbfMenu fmenu;
| |
| dbfEnum fenum
| |
| dbfStruct fstruct;
| |
| dbfLink flink;
| |
| dbfDevice fdevice;
| |
| };
| |
|
| |
| const dbfInt16 allTypes_firstIndex = 1001001
| |
| const dbfInt16 allTypes_fbool = 1001001;
| |
| const dbfInt16 allTypes_foctet = 1001002;
| |
| const dbfInt16 allTypes_fint16 = 1001003;
| |
| const dbfInt16 allTypes_fuint16 = 1001004;
| |
| const dbfInt16 allTypes_fint32 = 1001005;
| |
| const dbfInt16 allTypes_fuint32 = 1001006;
| |
| const dbfInt16 allTypes_fint64 = 1001007;
| |
| const dbfInt16 allTypes_fuint64 = 1001008;
| |
| const dbfInt16 allTypes_ffloat32 = 1001009;
| |
| const dbfInt16 allTypes_ffloatn64 = 10010010;
| |
| const dbfInt16 allTypes_ffstring = 10010011;
| |
| const dbfInt16 allTypes_fmenu = 10010012;
| |
| const dbfInt16 allTypes_fenum = 10010013;
| |
| const dbfInt16 allTypes_fstruct = 10010014;
| |
| const dbfInt16 allTypes_flink = 10010015
| |
| const dbfInt16 allTypes_fdevice = 10010016
| |
| const dbfInt16 allTypes_lastIndex = allTypes_fdevice;
| |
| | |
| ----
| |
