EPICSWIKI - User contributions [en]

Ancient V4 Design

2006-02-07T11:48:45Z

MartyKraimer:

This page links to various documents for discussion by the EPICS core developers.

'''Code to implement this stuff doesn't exist yet, and the designs may change!'''

''Note to authors: please use 'V4' at the start of page names for Version 4 documentation, as this makes it clear which wiki pages refer to the new designs just from the page name.''

== Overall Design ==

* [[V4 Use Cases]] - Bob Dalesio, Kay Kasemir

== Core and Database ==

Marty Kraimer is currently working on a Java IOC. He is no longer updating any material in this section.

* [[V4 Modules and Interfaces]] - Andrew Johnson

* [[V4 Requirements for Standard Types]] - Andrew Johnson
* [[V4 Standard Properties and Events]] - Andrew Johnson

* V4 Database Definition - Marty Kraimer, Andrew Johnson
** [[V4 DBD Statement Syntax]] - Marty Kraimer, Andrew Johnson
** [[V4 DB Record Instance Syntax]] - Andrew Johnson
** [[V4 DB RecordCommon]] - Marty Kraimer
** [[V4 DBD Examples]] - Marty Kraimer, Andrew Johnson
** [[V4 Link Support Tutorial]] - Marty Kraimer
** [[V4 View Generated Code]] - Andrew Johnson

* V4 Database Runtime
** [[V4 Design: Record Processing]] - Marty Kraimer
** [[V4 Design: dbdInterfaces]] - Marty Kraimer
** [[V4 Design: Runtime Interfaces]] - Marty Kraimer
** [[V4 Design: RecordCommon Support]] - Marty Kraimer

* V4 Database Access:
** [[V4 Design: epicsTypes]] - Marty Kraimer, Andrew Johnson
** [[V4 Design: Assembling Record Support]] - Ben Franksen
** [[V4 Design: driverInterfaces]] - Marty Kraimer

* [[V4 User-defined fields]] - Kay Kasemir

* [[V4 Server Side Plugins]] - Ralph Lange, Benjamin Franksen

== Network Communications ==

* [[V4 CA Interfaces]] - Jeff Hill
* [[V4 CA Protocol Specification]] - Jeff Hill

* [[V4 Name Server]] - Doug Murray, Kay Kasemir
* [[V4 CA Client User Interface]] - Doug Murray, Kay Kasemir
* [[V4 Data Interface]] - Kay Kasemir
* [[V4 CA example timeStamp, sevr, status, data]] - Marty Kraimer

== Other Services ==

* [[V4 Replacement for drvTS]] - Timo Korhonen
* [[V4 Replacement for SNL]] - Ben Franksen, Go"tz Pfeiffer
* [[V4 Data Store]] - Ralph Lange

== Obselete pages ==

* [[V4 July Meeting Agenda]]

* [[V4 DBD dbCommon and iocRecord]] - Marty Kraimer
* [[V4 DBD Generated Code]] - Marty Kraimer
* [[V4 Design: dbdClass]] - Marty Kraimer
* [[V4 Design: dbdClass Examples]] - Marty Kraimer
* [[V4 Design: Database Initialization]] - Marty Kraimer
* [[V4 Design: Database Access Semantics]] - Marty Kraimer

V4 Design: dbdInterfaces

2005-11-04T15:25:13Z

MartyKraimer:

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:
* <tt>record</tt> - Used by record support.
* <tt>struct</tt> - Used by code that understands the struct.
* <tt>menu</tt> - Used by code that understands the menu.

----
<center>

= Syntax =
</center>

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 <tt>true</tt> or <tt>false</tt>
* 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 <tt>char *</tt> array containing UTF-8
compatible characters not necessarily terminated with a null character.
Wherever a <tt>string</tt> argument appears, the C++ definition
will have <tt>len</tt> and <tt>char *</tt> arguments.

For Java string will just be a <tt>String</tt>.
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);

----
<center>

= DbfTypes =
</center>
The following naming conventions are used:
; Dbf
: any class starting with Dbf describes a field in a header file generated from a <tt>struct</tt> or <tt>record</tt> definition. For example DbfArray describes a field generated from <tt>field(name,array(float64[])</tt>.
; 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.

== <tt>DbfTypes.h</tt> ==

The following <tt>enum</tt> definitions describe
each field in the header files generated from DBD <tt>struct</tt> and
<tt>record</tt> 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
}

----
<center>

= Database Fields =
</center>

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 <tt>DbfArray</tt>

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

== <tt>DbfMenu</tt> ==

<tt>DbfMenu</tt> is described as:
interface DbfMenu extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbdMenu getDbdMenu();
}

<tt>DbfMenu</tt> allows the menu index to be set and retrieved
and also provides access to the DbdMenu.

A <tt>DbfMenu</tt> field can be accessed via the generated header file or via
the introspection methods.

== DbfEnum ==

<tt>DbfEnum</tt> is described as:
interface DbfEnum extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbfStringArray getChoiceArray();
}

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

== DbfLink ==

<tt>DbfLink</tt> is described as

interface DbfLink extends Dbf {
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 ==

struct TimeStamp {
int64 secondsSinceEpoch;
int32 nanoSeconds;
}

interface DbfTimeStamp extends Dbf {
void get(TimeStamp timeStamp);
void put(TimeStamp timeStamp);
}

----
<center>

= DbdStatements =

</center>
These describe everything defined in database definition files.

== <tt>DbdMenu</tt> ==

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

== <tt>DbdSupport</tt> ==

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

== <tt>DbdStruct</tt> and <tt>DbdRecord</tt> ==

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)
}

; <tt>getName</tt>
: get the record name
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
; <tt>getInstance</tt>
: get instance for the record specific portion of the record
; <tt>getField</tt>
: get field instance.

----
<center>

= Locate Interfaces =

</center>

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");

----

V4 Design: dbdInterfaces

2005-11-03T19:49:27Z

MartyKraimer:

EPICS: dbdInterfaces - IOC Database Description November 03 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 code that use code automatically
generated from DBD files or by code that uses only introspection.

Code is automatically generated from the following definitions:
* <tt>record</tt> - Used by record support.
* <tt>struct</tt> - Used by code that understands the struct.
* <tt>menu</tt> - Used by code that understands the menu.

----
<center>

= Syntax =
</center>

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 <tt>true</tt> or <tt>false</tt>
* 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 <tt>char *</tt> array containing UTF-8
compatible characters not necessarily terminated with a null character.
Wherever a <tt>string</tt> argument appears, the C++ definition
will have <tt>len</tt> and <tt>char *</tt> arguments.

For Java string will just be a <tt>String</tt>.
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);

----
<center>

= DbfTypes =
</center>
The following naming conventions are used:
; Dbf
: any class starting with Dbf describes a field in a header file generated from a <tt>struct</tt> or <tt>record</tt> definition. For example DbfArray describes a field generated from <tt>field(name,array(float64[])</tt>.
; 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.

== <tt>DbfTypes.h</tt> ==

The following <tt>enum</tt> definitions describe
each field in the header files generated from DBD <tt>struct</tt> and
<tt>record</tt> 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
}

----
<center>

= Database Fields =
</center>

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);

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 <tt>DbfArray</tt>

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});

== DbfMDArray ==
NOT YET DEFINED

== <tt>DbfMenu</tt> ==

<tt>DbfMenu</tt> is described as:
interface DbfMenu extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbdMenu getDbdMenu();
}

<tt>DbfMenu</tt> allows the menu index to be set and retrieved
and also provides access to the DbdMenu.

A <tt>DbfMenu</tt> field can be accessed via the generated header file or via
the introspection methods.

== DbfEnum ==

<tt>DbfEnum</tt> is described as:
interface DbfEnum extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbfStringArray getChoiceArray();
}

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

== DbfLink ==

<tt>DbfLink</tt> is described as

interface DbfLink extends Dbf {
DbdLink getDbdLink();
}

== DbfTimeStamp ==

struct TimeStamp {
int64 secondsSinceEpoch;
int32 nanoSeconds;
}

interface DbfTimeStamp extends Dbf {
void get(TimeStamp timeStamp);
void put(TimeStamp timeStamp);
}

----
<center>

= DbdStatements =

</center>
These describe everything defined in database definition files.

== <tt>DbdMenu</tt> ==

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

== <tt>DbdSupport</tt> ==

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

== <tt>DbdStruct</tt> and <tt>DbdRecord</tt> ==

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)
}

; <tt>getNameLength</tt>
: get length of record name
; <tt>getName</tt>
: get the record name
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
; <tt>getRecordCommonDescription</tt>
: get the description of RecordCommon
; <tt>getInstance</tt>
: 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>
: get field instance.

----
<center>

= Locate Interfaces =

</center>

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");

----

V4 Design: Runtime Interfaces

2005-11-03T19:47:28Z

MartyKraimer:

EPICS: IOC Runtime Interfaces November 03 2005

----
= Overview =

This document describes definitions for IOC runtime,
i.e. interfaces implemented or used by database access, record support,
link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTES
* IOC runtime needs lots more work
* methods, arguments, and return values are likely to undergo many changes

The example code presented in this document assume the following database
definitions:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

record(Example) extends RecordCommon {
field(common,struct(RecordCommon))
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}
----
<center>
= Record Support =
</center>

enum ProcessState {
processCancel,
processStart,
processContinue,
processFinish,
}

enum ProcessReturn {
processDone,
processAbort,
processActive
}

interface RecordSupport {
void destroy();
void initialize(int16 pass);
ProcessReturn process(ProcessState state,Callback done);
// if special returns false when after is false put fails
boolean special(boolean after,Dbf[] field);
}

<tt>ProcessState</tt> supports the following semantics:
* cancel - If the record is active terminate
* For all other states see the companion document "V4 Design: Record Processing"

The methods of <tt>RecordSupport</tt> are:
* <tt>destroy</tt> - Called when a record instance is deleted.
* <tt>initialize</tt> - Called twice (pass = 0,1) when a record is initialized.
** pass 0 - Can do all local initialization but can not attach to anything external
** pass 1 - Can attach to external things
* <tt>process</tt> - Called to process a record. See "V4 Design: Record Processing" for semantics.
* <tt>special</tt> - Called when a field declared special in a DBD file is modified. <tt>field</tt> is an array of Dbfs showing which field is being modified.

== Discussion of special ==

Special is passed a Dbf array that identifies the field being modified.
For example <tt>ExampleRecord.dbd</tt> has a field:
field(displayLimit,struct(displayLimit))
<tt>ExampleRecordSupport.java</tt> might implement special as follows:
boolean special(boolean after, Dbf[] field)
{
switch(field[0].getIndex()) {
...
case ExampleRecord.displayLimitIndex:
if(field.length==1) {
// displayLimits itself is being modified. Do something
} else {
// a field of displayLimits is being modified
switch(field[1].getIndex) {
case DisplayLimit.lowIndex:
// low being modified. do something
case DisplayLimit.highIndex:
// high being modified. do something
}
}
...
}
}
----
<center>
= Support for link and struct fields =
</center>

Support can be provided for link and struct fields.
An arbitrary number of Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Recall that the support DBD definition is:

support(choiceName, supportStructName)

<tt>choiceName</tt> is the name that identifies the implementation.
<tt>supportStructName</tt> is the name of a structure used by support for
configuration.

The syntax for interface definitions is similar to Java syntax
since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual bool getBounds(int16_t &low, int16_t &high) = 0;
};

NOTE: Int16 becomes int16_t &data and int16 data becomes int16_t data.

Support and SupportMonitor are interfaces that are common to
the support for both link and struct fields.
All support must register interface <tt>Support</tt>
and if it supports monitors interface <tt>SupportMonitor</tt>.

NOTE: arguments and return types ignored for now
interface Support {
void report(int16 level);
void destroy();
void initialize(int16 pass);
void connect();
void disconnect();
void cancel();
}

interface SupportMonitor {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Support</tt> is an interface that must be implemented by every
support module.
An instance of this is connected to each DbfLink or DbfStruct field that is configured to use support.
The <tt>Support</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>SupportMonitor</tt> is an interface that is implemented by support that
supports monitors. An example is support for hardware interrupts.
The methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally recordSupport does not need to call any of the Support
or SupportMonitor methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.
---
<center>
= Link Support =
</center>

== Overview ==

This section describes the standard interfaces
used by the record types supplied with epics base.
These interfaces are appropriate for the soft support supplied with EPICS
base and should also be sufficient for a wide variety of hardware support.
In particular they sufficient for communication with asynDriver.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can define support structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkNoop, // field was modified. No wait is necessary
linkWait, // waiting for completion
}

interface Callback {
void done();
void failure();
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

== asynDigital Support ==

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,int32 data);
boolean getBounds(Int32 low, Int32 high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,int64 data);
boolean getBounds(Int64 low, Int64 high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.
---
<center>
= Struct Support =
</center>
== support for RecordCommon ==
This implements an interface, not yet defined, that is similar to the
interface record support implements.
== support for LinearConvert ==
This implements the interface
interface SupportLinearConvert{
void convert(int32 raw,Float64 value) // from raw to eng
void convert(float64 value,Int32 raw) // from eng to raw
}

In addition it provides a factory
interface FactoryLinearConvert{
SupportLinearConvert create(string choiceName,
DbfStruct linearConvert,DbfLink inlink)
}
== support for simulation ==
This needs to be defined.
== support for breakpoint tables ==
This needs to be defined.

----
<center>

= Runtime Database Access =

</center>

== Overview ==

Database Access, with help from record, link, and device support
implements the dbdInterfaces.
Other than Database Access, fields of a record can only
be accessed via the interfaces described in dbdInterfaces.
This allows the database to handle
actions like posting database monitors without any help from
record, link, or device support.

Database access by default allocates the actual storage for each field
but allows support code to register itself to manage storage for field
instances.
Two examples, both involving arrays, are:
* The compress record registers to provide storage for the value.
** This allows it to implement a circular buffer.
** Code that accesses the value field may have to issue two get requests.
* Device support for a transient recorder registers to provide storage for the array
** This allows device support to read data from hardware in segments
** Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required.
Database Access will probably have something like the following:

class Field {
DbRecord instance;
short index;
};
...
class IntField extends Field {
int data;
}
...

This each field has the overhead of
* instance - a reference to DbRecord, i.e. record instance
* index - a 16 bit integer
* vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors.
These fields can start out null and only allocate storage as needed.

== Database Access ==

interface DbAccess {
void lock(RecordInstance instance);
void unlock(RecordInstance instance);
void process(RecordInstance instance, Callback callback);
void processCancel(RecordInstance instance, Callback callback);
void processContinue(RecordInstance instance, Callback callback);
void processRequestAccept(Dbf field, boolean yesNo);
void registerDbfSource(Dbf field, Dbf source);
LinkSupport getLinkSupport(Dbf field);
Support getSupport(Dbf field);
RecordSupport getRecordSupport(RecordInstance instance);
RecordSupport getRecordCommonSupport(RecordInstance instance);
}

The methods are:
* <tt>lock</tt> - lock the record.
* <tt>unlock</tt> - unlock the record.
* <tt>process</tt> - Request processing. Record must be idle or active or request fails.
** <tt>instance</tt> - The record to process
** <tt>callback</tt> - A callback to call when processing completes or for failure.
* <tt>processRequestAccept</tt> - Should a process request from channel access be accepted,
* <tt>registerDbfSource</tt> - Register code that will implement storage for the field.
* <tt>getLinkSupport</tt> - Find the link support for a link field
* <tt>getSupport</tt> - Get the device support for a device field
* <tt>getRecordSupport</tt> - Get the record support for the record
* <tt>getRecordCommonSupport</tt> - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

----
<center>

= Code generated from Database Definition Files =
</center>

The following shows the Java code generated from DBD files:

== structure definitions ==

Two files are generated from <tt>struct(name)</tt> definitions.
# <tt>name.java</tt>
# <tt>nameSupport.java</tt>

<tt>name.java</tt> implements:
interface Struct {
Dbf getField(int16 index);
}

If a structure is defined as:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

A generated file <tt>DisplayLimit.java</tt> contains:

public class DisplayLimit implements Struct{
public DbfFloat64 low;
public DbfFloat64 high;
public static final short lowIndex = 1;
public static final short highIndex = 2;
public static final short lastIndex = indexHigh;
Dbf getField(short index) {
switch(index) {
case lowIndex: return(low);
case highIndex: return(high);
default: throw java.lang.IllegalStateException;
}
return null;
}
}

A generated file <tt>DisplayLimitAccess.java</tt> contains:

public class DisplayLimitData {
public double low;
public double high;
}
public final class DisplayLimitAccess implements StructFactory{
public Struct create() { return new DisplayLimit; }
public static final void get(DbfStruct from,DisplayLimitData data) {
DbfFloat64 dbf = from.getInterface(1);
data.low = dbf.get();
DbfFloat64 dbf = from.getInterface(2);
data.high = dbf.get();
}
public static final void put(DbfStruct to, DisplayLimitData data) {
DbfFloat64 dbf = to.getInterface(1);
dbf.put(data.low);
DbfFloat64 dbf = to.getInterface(2);
dbf.put(data.high);
}
}

public final class DisplayLimitAccessRegister {
static public createAndRegister() {
DisplayLimitAccess access = new DisplayLimitAccess;
RegisterSupport.structure(access,"DisplayLimit");
}
}

NOTES
* The V4 replacement for registerRecordDeviceDriver must call DisplayLimitAccessRegister.createAndRegister.
* For non primitive fields the generated field is the Dbf type for the field.

Similar files are generated for C++.

== record definitions ==
If a record is defined as:
record(Example) {
field(common,struct(RecordCommon))
...
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}

The generated Java file is

public class ExampleRecord implements Struct {
... // all the fields from menuStructBase
public DbfBoolean fboolean;
public DbfOctet ctet;
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 DbfDevice device;
public DbfStruct displayLimit;
public static final int16 fbooleanIndex = 1;
...
public static final int16 lastIndex = displayLimitIndex;
Dbf getField(short index) {
switch(index) {
case fbooleanIndex : return(fboolean);
...
case displayLimitIndex: return(displayLimit);
default: throw java.lang.IllegalStateException;
}
}
}

public final class ExampleRecordFactory implements StructFactory{
public static final Struct create() { return new ExampleRecord; }
}

public final class ExampleRecordFactoryRegister {
static public createAndRegister() {
ExampleRecordFactory factory = new ExampleRecordFactory;
RegisterSupport.record(factory,"ExampleRecord");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

----
<center>
= Support Code =
</center>

This section described interfaces for
strings, arrays, and conversions.
They are intended for use by Database Access, Record Support, etc.

== C++ support for strings ==

For most strings all the database needs is a nonmutable string.

Perhaps the only type of string connected with an IOC record
that changes frequently is a field in a record type
like stringin and stringout.

This what to do for strings?

== array copy ==

ArrayCopy copies arrays an array performing conversions if necessary.

interface ArrayCopy {
void copy(DbfArray from,DbfArray to);
}

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64.
It does NOT convert between
* DbfBoolean and another type.
* DbfOctet and another type.
Thus for DbfBoolean and DbfOctet it is willing to copy
but not convert to/from other types.

== Arithmetic Conversions ==
This is a static class that converts between primitie types and arrays of primitive types.

static class DbfConvertPrimitive {
public:
int16 get(Dbf from);
int32 get(Dbf from);
int64 get(Dbf from);
float32 get(Dbf from);
float64 get(Dbf from);
get(Dbf from, String value);
get(DbfOctet from, String value);
get(DbfBoolean from, String value);
put(Dbf to, int16 value);
put(Dbf to, int32 value);
put(Dbf to, int64 value);
put(Dbf to, float32 value);
put(Dbf to, float64 value);
put(Dbf to,int32 String value);
put(DbfOctet to, String value);
put(DbfBoolean to, String value);

get(DbfArray from, int16[] value);
get(DbfArray from, int32[] value);
get(DbfArray from, int64[] value);
get(DbfArray from, float32[] value);
get(DbfArray from, float64[] value);
put(DbfArray to, int16[] value);
put(DbfArray to, int32[] value);
put(DbfArray to, int64[] value);
put(DbfArray to, float32[] value);
put(DbfArray to, float64[] value);
}

NOTES:
* For Dbf <tt>to</tt> and <tt>from</tt> must be one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>
* The get to a string implements printf semantics
* The put from a string value just scanf semantics.
* The <tt>DbfOctet</tt> methods convert to/from a string of the form "0xXX"
* The <tt>DbfBoolean</tt> get method supports all the choices specified in the DBD Record Instance Specification
* For DbfArray <tt>to</tt> and <tt>from</tt> must be an array of one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>

V4 Link Support Tutorial

2005-11-03T19:46:11Z

MartyKraimer:

V4 Link Support Tutorial - November 03 2005

----
= Overview =

The V4 link/struct support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

Each link and struct field in a record can have associated support.
* record support communicates with support via interfaces
* link or struct support implements interfaces
** link or struct support registers the interfaces it implements
** record support looks for interfaces it uses
*** it uses only the interfaces it finds
*** if no interfaces are found it reports an error

Support has no knowledge of what record types are using it.
Struct support may have knowledge of the struct field
but not of the record type.
recordSupport has no knowledge about support other than the
interface it is using.

For the rest of this document recordSupport means record support and support,
unless qualified, means link or struct support.

EPICS base defines a standard set of interfaces for support,
which includes enough functionality such that
most link support can be implemented via just these interfaces.

Base provides struct support for the following:
* RecordCommon - used by all record types in base
* LinearConvert - can be used by any analog type record
* others TBD

Base provides channel/database access link support for primitive,
string, and array fields.
The link interfaces provided by base are also used by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
anyway it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link/struct support model.

----
<center>
= Database Definitions For links and structures =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
field(name,link)
A record struct has the syntax
field(name,struct(structName))
Support for a struct or link has the syntax
support(choiceName) // no SupportStruct
support(choiceName,SupportStruct)
A record instance link has the syntax
field = support(choiceName) SupportStruct{structAssignmentList}
A record instance struct has the the syntax
field = StructName{structAssignmentList} // no support
field = support(choiceName)
StructName{structAssignmentList} // support has no SupportStruct
field = support(choiceName) SupportStruct{structAssignmentList}
StructName{structAssignmentList}

; <tt>structName</tt>
: The name of a <tt>struct</tt>
; <tt>choiceName</tt>
: UTF-8 string that describes the choice. Each support must have a unique name.
; <tt>StructName</tt>
: The same name that appears in the field definition of the record.
; <tt>SupportStruct</tt>
: The name of a <tt>struct</tt> containing configuration information for the support. recordSupport normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.

Assume the following definitions:
record(AiRecord) {
...
field(in,link)
...
}
...
struct(MonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
support(monitorLink,MonitorLink)
support(inputLink,InputLink)
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
support(someVmeADC,VME)

The first example instance definition selects a monitor link.
AiRecord aiMonitorExample = {
...
in = {
support(monitorLink) MonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link.
AiRecord aiInputExample = {
...
in = {
support(inputLink) InputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example selects support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {support(someVmeADC) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

menuStructBase.dbd defines definitions for Channel/Database Access Links.
The base supplied support registers each choiceName in the support definitions.
The complete set of data structure and support definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* process
* monitor
* input
* output

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== support definitions ===

support(asynInt32,AsynLink)
support(asynInt32Average,AsynLink)
support(asynInt32Monitor,AsynLink)
support(asynFloat64,AsynLink)
support(asynFloat64Average,AsynLink)
support(asynFloat64Monitor,AsynLink)
support(asynDigitalMonitor,AsynLink)
support(asynDigital,AsynLink)
support(asynInt32Array,AsynLink)
support(asynFloat64Array,AsynLink)
support(asynOctet,AsynLink)

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. At least for the first few V4 releases,
asynDriver will not be part of base.
---
<center>
= interfaces for link and struct support =
</center>

Support can be provided for link and struct fields.
An arbitrary number of Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

The syntax for interface definitions is similar to Java syntax
since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual bool getBounds(int16_t &low, int16_t &high) = 0;
};

NOTE: Int16 becomes int16_t &data and int16 data becomes int16_t data.

Support and SupportMonitor are interfaces that are common to
the support for both link and struct fields.

NOTE: arguments and return types ignored for now
interface Support {
void report(int16 level);
void destroy();
void initialize(int16 pass);
void connect();
void disconnect();
void cancel();
}

interface SupportMonitor {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Support</tt> is an interface that must be implemented by every
support module.
<tt>SupportMonitor</tt> is an interface that is implemented by support that
supports monitors. An example is support for hardware interrupts.

Normally recordSupport does not need to call any of the Support
or SupportMonitor methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.
---
<center>
= interfaces for struct support =
</center>
== support for RecordCommon ==
This implements an interface, not yet defined, that is similar to the
interface record support implements.
== support for LinearConvert ==
This implements the interface
interface SupportLinearConvert{
convert(int32 raw,Float64 value) // from raw to eng
convert(float64 value,Int32 raw) // from eng to raw
}

In addition it provides a factory
interface FactoryLinearConvert{
SupportLinearConvert(string choiceName,
DbfStruct linearConvert,DbfLink inlink)
}
== support for simulation ==
This needs to be defined.
== support for breakpoint tables ==
This needs to be defined.

---
<center>
= interfaces for link Support =
</center>

EPICS base defines a number of standard interfaces
that are used by the record types supplied with epics base.
These interfaces are appropriate for the soft support supplied with EPICS
base and should also be sufficient for a wide variety of hardware support.
In particular they sufficient for communication with asynDriver.

The standard interfaces use the following definitions:

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkNoop, // field was modified. No wait is necessary
linkWait, // waiting for completion
}

interface Callback {
void done();
void failure();
}

The complete set of interfaces are described in V4 Design: Runtime Interfaces.
Some examples are:

interface LinkProcess {
LinkResult process(Callback callback);
}

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}

<tt>LinkProcess</tt> is the interface for process link fields
and <tt>LinkInt16</tt> is the interface for int16 fields.
----
<center>
= Example - VME ADC support =
</center>
Assume the VME and support definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initialize vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkNoop;
}
LinkResult put(Callback callback, int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

----
<center>
= Additional requirements for link support =
</center>

== Overview ==

The following are two important requirements:
* analog I/O
** link support can return raw value. Support must convert to engineering units.
** link support can return engineering units
* output records
** If possible link support should provide initial value during initialization
** If output can be modified other than by record itself than the records balue should be modified without causing a new output

Lets consider each of these separately.
== Analog I/O ==
In V3 the aiRecord and aoRecords are responsible for conversion between
raw values and engineering units. Raw values are 32 bit integers. Device
support is responsible for setting the slope and intercept fields of the record.
recordSupport takes care of the actual conversions.
Device support can tell recordSupport that it set the engineering units
rather than a raw value by a different return value.

For V4 the following is done:

aiRecord and aoRecord both have the following fields:

menu(menuConvert) {
choice(menuConvertRaw, "None")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(engUnitsHigh,float64)
field(engUnitsLow,float64)
field(slope,float64)
field(intercept,float64)
}

...
field(convert, menu(menuConvert))
field(linearConvert, struct(LinearConvert))
field(convertTable,string);
field(units, string)

NOTE This section is written as though record support itself does
the conversions. Most record support would call the standard support
for LinearConvert.

If a record instance has convert set to None then recordSupport does the following.
* if link support implements LinkFloat64 it just calls this to obtain an engineering units value
* otherwise it gets a value via interface LinkInt32 and converts the value from in int32 to a float64.

If a record instance has convert linear
* if link support implements LinkInt32 it uses LinkInt32 otherwise it uses LinkFloat64
* it uses slope and interccept to convert from raw to engineering units

<tt>LinkInt32</tt> is defined as:
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If convert is linear and getBounds returns true than recordSupport
uses the returned value to compute slope and intercept. In all
other cases recordSupport just uses whatever values they have.

For example support for a 16 bit unipolar ADC would set low=0, high=65535,
and return true.
If link support can not determine the bounds then getBounds returns false.

NOTE:The interface implemented by breakpoint tables must be defined.
It will support the same semantics as the V3 breakpoint tables.

== Output Records ==

The following are two features that link support should implement
whenever possible:
# When a record is initalized provide the current value of the output
# If the actual output is changed by something other than the output record than the output record should also be modified to reflect the new output value.

The first feature is especially desirable when an IOC is rebooted.
If a hardware output can survive a reboot this is a very desirable feature.
If the output is to a field bus, a PLC, or to a record in another IOC
it is often possible for the link support to determine the current value.

The second feature is something that was often asked for in V3 but
only implemented
for some special cases. This is especially desirable when the output is
connected to a system that can have multiple sources of control.
Examples are GPIB devices with front pannel controls, PLC systems that
have manual controls or non-epics network access.

For V3 some of the hardware , but none of the soft,
support implemented the first feature but by
modifying actual fields in the record. V3 did not implement the second
feature. Some special device support, not part of base, was implemented
to support this feature.

For V4 these features are supported as follows:

=== record initialization ===

The link support implements an interface that has a put and a get method.
For example:

interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If the link support can support readbacks then it implements get
and returns linkNoop. If it does not support readbacks
then it implements get by just returning linkNoop.

=== monitors for outputs ===

If output link support can detect when something besides the link support
itself modifies the output then it implements interface <tt>MonitorLink</tt>
interface SupportMonitor {
void addMonitor(Callback callback);
void removeMonitor();
}
At initialization recordSupport looks for this interface and if found
it calls <tt>addMonitor</tt>. The link support calls the callback whenever
it detects a change in the output that it did not cause. recordSupport
causes itself to be processed without making a new call to the
link support.
---

V4 Design: dbdInterfaces

2005-11-02T20:33:54Z

MartyKraimer:

EPICS: dbdInterfaces - IOC Database Description November 02 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 code that use code automatically
generated from DBD files or by code that uses only introspection.

Code is automatically generated from the following definitions:
* <tt>record</tt> - Used by record support.
* <tt>struct</tt> - Used by code that understands the struct.
* <tt>menu</tt> - Used by code that understands the menu.

----
<center>

= Syntax =
</center>

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 <tt>true</tt> or <tt>false</tt>
* 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 <tt>char *</tt> array containing UTF-8
compatible characters not necessarily terminated with a null character.
Wherever a <tt>string</tt> argument appears, the C++ definition
will have <tt>len</tt> and <tt>char *</tt> arguments.

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

An example of a definition that includes a string argument is
void get(String name);

In C++ this will become
void get(int lenName, char *name);
In Java this will become
void get(String name);
=== 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);

----
<center>

= DbfTypes =
</center>
The following naming conventions are used:
; Dbf
: any class starting with Dbf describes a field in a header file generated from a <tt>struct</tt> or <tt>record</tt> definition. For example DbfArray describes a field generated from <tt>field(name,array(float64[])</tt>.
; 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.

== <tt>DbfTypes.h</tt> ==

The following <tt>enum</tt> definitions describe
each field in the header files generated from DBD <tt>struct</tt> and
<tt>record</tt> 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
}

----
<center>

= Database Fields =
</center>

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 {
int32 getLength();
void get(string value);
void setPutSize(int32 size);
void put(string value);
}

The following code prints a string.

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

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(name);
printf("field %s\n",name);
}

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 <tt>DbfArray</tt>

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});

== DbfMDArray ==
NOT YET DEFINED

== <tt>DbfMenu</tt> ==

<tt>DbfMenu</tt> is described as:
interface DbfMenu extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbdMenu getDbdMenu();
}

<tt>DbfMenu</tt> allows the menu index to be set and retrieved
and also provides access to the DbdMenu.

A <tt>DbfMenu</tt> field can be accessed via the generated header file or via
the introspection methods.

== DbfEnum ==

<tt>DbfEnum</tt> is described as:
interface DbfEnum extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbfStringArray getChoiceArray();
}

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

== DbfLink ==

<tt>DbfLink</tt> is described as

interface DbfLink extends Dbf {
DbdLink getDbdLink();
}

== DbfTimeStamp ==

struct TimeStamp {
int64 secondsSinceEpoch;
int32 nanoSeconds;
}

interface DbfTimeStamp extends Dbf {
void get(TimeStamp timeStamp);
void put(TimeStamp timeStamp);
}

----
<center>

= DbdStatements =

</center>
These describe everything defined in database definition files.

== <tt>DbdMenu</tt> ==

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

== <tt>DbdSupport</tt> ==

interface DbdSupport {
int32 getChoiceNameLength();
void getChoiceName(String name);
int32 getSupportStructNameLength();
void getSupportStructName(String name);
}

== <tt>DbdStruct</tt> and <tt>DbdRecord</tt> ==

interface DbdAttribute {
int32 getDefaultLength();
void getDefault(String value);
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();
void getName(String name);
DbfType getType();
DbdDefaults getDefaults();
DbdAttribute getAttributes();
}

interface DbdStruct {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

interface DbdRecord {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

== Record Instance ==

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

; <tt>getNameLength</tt>
: get length of record name
; <tt>getName</tt>
: get the record name
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
; <tt>getRecordCommonDescription</tt>
: get the description of RecordCommon
; <tt>getInstance</tt>
: 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>
: get field instance.

----
<center>

= Locate Interfaces =

</center>

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");

----
<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++.
----

V4 DBD Examples

2005-11-02T19:54:24Z

MartyKraimer:

Example Record Types November 02 2005
= Overview =
This document present proposed V4 replacements for a few of the
V3 record types.

<center>
= aoRecord =
</center>

aoRecord.dbd might be defined as follows:

include "menuStructBase.dbd"
record(AoRecord) {
field(common,struct(RecordCommon))
field(desiredValue, float64) {
asl(0)
}
field(currentValue, float64) {
readonly(yes)
}
field(out,link)
field(outputRateOfChange, float64)
field(desiredOutputLink,link)
field(closedLoop, bool)
field(outputIncremental, bool)
field(convert, menu(menuConvert)) {
special(yes)
}
field(linearConvert, struct(LinearConvert)) {
special(yes)
}
field(convertTable,string);
field(units, string)
field(displayLimit, struct(DisplayLimit))
field(controlLimit, struct(ControlLimit))
field(alarmLimit, struct(AlarmLimit))
field(rawValue, int32) {
design(no)
}
field(readBackValue, int32) {
design(no)
readonly(yes)
}
field(simulation,struct(SimulationFloat64))
field(invalidAction, menu(menuIvoa))
field(invalidValue, float64)
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(controlLimit, controlLimit)
property(alarmLimit, alarmLimit)
}
}
view(output) {
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(raw) {
property(value, rawValue) {
property(timeStamp, time)
}
}
view(readback) {
property(value, readBackValue) {
property(timeStamp, time)
}
}
}

<center>
= calcRecord =
</center>

calcRecord.dbd defines the following:

include "menuStructBase.dbd"
struct(CalcInpLink) {
field(block,boolean)
field(link,link)
field(value,float64)
}

record(CalcRecord){
field(common,struct(RecordCommon))
field(value,float64) {
asl(0)
}
field(calc,string) {
special(yes)
}
field(input,array(struct(CalcInpLink)[]))
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(alarmLimit,struct(AlarmLimit))
view(result) {
property(value, result) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(alarmLimit, alarmLimit)
}
}
view(expression) {
property(value, calc)
}
}

<center>
= mbbiRecord =
</center>

mbbiRecord.dbd could be:

include "menuStructBase.dbd"
struct(MbbiState) {
field(name, string)
field(value, array(octet[]))
field(severity, menu(menuAlarmSevr))
}
record(MbbiRecord) {
field(common,struct(RecordCommon))
field(state, array(struct(MbbiState)[])) {
special(yes)
}
#NOTE: stateName needed because enum must refer to array of string
field(stateName,array(string[])) {
design(no) readonly(yes)
}
field(value, enum(stateName)) {
asl(0)
}
field(unknownStateSeverity, menu(menuAlarmSevr))
field(changeStateSeverity, menu(menuAlarmSevr))
field(inp, link)
field(rawValue, array(octet[])) {
design(no)
readonly(yes)
}
field(hardwareShift, int16) {
readonly(yes)
}
field(hardwareMask, array(octet[]) {
readonly(yes)
}
view(choice) {
property(value, value) {
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(raw) {
property(value, raw) {
property(timeStamp, time)
}
}
}

<center>
= waveformRecord =
</center>

waveformRecord.dbd defines the following:

include "menuStructBase.dbd"
record(WaveformRecord) {
field(common,struct(RecordCommon))
field(value, array([])) {
asl(0)
special(yes)
}
field(reArm,bool)
field(io,link)
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(busy,bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
}

V4 DBD Statement Syntax

2005-11-02T19:53:04Z

MartyKraimer:

DBD Statement Syntax November 02 2005
----
= Overview =
This document presents the syntax for V4 database definition files.

NOTE This version of the database definition and database instance
syntax does not provide:
# a direction for links
# a way to select a subset of the support definitions

Support can exist for either a link field or a struct field.
The support definition is just

support(choiceName,supportStructName)

When a record instance is created any choiceName can be specified for
a link or struct field. If an invalid choice is made, an error will
be issued during initialization.

<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

link

Examples:
field(disableLink,link)
field(process, link)
field(inp,link)

== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= support =
</center>

A <tt>support</tt> statement describes an implementation of support for a link
or struct field.
Link support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

support(choiceName)
or
support(choiceName,supportStructName)

where

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>supportStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName
selects the support to attach to a record link.

Examples:
link(processLink,ProcessLink)
link(monitorLink,MonitorLink)

V4 Design: Record Processing

2005-11-02T19:52:08Z

MartyKraimer:

EPICS V4: Record Processing November 02 2005

----

= Overview =

UNRESOLVED ISSUES
* This document is still evolving
* Monitors
** How will monitor data be managed?
** Big problem is how will array data be managed?
* Alarms
** How will V4 handle alarms?
* Events
** What is the V4 event model?
** What is required from the IOC database?

This document described semantics for V4 record processing that are
different than for V3.
This includes the following:
* Semantics for record processing
* Semantics for Database and Channel Access Links.
* Record Locking
* Posting database monitors
* Status and Alarm Severity
* Access to array and structure fields.

This version is based on feedback from the EPICS core developer's
meeting at ANL/APS on July 11th through July 14th.
In addition discussions with Andrew Johnson and Eric Norum have
led to many of the ideas described below.
This wiki is a companion to the wiki "V4 Design: dbdInterfaces".

V3 record processing semantics do not work well for data
acquisition applications. An example of data acquisition is:
* Move sample to new position.
** Several motors may be involved
** While moving post monitors to show current position, etc.
* Sample data
* Wait until CA client has fetched the data before next move.

SynAPPS provides the Scan, motor, etc records which help with
data processing applications. These records process as follows:

* Record does not complete processing until all inputs, outputs, etc done. Not completing means that they do not call recGblFwdLink until all proccessing is complete. Note that recGblFwdLink is what causes the V3 ioc to complete record processing.
* While waiting for asynchronous events these records have PACT=0 but keep state that shows it is still active
* Can be scanned and issue monitors while internal state is active

Leaving PACT 0 but not calling recGblFwdLink was not anticipated when the V3 record processing semantics were created.
For V4 a record can be processed while it is waiting
for asynchronous processing to complete.

In V3, if an input link is asynchronous, Process Passive does not wait
for asynchronous processing to complete before fetching data.
This also complicated data acquisition applications.

V4 record processing is designed to make data acquisition easier.
Both input and output links can wait for record processing.
This is done, however, without record support blocking.
If blocking makes it easier to implement record support,
then the support can spawn a separate thread that does block.
Record support can communicate with the separate thread to decide when
to complete record processing.

----

<center>
= Overview of V4 Record Processing =
</center>

V4 will provide a replacement for dbProcess.
The name may be different but for now it will still be called dbProcess.

In V4 database access and channel access appear the same to record and
link support.
Only the implementation knows the difference.
In this document the term channelAccess will mean access to a record.
Thus it can mean a workstation client or a field of
a record that is a link to a record.

V4 also allows support for struct fields.
For example base provides support for
field(common,struct(RecordCommon))
In the record types provided with base, this is the first field.
The fields in <tt>RecordCommon</tt> are the V4 replacement for
the V3 dbCommon fields.

V4 record processing has the following features.

* database fields
** "owned" by database not record support
** fields can only be accessed via interfaces
** support can optionally provide storage for data associated with a field
** for channelAccess all fields appear as type primitive, string, struct, array or combination thereof
* dbProcess
** processes synchronous linked records by queuing requests rather than recursive calls to dbProcess
** can be called an arbitrary number of times while record is active
* link
** always has associated support
** can be record link or can be something else, e.g. a link to hardware
* record link
** can request process and/or wait for asynchronous completion
** local synchronous requests queued by dbProcess
** record is active and can be processed while asynchronous links active
* struct fields
** Can have associated support which can be synchronous or asynchronous
* block
** is requested via a separate field
** if true than support waits for all outstanding I/O to complete before further processing
** if false than asynchronous support can proceed in parallel
* lock
** record instances are locked
** dbProcess locks before calling support
** other code can also lock
** Two records can be locked without deadlock
* monitors
** dbProcess handles monitors
** support triggers monitors by writing to fields

<center>
= Database Fields =
</center>
== Field Access by Support Code ==
Support code can access database fields only via interfaces implemented by
the IOC database.
Thus record fields are owned by the IOC database not by record support.

Support code can register to provide storage for particular fields.
For example support code could implement a circular buffer for field <tt>value</tt>.
When some other code
request the array associated with <tt>value</tt>, the IOC database
calls the support. The support returns the first portion of the circular
buffer and the caller must make an additional call to retrieve the rest of
the circular buffer.

== Field Access by Channel Access ==

For V4 database access and channel access appear the same to record
instances.
It is only the code that implements link support that knows the difference.
If a linked record is local, database access is used, and, if the record
is remote, channel access.

V4 allows channel access to the following types of fields:

* primitive types
* string
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** struct
** array of primitive or string or struct

For other database field types, i.e. links, the database will make the field
appear as one of the above types. For example a link field will appear
as a string with syntax that matches the information associated with the link.
For example a process link will have a string something like
support(processLink) ProcessLink(pvname = 'pvname'; wait = true)
where
; <tt>processLink</tt>
: selects the support for a process link
; <tt>ProcessLink</tt>
: Names the struct that the support uses for configuration information

<center>
= Record Processing Semantics =
</center>

This section describes the semantics implemented by dbProcess.

The following are involved in record processing
* dbProcess
** implements a queue for local records that are processed because of record links
** posts monitors caused by field changes during record processing
* record support
** calls support code for RecordCommon fields
** is responsible for record instance fields
** calls link/struct support via interfaces implemented by the support
* link support
** can be links to other records, to driver support, etc
** implements interfaces called by record and/or other support
* struct support
** is responsible for the fields in the struct
** implements interfaces called by record and/or other support

== Processing Life Cycle ==
Assume a record instance is idle, i.e. is ready to start processing.
*dbProcess calls record support with one of the following states
** processCancel - record support must terminate any outstanding processing
** processStart - start processing. record support returns one of
*** processDone - All done and successful
*** processQuit - dont do any more processing. Return to idle state
*** processActive - not done. Call again
** processContinue - another request to process while record is active. Record support again returns one of the above.

Record support, with associated link/struct support does the following:
* When it is called for processStart
** calls the support for RecordCommon with state processStart. it returns
*** processDone - Record support starts processing record specific fields
*** processQuit - Record support just returns processQuit to dbProcess
*** processActive - Record returns processActive. It will be called again with state processContinue. It calls RecordCommon support with state processActive. This continues until Record Common returns processDone or processQuit
* When RecordCommon returns processDone record support starts processing record specific fields
** Associated link or struct support may be called
*** Record support implements any <tt>block</tt> fields.
*** It detects when asynchronous support completes
*** as long as there is incomplete asynchronous support it returns processActive to dbProcess
** When all record specific fields have been processed it calls RecordCommon suport with state processQuit
*** RecordCommon support can return processActive. Until it returns processDone, record support just returns processActive to dbProcess
** When RecordCommon returns processDone, record support returns processDone to dbProcess.

struct and link fields can have associated support
* associated support may be asynchronous
** support returns indicating that it is active
** support is required to detect when asynchronous support completes
** when processing is complete support returns indicating that it is done.
* whenever record support returns to dbProcess, dbProcess posts any fields that were modified.
** record may be active or done
* when record support returns processDone or processQuit record is again set idle.

== record common ==

These fields are optional but it is expected that most record
types will include a standard set of fields.

The support for RecordCommon processes the following fields:

* at the beginning of record processing
** disabled - if true NO processing will be done, i.e. processQuit is returned
** scanDisable
*** has associated support
*** if record is scan disabled processQuit is returned
** alarm fields
*** alarm handling is described below
* after record support completes
** processLink array
*** has associated support

== record support ==

Record support is responsible for all its fields.
For link and struct fields there may be associated support which
may be synchronous or asynchronous.
Record support communicates with
the link/struct support via interfaces that are implemented by the support.
If the record includes a field for struct(RecordCommon) it should
use the associated support for its fields.

Record support may be called multiple times by dbProcess while a record instance
is active.
One of the arguments to process is ProcessState which has the values:
* processCancel - Cancel any outstanding activity
* processStart - Start processing
* processContinue - Making additional call

process returns ProcessReturn which is one of the following:
* processDone - Done and successful
* processQuit - Do not do any more processing
* processActive - Not done

If record support returns processActive it must keep internal state so
that it knows how to handle processCancel and processContinue.

For record support the above rules allow:
* process can be called repeatedly. This will continue as long as it returns processActive
* Everytime process returns processActive DbProcess posts monitors.

== Record Locking ==

V3 implemented lock sets in order to prevent different threads
from simultaneously accessing linked records.

Instead of lock sets V4:
* implements a per record instance lock.
* defines a rule that allows two records to be locked without deadlocks

== Posting Monitors ==

In V3 monitors are posted when code (record support, device support, database access, etc) calls db_post_event. In V4 database access will itself handle
the posting of monitors.

Monitors are posted by DbProcess when
* record support returns processActive.
* at the end of record processing.

<center>
= link/struct Semantics =
</center>

Both link and struct fields can have associated support.
The support can be synchronous or asynchronous.

Support code implements interfaces.
Code that is responsible for a field communicates with the support via
the interface. Lets call this code the client.

Each link and struct field has a well defined client.
* The support for RecordCommon is the client for fields in dbCommon
* record support is the client for the other top level fields in a record
* the struct support is the client for any link or struct fields in the struct

A link/struct may have an associated block. The client is responsible for
implementing block. If block is true then the support will not be called
until all outstanding record activity completes.

<center>
= channelAccess links =
</center>

channelAccess link means access to a record or field. The requester can be:
* A database link in a record
* A channel access link in a record
* A workstation channel access client

A channelAccess link is one of the following types:
* Monitor Link
** Implemented via a monitor request on linked field
** Optionally process record containing the link when monitor value is returned.
* Input Link
** Optionally request that record be processed.
** Optionally wait for linked record to complete processing.
** Get value.
* Output Link:
** Put value
** Optionally request processing.
** Optionally wait until completion
* Process Link: Perform the following actions
** Request processing
** Optionally wait until linked record completes

NOTES:
* processLink is the replacement for the V3 forwardLink
* wait does NOT mean to wait synchronously. It means to save state, return, and resume at the saved state when called again.

Links are processed as follows:

The following rules apply when a process request is made:
* If record is already being processed the request is just ignored
* record support can specify that links to particular fields not cause processing.
** Where should this be specified? In the Database Definition, the record instance, or both.
** If a process request is allowed, should it be done regardless of the scan mechanism, i.e. the record does not have to be passive?

----
<center>
= Mutual Exclusion =
</center>

V3 implemented lock sets, i.e. when a record was being processed it and all records linked via database links were locked.

Lock sets solved two Mutual Exclusion problems:
* V3 allowed dbProcess to be called recursively.
** process passive database links and forward links were implemented via recursive calls to DbProcess
** Lock sets prevented deadly embrace problems for circular links.
* No puts could be done to a record in a lock set while record processing is active.
** For synchronous records this guarantees that no fields are modified except by record processing itself.
** For asynchronous records this guarantee is not valid.

V4 does not call dbProcess recursively. Instead a process request is queued.
The request fails if either of the following is true:
* The record is active.
* The record is already queued.

dbProcess itself manages the queue , which is FIFO.
When record support returns the first entry in the queue is processed.
In addition if link or struct support completes before the queue
is empty, a request to process the record containing the link/struct will
be added to the same queue.
Thus if a set of synchronous records are processed they will complete processing
without any context switch.

Question What about periodically scanned records? Needs thought.

This leaves the question of what should be done about mutual exclusion.

For V4 there will be two locks associated with the IOC database:
1) a global lock, and 2) A per record instance lock.

The global lock must be taken
whenever the structure of the database is modified. Examples are
1) adding new record types, 2) adding new record instances, and 3) modifying
database links. Global locks are not discussed further in this document.

Each record instance has an associated lock.
When dbProcess is called it takes the lock.
Before it returns it unlocks.
Thus record support does not need to lock or unlock.

Other code that needs access to fields of a record instance must
lock before accessing any fields and unlock after all accesses are complete.

This leaves the problem of how to access fields from two different record
instances simultaneously. For example code that implements database
access needs such access. Code that needs such access must call dbLockLink before accessing the linked record and dbUnlockLink after access.

dbLockLink is implemented as follows:
* Each Record instances has a unique ordinal number
* Assume Record X has a link to record Y
* If the ordinal number of X is less than that of Y
** Just call dbLock for record Y
* If the ordinal numnber of X is greater than that of Y
** call dbUnlock for X
** call dbLock for Y
** call dbLock for X

----
<center>
= Posting Modifications =
</center>

The document "V4 Design: dbdIterfaces" provides a design that allows
database access to handle all posting on monitors without requiring
any help from the code that modifies database fields.
It can do this because fields can be modified only via an
interface implemented by database access.

dbProcess posts monitors when:
* When record support returns processActive.
* When it finishes record processing.

How to implement monitors must be decided.

----
<center>
= Alarm Processing =
</center>

Question Will V4 alarm handling be different than V3? If so this section
may be meaningless.

The V4 semantics for status and severity have the following goals:
* alarmSeverity has the same values as for V3
* alarmStatus is a string
* a record starts processing with alarmSeverity = "NO_ALARM" and status empty.
* status will ONLY be posted if it has changed since the last time it was posted.
* alarmSeverity will ONLY be posted if it has changed since the last time it was posted

The semantics, which are implemented by the support for RecordCommon, are:

* When recordCommon is called with processStart
** A private variable newSeverity is set to NO_ALARM
** A private variable prevSeverity is set to alarmSeverity
* When recordCommon completes its part of record processing
** If newSeverity is NO_ALARM and prevSeverity has a different value
*** alarmSeverity is set to NO_ALARM
*** alarmStatus is set to empty

* When the recordCommon.setSeverity(sevr,status) is called
** If sevr is less than or equal to newSeverity nothing is done
** else
*** alarmSeverity is set to sevr
*** alarmStatus is set to status
*** newSeverity is set to sevr

NOTE: alarmStatus and alarmSeverity are written by the normal method.
This means that their values will be posted.
----
<center>
= Channel Access/ Database Access field types =
</center>

== Overview ==

This section discusses how IOC database fields are accessed by channel access
or via database links.

For the initial V4 implementation only the following types of data
will be accessable.

* primitive types
* string
* enum
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** enum
** struct (use recursion for allowed types)
** one dimensional array of primitive or string or struct

The dbdInterfaces document defines database field types.
It also defines a subset called basic types, which consists
of primitive types, string, array, and structure.
For external access only basic types can be accessed.
This means that structures and arrays that do not consist of basic types
are not accessablevia clannelAccess. For example a DbfLink is
not accessable via channel access as a DbfLink.

Non basic fields will only be available via some combination of basic types.

For example a DbfLink field will appear as a string.
If a Database Definition is

struct(calcInpLink) {
field(block,boolean)
field(link,link)
field(value,float64)
};

record(xxx) {
field(link,link)
field(value,float64)
...
field(inp,array(struct(calcInpLink)[]))
...
}

If a client attaches to
record.field(link)
The data will be appear in the form:
choice(choiceName) SupportStruct(pvname= ...)
where <tt>choiceName</tt> is the name of the link support, <tt>SupportStruct</tt> is the name of the support struct asociated with the support, and the arguments are the values for the support structure.

Then if a client specifies the process variable:
record.field(inp[1].link)
Then it connects to the link field of the second calcInpLink of field inp.

== primitive types ==

This includes DbfBool, DbfOctet, DbfInt16, ... , DbfFloat64.
These do not present any problems. The scalar value is transfered.

== string ==

A string is just a UTF_8 encoded character string

== DbfMenu and DbfEnum ==

Handled as an enum

== DbfLink ==

A string with the same syntax as defined for a link field in "V4 DB Record Instance Syntax"

== timeStamp ==

This is just transfered like a struct with two fields:
* int64 secondsSinceEpoch
* int32 nanoSeconds

== struct ==

The individual fields can be accessed directly so this discussion
only involves access to the entire structure.

The entire structure can be accessed as a string with the same syntax
as defined for a struct field in "V4 DB Record Instance Syntax"

== array ==

Arrays of the following types are accessable:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfStruct - As long as its fields are valid types

Note that arrays of structs are not accessable in the early V4 releases.

Arrays still need lots more discussion!!!
The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.

For the initial V4 version, database access only allows access to arrays of the following types.
* primitive - DbfBool,...,DbfFloat64
* DbfString
* ???? What else

An individual element of an array of type DbfStruct can be accessed
directly if it satisfies the criteria for accessing a DbfStruct.

Question: Should database Access be implemented so that record/link support can transfer an array in segments. Examples:
* If the array is a circular buffer, it is presented in two segements
* If the array is stored in hardware, e.g. a transient recorder, the array can be read from the hardware and passed to the client in segments.

If an array is available only in segments then can we
prevent two clients from trying to access the same array simultaneously?

Perhaps this is a problem that must be solved by an application:
* runControl records are one solution
* Other solutions can be envisioned

== MDArray ==

Not implemented if the early V4 releases.

== Associated Data ==

The typical example is a client that asks for timeStamp, severity, status,
and data.

V4 DB RecordCommon

2005-11-02T19:51:09Z

MartyKraimer:

EPICS V4: Standard Support November 02 2005
----

= Overview =

This document describes two base supplied components for EPICS V4 databases.
# menuStructBase.dbd - menu and struct definitions
# baseSupport.dbd - link definitions for base supplied support

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

NOTE: This document is ahead of the two above V4 documents so it may use
slightly different syntax.
----
<center>
= menuStructBase.dbd =
</center>

== Channel/Database Access Links ==

struct(ProcessLink) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
}
struct(MonitorLink) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
struct(OutputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}

== asynDriver Link ==
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

== Definitions for recordCommon ==

# menu definitions for recordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}

#struct definitions for recordCommon
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link)
}

struct Disable {
field(disabled,boolean)
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link)
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

struct(ProcessLink) {
field(block,boolean)
field(link,link)
}

struct(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(processAtInit,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmNoAckTransient,menu(menuAlarmSevr)) {
# highest level of alarm that does not have to be acknowledged"
}
field(undefined,boolean) {
dynamic(yes)
default(true)
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(ProcessLink[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be private to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(engUnitsHigh,float64)
field(engUnitsLow,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
field(hysteresis,float64)
}

MAY NEED NEW DEFINITION
struct(SimulationFloat64) {
field(modeLink,link)
field(mode,boolean)
field(link,link)
field(value,float64)
field(alarmSevr,menu(menuAlarmSevr))
}

----
<center>
= definition of record types =
</center>
Most record types are defined as follows:
#include "menuStructBase.dbd"
record(AiRecord) {
field(common,struct(RecordCommon))
...
}

----
<center>
= baseSupport.dbd =
</center>

== Channel/Database Access Support ==

Link support is provided for
* monitor support
* input support
* output
* process

For monitor, input, and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

support(processLink,ProcessLink)
support(monitorLink,MonitorLink)
support(monitorLinkArray,MonitorLink)
support(inputLink,InputLink)
support(inputLinkArray,InputLink)
support(outputLink,OutputLink)
support(outputLinkArray)

== asynDriver support ==

support(asynInt32,AsynLink)
support(asynInt32Average,AsynLink)
support(asynInt32Monitor,AsynLink)
support(asynFloat64,AsynLink)
support(asynFloat64Average,AsynLink)
support(asynFloat64Monitor,AsynLink)
support(asynDigitalMonitor,AsynLink)
support(asynDigital,AsynLink)
support(asynInt32Array,AsynLink)
support(asynFloat64Array,AsynLink)
support(asynOctet,AsynLink)

== struct support ==
For RecordCommon
support(common) # no SupportStruct
For linear conversion
support(linearConvert)
For simulation
support(simulation)

V4 DB Record Instance Syntax

2005-11-02T19:50:07Z

MartyKraimer:

2005-11-02 MRK

= Overview =

The syntax used for record instances has to change in EPICS V4,
since we now have to support structured data.
A complete redesign of the syntax has been done to help improve parsing, and to provide commonality between the syntax of a DB file and the string representation of structured data values passed through Channel Access.

NOTE: See the note at the beginning of the "V4 DBD Statement Syntax"
concerning the syntax for link and struct fields.

= Document Conventions =

This syntax is presented below in the form of a grammar. The conventions I'm using are as follows:

;''symbolBeingDefined:''
: ''otherSymbol''
: ''alternateSymbolFollowedBy'' <tt>literal</tt>
: ''one of:'' <tt>list of posible literal values</tt>

= Common Symbols =

The symbols described in this section are used in the grammar, but may be implemented as lexical tokens.

;''identifier:''
: A legal C99 identifier. Note that C99 permits implementations to allow extended characters to be used in identifiers, but does not require it, so the use of extended characters may reduce portability and is not recommended.

== Integer Constants ==

;''integerConstant:''
: ''positiveInteger''

;''positiveInteger:''
: ''octalConstant''
: ''hexConstant''
: ''decimalConstant''

;''octalConstant:''
: <tt>0</tt>
: ''octalConstant'' ''octalDigit''

;''octalDigit:''
: ''one of:'' <tt>0-7</tt>

;''hexConstant:''
: <tt>0x</tt> ''hexDigit''
: <tt>0X</tt> ''hexDigit''
: ''hexConstant'' ''hexDigit''

;''hexDigit:''
: ''one of:'' <tt>0-9 a-f A-F</tt>

;''decimalConstant:''
: ''one of:'' <tt>1-9</tt>
: ''decimalConstant'' ''decimalDigit''

;''decimalDigit:''
: ''one of:'' <tt>0-9</tt>

This was meant to be a description of the C99 standard integer representation, but I made it up myself so it may be flawed. Note that we will not accept the C99 numeric suffixes u/U and l/L since (unlike a C compiler) we know the type of the number we're expecting.

== Floating Point Constants ==

;''realConstant:''
:'' positiveReal''
: <tt>-</tt> ''positiveReal''

;''positiveReal:''
: ''digitSequence''
: ''digitSequence'' <tt>.</tt>
: ''digitSequence'' <tt>.</tt> ''exponentPart''
: ''digitSequence'' <tt>.</tt> ''digitSequence''
: ''digitSequence'' <tt>.</tt> ''digitSequence'' ''exponentPart''
: <tt>.</tt> ''digitSequence''
: <tt>.</tt> ''digitSequence'' ''exponentPart''
: ''digitSequence'' ''exponentPart''

;''digitSequence:''
: ''decimalDigit''
: ''digitSequence'' ''decimalDigit''

;''exponentPart:''
: <tt>e</tt> ''signedExponent''
: <tt>E</tt> ''signedExponent''

;''signedExponent:''
: <tt>-</tt> ''digitSequence''
: <tt>+</tt> ''digitSequence''
: ''digitSequence''

In ANSI C source code, a sequence of decimal digits with neither a decimal point nor an exponent is an integer constant, not a floating-point constant. We will permit this however, since we always know the field type in advance.

== Boolean Constants ==

We can afford to be generous in what we accept as a boolean value:

;''booleanConstant:''
: ''booleanTrue''
: <tt>"</tt> ''booleanTrue'' <tt>"</tt>
: ''booleanFalse''
: <tt>"</tt> ''booleanFalse'' <tt>"</tt>

;''booleanTrue:''
: ''one of:'' <tt>1 T TRUE t true True Y YES Yes y yes</tt>

;''booleanFalse:''
: ''one of:'' <tt>0 F FALSE f false False N NO No n no</tt>

'''I'm proposing all these possibilities for true/false as they are all obvious in meaning, and will allow a CA Put of any of these strings to a boolean field. We might even want to allow registration of boolean strings in other languages...'''

== String Constants ==

;''stringConstant:''
: <tt>"</tt> ''escapedCharacterList'' <tt>"</tt>

;''escapedCharacterList:''
: A series of characters, using the C99 ''escapeSequence'' syntax defined below:

;''escapeSequence:''
: ''simpleEscapeSequence''
: ''octalEscapeSequence''
: ''hexEscapeSequence''
: ''universalCharacterName''

;''simpleEscapeSequence:''
: ''one of:'' <tt>\' \" \? \\ \a \b \f \n \r \t \v</tt>

;''octalEscapeSequence:''
: <tt>\</tt> ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit'' ''octalDigit''

;''hexEscapeSequence:''
: <tt>\x</tt> ''hexDigit''
: ''hexEscapeSequence'' ''hexDigit''

Note: C99 does not limit the number of hexadecimal digits that can appear in a ''hexEscapeSequence'', but it does state that the behaviour is undefined if the resulting character value exceeds that of the largest character.

;''universalCharacterName:''
: <tt>\u</tt> ''hexQuad''
: <tt>\U</tt> ''hexQuad'' ''hexQuad''

;''hexQuad:''
: ''hexDigit'' ''hexDigit'' ''hexDigit'' ''hexDigit''

= Database File =

This section will eventually define what can appear in a .db file. That currently means:

* record instances
* comments
* macro instances, including where they will be allowed
* template files and substitution macro definitions
* port definitions for template instances
* data for tools such as VDCT, that will not be discarded by .db processing tools.

The templates, macros and ports design should be very similar to the ideas produced for R3.14 VDCT templates.

= Record Definitions =

;''recordDefinition:''
: ''recordType'' ''recordName'' <tt>= {</tt> ''recordBody'' <tt>}</tt>

;''recordType:''
: ''identifier''

;''recordName:''
: ''recordNameChar''
: ''recordName'' ''recordNameChar''

;''recordNameChar:''
: ''one of:'' <tt>0-9 A-Z a-z _ - : ; < > [ ]</tt>
: Any Unicode/UTF-8 character outside of the Basic Latin set

This extends the character set available to a V3 record name, adding all possible multi-byte characters. However, EPICS sites are strongly advised to confirm that such record names can be processed using all of their database and CA client tools before actually making use of this particular extension.

;''recordBody:''
: ''recordBodyItem''
: ''recordBody'' ''recordBodyItem''

Record instance definitions in EPICS V4 look very similar to a C99 structure definition with initialization. For example:

ai foo:bar:temperature = {
...
}

Inside the body of the record definition, there are three possible kinds of statements, similar to a C assignment statement. Note these statements must be terminated with a semi-colon (which is different from inside a struct). The reason for this difference is to prevent database instance files from becoming dependent on the order of fields in a record; if we permit record instances to be created from a single comma-separated list of field values without the field names, it could lead to significant confusion if the field order ever changes.

;''recordBodyItem:''
: ''infoAssignment''
: ''fieldAssignment''
: ''extraFieldAssigment''

== Information Fields ==

;''infoAssignment:''
: <tt>info</tt> ''infoName'' <tt>=</tt> ''stringConstant'' <tt>;</tt>

;''infoName:''
: ''identifier''
: ''stringConstant''

Info items provide additional configuration data about this record that can be accessed by other software running on the IOC.

info savePeriod = "30.0";
info restorePhase = "1";
info "my favourite things" = "raindrops on roses";

== Field Assignment ==

;''fieldAssignment:''
: ''fieldName'' <tt>=</tt> ''initializer'' <tt>;</tt>

;''fieldName:''
: ''identifier''

;''initializer:''
: ''constant''
: ''structInitializer''
: ''arrayInitializer''
: ''linkInitializer''

;''initializerList:''
: ''initializer''
: ''initializerList'' <tt>,</tt> ''initializer''

The ''initializer'' in a field assignment is also the exact same syntax that will be used when converting a string value from a CA client for example into a field value that is being put into a field.

=== Basic and Enumerated Initializers ===

;''constant:''
: ''booleanConstant''
: ''integerConstant''
: ''realConstant''
: ''stringConstant''

The syntax for the field initializer depends on the data type represented by fieldName. Basic types (numeric or string) should need no comment other than to note that values for numeric fields must not be given inside quotes (unlike EPICS V3). Menu field values may be given as either a string or an integer. For enum fields, if the related field that contains the strings is defined first, the enum field may be specified using a string; otherwise it can only be set using an integer value.

Examples:
ai foo:bar:temperature = {
inputSmoothing = 0.98;
invalidValue = 1000;
units = "Celcius";
scan = "Interrupt";
...
}

=== Structure Initializers ===

;''structInitializer:''
: <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''structAssignmentList:''
: ''initializerList''
: ''fieldName'' <tt>=</tt> ''initializerList''
: ''structAssignmentList'' <tt>;</tt> ''fieldName'' <tt>=</tt> ''initializerList''

Initializers for a structure field look similar to a nested record body, but the rules are slightly different:
* You can give a series of values for adjacent items using a simple comma-separated list (for a record body, you ''must'' name each field)
* Semi-colons are required between a value and a following named item.

For example:

ai foo:temperature:sensor = {
linearConvert = {
mode = "Linear";
low = -12.5, 133.5
};
displayLimit = { 0, 100 };
...
}

=== Link Initializer ===

;''linkInitializer:''
: ''support(choiceName) supportStructName'' <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''choiceName:''
: ''identifier''

;''supportStructName:''
: ''identifier''

These select a particular link support and interface for the field, and set its address according to the structure type defined for that link type.

calcout foo:temperature:controller = {
block = true
output = support(outputLink) OutputLink{
pvname = "fum:baz:heater";
process = true;
wait = true;
}
input = [2] {
{ link = {
support(monitorLink) MonitorLink{
pvname = "foo:temperature:setpoint";
process = false
}
}
}
{ block=true
link = {
support(inputLink) InputLink {
pvname = "foo:temperature:sensor";
process = true;
wait = true;
inheritSeverity = true
}
}
}
};
expression = "(B - A) > 0";
...
}

mbbi foo:bar:door = {
input = support(acro9440) VME{0, 5};
...
}

QUESTION There is nothing that allows a DVT to prompt a user
with a valid set if support for a particular link. Should there be?

=== Array Initializers ===

;''arrayInitializer:''
: <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>

;''arrayAssignmentList:''
: ''initializerList''
: <tt>[</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''
: ''arrayAssignmentList'' <tt>; [</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''

;''arrayType:''
: ''one of:'' <tt>bool</tt> <tt>int16</tt> <tt>uint16</tt> <tt>int32</tt> <tt>uint32</tt>
: ''one of:'' <tt>float32</tt> <tt>float64</tt> <tt>octet</tt> <tt>string</tt>

;''arrayCapacity:''
: ''integerConstant''
: ''arrayCapacity'' <tt>,</tt> ''integerConstant''

If the definition of the array field being set did not do so, an array field initialization must include the size of the array and/or the type of the data stored in it. Inside the braces data values are given in a comma-separated list; the index can also be set to initialize individual values, and any mixture of the two can be used as desired:

mbbi foo:bar:door = {
stateNames = [4] {"Broken", "Closed", "Open", "Moving"};
stateSeverity = [4] {"Major"; [3] = "Minor"};
...
}

For multi-dimensional arrays, data values can only appear inside the inner-most sets of braces, although index settings are permitted outside of these. These two definitions give the same result:

matrix identity1 = {
value = float32 [3,3] { {1, 0, 0}, {0, 1, 0}, {1, 0, 0}};
}
matrix identity2 = {
value = float32 [3,3] { {1}, {[1] = 1}, {[2] = 1}};
}

V4 Link Support Tutorial

2005-11-02T19:48:50Z

MartyKraimer:

EPICS: IOC link and struct Support November 02 2005

----
= Overview =

The V4 link/struct support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

Each link and struct field in a record can have associated support.
* record support communicates with support via interfaces
* link or struct support implements interfaces
** link or struct support registers the interfaces it implements
** record support looks for interfaces it uses
*** it uses only the interfaces it finds
*** if no interfaces are found it reports an error

Support has no knowledge of what record types are using it.
Struct support may have knowledge of the struct field
but not of the record type.
recordSupport has no knowledge about support other than the
interface it is using.

For the rest of this document recordSupport means record support and support,
unless qualified, means link or struct support.

EPICS base defines a standard set of interfaces for support,
which includes enough functionality such that
most support can be implemented via just these interfaces.

Most of the support supplied with base is link support. In particular
support for channel/database access links. It also briefly describes
support for interfacing with asynDriver.

The link interfaces support Channel/Database access
and the standard interfaces used by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link/struct support model.

----
<center>
= Database Definitions For links and structures =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
field(name,link)
A record struct has the syntax
field(name,struct(structName))
Support for a struct or link has the syntax
support(choiceName) // no SupportStruct
support(choiceName,supportStructName)
A record instance struct has the the syntax
field = StructName{structAssignmentList} // no support
field = support(choiceName)
StructName{structAssignmentList} // support has no SupportStruct
field = support(choiceName) SupportStruct{structAssignmentList}
StructName{structAssignmentList}

; <tt>structName</tt>
: The name of a <tt>struct</tt>
; <tt>choiceName</tt>
: UTF-8 string that describes the choice. Each support must have a unique name.
; <tt>SupportStruct</tt>
: The name of a <tt>struct</tt> containing configuration information for the support. recordSupport normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.

Assume the following definitions:
record(AiRecord) {
...
field(in,link)
...
}
...
struct(MonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
support(monitorLink,MonitorLink)
support(inputLink,InputLink)
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
support(someVmeADC,VME)

The first example instance definition selects a monitor link.
AiRecord aiMonitorExample = {
...
in = {support(monitorLink)
MonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link.
AiRecord aiInputExample = {
...
in = {support(inputLink)
InputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example selects support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {support(someVmeADC) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

menuStructBase.dbd defines definitions for Channel/Database Access Links.
The base supplied support registers each choiceName in the support definitions.
The complete set of data structure and support definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* process
* monitor
* input
* output

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== support definitions ===

support(asynInt32,AsynLink)
support(asynInt32Average,AsynLink)
support(asynInt32Monitor,AsynLink)
support(asynFloat64,AsynLink)
support(asynFloat64Average,AsynLink)
support(asynFloat64Monitor,AsynLink)
support(asynDigitalMonitor,AsynLink)
support(asynDigital,AsynLink)
support(asynInt32Array,AsynLink)
support(asynFloat64Array,AsynLink)
support(asynOctet,AsynLink)

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. At least for the first few V4 releases,
asynDriver will not be part of base.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Whenever possible support should implement the standard interfaces
defined by EPICS base, since these are the interfaces that the record types
supplied with base use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can define support structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual bool getBounds(int16_t &low, int16_t &high) = 0;
};

NOTE: Int16 becomes int16_t &data and int16 data becomes int16_t data.

== Link and MonitorLink ==

All support must register interface <tt>Link</tt>
and if it supports monitors interface <tt>MonitorLink</tt>.

NOTE: arguments and return types ignored for now
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally recordSupport does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

== asynDigital Support ==

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,int16 data);
boolean getBounds(Int16 low, Int16 high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,int32 data);
boolean getBounds(Int32 low, Int32 high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,int64 data);
boolean getBounds(Int64 low, Int64 high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and support definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initialize vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkResult put(Callback callback, int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

----
<center>
= Discussion of link support interfaces =
</center>

== Overview ==
The definitions: record link, support, record instance links,
and the link interfaces are designed to support channel/database links,
links to hardware support, and links to other types of support.

The following are two important requirements:
* analog I/O
** link support can return raw value. Support must convert to engineering units.
** link support can return engineering units
* output records
** Can link support provide initial value?
** What if multiple sources can change linked output?

Lets consider each of these separately.
== Analog I/O ==
In V3 the aiRecord and aoRecords are responsible for conversion between
raw values and engineering units. Raw values are 32 bit integers. Device
support is responsible for setting the slope and intercept fields of the record.
recordSupport takes care of the actual conversions.
Device support can tell recordSupport that it set the engineering units
rather than a raw value by a different return value.

For V4 the following is done:

aiRecord and aoRecord both have the following fields:

menu(menuConvert) {
choice(menuConvertRaw, "None")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(engUnitsHigh,float64)
field(engUnitsLow,float64)
field(slope,float64)
field(intercept,float64)
}

...
field(convert, menu(menuConvert))
field(linearConvert, struct(LinearConvert))
field(convertTable,string);
field(units, string)

NOTE This section is written as though record support itself does
the conversions. Most record support would call the standard support
for LinearConvert.

If a record instance has convert set to None then recordSupport does the following.
* if link support implements LinkFloat64 it just calls this to obtain an engineering units value
* otherwise it gets a value via interface LinkInt32 and converts the value from in int32 to a float64.

If a record instance has convert linear
* if link support implements LinkInt32 it uses LinkInt32 otherwise it uses LinkFloat64
* it uses slope and interccept to convert from raw to engineering units

<tt>LinkInt32</tt> is defined as:
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If convert is linear and getBounds returns true than recordSupport
uses the returned value to compute slope and intercept. In all
other cases recordSupport just uses whatever values they have.

For example support for a 16 bit unipolar ADC would set low=0, high=65535,
and return true.
If link support can not determine the bounds then getBounds returns false.

NOTE:The interface implemented by breakpoint tables must be defined.
It will support the same semantics as the V3 breakpoint tables.

== Output Records ==

The following are two features that link support should implement
whenever possible:
# When a record is initalized provide the current value of the output
# If the actual output is changed by something other than the output record than the output record should also be modified to reflect the new output value.

The first feature is especially desirable when an IOC is rebooted.
If a hardware output can survive a reboot this is a very desirable feature.
If the output is to a field bus, a PLC, or to a record in another IOC
it is often possible for the link support to determine the current value.

The second feature is something that was often asked for in V3 but
only implemented
for some special cases. This is especially desirable when the output is
connected to a system that can have multiple sources of control.
Examples are GPIB devices with front pannel controls, PLC systems that
have manual controls or non-epics network access.

For V3 some of the hardware , but none of the soft,
support implemented the first feature but by
modifying actual fields in the record. V3 did not implement the second
feature. Some special device support, not part of base, was implemented
to support this feature.

For V4 these features are supported as follows:

=== record initialization ===

The link support implements an interface that has a put and a get method.
For example:

interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If the link support can support readbacks then it implements get
and returns linkDone. If it does not support readbacks
then it implements get by just returning linkNoop.

=== monitors for outputs ===

If output link support can detect when something besides the link support
itself modifies the output then it implements interface <tt>MonitorLink</tt>
interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}
At initialization recordSupport looks for this interface and if found
it calls <tt>addMonitor</tt>. The link support calls the callback whenever
it detects a change in the output that it did not cause. recordSupport
causes itself to be processed without making a new call to the
link support.
---
<center>
= Struct Support =
</center>
== support for RecordCommon ==
This implements an interface, not yet defined, that is similar to the
interface record support implements.
== support for LinearConvert ==
This implements the interface
interface LinearConvertSupport {
convert(int32 raw,Float64 value) // from raw to eng
convert(float64 value,Int32 raw) // from eng to raw
}

In addition it provides a factory
interface LinearConvertFactory {
LinearConvertSupport(string choiceName,
DbfStruct linearConvert,DbfLink inlink)
}
== support for simulation ==
This needs to be defined.
== support for breakpoint tables ==
This needs to be defined.

V4 DBD Statement Syntax

2005-11-01T20:49:53Z

MartyKraimer:

DBD Statement Syntax November 01 2005
----
= Overview =
This document presents the syntax for V4 database definition files.

NOTE This version of the database definition and database instance
syntax does not provide:
# a direction for links
# a way to select a subset of the support definitions

Support can exist for either a link field or a struct field.
The support definition is just

support(choiceName,supportStructName)

When a record instance is created any choiceName can be specified for
a link or struct field. If an invalid choice is made, an error will
be issued during initialization.

<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

field(name,link)

Examples:
field(disableLink,link)
field(process, link)
field(inp,link)

== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= support =
</center>

A <tt>support</tt> statement describes an implementation of support for a link
or struct field.
Link support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

support(choiceName)
or
support(choiceName,supportStructName)

where

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>supportStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName
selects the support to attach to a record link.

Examples:
link(processLink)
link(monitorLink,MonitorLinkData)

V4 DB Record Instance Syntax

2005-11-01T20:48:20Z

MartyKraimer:

2005-11-01 MRK

= Overview =

The syntax used for record instances has to change in EPICS V4,
since we now have to support structured data.
A complete redesign of the syntax has been done to help improve parsing, and to provide commonality between the syntax of a DB file and the string representation of structured data values passed through Channel Access.

NOTE: See the note at the beginning of the "V4 DBD Statement Syntax"
concerning the syntax for link and struct fields.

= Document Conventions =

This syntax is presented below in the form of a grammar. The conventions I'm using are as follows:

;''symbolBeingDefined:''
: ''otherSymbol''
: ''alternateSymbolFollowedBy'' <tt>literal</tt>
: ''one of:'' <tt>list of posible literal values</tt>

= Common Symbols =

The symbols described in this section are used in the grammar, but may be implemented as lexical tokens.

;''identifier:''
: A legal C99 identifier. Note that C99 permits implementations to allow extended characters to be used in identifiers, but does not require it, so the use of extended characters may reduce portability and is not recommended.

== Integer Constants ==

;''integerConstant:''
: ''positiveInteger''

;''positiveInteger:''
: ''octalConstant''
: ''hexConstant''
: ''decimalConstant''

;''octalConstant:''
: <tt>0</tt>
: ''octalConstant'' ''octalDigit''

;''octalDigit:''
: ''one of:'' <tt>0-7</tt>

;''hexConstant:''
: <tt>0x</tt> ''hexDigit''
: <tt>0X</tt> ''hexDigit''
: ''hexConstant'' ''hexDigit''

;''hexDigit:''
: ''one of:'' <tt>0-9 a-f A-F</tt>

;''decimalConstant:''
: ''one of:'' <tt>1-9</tt>
: ''decimalConstant'' ''decimalDigit''

;''decimalDigit:''
: ''one of:'' <tt>0-9</tt>

This was meant to be a description of the C99 standard integer representation, but I made it up myself so it may be flawed. Note that we will not accept the C99 numeric suffixes u/U and l/L since (unlike a C compiler) we know the type of the number we're expecting.

== Floating Point Constants ==

;''realConstant:''
:'' positiveReal''
: <tt>-</tt> ''positiveReal''

;''positiveReal:''
: ''digitSequence''
: ''digitSequence'' <tt>.</tt>
: ''digitSequence'' <tt>.</tt> ''exponentPart''
: ''digitSequence'' <tt>.</tt> ''digitSequence''
: ''digitSequence'' <tt>.</tt> ''digitSequence'' ''exponentPart''
: <tt>.</tt> ''digitSequence''
: <tt>.</tt> ''digitSequence'' ''exponentPart''
: ''digitSequence'' ''exponentPart''

;''digitSequence:''
: ''decimalDigit''
: ''digitSequence'' ''decimalDigit''

;''exponentPart:''
: <tt>e</tt> ''signedExponent''
: <tt>E</tt> ''signedExponent''

;''signedExponent:''
: <tt>-</tt> ''digitSequence''
: <tt>+</tt> ''digitSequence''
: ''digitSequence''

In ANSI C source code, a sequence of decimal digits with neither a decimal point nor an exponent is an integer constant, not a floating-point constant. We will permit this however, since we always know the field type in advance.

== Boolean Constants ==

We can afford to be generous in what we accept as a boolean value:

;''booleanConstant:''
: ''booleanTrue''
: <tt>"</tt> ''booleanTrue'' <tt>"</tt>
: ''booleanFalse''
: <tt>"</tt> ''booleanFalse'' <tt>"</tt>

;''booleanTrue:''
: ''one of:'' <tt>1 T TRUE t true True Y YES Yes y yes</tt>

;''booleanFalse:''
: ''one of:'' <tt>0 F FALSE f false False N NO No n no</tt>

'''I'm proposing all these possibilities for true/false as they are all obvious in meaning, and will allow a CA Put of any of these strings to a boolean field. We might even want to allow registration of boolean strings in other languages...'''

== String Constants ==

;''stringConstant:''
: <tt>"</tt> ''escapedCharacterList'' <tt>"</tt>

;''escapedCharacterList:''
: A series of characters, using the C99 ''escapeSequence'' syntax defined below:

;''escapeSequence:''
: ''simpleEscapeSequence''
: ''octalEscapeSequence''
: ''hexEscapeSequence''
: ''universalCharacterName''

;''simpleEscapeSequence:''
: ''one of:'' <tt>\' \" \? \\ \a \b \f \n \r \t \v</tt>

;''octalEscapeSequence:''
: <tt>\</tt> ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit'' ''octalDigit''

;''hexEscapeSequence:''
: <tt>\x</tt> ''hexDigit''
: ''hexEscapeSequence'' ''hexDigit''

Note: C99 does not limit the number of hexadecimal digits that can appear in a ''hexEscapeSequence'', but it does state that the behaviour is undefined if the resulting character value exceeds that of the largest character.

;''universalCharacterName:''
: <tt>\u</tt> ''hexQuad''
: <tt>\U</tt> ''hexQuad'' ''hexQuad''

;''hexQuad:''
: ''hexDigit'' ''hexDigit'' ''hexDigit'' ''hexDigit''

= Database File =

This section will eventually define what can appear in a .db file. That currently means:

* record instances
* comments
* macro instances, including where they will be allowed
* template files and substitution macro definitions
* port definitions for template instances
* data for tools such as VDCT, that will not be discarded by .db processing tools.

The templates, macros and ports design should be very similar to the ideas produced for R3.14 VDCT templates.

= Record Definitions =

;''recordDefinition:''
: ''recordType'' ''recordName'' <tt>= {</tt> ''recordBody'' <tt>}</tt>

;''recordType:''
: ''identifier''

;''recordName:''
: ''recordNameChar''
: ''recordName'' ''recordNameChar''

;''recordNameChar:''
: ''one of:'' <tt>0-9 A-Z a-z _ - : ; < > [ ]</tt>
: Any Unicode/UTF-8 character outside of the Basic Latin set

This extends the character set available to a V3 record name, adding all possible multi-byte characters. However, EPICS sites are strongly advised to confirm that such record names can be processed using all of their database and CA client tools before actually making use of this particular extension.

;''recordBody:''
: ''recordBodyItem''
: ''recordBody'' ''recordBodyItem''

Record instance definitions in EPICS V4 look very similar to a C99 structure definition with initialization. For example:

ai foo:bar:temperature = {
...
}

Inside the body of the record definition, there are three possible kinds of statements, similar to a C assignment statement. Note these statements must be terminated with a semi-colon (which is different from inside a struct). The reason for this difference is to prevent database instance files from becoming dependent on the order of fields in a record; if we permit record instances to be created from a single comma-separated list of field values without the field names, it could lead to significant confusion if the field order ever changes.

;''recordBodyItem:''
: ''infoAssignment''
: ''fieldAssignment''
: ''extraFieldAssigment''

== Information Fields ==

;''infoAssignment:''
: <tt>info</tt> ''infoName'' <tt>=</tt> ''stringConstant'' <tt>;</tt>

;''infoName:''
: ''identifier''
: ''stringConstant''

Info items provide additional configuration data about this record that can be accessed by other software running on the IOC.

info savePeriod = "30.0";
info restorePhase = "1";
info "my favourite things" = "raindrops on roses";

== Field Assignment ==

;''fieldAssignment:''
: ''fieldName'' <tt>=</tt> ''initializer'' <tt>;</tt>

;''fieldName:''
: ''identifier''

;''initializer:''
: ''constant''
: ''structInitializer''
: ''arrayInitializer''
: ''linkInitializer''

;''initializerList:''
: ''initializer''
: ''initializerList'' <tt>,</tt> ''initializer''

The ''initializer'' in a field assignment is also the exact same syntax that will be used when converting a string value from a CA client for example into a field value that is being put into a field.

=== Basic and Enumerated Initializers ===

;''constant:''
: ''booleanConstant''
: ''integerConstant''
: ''realConstant''
: ''stringConstant''

The syntax for the field initializer depends on the data type represented by fieldName. Basic types (numeric or string) should need no comment other than to note that values for numeric fields must not be given inside quotes (unlike EPICS V3). Menu field values may be given as either a string or an integer. For enum fields, if the related field that contains the strings is defined first, the enum field may be specified using a string; otherwise it can only be set using an integer value.

Examples:
ai foo:bar:temperature = {
inputSmoothing = 0.98;
invalidValue = 1000;
units = "Celcius";
scan = "Interrupt";
...
}

=== Structure Initializers ===

;''structInitializer:''
: <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''structAssignmentList:''
: ''initializerList''
: ''fieldName'' <tt>=</tt> ''initializerList''
: ''structAssignmentList'' <tt>;</tt> ''fieldName'' <tt>=</tt> ''initializerList''

Initializers for a structure field look similar to a nested record body, but the rules are slightly different:
* You can give a series of values for adjacent items using a simple comma-separated list (for a record body, you ''must'' name each field)
* Semi-colons are required between a value and a following named item.

For example:

ai foo:temperature:sensor = {
linearConvert = {
mode = "Linear";
low = -12.5, 133.5
};
displayLimit = { 0, 100 };
...
}

=== Link Initializer ===

; '''Comment from ANJ'''
: I do not like this syntax, which is verbose and requires the application developer to know the interface names supported by that particular field of the record type (DCTs can provide a menu to choose from, but for anyone who doesn't use a DCT this is not a nice thing to require users to get right).
: The calcout example presented uses generic choice names which presumably are equivalent to the version 3 PV_LINK type, but the meaning of the link parameters for these is under debate.
: The syntax for link fields should only need the user to learn a single choice name for each link type. There may be more link types and more choice names as a result, but the interface names themselves should not have to appear in DB files at all.
: The mbbi example below uses my original and preferred syntax, which is shorter and more in keeping with the rest of the new DB file syntax.

;''linkInitializer:''
: ''choice(choiceName) supportStructName'' <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''choiceName:''
: ''identifier''

;''supportStructName:''
: ''identifier''

These select a particular link support and interface for the field, and set its address according to the structure type defined for that link type.

calcout foo:temperature:controller = {
block = true
output = choice(outputLink) PvOutputLink{
pvname = "fum:baz:heater";
process = true;
wait = true;
}
input = [2] {
{ link = {
choice(monitorLink) PvMonitorLink{
pvname = "foo:temperature:setpoint";
process = false
}
}
}
{ block=true
link = {
choice(inputLink) PvInputLink {
pvname = "foo:temperature:sensor";
process = true;
wait = true;
inheritSeverity = true
}
}
}
};
expression = "(B - A) > 0";
...
}

mbbi foo:bar:door = {
input = choice(acro9440) VME{0, 5};
...
}

QUESTION There is nothing that allows a DVT to prompt a user
with a valid set if support for a particular link. Should there be?

=== Array Initializers ===

;''arrayInitializer:''
: <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>

;''arrayAssignmentList:''
: ''initializerList''
: <tt>[</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''
: ''arrayAssignmentList'' <tt>; [</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''

;''arrayType:''
: ''one of:'' <tt>bool</tt> <tt>int16</tt> <tt>uint16</tt> <tt>int32</tt> <tt>uint32</tt>
: ''one of:'' <tt>float32</tt> <tt>float64</tt> <tt>octet</tt> <tt>string</tt>

;''arrayCapacity:''
: ''integerConstant''
: ''arrayCapacity'' <tt>,</tt> ''integerConstant''

If the definition of the array field being set did not do so, an array field initialization must include the size of the array and/or the type of the data stored in it. Inside the braces data values are given in a comma-separated list; the index can also be set to initialize individual values, and any mixture of the two can be used as desired:

mbbi foo:bar:door = {
stateNames = [4] {"Broken", "Closed", "Open", "Moving"};
stateSeverity = [4] {"Major"; [3] = "Minor"};
...
}

For multi-dimensional arrays, data values can only appear inside the inner-most sets of braces, although index settings are permitted outside of these. These two definitions give the same result:

matrix identity1 = {
value = float32 [3,3] { {1, 0, 0}, {0, 1, 0}, {1, 0, 0}};
}
matrix identity2 = {
value = float32 [3,3] { {1}, {[1] = 1}, {[2] = 1}};
}

V4 DB RecordCommon

2005-11-01T20:27:19Z

MartyKraimer:

EPICS V4: Standard Support November 01 2005
----

= Overview =

This document describes two base supplied components for EPICS V4 databases.
# menuStructBase.dbd - menu and struct definitions
# baseSupport.dbd - link definitions for base supplied support

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

NOTE: This document is ahead of the two above V4 documents so it may use
slightly different syntax.
----
<center>
= menuStructBase.dbd =
</center>

== Channel/Database Access Links ==

struct(PvProcessLink) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
}
struct(PvMonitorLink) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
struct(PvOutputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}

== asynDriver Link ==
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

== Definitions for recordCommon ==

# menu definitions for recordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}

#struct definitions for recordCommon
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link)
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link)
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

struct(ProcessLink) {
field(block,boolean)
field(link,link)
}

struct(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmNoAckTransient,menu(menuAlarmSevr)) {
# highest level of alarm that does not have to be acknowledged"
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(ProcessLink[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be private to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(eguf,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= definition of record types =
</center>
Most record types are defined as follows:
#include "menuStructBase.dbd"
record(AiRecord) {
field(common,struct(RecordCommon))
...
}

----
<center>
= baseSupport.dbd =
</center>

== Channel/Database Access Support ==

Link support is provided for
* monitor support
* input support
* output
* process

For monitor, input, and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

support(processLink,PvProcessLink)
support(monitorLink,PvMonitorLink)
support(monitorLinkArray,PvMonitorLink)
support(inputLink,PvInputLink)
support(inputLinkArray,PvInputLink)
support(outputLink,PvOutputLink)
support(outputLinkArray)

== asynDriver support ==

support(asynInt32,AsynLink)
support(asynInt32Average,AsynLink)
support(asynInt32Monitor,AsynLink)
support(asynFloat64,AsynLink)
support(asynFloat64Average,AsynLink)
support(asynFloat64Monitor,AsynLink)
support(asynDigitalMonitor,AsynLink)
support(asynDigital,AsynLink)
support(asynInt32Array,AsynLink)
support(asynFloat64Array,AsynLink)
support(asynOctet,AsynLink)

== struct support ==
For RecordCommon
support(common) # no SupportStruct

V4 DBD Examples

2005-11-01T20:25:03Z

MartyKraimer:

Example Record Types November 01 2005
= Overview =
This document present proposed V4 replacements for a few of the
V3 record types.

<center>
= aoRecord =
</center>

aoRecord.dbd might be defined as follows:

include "menuStructBase.dbd"
record(AoRecord) {
field(common,struct(RecordCommon))
field(value, float64) {
asl(0)
}
field(outValue, float64) {
readonly(yes)
}
field(out,link)
field(outputRateOfChange, float64)
field(desiredOutputLink,link)
field(closedLoop, bool)
field(outputIncremental, bool)
field(convert, menu(menuConvert)) {
special(yes)
}
field(linearConvert, struct(LinearConvert)) {
special(yes)
}
field(convertTable,string);
field(units, string)
field(displayLimit, struct(DisplayLimit))
field(controlLimit, struct(ControlLimit))
field(alarmLimit, struct(AlarmLimit))
field(alarmDeadband, float64)
field(rawValue, int32) {
design(no)
}
field(readBackValue, int32) {
design(no)
readonly(yes)
}
field(init, bool) {
design(no)
readonly(yes)
}
field(simOutputLink,link)

field(simModeLink,link)
field(simMode, bool)
field(simSevr, menu(menuAlarmSevr))
field(invalidAction, menu(menuIvoa))
field(invalidValue, float64)
field(outValueModified, bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(controlLimit, controlLimit)
property(alarmLimit, alarmLimit)
}
}
view(output) {
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(raw) {
property(value, rawValue) {
property(timeStamp, time)
}
}
view(readback) {
property(value, readBackValue) {
property(timeStamp, time)
}
}
}

<center>
= calcRecord =
</center>

calcRecord.dbd defines the following:

include "menuStructBase.dbd"
struct(CalcInpLink) {
field(block,boolean)
field(link,link)
field(value,float64)
}

record(CalcRecord){
field(common,struct(RecordCommon))
field(result,float64) {
asl(0)
}
field(calc,string) {
special(yes)
}
field(input,array(struct(CalcInpLink)[]))
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(alarmLimit,struct(AlarmLimit))
field(alarmDeadband,float64)
field(lastValueAlarmed,float64) {
design(no)
readonly(yes)
}
field(rpcl,private("char *"))
view(result) {
property(value, result) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(alarmLimit, alarmLimit)
}
}
view(expression) {
property(value, calc)
}
}

<center>
= mbbiRecord =
</center>

mbbiRecord.dbd could be:

include "menuStructBase.dbd"
struct(MbbiState) {
field(name, string)
field(value, array(octet[]))
field(severity, menu(menuAlarmSevr))
}
record(MbbiRecord) {
field(common,struct(RecordCommon))
field(state, array(struct(MbbiState)[])) {
special(yes)
}
#NOTE: stateName needed because enum must refer to array of string
field(stateName,array(string[])) {
design(no) readonly(yes)
}
field(value, enum(stateName)) {
asl(0)
}
field(unknownStateSeverity, menu(menuAlarmSevr))
field(changeStateSeverity, menu(menuAlarmSevr))
field(inp, link)
field(rawValue, array(octet[])) {
design(no)
readonly(yes)
}
field(hardwareShift, int16) {
readonly(yes)
}
field(hardwareMask, array(octet[]) {
readonly(yes)
}
view(choice) {
property(value, value) {
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(raw) {
property(value, raw) {
property(timeStamp, time)
}
}
}

<center>
= waveformRecord =
</center>

waveformRecord.dbd defines the following:

include "menuStructBase.dbd"
record(WaveformRecord) {
field(common,struct(RecordCommon))
field(value, array([])) {
asl(0)
special(yes)
}
field(reArm,bool)
field(io,link)
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(busy,bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
}

V4 Link Support Tutorial

2005-11-01T20:23:00Z

MartyKraimer:

EPICS: IOC link and struct Support November 01 2005

----
= Overview =

The V4 link/struct support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

Each link and struct field in a record can have associated support.
* record support communicates with support via interfaces
* link or struct support implements interfaces
** link or struct support registers the interfaces it implements
** record support looks for interfaces it uses
*** it uses only the interfaces it finds
*** if no interfaces are found it reports an error

Support has no knowledge of what record types are using it.
Struct support may have knowledge of the struct field
but not of the record type.
recordSupport has no knowledge about support other than the
interface it is using.

For the rest of this document recordSupport means record support and support,
unless qualified, means link or struct support.

EPICS base defines a standard set of interfaces for support,
which includes enough functionality such that
most support can be implemented via just these interfaces.

Most of the support supplied with base is link support. In particular
support for channel/database access links. It also briefly describes
support for interfacing with asynDriver.

The link interfaces support Channel/Database access
and the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link/struct support model.

----
<center>
= Database Definitions For links and structures =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
field(name,link)
A record struct has the syntax
field(name,struct(structName))
Support for a struct or link has the syntax
support(choiceName) // no SupportStruct
support(choiceName,supportStructName)
A record instance struct has the the syntax
field = StructName{structAssignmentList} // no support
field = support(choiceName)
StructName{structAssignmentList} // support has no SupportStruct
field = support(choiceName) SupportStruct{structAssignmentList}
StructName{structAssignmentList}

; <tt>structName</tt>
: The name of a <tt>struct</tt>
; <tt>choiceName</tt>
: UTF-8 string that describes the choice. Each support must have a unique name.
; <tt>supportStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the support. recordSupport normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.

Assume the following definitions:
record(AiRecord) {
...
field(in,link)
...
}
...
struct(PvMonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
support(monitorLink,PvMonitorLink)
support(inputLink,PvInputLink)
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
support(someVmeADC,VME)

The first example instance definition selects a monitor link.
AiRecord aiMonitorExample = {
...
in = {support(monitorLink)
PvMonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link.
AiRecord aiInputExample = {
...
in = {support(inputLink)
PvInputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example selects support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {support(someVmeADC) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

menuStructBase.dbd defines definitions for Channel/Database Access Links.
The base supplied support registers each choiceName in the support definitions.
The complete set of data structure and support definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* monitor
* input
* output
* process

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== support definitions ===

support(asynInt32,AsynLink)
support(asynInt32Average,AsynLink)
support(asynInt32Monitor,AsynLink)
support(asynFloat64,AsynLink)
support(asynFloat64Average,AsynLink)
support(asynFloat64Monitor,AsynLink)
support(asynDigitalMonitor,AsynLink)
support(asynDigital,AsynLink)
support(asynInt32Array,AsynLink)
support(asynFloat64Array,AsynLink)
support(asynOctet,AsynLink)

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
Whenever possible support should implement the standard interfaces
supplied by EPICS base, since these are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
boolean getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual bool getBounds(int16_t &low, int16_t &high) = 0;
};

== Link and MonitorLink ==

All support must register interface <tt>Link</tt>
and if it supports monitors interface <tt>MonitorLink</tt>.
NOTE: arguments and return types ignored for now
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally recordSupport does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

== asynDigital Support ==

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
boolean getBounds(Int16 low, Int16 high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,Int64 data);
boolean getBounds(Int64 low, Int64 high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and support definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initialize vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkResult put(Callback callback, Int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

----
<center>
= Discussion of link support interfaces =
</center>

== Overview ==
The definitions: record link, support, record instance links,
and the link interfaces are designed to support channel/database links,
links to hardware support, and links to other types of support.

The following are two important requirements:
* analog I/O
** link support can return raw value. Support must convert to engineering units.
** link support can return engineering units
* output records
** Can link support provide initial value?
** What if multiple sources can change linked output?

Lets consider each of these separately.
== Analog I/O ==
In V3 the aiRecord and aoRecords are responsible for conversion between
raw values and engineering units. Raw values are 32 bit integers. Device
support is responsible for setting the slope and intercept fields of the record.
recordSupport takes care of the actual conversions.
Device support can tell recordSupport that it set the engineering units
rather than a raw value by a different return value.

For V4 the following is done:

aiRecord and aoRecord both have the following fields:

menu(menuConvert) {
choice(menuConvertRaw, "None")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(eguf,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

...
field(convert, menu(menuConvert))
field(linearConvert, struct(LinearConvert))
field(convertTable,string);
field(units, string)

If a record instance has convert set to None then recordSupport does the following.
* if link support implements LinkFloat64 it just calls this to obtain an engineering units value
* otherwise it gets a value via interface LinkInt32 and converts the value from in int32 to a float64.

If a record instance has convert linear
* if link support implements LinkInt32 it uses LinkInt32 otherwise it uses LinkFloat64
* it uses slope and interccept to convert from raw to engineering units

<tt>LinkInt32</tt> is defined as:
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If convert is linear and getBounds returns true than recordSupport
uses the returned value to compute slope and intercept. In all
other cases recordSupport just uses whatever values they have.

For example support for a 16 bit unipolar ADC would set low=0, high=65535,
and return true.
If link support can not determine the bounds then getBounds returns false.

NOTE:The interface implemented by breakpoint tables must be defined.
It will support the same semantics as the V3 breakpoint tables.

== Output Records ==

The following are two features that link support should implement
whenever possible:
# When a record is initalized provide the current value of the output
# If something else modifies the actual output value in the record

The first feature is especially desirable when an IOC is rebooted.
If a hardware output can survive a reboot this is a very desirable feature.
If the output is to a field bus, a PLC, or to a record in another IOC
it is often possible for the link support to determine the current value.

The second feature is something that was often asked for in V3 but
only implemented
for some special cases. This is especially desirable when the output is
connected to a system that can have multiple sources of control.
Examples are GPIB devices with front pannel controls, PLC systems that
have manual controls or non-epics network access.

For V3 some of the hardware , but none of the soft,
support implemented the first feature but by
modifying actual fields in the record. V3 did not implement the second
feature. Some special device support, not part of base, was implemented
to support this feature.

For V4 these features are supported as follows:

=== record initialization ===

The link support implements an interface that has a put and a get method.
For example:

interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If the link support can support readbacks then it implements get
and returns linkDone. If it does not support readbacks
then it implements get by just returning linkNoop.

=== monitors for outputs ===

If output link support can detect when something besides the link support
itself modifies the output then it implements interface <tt>MonitorLink</tt>
interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}
At initialization recordSupport looks for this interface and if found
it calls <tt>addMonitor</tt>. The link support calls the callback whenever
it detects a change in the output that it did not cause. recordSupport
causes itself to be processed without making a new call to the
link support.
---
<center>
= Struct Support =
</center>
== support for RecordCommon ==
This implements the same interface a record support.
== support for LinearConvert ==
This implements the interface
interface LinearConvertSupport {
convert(int32 raw,Float64 value) // from raw to eng
convert(float64 value,Int32 raw) // from eng to raw
}

In addition it provides a factory
interface LinearConvertFactory {
LinearConvertSupport(string choiceName,
DbfStruct linearConvert,DbfLink inlink)
}
== support for simulation ==
This needs to be defined.
== support for breakpoint tables ==
This needs to be defined.

V4 Design: Record Processing

2005-11-01T20:09:11Z

MartyKraimer:

EPICS V4: Record Processing November 01 2005

----

= Overview =

UNRESOLVED ISSUES
* This document is still evolving
* Monitors
** How will monitor data be managed?
** Big problem is how will array data be managed?
* Alarms
** How will V4 handle alarms?
* Events
** What is the V4 event model?
** What is required from the IOC database?

This document described semantics for V4 record processing that are
different than for V3.
This includes the following:
* Semantics for record processing
* Semantics for Database and Channel Access Links.
* Record Locking
* Posting database monitors
* Status and Alarm Severity
* Access to array and structure fields.

This version is based on feedback from the EPICS core developer's
meeting at ANL/APS on July 11th through July 14th.
In addition discussions with Andrew Johnson and Eric Norum have
led to many of the ideas described below.
This wiki is a companion to the wiki "V4 Design: dbdInterfaces".

V3 record processing semantics do not work well for data
acquisition applications. An example of data acquisition is:
* Move sample to new position.
** Several motors may be involved
** While moving post monitors to show current position, etc.
* Sample data
* Wait until CA client has fetched the data before next move.

SynAPPS provides the Scan, motor, etc records which help with
data processing applications. These records process as follows:

* Record does not complete processing until all inputs, outputs, etc done. Not completing means that they do not call recGblFwdLink until all proccessing is complete. Note that recGblFwdLink is what causes the V3 ioc to complete record processing.
* While waiting for asynchronous events these records have PACT=0 but keep state that shows it is still active
* Can be scanned and issue monitors while internal state is active

Leaving PACT 0 but not calling recGblFwdLink was not anticipated when the V3 record processing semantics were created.
For V4 a record can be processed while it is waiting
for asynchronous processing to complete.

In V3, if an input link is asynchronous, Process Passive does not wait
for asynchronous processing to complete before fetching data.
This also complicated data acquisition applications.

V4 record processing is designed to make data acquisition easier.
Both input and output links can wait for record processing.
This is done, however, without record support blocking.
If blocking makes it easier to implement record support,
then the support can spawn a separate thread that does block.
Record support can communicate with the separate thread to decide when
to complete record processing.

----

<center>
= Overview of V4 Record Processing =
</center>

V4 will provide something analogous to V3 dbProcess.
The name may be different but for now it will still be called dbProcess.

In V4 database access and channel access appear the same to record and
link support.
Only the implementation knows the difference.
In this document the term channelAccess will mean access to a record.
Thus it can mean a workstation client or a field of
a record that is a link to a record.

V4 also allows support for struct fields.
In particular base provides support for
field(common,struct(RecordCommon))
This field appears as the first field in the record types provided with base
and can also appear as the first field of other types.
The fields in RecordCommon are the V4 replacement for
the V3 dbCommon fields.

V4 record processing has the following features.

* database fields
** "owned" by database not record support
** fields can only be accessed via interfaces
** support can optionally provide storage for data associated with a field
** for channelAccess all fields appear as type primitive, string, struct, array or combination thereof
* dbProcess
** processes synchronous linked records by queuing requests rather than recursive calls to dbProcess
** can be called an arbitrary number of times while record is active
* link
** always has associated support
** can be record link or can be something else, e.g. a link to hardware
* record link
** can request process and/or wait for asynchronous completion
** local synchronous requests queued by dbProcess
** record is active and can be processed while asynchronous links active
* struct fields
** Can have associated support which can be synchronous or asynchronous
* block
** is requested via a separate field
** if true than support waits for all outstanding I/O to complete before calling link or struct support
** if false than asynchronous support can proceed in parallel
* lock
** record instances are locked
** dbProcess locks before calling support
** other code can also lock
** Two records can be locked without deadlock
* monitors
** dbProcess handles monitors
** support triggers monitors by writing to fields

<center>
= Database Fields =
</center>
== Field Access by Support Code ==
Support code can access database fields only via interfaces implemented by
the IOC database.
Thus record fields are owned by the IOC database not by record support.

Support code can register to provide storage for particular fields.
For example support code could implement a circular buffer for field <tt>value</tt>.
When some other code
request the array associated with <tt>value</tt>, the IOC database
calls the support. The support returns the first portion of the circular
buffer and the caller must make an additional call to retrieve the rest of
the circular buffer.

== Field Access by Channel Access ==

For V4 database access and channel access appear the same to record
instances.
It is only the code that implements link support that knows the difference.
If a linked record is local, database access is used, and, if the record
is remote, channel access.

V4 allows channel access to the following types of fields:

* primitive types
* string
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** struct
** array of primitive or string or struct

For other database field types, i.e. links, the database will make the field
appear as one of the above types. For example a link field will appear
as a string with syntax that matches the information associated with the link.
For example a process link will have a string something like
support(processLink) PvProcessLink(pvname = 'pvname'; wait = true)
where
; <tt>processLink</tt>
: selects the support for a process link
; <tt>PvProcessLink</tt>
: Names the struct that the support uses for configuration information

<center>
= Record Processing Semantics =
</center>

This section describes the semantics implemented by dbProcess.

The following are involved in record processing
* dbProcess
** implements a queue for local records that are processed because of record links
** posts monitors caused by field changes during record processing
* record support
** calls support code for RecordCommon fields
** is responsible for record instance fields
** calls link/struct support via interfaces implemented by the support
* link support
** can be links to other records, to driver support, etc
** implements interfaces called by record and/or other support
* struct support
** is responsible for all fields in the struct
** implements interfaces called by record and/or other support

== Processing Life Cycle ==
Assume a record instance is idle, i.e. is ready to start processing.
*dbProcess calls record support with one of the following states
** processCancel - record support must terminate any outstanding processing
** processStart - start processing. record support returns one of
*** processDone - All done and successful
*** processQuit - dont do any more processing. Return to idle state
*** processActive - not done. Call again
** processContinue - another request to process while record is active. Record support again returns one of the above.

Record support, with associated link/struct support does the following:
* When it is called for processStart
** calls the support for RecordCommon with state processStart. it returns
*** processDone - Record support starts processing record specific fields
*** processQuit - Record support just returns processQuit to dbProcess
*** processActive - Record returns processActive. It will be called again with state processContinue. It calls RecordCommon support with state processActive. This continues until Record Common returns processDone or processQuit
* When RecordCommon returns processDone it starts processing record specific fields
** Associated link or struct support may be called
*** Record support implements any <tt>block</tt> fields.
*** It detects when asynchronous support completes
*** as long as there is incomplete asynchronous support it returns processActive to dbProcess
** When all record specific fields have been processed it calls RecordCommon suport with state processQuit
*** RecordCommon support can return processActive. Until it returns processDone, record support just returns processActive to dbProcess
** When RecordCommon returns processDone, record support returns processDone to dbProcess.

struct and link fields can have associated support
* associated support may be asynchronous
** support returns indicating that it is active
** support is required to detect when asynchronous support completes
** when processing is complete support returns indicating that it is done.
* whenever record support returns to dbProcess, dbProcess posts any fields that were modified.
** record may be active or done
* when record support returns processDone or processQuit record is again set idle.

== record common ==

These fields are optional but it is expected that most record
types will include a standard set of fields.

The support for RecordCommon processes the following fields:

* at the beginning of record processing
** disable - if true NO processing will be done, i.e. processQuit is returned
** scanDisable
*** has associated support
*** if record is scan disabled processQuit is returned
** alarm fields
*** alarm handling is described below
* after record support completes
** processLink array
*** has associated support

== record support ==

Record support is responsible for all its fields.
For link and struct fields there may be associated support which
may be synchronous or asynchronous.
Record support communicates with
the link/struct support via interfaces that are implemented by the support.
If the record includes a field for struct(RecordCommon) it should
use the associated support for its fields.

Record support may be called multiple times by dbProcess while a record instance
is active.
One of the arguments to process is ProcessState which has the values:
* processCancel - Cancel any outstanding activity
* processStart - Start processing
* processContinue - Making additional call

process returns ProcessReturn which is one of the following:
* processDone - Done and successful
* processQuit - Do not do any more processing
* processActive - Not done

If record support returns processActive it must keep internal state so
that it knows how to handle processCancel and processContinue.

For record support the above rules allow:
* process can be called repeatedly. This will continue as long as it returns processActive
* Everytime process returns processActive DbProcess posts monitors.

== Record Locking ==

V3 implemented lock sets in order to prevent different threads
from simultaneously accessing linked records.

Instead of lock sets V4:
* implements a per record instance lock.
* defines a rule that allows two records to be locked without deadlocks

== Posting Monitors ==

In V3 monitors are posted when code (record support, device support, database access, etc) calls db_post_event. In V4 database access will itself handle
the posting of monitors.

Monitors are posted by DbProcess when
* record support returns processActive.
* at the end of record processing.

<center>
= link/struct Semantics =
</center>

Both link and struct fields can have associated support.
The support can be synchronous or asynchronous.

Support code implements interfaces.
Code that is responsible for a field communicates with the support via
the interface. Lets call this code the client.

Each link and struct field has a well defined client.
* dbProcess is the client for fields in dbCommon
* record support is the client for the other top level fields in a record
* the struct support is the client for any link or struct fields in the struct

A link/struct may have an associated block. The client is responsible for
implementing block. If block is true then the support will not be called
until all outstanding record activity completes.

<center>
= channelAccess links =
</center>

channelAccess link means access to a record or field. The requester can be:
* A database link in a record
* A channel access link in a record
* A workstation channel access client

A channelAccess link is one of the following types:
* Monitor Link
** Implemented via a monitor request on linked field
** Optionally process record containing the link when monitor value is returned.
* Input Link
** Optionally request that record be processed.
** Optionally wait for linked record to complete processing.
** Get value.
* Output Link:
** Put value
** Optionally request processing. If record can not be processed should the value be changed?
** Optionally wait until completion
* Process Link: Perform the following actions
** Request processing
** Optionally wait until linked record completes

NOTES:
* processLink is the replacement for the V3 forwardLink
* wait does NOT mean to wait synchronously. It means to save state, return, and resume at the saved state when called again.

Links are processed as follows:

The following rules apply when a process request is made:
* If record is already being processed the request is just ignored
* record support can specify that links to particular fields not cause processing.
** Where should this be specified? In the Database Definition, the record instance, or both.
** If a process request is allowed, should it be done regardless of the scan mechanism, i.e. the record does not have to be passive?

----
<center>
= Mutual Exclusion =
</center>

V3 implemented lock sets, i.e. when a record was being processed it and all records linked via database links were locked.

Lock sets solved two Mutual Exclusion problems:
* V3 allowed dbProcess to be called recursively.
** process passive database links and forward links were implemented via recursive calls to DbProcess
** Lock sets prevented deadly embrace problems for circular links.
* No puts could be done to an record in a lock set while record processing is active.
** For synchronous records this guarantees that no fields are modified except by record processing itself.
** For asynchronous records this guarantee is not valid.

V4 does not call dbProcess recursively. Instead a process request is queued.
The request fails if either of the following is true:
* The record is active.
* The record is already queued.

dbProcess itself manages the queue , which is FIFO.
When record support returns the first entry in the queue is processed.
In addition if link or struct support completes before the queue
is empty, a request to process the record containing the link/struct will
be added to the same queue.
Thus if a set of synchronous records are processed they will complete processing
without any context switch.

Question What about periodically scanned records? Needs thought.

This leaves the question of what should be done about mutual exclusion.

For V4 there will be two locks associated with the IOC database:
1) a global lock, and 2) A per record instance lock.

The global lock must be taken
whenever the structure of the database is modified. Examples are
1) adding new record types, 2) adding new record instances, and 3) modifying
database links. Global locks are not discussed further in this document.

Each record instance has an associated lock.
When dbProcess is called it takes the lock.
Before it returns it unlocks.
Thus record support does not need to lock or unlock.

Other code that needs access to fields of a record instance must
lock before accessing any fields and unlock after all accesses are complete.

This leaves the problem of how to access fields from two different record
instances simultaneously. For example code that implements database
access needs such access. Code that needs such access must call dbLockLink before accessing the linked record and dbUnlockLink after access.

dbLockLink is implemented as follows:
* Each Record instances has a unique ordinal number
* Assume Record X has a link to record Y
* If the ordinal number of X is less than that of Y
** Just call dbLock for record Y
* If the ordinal numnber of X is greater than that of Y
** call dbUnlock for X
** call dbLock for Y
** call dbLock for X

----
<center>
= Posting Modifications =
</center>

The document "V4 Design: dbdIterfaces" provides a design that allows
database access to handle all posting on monitors without requiring
any help from the code that modifies database fields.
It can do this because fields can be modified only via an
interface implemented by database access.

dbProcess posts monitors when:
* When record support returns processActive.
* When it finishes record processing.

How to implement monitors must be decided.

----
<center>
= Alarm Processing =
</center>

Question Will V4 alarm handling be different than V3? If so this section
may be meaningless.

The V4 semantics for status and severity have the following goals:
* alarmSeverity has the same values as for V3
* alarmStatus is a string
* a record starts processing with alarmSeverity = "NO_ALARM" and status empty.
* status will ONLY be posted if it has changed since the last time it was posted.
* alarmSeverity will ONLY be posted if it has changed since the last time it was posted

The semantics, which are implemented by recordCommon, are:

* When recordCommon is called with processStart
** A private variable newSeverity is set to NO_ALARM
** A private variable prevSeverity is set to alarmSeverity
* When recordCommon completes its part of record processing
** If newSeverity is NO_ALARM and prevSeverity has a different value
*** alarmSeverity is set to NO_ALARM
*** alarmStatus is set to empty

* When the recordCommon.setSeverity(sevr,status) is called
** If sevr is less than or equal to newSeverity nothing is done
** else
*** alarmSeverity is set to sevr
*** alarmStatus is set to status
*** newSeverity is set to sevr

NOTE: alarmStatus and alarmSeverity are written by the normal method.
This means that their values will be posted.
----
<center>
= Channel Access/ Database Access field types =
</center>

== Overview ==

This section discusses how IOC database fields are accessed by channel access
or via database links.

For the initial V4 implementation only the following types of data
will be accessable.

* primitive types
* string
* enum
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** enum
** struct (use recursion for allowed types)
** one dimensional array of primitive or string or struct

The dbdInterfaces document defines database field types.
It also defines a subset called basic types, which consists
of primitive types, string, array, and structure.
For external access only basic types can be accessed.
This means that structures and arrays that do not consist of basic types
are not accessablevia clannelAccess. For example a DbfLink is
not accessable via channel access as a DbfLink.

Non basic fields will only be available via some combination of basic types.

For example a DbfLink field will appear as a string.
If a Database Definition is

struct(calcInpLink) {
field(block,boolean)
field(link,link)
field(value,float64)
};

record(xxx) {
field(link,link)
field(value,float64)
...
field(inp,array(struct(calcInpLink)[]))
...
}

If a client attaches to
record.field(link)
The data will be appear in the form:
choice(choiceName) SupportStruct(pvname= ,;...)
where <tt>choiceName</tt> is the name of the link support, <tt>SupportStruct</tt> is the name of the support struct asociated with the support, and the arguments are the values for the support structure.

Then if a client specifies the process variable:
record.field(inp[1].link)
Then it connects to the link field of the second calcInpLink of field inp.

== primitive types ==

This includes DbfBool, DbfOctet, DbfInt16, ... , DbfFloat64.
These do not present any problems. The scalar value is transfered.

== string ==

A string is just a UTF_8 encoded character string

== DbfMenu and DbfEnum ==

Handled as an enum

== DbfLink ==

Both of these have the following:

* <tt>choiceName</tt> A string that selects the link support.
* <tt>dataStructName</tt> Each support has an associated struct for configuration.

How should these be made available? Perhaps:

The field appears as a string with the following syntax:

<tt>choiceName(structAssignmentList)</tt>

where structAssignmentList has the same syntax as defined in "V4 DB Record Instance Syntax"

== timeStamp ==

This is just transfered like a struct with two fields:
* int64 secondsSinceEpoch
* int32 nanoSeconds

== struct ==

The database definition syntax allows a struct to be composed of fields
of any DbfType.
Database access, however, will only allow access to structs with fields
of the following types:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfArray of primitive type or string
* DbfStruct - As long as its fields are valid types

The individual fields can be accessed directly so this discussion
only involves access to the entire structure.

Access will only be available to clients that have knowledge of
fields within the structure. For channel access clients this means that
they provide a propertyCatalog that has some subset of the fields in the structure.

== array ==

Arrays of the following types are accessable:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfStruct - As long as its fields are valid types

Note that arrays of structs are not accessable in the early V4 releases.

Arrays still need lots more discussion!!!
The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.

For the initial V4 version, database access only allows access to arrays of the following types.
* primitive - DbfBool,...,DbfFloat64
* DbfString
* ???? What else

An individual element of an array of type DbfStruct can be accessed
directly if it satisfies the criteria for accessing a DbfStruct.

Question: Should database Access be implemented so that record/link support can transfer an array in segments. Examples:
* If the array is a circular buffer, it is presented in two segements
* If the array is stored in hardware, e.g. a transient recorder, the array can be read from the hardware and passed to the client in segments.

If an array is available only in segments then can we
prevent two clients from trying to access the same array simultaneously?

Perhaps this is a problem that must be solved by an application:
* runControl records are one solution
* Other solutions can be envisioned

== MDArray ==

Not implemented if the early V4 releases.

== Associated Data ==

The typical example is a client that asks for timeStamp, severity, status,
and data.

V4 Link Support Tutorial

2005-10-26T18:17:33Z

MartyKraimer: added discussion about analog conversion and special support for output records

EPICS: IOC Link Support Tutorial Oct 26 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))
A record instance link definition has the syntax:
field = { choice(interfaceName) {structAssignmentList}}
or
field = { choice(interfaceName) dataStructName {structAssignmentList} }

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands or that link support implements.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with link support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.
; <tt>choice</tt>
: Selects a link with <tt>choiceName</tt> = <tt>choice</tt>

A record instance link definition selects a link as follows:
* The linkDirections must be compatible
** Except for inout the record link and link directions must be the same
** If record link specifies inout the link can specify either in or out or inout
* The interfaceName specified by the record instance must be in the record link interface list and in the link interface list.
* The dataStructName specified in the record instance must match the dataStructName in the link definition.

Assume the following definitions:
record(AiRecord) {
...
field(in,link(in,interface(LinkInt64,LinkFloat64)))
...
}
struct(PvMonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
link(in,monitorLink,PvMonitorLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLink,PvInputLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
...
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
link(in,someVmeADC,VME, interface(LinkInt32))

The first example instance definition selects a monitor link. It selects interface LinkInt32, which means the support will provide a "raw" value that the
record support will convert to engineering units.
AiRecord aiMonitorExample = {
...
in = {monitorLink(LinkInt32)
PvMonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link. It selects interface
LinkFloat64, which means the support will provide a value in engineering units.
It asks that the linked record be processed and that the link not complete
until the linked record completes processing.
AiRecord aiInputExample = {
...
in = {inputLink(LinkFloat64)
PvInputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example selects support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {someVmeADC(LinkInt32) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.
This support registers each choiceName in the link definitions.
The complete set of data structure and link definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* monitor
* input
* output
* process

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLink,interface(LinkInt32))
link(in,asynInt32Average,AsynLink,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
link(inout,asynDigital,AsynLink,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLink,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
Whenever possible support should implement the standard interfaces
supplied by EPICS base, since these are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
boolean getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual bool getBounds(int16_t &low, int16_t &high) = 0;
};

== Link and MonitorLink ==

All support must register interface <tt>Link</tt>
and if it supports monitors interface <tt>MonitorLink</tt>.
NOTE: arguments and return types ignored for now
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

== asynDigital Support ==

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
boolean getBounds(Int16 low, Int16 high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,Int64 data);
boolean getBounds(Int64 low, Int64 high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and link definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initialize vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkResult put(Callback callback, Int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

----
<center>
= Discussion of link support interfaces =
</center>

== Overview ==
The link definitions: record link, link, record instance links,
and the link interfaces are designed to support channel/database links,
links to hardware support, and links to other types of support.

The following are two important requirements:
* analog I/O
** link support can return raw value. Support must convert to engineering units.
** link support can return engineering units
* output records
** Can link support provide initial value?
** What if multiple sources can change linked output?

Lets consider each of these separately.
== Analog I/O ==
In V3 the aiRecord and aoRecords are responsible for conversion between
raw values and engineering units. Raw values are 32 bit integers. Device
support is responsible for setting the slope and intercept fields of the record.
Record support takes care of the actual conversions.
Device support can tell record support that it set the engineering units
rather than a raw value by a different return value.

NOTE:Perhaps in V4 aiRecord should be separated into two records,
e.g. a record that always uses float values and an ADC record which handles
raw values. Another possibility is special link support that provides
floating values to the record support and links to the actual hardware support.
For this discussion it is assummed that aiRecord and aoRecord are still
responsible for conversions since most of the discussion is
independent of how the record support is structured.

For V4 the following is done:

aiRecord and aoRecord both have the following fields:

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(eguf,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

...
field(convert, menu(menuConvert))
field(linearConvert, struct(LinearConvert))
field(convertTable,string);
field(units, string)

The link field for aiRecord is
field(in,link(in,interface( LinkInt32, LinkFloat64)))

The link field for aoRecord is
field(out,link(out,interface( LinkInt32, LinkFloat64)))

When a record instance is defined the link specifies the interface to use.
If the interface is:
* <tt>LinkInt32</tt> - Then the link support supplies raw values
* <tt>LinkFloat64</tt> - Then the link support supplies engineering units

<tt>LinkInt32</tt> is defined as:
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
void getBounds(Int32 low, Int32 high);
}
Thus link support is responsible for returning the ADC bounds.
For example support for a 16 bit unipolar ADC would set low=0, high=65535,
and return true.
If link support can not determine the bounds then getBounds returns false.

If the link interface is LinkFloat64 then record support does no conversion.
Thus the following only applys if the interface is LinkInt32.

Record support handles conversions as follows:
* Raw - The value obtained from the link support is converted to a double.
* Linear
** If link support returned the bounds record support computes slope and intercept
** otherwise it uses the slope and intercept from instance definition
* Table - The interface implementation for convertTable is located and used.

NOTE:The interface implemented by breakpoint tables must be defined.
It will support the same semantics as the V3 breakpoint tables.

== Output Records ==

The following are two features that link support should implement
whenever possible:
# When a record is initalized provide the current value of the output
# If something else modifies the actual output value in the record

The first feature is especially desirable when an IOC is rebooted.
If a hardware output can survive a reboot this is a very desirable feature.
If the output is to a field bus, a PLC, or to a record in another IOC
it is often possible for the link support to determine the current value.

The second feature is something that was often asked for in V3 but
only implemented
for some special cases. This is especially desirable when the output is
connected to a system that can have multiple sources of control.
Examples are GPIB devices with front pannel controls, PLC systems that
have manual controls or non-epics network access.

For V3 some of the hardware , but none of the soft,
support implemented the first feature but by
modifying actual fields in the record. V3 did not implement the second
feature. Some special device support, not part of base, was implemented
to support this feature.

For V4 these features are supported as follows:

=== record initialization ===

The link support implements an interface that has a put and a get method.
For example:

interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
boolean getBounds(Int32 low, Int32 high);
}

If the link support can support readbacks then it implements get
and returns linkDone. If it does not support readbacks
then it implements get by just returning linkNoop.

=== monitors for outputs ===

If output link support can detect when something besides the link support
itself modifies the output then it implements interface <tt>MonitorLink</tt>
interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}
At initialization record support looks for this interface and if found
it calls <tt>addMonitor</tt>. The link support calls the callback whenever
it detects a change in the output that it did not cause. Record support
causes itself to be processed without making a new call to the
link support.

V4 Link Support Tutorial

2005-10-25T19:29:24Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Oct 25 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))
A record instance link definition has the syntax:
field = { choice(interfaceName) {structAssignmentList}}
or
field = { choice(interfaceName) dataStructName {structAssignmentList} }

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands or that link support implements.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with link support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.
; <tt>choice</tt>
: Selects a link with <tt>choiceName</tt> = <tt>choice</tt>

A record instance link definition selects a link as follows:
* The linkDirections must be compatible
** Except for inout the record link and link directions must be the same
** If record link specifies inout the link can specify either in or out or inout
* The interfaceName specified by the record instance must be in the record link interface list and in the link interface list.
* The dataStructName specified in the record instance must match the dataStructName in the link definition.

Assume the following definitions:
record(AiRecord) {
...
field(in,link(in,interface(LinkInt64,LinkFloat64)))
...
}
struct(PvMonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
link(in,monitorLink,PvMonitorLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLink,PvInputLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
...
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
link(in,someVmeADC,VME, interface(LinkInt32))

The first example instance definition selects a monitor link. It selects interface LinkInt32, which means the support will provide a "raw" value that the
record support will convert to engineering units.
AiRecord aiMonitorExample = {
...
in = {monitorLink(LinkInt32)
PvMonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link. It selects interface
LinkFloat64, which means the support will provide a value in engineering units.
It asks that the linked record be processed and that the link not complete
until the linked record completes processing.
AiRecord aiInputExample = {
...
in = {inputLink(LinkFloat64)
PvInputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example selects support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {someVmeADC(LinkInt32) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.
This support registers each choiceName in the link definitions.
The complete set of data structure and link definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* monitor
* input
* output
* process

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLink,interface(LinkInt32))
link(in,asynInt32Average,AsynLink,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
link(inout,asynDigital,AsynLink,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLink,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
Whenever possible support should implement the standard interfaces
supplied by EPICS base, since these are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
void getBounds(Int16 low, Int16 high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t &data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
virtual void getBounds(int16_t &low, int16_t &high) = 0;
};

== Link and MonitorLink ==

All support must register interface <tt>Link</tt>
and if it supports monitors interface <tt>MonitorLink</tt>.
NOTE: arguments and return types ignored for now
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

== asynDigital Support ==

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
void getBounds(Int16 low, Int16 high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
void getBounds(Int32 low, Int32 high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,Int64 data);
void getBounds(Int64 low, Int64 high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and link definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initialize vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkResult put(Callback callback, Int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

V4 DB RecordCommon

2005-10-25T19:07:05Z

MartyKraimer:

EPICS V4: Standard Support October 25 2005
----

= Overview =

This document describes three base supplied components for EPICS V4 databases.
# menuStructBase.dbd - menu and struct definitions
# recordCommon.dbd - common fields for record definitions
# baseSupport.dbd - link definitions for base supplied support

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

NOTE: This document is ahead of the two above V4 documents so it may use
slightly different syntax.
----
<center>
= menuStructBase.dbd =
</center>

== Channel/Database Access Links ==

struct(PvProcessLink) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
}
struct(PvMonitorLink) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
struct(PvOutputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}

== asynDriver Link ==
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

== Definitions for recordCommon ==

# menu definitions for recordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}

#struct definitions for recordCommon
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in,interface(????))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in,interface(LinkBoolean)))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

struct(ProcessLink) {
field(block,boolean)
field(link,link(process,interface(ProcessLink)))
}

== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= recordCommon.dbd =
</center>
This is a file that is included by most of the record types provided by
base. For example
#include "menuStructBase.dbd"
record(AiRecord) {
#include "recordCommon.dbd"
...
}

<tt>recordCommon.dbd</tt> contains the following definitions
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmNoAckTransient,menu(menuAlarmSevr)) {
# highest level of alarm that does not have to be acknowledged"
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(ProcessLink[])) {
special(yes)
}

Although it has many fewer fields,
recordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be private to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

----
<center>
= baseSupport.dbd =
</center>

== Channel/Database Access Support ==

Link support is provided for
* monitor support
* input support
* output
* process

For monitor, input, and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(process,processLink,PvProcessLink,interface(LinkProcess))

link(in,monitorLink,PvMonitorLink,interface(
LinkOctet,LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,monitorLinkArray,PvMonitorLink,interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,inputLink,PvInputLink, interface(
LinkOctet,LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLinkArray,PvInputLink, interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(out,outputLink,PvOutputLink, interface(
LinkOctet,LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(out,outputLinkArray,PvOutputLink, interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))

== asynDriver support ==

link(inout,asynInt32,AsynLink,interface(LinkInt32))
link(in,asynInt32Average,AsynLink,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
link(inout,asynDigital,AsynLink,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLink,interface(AsynOctet)))

V4 Link Support Tutorial

2005-10-25T18:35:13Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Oct 25 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))
A record instance link definition has the syntax:
field = { choice(interfaceName) {structAssignmentList}}
or
field = { choice(interfaceName) dataStructName {structAssignmentList} }

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands or that link support implements.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with link support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.
; <tt>choice</tt>
: Selects a link with <tt>choiceName</tt> = <tt>choice</tt>

A record instance link definition selects a link as follows:
* The linkDirections must be compatible
** Except for inout the record link and link directions must be the same
** If record link specifies inout the link can specify either in or out or inout
* The interfaceName specified by the record instance must be in the record link interface list and in the link interface list.
* The dataStructName specified in the record instance must match the dataStructName in the link definition.

Assume the following definitions:
record(AiRecord) {
...
field(in,link(in,interface(LinkInt64,LinkFloat64)))
...
}
struct(PvMonitorLink) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
link(in,monitorLink,PvMonitorLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLink,PvInputLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
...
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
link(in,someVmeADC,VME, interface(LinkInt32))

The first example instance definition selects a monitor link. It selects interface LinkInt32, which means the support will provide a "raw" value that the
record support will convert to engineering units.
AiRecord aiMonitorExample = {
...
in = {monitorLink(LinkInt32)
PvMonitorLink {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link. It selects interface
LinkFloat64, which means the support will provide a value in engineering units.
It asks that the linked record be processed and that the link not complete
until the linked record completes processing.
AiRecord aiInputExample = {
...
in = {inputLink(LinkFloat64)
PvInputLink {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example attaches the link to support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {someVmeADC(LinkInt32) VME {a16 = 0xc000; channel = 1} }

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.
This support registers each choiceName in the link definitions.
The complete set of data structure and link definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* monitor
* input
* output
* process

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLink,interface(LinkInt32))
link(in,asynInt32Average,AsynLink,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
link(inout,asynDigital,AsynLink,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLink,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
Whenever possible support should implement the standard interfaces
supplied by EPICS base, since these are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++.
It can easily be translated to C++ syntax. For example the
definition:
interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
void getBounds(<type> low, <type> high);
}
In C++ would be:
class LinkInt16 {
public:
virtual LinkResult get(Callback &callback, int16_t *data) = 0;
virtual LinkResult put(Callback &callback, int16_t data) = 0;
};

== Link and MonitorLink ==

NOTE: arguments and return types ignored for now
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkResult get(Callback callback, Octet data);
LinkResult put(Callback callback, octet data);
}
interface LinkArrayOctet {
LinkResult get(Callback callback, octet[] data);
LinkResult put(Callback callback, octet[] data);
}

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkResult write(Callback callback,octet[] value, octet[] mask);
LinkResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkResult get(Callback callback,Boolean data);
LinkResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkResult get(Callback callback,boolean[] data);
LinkResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.

interface LinkInt16 {
LinkResult get(Callback callback,Int16 data);
LinkResult put(Callback callback,Int16 data);
void getBounds(<type> low, <type> high);
}
interface LinkArrayInt16 {
LinkResult get(Callback callback,int16[] data);
LinkResult put(Callback callback,int16[] data);
}
interface LinkInt32 {
LinkResult get(Callback callback,Int32 data);
LinkResult put(Callback callback,Int32 data);
void getBounds(<type> low, <type> high);
}
interface LinkArrayInt32 {
LinkResult get(Callback callback,int32[] data);
LinkResult put(Callback callback,int32[] data);
}
interface LinkInt64 {
LinkResult get(Callback callback,Int64 data);
LinkResult put(Callback callback,Int64 data);
void getBounds(<type> low, <type> high);
}
interface LinkArrayInt64 {
LinkResult get(Callback callback,int64[] data);
LinkResult put(Callback callback,int64[] data);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.

interface LinkFloat32 {
LinkResult get(Callback callback,Float32 data);
LinkResult put(Callback callback,float32 data);
}
interface LinkArrayFloat32 {
LinkResult get(Callback callback,float32[] data);
LinkResult put(Callback callback,float32[] data);
}
interface LinkFloat64 {
LinkResult get(Callback callback,Float64 data);
LinkResult put(Callback callback,float64 data);
}
interface LinkArrayFloat64 {
LinkResult get(Callback callback,float64[] data);
LinkResult put(Callback callback,float64[] data);
}

== String Support ==
interface LinkString {
LinkResult get(Callback callback,string data);
LinkResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkResult get(Callback callback,string[] data);
LinkResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and link definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initailze vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkResult put(Callback callback, Int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

V4 DB RecordCommon

2005-10-25T18:33:11Z

MartyKraimer:

EPICS V4: Standard Support October 25 2005
----

= Overview =

This document describes three base supplied components for EPICS V4 databases.
# menuStructBase.dbd - menu and struct definitions
# recordCommon.dbd - common fields for record definitions
# baseSupport.dbd - link definitions for base supplied support

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

NOTE: This document is ahead of the two above V4 documents so it may use
slightly different syntax.
----
<center>
= menuStructBase.dbd =
</center>

== Channel/Database Access Links ==

struct(PvMonitorLink) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(PvInputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
struct(PvOutputLink) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
struct(PvProcessLink) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
}

== asynDriver Link ==
struct(AsynLink) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

== Definitions for recordCommon ==

# menu definitions for recordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}

#struct definitions for recordCommon
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in,interface(????))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in,interface(LinkBoolean)))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

struct(ProcessLink) {
field(block,boolean)
field(link,link(process,interface(ProcessLink)))
}

== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= recordCommon.dbd =
</center>
This is a file that is included by most of the record types provided by
base. For example
#include "menuStructBase.dbd"
record(AiRecord) {
#include "recordCommon.dbd"
...
}

<tt>recordCommon.dbd</tt> contains the following definitions
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmNoAckTransient,menu(menuAlarmSevr)) {
# highest level of alarm that does not have to be acknowledged"
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(RecordCommonProcessLink[])) {
special(yes)
}

Although it has many fewer fields,
recordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be privaye to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

----
<center>
= baseSupport.dbd =
</center>

== Channel/Database Access Support ==

Link support is provided for
* monitor support
* input support
* output
* process

For monitor, input, and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(process,processLink,PvProcessLink,interface(LinkProcess))

link(in,monitorLink,PvMonitorLink,interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,monitorLinkArray,PvMonitorLink,interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,inputLink,PvInputLink, interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLinkArray,PvInputLink, interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(out,outputLink,PvOutputLink, interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(out,outputLinkArray,PvOutputLink, interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))

== asynDriver support ==

link(inout,asynInt32,AsynLink,interface(LinkInt32))
link(in,asynInt32Average,AsynLink,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
link(inout,asynDigital,AsynLink,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLink,interface(AsynOctet)))

V4 Link Support Tutorial

2005-10-24T15:17:28Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Oct 24 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))
A record instance link definition has the syntax:
field = { blockValue, choice(interfaceName), {structAssignmentList}}
or
field = { block = blockValue; choiceName = choice(interfaceName);
dataStructName {structAssignmentList{}
}

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.
; <tt>blockValue</tt>
: Must be <tt>true</tt> or <tt>false</tt>
; <tt>choice</tt>
: Selects a link with <tt>choiceName</tt> = <tt>choice</tt>

A record instance link definition selects a link as follows:
* The linkDirections must be compatible
** Except for inout the record link and link directions must be the same
** If record link specifies inout the link can specify either in or out
* The interfaceName specified by the record instance must be in the record link interface list and in the link interface list.
* The dataStructName specified in the record instance must match the dataStructName in the link definition.

Assume the following definitions:
record(AiRecord) {
...
field(in,link(in,interface(LinkInt64,LinkFloat64)))
...
}
struct(MonitorLinkData) {
field(pvname,string)
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string)
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(inheritSeverity,boolean)
}
...
link(in,monitorLink,MonitorLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLink,InputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
...
struct VME{
field(a16,int16)
field(a32,int32)
field(channel,int16)
}
...
link(in,someVmeADC,VME, interface(LinkInt32))

The first example instance definition selects a monitor link. It selects interface LinkInt32, which means the support will provide a "raw" value that the
record support will convert to engineering units.
AiRecord aiMonitorExample = {
...
in = {choiceName = monitorLink(LinkInt32)
MonitorLinkData {
pvname = "someRecord";
process = true;
inheritSeverity = false
}
}
The next example selects a channel access input link. It selects interface
LinkFloat64, which means the support will provide a value in engineering units.
It asks that the linked record be processed and that the link not complete
until the linked record completes processing.
AiRecord aiInputExample = {
...
in = {choiceName = inputLink(LinkFloat64)
MonitorLinkData {
pvname = "someRecord";
process = true;
wait = true;
timeout = 1.0;
inheritSeverity = false
}
}
The last example attaches the link to support for a VME Analog to Digital device.
AiRecord aiMonitorExample = {
...
in = {choiceName = someVmeADC(LinkInt32)
VME {a16 = 0xc000; channel = 1}
}

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.
This support registers each choiceName in the link definitions.
The complete set of data structure and link definitions are defined
in "V4 DB RecordCommon".

Link support is provided for
* monitor
* input
* output
* process

For monitor, input, and output the following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Average,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLinkData,interface(LinkInt32))
link(inout,asynFloat64,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLinkData,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLinkData,interface(AsynDigital))
link(inout,asynDigital,AsynLinkData,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLinkData,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLinkData,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLinkData,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
Whenever possible support should implement the standard interfaces
supplied by EPICS base, since these are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that the support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Link and MonitorLink ==

interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the <tt>link</tt> database
definition since they are generic.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess {
LinkWaitResult process(Callback callback);
}

== Octet Support ==

interface LinkOctet {
LinkWaitResult get(Callback callback, Octet data);
LinkWaitResult put(Callback callback, Octet data);
}
interface LinkArrayOctet {
LinkWaitResult get(Callback callback, octet[] data);
LinkWaitResult put(Callback callback, octet[] data);
}

The data source must be an array of octets or the connect request will fail.

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(Callback callback,octet[] value, octet[] mask);
LinkWaitResult read(Callback callback,octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult get(Callback callback,Boolean data);
LinkWaitResult put(Callback callback,boolean data);
}
interface LinkArrayBoolean {
LinkWaitResult get(Callback callback,boolean[] data);
LinkWaitResult put(Callback callback,boolean[] data);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult get(Callback callback,<type> data);
LinkWaitResult put(Callback callback,<type> data);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult get(Callback callback,<type>[] data);
LinkWaitResult put(Callback callback,<type>[] data);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult get(Callback callback,<type> data);
LinkWaitResult put(Callback callback,<type> data);
}
interface LinkArray<type> {
LinkWaitResult get(Callback callback,<type>[] data);
LinkWaitResult put(Callback callback,<type>[] data);
}

== String Support ==
interface LinkString {
LinkWaitResult get(Callback callback,string data);
LinkWaitResult put(Callback callback,string data);
}
interface LinkArrayString {
LinkWaitResult get(Callback callback,string[] data);
LinkWaitResult put(Callback callback,string[] data);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
Assume the VME and link definitions given in the examples at the beginning
of this document.

The following is presented with Java syntax.
It assumes that there is VME support of the form

public class vme {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VME fromFactory)
{
addr = fromFactory;
connected = false;
// from the VME initailze vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkWaitResult get(Callback callback, Int data)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkWaitResult put(Callback callback, Int data)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VME addr;
int vmeaddr;
int channel;
boolean connected;
}

V4 Design: Record Processing

2005-10-21T14:25:42Z

MartyKraimer:

EPICS V4: Record Processing October 21 2005

----

= Overview =

UNRESOLVED ISSUES
* This document is still evolving
* Monitors
** How will monitor data be managed?
** Big problem is how will array data be managed?
* Alarms
** How will V4 handle alarms?
* Events
** What is the V4 event model?
** What is required from the IOC database?

This document described semantics for V4 record processing that are
different than for V3.
This includes the following:
* Semantics for record processing
* Semantics for Database and Channel Access Links.
* Record Locking
* Posting database monitors
* Status and Alarm Severity
* Access to array and structure fields.

This version is based on feedback from the EPICS core developer's
meeting at ANL/APS on July 11th through July 14th.
In addition discussions with Andrew Johnson and Eric Norum have
led to many of the ideas described below.
This wiki is a companion to the wiki "V4 Design: dbdInterfaces".

V3 record processing semantics do not work well for data
acquisition applications. An example of data acquisition is:
* Move sample to new position.
** Several motors may be involved
** While moving post monitors to show current position, etc.
* Sample data
* Wait until CA client has fetched the data before next move.

SynAPPS provides the Scan, motor, etc records which help with
data processing applications. These records process as follows:

* Record does not complete processing until all inputs, outputs, etc done. Not completing means that they do not call recGblFwdLink until all proccessing is complete. Note that recGblFwdLink is what causes the V3 ioc to complete record processing.
* While waiting for asynchronous events these records have PACT=0 but keep state that shows it is still active
* Can be scanned and issue monitors while internal state is active

Leaving PACT 0 but not calling recGblFwdLink was not anticipated when the V3 record processing semantics were created.
For V4 a record can be processed while it is waiting
for asynchronous processing to complete.

In V3, if an input link is asynchronous, Process Passive does not wait
for asynchronous processing to complete before fetching data.
This also complicated data acquisition applications.

V4 record processing is designed to make data acquisition easier.
Both input and output links can wait for record processing.
This is done, however, without record support blocking.
If blocking makes it easier to implement record support,
then the support can spawn a separate thread that does block.
Record support can communicate with the separate thread to decide when
to complete record processing.

----

<center>
= Overview of V4 Record Processing =
</center>

V4 will provide something analogous to V3 dbProcess.
The name may be different but for now it will still be called dbProcess.

In V4 database access and channel access appear the same to record and
link support.
Only the implementation knows the difference.
In this document the term channelAccess will mean access to a record.
Thus it can mean a workstation client or a field of
a record that is a link to a record.

V4 record processing has the following features.

* database fields
** "owned" by database not record support
** fields can only be accessed via interfaces
** support can optionally provide storage for data associated with a field
** for channelAccess all fields appear as type primitive, string, struct, array or combination thereof
* dbProcess
** is responsible for common fields
** processes synchronous linked records by queuing requests rather than recursive calls to dbProcess
** can be called an arbitrary number of times while record is active
* link
** always has associated support
** can be record link or can be something else, e.g. a link to hardware
* record link
** can request process and/or wait for asynchronous completion
** local synchronous requests queued by dbProcess
** record is active and can be processed while asynchronous links active
* struct fields
** Can have associated support which can be synchronous or asynchronous
* block
** asynchronous support can proceed in parallel
** record instance can request that all active asynchronous support complete before calling link/struct support.
* lock
** record instances are locked
** dbProcess locks before calling support
** other code can also lock
** Two records can be locked without deadlock
* monitors
** dbProcess handles monitors
** support triggers monitors by writing to fields

<center>
= Database Fields =
</center>
== Field Access by Support Code ==
Support code can access database fields only via interfaces implemented by
the IOC database.
Thus record fields are owned by the IOC database not by record support.

Support code can register to provide storage for particular fields.
For example support code could implement a circular buffer for field <tt>value</tt>.
When some other code
request the array associated with <tt>value</tt>, the IOC database
calls the support. The support returns the first portion of the circular
buffer and the caller must make an additional call to retrieve the rest of
the circular buffer.

== Field Access by Channel Access ==

For V4 database access and channel access appear the same to record
instances.
It is only the code that implements link support that knows the difference.
If a linked record is local, database access is used, and, if the record
is remote, channel access.

V4 allows channel access to the following types of fields:

* primitive types
* string
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** struct
** array of primitive or string or struct

For other database field types, i.e. links, the database will make the field
appear as one of the above types. For example a link field will appear
as a string with syntax that matches the information associated with the link.
For example a process link will have a string something like
processLink(pvname = 'pvname', wait = true)

<center>
= dbProcess - Record Processing Semantics =
</center>

This section describes the semantics implemented by dbProcess.

The following are involved in record processing
* dbProcess
** is responsible for the fields in recordCommon
** implements a queue for local records that are processed because of record links
** posts monitors caused by field changes during record processing
* record support
** is responsible for record instance fields
** calls link/struct support via interfaces implemented by the support
* link support
** can be links to other records, to driver support, etc
** implements interfaces called by record and/or other support
* struct support
** is responsible for all fields in the struct
** implements interfaces called by record and/or other support

== Processing Life Cycle ==
Assume a record instance is idle, i.e. is ready to start processing.
The following sequence of events occur:
* dbProcess processes the fields in recordCommon that must be processed before record support is called
** fields that have associated support may be asynchronous
** record support will not be called until all asynchronous support in recordCommon completes
* dbProcess calls record support after recordCommon support completes and as long as record support is active
** record support handles the record specific fields
** struct and link fields can have associated support
** associated support may be asynchronous
*** record support returns to dbProcess indicating that it is active
*** record support is required to detect when asynchronous support completes
*** when processing is complete record support returns to dbProcess indicating that it is done.
* whenever record support returns to dbProcess while still active, dbProcess posts any fields that were modified.
* when record support completes
** dbProcess processes the fields in recordCommon that must be processed after record support completes.
** dbProcess posts monitors for all fields that were modified since before the last time record support was called.
* record processing is complete. The record is again idle.

An additional complication is that it is possible to cancel processing while
a record is active.

== record common ==

A record type can have fields that are processed by dbCommon rather than
record support. These fields are optional but it is expected that most record
types will include a standard set of fields.

dbCommon will process the following fields:

* before record support is called
** disable - if true NO processing will be done.
** scanDisable
*** has associated support
*** if record is scan disabled record processing completes immediately
** alarm fields
*** alarm handling is described below
* after record support completes
** processLink array
*** has associated support

== record support ==

Record support is responsible for all the fields not in dbCommon.
For link and struct fields there may be associated support which
may be synchronous or asynchronous. Record support communicates with
the link/struct support via interfaces that are implemented by the support.

Record support may be called multiple times by dbProcess while a record instance
is active.
One of the arguments to process is ProcessState which has the values:
* processCancel - Cancel any outstanding activity
* processStart - Start processing
* processContinue - Making additional call

process returns ProcessReturn which is one of the following:
* processDone - Done and successful
* processQuit - Do not do any more processing
* processActive - Not done

If record support returns processActive it must keep internal state so
that it knows how to handle processCancel and processContinue.

For record support the above rules allow:
* process can be called repeatedly. This will continue as long as it returns processActive
* Everytime process returns processActive DbProcess posts monitors.

== Record Locking ==

V3 implemented lock sets in order to prevent different threads
from simultaneously accessing linked records.

Instead of lock sets V4:
* implements a per record instance lock.
* defines a rule that allows two records to be locked without deadlocks

== Posting Monitors ==

In V3 monitors are posted when code (record support, device support, database access, etc) calls db_post_event. In V4 database access will itself handle
the posting of monitors.

Monitors are posted by DbProcess when
* record support returns processActive.
* at the end of record processing.

<center>
= link/struct Semantics =
</center>

Both link and struct fields can have associated support.
The support can be synchronous or asynchronous.

Support code implements interfaces.
Code that is responsible for a field communicates with the support via
the interface. Lets call this code the client.

Each link and struct field has a well defined client.
* dbProcess is the client for fields in dbCommon
* record support is the client for the other top level fields in a record
* the struct support is the client for any link or struct fields in the struct

Every link/struct has an associated block. The client is responsible for
implementing block. If block is true then the support will not be called
until all outstanding record activity completes.

<center>
= channelAccess links =
</center>

channelAccess link means access to a record or field. The requester can be:
* A database link in a record
* A channel access link in a record
* A workstation channel access client

A channelAccess link is one of the following types:
* Monitor Link
** Implemented via a monitor request on linked field
** Optionally process record containing the link when monitor value is returned.
* Input Link
** Optionally request that record be processed.
** Optionally wait for linked record to complete processing.
** Get value.
* Output Link:
** Put value
** Optionally request processing. If record can not be processed should the value be changed?
** Optionally wait until completion
* Process Link: Perform the following actions
** Request processing
** Optionally wait until linked record completes

NOTES:
* processLink is the replacement for the V3 forwardLink
* wait does NOT mean to wait synchronously. It means to save state, return, and resume at the saved state when called again.

Links are processed as follows:

The following rules apply when a process request is made:
* If record is already being processed the request is just ignored
* record support can specify that links to particular fields not cause processing.
** Where should this be specified? In the Database Definition, the record instance, or both.
** If a process request is allowed, should it be done regardless of the scan mechanism, i.e. the record does not have to be passive?

----
<center>
= Mutual Exclusion =
</center>

V3 implemented lock sets, i.e. when a record was being processed it and all records linked via database links were locked.

Lock sets solved two Mutual Exclusion problems:
* V3 allowed dbProcess to be called recursively.
** process passive database links and forward links were implemented via recursive calls to DbProcess
** Lock sets prevented deadly embrace problems for circular links.
* No puts could be done to an record in a lock set while record processing is active.
** For synchronous records this guarantees that no fields are modified except by record processing itself.
** For asynchronous records this guarantee is not valid.

V4 does not call dbProcess recursively. Instead a process request is queued.
The request fails if either of the following is true:
* The record is active.
* The record is already queued.

dbProcess itself manages the queue , which is FIFO.
When record support returns the first entry in the queue is processed.
In addition if link or struct support completes before the queue
is empty, a request to process the record containing the link/struct will
be added to the same queue.
Thus if a set of synchronous records are processed they will complete processing
without any context switch.

Question What about periodically scanned records? Needs thought.

This leaves the question of what should be done about mutual exclusion.

For V4 there will be two locks associated with the IOC database:
1) a global lock, and 2) A per record instance lock.

The global lock must be taken
whenever the structure of the database is modified. Examples are
1) adding new record types, 2) adding new record instances, and 3) modifying
database links. Global locks are not discussed further in this document.

Each record instance has an associated lock.
When dbProcess is called it takes the lock.
Before it returns it unlocks.
Thus record support does not need to lock or unlock.

Other code that needs access to fields of a record instance must
lock before accessing any fields and unlock after all accesses are complete.

This leaves the problem of how to access fields from two different record
instances simultaneously. For example code that implements database
access needs such access. Code that needs such access must call dbLockLink before accessing the linked record and dbUnlockLink after access.

dbLockLink is implemented as follows:
* Each Record instances has a unique ordinal number
* Assume Record X has a link to record Y
* If the ordinal number of X is less than that of Y
** Just call dbLock for record Y
* If the ordinal numnber of X is greater than that of Y
** call dbUnlock for X
** call dbLock for Y
** call dbLock for X

----
<center>
= Posting Modifications =
</center>

The document "V4 Design: dbdIterfaces" provides a design that allows
database access to handle all posting on monitors without requiring
any help from the code that modifies database fields.
It can do this because fields can be modified only via an
interface implemented by database access.

dbProcess posts monitors when:
* When record support returns processActive.
* When it finishes record processing.

How to implement monitors must be decided.

----
<center>
= Alarm Processing =
</center>

Question Will V4 alarm handling be different than V3? If so this section
may be meaningless.

The V4 semantics for status and severity have the following goals:
* alarmSeverity has the same values as for V3
* alarmStatus is a string
* a record starts processing with alarmSeverity = "NO_ALARM" and status empty.
* status will ONLY be posted if it has changed since the last time it was posted.
* alarmSeverity will ONLY be posted if it has changed since the last time it was posted

The semantics, which are implemented by recordCommon, are:

* When recordCommon is called with processStart
** A private variable newSeverity is set to NO_ALARM
** A private variable prevSeverity is set to alarmSeverity
* When recordCommon completes its part of record processing
** If newSeverity is NO_ALARM and prevSeverity has a different value
*** alarmSeverity is set to NO_ALARM
*** alarmStatus is set to empty

* When the recordCommon.setSeverity(sevr,status) is called
** If sevr is less than or equal to newSeverity nothing is done
** else
*** alarmSeverity is set to sevr
*** alarmStatus is set to status
*** newSeverity is set to sevr

NOTE: alarmStatus and alarmSeverity are written by the normal method.
This means that their values will be posted.
----
<center>
= Channel Access/ Database Access field types =
</center>

== Overview ==

This section discusses how IOC database fields are accessed by channel access
or via database links.

For the initial V4 implementation only the following types of data
will be accessable.

* primitive types
* string
* enum
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** enum
** struct (use recursion for allowed types)
** one dimensional array of primitive or string or struct

The dbdInterfaces document defines database field types.
It also defines a subset called basic types, which consists
of primitive types, string, array, and structure.
For external access only basic types can be accessed.
This means that structures and arrays that do not consist of basic types
are not accessablevia clannelAccess. For example a DbfLink is
not accessable via channel access as a DbfLink.

Non basic fields will only be available via some combination of basic types.

For example a DbfLink field will appear as a string.
If a Database Definition is

struct(calcInpLink) {
field(link,link(in))
field(value,float64)
};

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

If a client attaches to
record.field(link)
The data will be appear in the form:
choiceName(pvname,...)
where <tt>choiceName</tt> is the name of the link support and the arguments
are the values of the dataStruct associated with the support.

Then if a client specifies the process variable:
record.field(inp[1].link)
Then it connects to the link field of the second calcInpLink of field inp.

== primitive types ==

This includes DbfBool, DbfOctet, DbfInt16, ... , DbfFloat64.
These do not present any problems. The scalar value is transfered.

== string ==

A string is just a UTF_8 encoded character string

== DbfMenu and DbfEnum ==

Handled as an enum

== DbfLink ==

Both of these have the following:

* <tt>choiceName</tt> A string that selects the link support.
* <tt>dataStructName</tt> Each support has an associated struct for configuration.

How should these be made available? Perhaps:

The field appears as a string with the following syntax:

<tt>choiceName(structAssignmentList)</tt>

where structAssignmentList has the same syntax as defined in "V4 DB Record Instance Syntax"

== timeStamp ==

This is just transfered like a struct with two fields:
* int64 secondsSinceEpoch
* int32 nanoSeconds

== struct ==

The database definition syntax allows a struct to be composed of fields
of any DbfType.
Database access, however, will only allow access to structs with fields
of the following types:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfArray of primitive type or string
* DbfStruct - As long as its fields are valid types

The individual fields can be accessed directly so this discussion
only involves access to the entire structure.

Access will only be available to clients that have knowledge of
fields within the structure. For channel access clients this means that
they provide a propertyCatalog that has some subset of the fields in the structure.

== array ==

Arrays of the following types are accessable:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfStruct - As long as its fields are valid types

Note that arrays of structs are not accessable in the early V4 releases.

Arrays still need lots more discussion!!!
The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.

For the initial V4 version, database access only allows access to arrays of the following types.
* primitive - DbfBool,...,DbfFloat64
* DbfString
* ???? What else

An individual element of an array of type DbfStruct can be accessed
directly if it satisfies the criteria for accessing a DbfStruct.

Question: Should database Access be implemented so that record/link support can transfer an array in segments. Examples:
* If the array is a circular buffer, it is presented in two segements
* If the array is stored in hardware, e.g. a transient recorder, the array can be read from the hardware and passed to the client in segments.

If an array is available only in segments then can we
prevent two clients from trying to access the same array simultaneously?

Perhaps this is a problem that must be solved by an application:
* runControl records are one solution
* Other solutions can be envisioned

== MDArray ==

Not implemented if the early V4 releases.

== Associated Data ==

The typical example is a client that asks for timeStamp, severity, status,
and data.

V4 Design: dbdInterfaces

2005-10-04T15:02:43Z

MartyKraimer:

EPICS: dbdInterfaces - IOC Database Description October 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 code that use code automatically
generated from DBD files or by code that uses only introspection.

Code is automatically generated from the following definitions:
* <tt>record</tt> - Used by record support.
* <tt>struct</tt> - Used by code that understands the struct.
* <tt>menu</tt> - Used by code that understands the menu.

----
<center>

= Syntax =
</center>

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 <tt>true</tt> or <tt>false</tt>
* 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 <tt>char *</tt> array containing UTF-8
compatible characters not necessarily terminated with a null character.
Wherever a <tt>string</tt> argument appears, the C++ definition
will have <tt>len</tt> and <tt>char *</tt> arguments.

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

An example of a definition that includes a string argument is
void get(String name);

In C++ this will become
void get(int lenName, char *name);
In Java this will become
void get(String name);
=== 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);

----
<center>

= DbfTypes =
</center>
The following naming conventions are used:
; Dbf
: any class starting with Dbf describes a field in a header file generated from a <tt>struct</tt> or <tt>record</tt> definition. For example DbfArray describes a field generated from <tt>field(name,array(float64[])</tt>.
; 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.

== <tt>DbfTypes.h</tt> ==

The following <tt>enum</tt> definitions describe
each field in the header files generated from DBD <tt>struct</tt> and
<tt>record</tt> 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
}

== Discussion of DbfTypes ==

The example code shown below uses Java syntax.
It assumes the following definitions:

struct(DisplayLimit) {
field(low,double)
field(high,double)
}
record(Example) extends RecordCommon {
...
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)
//FOLLOWING IS NOT VALID LINK DEFINITION
field(link,link(in))
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++.

----
<center>

= Database Fields =
</center>

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;
short myint;
...
precord.ffloat.put(10.0);
...
myint = precord.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 {
int32 getLength();
void get(string value);
void setPutSize(int32 size);
void put(string value);
}

The following code prints a string.

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

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(name);
printf("field %s\n",name);
}

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 <tt>DbfArray</tt>

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});

== DbfMDArray ==
NOT YET DEFINED

== <tt>DbfMenu</tt> ==

<tt>DbfMenu</tt> is described as:
interface DbfMenu extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbdMenu getDbdMenu();
}

<tt>DbfMenu</tt> allows the menu index to be set and retrieved
and also provides access to the DbdMenu.

A <tt>DbfMenu</tt> field can be accessed via the generated header file or via
the introspection methods.

== DbfEnum ==

<tt>DbfEnum</tt> is described as:
interface DbfEnum extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbfStringArray getChoiceArray();
}

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

== DbfLink and DbfDevice ==

<tt>DbfLink</tt> is described as

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

interface DbfLink extends Dbf {
LinkDir getDir();
DbdLink getDbdLink();
}

== DbfTimeStamp ==

struct TimeStamp {
int64 secondsSinceEpoch;
int32 nanoSeconds;
}

interface DbfTimeStamp extends Dbf {
void get(TimeStamp timeStamp);
void put(TimeStamp timeStamp);
}

----
<center>

= DbdStatements =

</center>
These describe everything defined in database definition files.

== <tt>DbdMenu</tt> ==

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

== <tt>DbdLink</tt> ==

interface DbdLink {
LinkDir getDir();
int32 getChoiceNameLength();
void getChoiceName(String name);
int32 getInterfaceNameLength();
void getInterfaceName(String name);
int32 getDataStructNameLength();
void getDataStructName(String name);
}

== <tt>DbdStruct</tt> and <tt>DbdRecord</tt> ==

interface DbdAttribute {
int32 getDefaultLength();
void getDefault(String value);
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();
void getName(String name);
DbfType getType();
DbdDefaults getDefaults();
DbdAttribute getAttributes();
}

interface DbdStruct {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

interface DbdRecord {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

== Record Instance ==

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

; <tt>getNameLength</tt>
: get length of record name
; <tt>getName
: get the record name
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
; <tt>getRecordCommonDescription</tt>
: get the description of RecordCommon
; <tt>getInstance</tt>
: 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>
: get field instance. Workd for both record specific or RecordCommon field

----
<center>

= Locate Interfaces =

</center>

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");

----

V4 Link Support Tutorial

2005-10-04T15:00:44Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Oct 04 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName and interfaceName select
the support to attach to a record link.
The interfaceName must be one of the interface names the record
has listed as a valid type and linkDirection must be compatible
with the linkDirection the record type specified.

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.

=== Data Structures ===

The complete set of definitions are defined in "V4 DB RecordCommon".
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
... also OutputLinkData and ProcessLinkData

A look at the fields shows that these are what is required to implement
the V4 semantics for Channel/Database access links.

=== Link Definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

"V4 DB RecordCommon" describes the complete set of link definitions
supplied by EPICS base. These are:

link(process,processLink,ProcessLinkData,interface(ProcessLink))

link(in,monitorLink,MonitorLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,monitorLinkArray,MonitorLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,inputLink,InputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLinkArray,InputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,outputLink,OutputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,outputLinkArray,OutputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))

These are the link definitions for the Channel/Database access link
support supplied with base. The support registers support for processLink,
monitorLinkArrayOctet, ...

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Average,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLinkData,interface(LinkInt32))
link(inout,asynFloat64,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLinkData,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLinkData,interface(AsynDigital))
link(inout,asynDigital,AsynLinkData,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLinkData,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLinkData,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLinkData,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
New support should try very hard to implement the standard interfaces
supplied by EPICS base. These are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that nthe support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record links.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Link and MonitorLink ==

interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Neither Link or MonitorLink is listed in the <tt>link</tt> database
definition.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
== database definitions ==
The following struct is defined for configuration information.
struct VMEADC {
field(a16 int16)
field(a32 int32)
field(channel int16)
}
The following link definition is defined:
link(in,myAdcSupport,VMEADCinterface(LinkInt32))

This allows record instance definitions like:
AiRecord aiExample = {
...
input = myAdcSupport(LinkInt32){a16=0x0010;channel=1}
...
}

== link support implementation ==
The following is presented with Java syntax.
It assumes that there is VME support of the form

public class VME {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VMEADCData fromFactory)
{
data = fromFactory;
connected = false;
// from the VMEADC initailze vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkWaitResult getWait(Int data,Callback callback)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkWaitResult putWait(Int data,Callback callback)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VMEADCData data;
int vmeaddr;
int channel;
boolean connected;
}

V4 Design: Runtime Interfaces

2005-10-04T14:58:49Z

MartyKraimer: DbInstance => RecordInstance; new state for process

EPICS: IOC Runtime Interfaces Oct 04 2005

----
= Overview =

This document describes definitions for IOC runtime,
i.e. interfaces implemented or used by database access, record support,
link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTE IOC runtime needs lots more work

----
<center>
= Support Code =
</center>

This section described interfaces for
strings, arrays, and conversions.
They are intended for use by Database Access, Record Support, etc.

== C++ support for strings ==

For most strings all the database needs is a nonmutable string.
For these it wants to be able to pass a reference to it to arbitrary code.
It needs this for things like record type names, field names, record instance names, menu choice names, etc. etc. Some of these may change but very infrequently.
The string always contains UTF-8 encoded strings, which I believe can be printed with a "%s" format if
the string is made available as a "const char *"

Perhaps the only type of string connected with an IOC record that changes frequently is a field in a record type like stringin and stringout. In this case the record support can do what ever it wants to handle the string. It can even just use C style strings!!!

Thus all the IOC database needs is a:

1) nonmutable reference counted continguous string. When the reference count goes to 0 the storage can be reclaimed
2) The ability to copy the value from a nonmutable string to a mutable string.

In Java String and StringBuffer are all that is needed.

In C++ all that is needed is

1) A class that holds UFT-8 encoded non-mutable strings and make the contents available as a "const char *" and it's length. The class keeps a reference count and frees the storage when done.
2) The ability to copy the nonmutable string to a "char *" array allocated by the requester.

That is all.

== array copy ==

ArrayCopy copies arrays an array performing conversions if necessary.

interface ArrayCopy {
void copy(DbfArray from,DbfArray to);
}

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64.
It does NOT convert between
* DbfBoolean and another type.
* DbfOctet and another type.
Thus for DbfBoolean and DbfOctet it is willing to copy
but not convert to/from other types.

== Arithmetic Conversions ==
This is a static class that converts between primitie types and arrays of primitive types.

static class DbfConvertPrimitive {
public:
int16 get(Dbf from);
int32 get(Dbf from);
int64 get(Dbf from);
float32 get(Dbf from);
float64 get(Dbf from);
get(Dbf from, String value);
get(DbfOctet from, String value);
get(DbfBoolean from, String value);
put(Dbf to, int16 value);
put(Dbf to, int32 value);
put(Dbf to, int64 value);
put(Dbf to, float32 value);
put(Dbf to, float64 value);
put(Dbf to,int32 String value);
put(DbfOctet to, String value);
put(DbfBoolean to, String value);

get(DbfArray from, int16[] value);
get(DbfArray from, int32[] value);
get(DbfArray from, int64[] value);
get(DbfArray from, float32[] value);
get(DbfArray from, float64[] value);
put(DbfArray to, int16[] value);
put(DbfArray to, int32[] value);
put(DbfArray to, int64[] value);
put(DbfArray to, float32[] value);
put(DbfArray to, float64[] value);
}

NOTES:
* For Dbf <tt>to</tt> and <tt>from</tt> must be one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>
* The get to a string implements printf semantics
* The put from a string value just scanf semantics.
* The <tt>DbfOctet</tt> methods convert to/from a string of the form "0xXX"
* The <tt>DbfBoolean</tt> get method supports all the choices specified in the DBD Record Instance Specification
* For DbfArray <tt>to</tt> and <tt>from</tt> must be an array of one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>

----
<center>

= Code generated from Database Definition Files =
</center>

The following shows the Java code generated from DBD files:

== structure definitions ==

Two files are generated from <tt>struct(name)</tt> definitions.
# <tt>name.java</tt>
# <tt>nameSupport.java</tt>

<tt>name.java</tt> implements:
interface Struct {
Dbf getField(int16 index);
}

If a structure is defined as:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

A generated file <tt>DisplayLimit.java</tt> contains:

public class DisplayLimit implements Struct{
public DbfFloat64 low;
public DbfFloat64 high;
public static final short lowIndex = 1;
public static final short highIndex = 2;
public static final short lastIndex = indexHigh;
Dbf getField(short index) {
switch(index) {
case lowIndex: return(low);
case highIndex: return(high);
default: throw java.lang.IllegalStateException;
}
return null;
}
}

A generated file <tt>DisplayLimitAccess.java</tt> contains:

public class DisplayLimitData {
public double low;
public double high;
}
public final class DisplayLimitAccess implements StructFactory{
public Struct create() { return new DisplayLimit; }
public static final void get(DbfStruct from,DisplayLimitData data) {
DbfFloat64 dbf = from.getInterface(1);
data.low = dbf.get();
DbfFloat64 dbf = from.getInterface(2);
data.high = dbf.get();
}
public static final void put(DbfStruct to, DisplayLimitData data) {
DbfFloat64 dbf = to.getInterface(1);
dbf.put(data.low);
DbfFloat64 dbf = to.getInterface(2);
dbf.put(data.high);
}
}

public final class DisplayLimitAccessRegister {
static public createAndRegister() {
DisplayLimitAccess access = new DisplayLimitAccess;
RegisterSupport.structure(access,"DisplayLimit");
}
}

NOTES
* The V4 replacement for registerRecordDeviceDriver must call DisplayLimitAccessRegister.createAndRegister.
* For non primitive fields the generated field is the Dbf type for the field.

Similar files are generated for C++.

== record definitions ==
If a record is defined as:
record(Example) extends RecordCommon {
...
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}

The generated Java file is

public class ExampleRecord implements Struct {
public DbfBoolean fboolean;
public DbfOctet ctet;
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 DbfDevice device;
public DbfStruct displayLimit;
public static final int16 fbooleanIndex = 1;
...
public static final int16 lastIndex = displayLimitIndex;
Dbf getField(short index) {
switch(index) {
case fbooleanIndex : return(fboolean);
...
case displayLimitIndex: return(displayLimit);
default: throw java.lang.IllegalStateException;
}
}
}

public final class ExampleRecordFactory implements StructFactory{
public static final Struct create() { return new ExampleRecord; }
}

public final class ExampleRecordFactoryRegister {
static public createAndRegister() {
ExampleRecordFactory factory = new ExampleRecordFactory;
RegisterSupport.record(factory,"ExampleRecord");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

----
<center>
= Record Support =
</center>

enum ProcessState {
processCancel,
processStart,
processContinue,
processFinish,
}

enum ProcessReturn {
processDone,
processAbort,
processActive
}

interface RecordSupport {
void destroy();
void initialize(int32 pass);
ProcessState process(ProcessState state,Callback done);
// if special returns false when after is false put fails
boolean special(boolean after,Dbf[] field);
}

<tt>ProcessState</tt> supports the following semantics:
* cancel - If the record is active terminate
* For all other states see the companion document "V4 Design: Record Processing"

The methods of <tt>RecordSupport</tt> are:
* <tt>destroy</tt> - Called when a record instance is deleted.
* <tt>initialize</tt> - Called twice (pass = 0,1) when a record is initialized.
* <tt>process</tt> - Called to process a record. See "V4 Design: Record Processing" for semantics.
* <tt>special</tt> - Called when a field declared special in a DBD file is modified. <tt>field</tt> is an array of Dbfs showing which field is being modified.

== Discussion of special ==

Special is passed a Dbf array that identifies the field being modified.
For example <tt>ExampleRecord.dbd</tt> has a field:
field(displayLimit,struct(displayLimit))
<tt>ExampleRecordSupport.java</tt> might implement special as follows:
boolean special(boolean after, Dbf[] field)
{
switch(field[0].getIndex()) {
...
case ExampleRecord.displayLimitIndex:
if(field.length==1) {
// displayLimits itself is being modified. Do something
} else {
// a field of displayLimits is being modified
switch(field[1].getIndex) {
case DisplayLimit.lowIndex:
// low being modified. do something
case DisplayLimit.highIndex:
// high being modified. do something
}
}
...
}
}
----
<center>

= Link Support =
</center>

An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.
EPICS base supplies support that accesses data via channel access, i.e.
access to records in the same or other IOCS.

Recall that the link DBD definition is:

link(dir, choiceName, interfaceName, dataStructName)

<tt>choiceName</tt> is the name that identifies the implementation.
<tt>interfaceName</tt> is the name of the interface that record support
uses and the support implements.
<tt>dataStructName</tt> is the name of a structure used by support for
configuration.

This section describes that standard <tt>interfaceNames</tt> that
are used by the record types supplied with epics base.
These interfaces are appropriate for the soft support supplied with EPICS
base and should also be sufficient for a wide variety of hardware support.
In particular it is sufficient for communication with asynDriver.

== Link ==
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. Example are hardware interrupts.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call
destroy before modifying the link and initialize and connect after the
link is modified.

== Definitions that apply to Process,Monitor,Input,and Output support ==

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface LinkProcess<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----

<center>
= Registration and Instance Creation =
</center>

interface StructFactory {
DbfStruct create();
}

interface RecordSupportFactory {
RecordSupport create(RecordInstance instance);
}

interface SupportFactory {
Support create(Dbf field);
}

interface RegisterSupport {
structure(StructFactory create, string name);
record(StructFactory create, string name);
link(SupportFactory support,string name);
device(SupportFactory support,string name);
record(RecordSupportFactory support,string name);
}

<tt>RegisterSupport</tt> is implemented by iocCore.
Each <tt>struct</tt> DBD definition must register a StructFactory to
create instances of the structure or record.

Each link, device, and record support must register a SupportFactory to create
instances of the support to attach to the link, device, or record instance.
During database initialization, iocCore calls the factory methods.

----
<center>

= Runtime Database Access =

</center>

== Overview ==

Database Access, with help from record, link, and device support
implements the dbdInterfaces.
Other than Database Access, fields of a record can only
be accessed via the interfaces described in dbdInterfaces.
This allows the database to handle
actions like posting database monitors without any help from
record, link, or device support.

Database access by default allocates the actual storage for each field
but allows support code to register itself to manage storage for field
instances.
Two examples, both involving arrays, are:
* The compress record registers to provide storage for the value.
** This allows it to implement a circular buffer.
** Code that accesses the value field may have to issue two get requests.
* Device support for a transient recorder registers to provide storage for the array
** This allows device support to read data from hardware in segments
** Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required.
Database Access will probably have something like the following:

class Field {
DbRecord instance;
short index;
};
...
class IntField extends Field {
int data;
}
...

This each field has the overhead of
* instance - a reference to DbRecord, i.e. record instance
* index - a 16 bit integer
* vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors.
These fields can start out null and only allocate storage as needed.

== Database Access ==

interface DbAccess {
void lock(RecordInstance instance);
void unlock(RecordInstance instance);
void process(RecordInstance instance, Callback callback);
void processCancel(RecordInstance instance, Callback callback);
void processContinue(RecordInstance instance, Callback callback);
void processRequestAccept(Dbf field, boolean yesNo);
void registerDbfSource(Dbf field, Dbf source);
LinkSupport getLinkSupport(Dbf field);
Support getSupport(Dbf field);
RecordSupport getRecordSupport(RecordInstance instance);
RecordSupport getRecordCommonSupport(RecordInstance instance);
}

The methods are:
* <tt>lock</tt> - lock the record.
* <tt>unlock</tt> - unlock the record.
* <tt>process</tt> - Request processing. Record must be idle or active or request fails.
** <tt>instance</tt> - The record to process
** <tt>callback</tt> - A callback to call when processing completes or for failure.
* <tt>processRequestAccept</tt> - Should a process request from channel access be accepted,
* <tt>registerDbfSource</tt> - Register code that will implement storage for the field.
* <tt>getLinkSupport</tt> - Find the link support for a link field
* <tt>getSupport</tt> - Get the device support for a device field
* <tt>getRecordSupport</tt> - Get the record support for the record
* <tt>getRecordCommonSupport</tt> - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

----

V4 Design: RecordCommon Support

2005-10-04T14:49:23Z

MartyKraimer:

EPICS V4: RecordCommonSupport - October 04 2005
----
= Overview =

This document describes the implementation of the record support
for RecordCommon, i.e. the set of fields associated with every record type.

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd define widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document describes the following:

* The code automatically generated from dbCommon.dbd and RecordCommon.dbd
* A proposed implementation of RecordCommonSupport.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 Design: Record Processing
# V4 Design: dbdInterfaces
# V4 Design: Runtime interfaces
# V4 Design: RecordCommon

Java is used as the example code for two reasons:
# For V4 iocCore it is intended that both C++ and Java implementations will be provided. Since V3 is only implemented in C and C++ the Java implemention of V4 is described first to make sure that the interfaces defined in dbdInterfaces will work for Java.
# Java provides facilities that make it easy to handle strings, arrays, and structures.

An implementaion of RecordCommonSupport is presented for two reasons:
# It demonstrates how to implement code that uses or implements the interfaces described in "V4 Design: dbdInterfaces" and "V4 Design: Runtime interfaces".
# It helps refine the interfaces described in them

----
<center>
= dbCommon.dbd =
</center>

See the description of <tt>dbCommon.dbd</tt> in "V4 Design: RecordCommon"

Link support must register support for each of the <tt>link</tt> definitions.

From <tt>dbCommon.dbd</tt> the following class implementations are generated:
* For the link structures:
** <tt>MonitorLink</tt>, <tt>MonitorLinkData</tt>, and <tt>MonitorLinkSupport</tt>
** <tt>InputLink</tt>, <tt>InputLinkData</tt>, and <tt>InputLinkSupport</tt>
** <tt>OutputLink</tt>, <tt>OutputLinkData</tt>, and <tt>OutputLinkSupport</tt>
** <tt>ProcessLink</tt>, <tt>ProcessLinkData</tt>, and <tt>ProcessLinkSupport</tt>
* For TimeStamp
** <tt>TimeStamp</tt>, <tt>TimeStampData</tt>, and <tt>TimeStampSupport</tt>
* For Scan
** <tt>Scan</tt>, <tt>ScanData</tt>, and <tt>ScanSupport</tt>

See "V4 Design: Runtime interfaces" for an example of how these classes are defined.

----
<center>
= RecordCommon.dbd =
</center>

See the description of <tt>RecordCommon.dbd</tt> in "V4 Design: RecordCommon"

<tt>RecordCommon.dbd</tt> must be part of every record.

Implementations of <tt>Disable</tt>, <tt>DisableData</tt>,
and <tt>DisableDataSupport</tt>
are automatically generated.

An implementations of RecordCommon is also generated.
See "V4 Design: Runtime interfaces" for an example of the generated
classes.
----
<center>
= RecordCommonSupport.java =
</center>

== Overview ==
This section describes the java implementation of RecordCommon
functionality. This code handles processing of the following fields
of RecordCommon:
; <tt>disable</tt>
: Decides if the record is disabled.
; <tt>alarmStatus</tt> and <tt>alarmSeverity</tt>
: The only way to change alarmStatus and alarmSeverity is via interface Common, which is implemented by RecordCommonSupport.
; <tt>processLink</tt>
: This is an array of process links, which replace the V3 <tt>FLNK</tt>

The following subsection describes the code for RecordCommonSupport.java.
The remaining subsections describes the code for additional classes
that are part of the implementation.

== RecordCommonSupport.java ==

interface Common {
boolean setSeverity(AlarmSeverity severity, string status);
}

public class RecordCommonSupport implements RecordSupport, Common
{
private RecordInstance instance;
private Input input;
private Output output;
// The following are for implementing Common.setSeverity
private short severity;
private String status;
private DbfMenu alarmSeverity;
private DbfString alarmStatus;
private boolean modifyingAlarm;

// Constructor
public RecordCommonSupport(RecordInstance instance) {
this.instance = instance;
}

// Beginning of RecordSupport
public destroy() {} // destroy not needed for Java
public initialize(int pass) {
if(pass==0) return;
input = new Input(instance);
output = new Output(instance);
alarmSeverity = instance.getField("alarmSeverity");
alarmStatus = instance.getField("alarmStatus");
severity = alarmSeverity.get();
alarmStatus.get(status);
}

public ProcessReturn process(processState state,Callback callback) {
if(state==processCancel) {
input.process(state,callback);
output.process(state,callback);
return processDone;
}
if(state==processStart) {
ProcessReturn result = input.process(state,callback);
if(result!=processDone) return result;
}
if(state==processFinish) {
ProcessReturn result = output.process(state,callback);
if(result!=processDone) return result;
}
return output.process(state,callback)
}

public boolean special(boolean after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input = new Input(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output = new Output(instance); break;
default: printf("Why is special being called?\n");
}
}

// Start of Common methods
boolean setSeverity(AlarmSeverity severity, string status) {
if(severity<= this.severity) return false;
this.severity = severity;
this.status = status;
this.modifyingAlarm = true;
this.alarmSeverity.putIndex(severity);
this.alarmStatus.put(status);
this.modifyingAlarm = false;
}
}

RecordCommonSupport implements the following interfaces:
; <tt>RecordSupport</tt>
: Record support for the fields in RecordCommon.
; <tt>Common</tt>
: For now this just has the method <tt>setSeverity</tt>

It has the following private fields:
* <tt>instance</tt> - The record instance to which it is attached. <tt>RecordCommonSupport</tt> has a single constructor which is passed the <tt>RecordInstance</tt> to which it is attached.
* <tt>input</tt> - Input is a private class that provides access to the fields of disable.
* <tt>output</tt> - Output is a private class that provides access to processLink.
* <tt>severity</tt>, ..., <tt>modifyingAlarm</tt> - private fields for implementing <tt>Common.setSeverity</tt>

Notes about <tt>Input</tt> and <tt>Output</tt>.
* Each of these is a private class to RecordCommonSupport.
* The implementations of each of these private classes is given after the implementaion of RecordCommonSupport.

=== RecordSupport Methods ===

==== destroy ====
public destroy() {} // destroy not needed for Java

Since Java does garbage collection destroy is not needed.
Note that iocCore will call all the link support destroy methods.
==== initialize ====

public initialize(int pass) {
if(pass==0) return;
input = new Input(instance);
output = new Output(instance);
alarmSeverity = instance.getField("alarmSeverity");
alarmStatus = instance.getField("alarmStatus");
severity = alarmSeverity.get();
alarmStatus.get(status);
}

During the first pass of initialization, nothing needs to be done.
Before initialize is called on pass 1, iocInit has
already called link support so that it connects.
Initialize just creates it's private class instances for Input and Output,
and initializes the private fields for implementing setSeverity.

==== process ====

<tt>process</tt> is called by dbProcess at the beginning of record processing,
when a request is made to process while the record is active,
and after the record specific record support completes.
During the beginning of record processing
process takes care of field <tt>disable</tt>, via class Input,
During the end of record processing process
takes care of field <tt>processLink</tt>, via class Output

public ProcessReturn process(processState state,Callback callback) {
if(state==processCancel) {
input.process(state,callback);
output.process(state,callback);
return processDone;
}
if(state==processStart) {
ProcessReturn result = input.process(state,callback);
if(result!=processDone) return result;
}
if(state==processFinish) {
ProcessReturn result = output.process(state,callback);
if(result!=processDone) return result;
}
return output.process(state,callback)
}

==== special ====
<tt>special</tt> is called when any of the fields in <tt>disable</tt>,
<tt>alarmStatus</tt>, <tt>alarmSeverity</tt>, or <tt>processLink</tt> are changed.
public boolean special(boolean after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input = new Input(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output = new Output(instance); break;
default: printf("Why is special being called?\n");
}
}

==== setSeverity ====
This is the implementation of Common.setSeverity.

boolean setSeverity(AlarmSeverity severity, string status) {
if(severity<= this.severity) return false;
this.severity = severity;
this.status = status;
this.modifyingAlarm = true;
this.alarmSeverity.putIndex(severity);
this.alarmStatus.put(status);
this.modifyingAlarm = false;
}
=== Input ===
This is the package private class the handles disable.

class Input implements Callback{
RecordInstance instance;
DisableData disable;
LinkInt16 disableSupport;
Callback processCallback;

Input(RecordInstance instance) {
this.instance = instance;
DisplayLimitAccess.get(
(DbfStruct)instance.getField("disable"),disable);
disableSupport = DbAccess.getLinkSupport(disable.disableLink);
}
public ProcessReturn process(processState state,Callback callback) {
switch(state) {
case processCancel:
processCallback = null;
disableSupport.cancel(); return(processDone);
case processStart:
LinkWaitResult result;
result = disableSupport.getWait(disable.disableInput,this);
switch(result) {
case linkNoop:
case linkDone:
if(disable.disableInput==disable.disableValue)
return processAbort;
return processDone;
case linkWait:
case linkWaitBlock:
processCallback = callback;
return processActive;
default:
throw java.lang.IllegalStateException;
}
}
void special(RecordInstance instance,Dbf field) {
int16 index = Dbf.getIndex();
switch(index) {
case disableValueIndex:
disable.disableValue = ((DbfInt16)Dbf).get(); break;
case disableInputIndex:
disable.disableInput = ((DbfInt16)Dbf).get(); break;
case disableAlarmSeverityIndex:
disable.alarmSeverity = ((dbfMenu)Dbf).getIndex(); break;
case disableLinkIndex:
case disableIndex:
DisplayLimitAccess.get(
(DbfStruct)instance.getField("disable"),disable);
disableSupport = disable.disableLink.getSupport();
break;
default:
throw java.lang.IllegalStateException;
}
}

// Start of Callback methods
public void done() {
DbAccess.lock(instance);
Callback callback = processCallback;
processCallback = null;
DbAccess.unlock(instance);
if(callback!=null) callback.done();
}
public void failure() { done(); }
}

=== Output ===
This is the package private class that handles processLink.

class OutputLink {
Link link;
LinkProcess support;
void init(RecordInstance instance,String linkFieldName) {
DbfLink link = (DbfLink)instance.getField(linkFieldName);
support = DbAccess.getLinkSupport(link);
}
};

class Output {
RecordInstance instance;
int nextLink;
int numberLinksActive;
OutputLink[] link;
Callback processCallback;

Output(RecordInstance instance) {
this.instance = instance;
DbfArray array = instance.getField("processLink");
int n = array.getNelements();
link = new OutputLink[n];
for(i=0; i< n; i++) {
String field = "processLink[" + "i" + "]";
link[i].init(instance,field);
}
}
public ProcessReturn process(processState state,Callback processCallback) {
switch(state) {
case processCancel:
processCallback = null;
for(int i=0; i<link.length) {
link[i].support.cancel();
}
return(processDone);
case processDone:
nextLink = 0;
numberLinksActive = 0;
// fall through to processOutputActive
case processActive:
LinkWaitResult result = linkWait;
while(nextLink< link.length) {
result = link[nextLink].support.process(this);
if(result==linkWait || result==linkWaitBlock) {
link[nextLink].active = true;
numberLinksActive++;
}
if(result==linkWaitBlock) break;
output.nextLink++;
}
if(output.numberLinksActive==0) return processDone;
return processActive;
default:
throw java.lang.IllegalStateException;
}

// Start of Callback methods
public void done() {
DbAccess.lock(instance);
numberLinksActive--;
Callback callback = processCallback;
processCallback = null;
DbAccess.unlock(instance);
if(numberLinksActive==0 && callback!=null) callback.done();
}
public void failure() { done(); }
}
== RecordCommonSupportFactory ==
This is the factory for creating an RecordCommonSupport.
It is called by dbLoadRecords.

public class RecordCommonSupportFactory implements RecordSupportFactory{
RecordSupport create(RecordInstance instance) {
return new RecordCommonSupport(instance);
}
void destroy(RecordSupport support) {
RecordCommonSupport RecordCommonSupport = support;
RecordCommonSupport.destroy();
}
}

public final class RecordCommonSupportFactoryRegister {
static public createAndRegister() {
RecordCommonSupportFactory factory = new RecordCommonSupportFactory;
RegisterSupport.record(factory,"RecordCommon");
}
}

Question
Who calls RecordCommonSupportFactoryRegister.createAndRegister?

V4 Link Support Tutorial

2005-09-30T15:15:05Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Sept 30 2005

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(interfaceName,...))
A link itself has the syntax:
link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName and interfaceName select
the support to attach to a record link.
The interfaceName must be one of the interface names the record
has listed as a valid type and linkDirection must be compatible
with the linkDirection the record type specified.

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.

=== Data Structures ===

The complete set of definitions are defined in "V4 DB RecordCommon".
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
... also OutputLinkData and ProcessLinkData

A look at the fields shows that these are what is required to implement
the V4 semantics for Channel/Database access links.

=== Link Definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

"V4 DB RecordCommon" describes the complete set of link definitions
supplied by EPICS base. These are:

link(process,processLink,ProcessLinkData,interface(ProcessLink))

link(in,monitorLink,MonitorLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,monitorLinkArray,MonitorLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,inputLink,InputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLinkArray,InputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,outputLink,OutputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,outputLinkArray,OutputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))

These are the link definitions for the Channel/Database access link
support supplied with base. The support registers support for processLink,
monitorLinkArrayOctet, ...

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Average,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLinkData,interface(LinkInt32))
link(inout,asynFloat64,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLinkData,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLinkData,interface(AsynDigital))
link(inout,asynDigital,AsynLinkData,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLinkData,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLinkData,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLinkData,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
New support should try very hard to implement the standard interfaces
supplied by EPICS base. These are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that nthe support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record links.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Link and MonitorLink ==

interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

Neither Link or MonitorLink is listed in the <tt>link</tt> database
definition.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface ProcessLinkSupport<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
== database definitions ==
The following struct is defined for configuration information.
struct VMEADC {
field(a16 int16)
field(a32 int32)
field(channel int16)
}
The following link definition is defined:
link(in,myAdcSupport,VMEADCinterface(LinkInt32))

This allows record instance definitions like:
AiRecord aiExample = {
...
input = myAdcSupport(LinkInt32){a16=0x0010;channel=1}
...
}

== link support implementation ==
The following is presented with Java syntax.
It assumes that there is VME support of the form

public class VME {
static public short getShort(long addr);
...
}

The link support would be something like:

class AdcSupport implements Link LinkInt32 {
AdcSupport(VMEADCData fromFactory)
{
data = fromFactory;
connected = false;
// from the VMEADC initailze vmeaddr and channel
// details left to your imagination
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {} //nothing to do
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkWaitResult getWait(Int data,Callback callback)
{
data = (Int)VME.getShort(vmeaddr);
return linkDone;
}
LinkWaitResult putWait(Int data,Callback callback)
{
throw CantWriteAdc;
}
void getBounds(Int low, Int high)
{
// assume 16 bit unipolor adc
low = 0; high = 0xffff;
}
private:
VMEADCData data;
int vmeaddr;
int channel;
boolean connected;
}

V4 DB Record Instance Syntax

2005-09-30T15:14:04Z

MartyKraimer: Change link syntax

Record Instance Syntax Sept 30 2005
= Overview =

The syntax used for record instances has to change in EPICS V4,
since we now have to support structured data.
A complete redesign of the syntax has been done to help improve parsing, and to provide commonality between the syntax of a DB file and the string representation of structured data values passed through Channel Access.

= Document Conventions =

This syntax is presented below in the form of a grammar. The conventions I'm using are as follows:

;''symbolBeingDefined:''
: ''otherSymbol''
: ''alternateSymbolFollowedBy'' <tt>literal</tt>
: ''one of:'' <tt>list of posible literal values</tt>

= Common Symbols =

The symbols described in this section are used in the grammar, but may be implemented as lexical tokens.

;''identifier:''
: A legal C99 identifier. Note that C99 permits implementations to allow extended characters to be used in identifiers, but does not require it, so the use of extended characters may reduce portability and is not recommended.

== Integer Constants ==

;''integerConstant:''
: ''positiveInteger''

;''positiveInteger:''
: ''octalConstant''
: ''hexConstant''
: ''decimalConstant''

;''octalConstant:''
: <tt>0</tt>
: ''octalConstant'' ''octalDigit''

;''octalDigit:''
: ''one of:'' <tt>0-7</tt>

;''hexConstant:''
: <tt>0x</tt> ''hexDigit''
: <tt>0X</tt> ''hexDigit''
: ''hexConstant'' ''hexDigit''

;''hexDigit:''
: ''one of:'' <tt>0-9 a-f A-F</tt>

;''decimalConstant:''
: ''one of:'' <tt>1-9</tt>
: ''decimalConstant'' ''decimalDigit''

;''decimalDigit:''
: ''one of:'' <tt>0-9</tt>

This was meant to be a description of the C99 standard integer representation, but I made it up myself so it may be flawed. Note that we will not accept the C99 numeric suffixes u/U and l/L since (unlike a C compiler) we know the type of the number we're expecting.

== Floating Point Constants ==

;''realConstant:''
:'' positiveReal''
: <tt>-</tt> ''positiveReal''

;''positiveReal:''
: ''digitSequence''
: ''digitSequence'' <tt>.</tt>
: ''digitSequence'' <tt>.</tt> ''exponentPart''
: ''digitSequence'' <tt>.</tt> ''digitSequence''
: ''digitSequence'' <tt>.</tt> ''digitSequence'' ''exponentPart''
: <tt>.</tt> ''digitSequence''
: <tt>.</tt> ''digitSequence'' ''exponentPart''
: ''digitSequence'' ''exponentPart''

;''digitSequence:''
: ''decimalDigit''
: ''digitSequence'' ''decimalDigit''

;''exponentPart:''
: <tt>e</tt> ''signedExponent''
: <tt>E</tt> ''signedExponent''

;''signedExponent:''
: <tt>-</tt> ''digitSequence''
: <tt>+</tt> ''digitSequence''
: ''digitSequence''

In ANSI C source code, a sequence of decimal digits with neither a decimal point nor an exponent is an integer constant, not a floating-point constant. We will permit this however, since we always know the field type in advance.

== Boolean Constants ==

We can afford to be generous in what we accept as a boolean value:

;''booleanConstant:''
: ''booleanTrue''
: <tt>"</tt> ''booleanTrue'' <tt>"</tt>
: ''booleanFalse''
: <tt>"</tt> ''booleanFalse'' <tt>"</tt>

;''booleanTrue:''
: ''one of:'' <tt>1 T TRUE t true True Y YES Yes y yes</tt>

;''booleanFalse:''
: ''one of:'' <tt>0 F FALSE f false False N NO No n no</tt>

'''I'm proposing all these possibilities for true/false as they are all obvious in meaning, and will allow a CA Put of any of these strings to a boolean field. We might even want to allow registration of boolean strings in other languages...'''

== String Constants ==

;''stringConstant:''
: <tt>"</tt> ''escapedCharacterList'' <tt>"</tt>

;''escapedCharacterList:''
: A series of characters, using the C99 ''escapeSequence'' syntax defined below:

;''escapeSequence:''
: ''simpleEscapeSequence''
: ''octalEscapeSequence''
: ''hexEscapeSequence''
: ''universalCharacterName''

;''simpleEscapeSequence:''
: ''one of:'' <tt>\' \" \? \\ \a \b \f \n \r \t \v</tt>

;''octalEscapeSequence:''
: <tt>\</tt> ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit'' ''octalDigit''

;''hexEscapeSequence:''
: <tt>\x</tt> ''hexDigit''
: ''hexEscapeSequence'' ''hexDigit''

Note: C99 does not limit the number of hexadecimal digits that can appear in a ''hexEscapeSequence'', but it does state that the behaviour is undefined if the resulting character value exceeds that of the largest character.

;''universalCharacterName:''
: <tt>\u</tt> ''hexQuad''
: <tt>\U</tt> ''hexQuad'' ''hexQuad''

;''hexQuad:''
: ''hexDigit'' ''hexDigit'' ''hexDigit'' ''hexDigit''

= Database File =

This section will eventually define what can appear in a .db file. That currently means:

* record instances
* comments
* macro instances, including where they will be allowed
* template files and substitution macro definitions
* port definitions for template instances
* data for tools such as VDCT, that will not be discarded by .db processing tools.

The templates, macros and ports design should be very similar to the ideas produced for R3.14 VDCT templates.

= Record Definitions =

;''recordDefinition:''
: ''recordType'' ''recordName'' <tt>= {</tt> ''recordBody'' <tt>}</tt>

;''recordType:''
: ''identifier''

;''recordName:''
: ''recordNameChar''
: ''recordName'' ''recordNameChar''

;''recordNameChar:''
: ''one of:'' <tt>0-9 A-Z a-z _ - : ; < > [ ]</tt>
: Any Unicode/UTF-8 character outside of the Basic Latin set

This extends the character set available to a V3 record name, adding all possible multi-byte characters. However, EPICS sites are strongly advised to confirm that such record names can be processed using all of their database and CA client tools before actually making use of this particular extension.

;''recordBody:''
: ''recordBodyItem''
: ''recordBody'' ''recordBodyItem''

Record instance definitions in EPICS V4 look very similar to a C99 structure definition with initialization. For example:

ai foo:bar:temperature = {
...
}

Inside the body of the record definition, there are three possible kinds of statements, similar to a C assignment statement. Note these statements must be terminated with a semi-colon (which is different from inside a struct). The reason for this difference is to prevent database instance files from becoming dependent on the order of fields in a record; if we permit record instances to be created from a single comma-separated list of field values without the field names, it could lead to significant confusion if the field order ever changes.

;''recordBodyItem:''
: ''infoAssignment''
: ''fieldAssignment''
: ''extraFieldAssigment''

== Information Fields ==

;''infoAssignment:''
: <tt>info</tt> ''infoName'' <tt>=</tt> ''stringConstant'' <tt>;</tt>

;''infoName:''
: ''identifier''
: ''stringConstant''

Info items provide additional configuration data about this record that can be accessed by other software running on the IOC.

info savePeriod = "30.0";
info restorePhase = "1";
info "my favourite things" = "raindrops on roses";

== Field Assignment ==

;''fieldAssignment:''
: ''fieldName'' <tt>=</tt> ''initializer'' <tt>;</tt>

;''fieldName:''
: ''identifier''

;''initializer:''
: ''constant''
: ''structInitializer''
: ''arrayInitializer''
: ''linkInitializer''

;''initializerList:''
: ''initializer''
: ''initializerList'' <tt>,</tt> ''initializer''

The ''initializer'' in a field assignment is also the exact same syntax that will be used when converting a string value from a CA client for example into a field value that is being put into a field.

=== Basic and Enumerated Initializers ===

;''constant:''
: ''booleanConstant''
: ''integerConstant''
: ''realConstant''
: ''stringConstant''

The syntax for the field initializer depends on the data type represented by fieldName. Basic types (numeric or string) should need no comment other than to note that values for numeric fields must not be given inside quotes (unlike EPICS V3). Menu field values may be given as either a string or an integer. For enum fields, if the related field that contains the strings is defined first, the enum field may be specified using a string; otherwise it can only be set using an integer value.

Examples:
ai foo:bar:temperature = {
inputSmoothing = 0.98;
invalidValue = 1000;
units = "Celcius";
scan = "Interrupt";
...
}

=== Structure Initializers ===

;''structInitializer:''
: <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''structAssignmentList:''
: ''initializerList''
: ''fieldName'' <tt>=</tt> ''initializerList''
: ''structAssignmentList'' <tt>;</tt> ''fieldName'' <tt>=</tt> ''initializerList''

Initializers for a structure field look similar to a nested record body, but the rules are slightly different:
* You can give a series of values for adjacent items using a simple comma-separated list (for a record body, you ''must'' name each field)
* Semi-colons are required between a value and a following named item.

For example:

ai foo:temperature:sensor = {
linearConvert = {
mode = "Linear";
low = -12.5, 133.5
};
displayLimit = { 0, 100 };
...
}

=== Link Initializer ===

;''linkInitializer:''
: ''choiceName(interfaceName)'' <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''choiceName:''
: ''identifier''

;''interfaceName:''
: ''identifier''

These select a particular link support and interface for the field, and set its address according to the structure type defined for that link type.

calcout foo:temperature:controller = {
output = outputLink(LinkFloat64){
pvname = "fum:baz:heater";
process = true;
wait = true;
block = true;
}
input = [2] {
{link = {
monitorLink(LinkFloat64){
pvname = "foo:temperature:setpoint";
process = false
}
}
{link = {
inputLink(LinkFloat64){
pvname = "foo:temperature:sensor";
process = true;
wait = true;
block = true;
inheritSeverity = true
}
}
};
expression = "(setpoint - current) > 0";
...
}

mbbi foo:bar:door = {
input = acro9440(0, 5);
...
}

=== Array Initializers ===

;''arrayInitializer:''
: <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>

;''arrayAssignmentList:''
: ''initializerList''
: <tt>[</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''
: ''arrayAssignmentList'' <tt>; [</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''

;''arrayType:''
: ''one of:'' <tt>bool</tt> <tt>int16</tt> <tt>uint16</tt> <tt>int32</tt> <tt>uint32</tt>
: ''one of:'' <tt>float32</tt> <tt>float64</tt> <tt>octet</tt> <tt>string</tt>

;''arrayCapacity:''
: ''integerConstant''
: ''arrayCapacity'' <tt>,</tt> ''integerConstant''

If the definition of the array field being set did not do so, an array field initialization must include the size of the array and/or the type of the data stored in it. Inside the braces data values are given in a comma-separated list; the index can also be set to initialize individual values, and any mixture of the two can be used as desired:

mbbi foo:bar:door = {
stateNames = [4] {"Broken", "Closed", "Open", "Moving"};
stateSeverity = [4] {"Major"; [3] = "Minor"};
...
}

For multi-dimensional arrays, data values can only appear inside the inner-most sets of braces, although index settings are permitted outside of these. These two definitions give the same result:

matrix identity1 = {
value = float32 [3,3] { {1, 0, 0}, {0, 1, 0}, {1, 0, 0}};
}
matrix identity2 = {
value = float32 [3,3] { {1}, {[1] = 1}, {[2] = 1}};
}

V4 DBD Statement Syntax

2005-09-30T15:12:36Z

MartyKraimer: Changed DBD link definition

DBD Statement Syntax Sept 30 2005
----
= Overview =
This document presents the syntax for V4 database definition files.
<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

link(linkDirection,interface(interfaceName,...))

ANDREW
What syntax should we use?
The idea is that the record definition gives a list of interfaces it understands.

where
* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
* <tt>interface(string,...)</tt> : Each interfaceName is the name of an interface implemented by link support and used by record support.

Examples:
field(disableLink,
link(in,interface ( LinkInt32, LinkFloat64 ))
)
field(process, link(process,interface(ProcessLink))
field(inp,
link(in, interface (LinkInt32, LinkFloat64, AsynDigital))
)

== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= link =
</center>

A <tt>link</tt> statement describes an implementation of support for a link
field. the support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

link(dir, choiceName, dataStructName, interface(interfaceName,...))

where

; <tt>dir</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

; <tt>interface</tt>
: A list of the interfaces implemented by the link support

When a record instance is created the choiceName and interfaceName
selects the support to attach to a record link.
The interfaceName must be one of the
interface names the record has listed as a valid type and dir must be compatible
with the dir the record type specified.
Compatibility means that the dir specified in the link definition is at
least as generic as the link definition in the record.
If the record link dir is:
; <tt>none</tt>
: The link definition must also be <tt>none</tt>
; <tt>process</tt>
: The link definition must also be <tt>process</tt>
; <tt>in</tt>
: The link definition must be <tt>in</tt> or <tt>inout</tt>
; <tt>out</tt>
: The link definition must be <tt>out</tt> or <tt>inout</tt>
; <tt>inout</tt>
: The link definition must be <tt>out</tt> or <tt>inout</tt> or <tt>inout</tt>

Examples:
link(process,processLink,ProcessLinkData,interface(ProcessLink))

link(in,monitorLink,MonitorLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))

V4 DB RecordCommon

2005-09-30T15:11:15Z

MartyKraimer:

EPICS V4: Standard Support September 30 2005
----

= Overview =

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd defines widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

----
<center>
= dbCommon =
</center>

== Channel/Database Access Support ==

=== Data Structures ===
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(OutputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(ProcessLinkData) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
}

=== link support definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(process,processLink,ProcessLinkData,interface(ProcessLink))

link(in,monitorLink,MonitorLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,monitorLinkArray,MonitorLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,inputLink,InputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,inputLinkArray,InputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))
link(in,outputLink,OutputLinkData interface(
LinkBoolean,
LinkInt16,LinkInt32,LinkInt64,
LinkFloat32,LinkFloat64,
LinkString
))
link(in,outputLinkArray,OutputLinkData interface(
LinkArrayOctet,LinkArrayBoolean,
LinkArrayInt16,LinkArrayInt32,LinkArrayInt64,
LinkArrayFloat32,LinkArrayFloat64,
LinkArrayString
))

== asynDriver link support ==
=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Average,AsynLinkData,interface(LinkInt32))
link(in,asynInt32Monitor,AsynLinkData,interface(LinkInt32))
link(inout,asynFloat64,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Average,AsynLinkData,interface(LinkFloat64))
link(in,asynFloat64Monitor,AsynLinkData,interface(LinkFloat64))
link(in,asynDigitalMonitor,AsynLinkData,interface(AsynDigital))
link(inout,asynDigital,AsynLinkData,interface(AsynDigital)))
link(inout,asynInt32Array,AsynLinkData,interface(LinkArrayInt32)))
link(inout,asynFloat64Array,AsynLinkData,interface(LinkArrayFloat64)))
link(inout,asynOctet,AsynLinkData,interface(AsynOctet)))
== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

# usefull struct definitions

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= RecordCommon =
</center>

== Menu Definitions ==

# menu definitions for RecordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}
== struct definitions for RecordSupport ==
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in,interface(????))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in,interface(LinkBoolean)))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

== RecordCommon Record Definition ==

struct(RecordCommonProcessLink) {
field(link,link(process,interface(ProcessLink)))
}

record(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmAckTransient,boolean) {
readonly(yes)
default("YES")
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(RecordCommonProcessLink[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be privaye to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

V4 Link Support Tutorial

2005-09-29T19:26:18Z

MartyKraimer:

EPICS: IOC Link Support Tutorial Sept 29 2005
UNDER CONSTRUCTION

----
= Overview =

The V4 link support is a replacement for V3
# DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
# device DBD definition and device support
# driver DBD definition and driver support

The link support model is:
* For each link, record support defines a list of interfaces it can use for communicating with link support
* Link support registers the set of interfaces it implements

Link support has no knowledge of what record types are using it
and record support has no knowledge about link support other than the
interface it is using.

EPICS base defines a standard set of interfaces for link support.
The intention is that the set includes enough functionality such that
most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access
and by the generic EPICS device support supplied by asynDriver.
Since asynDriver is intended as a framework for interfacing to most hardware,
this means that the interfaces supplied and used by base allows support
for most hardware. The support can communicate with the hardware
however it wants but must implement some set of the interfaces defined
by base.

This document gives a brief overview of the V4 link support model.

----
<center>
= Database Definitions For Links =
</center>

This section first reviews the DBD syntax related to link definitions.
It then gives a brief description of link related definitions in dbCommon.dbd

== Syntax ==

A record link has the syntax:
link(linkDirection,interface(string,...))
A link itself has the syntax:
link(linkDirection, choiceName, interfaceName, dataStructName)

where

; <tt>linkDirection</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>interface</tt>
: This is a list of the interfaces that the record support understands.
; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName selects the support
to attach to a record link. The interfaceName must be one of the
interface names the record has listed as a valid type and linkDirection must be compatible
with the linkDirection the record type specified.

== Standard Definitions For Channel/Database Access ==

These are the database definitions defined in dbCommon are used by
the base supplied support for Channel/Database access.

=== Data Structures ===

The complete set of definitions are defined in "V4 DB RecordCommon".
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
... also OutputLinkData and ProcessLinkData

A look at the fields shows that these are what is required to implement
the V4 semantics for Channel/Database access links.

=== Link Definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

"V4 DB RecordCommon" describes the complete set of link definitions
supplied by EPICS base. Some examples are:

link(process,processLink,ProcessLink,ProcessLinkData);

link(in,monitorLinkArrayOctet,LinkArrayOctet,MonitorLinkData);
link(in,inputLinkArrayOctet,LinkArrayOctet,InputLinkData);
link(out,outputLinkArrayOctet,LinkArrayOctet,OutputLinkData);

link(in,monitorLinkBoolean,LinkBoolean,MonitorLinkData);
...

link(in,monitorLinkInt16,LinkInt16,MonitorLinkData);
link(in,monitorLinkInt32,LinkInt32,MonitorLinkData);
link(in,monitorLinkInt64,LinkInt64,MonitorLinkData);
...

link(in,monitorLinkFloat32,LinkFloat32,MonitorLinkData);
link(in,monitorLinkFloat64,LinkFloat64,MonitorLinkData);
...

link(in,monitorLinkArrayString,LinkArrayString,MonitorLinkData);
link(in,inputLinkArrayString,LinkArrayString,InputLinkData);
link(out,outputLinkArrayString,LinkArrayString,OutputLinkData);

These are the link definitions for the Channel/Database access link
support supplied with base. The support registers support for processLink,
monitorLinkArrayOctet, ...

== asynDriver link support ==

These are definitions that are used by the standard EPICS device support
for asynDriver. Since asynDriver is a generic way of interfacing arbitrary
hardware support, this is a generic way of attaching links in records to
hardware.

=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,LinkInt32,AsynLinkData)
link(in,asynInt32Average,LinkInt32,AsynLinkData)
link(in,asynInt32Monitor,LinkInt32,AsynLinkData)
link(inout,asynFloat64,LinkFloat64,AsynLinkData)
link(in,asynFloat64Average,LinkFloat64,AsynLinkData)
link(in,asynFloat64Monitor,LinkFloat64,AsynLinkData)
link(in,asynDigitalMonitor,AsynDigital,AsynLinkData)
link(inout,asynDigital,AsynDigital,AsynLinkData)
link(inout,asynInt32Array,LinkArrayInt32,AsynLinkData)
link(inout,asynFloat64Array,LinkArrayFloat64,AsynLinkData)
link(inout,asynOctet,AsynOctet,AsynLinkData)

This is the set of definitions for the standard EPICS device support implemented
by asynDriver. Although, at least for the first few V4 releases,
asynDriver will not be part of base, they are shown here because the
LinkInt32,... interface definitions are defined as part of base.
Again it is expected that almost all hardware support be created by
implementing a combination of these link interface definitions or
the interfaces implemented by Channel/Database access link support.
---
<center>
= Link Support =
</center>

== Overview ==
An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.

Other link support can also be supplied.
New support should try very hard to implement the standard interfaces
supplied by EPICS base. These are the interfaces that the record types
supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by
the Channel/Database access support supplied with base. The support
can, of course, define data structures for it's own use.
Implementing these interfaces means that nthe support will work for
the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces
implemented by the Channel/Database access support.
Message based support may also have to implement the AsynOctet interface
but this interface is only used by a few record links.

This section describes the interfaces implemented by all link support
and then the standard interfaces used by the records supplied with base.

== Link and MonitorLink ==

interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. An example is support for hardware interrupts.
The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call destroy before modifying the link
and initialize and connect after the link is modified.

== Definitions that apply to Process,Monitor,Input,and Output support ==
These are the definitions used by the Channel/Database access support
supplied with base. It is also used by the standard EPICS support from asyn.

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface ProcessLinkSupport<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

GENERIC QUESTION The data is passed as primitive or arrays of
primitive types. Should <tt>Dbf</tt> interfaces be used? Needs thought.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----
<center>
= Example - VME ADC support =
</center>
== DBD definitions ==
The following struct is defined for configuration information.
struct VMEADC {
field(a16 int16)
field(a32 int32)
field(channel int16)
}
The following link definition is defined:
link(in,myAdcSupport,LinkInt32,VMEADC)

This allows record instance definitions like:
AiRecord aiExample = {
...
input = myAdcSupport{a16=0x0010;channel=1}
...
}

The link support would be something like:

class AdcSupport : public Link LinkInt32 {
public:
AdcSupport(VMEADCData fromFactory) : data(fromFactory) connected(false)
{
// from the VMEADC initailze vmeaddr and channel
}

// Link methods
void report(int16_t level)
{
printf("AdcSupport a16 %x channel %d\n",a16,channel);
}
void cancel() {} // nothing to do
void destroy() {delete this};
void initialize()
{
// make sure we can access a16
}
void connect() {connected = true}
void disconnect() {connected = false}

// LinkInt32 methods
LinkWaitResult getWait(int32_t *data,Callback callback)
{
*data = (int32_t)vmeaddr[1];
return linkDone;
}
LinkWaitResult putWait(int32_t *data,Callback callback)
{
throw CantWriteAdc;
}
void getBounds(int32_t *low, int32_t *high)
{
// assume 16 bit unipolor adc
*low = 0; *high = 0xffff;
}
private:
VMEADCData data;
uint16_t *vmeaddr;
int channel;
bool connected;
}

Ancient V4 Design

2005-09-29T18:22:58Z

MartyKraimer:

This page links to various documents for discussion by the EPICS core developers.

'''Code to implement this stuff doesn't exist yet, and the designs may change!'''

''Note to authors: please use 'V4' at the start of page names for Version 4 documentation, as this makes it clear which wiki pages refer to the new designs just from the page name.''

I've started listing some discussion topics for a [[V4 July Meeting Agenda]], feel free to add to these - Andrew Johnson

== Overall Design ==
* [[V4 Use Cases]] - Bob Dalesio, Kay Kasemir

== Core and Database ==

* [[V4 Modules and Interfaces]] - Andrew Johnson

* [[V4 Requirements for Standard Types]] - Andrew Johnson
* [[V4 Standard Properties and Events]] - Andrew Johnson

* V4 Database Definition - Marty Kraimer, Andrew Johnson
** [[V4 DBD Statement Syntax]] - Marty Kraimer, Andrew Johnson
** [[V4 DB Record Instance Syntax]] - Andrew Johnson
** [[V4 DB RecordCommon]] - Marty Kraimer
** [[V4 DBD Examples]] - Marty Kraimer, Andrew Johnson
** [[V4 Link Support Tutorial]] - Marty Kraimer
** [[V4 View Generated Code]] - Andrew Johnson

* V4 Database Runtime
** [[V4 Design: Record Processing]] - Marty Kraimer
** [[V4 Design: dbdInterfaces]] - Marty Kraimer
** [[V4 Design: Runtime Interfaces]] - Marty Kraimer
** [[V4 Design: RecordCommon Support]] - Marty Kraimer

* V4 Database Access:
** [[V4 Design: epicsTypes]] - Marty Kraimer, Andrew Johnson
** [[V4 Design: Assembling Record Support]] - Ben Franksen
** [[V4 Design: driverInterfaces]] - Marty Kraimer

* [[V4 User-defined fields]] - Kay Kasemir

* [[V4 Server Side Plugins]] - Ralph Lange, Benjamin Franksen

* Obsolete
** [[V4 DBD dbCommon and iocRecord]] - Marty Kraimer
** [[V4 DBD Generated Code]] - Marty Kraimer
** [[V4 Design: dbdClass]] - Marty Kraimer
** [[V4 Design: dbdClass Examples]] - Marty Kraimer
** [[V4 Design: Database Initialization]] - Marty Kraimer
** [[V4 Design: Database Access Semantics]] - Marty Kraimer

== Network Communications ==

* [[V4 Name Server]] - Doug Murray, Kay Kasemir
* [[V4 CA Interfaces]] - Jeff Hill
* [[V4 CA Client User Interface]] - Doug Murray, Kay Kasemir
* [[V4 Data Interface]] - Kay Kasemir
* [[V4 CA example timeStamp, sevr, status, data]] - Marty Kraimer

== Other Services ==

* [[V4 Replacement for drvTS]] - Timo Korhonen
* [[V4 Replacement for SNL]] - Ben Franksen, Go"tz Pfeiffer
* [[V4 Data Store]] - Ralph Lange

V4 Design: RecordCommon Support

2005-09-28T19:41:08Z

MartyKraimer:

EPICS V4: RecordCommonSupport - September 22 2005
----
= Overview =

THIS WIKI IS OUT OF SYNC WITH OTHER WIKI PAGES. IT NEEDS LOTS OF WORK

This document describes the implementation of the record support
for RecordCommon, i.e. the set of fields associated with every record type.

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd define widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document describes the following:

* The code automatically generated from dbCommon.dbd and RecordCommon.dbd
* A proposed implementation of RecordCommonSupport.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 Design: Record Processing
# V4 Design: dbdInterfaces
# V4 Design: Runtime interfaces
# V4 Design: RecordCommon

Unless the reader is familiar with these most of this document will
be very difficult to understand.

Java is used as the example code for two reasons:
# For V4 iocCore it is intended that both C++ and Java implementations will be provided. Since V3 is only implemented in C and C++ the Java implemention of V4 is described first to make sure that the interfaces defined in dbdInterfaces will work for Java.
# Java provides facilities that make it easy to handle strings, arrays, and structures.

An implementaion of RecordCommonSupport is presented for two reasons:
# It demonstrates how to implement code that uses or implements the interface described in "V4 Design: dbdInterfaces" and "V4 Design: Runtime interfaces".
# It helps refine the interfaces described in them

----
<center>
= dbCommon.dbd =
</center>

See the description of <tt>dbCommon.dbd</tt> in "V4 Design: RecordCommon"

Link support must register support each of the <tt>link</tt> definitions.

From <tt>dbCommon.dbd</tt> the following class implementations are generated:
* For the link structures:
** <tt>MonitorLink</tt> and <tt>MonitorLinkData</tt>, and <tt>MonitorLinkSupport</tt>
** <tt>InputLink</tt>, <tt>InputLinkData</tt>, and <tt>InputLinkSupport</tt>
** <tt>OutputLink</tt>, <tt>OutputLinkData</tt>, and <tt>OutputLinkSupport</tt>
** <tt>ProcessLink</tt>, <tt>ProcessLinkData</tt>, and <tt>ProcessLinkSupport</tt>
* For TimeStamp
** <tt>TimeStamp</tt>, <tt>TimeStampData</tt>, and <tt>TimeStampSupport</tt>
* For Scan
** <tt>Scan</tt>, <tt>ScanData</tt>, and <tt>ScanSupport</tt>

See "V4 Design: Runtime interfaces" for an example of how these classes are defined.

----
<center>
= RecordCommon.dbd =
</center>

See the description of <tt>RecordCommon.dbd</tt> in "V4 Design: RecordCommon"

<tt>RecordCommon.dbd</tt> must be part of every record.

Implementations of <tt>Disable</tt>, <tt>DisableData</tt>,
and <tt>DisableDataSupport</tt>
are automatically generated.

An implementations of RecordCommon is also generated.
See "V4 Design: Runtime interfaces" for an example of the generated
classes.
----
<center>
= RecordCommonSupport.java =
</center>

== Overview ==
This section describes the java implementation of RecordCommon
functionality. This code handles processing of the following fields
of RecordCommon:
; <tt>disable</tt>
: Decides if the record is disabled.
; <tt>alarmStatus</tt> and <tt>alarmSeverity</tt>
: The only way to change alarmStatus and alarmSeverity is via interface Common, which is implemented by RecordCommonSupport.
; <tt>processLink</tt>
: This is an array of process links, which replace the V3 <tt>FLNK</tt>

The following subsection contains the complete code for RecordCommonSupport.java.
The remaining subsections discuss each part of the code.

== IocCommon.java ==

This defines
interface Common {
bool setSeverity(AlarmSeverity severity, string status);
}

== RecordCommonSupport.java ==
enum Mode {modeNone,modeInput,modeOutput};

public class RecordCommonSupport implements RecordSupport,Callback,Common
{
private RecordInstance instance;
private Mode mode;
private Input input;
private Output output;
private Alarm alarm;
private bool requestProcess;

// Constructor
public RecordCommonSupport(RecordInstance instance) {
this.instance = instance;
}

// Beginning of RecordSupport
public destroy() {} // destroy not needed for Java
public destroy() {} // destroy not needed for Java
public initialize(int pass) {
if(pass==0) return;
input.init(instance);
output.init(instance);
alarm.init(instance);
}

public processState process(processState state) {
switch(state) {
case processCancel:
//MUCH MORE NEEDS TO BE DONE
// MUST CANCAL ANY OUTSTANDING I/O
mode = modeNone; return processDone;
case processStart: {
mode = modeInput;
requestProcess = false;
LinkWaitResult result = input.disableSupport.getWait(
input.disableInput,0.0,this);
if(result==linkNoop || result==linkDone) return processDone;
requestProcess = true;
}
// fall through to processInputActive
case processInputActive: {
if(requestProcess) return processInputActive;
if(input.disable.disableValue == disable.disableInput)
return processDone;
return processActive;
}
case processDone: {
mode = modeOutput;
output.nextLink = 0;
output.numberLinksActive = 0;

}
// fall through to processOutputActive
case processOutputActive:
LinkWaitResult result = linkWaitParallel;
requestProcess = false;
while(output.nextLink< output.link.length) {
if(result==linkWaitSequential) break;
result = output.link[nextLink].support.processWait(0.0,this);
if(result==linkWaitSequential || result==linkWaitParallel)
output.numberLinksActive++
output.nextLink++;
}
if(output.numberLinksActive==0) {
mode = modeNone;
return processDone;
}
requestProcess = true;
return processOutputActive;
default: throw java.lang.IllegalStateException;
}
}

public bool special(bool after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input.init(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output.init(instance); break;
default: printf("Why is special being called?\n");
}
}

// Start of Callback methods
public void done() {
lock(instance);
switch(mode) {
case modeNone:
unlock(instance)
throw java.lang.IllegalStateException;
case modeInput:
if(requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
break;
case modeOutput:
output.numberLinksActive--;
if(output.numberLinksActive==0 && requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
if(output.numberLinksActive==0 && requestProcess)
break;
}
unlock(instance)
}
public void failure() { done(); }

// Start of Common methods
bool setSeverity(AlarmSeverity severity, string status) {
Alarm alarm = this.alarm;
if(severity<= alarm.severity) return false;
alarm.severity = severity;
alarm.status = status;
alarm.modifyingAlarm = true;
alarm.alarmSeverity.putIndex(severity);
alarm.alarmStatus.put(status);
alarm.modifyingAlarm = false;
}
}

// Definitions for modeInput
class Input {
DisableData disable;
LinkSupport disableSupport;
DbfInt16 disableInput;
DbfInt16 disableValue;
DbfInt16 alarmSeverity;

void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField("disable.disableLink");
disableSupport = link.getSupport();
DisplayLimitAccess.get(
recordAccess.getField("disable"),disable);
recordAccess.getField("disable.disableInput",disableInput);
}
void special(RecordInstance instance,Dbf field) {
int16 index = Dbf.getIndex();
switch(index) {
case disableValueIndex:
disableValue = ((DbfInt16)Dbf).get(); break;
case disableInputIndex:
disableInput = ((DbfInt16)Dbf).get(); break;
case disableAlarmSeverityIndex:
alarmSeverity = ((dbfMenu)Dbf).getIndex(); break;
case disableLinkIndex:
init(instance); break;
default:
throw java.lang.IllegalStateException;
}
}
}

// Definitions for modeOutput
class OutputLink {
Link link;
LinkSupport support;
void init(RecordInstance instance,String linkFieldName) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField(linkFieldName);
support = link.getSupport();
}
};

class Output {
int nextLink;
int numberLinksActive;
OutputLink[] link;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfArray array = recordAccess.getField("processLink");
int n = array.getNelements();
link = new OutputLink[n];
for(i=0; i< n; i++) {
String field = "processLink[" + "i" + "]";
link[i].init(instance,field);
}
}
}

// Definitions for alarm handling
class Alarm {
short severity;
String status;
DbfMenu alarmSeverity;
DbfString alarmStatus;
bool modifyingAlarm;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
alarmSeverity = recordAccess.getField("alarmSeverity");
alarmStatus = recordAccess.getField("alarmStatus");
}
}

== Beginning of class definition ==
enum Mode {modeNone,modeInput,modeOutput};

public class RecordCommonSupport implements RecordSupport,Callback, Common
{
private RecordInstance instance;
private Mode mode;
private Input input;
private Output output;
private Alarm alarm;
private bool requestProcess;

// Constructor
public RecordCommonSupport(RecordInstance instance) {
this.instance = instance;
}

RecordCommonSupport implements the following interfaces:
; <tt>RecordSupport</tt>
: Record support for the fields in RecordCommon.
; <tt>Callback</tt>
: The callbacks called by link support
; <tt>Common</tt>
: For now this just has the method <tt>setSeverity</tt>

It has the following private fields:
* <tt>instance</tt> - The record instance to which it is attached. <tt>RecordCommonSupport</tt> has a single constructor which is passed the <tt>RecordInstance</tt> to which it is attached.
* <tt>mode</tt> - This keeps the state for record processing:
** <tt>modeNone</tt> - The record is not being processed.
** <tt>modeInput</tt> - The disable link is active but not complete.
** <tt>modeOutput</tt> - The processLinks are active but not complete.
* <tt>input</tt> - Input is a private class that provides access to the fields of disable.
* <tt>output</tt> - Output is a private class that provides access to processLink.
* <tt>alarm</tt> - Alarm is a private class that provides access to fields alarmSeverity and alarmStatus.
* <tt>requestProcess</tt> - This is used by callback to decide if a request should be made to process the record.

Notes about <tt>Input</tt>, <tt>Output</tt>, and <tt>Alarm</tt>.
* Each of these is a private class to RecordCommonSupport.
* Each makes fields available to RecordCommonSupport.
* Each has "introspection" code that gets the values of the private fields from RecordCommon fields during record initialization of if the an RecordCommon fields is changed via a call to <tt>Dbf.put</tt>.
* The implementations of each of these private classes is given after the implementaion of RecordCommonSupport.

== RecordSupport Methods ==
=== initialize ===

public initialize(int pass) {
if(pass==0) return;
input.init(instance);
output.init(instance);
alarm.init(instance);
}

During the first pass of initialization, nothing needs to be done.
Before initialize is called on pass 1, iocInit has
already called link support so that it connects.
Initialize just calls its private class init methods. They get the
current values of their private fields.

=== destroy ===
public destroy() {} // destroy not needed for Java

Since Java does garbage collection destroy is not needed.
Note that iocCore will call all the link support destroy methods.

=== process ===

<tt>process</tt> is called by dbProcess at the beginning of record processing
and after the record specific record support completes.
During the beginning of record processing
process takes care of field <tt>disable</tt>
During the end of record processing process
takes care of field <tt>processLink</tt>.

A few features of <tt>process</tt> are:
* implements a state machine that handles the links.
* interacts with Callback, which is called by link support when links complete.
* interacts with special, which is called when fields in RecordCommon are modified.

public processState process(processState state) {
switch(state) {
case processCancel: mode = modeNone; return processDone;
case processStart: {
mode = modeInput;
requestProcess = false;
LinkWaitResult result = input.disableSupport.getWait(
input.disableInput,0.0,this);
if(result==linkNoop || result==linkDone) return processDone;
requestProcess = true;
}
// fall through to processInputActive
case processInputActive: {
if(requestProcess) return processInputActive;
if(input.disable.disableValue == disable.disableInput)
return processDone;
return processActive;
}
case processDone: {
mode = modeOutput;
output.nextLink = 0;
output.numberLinksActive = 0;

}
// fall through to processOutputActive
case processOutputActive:
LinkWaitResult result = linkWaitParallel;
requestProcess = false;
while(output.nextLink< output.link.length) {
if(result==linkWaitSequential) break;
result = output.link[nextLink].support.processWait(0.0,this);
if(result==linkWaitSequential || result==linkWaitParallel)
output.numberLinksActive++
output.nextLink++;
}
if(output.numberLinksActive==0) {
mode = modeNone;
return processDone;
}
requestProcess = true;
return processOutputActive;
default: throw java.lang.IllegalStateException;
}
}

=== special ===
<tt>special</tt> is called when any of the fields in <tt>disable</tt>,
<tt>alarmStatus</tt>, <tt>alarmSeverity</tt>, or <tt>processLink</tt> are changed.
public bool special(bool after,Dbf[] field) {
int nlevels = field.length;
assert(nlevels>0);
if(index==alarmStatusIndex || index==alarmSeverityIndex) {
if(!alarm.modifyingAlarm) return false;
return true;
}
if(!after) return;
switch(index) {
case disableIndex: {
if(nlevels==1) {
input.init(instance);
} else {
input.special(instance,Dbf[1]);
}
break;
}
case processLinkIndex : output.init(instance); break;
default: printf("Why is special being called?\n");
}
}

== Private Class Methods ==
=== Callback methods ===
These are the callback methods that are called by link support.
// Start of Callback methods
public void done() {
lock(instance);
switch(mode) {
case modeNone:
unlock(instance);
throw java.lang.IllegalStateException;
case modeInput:
if(requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
break;
case modeOutput:
output.numberLinksActive--;
if(output.numberLinksActive==0 && requestProcess) {
requestProcess = false;
DbAccess.process(instance);
}
return;
}
unlock(instance);
}
public void failure() { done(); }

=== Common methods ===
For now the only method is <tt>setSeverity,</tt>
The only way code can change severity and status is to call this method.

// Start of Common methods
bool setSeverity(AlarmSeverity severity, string status) {
Alarm alarm = this.alarm;
if(severity<= alarm.severity) return false;
alarm.severity = severity;
alarm.status = status;
alarm.modifyingAlarm = true;
alarm.alarmSeverity.putIndex(severity);
alarm.alarmStatus.put(status);
alarm.modifyingAlarm = false;
}
}

=== Input ===
This is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init and special methods are called to get values for the private fields.

// Definitions for modeInput
class Input {
DisableData disable;
LinkSupport disableSupport;
DbfInt16 disableInput;
DbfInt16 disableValue;
DbfInt16 alarmSeverity;

void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField("disable.disableLink");
disableSupport = link.getSupport();
DisplayLimitAccess.get(
recordAccess.getField("disable"),disable);
recordAccess.getField("disable.disableInput",disableInput);
}
void special(RecordInstance instance,Dbf field) {
int16 index = Dbf.getIndex();
switch(index) {
case disableValueIndex:
disableValue = ((DbfInt16)Dbf).get(); break;
case disableInputIndex:
disableInput = ((DbfInt16)Dbf).get(); break;
case disableAlarmSeverityIndex:
alarmSeverity = ((dbfMenu)Dbf).getIndex(); break;
case disableLinkIndex:
init(instance); break;
default:
throw java.lang.IllegalStateException;
}
}
}

=== OutputLink and Output ===
Output is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init method is called to get values for the private fields.
OutputLink is used by Output.

// Definitions for modeOutput
class OutputLink {
Link link;
LinkSupport support;
void init(RecordInstance instance,String linkFieldName) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfLink link = recordAccess.getField(linkFieldName);
support = link.getSupport();
}
};

class Output {
int nextLink;
int numberLinksActive;
OutputLink[] link;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
DbfArray array = recordAccess.getField("processLink");
int n = array.getNelements();
link = new OutputLink[n];
for(i=0; i< n; i++) {
String field = "processLink[" + "i" + "]";
link[i].init(instance,field);
}
}
}

=== Alarm ===
This is a private class for RecordCommonSupport.
It directly accesses the fields in this class.
The init method is called to get values for the private fields.

// Definitions for alarm handling
class Alarm {
short severity;
String status;
DbfMenu alarmSeverity;
DbfString alarmStatus;
bool modifyingAlarm;
void init(RecordInstance instance) {
RecordAccess recordAccess = instance.getRecordCommonAccess();
alarmSeverity = recordAccess.getField("alarmSeverity");
alarmStatus = recordAccess.getField("alarmStatus");
}
}

== RecordCommonSupportFactory ==
This is the factory for creating an RecordCommonSupport.
It is called by dbLoadRecords.

public class RecordCommonSupportFactory implements RecordSupportFactory{
RecordSupport create(RecordInstance instance) {
return new RecordCommonSupport(instance);
}
void destroy(RecordSupport support) {
RecordCommonSupport RecordCommonSupport = support;
RecordCommonSupport.destroy();
}
}

public final class RecordCommonSupportFactoryRegister {
static public createAndRegister() {
RecordCommonSupportFactory factory = new RecordCommonSupportFactory;
RegisterSupport.record(factory,"RecordCommon");
}
}

Question
Who calls RecordCommonSupportFactoryRegister.createAndRegister?

V4 Design: Runtime Interfaces

2005-09-28T19:32:08Z

MartyKraimer:

EPICS: IOC Runtime Interfaces September 28 2005

----
= Overview =

This document describes definitions for IOC runtime,
i.e. interfaces implemented or used by database access, record support,
link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTE IOC runtime needs lots more work

----
<center>
= Support Code =
</center>

This section described interfaces for
strings, arrays, and conversions.
They are intended for use by Database Access, Record Support, etc.

== C++ support for strings ==

For most strings all the database needs is a nonmutable string.
For these it wants to be able to pass a reference to it to arbitrary code.
It needs this for things like record type names, field names, record instance names, menu choice names, etc. etc. Some of these may change but very infrequently.
The string always contains UTF-8 encoded strings, which I believe can be printed with a "%s" format if
the string is made available as a "const char *"

Perhaps the only type of string connected with an IOC record that changes frequently is a field in a record type like stringin and stringout. In this case the record support can do what ever it wants to handle the string. It can even just use C style strings!!!

Thus all the IOC database needs is a:

1) nonmutable reference counted continguous string. When the reference count goes to 0 the storage can be reclaimed
2) The ability to copy the value from a nonmutable string to a mutable string.

In Java String and StringBuffer are all that is needed.

In C++ all that is needed is

1) A class that holds UFT-8 encoded non-mutable strings and make the contents available as a "const char *" and it's length. The class keeps a reference count and frees the storage when done.
2) The ability to copy the nonmutable string to a "char *" array allocated by the requester.

That is all.

== array copy ==

ArrayCopy copies arrays an array performing conversions if necessary.

interface ArrayCopy {
void copy(DbfArray from,DbfArray to);
}

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64.
It does NOT convert between
* DbfBoolean and another type.
* DbfOctet and another type.
Thus for DbfBoolean and DbfOctet it is willing to copy
but not convert to/from other types.

== Arithmetic Conversions ==
This is a static class that converts between primitie types and arrays of primitive types.

static class DbfConvertPrimitive {
public:
int16 get(Dbf from);
int32 get(Dbf from);
int64 get(Dbf from);
float32 get(Dbf from);
float64 get(Dbf from);
get(Dbf from, String value);
get(DbfOctet from, String value);
get(DbfBoolean from, String value);
put(Dbf to, int16 value);
put(Dbf to, int32 value);
put(Dbf to, int64 value);
put(Dbf to, float32 value);
put(Dbf to, float64 value);
put(Dbf to,int32 String value);
put(DbfOctet to, String value);
put(DbfBoolean to, String value);

get(DbfArray from, int16[] value);
get(DbfArray from, int32[] value);
get(DbfArray from, int64[] value);
get(DbfArray from, float32[] value);
get(DbfArray from, float64[] value);
put(DbfArray to, int16[] value);
put(DbfArray to, int32[] value);
put(DbfArray to, int64[] value);
put(DbfArray to, float32[] value);
put(DbfArray to, float64[] value);
}

NOTES:
* For Dbf <tt>to</tt> and <tt>from</tt> must be one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>
* The get to a string implements printf semantics
* The put from a string value just scanf semantics.
* The <tt>DbfOctet</tt> methods convert to/from a string of the form "0xXX"
* The <tt>DbfBoolean</tt> get method supports all the choices specified in the DBD Record Instance Specification
* For DbfArray <tt>to</tt> and <tt>from</tt> must be an array of one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>

----
<center>

= Code generated from Database Definition Files =
</center>

The following shows the Java code generated from DBD files:

== structure definitions ==

Two files are generated from <tt>struct(name)</tt> definitions.
# <tt>name.java</tt>
# <tt>nameSupport.java</tt>

<tt>name.java</tt> implements:
interface Struct {
Dbf getField(int16 index);
}

If a structure is defined as:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

A generated file <tt>DisplayLimit.java</tt> contains:

public class DisplayLimit implements Struct{
public DbfFloat64 low;
public DbfFloat64 high;
public static final short lowIndex = 1;
public static final short highIndex = 2;
public static final short lastIndex = indexHigh;
Dbf getField(short index) {
switch(index) {
case lowIndex: return(low);
case highIndex: return(high);
default: throw java.lang.IllegalStateException;
}
return null;
}
}

A generated file <tt>DisplayLimitAccess.java</tt> contains:

public class DisplayLimitData {
public double low;
public double high;
}
public final class DisplayLimitAccess implements StructFactory{
public Struct create() { return new DisplayLimit; }
public static final void get(DbfStruct from,DisplayLimitData data) {
DbfFloat64 dbf = from.getInterface(1);
data.low = dbf.get();
DbfFloat64 dbf = from.getInterface(2);
data.high = dbf.get();
}
public static final void put(DbfStruct to, DisplayLimitData data) {
DbfFloat64 dbf = to.getInterface(1);
dbf.put(data.low);
DbfFloat64 dbf = to.getInterface(2);
dbf.put(data.high);
}
}

public final class DisplayLimitAccessRegister {
static public createAndRegister() {
DisplayLimitAccess access = new DisplayLimitAccess;
RegisterSupport.structure(access,"DisplayLimit");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call DisplayLimitAccessRegister.createAndRegister.

Similar files are generated for C++.

== record definitions ==
If a record is defined as:
record(Example) extends RecordCommon {
...
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}

The generated Java file is

public class ExampleRecord implements Struct {
public DbfBoolean fboolean;
public DbfOctet ctet;
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 DbfDevice device;
public DbfStruct displayLimit;
public static final int16 fbooleanIndex = 1;
...
public static final int16 lastIndex = displayLimitIndex;
Dbf getField(short index) {
switch(index) {
case fbooleanIndex : return(fboolean);
...
case displayLimitIndex: return(displayLimit);
default: throw java.lang.IllegalStateException;
}
}
}

public final class ExampleRecordFactory implements StructFactory{
public static final Struct create() { return new ExampleRecord; }
}

public final class ExampleRecordFactoryRegister {
static public createAndRegister() {
ExampleRecordFactory factory = new ExampleRecordFactory;
RegisterSupport.record(factory,"ExampleRecord");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

----
<center>
= Record Support =
</center>

enum ProcessState {
processCancel,
processStart,
processContinue,
}

enum ProcessReturn {
processDone,
processAbort,
processActive
}

interface RecordSupport {
void destroy();
void initialize(int32 pass);
ProcessState process(ProcessState state,Callback done);
// if special returns false when after is false put fails
boolean special(boolean after,Dbf[] field);
}

<tt>ProcessState</tt> supports the following semantics:
* cancel - If the record is active terminate
* For all other states see the companion document "V4 Design: Record Processing"

The methods of <tt>RecordSupport</tt> are:
* <tt>destroy</tt> - Called when a record instance is deleted.
* <tt>initialize</tt> - Called twice (pass = 0,1) when a record is initialized.
* <tt>process</tt> - Called to process a record. See "V4 Design: Record Processing" for semantics.
* <tt>special</tt> - Called when a field declared special in a DBD file is modified. <tt>field</tt> is an array of Dbfs showing which field is being modified.

== Discussion of special ==

Special is passed a Dbf array that identifies the field being modified.
For example <tt>ExampleRecord.dbd</tt> has a field:
field(displayLimit,struct(displayLimit))
<tt>ExampleRecordSupport.java</tt> might implement special as follows:
boolean special(boolean after, Dbf[] field)
{
switch(field[0].getIndex()) {
...
case ExampleRecord.displayLimitIndex:
if(field.length==1) {
// displayLimits itself is being modified. Do something
} else {
// a field of displayLimits is being modified
switch(field[1].getIndex) {
case DisplayLimit.lowIndex:
// low being modified. do something
case DisplayLimit.highIndex:
// high being modified. do something
}
}
...
}
}
----
<center>

= Link Support =
</center>

An arbitrary number of Link Support implementations can exist.
An implementation can be either soft support or support that communicates with
hardware.
EPICS base supplies support that accesses data via channel access, i.e.
access to records in the same or other IOCS.

Recall that the link DBD definition is:

link(dir, choiceName, interfaceName, dataStructName)

<tt>choiceName</tt> is the name that identifies the implementation.
<tt>interfaceName</tt> is the name of the interface that record support
uses and the support implements.
<tt>dataStructName</tt> is the name of a structure used by support for
configuration.

This section describes that standard <tt>interfaceNames</tt> that
are used by the record types supplied with epics base.
These interfaces are appropriate for the soft support supplied with EPICS
base and should also be sufficient for a wide variety of hardware support.
In particular it is sufficient for communication with asynDriver.

== Link ==
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

interface MonitorLink {
void addMonitor(Callback callback);
void removeMonitor();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
<tt>MonitorLink</tt> is an interface that is implemented by link support that
supports monitors. Example are hardware interrupts.
The <tt>Link</tt> methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

The <tt>MonitorLink</tt> methods are:
* <tt>addMonitor</tt> - Add a monitor callback
* <tt>removeMonitor</tt> - Remove monitor

Normally record support does not need to call any of the Link
or MonitorLink methods since database access does this automatically.
For example if a link field is modified via a channel access put,
database access will call
destroy before modifying the link and initialize and connect after the
link is modified.

== Definitions that apply to Process,Monitor,Input,and Output support ==

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface ProcessLinkSupport<type> {
LinkWaitResult process(Callback callback);
}

== Octet Support ==
There is no support for octet but there is support for an array of octets.

interface LinkArrayOctet {
LinkWaitResult getWait(octet[] data,Callback callback);
LinkWaitResult putWait(octet[] data,Callback callback);
}

The data source must be an array of octets or the connect request will fail.

== asynOctet Support ==

This still needs more work. It attempts to reproduce the functionality
of V3 asynDriver.

interface AsynOctet {
LinkWaitResult write(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult writeRaw(Callback callback,
octet[] data, int32 numchars, Int32 nbytesTransfered);
LinkWaitResult read(Callback callback,
octet[] data, Int32 nbytesTransfered);
LinkWaitResult readRaw(Callback callback,
octet[] data, Int32 nbytesTransfered);
void flush();
void setInputEos(octet[] eos);
void getInputEos(octet[] eos);
void setOutputEos(octet[] eos);
void getOutputEos(octet[] eos);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}
struct asynDigitalInterrupt {
octet[] mask;
int32 addr;
Callback callback
}

interface AsynDigital {
LinkWaitResult write(octet[] value, octet[] mask);
LinkWaitResult read(octet[] value, octet[] mask);
void setInterrupt(octet[] mask, interruptReason reason);
void clearInterrupt(octet[] mask);
void getInterrupt(octet[] mask, interruptReason reason);
void registerInterruptUser(interruptCallbackUInt32Digital callback,
octet[] mask);
void cancelInterruptUser();
}

== Boolean Support ==
interface LinkBoolean {
LinkWaitResult getWait(Boolean data,Callback callback);
LinkWaitResult putWait(boolean data,Callback callback);
}
interface LinkArrayBoolean {
LinkWaitResult getWait(boolean[] data,Callback callback);
LinkWaitResult putWait(boolean[] data,Callback callback);
}

The data source must be a boolean or a string that contains a valid
boolean value.

== Integer Support ==

Support is available. for int16, int32, and int64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be int16, int32, or int64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
void getBounds(<type> low, <type> high);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

enum interruptReason {
interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
}

== Float Support ==

Support is available. for float32 and float64.
This section uses the Java generic syntax, e.g. <type>. In this
section <type> must be float32 or float64.

interface Link<type> {
LinkWaitResult getWait(<type> data,Callback callback);
LinkWaitResult putWait(<type> data,Callback callback);
}
interface LinkArray<type> {
LinkWaitResult getWait(<type>[] data,Callback callback);
LinkWaitResult putWait(<type>[] data,Callback callback);
}

== String Support ==
interface LinkString {
LinkWaitResult getWait(string data,Callback callback);
LinkWaitResult putWait(string data,Callback callback);
}
interface LinkArrayString {
LinkWaitResult getWait(string[] data,Callback callback);
LinkWaitResult putWait(string[] data,Callback callback);
}

The data source must be a string.

----

<center>
= Registration and Instance Creation =
</center>

interface StructFactory {
DbfStruct create();
}

interface RecordSupportFactory {
RecordSupport create(RecordInstance instance);
}

interface SupportFactory {
Support create(Dbf field);
}

interface RegisterSupport {
structure(StructFactory create, string name);
record(StructFactory create, string name);
link(SupportFactory support,string name);
device(SupportFactory support,string name);
record(RecordSupportFactory support,string name);
}

<tt>RegisterSupport</tt> is implemented by iocCore.
Each <tt>struct</tt> DBD definition must register a StructFactory to
create instances of the structure or record.

Each link, device, and record support must register a SupportFactory to create
instances of the support to attach to the link, device, or record instance.
During database initialization, iocCore calls the factory methods.

----
<center>

= Runtime Database Access =

</center>

== Overview ==

Database Access, with help from record, link, and device support
implements the dbdInterfaces.
Other than Database Access, fields of a record can only
be accessed via the interfaces described in dbdInterfaces.
This allows the database to handle
actions like posting database monitors without any help from
record, link, or device support.

Database access by default allocates the actual storage for each field
but allows support code to register itself to manage storage for field
instances.
Two examples, both involving arrays, are:
* The compress record registers to provide storage for the value.
** This allows it to implement a circular buffer.
** Code that accesses the value field may have to issue two get requests.
* Device support for a transient recorder registers to provide storage for the array
** This allows device support to read data from hardware in segments
** Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required.
Database Access will probably have something like the following:

class Field {
DbRecord instance;
short index;
};
...
class IntField extends Field {
int data;
}
...

This each field has the overhead of
* instance - a reference to DbRecord, i.e. record instance
* index - a 16 bit integer
* vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors.
These fields can start out null and only allocate storage as needed.

== Database Access ==

interface DbAccess {
void process(RecordInstance instance, Callback callback);
void processCancel(RecordInstance instance, Callback callback);
void processContinue(RecordInstance instance, Callback callback);
void processRequestAccept(Dbf field, boolean yesNo);
void registerDbfSource(Dbf field, Dbf source);
LinkSupport getLinkSupport(Dbf field);
Support getSupport(Dbf field);
RecordSupport getRecordSupport(DbInstance instance);
RecordSupport getRecordCommonSupport(DbInstance instance);
}

The methods are:
* <tt>process</tt> - Request processing. Record must be idle or active or request fails.
** <tt>instance</tt> - The record to process
** <tt>callback</tt> - A callback to call when processing completes or for failure.
* <tt>processRequestAccept</tt> - Should a process request from channel access be accepted,
* <tt>registerDbfSource</tt> - Register code that will implement storage for the field.
* <tt>getLinkSupport</tt> - Find the link support for a link field
* <tt>getSupport</tt> - Get the device support for a device field
* <tt>getRecordSupport</tt> - Get the record support for the record
* <tt>getRecordCommonSupport</tt> - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

----

V4 DBD Examples

2005-09-28T19:30:45Z

MartyKraimer:

Example Record Types Sept 28 2005
= Overview =
This document present proposed V4 replacements for a few of the
V3 record types.

<center>
= aoRecord =
</center>

aoRecord.dbd might be defined as follows:

include "dbCommon.dbd"
record(AoRecord) extends RecordCommon {
field(value, float64) {
asl(0)
}
field(outValue, float64) {
readonly(yes)
}
field(out,
link(out,interface( LinkInt64, LinkFloat64))
)
field(outputRateOfChange, float64)
field(desiredOutputLink,
link(in,interface(LinkFloat64))
)
field(closedLoop, bool)
field(outputIncremental, bool)
field(convert, menu(menuConvert)) {
special(yes)
}
field(linearConvert, struct(LinearConvert)) {
special(yes)
}
field(units, string)
field(displayLimit, struct(DisplayLimit))
field(controlLimit, struct(ControlLimit))
field(alarmLimit, struct(AlarmLimit))
field(alarmDeadband, float64)
field(rawValue, int64) {
design(no)
}
field(prevRawValue, int64) {
design(no)
readonly(yes)
}
field(readBackValue, int64) {
design(no)
readonly(yes)
}
field(init, bool) {
design(no)
readonly(yes)
}
field(simOutputLink,
link(out,interface(LinkFloat64))
)

field(simModeLink,
link(in,interface(LinkBoolean))
)
field(simMode, bool)
field(simSevr, menu(menuAlarmSevr))
field(invalidAction, menu(menuIvoa))
field(invalidValue, float64)
field(outValueModified, bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(controlLimit, controlLimit)
property(alarmLimit, alarmLimit)
}
}
view(output) {
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(raw) {
property(value, rawValue) {
property(timeStamp, time)
}
}
view(readback) {
property(value, readBackValue) {
property(timeStamp, time)
}
}
}

<center>
= calcRecord =
</center>

calcRecord.dbd defines the following:

include "dbCommon.dbd"
struct(CalcInpLink) {
field(link,link(in,interface(LinkFloat64))
field(value,float64)
}

record(CalcRecord) extends RecordCommon {
field(result,float64) {
asl(0)
}
field(calc,string) {
special(yes)
}
field(input,array(struct(CalcInpLink)[]))
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(alarmLimit,struct(AlarmLimit))
field(alarmDeadband,float64)
field(lastValueAlarmed,float64) {
design(no)
readonly(yes)
}
field(rpcl,private("char *"))
view(result) {
property(value, result) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(alarmLimit, alarmLimit)
}
}
view(expression) {
property(value, calc)
}
}

<center>
= mbbiRecord =
</center>

mbbiRecord.dbd could be:

include "dbCommon.dbd"
struct(MbbiState) {
field(name, string)
field(value, array(octet[]))
field(severity, menu(menuAlarmSevr))
}
record(MbbiRecord) extends RecordCommon {
field(state, array(struct(MbbiState)[])) {
special(yes)
}
#NOTE: stateName needed because enum must refer to array of string
field(stateName,array(string[])) {
design(no) readonly(yes)
}
field(value, enum(stateName)) {
asl(0)
}
field(unknownStateSeverity, menu(menuAlarmSevr))
field(changeStateSeverity, menu(menuAlarmSevr))
field(inp, link(in,interface(LinkOctetArray,AsynDigital))
field(rawValue, array(octet[])) {
design(no)
readonly(yes)
}
field(hardwareShift, int16) {
readonly(yes)
}
field(hardwareMask, array(octet[]) {
readonly(yes)
}
view(choice) {
property(value, value) {
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(raw) {
property(value, raw) {
property(timeStamp, time)
}
}
}

<center>
= waveformRecord =
</center>

waveformRecord.dbd defines the following:

include "dbCommon.dbd"
record(WaveformRecord) extends RecordCommon {
field(value, array([])) {
asl(0)
special(yes)
}
field(reArm,bool)
field(io,
link(inout,interface(
"LinkArrayOctet",
"LinkArrayBoolean",
"LinkArrayInt16",
"LinkArrayInt32",
"LinkArrayInt64",
"LinkArrayFloat32",
"LinkArrayFloat64",
"LinkArrayString",
} ))
)
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(busy,bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
}

V4 DB RecordCommon

2005-09-28T19:29:23Z

MartyKraimer:

EPICS V4: Standard Support September 28 2005
----

= Overview =

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd defines widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

----
<center>
= dbCommon =
</center>

== Channel/Database Access Support ==

=== Data Structures ===
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(OutputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(ProcessLinkData) {
field(pvname,string) { link}
field(wait,boolean)
field(timeout,float64)
field(block,boolean)
}

=== link support definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(process,processLink,ProcessLink,ProcessLinkData);

link(in,monitorLinkArrayOctet,LinkArrayOctet,MonitorLinkData);
link(in,inputLinkArrayOctet,LinkArrayOctet,InputLinkData);
link(out,outputLinkArrayOctet,LinkArrayOctet,OutputLinkData);

link(in,monitorLinkBoolean,LinkBoolean,MonitorLinkData);
link(in,monitorLinkArrayBoolean,LinkArrayBoolean,MonitorLinkData);
link(in,inputLinkBoolean,LinkBoolean,InputLinkData);
link(in,inputLinkArrayBoolean,LinkArrayBoolean,InputLinkData);
link(out,outputLinkBoolean,LinkBoolean,OutputLinkData);
link(out,outputLinkArrayBoolean,LinkArrayBooleanData);

link(in,monitorLinkInt16,LinkInt16,MonitorLinkData);
link(in,monitorLinkInt32,LinkInt32,MonitorLinkData);
link(in,monitorLinkInt64,LinkInt64,MonitorLinkData);
link(in,inputLinkInt16,LinkInt16,InputLinkData);
link(in,inputLinkInt32,LinkInt32,InputLinkData);
link(in,inputLinkInt64,LinkInt64,InputLinkData);
link(out,outputLinkInt16,LinkInt16,OutputLinkData);
link(out,outputLinkInt32,LinkInt32,OutputLinkData);
link(out,outputLinkInt64,LinkInt64,OutputLinkData);
link(in,monitorLinkArrayInt16,LinkArrayInt16,MonitorLinkData);
link(in,monitorLinkArrayInt32,LinkArrayInt32,MonitorLinkData);
link(in,monitorLinkArrayInt64,LinkArrayInt64,MonitorLinkData);
link(in,inputLinkArrayInt16,LinkArrayInt16,InputLinkData);
link(in,inputLinkArrayInt32,LinkArrayInt32,InputLinkData);
link(in,inputLinkArrayInt64,LinkArrayInt64,InputLinkData);
link(out,outputLinkArrayInt16,LinkArrayInt16,OutputLinkData);
link(out,outputLinkArrayInt32,LinkArrayInt32,OutputLinkData);
link(out,outputLinkArrayInt64,LinkArrayInt64,OutputLinkData);

link(in,monitorLinkFloat32,LinkFloat32,MonitorLinkData);
link(in,monitorLinkFloat64,LinkFloat64,MonitorLinkData);
link(in,monitorLinkString,LinkString,MonitorLinkData);
link(in,inputLinkFloat32,LinkFloat32,InputLinkData);
link(in,inputLinkFloat64,LinkFloat64,InputLinkData);
link(in,inputLinkString,LinkString,InputLinkData);
link(out,outputLinkFloat32,LinkFloat32,OutputLinkData);
link(out,outputLinkFloat64,LinkFloat64,OutputLinkData);
link(out,outputLinkString,LinkString,OutputLinkData);
link(in,inputLinkArrayFloat32,LinkArrayFloat32,InputLinkData);
link(in,inputLinkArrayFloat64,LinkArrayFloat64,InputLinkData);
link(out,outputLinkArrayFloat32,LinkArrayFloat32,OutputLinkData);
link(out,outputLinkArrayFloat64,LinkArrayFloat64,OutputLinkData);

link(in,monitorLinkArrayString,LinkArrayString,MonitorLinkData);
link(in,inputLinkArrayString,LinkArrayString,InputLinkData);
link(out,outputLinkArrayString,LinkArrayString,OutputLinkData);

== asynDriver link support ==
=== Data Definitions ===
struct(AsynLinkData) {
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}

=== link definitions ===

link(inout,asynInt32,LinkInt32,AsynLinkData)
link(in,asynInt32Average,LinkInt32,AsynLinkData)
link(in,asynInt32Monitor,LinkInt32,AsynLinkData)
link(inout,asynFloat64,LinkFloat64,AsynLinkData)
link(in,asynFloat64Average,LinkFloat64,AsynLinkData)
link(in,asynFloat64Monitor,LinkFloat64,AsynLinkData)
link(in,asynDigitalMonitor,AsynDigital,AsynLinkData)
link(inout,asynDigital,AsynDigital,AsynLinkData)
link(inout,asynInt32Array,LinkArrayInt32,AsynLinkData)
link(inout,asynFloat64Array,LinkArrayFloat64,AsynLinkData)
link(inout,asynOctet,AsynOctet,AsynLinkData)
== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

# usefull struct definitions

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= RecordCommon =
</center>

== Menu Definitions ==

# menu definitions for RecordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}
== struct definitions for RecordSupport ==
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in,interface(????))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in,interface(LinkBoolean)))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

== RecordCommon Record Definition ==

struct(RecordCommonProcessLink) {
field(link,link(process,interface(ProcessLink)))
}

record(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmAckTransient,boolean) {
readonly(yes)
default("YES")
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(RecordCommonProcessLink[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be privaye to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

V4 DBD Statement Syntax

2005-09-28T19:19:08Z

MartyKraimer:

DBD Statement Syntax Sept 28 2005
----
= Overview =
This document presents the syntax for V4 database definition files.
<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

link(linkDirection,interface(string,...))

ANDREW
What syntax should we use?
The idea is that the record definition gives a list of interfaces it understands.

where
* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
* <tt>interface(string,...)</tt> : Each string is the name of Link Interface implemented by link support and used by record support.

Examples:
field(disableLink,
link(in,interface ( LinkInt32, LinkFloat64 ))
)
field(process, link(process,interface(ProcessLink))
field(inp,
link(in, interface (LinkInt32, LinkFloat64, AsynDigital))
)

== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= link =
</center>

A <tt>link</tt> statement describes an implementation of support for a link
field. the support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

link(dir, choiceName, interfaceName, dataStructName)

where

; <tt>dir</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools do prompt the user to assign values to the structure.

When a record instance is created the choiceName selects the support
to attach to a record link. The interfaceName must be one of the
interface names the record has listed as a valid type and dir must be compatible
with the dir the record type specified.
Compatibility means that the dir specified in the link definition is at
least as generic as the link definition in the record.
If the record link dir is:
; <tt>none</tt>
: The link definition must also be <tt>none</tt>
; <tt>process</tt>
: The link definition must also be <tt>process</tt>
; <tt>in</tt>
: The link definition must be <tt>in</tt> or <tt>inout</tt>
; <tt>out</tt>
: The link definition must be <tt>out</tt> or <tt>inout</tt>
; <tt>inout</tt>
: The link definition must be <tt>out</tt> or <tt>inout</tt> or <tt>inout</tt>

Examples:
link(in,monitorLinkInt16,LinkInt16,MonitorLinkData);
link(in,inputLinkInt16,LinkInt16,InputLinkData);
link(out,outputLinkInt16,LinkInt16,OutputLinkData);
link(inout,asynInt32,LinkInt32,AsynLinkData)

V4 Design: Runtime Interfaces

2005-09-27T20:11:21Z

MartyKraimer:

EPICS: IOC Runtime Interfaces September 27 2005

----
= Overview =

This document describes definitions for IOC runtime,
i.e. interfaces implemented or used by database access, record support,
link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTE IOC runtime needs lots more work

----
<center>
= Support Code =
</center>

This section described interfaces for
strings, arrays, and conversions.
They are intended for use by Database Access, Record Support, etc.

== C++ support for strings ==

For most strings all the database needs is a nonmutable string.
For these it wants to be able to pass a reference to it to arbitrary code.
It needs this for things like record type names, field names, record instance names, menu choice names, etc. etc. Some of these may change but very infrequently.
The string always contains UTF-8 encoded strings, which I believe can be printed with a "%s" format if
the string is made available as a "const char *"

Perhaps the only type of string connected with an IOC record that changes frequently is a field in a record type like stringin and stringout. In this case the record support can do what ever it wants to handle the string. It can even just use C style strings!!!

Thus all the IOC database needs is a:

1) nonmutable reference counted continguous string. When the reference count goes to 0 the storage can be reclaimed
2) The ability to copy the value from a nonmutable string to a mutable string.

In Java String and StringBuffer are all that is needed.

In C++ all that is needed is

1) A class that holds UFT-8 encoded non-mutable strings and make the contents available as a "const char *" and it's length. The class keeps a reference count and frees the storage when done.
2) The ability to copy the nonmutable string to a "char *" array allocated by the requester.

That is all.

== array copy ==

ArrayCopy copies arrays an array performing conversions if necessary.

interface ArrayCopy {
void copy(DbfArray from,DbfArray to);
}

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64.
It does NOT convert between
* DbfBoolean and another type.
* DbfOctet and another type.
Thus for DbfBoolean and DbfOctet it is willing to copy
but not convert to/from other types.

== Arithmetic Conversions ==
This is a static class that converts between primitie types and arrays of primitive types.

static class DbfConvertPrimitive {
public:
int16 get(Dbf from);
int32 get(Dbf from);
int64 get(Dbf from);
float32 get(Dbf from);
float64 get(Dbf from);
get(Dbf from, String value);
get(DbfOctet from, String value);
get(DbfBoolean from, String value);
put(Dbf to, int16 value);
put(Dbf to, int32 value);
put(Dbf to, int64 value);
put(Dbf to, float32 value);
put(Dbf to, float64 value);
put(Dbf to,int32 String value);
put(DbfOctet to, String value);
put(DbfBoolean to, String value);

get(DbfArray from, int16[] value);
get(DbfArray from, int32[] value);
get(DbfArray from, int64[] value);
get(DbfArray from, float32[] value);
get(DbfArray from, float64[] value);
put(DbfArray to, int16[] value);
put(DbfArray to, int32[] value);
put(DbfArray to, int64[] value);
put(DbfArray to, float32[] value);
put(DbfArray to, float64[] value);
}

NOTES:
* For Dbf <tt>to</tt> and <tt>from</tt> must be one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>
* The get to a string implements printf semantics
* The put from a string value just scanf semantics.
* The <tt>DbfOctet</tt> methods convert to/from a string of the form "0xXX"
* The <tt>DbfBoolean</tt> get method supports all the choices specified in the DBD Record Instance Specification
* For DbfArray <tt>to</tt> and <tt>from</tt> must be an array of one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>

----
<center>

= Code generated from Database Definition Files =
</center>

The following shows the Java code generated from DBD files:

== structure definitions ==

Two files are generated from <tt>struct(name)</tt> definitions.
# <tt>name.java</tt>
# <tt>nameSupport.java</tt>

<tt>name.java</tt> implements:
interface Struct {
Dbf getField(int16 index);
}

If a structure is defined as:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

A generated file <tt>DisplayLimit.java</tt> contains:

public class DisplayLimit implements Struct{
public DbfFloat64 low;
public DbfFloat64 high;
public static final short lowIndex = 1;
public static final short highIndex = 2;
public static final short lastIndex = indexHigh;
Dbf getField(short index) {
switch(index) {
case lowIndex: return(low);
case highIndex: return(high);
default: throw java.lang.IllegalStateException;
}
return null;
}
}

A generated file <tt>DisplayLimitAccess.java</tt> contains:

public class DisplayLimitData {
public double low;
public double high;
}
public final class DisplayLimitAccess implements StructFactory{
public Struct create() { return new DisplayLimit; }
public static final void get(DbfStruct from,DisplayLimitData data) {
DbfFloat64 dbf = from.getInterface(1);
data.low = dbf.get();
DbfFloat64 dbf = from.getInterface(2);
data.high = dbf.get();
}
public static final void put(DbfStruct to, DisplayLimitData data) {
DbfFloat64 dbf = to.getInterface(1);
dbf.put(data.low);
DbfFloat64 dbf = to.getInterface(2);
dbf.put(data.high);
}
}

public final class DisplayLimitAccessRegister {
static public createAndRegister() {
DisplayLimitAccess access = new DisplayLimitAccess;
RegisterSupport.structure(access,"DisplayLimit");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call DisplayLimitAccessRegister.createAndRegister.

Similar files are generated for C++.

== record definitions ==
If a record is defined as:
record(Example) extends RecordCommon {
...
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}

The generated Java file is

public class ExampleRecord implements Struct {
public DbfBoolean fboolean;
public DbfOctet ctet;
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 DbfDevice device;
public DbfStruct displayLimit;
public static final int16 fbooleanIndex = 1;
...
public static final int16 lastIndex = displayLimitIndex;
Dbf getField(short index) {
switch(index) {
case fbooleanIndex : return(fboolean);
...
case displayLimitIndex: return(displayLimit);
default: throw java.lang.IllegalStateException;
}
}
}

public final class ExampleRecordFactory implements StructFactory{
public static final Struct create() { return new ExampleRecord; }
}

public final class ExampleRecordFactoryRegister {
static public createAndRegister() {
ExampleRecordFactory factory = new ExampleRecordFactory;
RegisterSupport.record(factory,"ExampleRecord");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

----
<center>
= Record Support =
</center>

enum ProcessState {
processCancel,
processStart,
processContinue,
}

enum ProcessReturn {
processDone,
processAbort,
processActive
}

interface RecordSupport {
void destroy();
void initialize(int32 pass);
ProcessState process(ProcessState state,Callback done);
// if special returns false when after is false put fails
boolean special(boolean after,Dbf[] field);
}

<tt>ProcessState</tt> supports the following semantics:
* cancel - If the record is active terminate
* For all other states see the companion document "V4 Design: Record Processing"

The methods of <tt>RecordSupport</tt> are:
* <tt>destroy</tt> - Called when a record instance is deleted.
* <tt>initialize</tt> - Called twice (pass = 0,1) when a record is initialized.
* <tt>process</tt> - Called to process a record. See "V4 Design: Record Processing" for semantics.
* <tt>special</tt> - Called when a field declared special in a DBD file is modified. <tt>field</tt> is an array of Dbfs showing which field is being modified.

== Discussion of special ==

Special is passed a Dbf array that identifies the field being modified.
For example <tt>ExampleRecord.dbd</tt> has a field:
field(displayLimit,struct(displayLimit))
<tt>ExampleRecordSupport.java</tt> might implement special as follows:
boolean special(boolean after, Dbf[] field)
{
switch(field[0].getIndex()) {
...
case ExampleRecord.displayLimitIndex:
if(field.length==1) {
// displayLimits itself is being modified. Do something
} else {
// a field of displayLimits is being modified
switch(field[1].getIndex) {
case DisplayLimit.lowIndex:
// low being modified. do something
case DisplayLimit.highIndex:
// high being modified. do something
}
}
...
}
}
----
<center>

= Link Support =
</center>

== Link ==
interface Link {
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

<tt>Link</tt> is an interface that must be implemented by every link
support.
An instance of this is connected to each DbfLink field.
The methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

Normally record support does not need to call any of the Link methods
since database access does this automatically. For example if a link
field is modified via a channel access put, database access will call
destroy before modifying the link and initialize and connect after the
link is modidied.

== Definitions that apply to Process,Monitor,Input,and Output support ==

enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWait, // waiting. can do additional procsssing
linkWaitBlock, // waiting. dont do additional processing until
}

interface Callback {
void done();
void failure();
}
== Process Link Support ==
interface ProcessLinkSupport<type> {
void process();
LinkWaitResult processWait(double timeout,Callback callback);
}

== Monitor Link Support ==
There is support for the following types: octet, boolean, int16, int32,
int64, float32, float64, and arrays of each of these types.

interface MonitorLink<type> {
void get(<type> data);
}

== Input Link Support ==
There is support for the following types: octet, boolean, int16, int32,
int64, float32, float64, and arrays of each of these types.

interface InputLinkSupport<type> {
void get(<type> data);
LinkWaitResult getWait(<type> data, double timeout,Callback callback);
}
== Output Link Support ==
There is support for the following types: octet, boolean, int16, int32,
int64, float32, float64, and arrays of each of these types.

interface OutputLinkSupport<type> {
void put(Dbf field);
LinkWaitResult putWait(Dbf field, double timeout,Callback callback);
}

----

<center>
= Registration and Instance Creation =
</center>

interface StructFactory {
DbfStruct create();
}

interface RecordSupportFactory {
RecordSupport create(RecordInstance instance);
}

interface SupportFactory {
Support create(Dbf field);
}

interface RegisterSupport {
structure(StructFactory create, string name);
record(StructFactory create, string name);
link(SupportFactory support,string name);
device(SupportFactory support,string name);
record(RecordSupportFactory support,string name);
}

<tt>RegisterSupport</tt> is implemented by iocCore.
Each <tt>struct</tt> DBD definition must register a StructFactory to
create instances of the structure or record.

Each link, device, and record support must register a SupportFactory to create
instances of the support to attach to the link, device, or record instance.
During database initialization, iocCore calls the factory methods.

----
<center>

= Runtime Database Access =

</center>

== Overview ==

Database Access, with help from record, link, and device support
implements the dbdInterfaces.
Other than Database Access, fields of a record can only
be accessed via the interfaces described in dbdInterfaces.
This allows the database to handle
actions like posting database monitors without any help from
record, link, or device support.

Database access by default allocates the actual storage for each field
but allows support code to register itself to manage storage for field
instances.
Two examples, both involving arrays, are:
* The compress record registers to provide storage for the value.
** This allows it to implement a circular buffer.
** Code that accesses the value field may have to issue two get requests.
* Device support for a transient recorder registers to provide storage for the array
** This allows device support to read data from hardware in segments
** Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required.
Database Access will probably have something like the following:

class Field {
DbRecord instance;
short index;
};
...
class IntField extends Field {
int data;
}
...

This each field has the overhead of
* instance - a reference to DbRecord, i.e. record instance
* index - a 16 bit integer
* vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors.
These fields can start out null and only allocate storage as needed.

== Database Access ==

interface DbAccess {
void process(RecordInstance instance, Callback callback);
void processCancel(RecordInstance instance, Callback callback);
void processContinue(RecordInstance instance, Callback callback);
void processRequestAccept(Dbf field, boolean yesNo);
void registerDbfSource(Dbf field, Dbf source);
LinkSupport getLinkSupport(Dbf field);
Support getSupport(Dbf field);
RecordSupport getRecordSupport(DbInstance instance);
RecordSupport getRecordCommonSupport(DbInstance instance);
}

The methods are:
* <tt>process</tt> - Request processing. Record must be idle or active or request fails.
** <tt>instance</tt> - The record to process
** <tt>callback</tt> - A callback to call when processing completes or for failure.
* <tt>processRequestAccept</tt> - Should a process request from channel access be accepted,
* <tt>registerDbfSource</tt> - Register code that will implement storage for the field.
* <tt>getLinkSupport</tt> - Find the link support for a link field
* <tt>getSupport</tt> - Get the device support for a device field
* <tt>getRecordSupport</tt> - Get the record support for the record
* <tt>getRecordCommonSupport</tt> - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

----

V4 Design: dbdInterfaces

2005-09-27T20:09:03Z

MartyKraimer:

EPICS: dbdInterfaces - IOC Database Description September 27 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 code that use code automatically
generated from DBD files or by code that uses only introspection.

Code is automatically generated from the following definitions:
* <tt>record</tt> - Used by record support.
* <tt>struct</tt> - Used by code that understands the struct.
* <tt>menu</tt> - Used by code that understands the menu.

----
<center>

= Syntax =
</center>

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 <tt>true</tt> or <tt>false</tt>
* 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 <tt>char *</tt> array containing UTF-8
compatible characters not necessarily terminated with a null character.
Wherever a <tt>string</tt> argument appears, the C++ definition
will have <tt>len</tt> and <tt>char *</tt> arguments.

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

An example of a definition that includes a string argument is
void get(String name);

In C++ this will become
void get(int lenName, char *name);
In Java this will become
void get(String name);
=== 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);

----
<center>

= DbfTypes =
</center>
The following naming conventions are used:
; Dbf
: any class starting with Dbf describes a field in a header file generated from a <tt>struct</tt> or <tt>record</tt> definition. For example DbfArray describes a field generated from <tt>field(name,array(float64[])</tt>.
; 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.

== <tt>DbfTypes.h</tt> ==

The following <tt>enum</tt> definitions describe
each field in the header files generated from DBD <tt>struct</tt> and
<tt>record</tt> 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
}

== Discussion of DbfTypes ==

The example code shown below uses Java syntax.
It assumes the following definitions:

struct(DisplayLimit) {
field(low,double)
field(high,double)
}
record(Example) extends RecordCommon {
...
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)
//FOLLOWING IS NOT VALID LINK DEFINITION
field(link,link(in))
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++.

----
<center>

= Database Fields =
</center>

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();
DbInstance 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;
short myint;
...
precord.ffloat.put(10.0);
...
myint = precord.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 = DbInstanceLocate.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(DbInstanceLocate.getField("recordname.value"),10.0);

== String fields ==

The interface for a string field is:

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

The following code prints a string.

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

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(name);
printf("field %s\n",name);
}

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 <tt>DbfArray</tt>

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});

== DbfMDArray ==
NOT YET DEFINED

== <tt>DbfMenu</tt> ==

<tt>DbfMenu</tt> is described as:
interface DbfMenu extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbdMenu getDbdMenu();
}

<tt>DbfMenu</tt> allows the menu index to be set and retrieved
and also provides access to the DbdMenu.

A <tt>DbfMenu</tt> field can be accessed via the generated header file or via
the introspection methods.

== DbfEnum ==

<tt>DbfEnum</tt> is described as:
interface DbfEnum extends Dbf {
int16 getIndex();
void putIndex(int16 val);
DbfStringArray getChoiceArray();
}

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

== DbfLink and DbfDevice ==

<tt>DbfLink</tt> is described as

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

interface DbfLink extends Dbf {
LinkDir getDir();
DbdLink getDbdLink();
}

== DbfTimeStamp ==

struct TimeStamp {
int64 secondsSinceEpoch;
int32 nanoSeconds;
}

interface DbfTimeStamp extends Dbf {
void get(TimeStamp timeStamp);
void put(TimeStamp timeStamp);
}

----
<center>

= DbdStatements =

</center>
These describe everything defined in database definition files.

== <tt>DbdMenu</tt> ==

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

== <tt>DbdLink</tt> ==

interface DbdLink {
LinkDir getDir();
int32 getChoiceNameLength();
void getChoiceName(String name);
int32 getInterfaceNameLength();
void getInterfaceName(String name);
int32 getDataStructNameLength();
void getDataStructName(String name);
}

== <tt>DbdStruct</tt> and <tt>DbdRecord</tt> ==

interface DbdAttribute {
int32 getDefaultLength();
void getDefault(String value);
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();
void getName(String name);
DbfType getType();
DbdDefaults getDefaults();
DbdAttribute getAttributes();
}

interface DbdStruct {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

interface DbdRecord {
int32 getNameLength();
void getName(String name);
int16 getNumberFields();
DbdField getFieldDescription(int16 index);
}

== Record Instance ==

interface DbInstance {
int32 getNameLength();
void getName(String name);
DbdRecord getDescription();
DbdRecord getRecordCommonDescription();
DbfStruct getInstance();
DbfStruct getRecordCommonInstance();
Dbf getField(String fieldName);
}

; <tt>getNameLength</tt>
: get length of record name
; <tt>getName
: get the record name
; <tt>getDescription</tt>
: get the description of the record specific portion of the record
; <tt>getRecordCommonDescription</tt>
: get the description of RecordCommon
; <tt>getInstance</tt>
: 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>
: get field instance. Workd for both record specific or RecordCommon field

----
<center>

= Locate Interfaces =

</center>

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 DbInstanceLocate {
public DbInstance getRecord(String name);
public Dbf getField(String name);
public Dbf getField(String recordName, String fieldName);
public LinkedList<DbInstance> instanceList;
public LinkedList<DbInstance> instanceList(String recordTypeName);
}

Question Are the above methods static or should there be something like
public class FindLocator {
public static DbdLocate findDbdLocate();
public static DbInstance findDbInstance();
}

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 = DbInstanceLocate.getField("example.value");
if(addr!=null) printf("found %s\n","example.value");

----

V4 Design: Record Processing

2005-09-27T20:07:47Z

MartyKraimer:

EPICS V4: Record Processing September 27 2005

----

= Overview =

UNRESOLVED ISSUES
* This document will undergo LOTS of evolution1
* Monitors
** How will monitor data be managed?
** Big problem is how will array data be managed?

This document described semantics for V4 record processing that are
different than for V3.
This includes the following:
* Semantics for Database and Channel Access Links.
* Semantics for record processing
* Record Locking
* Posting database monitors
* Status and Alarm Severity
* Access to array and structure fields.

This version is based on feedback from the EPICS core developer's
meeting at ANL/APS on July 11th through July 14th.
In addition discussions with Andrew Johnson and Eric Norum have
led to many of the ideas described below.
This wiki is a companion to the wiki "V4 Design: dbdInterfaces".

V3 record processing semantics do not work well for data
acquisition applications. An example of data acquisition is:
* Move sample to new position.
** Several motors may be involved
** While moving post monitors to show current position, etc.
* Sample data
* Wait until CA client has fetched the data before next move.

SynAPPS provides the Scan, motor, etc records which help with
data processing applications. These records process as follows:

* Record does not complete processing until all inputs, outputs, etc done. Not completing means that they do not call recGblFwdLink until all proccessing is complete. Note that recGblFwdLink is what causes the V3 ioc to complete record processing.
* While waiting for asynchronous events these records have PACT=0 but keep state that shows it is still active
* Can be scanned and issue monitors while internal state is active

Leaving PACT 0 but not calling recGblFwdLink was not anticipated when the V3 record processing semantics were created.
For V4 a record can be processed while it is waiting
for asynchronous processing to complete.

In V3, if an input link is asynchronous, Process Passive does not wait
for asynchronous processing to complete before fetching data.
This also complicated data acquisition applications.

V4 record processing is designed to make data acquisition easier.
Both input and output links can wait for record processing.
This is done, however, without record support blocking.
If blocking makes it easier to implement record support,
then the support can spawn a separate thread that does block.
Record support can communicate with the separate thread to decide when
to complete record processing.

----

<center>
= Goals for V4 Record Processing =
</center>

V4 record processing has the following features.
Some of these features were partially available in V3 but not in a
consistant way.

* All links to other records:
** Can request that the linked record be processed.
** Can wait until the linked record completes asynchronous processing.
* While record support is active a record can still be processed and post monitors.
* Database links are processed via queue requests rather than recursive calls to dbProcess
* Instead of lock sets, each record instance has a lock.
* Monitors are implemented by database access without help from record support

== Link Semantics ==

The link semanics are similar for database and channel access links (
input, output, and process).
All provide the ability to request processing and to wait until processing completes.

== Processing Local Links ==

A local link just means a link to a record in the same IOC.
In V3 records linked via database links are processed via recursive calls to
dbProcess. In V4 this will no longer be done.
Each thread that scans records,
e.g. the 1 second scan thread does the following
when a record requests processing of a local link:

* If the linked record is active or already queued the request fails.
* If the linked record does not allow link requests to cause processing the request fails.
* If a queue request is allowed then the request is handled as follows:
** The requests are queued if FIFO order
** The queue is emptied immediately after the record containing the link returns to DbProcess
** If all linked records complete synchronously the record containing the link is reprocessed before the thread processes any other records.

== Record Locking ==

V3 implemented lock sets in order to prevent different threads
from simultaneously accessing linked records.

Instead of lock sets V4:
* Implements a per record instance lock.
* Defines a rule that allows two records to be locked without deadlocks

== Posting Monitors ==

In V3 monitors are posted when code (record support, device support, database access, etc) calls db_post_event. In V4 database access will itself handle
the posting of monitors.

Monitors are posted by DbProcess when
* record support returns processActive.
* at the end of record processing.

== Database Field Types ==

V4 allows Channel and Database Access to the
following types of fields:

* primitive types
* string
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** struct
** array of primitive or string or struct

<center>
= Link Semantics =
</center>

NOTES:
* Link just means access to a record or field. The requester can be:
** A database link in a record
** A channel access link in a record
** A channel access client PV.
* Instead of "forward link" the name "process link" is used.
* wait does NOT mean to wait synchronously. It means to save state, return, and resume at the saved state when called again.
* block means to pause additional record processing until link completion. It doesd NOT mean to block synchronously. This determines if multiple links can be procesed in parallel.

Links are processed as follows:

* Process Link: Perform the following actions
** Request processing
** Optionally wait until linked record completes
** Optionally block until linked record completes
* Output Link:
** Put value
** Optionally request processing. If record can not be processed should the value be changed?
** Optionally wait until completion
** Optionally block until completion
* Input Link: Two flavors are available
** Monitor Link
*** Implemented via a monitor request on linked field
*** Optionally process record containing the link when monitor value is returned.
** Input Link: Perform the following actions
*** Optionally request that record be processed.
*** Optionally wait for linked record to complete processing.
*** Optionally block until completion
*** Get value.

The following rules apply when a process request is made:
* If record is already being processed the request fails.
* Record support can specify that links to particular fields not cause processing.
* A record can declare that it can not be processed via process links.
** This can be specified in the Database Definition or the record instance.
* If a process request is allowed, it will be done regardless of the scan mechanism, i.e. the record does not have to be passive.

----
<center>
= Record Processing Semantics =
</center>

This section describes the semantics implemented by DbProcess.

Each record type has two sets of record support.
One is implemented by RecordCommonSupport, which provides support for the
fields in RecordCommon.
The other is the record support for the fields in the record type,
which will be called RecordSupport in this section.
When "record support" is mentioned it can apply to either RecordCommonSupport or
RecordSupport.
Each support implements method process.

One of the arguments to process is processState which has the values:
* processCancel - Cancel any outstanding activity
* processStart - Start processing
* processContinue - Making additional call

process returns ProcessReturn which is one of the following:
* processDone - Done and successful
* processQuit - Do not do any more processing
* processActive - Not done

There are three stages to processing a record:
* RecordCommonSupport perform initial processing, e.g. all input links are processed.
* RecordSupport performs its processing in collaboration with link support
* RecordCommonSupport performs final processing, e.g. ouput links and process links are processed.

It is up to RecordCommonSupport to keep internal state so that it knows if
it is being called for initial or final processing.

During each stage DbProcess can call process multiple times:
* At the beginning of each stage process is called with state processStart. process returns one of:
** processDone - DbProcess proceeds to the next stage of record processing:
*** RecordCommonSupport initial - DbProcess calls RecordSupport
*** RecordSupport - Calls RecordCommonSupport
*** RecordCommonSupport final - DbProcess performs final processing and sets record idle.
** processActive
*** RecordCommonSupport must call the callback passed to process to continue processing
*** RecordSupport can call the callback passed to process when it is done. A call to DbProcess will also call process.
** processQuit
*** If RecordSupport returned this DbProcess calls RecordCommonSupport with state processCancel
*** Otherwise RecordSupport does its normal end of processing and sets the record idle.

For RecordCommonSupport the above rules allow asynchronous links.
The standard RecordCommonSupport does the following:
* initial processing means to handle the disable fields
** A get request is made for the disable link
*** If it is synchronous RecordCommonSupport returns processAbort if the record is disable or processDone otherwise.
*** If it is asynchronous, processContinue is returned and RecordCommonSupport arranges for DbProcessContinue to be called when the link completes.
* final processing means to handle the array of process links
** If all are synchronous RecordCommonSupport returns processDone
** If any are asynchronous, processContinue is returned and RecordCommonSupport arranges for DbProcessContinue to be called when the link completes.

For RecordSupport the above rules allow:
* process can be called repeatedly. This will continue as long as it returns processActive
* Everytime process returns processActive DbProcess posts monitors.
* The record can be periodically scanned.

== Links to Other Records ==

Links can be processed in parallel, sequentially, or a
combination of these.
RecordCommonSupport handles the links in RecordCommon and RecordSupport
handles record specific links. Record support is responsible for
implementing sequential or parallel link processing.
LinkSupport performs the actual I/O. The LinkSupport methods
provide options specifying if the linked record should be processed and
provide a callback to call when link processing completes. It is up to
RecordCommonSupport or RecordSupport to call DbProcessContinue
when all links complete.

----
<center>
= Mutual Exclusion =
</center>

V3 implemented lock sets, i.e. when a record was being processed it and all records linked via database links were locked.

Lock sets solved two Mutual Exclusion problems:
* V3 allowed dbProcess to be called recursively.
** process passive database links and forward links were implemented via recursive calls to DbProcess
** Lock sets prevented deadly embrace problems for circular links.
* No puts could be done to an record in a lock set while record processing is active.
** For synchronous records this guarantees that no fields are modified except by record processing itself.
** For asynchronous records this guarantee is not valid.

V4 does not call DbProcess recursively. Instead a process request is queued.
The request fails if either of the following is true:
* The record is active.
* The record is already queued.

Queuing requests to process rather than recursively calling DbProcess
does not necessarily cause unnecessary context switches.


Must design a way to queue process requests to the same thread
that issues the requests if the link is to a local record.
First thoughts is that this should be FIFO and queue emptied immediately
after the requesting record returns from process.


For example if all linked records are passive and the same priority then
all processing can occur without any context switches.
* A request is made to a thread to call DbProcess.
** The request is put on a queue associated with the thread.
* Sometime later the request is dequeued and DbProcess is called.
** For each link, with a request to process request, the request is put on the queue for the same thread
** After all requests are queued DbProcess returns
* The thread takes each request off the queue and calls DbProcess for the associated linked record
** When all linked records finish processing a request is queued to call DbProcess for the original record
* The request for the original record is removed from the queue and it's DbProcess is again called.
** The record completes.
Question What about periodically scanned records? Needs thought.

This leaves the question of what should be done about mutual exclusion.

For V4 there will be two locks associated with the IOC database:
1) a global lock, and 2) A per record instance lock.

The global lock, which is implemented by DbAccess, must be taken
whenever the structure of the database is modified. Examples are
1) adding new record types, 2) adding new record instances, and 3) modifying
database links. Global locks are not discussed further in this document.

Each record instance has an associated lock maintained by dbAccess.
When DbProcess is called it takes the lock.
Before it returns it unlocks.
Thus recordCommon and record support do not need to lock or unlock.

Other code that needs access to fields of a record instance must call
dbLock before accessing any fields and dbUnlock after all accesses are complete.

This leaves the problem of how to access fields from two different record
instances simultaneously. For example code that implements database
access needs such access. Code that needs such access must call dbLockLink before accessing the linked record and dbUnlockLink after access.

dbLockLink is implemented as follows:
* Each Record instances has a unique ordinal number
* Assume Record X has a link to record Y
* If the ordinal number of X is less than that of Y
** Just call dbLock for record Y
* If the ordinal numnber of X is greater than that of Y
** call dbUnlock for X
** call dbLock for Y
** call dbLock for X

----
<center>
= Posting Modifications =
</center>

The document "V4 Design: dbdIterfaces" provides a design that allows
database access to handle all posting on monitors without requiring
any help from the code that modifies database fields.
It can do this because fields can be modified only via an
interface implemented by database access.

Fields are modified in one of two ways:
* Changes made while record is being processed. For these posting is handled by DbProcess.
* Changes by other code. For these posting is handled by dbLock/dbUnlock.

Each field of a record instance has two associated "modified" bits.
One is for changes handled by DbProcess. The other is for changes made
by dbLock/dbUnlock.

DbProcess posts monitors when:
* When record support returns processActive.
* When it finishes record processing.

Other code can only change fields between calls to dbLock/dbUnlock
* When dbLock is called all its modify bits are false.
* Each field modification causes the associated modify bit to be set true.
* When dbUnlock is called it
** posts all fields that have changed
** sets the associated modify bits false

The following is the initial attempt to describe how monitors are implemented.

The following definitions are used:
* monitor - A client has asked to be notified when a field value changes.
* post - Create storage, copy the current value of the field into the storage, and pass the storage to the monitor subsystem.

Separate discussions is required for the following: 1) primitive fields,
2) string fields, 3) structured fields, and 4) array fields.

The following are just some thoughts.

* primitive fields - No problems.
* string fields - Memory is an issue.
** Should there be a way to postpone posting until the monitor is ready to retrieve the value?
** If so who decides?
* struct fields - Memory is again an issue.
** Structure with only primitive field or string should be posted immediately but what about array fields?
** Who decides?
** How?
* array fields - memory is an issue
** It should be possible to post small arrays of primitive type.
** Large arrays should not be posted until monitor system is ready to accept the data.
*** It should also be possible to just notify the client that the array changed but the client must issue a read request to retrieve the data.

In any case the way monitors are posted must take into consideration
the views defined in the database definition for each record.

----
<center>
= Alarm Processing =
</center>

The V4 semantics for status and severity have the following goals:
* alarmSeverity has the same values as for V3
* alarmStatus is a string
* a record starts processing with alarmSeverity = "NO_ALARM" and status empty.
* status will ONLY be posted if it has changed since the last time it was posted.
* alarmSeverity will ONLY be posted if it has changed since the last time it was posted

The semantics, which are implemented by recordCommon, are:

* When recordCommon is called with processStart
** A private variable newSeverity is set to NO_ALARM
** A private variable prevSeverity is set to alarmSeverity
* When recordCommon completes its part of record processing
** If newSeverity is NO_ALARM and prevSeverity has a different value
*** alarmSeverity is set to NO_ALARM
*** alarmStatus is set to empty

* When the recordCommon.setSeverity(sevr,status) is called
** If sevr is less than or equal to newSeverity nothing is done
** else
*** alarmSeverity is set to sevr
*** alarmStatus is set to status
*** newSeverity is set to sevr

NOTE: alarmStatus and alarmSeverity are written by the normal method.
This means that their values will be posted.
----
<center>
= Channel Access/ Database Access field types =
</center>

== Overview ==

This section discusses how IOC database fields are accessed by channel access
or via database links.

For the initial V4 implementation only the following types of data
will be accessable.

* primitive types
* string
* enum
* one dimensional array of primitive or string or struct
* struct with fields of following types:
** primitive
** string
** enum
** struct (use recursion for allowed types)
** one dimensional array of primitive or string or struct

The dbdInterfaces document defines database field types.
It also defines a subset called basic types, which consists
of primitive types, string, array, and structure.
For external access only basic types can be accessed.
This means that structures and arrays that do not consist of basic types
are not accessable outside the record. For example a DbfLink is
not accessable via channel access as a DbfLink.

Non basic fields will only be available via some combination of basic types.

For example a DbfLink field will appear as a string.
If a Database Definition is

struct(calcInpLink) {
field(link,link(in))
field(value,float64)
};

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

If a client attaches to
record.field(link)
The data will be appear in the form:
choiceName(pvname,...)
where <tt>choiceName</tt> is the name of the link support and the arguments
are the values of the dataStruct associated with the support.

Then if a client specifies the process variable:
record.field(inp[1].link)
Then it connects to the link field of the second calcInpLink of field inp.

== primitive types ==

This includes DbfBool, DbfOctet, DbfInt16, ... , DbfFloat64.
These do not present any problems. The scalar value is transfered.

== string ==

A string is just a UTF_8 encoded character string

== DbfMenu and DbfEnum ==

Handled as an enum

== DbfLink ==

Both of these have the following:

* <tt>choiceName</tt> A string that selects the link support.
* <tt>dataStructName</tt> Each support has an associated struct for configuration.

How should these be made available? Perhaps:

The field appears as a string with the following syntax:

<tt>choiceName(structAssignmentList)</tt>

where structAssignmentList has the same syntax as defined in "V4 DB Record Instance Syntax"

== timeStamp ==

This is just transfered like a struct with two fields:
* int64 secondsSinceEpoch
* int32 nanoSeconds

== struct ==

The database definition syntax allows a struct to be composed of fields
of any DbfType.
Database access, however, will only allow access to structs with fields
of the following types:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfArray of primitive type or string
* DbfStruct - As long as its fields are valid types

The individual fields can be accessed directly so this discussion
only involves access to the entire structure.

Access will only be available to clients that have knowledge of
fields within the structure. For channel access clients this means that
they provide a propertyCatalog that has some subset of the fields in the structure.

== array ==

Arrays of the following types are accessable:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfStruct - As long as its fields are valid types

Note that arrays of structs are not accessable in the early V4 releases.

Arrays still need lots more discussion!!!
The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.

For the initial V4 version, database access only allows access to arrays of the following types.
* primitive - DbfBool,...,DbfFloat64
* DbfString
* ???? What else

An individual element of an array of type DbfStruct can be accessed
directly if it satisfies the criteria for accessing a DbfStruct.

Question: Should database Access be implemented so that record/link support can transfer an array in segments. Examples:
* If the array is a circular buffer, it is presented in two segements
* If the array is stored in hardware, e.g. a transient recorder, the array can be read from the hardware and passed to the client in segments.

If an array is available only in segments then can we
prevent two clients from trying to access the same array simultaneously?

Perhaps this is a problem that must be solved by an application:
* runControl records are one solution
* Other solutions can be envisioned

== MDArray ==

Not implemented if the early V4 releases.

== Associated Data ==

The typical example is a client that asks for timeStamp, severity, status,
and data.
These are handled automatically as described in "Posting Modifications"

V4 DB RecordCommon

2005-09-27T20:05:18Z

MartyKraimer:

EPICS V4: Standard Support September 27 2005
----

= Overview =

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd defines widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

----
<center>
= dbCommon =
</center>

== Channel/Database Access Support ==

=== Data Structures ===
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,boolean) // process this record when monitor occurs
field(inheritSeverity,boolean)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(OutputLinkData) {
field(pvname,string) { link}
field(process,boolean)
field(wait,boolean)
field(block,boolean)
field(inheritSeverity,boolean)
}
struct(ProcessLinkData) {
field(pvname,string) { link}
field(wait,boolean)
field(block,boolean)
}

=== link support definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(in,"monitorLinkOctet","monitorLinkOctet",MonitorLinkData);
link(in,"monitorLinkBoolean","monitorLinkBoolean",MonitorLinkData);
link(in,"monitorLinkInt16","monitorLinkInt16",MonitorLinkData);
link(in,"monitorLinkInt32","monitorLinkInt32",MonitorLinkData);
link(in,"monitorLinkInt64","monitorLinkInt64",MonitorLinkData);
link(in,"monitorLinkFloat32","monitorLinkFloat32",MonitorLinkData);
link(in,"monitorLinkFloat64","monitorLinkFloat64",MonitorLinkData);
link(in,"monitorLinkString","monitorLinkString",MonitorLinkData);
link(in,"inputLinkOctet","inputLinkOctet",InputLinkData);
link(in,"inputLinkBoolean","inputLinkBoolean",InputLinkData);
link(in,"inputLinkInt16","inputLinkInt16",InputLinkData);
link(in,"inputLinkInt32","inputLinkInt32",InputLinkData);
link(in,"inputLinkInt64","inputLinkInt64",InputLinkData);
link(in,"inputLinkFloat32","inputLinkFloat32",InputLinkData);
link(in,"inputLinkFloat64","inputLinkFloat64",InputLinkData);
link(in,"inputLinkString","inputLinkString",InputLinkData);
link(out,"outputLinkOctet","outputLinkOctet",OutputLinkData);
link(out,"outputLinkBoolean","outputLinkBoolean",OutputLinkData);
link(out,"outputLinkInt16","outputLinkInt16",OutputLinkData);
link(out,"outputLinkInt32","outputLinkInt32",OutputLinkData);
link(out,"outputLinkInt64","outputLinkInt64",OutputLinkData);
link(out,"outputLinkFloat32","outputLinkFloat32",OutputLinkData);
link(out,"outputLinkFloat64","outputLinkFloat64",OutputLinkData);
link(out,"outputLinkString","outputLinkString",OutputLinkData);

link(in,"monitorLinkArrayOctet","monitorLinkArrayOctet",MonitorLinkData);
link(in,"monitorLinkArrayBoolean","monitorLinkArrayBoolean",MonitorLinkData);
link(in,"monitorLinkArrayInt16","monitorLinkArrayInt16",MonitorLinkData);
link(in,"monitorLinkArrayInt32","monitorLinkArrayInt32",MonitorLinkData);
link(in,"monitorLinkArrayInt64","monitorLinkArrayInt64",MonitorLinkData);
link(in,"monitorLinkArrayFloat32","monitorLinkArrayFloat32",MonitorLinkData);
link(in,"monitorLinkArrayFloat64","monitorLinkArrayFloat64",MonitorLinkData);
link(in,"monitorLinkArrayString","monitorLinkArrayString",MonitorLinkData);
link(in,"inputLinkArrayOctet","inputLinkArrayOctet",InputLinkData);
link(in,"inputLinkArrayBoolean","inputLinkArrayBoolean",InputLinkData);
link(in,"inputLinkArrayInt16","inputLinkArrayInt16",InputLinkData);
link(in,"inputLinkArrayInt32","inputLinkArrayInt32",InputLinkData);
link(in,"inputLinkArrayInt64","inputLinkArrayInt64",InputLinkData);
link(in,"inputLinkArrayFloat32","inputLinkArrayFloat32",InputLinkData);
link(in,"inputLinkArrayFloat64","inputLinkArrayFloat64",InputLinkData);
link(in,"inputLinkArrayString","inputLinkArrayString",InputLinkData);
link(out,"outputLinkArrayOctet","outputLinkArrayOctetData);
link(out,"outputLinkArrayBoolean","outputLinkArrayBooleanData);
link(out,"outputLinkArrayInt16","outputLinkArrayInt16",OutputLinkData);
link(out,"outputLinkArrayInt32","outputLinkArrayInt32",OutputLinkData);
link(out,"outputLinkArrayInt64","outputLinkArrayInt64",OutputLinkData);
link(out,"outputLinkArrayFloat32","outputLinkArrayFloat32",OutputLinkData);
link(out,"outputLinkArrayFloat64","outputLinkArrayFloat64",OutputLinkData);
link(out,"outputLinkArrayString","outputLinkArrayString",OutputLinkData);

link(process,"processLink",ProcessLink,ProcessLinkData);

== asynDriver link support ==
=== Data Definitions ===

struct(AsynDevice) }
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}
=== link definitions ===

link(in,"asynInt32","inputLinkInt32",AsynDevice)
link(in,"asynInt32Average","inputLinkInt32",AsynDevice)
link(in,"asynInt32Monitor","monitorLinkInt32",AsynDevice)
link(in,"asynFloat64","inputLinkFloat64",AsynDevice)
link(in,"asynFloat64Average","inputLinkFloat64",AsynDevice)
link(in,"asynFloat64Monitor","monitorLinkFloat64",AsynDevice)
link(out,"asynInt32","outputLinkInt32",AsynDevice)
link(out,"asynFloat64","outputLinkFloat64",AsynDevice)
link(in,"asynDigital","asynDigital",AsynDevice)
link(in,"asynDigitalMonitor","asynDigitalMonitor",AsynDevice)
link(out,"asynDigital","asynDigital",AsynDevice)
link(in,"asynInt32Array","inputLinkArrayInt32",AsynDevice)
link(out,"asynInt32Array","outputLinkArrayInt32",AsynDevice)
link(in,"asynFloat64Array","inputLinkArrayFloat64",AsynDevice)
link(out,"asynFloat64Array","outputLinkArrayFloat64",AsynDevice)
link(in,"asynOctetArray","asynOctetArray",AsynDevice)
link(out,"asynOctetArray","asynOctetArray",AsynDevice)
== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

# usefull struct definitions

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= RecordCommon =
</center>

== Menu Definitions ==

# menu definitions for RecordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}
== struct definitions for RecordSupport ==
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

== RecordCommon Record Definition ==

record(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,boolean)
field(disablePutField,boolean)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmAckTransient,boolean) {
readonly(yes)
default("YES")
}
field(udf,boolean) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(link[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be privaye to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

V4 DBD Statement Syntax

2005-09-27T20:02:43Z

MartyKraimer:

DBD Statement Syntax Sept 27 2005
= Overview =
This document presents the syntax for V4 database definition files.
<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

<blockquote>

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

link(linkDirection,array(string[])= {name,...})

where
* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
* <tt>array(string[])</tt> : Each string is the name of Link Interface implemented by link support and used by record support.

Examples:
field(disableLink,
link(in,array(string[4]) = {
"monitorLinkInt32",
"inputLinkInt32",
"monitorLinkFloat64",
"inputLinkFloat64"
} ))
)
field(process, link(process,array(string[1])= {processLink}))
field(inp,
link(in, array(string[3]) = {
"monitorLinkInt32",
"inputLinkInt32",
"digitalIO"
}))
)
</blockquote>

Andrew: Do we want the above syntax? Another possibility is just:
link(linkDirection,interface(string,...))


== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= link =
</center>

A <tt>link</tt> statement describes an implementation of support for a link
field. the support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

link(dir, choiceName, interfaceName, dataStructName)

where

; <tt>dir</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.
: '''Q: What are the rules?'''
:: ''It certainly doesn't seem to make sense to have a none or inout link for instance.''

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> that the interface understands. This interface can contain data and configuration information. The <tt>struct</tt> must be defined before record instances can be created that assign values to it.
:: ''Need to rewrite this paragraph to clarify.''

When a record instance is created the choiceName selects the support
to attach to a record link. The interfaceName must be one of the
interface names the record has listed as a valid type and dir must be compatible
with the dir the record type specified.

Examples:
link(in,"monitorLinkInt16","monitorLinkInt16",MonitorLinkData);
link(in,"inputLinkInt16","inputLinkInt16",InputLinkData);
link(out,"outputLinkFloat64","outputLinkFloat64",OutputLinkData);
link(process,"processLink",ProcessLink,ProcessLinkData);

V4 DBD Examples

2005-09-27T15:23:02Z

MartyKraimer:

Example Record Types Sept 27 2005
= Overview =
This document present proposed V4 replacements for a few of the
V3 record types.

<center>
= aoRecord =
</center>

aoRecord.dbd might be defined as follows:

include "dbCommon.dbd"
record(AoRecord) extends RecordCommon {
field(value, float64) {
asl(0)
}
field(outValue, float64) {
readonly(yes)
}
field(out,
link(out,array(string[3]) = {
"outputLinkInt64",
"outputLinkFloat64",
"asynInt32",
"asynFloat64"
} ))
)
field(outputRateOfChange, float64)
field(desiredOutputLink,
link(in,array(string[2]) = {
"monitorLinkFloat64",
"inputLinkFloat64"
} ))
)
field(closedLoop, bool)
field(outputIncremental, bool)
field(convert, menu(menuConvert)) {
special(yes)
}
field(linearConvert, struct(LinearConvert)) {
special(yes)
}
field(units, string)
field(displayLimit, struct(DisplayLimit))
field(controlLimit, struct(ControlLimit))
field(alarmLimit, struct(AlarmLimit))
field(alarmDeadband, float64)
field(rawValue, int64) {
design(no)
}
field(prevRawValue, int64) {
design(no)
readonly(yes)
}
field(readBackValue, int64) {
design(no)
readonly(yes)
}
field(init, bool) {
design(no)
readonly(yes)
}
field(simOutputLink,
link(out,array(string[2]) = {
"outputLinkInt64",
"outputLinkFloat64",
} ))
)

field(simModeLink,
link(in,array(string[2]) = {
"monitorLinkString",
"inputLinkString"
} ))
)
field(simMode, bool)
field(simSevr, menu(menuAlarmSevr))
field(invalidAction, menu(menuIvoa))
field(invalidValue, float64)
field(outValueModified, bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(controlLimit, controlLimit)
property(alarmLimit, alarmLimit)
}
}
view(output) {
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(raw) {
property(value, rawValue) {
property(timeStamp, time)
}
}
view(readback) {
property(value, readBackValue) {
property(timeStamp, time)
}
}
}

<center>
= calcRecord =
</center>

calcRecord.dbd defines the following:

include "dbCommon.dbd"
struct(CalcInpLink) {
field(link,link(in))
link(in,array(string[2]) = {
"monitorLinkFloat64",
"inputLinkFloat64"
} ))
)
field(value,float64)
}

record(CalcRecord) extends RecordCommon {
field(result,float64) {
asl(0)
}
field(calc,string) {
special(yes)
}
field(input,array(struct(CalcInpLink)[]))
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(alarmLimit,struct(AlarmLimit))
field(alarmDeadband,float64)
field(lastValueAlarmed,float64) {
design(no)
readonly(yes)
}
field(rpcl,private("char *"))
view(result) {
property(value, result) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
property(alarmLimit, alarmLimit)
}
}
view(expression) {
property(value, calc)
}
}

<center>
= mbbiRecord =
</center>

mbbiRecord.dbd could be:

include "dbCommon.dbd"
struct(MbbiState) {
field(name, string)
field(value, array(octet[]))
field(severity, menu(menuAlarmSevr))
}
record(MbbiRecord) extends RecordCommon {
field(state, array(struct(MbbiState)[])) {
special(yes)
}
#NOTE: stateName needed because enum must refer to array of string
field(stateName,array(string[])) {
design(no) readonly(yes)
}
field(value, enum(stateName)) {
asl(0)
}
field(unknownStateSeverity, menu(menuAlarmSevr))
field(changeStateSeverity, menu(menuAlarmSevr))
field(inp,
link(in,array(string[3]) = {
"inputLinkOctet",
"asynDigital",
} ))
)
field(rawValue, array(octet[])) {
design(no)
readonly(yes)
}
field(hardwareShift, int16) {
readonly(yes)
}
field(hardwareMask, array(octet[]) {
readonly(yes)
}
view(choice) {
property(value, value) {
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(raw) {
property(value, raw) {
property(timeStamp, time)
}
}
}

<center>
= waveformRecord =
</center>

waveformRecord.dbd defines the following:

include "dbCommon.dbd"
record(WaveformRecord) extends RecordCommon {
field(value, array([])) {
asl(0)
special(yes)
}
field(reArm,bool)
field(io,
link(inout,array(string[4]) = {
"monitorLinkArrayOctet",
"monitorLinkArrayBoolean",
"monitorLinkArrayInt16",
"monitorLinkArrayInt32",
"monitorLinkArrayInt64",
"monitorLinkArrayFloat32",
"monitorLinkArrayFloat64",
"monitorLinkArrayString",
"inputLinkArrayOctet",
"inputLinkArrayBoolean",
"inputLinkArrayInt16",
... all input and link types
} ))
)
field(units,string)
field(displayLimit,struct(DisplayLimit))
field(busy,bool) {
design(no)
readonly(yes)
}
view(value) {
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
}

V4 DB RecordCommon

2005-09-27T15:21:51Z

MartyKraimer:

EPICS V4: Standard Support September 27 2005
----

= Overview =

For V4 dbCommon.dbd and RecordCommon.dbd replace the V3 dbCommon.dbd.
dbCommon.dbd defines widely used definitions and RecordCommon.dbd defines
the fields that are common to all record types.

This document requires that the reader be familiar with:
# V3 iocCore
# V4 DBD Statement Syntax
# V4 DB Record Instance Syntax

----
<center>
= dbCommon =
</center>

== Channel/Database Access Support ==

=== Data Structures ===
struct(MonitorLinkData) {
field(pvname,string) { link}
field(process,bool) // process this record when monitor occurs
field(inheritSeverity,bool)
}
struct(InputLinkData) {
field(pvname,string) { link}
field(process,bool)
field(wait,bool)
field(block,bool)
field(inheritSeverity,bool)
}
struct(OutputLinkData) {
field(pvname,string) { link}
field(process,bool)
field(wait,bool)
field(block,bool)
field(inheritSeverity,bool)
}
struct(ProcessLinkData) {
field(pvname,string) { link}
field(wait,bool)
field(block,bool)
}

=== link support definitions ===

Link support is provided for
* input
** monitor support
** input support
* output
* process

For input and output The following data types are supported:
* primitive types
* string
* arrays of primitive types and strings

link(in,"monitorLinkOctet","monitorLinkOctet",MonitorLinkData);
link(in,"monitorLinkBoolean","monitorLinkBoolean",MonitorLinkData);
link(in,"monitorLinkInt16","monitorLinkInt16",MonitorLinkData);
link(in,"monitorLinkInt32","monitorLinkInt32",MonitorLinkData);
link(in,"monitorLinkInt64","monitorLinkInt64",MonitorLinkData);
link(in,"monitorLinkFloat32","monitorLinkFloat32",MonitorLinkData);
link(in,"monitorLinkFloat64","monitorLinkFloat64",MonitorLinkData);
link(in,"monitorLinkString","monitorLinkString",MonitorLinkData);
link(in,"inputLinkOctet","inputLinkOctet",InputLinkData);
link(in,"inputLinkBoolean","inputLinkBoolean",InputLinkData);
link(in,"inputLinkInt16","inputLinkInt16",InputLinkData);
link(in,"inputLinkInt32","inputLinkInt32",InputLinkData);
link(in,"inputLinkInt64","inputLinkInt64",InputLinkData);
link(in,"inputLinkFloat32","inputLinkFloat32",InputLinkData);
link(in,"inputLinkFloat64","inputLinkFloat64",InputLinkData);
link(in,"inputLinkString","inputLinkString",InputLinkData);
link(out,"outputLinkOctet","outputLinkOctet",OutputLinkData);
link(out,"outputLinkBoolean","outputLinkBoolean",OutputLinkData);
link(out,"outputLinkInt16","outputLinkInt16",OutputLinkData);
link(out,"outputLinkInt32","outputLinkInt32",OutputLinkData);
link(out,"outputLinkInt64","outputLinkInt64",OutputLinkData);
link(out,"outputLinkFloat32","outputLinkFloat32",OutputLinkData);
link(out,"outputLinkFloat64","outputLinkFloat64",OutputLinkData);
link(out,"outputLinkString","outputLinkString",OutputLinkData);

link(in,"monitorLinkArrayOctet","monitorLinkArrayOctet",MonitorLinkData);
link(in,"monitorLinkArrayBoolean","monitorLinkArrayBoolean",MonitorLinkData);
link(in,"monitorLinkArrayInt16","monitorLinkArrayInt16",MonitorLinkData);
link(in,"monitorLinkArrayInt32","monitorLinkArrayInt32",MonitorLinkData);
link(in,"monitorLinkArrayInt64","monitorLinkArrayInt64",MonitorLinkData);
link(in,"monitorLinkArrayFloat32","monitorLinkArrayFloat32",MonitorLinkData);
link(in,"monitorLinkArrayFloat64","monitorLinkArrayFloat64",MonitorLinkData);
link(in,"monitorLinkArrayString","monitorLinkArrayString",MonitorLinkData);
link(in,"inputLinkArrayOctet","inputLinkArrayOctet",InputLinkData);
link(in,"inputLinkArrayBoolean","inputLinkArrayBoolean",InputLinkData);
link(in,"inputLinkArrayInt16","inputLinkArrayInt16",InputLinkData);
link(in,"inputLinkArrayInt32","inputLinkArrayInt32",InputLinkData);
link(in,"inputLinkArrayInt64","inputLinkArrayInt64",InputLinkData);
link(in,"inputLinkArrayFloat32","inputLinkArrayFloat32",InputLinkData);
link(in,"inputLinkArrayFloat64","inputLinkArrayFloat64",InputLinkData);
link(in,"inputLinkArrayString","inputLinkArrayString",InputLinkData);
link(out,"outputLinkArrayOctet","outputLinkArrayOctetData);
link(out,"outputLinkArrayBoolean","outputLinkArrayBooleanData);
link(out,"outputLinkArrayInt16","outputLinkArrayInt16",OutputLinkData);
link(out,"outputLinkArrayInt32","outputLinkArrayInt32",OutputLinkData);
link(out,"outputLinkArrayInt64","outputLinkArrayInt64",OutputLinkData);
link(out,"outputLinkArrayFloat32","outputLinkArrayFloat32",OutputLinkData);
link(out,"outputLinkArrayFloat64","outputLinkArrayFloat64",OutputLinkData);
link(out,"outputLinkArrayString","outputLinkArrayString",OutputLinkData);

link(process,"processLink",ProcessLink,ProcessLinkData);

== asynDriver link support ==
=== Data Definitions ===

struct(AsynDevice) }
field(portName,string)
field(addr,int32)
field(timeout,float64)
field(drvPvt,string)
}
=== link definitions ===

link(in,"asynInt32","asynInt32",AsynDevice)
link(in,"asynInt32Average","asynInt32Average",AsynDevice)
link(in,"asynInt32Monitor","asynInt32Monitor",AsynDevice)
link(in,"asynFloat64","asynFloat64",AsynDevice)
link(in,"asynFloat64Average","asynFloat64Average",AsynDevice)
link(in,"asynFloat64Monitor","asynFloat64Monitor",AsynDevice)
link(out,"asynInt32","asynInt32",AsynDevice)
link(out,"asynFloat64","asynFloat64",AsynDevice)
link(in,"asynDigital","asynDigital",AsynDevice)
link(in,"asynDigitalMonitor","asynDigitalMonitor",AsynDevice)
link(out,"asynDigital","asynDigital",AsynDevice)
link(in,"asynInt32Array","asynInt32Array",AsynDevice)
link(out,"asynInt32Array","asynInt32Array",AsynDevice)
link(in,"asynFloat64Array","asynFloat64Array",AsynDevice)
link(out,"asynFloat64Array","asynFloat64Array",AsynDevice)
link(in,"asynOctetArray","asynOctetArray",AsynDevice)
link(out,"asynOctetArray","asynOctetArray",AsynDevice)
== Other common definitions ==

menu(menuConvert) {
choice(menuConvertRaw, "Raw")
choice(menuConvertLinear, "Linear")
choice(menuConvertTable, "Table")
}

# usefull struct definitions

struct(LinearConvert) {
field(full,float64)
field(egul,float64)
field(slope,float64)
field(intercept,float64)
}

struct(DisplayLimit) {
field(low,float64)
field(high,float64)
}
struct(ControlLimit) {
field(low,float64)
field(high,float64)
}
struct(AlarmLimit) {
field(low,float64)
field(lowSevr,menu(menuAlarmSevr))
field(lowWarning,float64)
field(lowWarningSevr,menu(menuAlarmSevr))
field(highWarning,float64)
field(highWarningSevr,menu(menuAlarmSevr))
field(high,float64)
field(highSevr,menu(menuAlarmSevr))
}

----
<center>
= RecordCommon =
</center>

== Menu Definitions ==

# menu definitions for RecordCommon fields
menu(menuPriority) {
choice(menuPriorityLow, "Low")
choice(menuPriorityMedium, "Medium")
choice(menuPriorityHigh, "High")
}

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

menu(menuAlarmSevr) {
choice(menuAlarmSevrNone, "None")
choice(menuAlarmSevrMinor, "Minor")
choice(menuAlarmSevrMajor, "Major")
choice(menuAlarmSevrInvalid, "Invalid")
}
== struct definitions for RecordSupport ==
struct(TimeStamp) {
field(secondsPastEpoch,int64)
field(nanoSeconds,int32)
}

struct Scan {
field(scan,menu(menuScan)) {
special(yes)
}
field(phase,int16)
field(priority,menu(menuPriority)) {
special(yes)
}
}
Event NEEDS NEW DEFINITIONS
struct Event {
field(eventNumber,int16) {
special(yes)
}
field(timeStampEvent,int16)
field(timeStampLink,link(in))
}

struct Disable {
field(disableValue,int16) {
default("1")
}
field(disableInput,int16)
field(disableLink,link(in))
field(disableAlarmSeverity,menu(menuAlarmSevr))
}

== RecordCommon Record Definition ==

record(RecordCommon) {
field(description,string)
field(scan,struct(Scan))
field(event,struct(Event))
field(accessSecurityGroup,string)
field(pini,bool)
field(disablePutField,bool)
field(alarmAckSeverity,menu(menuAlarmSevr)) {
design(no)
readonly(yes)
}
field(alarmAckTransient,bool) {
readonly(yes)
default("YES")
}
field(udf,bool) {
dynamic(yes)
default("1")
}
field(time,struct(TimeStamp)) {
design(no)
dynamic(yes)
readonly(yes)
}
field(disable,struct(Disable)) {
special(yes)
}
field(alarmStatus,string) {
default("UDF")
}
field(alarmSeverity,menu(menuAlarmSevr)) {
readonly(yes)
default("Invalid")
}
field(processLink,array(link[])) {
special(yes)
}
}

Although it has many fewer fields,
RecordCommon.dbd is a complete replacement for the V3 dbCommon.
The following V3 fields are no longer needed:
* private fields - Private fields will truly be privaye to the implementation
* previous value fields - All puts to database fields will be posted. The layer above will decide if clients should be notified of changes.

V4 DB Record Instance Syntax

2005-09-27T15:18:51Z

MartyKraimer:

Record Instance Syntax Sept 27 2005
= Overview =

The syntax used for record instances has to change in EPICS V4,
since we now have to support structured data.
A complete redesign of the syntax has been done to help improve parsing, and to provide commonality between the syntax of a DB file and the string representation of structured data values passed through Channel Access.

= Document Conventions =

This syntax is presented below in the form of a grammar. The conventions I'm using are as follows:

;''symbolBeingDefined:''
: ''otherSymbol''
: ''alternateSymbolFollowedBy'' <tt>literal</tt>
: ''one of:'' <tt>list of posible literal values</tt>

= Common Symbols =

The symbols described in this section are used in the grammar, but may be implemented as lexical tokens.

;''identifier:''
: A legal C99 identifier. Note that C99 permits implementations to allow extended characters to be used in identifiers, but does not require it, so the use of extended characters may reduce portability and is not recommended.

== Integer Constants ==

;''integerConstant:''
: ''positiveInteger''

;''positiveInteger:''
: ''octalConstant''
: ''hexConstant''
: ''decimalConstant''

;''octalConstant:''
: <tt>0</tt>
: ''octalConstant'' ''octalDigit''

;''octalDigit:''
: ''one of:'' <tt>0-7</tt>

;''hexConstant:''
: <tt>0x</tt> ''hexDigit''
: <tt>0X</tt> ''hexDigit''
: ''hexConstant'' ''hexDigit''

;''hexDigit:''
: ''one of:'' <tt>0-9 a-f A-F</tt>

;''decimalConstant:''
: ''one of:'' <tt>1-9</tt>
: ''decimalConstant'' ''decimalDigit''

;''decimalDigit:''
: ''one of:'' <tt>0-9</tt>

This was meant to be a description of the C99 standard integer representation, but I made it up myself so it may be flawed. Note that we will not accept the C99 numeric suffixes u/U and l/L since (unlike a C compiler) we know the type of the number we're expecting.

== Floating Point Constants ==

;''realConstant:''
:'' positiveReal''
: <tt>-</tt> ''positiveReal''

;''positiveReal:''
: ''digitSequence''
: ''digitSequence'' <tt>.</tt>
: ''digitSequence'' <tt>.</tt> ''exponentPart''
: ''digitSequence'' <tt>.</tt> ''digitSequence''
: ''digitSequence'' <tt>.</tt> ''digitSequence'' ''exponentPart''
: <tt>.</tt> ''digitSequence''
: <tt>.</tt> ''digitSequence'' ''exponentPart''
: ''digitSequence'' ''exponentPart''

;''digitSequence:''
: ''decimalDigit''
: ''digitSequence'' ''decimalDigit''

;''exponentPart:''
: <tt>e</tt> ''signedExponent''
: <tt>E</tt> ''signedExponent''

;''signedExponent:''
: <tt>-</tt> ''digitSequence''
: <tt>+</tt> ''digitSequence''
: ''digitSequence''

In ANSI C source code, a sequence of decimal digits with neither a decimal point nor an exponent is an integer constant, not a floating-point constant. We will permit this however, since we always know the field type in advance.

== Boolean Constants ==

We can afford to be generous in what we accept as a boolean value:

;''booleanConstant:''
: ''booleanTrue''
: <tt>"</tt> ''booleanTrue'' <tt>"</tt>
: ''booleanFalse''
: <tt>"</tt> ''booleanFalse'' <tt>"</tt>

;''booleanTrue:''
: ''one of:'' <tt>1 T TRUE t true True Y YES Yes y yes</tt>

;''booleanFalse:''
: ''one of:'' <tt>0 F FALSE f false False N NO No n no</tt>

'''I'm proposing all these possibilities for true/false as they are all obvious in meaning, and will allow a CA Put of any of these strings to a boolean field. We might even want to allow registration of boolean strings in other languages...'''

== String Constants ==

;''stringConstant:''
: <tt>"</tt> ''escapedCharacterList'' <tt>"</tt>

;''escapedCharacterList:''
: A series of characters, using the C99 ''escapeSequence'' syntax defined below:

;''escapeSequence:''
: ''simpleEscapeSequence''
: ''octalEscapeSequence''
: ''hexEscapeSequence''
: ''universalCharacterName''

;''simpleEscapeSequence:''
: ''one of:'' <tt>\' \" \? \\ \a \b \f \n \r \t \v</tt>

;''octalEscapeSequence:''
: <tt>\</tt> ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit''
: <tt>\</tt> ''octalDigit'' ''octalDigit'' ''octalDigit''

;''hexEscapeSequence:''
: <tt>\x</tt> ''hexDigit''
: ''hexEscapeSequence'' ''hexDigit''

Note: C99 does not limit the number of hexadecimal digits that can appear in a ''hexEscapeSequence'', but it does state that the behaviour is undefined if the resulting character value exceeds that of the largest character.

;''universalCharacterName:''
: <tt>\u</tt> ''hexQuad''
: <tt>\U</tt> ''hexQuad'' ''hexQuad''

;''hexQuad:''
: ''hexDigit'' ''hexDigit'' ''hexDigit'' ''hexDigit''

= Database File =

This section will eventually define what can appear in a .db file. That currently means:

* record instances
* comments
* macro instances, including where they will be allowed
* template files and substitution macro definitions
* port definitions for template instances
* data for tools such as VDCT, that will not be discarded by .db processing tools.

The templates, macros and ports design should be very similar to the ideas produced for R3.14 VDCT templates.

= Record Definitions =

;''recordDefinition:''
: ''recordType'' ''recordName'' <tt>= {</tt> ''recordBody'' <tt>}</tt>

;''recordType:''
: ''identifier''

;''recordName:''
: ''recordNameChar''
: ''recordName'' ''recordNameChar''

;''recordNameChar:''
: ''one of:'' <tt>0-9 A-Z a-z _ - : ; < > [ ]</tt>
: Any Unicode/UTF-8 character outside of the Basic Latin set

This extends the character set available to a V3 record name, adding all possible multi-byte characters. However, EPICS sites are strongly advised to confirm that such record names can be processed using all of their database and CA client tools before actually making use of this particular extension.

;''recordBody:''
: ''recordBodyItem''
: ''recordBody'' ''recordBodyItem''

Record instance definitions in EPICS V4 look very similar to a C99 structure definition with initialization. For example:

ai foo:bar:temperature = {
...
}

Inside the body of the record definition, there are three possible kinds of statements, similar to a C assignment statement. Note these statements must be terminated with a semi-colon (which is different from inside a struct). The reason for this difference is to prevent database instance files from becoming dependent on the order of fields in a record; if we permit record instances to be created from a single comma-separated list of field values without the field names, it could lead to significant confusion if the field order ever changes.

;''recordBodyItem:''
: ''infoAssignment''
: ''fieldAssignment''
: ''extraFieldAssigment''

== Information Fields ==

;''infoAssignment:''
: <tt>info</tt> ''infoName'' <tt>=</tt> ''stringConstant'' <tt>;</tt>

;''infoName:''
: ''identifier''
: ''stringConstant''

Info items provide additional configuration data about this record that can be accessed by other software running on the IOC.

info savePeriod = "30.0";
info restorePhase = "1";
info "my favourite things" = "raindrops on roses";

== Field Assignment ==

;''fieldAssignment:''
: ''fieldName'' <tt>=</tt> ''initializer'' <tt>;</tt>

;''fieldName:''
: ''identifier''

;''initializer:''
: ''constant''
: ''structInitializer''
: ''arrayInitializer''
: ''linkInitializer''

;''initializerList:''
: ''initializer''
: ''initializerList'' <tt>,</tt> ''initializer''

The ''initializer'' in a field assignment is also the exact same syntax that will be used when converting a string value from a CA client for example into a field value that is being put into a field.

=== Basic and Enumerated Initializers ===

;''constant:''
: ''booleanConstant''
: ''integerConstant''
: ''realConstant''
: ''stringConstant''

The syntax for the field initializer depends on the data type represented by fieldName. Basic types (numeric or string) should need no comment other than to note that values for numeric fields must not be given inside quotes (unlike EPICS V3). Menu field values may be given as either a string or an integer. For enum fields, if the related field that contains the strings is defined first, the enum field may be specified using a string; otherwise it can only be set using an integer value.

Examples:
ai foo:bar:temperature = {
inputSmoothing = 0.98;
invalidValue = 1000;
units = "Celcius";
scan = "Interrupt";
...
}

=== Structure Initializers ===

;''structInitializer:''
: <tt>{</tt> ''structAssignmentList'' <tt>}</tt>

;''structAssignmentList:''
: ''initializerList''
: ''fieldName'' <tt>=</tt> ''initializerList''
: ''structAssignmentList'' <tt>;</tt> ''fieldName'' <tt>=</tt> ''initializerList''

Initializers for a structure field look similar to a nested record body, but the rules are slightly different:
* You can give a series of values for adjacent items using a simple comma-separated list (for a record body, you ''must'' name each field)
* Semi-colons are required between a value and a following named item.

For example:

ai foo:temperature:sensor = {
linearConvert = {
mode = "Linear";
low = -12.5, 133.5
};
displayLimit = { 0, 100 };
...
}

=== Link Initializer ===

;''linkInitializer:''
: ''choiceName'' <tt>(</tt> ''structAssignmentList'' <tt>)</tt>

;''choiceName:''
: ''identifier''

These select a particular link support for the field, and set its address according to the structure type defined for that link type.

calcout foo:temperature:controller = {
output = outputLinkFloat64(
pvname = "fum:baz:heater";
process = true;
wait = true;
block = true;
)
input = [2] {
{link = {
monitorLinkFloat64{
pvname = "foo:temperature:setpoint";
process = false
}
}
{link = {
inputLinkFloat64{
pvname = "foo:temperature:sensor";
process = true;
wait = true;
block = true;
inheritSeverity = true
}
}
};
expression = "(setpoint - current) > 0";
...
}

mbbi foo:bar:door = {
input = acro9440(0, 5);
...
}

=== Array Initializers ===

;''arrayInitializer:''
: <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>{</tt> ''arrayAssignmentList'' <tt>}</tt>
: <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>
: ''arrayType'' <tt>[</tt> ''arrayCapacity'' <tt>] {</tt> ''arrayAssignmentList'' <tt>}</tt>

;''arrayAssignmentList:''
: ''initializerList''
: <tt>[</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''
: ''arrayAssignmentList'' <tt>; [</tt> ''integerConstant'' <tt>] =</tt> ''initializerList''

;''arrayType:''
: ''one of:'' <tt>bool</tt> <tt>int16</tt> <tt>uint16</tt> <tt>int32</tt> <tt>uint32</tt>
: ''one of:'' <tt>float32</tt> <tt>float64</tt> <tt>octet</tt> <tt>string</tt>

;''arrayCapacity:''
: ''integerConstant''
: ''arrayCapacity'' <tt>,</tt> ''integerConstant''

If the definition of the array field being set did not do so, an array field initialization must include the size of the array and/or the type of the data stored in it. Inside the braces data values are given in a comma-separated list; the index can also be set to initialize individual values, and any mixture of the two can be used as desired:

mbbi foo:bar:door = {
stateNames = [4] {"Broken", "Closed", "Open", "Moving"};
stateSeverity = [4] {"Major"; [3] = "Minor"};
...
}

For multi-dimensional arrays, data values can only appear inside the inner-most sets of braces, although index settings are permitted outside of these. These two definitions give the same result:

matrix identity1 = {
value = float32 [3,3] { {1, 0, 0}, {0, 1, 0}, {1, 0, 0}};
}
matrix identity2 = {
value = float32 [3,3] { {1}, {[1] = 1}, {[2] = 1}};
}

V4 DBD Statement Syntax

2005-09-27T15:16:38Z

MartyKraimer:

DBD Statement Syntax Sept 27 2005
= Overview =
This document presents the syntax for V4 database definition files.
<center>
= General Statements =
</center>

== include ==

include "filename"

where

; <tt>filename</tt>
: must be a valid filename

The file system search path that will be used to look for the file is determined by the build system, and cannot be modified by the DBD file itself.

Include statements can be used at the top level, or inside the braces of a <tt>menu</tt>, <tt>struct</tt> or <tt>record</tt> definition.

== # comment ==

# anything

Anything on a line after a <tt>#</tt> character is a comment, and will be ignored. Comments may appear on a line by themselves, or at the end of another statement. They may not appear inside the parentheses belonging to another statement, but they are permitted inside braces. Inside a single- or double- quoted string the <tt>#</tt> character has no special meaning.

== menu ==

A menu is an enumerated type where the choice strings are defined once for each IOC. Menus are defined like this:

menu(menuName) {
choice(choiceName, "choiceValue")
...
}

where

; <tt>menuName</tt>
: Must be a valid, unique C identifier.
; <tt>choiceName</tt>
: Must be a valid, unique C identifier. By convention, every choiceName should start with the menuName it belongs to. These names are only available to C/C++ source code using the header file generated from the menu definition; they are not stored in the IOC itself.
; <tt>choiceValue</tt>
: Can be any UTF-8 compatible string, which should be unique within the context of this menu.

In general menus should only be definable once, in the DBD file (first definition seen wins in the event of duplicates, give a warning for duplicates and error if subsequent definition is different). However we may want to include a syntax that allows specific menu definitions to be extended at database load time.

Example:

menu(menuScan) {
choice(menuScanPassive, "Passive")
choice(menuScanEvent, "Event")
choice(menuScanInterrupt, "Interrupt")
choice(menuScan10second, "10 second")
choice(menuScan5second, "5 second")
choice(menuScan2second, "2 second")
choice(menuScan1second, "1 second")
choice(menuScan_5second, ".5 second")
choice(menuScan_2second, ".2 second")
choice(menuScan_1second, ".1 second")
}

<center>
= Structures, Record types, Fields and Views =
</center>

Structures and record types have significant commonality in that they both define a data structure type containing fields. The main difference is that you can't create or populate an instance of a structure outside of a record; only records can appear at the very top level. Record types also define views of the record, which is not possible for a structure.

== struct ==

A structure is defined as follows:

struct(name) {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
}

where

; <tt>name</tt>
: The structure name must be a valid, unique C identifier.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular structure.
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.

== record ==

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends RecordCommon {
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}
...
view(viewName) {
property(propName, fieldPath)
...
}
...
}

; <tt>name</tt>
: The record type name. It must be a valid, unique C identifier.
; <tt>extends RecordCommon</tt>
: This states that the record type extends the set of fields defined in "V4 DB RecordCommon". It should be permissable to name other record types instead of RecordCommon here, as long as the inheritance tree starts at RecordCommon. Inheritance from multiple record types is not supported; you can only have one <tt>extends</tt> phrase.
; <tt>fieldName</tt>
: Must be a valid C identifier, unique within the context of this particular record type and its parents (extends ...).
; <tt>fieldType</tt>
: See [[#fieldType|fieldType]] below.
; <tt>fieldAttribute</tt> and <tt>attributeValue</tt>
: See [[#fieldAttribute|fieldAttribute]] below.
; <tt>viewName</tt>, <tt>propName</tt> and <tt>fieldPath</tt>
: See [[#Views of a record|Views of a record]] below.

== fieldType ==

Both <tt>struct</tt> and <tt>record</tt> define a field as:
field(fieldName, fieldType) {
fieldAttribute(attributeValue)
...
}

The syntax for <tt>fieldType</tt> depends of the field type. For the more complex types the field definition needs additional information to be provided, which is given inside parentheses following the type name.

<blockquote>

=== Basic types: octet, boolean, numerics, and string ===

The following field types have no arguments:
<tt>octet</tt>, <tt>bool</tt>, <tt>int16</tt>, <tt>int32</tt>, <tt>int64</tt>,
<tt>float32</tt>, <tt>float64</tt>, and <tt>string</tt>.

Examples:
field(description,string)
field(value,float64)

=== enum ===

An <tt>enum</tt> field takes one argument after the type name:

enum(fieldName)

where fieldName is the name of another field in the same record that must be of type <tt>array(string[])</tt>. The values in this other field at runtime define the available choice strings for the enum field.

Examples:

field(choices, array(string[])
field(value, enum(choices))

=== menu ===

A <tt>menu</tt> field is defined like this:
menu(menuName)

where <tt>menuName</tt> is the name of the menu.

Example:
field(scan, menu(menuScan))

=== struct ===

A <tt>struct</tt> field is declared using the type name
struct(structName)

where <tt>structName</tt> is the name of a struct which must have been previously defined.

Example:
struct(Point) {
field(x,float64)
field(y,float64)
field(z,float64)
}
...
record(haspoint) extends RecordCommon {
...
field(point, struct(point))
}

=== array ===

An array field uses definitions like these:

; 1-dimensional array
: <tt>array(arrayType[capacity])</tt>
; multi-dimensional array
: <tt>array(arrayType[capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array
: <tt>array(arrayType)</tt>

; 1-dimensional array of unknown size
: <tt>array(arrayType[])</tt>
; 3-dimensional array of unknown size
: <tt>array(arrayType[,,])</tt>

; 1-dimensional array of unknown type
: <tt>array([capacity])</tt>
; multi-dimensional array of unknown type
: <tt>array([capacityX, capacityY, ...])</tt>
; arbitrarily dimensioned array of unknown type
: <tt>array()</tt>

; 1-dimensional array of unknown type or size
: <tt>array([])</tt>
; 2-dimensional array of unknown type or size
: <tt>array([,])</tt>

* <tt>arrayType</tt> may be any fieldType except <tt>array</tt>, or may be omitted completely in which case the data type stored is determined by record instance. If the record instance defines the type, it can only be one of the types listed above under [[#Basic types: boolean, numerics, octet, and string|Basic types]]
* <tt>capacity</tt> is the array's size in the relevent dimension, and must be specified for all dimensions or for none. If not specified by the record type, the record instance determines an array's dimensionality and size.

Examples:
field(VAL1D,array(float64[])) #1d array with arbitrary capacity
field(VAL2D,array(float64[,])) #2d array with arbitrary capacities
field(anyTypeAnyD,array()) #arbitrary type,number of dimensions, and capacities

=== link ===

This field type can get or put data from/to some source outside of the record.
Link fields replace the DBF_INLINK, DBF_OUTLINK, and DTYP fields from EPICS V3.

A link field's choices come from link definitions - see the [[#link]] section below for more details.
A link can be a link to another database record, to hardware device support,
or something else.

The syntax is:

link(linkDirection,array(string[])= {name,...})

where
* <tt>linkDirection</tt> : <tt>none</tt>, <tt>in</tt>, <tt>out</tt>, <tt>process</tt>, or <tt>inout</tt>. The direction <tt>none</tt> means there is no direction associated with this interface. For <tt>inout</tt> the direction is determined by the particular <tt>link</tt> that the record instance selects.
* <tt>array(string[])</tt> : Each string is the name of Link Interface implemented by link support and used by record support.

Examples:
field(disableLink,
link(in,array(string[4]) = {
"monitorLinkInt32",
"inputLinkInt32",
"monitorLinkFloat64",
"inputLinkFloat64"
} ))
)
field(process, link(process,array(string[1])= {processLink}))
field(inp,
link(in, array(string[3]) = {
"monitorLinkInt32",
"inputLinkInt32",
"digitalIO"
}))
)
</blockquote>

Andrew: Do we want the above syntax? Another possibility is just:
link(linkDirection,interface(string,...))


== fieldAttribute ==

Each field definition has several associated attributes, the values of which are set like this:

default("fieldValue")
readonly(yesNo)
design(yesNo)
special(yesNo)
asl(securityLevel)
link(yesNo)

'''Marty thinks we should get rid of these two:'''
prompt("promptString")
group("promptGroup")

'''I am thinking about combining readonly and design into a single attribute called access, which takes one of four choices: design (the default), runtime, readonly, or none.'''

The attribute parameter values have the following meanings:

; <tt>default("fieldValue")</tt>
: Default value for an instance of this field, using the [[V4 DB Record Instance Syntax|record instance value syntax]]. If a default is not specified, the field will initialize to all zero bits.
: If the field is itself a structure, the default value for the instance of the whole structure can override default values declared for individual fields inside that structure. This can occur at multiple levels.

; <tt>readonly(yesNo)</tt>
: Can this field be modified via channel access or database links? Takes the value No if not specified.

; <tt>design(yesNo)</tt>
: Should a Database Configuration Tool allow the field to be configured at design time? If No, values for the field cannot be set when loading record instance data at startup. Takes the value Yes if not specified.

; <tt>special(yesNo)</tt>
: Does the record have to take special action if the field is modified? If this is Yes, the record types special processing will be invoked to actually change the field value, which will allow it to perform value checks or additional processing. Takes the value No if not specified.

; <tt>asl(securityLevel)</tt>
: Channel Access security level for this field, 0 or 1. Takes the value 1 if not specified.

; <tt>link</tt>
: This is only valid for string fields. It signifies the the field is the name of an external record. This is for use by Database Configuration Tools.

''These attributes may disappear, see comment above:''

; <tt>prompt("promptString")</tt>
: A description of this field for the database designer, this string will be displayed by a Database Configuration Tool. Empty if not specified. Not used within the IOC.

; <tt>group("promptGroup")</tt>
: A name that can be used by a Database Configuration Tool to group similar or related fields together. Empty if not specified. Not used within the IOC.

== view ==

There needs to be more than one way to look at a record remotely (via Channel Access or some other similar network protocol). Often we just want to get the contents of the value field and some metadata associated with that value, but there are often several fields which can share metadata - engineering units for example. We can't do metadata using structures because that would mean replicating this metadata, so we add a level of indirection to allow us to group fields together.

A view of a record provides a hierarchical mapping of some of the record's fields from a named Data Access property catalog that can be reached using Channel Access. Records automatically get a view named "field" that provides direct access to the individual public fields of the record, with no metadata. Beyond that, record types can declare additional hierarchical views and define the fields that appear in them inside the DBD file. The first view defined for a record type is used as its default view (if no views are defined, the field view will become the default view; view parameters may not be permitted).

A simple view looks like this:

view(viewName) {
property(propName) {
property(propName, fieldPath)
...
}
property(propName, fieldPath)
...
}

; <tt>viewName</tt>
: The view name must be a valid C identifier, which must be unique in the context of the particular record type.
; <tt>propName</tt>
: A Data Access property name, which must be a valid C identifier.
; <tt>fieldPath</tt>
: The path to a field in this record type. To use a field inside a structure field, give the full path to that field: <tt>controlLimit.upper</tt> for example.
: If <tt>fieldPath</tt> resolves to a structure, a property catalog containing the whole structure will be sent, with property names matching the structure's field names.
: The <tt>fieldPath</tt> may be omitted as long as there is a subordinate property catalog below this property.

Example:

record(ao) extends RecordCommon {
field(value, float64) { ... }
field(outValue, float64) { ... }
field(rawValue, int32) { ... }
field(units, string) { ... }
field(displayLimit, struct(displayLimit)) { ... }
...
view(value)
property(value, value) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
property(displayLimit, displayLimit)
}
}
view(outValue)
property(value, outValue) {
property(units, units)
property(timeStamp, time)
property(alarmSeverity, alarmSeverity)
property(alarmStatus, alarmStatus)
}
}
view(rawValue)
property(value, rawValue) {
property(timeStamp, time)
}
}
...
}

<center>
= link =
</center>

A <tt>link</tt> statement describes an implementation of support for a link
field. the support can be any of the following:
* A link to another record either local or remote
* A link to hardware support
* Something else.

The syntax for these is:

device(dir, choiceName, interfaceName, dataStructName)

where

; <tt>dir</tt>
: Must be one of <tt>none</tt>,<tt>in</tt>,<tt>out</tt>,<tt>process</tt>, or <tt>inout</tt>. Compatible checks are made to match the interface with a field.
: '''Q: What are the rules?'''
:: ''It certainly doesn't seem to make sense to have a none or inout link for instance.''

; <tt>choiceName</tt>
: UTF-8 string that describes the choice

; <tt>interfaceName</tt>
: The name of an interface via which record support communicates with device support.

; <tt>dataStructName</tt>
: The name of a <tt>struct</tt> that the interface understands. This interface can contain data and configuration information. The <tt>struct</tt> must be defined before record instances can be created that assign values to it.
:: ''Need to rewrite this paragraph to clarify.''

When a record instance is created the choiceName selects the support
to attach to a record link. The interfaceName must be one of the
interface names the record has listed as a valid type and dir must be compatible
with the dir the record type specified.

Examples:
link(in,"monitorLinkInt16","monitorLinkInt16",MonitorLinkData);
link(in,"inputLinkInt16","inputLinkInt16",InputLinkData);
link(out,"outputLinkFloat64","outputLinkFloat64",OutputLinkData);
link(process,"processLink",ProcessLink,ProcessLinkData);

V4 Design: Runtime Interfaces

2005-09-23T16:04:25Z

MartyKraimer:

EPICS: IOC Runtime Interfaces September 23 2005

----
= Overview =

This document describes definitions for IOC runtime,
i.e. interfaces implemented or used by database access, record support,
link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTE IOC runtime needs lots more work

----
<center>
= Support Code =
</center>

This section described interfaces for
strings, arrays, and conversions.
They are intended for use by Database Access, Record Support, etc.

== C++ support for strings ==

This subsection describes interfaces for C++ code that needs tempory storage
for strings. For Java the String class is used.

The following interfaces are for allocating tempory storage for strings:

class NonmutableString {
public:
void destroy(); // Call this when done with string
int32_t getLength();
char data[];
}

class NonmutableStringFactory {
public:
static NonmutableString *create(int32_t len,char data[]);
}

class MutableString : public NonmutableString {
public:
int32_t getCapacity();
void setLength(int32_t len);
}

class MutableStringFactory {
static MutableString *create(int32_t capacity);
}

These will use free lists to manage the storage for the octet arrays.

== array copy ==

ArrayCopy copies arrays an array performing conversions if necessary.

interface ArrayCopy {
void copy(DbfArray from,DbfArray to);
}

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64.
It does NOT convert between
* DbfBoolean and another type.
* DbfOctet and another type.
Thus for DbfBoolean and DbfOctet it is willing to copy
but not convert to/from other types.

== Arithmetic Conversions ==
This is a static class that converts between primitie types and arrays of primitive types.

static class DbfConvertPrimitive {
public:
int16 get(Dbf from);
int32 get(Dbf from);
int64 get(Dbf from);
float32 get(Dbf from);
float64 get(Dbf from);
get(Dbf from, String value);
get(DbfOctet from, String value);
get(DbfBoolean from, String value);
put(Dbf to, int16 value);
put(Dbf to, int32 value);
put(Dbf to, int64 value);
put(Dbf to, float32 value);
put(Dbf to, float64 value);
put(Dbf to,int32 String value);
put(DbfOctet to, String value);
put(DbfBoolean to, String value);

get(DbfArray from, int16[] value);
get(DbfArray from, int32[] value);
get(DbfArray from, int64[] value);
get(DbfArray from, float32[] value);
get(DbfArray from, float64[] value);
put(DbfArray to, int16[] value);
put(DbfArray to, int32[] value);
put(DbfArray to, int64[] value);
put(DbfArray to, float32[] value);
put(DbfArray to, float64[] value);
}

NOTES:
* For Dbf <tt>to</tt> and <tt>from</tt> must be one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>
* The get to a string implements printf semantics
* The put from a string value just scanf semantics.
* The <tt>DbfOctet</tt> methods convert to/from a string of the form "0xXX"
* The <tt>DbfBoolean</tt> get method supports all the choices specified in the DBD Record Instance Specification
* For DbfArray <tt>to</tt> and <tt>from</tt> must be an array of one of <tt>DbfInt16</tt>, ..., <tt>DbfFloat64</tt>

----
<center>

= Code generated from Database Definition Files =
</center>

The following shows the Java code generated from DBD files:

== structure definitions ==

Two files are generated from <tt>struct(name)</tt> definitions.
# <tt>name.java</tt>
# <tt>nameSupport.java</tt>

<tt>name.java</tt> implements:
interface Struct {
Dbf getField(int16 index);
}

If a structure is defined as:
struct(DisplayLimit) {
field(low,double)
field(high,double)
}

A generated file <tt>DisplayLimit.java</tt> contains:

public class DisplayLimit implements Struct{
public DbfFloat64 low;
public DbfFloat64 high;
public static final short lowIndex = 1;
public static final short highIndex = 2;
public static final short lastIndex = indexHigh;
Dbf getField(short index) {
switch(index) {
case lowIndex: return(low);
case highIndex: return(high);
default: throw java.lang.IllegalStateException;
}
return null;
}
}

A generated file <tt>DisplayLimitAccess.java</tt> contains:

public class DisplayLimitData {
public double low;
public double high;
}
public final class DisplayLimitAccess implements StructFactory{
public Struct create() { return new DisplayLimit; }
public static final void get(DbfStruct from,DisplayLimitData data) {
DbfFloat64 dbf = from.getInterface(1);
data.low = dbf.get();
DbfFloat64 dbf = from.getInterface(2);
data.high = dbf.get();
}
public static final void put(DbfStruct to, DisplayLimitData data) {
DbfFloat64 dbf = to.getInterface(1);
dbf.put(data.low);
DbfFloat64 dbf = to.getInterface(2);
dbf.put(data.high);
}
}

public final class DisplayLimitAccessRegister {
static public createAndRegister() {
DisplayLimitAccess access = new DisplayLimitAccess;
RegisterSupport.structure(access,"DisplayLimit");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call DisplayLimitAccessRegister.createAndRegister.

Similar files are generated for C++.

== record definitions ==
If a record is defined as:
record(Example) extends RecordCommon {
...
field(fboolean,boolean)
field(octet,octet)
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(in))
field(device,link(in,analogIO))
field(displayLimit,struct(DisplayLimit))
}

The generated Java file is

public class ExampleRecord implements Struct {
public DbfBoolean fboolean;
public DbfOctet ctet;
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 DbfDevice device;
public DbfStruct displayLimit;
public static final int16 fbooleanIndex = 1;
...
public static final int16 lastIndex = displayLimitIndex;
Dbf getField(short index) {
switch(index) {
case fbooleanIndex : return(fboolean);
...
case displayLimitIndex: return(displayLimit);
default: throw java.lang.IllegalStateException;
}
}
}

public final class ExampleRecordFactory implements StructFactory{
public static final Struct create() { return new ExampleRecord; }
}

public final class ExampleRecordFactoryRegister {
static public createAndRegister() {
ExampleRecordFactory factory = new ExampleRecordFactory;
RegisterSupport.record(factory,"ExampleRecord");
}
}

NOTE The V4 replacement for registerRecordDeviceDriver must
call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

----
<center>
= Record Support =
</center>

enum ProcessState {
processCancel,
processStart,
processContinue,
}

enum ProcessReturn {
processDone,
processAbort,
processActive
}

interface RecordSupport {
void destroy();
void initialize(int32 pass);
ProcessState process(ProcessState state);
// if special returns false when after is false put fails
boolean special(boolean after,Dbf[] field);
}

<tt>ProcessState</tt> supports the following semantics:
* cancel - If the record is active terminate
* For all other states see the companion document "V4 Design: Record Processing"

The methods of <tt>RecordSupport</tt> are:
* <tt>destroy</tt> - Called when a record instance is deleted.
* <tt>initialize</tt> - Called twice (pass = 0,1) when a record is initialized.
* <tt>process</tt> - Called to process a record. See "V4 Design: Record Processing" for semantics.
* <tt>special</tt> - Called when a field declared special in a DBD file is modified. <tt>field</tt> is an array of Dbfs showing which field is being modified.

== Discussion of special ==

Special is passed a Dbf array that identifies the field being modified.
For example <tt>ExampleRecord.dbd</tt> has a field:
field(displayLimit,struct(displayLimit))
<tt>ExampleRecordSupport.java</tt> might implement special as follows:
boolean special(boolean after, Dbf[] field)
{
switch(field[0].getIndex()) {
...
case ExampleRecord.displayLimitIndex:
if(field.length==1) {
// displayLimits itself is being modified. Do something
} else {
// a field of displayLimits is being modified
switch(field[1].getIndex) {
case DisplayLimit.lowIndex:
// low being modified. do something
case DisplayLimit.highIndex:
// high being modified. do something
}
}
...
}
}
----
<center>

= Link and Device Support =
</center>

== Link/Device Base ==
interface Support { // base for Link and Device support
void report(int16 level);
void cancel();
void destroy();
void initialize();
void connect();
void disconnect();
}

<tt>Support</tt> is the base class for all link and device support.
An instance of this is connected to each DbfLink or DbfDevice field.
The methods are:
* <tt>report</tt> - report
* <tt>cancel</tt> - Cancel any outstanding I/O
* <tt>destroy</tt> - This is called if the field is being changed after initialization or if the record is being removed.
* <tt>initialize</tt> - Called to initialize a link.
* <tt>connect</tt> - Called to connect. Note that this is different than initilization.
* <tt>disconnect</tt> - disconnect.

Normally record support does not need to call any of the Base Support methods
since Database Access does this automatically. For example if a link or
device field is modified via a channel access put, database access will call
destroy before modifying the link and initialize and connect after the
link is modidied.

== Link Support ==
enum LinkWaitResult {
linkNoop, // Nothing was done, e.g. link is null link
linkDone, // field was modified. No wait is necessary
linkWaitSequential, // waiting. must processes links sequentially
linkWaitParallel, // waiting. parallel processing OK
}

interface Callback {
void done();
void failure();
}

interface LinkSupport extends Support {
void get(Dbf field);
LinkWaitResult getWait(Dbf field, double timeout,Callback callback);
void put(Dbf field);
LinkWaitResult putWait(Dbf field, double timeout,Callback callback);
void process();
LinkWaitResult processWait(double timeout,Callback callback);
}

<tt>LinkSupport</tt> supports the following semantics:
* Input Link from another record
** get current value independent of processing state.
** Ask the record to process and wait for completion before fetching value.
** wait until next time record processes then get value. No request is made to process the record.
* Output Link to another record
** put value without requesting that record be processed.
** put value then process record but don't wait for processing to complete.
** put value, process record, and wait for completion
* process link to another record
** request processing but do not wait for completion
** request processing and wait for completion

The Wait methods all return LinkWaitResult.

== Device Support ==

Other than that it must extend <tt>Support</tt>,
nothing is defined for Device support in this document.
It will be modeled after the V3 asynDriver support.
----

<center>
= Registration and Instance Creation =
</center>

interface StructFactory {
DbfStruct create();
}

interface RecordSupportFactory {
RecordSupport create(RecordInstance instance);
}

interface SupportFactory {
Support create(Dbf field);
}

interface RegisterSupport {
structure(StructFactory create, string name);
record(StructFactory create, string name);
link(SupportFactory support,string name);
device(SupportFactory support,string name);
record(RecordSupportFactory support,string name);
}

<tt>RegisterSupport</tt> is implemented by iocCore.
Each <tt>struct</tt> DBD definition must register a StructFactory to
create instances of the structure or record.

Each link, device, and record support must register a SupportFactory to create
instances of the support to attach to the link, device, or record instance.
During database initialization, iocCore calls the factory methods.

----
<center>

= Runtime Database Access =

</center>

== Overview ==

Database Access, with help from record, link, and device support
implements the dbdInterfaces.
Other than Database Access, fields of a record can only
be accessed via the interfaces described in dbdInterfaces.
This allows the database to handle
actions like posting database monitors without any help from
record, link, or device support.

Database access by default allocates the actual storage for each field
but allows support code to register itself to manage storage for field
instances.
Two examples, both involving arrays, are:
* The compress record registers to provide storage for the value.
** This allows it to implement a circular buffer.
** Code that accesses the value field may have to issue two get requests.
* Device support for a transient recorder registers to provide storage for the array
** This allows device support to read data from hardware in segments
** Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required.
Database Access will probably have something like the following:

class Field {
DbRecord instance;
short index;
};
...
class IntField extends Field {
int data;
}
...

This each field has the overhead of
* instance - a reference to DbRecord, i.e. record instance
* index - a 16 bit integer
* vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors.
These fields can start out null and only allocate storage as needed.

== Database Access ==

interface DbAccess {
void process(RecordInstance instance, Callback callback);
void processCancel(RecordInstance instance, Callback callback);
void processContinue(RecordInstance instance, Callback callback);
void processRequestAccept(Dbf field, boolean yesNo);
void registerDbfSource(Dbf field, Dbf source);
LinkSupport getLinkSupport(Dbf field);
Support getSupport(Dbf field);
RecordSupport getRecordSupport(DbInstance instance);
RecordSupport getRecordCommonSupport(DbInstance instance);
}

The methods are:
* <tt>process</tt> - Request processing. Record must be idle or active or request fails.
** <tt>instance</tt> - The record to process
** <tt>callback</tt> - A callback to call when processing completes or for failure.
* <tt>processRequestAccept</tt> - Should a process request from channel access be accepted,
* <tt>registerDbfSource</tt> - Register code that will implement storage for the field.
* <tt>getLinkSupport</tt> - Find the link support for a link field
* <tt>getSupport</tt> - Get the device support for a device field
* <tt>getRecordSupport</tt> - Get the record support for the record
* <tt>getRecordCommonSupport</tt> - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

----