Difference between revisions of "V4 Design: dbdInterfaces"

From EPICSWIKI
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
EPICS: dbdInterfaces - IOC Database Description November 02 2005  
EPICS: dbdInterfaces - IOC Database Description November 04 2005  


----
----
Line 12: Line 12:
a running IOC database.
a running IOC database.


The definitions can be used by code that use code automatically
The definitions can be used by support code, e.g. record support,
generated from DBD files or by code that uses only introspection.
or by code that uses only introspection.


Code is automatically generated from the following definitions:
Code is automatically generated from the following definitions:
Line 148: Line 148:
when the data is transfered to/from the network.
when the data is transfered to/from the network.


An example of a definition that includes a string argument is
If a string is being passed to a method the syntax is:
     void get(String name);
    void put(string value);
In C++ this becomes
    void put(int valueLength, char *value);
In Java it becomes
     void put(String value);


In C++ this will become
If a method is returning a string the syntax is
     void get(int lenName, char *name);
    string get();
In Java this will become
In C++ this becomes
     void get(String name);
     int getValueLength();
    int get(int valueLength, char *value);
    // valueLength is number of octets in value
    // return value is the number of octets written
In Java it becomes
     String get();
=== array ===
=== array ===


Line 161: Line 170:
     void get(float64[] data);
     void get(float64[] data);


In C++ ,this would become:
In C++ this would become:


     void get(int lenData, double data[]);
     void get(int lenData, double data[]);
Line 210: Line 219:
         dbfTypeTimeStamp    // DbfTimeStamp
         dbfTypeTimeStamp    // DbfTimeStamp
     }
     }


----
----
Line 302: Line 309:


     interface DbfString extends Dbf {
     interface DbfString extends Dbf {
         int32 getLength();
         string get();
        void get(string value);
        void setPutSize(int32 size);
         void put(string value);
         void put(string value);
     }
     }
Line 311: Line 316:


     ExampleRecord record;
     ExampleRecord record;
     String string;
     String string = record.fstring.get();
    record.fstring.get(string);
     printf("%s\n",string);
     printf("%s\n",string);
or more concisely
    printf("%s\n",record.fstring.get());


Code that does not include the header file can use the introspection methods
Code that does not include the header file can use the introspection methods
Line 331: Line 337:
      
      
     for(i=0; i < dbfStruct.getNfields(); i++) {
     for(i=0; i < dbfStruct.getNfields(); i++) {
         DbdField dbdField = dbfStruct.getDescription(i);
         DbdField dbdField = dbfStruct.getDescription[i];
         String name;
         String name = dbdField.getName();
        dbdField.getName(name);
         printf("field %s\n",name);
         printf("field %s\n",name);
        // or just
        printf("field %s\n",dbfStruct.getDescription[i].dbdField.getName());
     }
     }


Line 432: Line 440:
     ...
     ...
     DbfConvertPrimitive.put(precord.array,new double[] {1.0,2.0,3.0});
     DbfConvertPrimitive.put(precord.array,new double[] {1.0,2.0,3.0});
For the primitive data types both get and put return an int32,
which is the number of array elements transfered.
The caller <b>must</b> be prepared to make multiple calls
in order to get or put an entire array.
For example
    DbfDoubleArray dbfarray;
    ...
    double[] data = double [dbfArray.getNelements];
    int offset=0;
    int len = data.length;
    int n;
    while(offset < len) {
        n = dbfarray.get(offset,len);
        if(n==len) break;
        len -= n;
        offset += n;
    }




Line 474: Line 500:
     interface DbfLink extends Dbf {
     interface DbfLink extends Dbf {
         DbdLink getDbdLink();
         DbdLink getDbdLink();
        DbfStruct getSupportStruct();
     }
     }
Where
* <tt>getDbdLink</tt> gets the link definition for the field
* <tt>getSupportStruct</tt> get a struct instance for the support structure. Thius is NOT a field in the record but appears like it is.


== DbfTimeStamp ==
== DbfTimeStamp ==
Line 499: Line 529:


     interface DbdMenu {
     interface DbdMenu {
         int32 getNameLength(
         string getName();
        void getName(String name);
         int16 getNchoices();
         int16 getNchoices();
         int32 getChoiceNameLength(int16 index);
         string getChoice(int16 index);
        void getChoice(int16 index,String choice);
     }
     }


Line 511: Line 539:


     interface DbdSupport {
     interface DbdSupport {
         int32 getChoiceNameLength();
         string getChoiceName();
        void getChoiceName(String name);
         string getSupportStructName(string name);
        int32 getSupportStructNameLength();
         void getSupportStructName(String name);
     }
     }
      
      
Line 520: Line 546:


     interface DbdAttribute {
     interface DbdAttribute {
         int32 getDefaultLength();
         string getDefault();
        void getDefault(String value);
         boolean isReadonly();
         boolean isReadonly();
         boolean isDesign();
         boolean isDesign();
Line 540: Line 565:
     interface DbdField {
     interface DbdField {
         int32 getNameLength();
         int32 getNameLength();
         void getName(String name);
         string getName();
         DbfType getType();
         DbfType getType();
         DbdDefaults getDefaults();
         DbdDefaults getDefaults();
Line 547: Line 572:


     interface DbdStruct {
     interface DbdStruct {
         int32 getNameLength();
         string getName();
        void getName(String name);
         int16 getNumberFields();
         int16 getNumberFields();
         DbdField getFieldDescription(int16 index);
         DbdField getFieldDescription(int16 index);
Line 554: Line 578:


     interface DbdRecord {
     interface DbdRecord {
         int32 getNameLength();
         string getName();
        void getName(String name);
         int16 getNumberFields();
         int16 getNumberFields();
         DbdField getFieldDescription(int16 index);
         DbdField getFieldDescription(int16 index);
Line 563: Line 586:


     interface RecordInstance {
     interface RecordInstance {
         int32 getNameLength();
         string getName();
        void getName(String name);
         DbdRecord getDescription();
         DbdRecord getDescription();
         DbfStruct getInstance();
         DbfStruct getInstance();
         Dbf getField(String fieldName);
         Dbf getField(string fieldName);
         Dbf getField(int16 index)
         Dbf getField(int16 index)
     }
     }


; <tt>getNameLength</tt>
: get length of record name
; <tt>getName</tt>
; <tt>getName</tt>
: get the record name
: get the record name
; <tt>getDescription</tt>
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
: get the description of the record specific portion of the record
; <tt>getRecordCommonDescription</tt>
: get the description of RecordCommon
; <tt>getInstance</tt>
; <tt>getInstance</tt>
: get instance for the record specific portion of the record
: get instance for the record specific portion of the record
; <tt>getRecordCommonInstance</tt>
: get instance for for RecordCommon portion of the record
; <tt>getField</tt>
; <tt>getField</tt>
: get field instance.
: get field instance.
Line 612: Line 628:


     public class RecordInstanceLocate {
     public class RecordInstanceLocate {
         public RecordInstance getRecord(String name);
         public RecordInstance getRecord(string name);
         public Dbf getField(String name);
         public Dbf getField(string name);
         public Dbf getField(String recordName, String fieldName);
         public Dbf getField(string recordName, string fieldName);
         public LinkedList<RecordInstance> instanceList;
         public LinkedList<RecordInstance> instanceList;
         public LinkedList<RecordInstance> instanceList(String recordTypeName);
         public LinkedList<RecordInstance> instanceList(string recordTypeName);
     }
     }


Line 636: Line 652:
     if(addr!=null) printf("found %s\n","example.value");
     if(addr!=null) printf("found %s\n","example.value");


----
<center>
= Generated Code =
</center>
The example code shown below uses Java syntax.
It assumes the following definitions:
    struct(DisplayLimit) {
        field(low,double)
        field(high,double)
    }
    record(Example) {
        ...
        field(octet,octet)
        field(fboolean,boolean)
        field(fint,int16)
        ...
        field(ffloat,float64)
        field(string,string)
        field(array,array(double[])
        field(mdarray,array(double[,])
        field(menu,menu(name))
        field(fenum,enum)
        field(link,link)
        field(displayLimit,struct(DisplayLimit))
    }
From this the following Java code is automatically generated.
    public class DisplayLimit implements Struct{
        public DbfFloat64 low;
        public DbfFloat64 high;
        ...
        Dbf getField(short index) {
            switch(index) {
                case lowIndex: return(low);
                case highIndex: return(high);
                default: throw java.lang.IllegalStateException;
            }
            return null;
        }
    }
    public class ExampleRecord implements Struct {
        ...
        public DbfOctet    ctet;
        public DbfBoolean  fboolean;
        public DbfInt16    fint;
        ...
        public DbfFloat64  ffloat;
        public DbfString    string;
        public DbfArray    array;
        public DbfMDArray  mdarray;
        public DbfMenu      menu;
        public DbfEnum      fenum;
        public DbfLink      link;
        public DbfStruct    displayLimit;
        Dbf getField(short index) {
            switch(index) {
                case fbooleanIndex : return(fboolean);
                ...
                case displayLimitIndex: return(displayLimit);
                default: throw java.lang.IllegalStateException;
            }
        }
    }
Similar code is generated for C++.
----
----

Latest revision as of 15:25, 4 November 2005

EPICS: dbdInterfaces - IOC Database Description November 04 2005


Overview

This document describes definitions for code that accessses IOC records, i.e. the records created from Database Definitions: menu, struct, record, link, device, and record instances.

The interfaces support introspection of everything created from Database Definitions. The interfaces can be used by tools such as VDCT or on a running IOC database.

The definitions can be used by support code, e.g. record support, or by code that uses only introspection.

Code is automatically generated from the following definitions:

  • record - Used by record support.
  • struct - Used by code that understands the struct.
  • menu - Used by code that understands the menu.

Syntax

The syntax is defined so that either C++ and Java implementations can be created.

NOTE: Most of the code fragments use Java syntax.

Primitive Types

  • octet - 8 bit byte
  • boolean - a value that takes the values true or false
  • int16 - 16 bit signed integer
  • int32 - 32 bit signed integer
  • int64 - 64 bit signed integer
  • float32 - 32 bit IEEE float
  • float64 - 64 bit IEEE float

In Java these types become:

  • octet => byte BUT no arithmetic is implied
  • boolean => boolean
  • int16 => short
  • int32 => int
  • int64 => long
  • float32 => float
  • float64 => double

In C++ these types become:

  • octet => char BUT no arithmetic is implied
  • boolean => bool BUT no arithmetic or conversion to/from int is implied
  • int16 => int16_t
  • int32 => int32_t
  • int64 => int64_t
  • float32 => float
  • float64 => double

NOTE:

  • The C++ integer types are from C99 stdint.h
  • Should exceptions be defined?

enum, struct, interface, class, string, array

In adition to the primitive types the syntax uses the terms enum, struct, interface, and array.

enum

An example of an enum is:

    enum LinkDir {
        LinkDirNone,
        LinkDirProcess,
        LinkDirIn,
        LinkDirOut,
        LinkDirInOut
    }

The C++ definition is identical. In Java 5 the definition would be:

    public enum LinkDir {
        LinkDirNone,
        LinkDirProcess,
        LinkDirIn,
        LinkDirOut,
        LinkDirInOut
    };

struct

An example of a struct definition is:

    struct DisplayLimitData {
        float64 low;
        float64 high;
    }

In C++ this would be:

   class DisplayLimitData {
   public:
        double low;
        double high;
    };

In Java this would be:

    class DisplayLimitData {
        public double low;
        public double high;
    }

interface

An example of an interface definition is:

    interface DbfBoolean extends Dbf {
        boolean get();
        void    put(boolean val);
    }

In C++ would be:

    class DbfBoolean : public Dbf {
    public:
        virtual bool get() = 0;
        virtual void put(bool val) = 0;
    };

In Java would be:

    interface DbfBoolean extends Dbf {
        boolean get();
        void    put(boolean val)
    }

class

Any class definitions are language specific.

string

For C++ a string will be a char * array containing UTF-8 compatible characters not necessarily terminated with a null character. Wherever a string argument appears, the C++ definition will have len and char * arguments.

For Java string will just be a String. It is assumed that Java Strings will be converted to/from UTF-8 byte streams when the data is transfered to/from the network.

If a string is being passed to a method the syntax is:

    void put(string value);

In C++ this becomes

    void put(int valueLength, char *value);

In Java it becomes

    void put(String value);

If a method is returning a string the syntax is

    string get();

In C++ this becomes

    int getValueLength();
    int get(int valueLength, char *value);
    // valueLength is number of octets in value
    // return value is the number of octets written

In Java it becomes

    String get();

array

An example of a definition that includes an array is:

    void get(float64[] data);

In C++ this would become:

    void get(int lenData, double data[]);

In Java this would be:

    void get(double[] data);

DbfTypes

The following naming conventions are used:

Dbf
any class starting with Dbf describes a field in a header file generated from a struct or record definition. For example DbfArray describes a field generated from field(name,array(float64[]).
Dbd
A class name starting with Dbd describes something related to dbd definitions. For example DbdMenu describes a dbd menu definition.

All Dbf and Dbd definitions are interfaces. Thus all access to data is via interfaces.

DbfTypes.h

The following enum definitions describe each field in the header files generated from DBD struct and record definitions.

    enum BasicType {
        basicTypeOctet,    // DbfOctet
        basicTypeBoolean,  // DbfBoolean
        basicTypeInt16,    // DbfInt16
        basicTypeInt32,    // DbfInt32
        basicTypeInt64,    // DbfInt64
        basicTypeFloat32,  // DbfFloat32
        basicTypeFloat64,  // DbfFloat64
        basicTypeString,   // DbfString
        basicTypeArray,    // DbfArray
        basicTypeStruct,   // DbfStruct
    }
    enum DbfType {
        dbfTypeBasic,       // DbfOctet,...,DbfStruct
        dbfTypeMenu,        // DbfMenu
        dbfTypeEnum,        // DbfEnum
        dbfTypeLink,        // DbfLink
        dbfTypeMDArray,     // DbfMDArray
        dbfTypeTimeStamp    // DbfTimeStamp
    }

Database Fields

Each database field is accessed via an interface which all extend the following interface:

    interface Dbf{
        DbfType getType();
        boolean isPrimitive(); // BasicTypeBoolean,...,BasicTypeFloat64
        boolean isBasic();
        BasicType getBasicType();
        RecordInstance getRecord();
        int16 getIndex();
    }

The interfaces are designed so that a field can be accessded without exposing the address of its data.

Primitive Types

DbfOctet, ..., DbfFloat64 are all interfaces with methods get and put.

    interface DbfOctet extends Dbf {
        octet get();
        void put(octet val);
    }
    interface DbfBoolean extends Dbf {
        boolean get();
        void put(boolean val);
    }
   
    interface DbfInt16 extends Dbf {
        int16 get();
        void put(int16 val);
    }
   
    interface DbfInt32 extends Dbf {
        int32 get();
        void put(int32 val);
    }
   
    interface DbfInt64 extends Dbf {
        int64 get();
        void put(int64 val);
    }
   
    interface DbfFloat32 extends Dbf {
        float32 get();
        void put(float32 val);
    }
   
    interface DbfFloat64 extends Dbf {
        float64 get();
        void put(float64 val);
    }


Record support code can access such fields via the generated header file. Some examples are:

    ExampleRecord record;
    ...
    precord.ffloat.put(10.0);
    ...
    short myint = record.fint.get();

Code that does not include the generated header file can access these fields via the introspection interfaces described later in this document. For example code that expects a float64 field can access it via

    Dbf dbf =  RecordInstanceLocate.getField("recordname.value");
    if(dbf==null
    || !dbf.isPrimitive()
    || (dbf.getBasicType() != basicTypeFloat64) ) // do something
    DbfFloat64 dbfdouble = (DbfFloat64)dbf;
    dbfdouble.put(10.0);

or more concisely (but exception may be thrown)

    DbfConvertPrimitive(RecordInstanceLocate.getField("recordname.value"),10.0);

String fields

The interface for a string field is:

    interface DbfString extends Dbf {
       string get();
       void put(string value);
    }

The following code prints a string.

    ExampleRecord record;
    String string = record.fstring.get();
    printf("%s\n",string);

or more concisely

    printf("%s\n",record.fstring.get());

Code that does not include the header file can use the introspection methods to locate the DbfString that provides access to the field.

Structure Fields

    interface DbfStruct extends Dbf {
        int16 getNfields();
        Dbf getInterface(int16 index);
        DbdField getDescription(int16 index);
    }

The following traverses the fields of a DbfStruct

    DbfStruct dbfStruct;
    
    for(i=0; i < dbfStruct.getNfields(); i++) {
        DbdField dbdField = dbfStruct.getDescription[i];
        String name = dbdField.getName();
        printf("field %s\n",name);
        // or just
        printf("field %s\n",dbfStruct.getDescription[i].dbdField.getName());
    }


Structure fields can only be accessed via introspection. However, for each structure, code is generated that does the introspection. For example DisplayLimitData can be obtained via the statements:

    ExampleRecord record;
    DisplayLimitData limit = new DisplayLimitData();
    
    ...
    DisplayLimitSupport.get(record.displayLimit,limit);
    printf("low %f high %f\n",limit.low,limit.high);

Array Fields

The generated header file will have a type that extends DbfArray

    interface DbfArray extends Dbf {
       DbfType getType();
       int32 getNelements();
       void setNelements(int32 len);
    }
    interface DbfBooleanArray extends DbfArray {
       int32 get(int32 offset, int32 len, boolean[] pto);
       int32 put(int32 offset, int32 len, boolean[] pfrom);
    }
    interface DbfOctetArray extends DbfArray {
       int32 get(int32 offset, int32 len, octet[] pto);
       int32 put(int32 offset, int32 len, octet[] pfrom);
    }
    interface DbfInt16Array extends DbfArray {
       int32 get(int32 offset, int32 len, int16[] pto);
       int32 put(int32 offset, int32 len, int16[] pfrom);
    }
    interface DbfInt32Array extends DbfArray {
       int32 get(int32 offset, int32 len, int32[] pto);
       int32 put(int32 offset, int32 len, int32[] pfrom);
    }
    interface DbfInt64Array extends DbfArray {
       int32 get(int32 offset, int32 len, int64[] pto);
       int32 put(int32 offset, int32 len, int64[] pfrom);
    }
    interface DbfFloat32Array extends DbfArray {
       int32 get(int32 offset, int32 len, float32[] pto);
       int32 put(int32 offset, int32 len, float32[] pfrom);
    }
    interface DbfFloat64Array extends DbfArray {
       int32 get(int32 offset, int32 len, float64[] pto);
       int32 put(int32 offset, int32 len, float64[] pfrom);
    }
    interface DbfStringArray extends DbfArray {
        DbfString getInterface(int32 index);
    }
    interface DbfArrayArray extends DbfArray {
        DbfArray getInterface(int32 index);
    }
    interface DbfStructArray extends DbfArray {
        DbfStruct getInterface(int32 index);
    }
    interface DbfMenuArray extends DbfArray {
        DbfMenu getInterface(int32 index);
    }
    interface DbfEnumArray extends DbfArray {
        DbfEnum getInterface(int32 index);
    }
    interface DbfLinkArray extends DbfArray {
        DbfLink getInterface(int32 index);
    }

The following puts data into a float64 field.

    ExampleRecord record;
    double[] data = new double[] {1.0,2.0,3.0};;
    if(!record.ffloat.isPrimitive()
    || record.ffloat.getBasicType()!=basicTypeFloat64)  // DO SOMTHING!!!!
    ...
    array.put(0,nelements,precord->data);

or more concisely

    ExampleRecord record;
    ...
    DbfConvertPrimitive.put(precord.array,new double[] {1.0,2.0,3.0});

For the primitive data types both get and put return an int32, which is the number of array elements transfered. The caller must be prepared to make multiple calls in order to get or put an entire array.

For example

    DbfDoubleArray dbfarray;
    ...
    double[] data = double [dbfArray.getNelements];
    int offset=0;
    int len = data.length;
    int n;
    while(offset < len) {
        n = dbfarray.get(offset,len);
        if(n==len) break;
        len -= n;
        offset += n;
    }


DbfMDArray

NOT YET DEFINED


DbfMenu

DbfMenu is described as:

    interface DbfMenu extends Dbf {
        int16 getIndex();
        void putIndex(int16 val);
        DbdMenu getDbdMenu();
    }

DbfMenu allows the menu index to be set and retrieved and also provides access to the DbdMenu.

A DbfMenu field can be accessed via the generated header file or via the introspection methods.


DbfEnum

DbfEnum is described as:

    interface DbfEnum extends Dbf {
        int16 getIndex();
        void putIndex(int16 val);
        DbfStringArray getChoiceArray();
    }


DbfEnum allows the enum index to be set and retrieved and also provides access to the The DbfArray field that contains the choices.

DbfLink

DbfLink is described as

    interface DbfLink extends Dbf {
        DbdLink getDbdLink();
        DbfStruct getSupportStruct();
    }

Where

  • getDbdLink gets the link definition for the field
  • getSupportStruct get a struct instance for the support structure. Thius is NOT a field in the record but appears like it is.

DbfTimeStamp

    struct TimeStamp {
        int64 secondsSinceEpoch;
        int32 nanoSeconds;
    }
    interface DbfTimeStamp extends Dbf {
        void get(TimeStamp timeStamp);
        void put(TimeStamp timeStamp);
    }

DbdStatements

These describe everything defined in database definition files.

DbdMenu

    interface DbdMenu {
        string getName();
        int16 getNchoices();
        string getChoice(int16 index);
    }


DbdSupport

    interface DbdSupport {
        string getChoiceName();
        string getSupportStructName(string name);
    }
   

DbdStruct and DbdRecord

    interface DbdAttribute {
        string getDefault();
        boolean isReadonly();
        boolean isDesign();
        boolean isSpecial();
        int16 getAsl();
    }
   
    interface DbdDefaults {}
   
    interface DbdArrayDefaults extends DbdDefaults{
        DbfType getType();
        int32 getLength();
    interface DbdStructDefaults extends DbdDefaults{
        DbdStruct getDescription();
    }
    interface DbdField {
        int32 getNameLength();
        string getName();
        DbfType getType();
        DbdDefaults getDefaults();
        DbdAttribute getAttributes();
    }
    interface DbdStruct {
        string getName();
        int16 getNumberFields();
        DbdField getFieldDescription(int16 index);
    }
    interface DbdRecord {
        string getName();
        int16 getNumberFields();
        DbdField getFieldDescription(int16 index);
    }

Record Instance

    interface RecordInstance {
        string getName();
        DbdRecord getDescription();
        DbfStruct getInstance();
        Dbf getField(string fieldName);
        Dbf getField(int16 index)
    }
getName
get the record name
getDescription
get the description of the record specific portion of the record
getInstance
get instance for the record specific portion of the record
getField
get field instance.

Locate Interfaces

Classes are available to find and traverse the various Dbd definitons and record instances. The implementation will be language specific. For Java they will be something like the following:

In addition the following is defined:

    public class DbdLocate {
        public DbdMenu getMenu(String name);
        public DbdLink getLink(String name);
        public DbdStruct getStruct(String name);
        public DbdRecord getRecord(String name);
        public LinkedList<DbdMenu> menuList;
        public LinkedList<DbdLink> linkList;
        public LinkedList<DbdStruct> structList;
        public LinkedList<DbdRecord> recordList;
    }
    public class RecordInstanceLocate {
        public RecordInstance getRecord(string name);
        public Dbf getField(string name);
        public Dbf getField(string recordName, string fieldName);
        public LinkedList<RecordInstance> instanceList;
        public LinkedList<RecordInstance> instanceList(string recordTypeName);
    }

Question Are the above methods static or should there be something like

    public class FindLocator {
        public static DbdLocate findDbdLocate();
        public static RecordInstance findRecordInstance();
    }
   

The following locates a specific menu.

    DbdMenu menu = DbdLocate.get("DisplayLimit");
    if(menu!=null) printf("found menu %s\n","DisplayLimit");

The following locates a field of a record instance.

    Dbf field = RecordInstanceLocate.getField("example.value");
    if(addr!=null) printf("found %s\n","example.value");