EPICS: IOC Database Definition

April 29 2005

Goals

The following is a brief summary of the goals for the V4 Database Definition.

Data Types
- Support "minimal" set of types, i.e. the minimum set that provides the functionality needed for V4 databases.
- Extensible: struct and array are DBD types
- Character Strings
  - Arbitrary Length
  - UTF-8
- Multidimensional Variable Length Arrays
- All supported types configurable by Database Configuration Tools

For example arrays and structs can be initialized via a DCT

record and struct fields
- Arrays of most supported types
- metadata for database access
  - Each field can have associated metadata
  - Extensible set of properties
- remove artifical limits. For example allow arrays of link and menus.
Links

Allow alternative implementations for soft links

Device Support

Record type independent. Use interface for communication between record and device support..

struct can be the way time synchronous gets/puts can be handled. A client can request a get, put, or monitor on a struct and guaranteed that entire set of data is performed with the record containing the struct locked, i.e. no record processing can occur during the get/put. If this is the way time synchronous data is handled, then all the issues of trying to lock sets of record are avoided.

Overview

This chapter describes the Database Definition Syntax for V4 databases. It assumes that the reader is familiar with the EPICS Version 3 (V3) Database Definition Syntax as described in chapter 6 of the 3.14 Application Developer's Guide. The new Database Definition Syntax is meant to be used both by iocCore and by Database Configuration Tools (especially VDCT).

This document only describes the V4 Database Definition. Support libraries need to be created to support the V4 database. These will need their own documentation divided into something like the following:

EPICS: iocTypes
EPICS: IOC Database Access
EPICS: IOC Record Support

Database Definitions

The following definitions are discussed:

include - same as V3 include
menu - like the V3 menu
struct - New for V4.
record - like the V3 recordtype
link
device - these replace V3 device plus much more
registrar - same as V3 registrar
variable - same as V3 variable
record instances - like the V3 record

This document will not discuss the definitions that are the same as for V4.

Database Field Types

The V4 database field types are:

bool: A value that is (0,1) meaning (false,true)
octet: A 8 bit byte. Replaces DBF_CHAR and DBF_UCHAR.
int16: Same as V3 DBF_SHORT.
uint16: Same as V3 DBF_USHORT.
int32: Same as V3 DBF_LONG.
uint32: Same as V3 DBF_ULONG.
int64: New 64 bit integer.
uint64: New unsigned 64 bit integer.
float32: Same as V3 DBF_FLOAT.
float64: Same as V3 DBF_DOUBLE.
string: Replaces V3 DBF_STRING. Arbitrary length character string. It supports Unicode/UTF-8.
menu: Like V3 DBF_MENU but with string for choices.
enum: Like V3 DBF_ENUM but with string for choices.
struct: New for V4.
link
device: link and device are new for V4. Extensible replacement for V3 DBF_XXXLINK and DTYP
array: Multidimensional arrays are now a field type
private: Like V3 DBF_NOACCESS but new syntax.

V3 features not in V4

V3 field types that do not exist in V4

The following V3 field types no longer exist:

DBF_CHAR: Replaced by octet but no arithmetic or conversions are supported.
DBF_UCHAR: Replaced by octet but no arithmetic or conversions are supported.
DBF_DEVICE: Replaced by device.
DBF_INLINK: Replaced by link and device
DBF_OUTLINK: Replaced by link and device
DBF_FWDLINK: Replaced by link and device

V3 Database Definitions not in V4

path: No longer needed.
addpath: No longer needed.
driver: Drivers must develop another way to configure and report. asynDrivers already has replacements.
breaktable: A replacement will be created. What!!!!

V3 field attributes not in V4

pp: Is this part of CA V4? It should be.
base: This was needed for 3.12 releases. It is no longer needed.
size: Not needed since string is arbitrary length string.
extra: New syntax replaces this.
menu: New syntax replaces this.
interest: Only used by dbpr. Find a better way!!!
prompt and group: Replaced by struct, arbitrary length field names, and nodct.

Summary of V4 Database Definition Syntax

include "filename"
 #comment
 menu(name) {
     choice("choice_value")
     ...
 }

 struct(name) {
     field(field_name,field_definition) {field_attributes}
     ...
 }

 record(name) extends iocRecord {
     include "filename"
     field(field_name,field_definition) {field_attributes}
     ...
 }
 #If field_definition is empty record instance determines type
 #     must be one of bool,...,string
 #field_definition is one of the following:
     bool
     octet
     int16
     uint16
     int32
     uint32
     int64
     uint64
     float32
     float64
     string
     menu(name)
     enum # has associated
          # struct() {
          #       field(index,iocInt16)
          #       field(choice,array(string[]))
          # }
     struct(structName,interfaceName)
     link(direction)
     device(direction,interfaceName)
          #direction is null,in,out,fwd, or inout
          #interfaceName is the name of the record/device interface

     # an array field_definition has one of the following forms
     array(<type>[capacity])              #1dim array
     array(<type>[capacity,capacity,...]) #ndim array
     array(<type>)                        #arbitary dimensional array
     #<type> is not specified or one of bool,...,link
     #      If not specified record instance determines type
     #capacity is optional. If not specified record instance determines capacity

     private("valid C type") #must NOT include field name

 #field_attributes is any combination of the following:
     asl(asl_level)
     default("default_value")
     nodct
     readonly
     special
     link                          #This field is a link to another record
     metadata(name,field,dynamic)  #multiple properties can be specified

 interface(interfaceName,choiceName)
 link(dir,choiceName,configStruct)
 device(dir,interfaceName,choiceName,configStruct)
     #dir is null,in,out,fwd, or inout
     #interfaceName is name of interface record support understands
     #choiceName is name that is mapped to interface implementation
     #configStruct is struct containing configuration information

 registrar(function_name)

 variable(variable_name)

 #The Following defines a Record Instance

 recordType "recordName" = {
     include "filename"
     info name = {"info_value"};
     fieldName = {fieldValue};
     fieldName = type {fieldValue}; /*Only if type is not defined in record*/
     fieldName = [capacities] {fieldValue}; /*Only if dim or capacities unknown*/
     fieldName = type[capacities] {fieldValue};/*type and capacities unknown*/
     fieldName = choiceName {configStructValue};/*for struct/link/device fields*/
     ...
 }

 # type is one of bool,...,string
 # capacity is one of
 #   capacity    1dim array
 #   capacity,capacity,...  ndim array
 #   
 #fieldValue is scalar_value or struct_value or array_def or link_value
 #where
 #scalar_value is num_value or string_value
 #    where
 #    num_value is value
 #        example: The following initializes a float64 field
 #                 outputRateOfChange = {1.0};
 #    string_value is "value"
 #        example for menu field
 #                 scan = {".1 second"};
 #        example for string field
 #                 command = {"getValue\r\n"};
 #struct_value is field_value or name = field_value , ... 
 #    assume struct(point) {field(x,float64) field(y,float64) field(z,float64)}
 #    example:  xxx = { y = 1.0, 2.0};
 #array_def is row_value (1dim) or {row_value}, {row_value} ... (ndim)
 #   row_value is  field_value or [index]=field_value , ...
 #   1dim example: The following perform the same initialization
 #         xxx = [4] {1.0,[2] = 3.0,4.0};
 #         xxx = [4] {1.0,0.0,3.0,4.0};
 #   2dim example: The following all create a 3x3 identity matrix
 #         xxx = [3,3]{{1, 0, 0} {0, 1, 0} {0, 0, 1}};
 #         xxx = [3,3]{{1}, {[1]=1}, {[2]=1}};
 #         xxx = [3,3]{[0]={1}, [1] = {0, 1}, {0, 0, 1}};
 #examples of link/device fields
 #    inp = constant {"stringValue");
 #    inp = dblink {pvname = "pvname",pp=1,ms=1};
 #    inp = SomeVMEdevice {card = 0,signal = 2,parm = "parm stuff"}

struct and record

struct

A struct is defined as follows:

struct(name) {
    field(field_name,field_definition) {field_attributes}
    ...
}

where

name: The structure name. It must be a valid C identifier. No two structures can have the same name.
field_name: Must be a valid C identifier
field_definition: See field_definition below.
field_attributes: See field_attributes below.

record

A record type is defined as follows:

include "dbCommon.dbd"
record(name) extends iocRecord {
    field(field_name,field_definition) {field_attributes}
    ...
}

name: The record type name. It must be a valid C identifier. No two record types can have the same name.
field_name: Must be a valid C identifier
field_definition: See field_definition below.
field_attributes: See field_attributes below.

field_definition

Both struct and record define a field as:

    field(field_name,field_definition)

The syntax for field_definition depends of the field type.

Numeric, Octet,and String Types

The following types have no arguments: bool, int16, uint16, int32, uint32,int64,uint54, float32, float64, octet,and string.

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

enum

An enum field also has no argument but has an implicit int32 and array(string[]).

struct() {
    field(index,int16)
    field(choice,array(string[])
}

menu

A menu has the definition:

menu(name)

where

name

The name of the menu.

Example:

     field(SCAN,menu(menuScan))

struct

A struct has the definition:

struct(structName,interfaceName)

where

structName

The name of the struct, which must have been previously defined.

interfaceName

The name of an interface that provides code for the struct.

Example:

struct(point) {
    field(x,float64)
    field(y,float64)
    field(z,float64)
}
...
record(haspoint) extends iocRecord {
    ...
    field(point,struct(point))
}

array

An array has one of the following definitions:

array(<type>[capacity])       #1dim array
array(<type>[capacity,...])   #ndim array
array(<type>)                 #arbitrary dimensional array

where

<type>

Any one of bool,...,link. In addition a null is acceptable. In this case the type is determined by record instance definitions.

capacity

The capacity for each dimension or null. If not specified then record instance determines capacity..

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

private

This is to allow "private" fields, i.e. fields not meant for use by database or channel access. The syntax is:

private("valid C definition")

where a valid C definition must be specified. Example:

    field(asp,private("void *"))

The C definition must not include a field name since the field name in the generated include file is taken from the database definition.

link device

This is for fields that can get or put data from/to a source outside the record. They replace the V3 DBF_XXXLINKs. A link field is similar to the non INP or OUT link fields from V3. A device field is similar to the INP or OUT together with the DTYP fields from V3. A link field obtains it's choices from link definitions. A device field obtains it's choices from device definitions. The main difference between link and device is that record support communicates with link support via a standard interface and with device support via specialized interfaces. The syntax is:

link(linkDirection)
device(linkDirection,deviceInterface)

where

linkDirection

one of null, "in", "out", "fwd", or "inout". If null or inout, i.e. the

direction is determined by the link or device a record instance selects. Examples:

    field(disableLink,link(in))
    field(flnk,link(fwd))
    field(inp,device(in,digitalIO))

field_attributes

field_attributes can be any combination of the following:

    asl(asl_level)
    default("default_value")
    nodct
    readonly
    special
    link
    metadata(name,field,dynamic)

asl: access security level. Must be 0 or 1
default: Default value
nodct: Database Configuration Tool should not show
readonly: This field can not be modified via channel access or database links
special: Take special action if field is modified.
link: The field is a link to another record. This attribute is normally only defined for a field in a struct that is referenced in a link or device definition For example struct(pvlink) specifies the link attribute for field pvname.
metadata: Defines a metadata for the field. Multiple metadata attributes can be defined for a field.

name The name of the metadata. field The name of a field in the same record. dynamic must be static or dynamic. The default is static. dynamic means that the value may change because of record processing. static means that the value does not change because of record processing. time is an example of a dynamic field and displayLimit is an example of a static field.

Example of metadata definitions

An analog output record can have fields like

record(ao) extends iocRecord {
    field(value,float64) {
       metadata("timeStamp",time,dynamic)
       metadata("displayLimit",displayLimit)
       metadata("controlLimit",controlLimit)
       ...
    }
    field(displayLimit,struct(displayLimit))
    field(controlLimit,struct(controlLimit))
    ...
}

link and device

link describes choices for link fields and device describes choices for device fields.

the syntax:

link(dir,choiceName,configStruct)
device(dir,interfaceName,choiceName,configStruct)

where

choiceName: UTF-8 string that describes the choice
dir: Must be one of null,in,out,fwd, or inout. Compatible checks are made to match the interface with a field. What are the rules?????
configStruct: The name of a struct for configuration information
interfaceName: The name of an interface via which record support communicates with device support.

record instance

A record instance has the following syntax

<recordType> "record_name" = {
    info name = {"info_value"};
    fieldName = {fieldValue};
    fieldName = type {fieldValue}; #Only if type is not defined in record
    fieldName = [capacities] {fieldValue}; #Only if dim or capacities unknown
    fieldName = type[capacities] {fieldValue}; #Only if type and capacities unknown
    fieldName = choiceName {configStructValue}; #for link/device fields  
    ...
}

where

recordType: The name of the record type
record_name: The name of the record instance. What restrictions will we place on record instance name? Can this contain non-ascii characters? That is will UTF-8 instance names be supported?
info name: Like V3 except new syntax
fieldName: The field name.
type: One of the types bool,...,string. This is only specified if the record definition did not specify a type.
capacities: The capacities for an array. This can only be specified if the record definition did not define the number of dimensions or the capacities. It has the format:

capacity,...
The number of dimensions must agree with what record defined. For example if the record defined that array as array(<type>[]) then only one capacity can be specified. If a record defined array(<type>) than the record instance determines the number of dimensions and the capacities.

choiceName: This is the syntax for struct, link, and device fields. choiceName is a choice defined in a struct, link, or device definition.
field_value: The syntax depends on the field type. The details are described next..

The format for field_value depends of the field type.

Single Item Field types

The following just have a single value: int16, uint16, int32, uint32, uint32, float32, float64, octet, string, enum, menu For example

    value = {"1.0"} #Field Definition is float64
    scan = {"1 second"} #Field Definition is menu
    description = {"This is a description"} #Field Definition is string
    junk = {"\x01\x02"} #Field Definition is array(octet[])

Structure fields

The syntax follows the C99 syntax for initializing structures. Lets give some examples. assume that the following definitions have been made in a dbd file:

struct(point) {
    field(x,float64)
    field(y,float64)
    field(z,float64)
}
...
struct (pointdes) {
    field(des,string)
    field(point,struct(point))
}
...
record(example) extends iocRecord {
...
    field(value,struct(pointdes))
...
}

Then the following are some of the valid ways to initialize the val field of an instance of an example record. They all do the same initialization.

    value = {"this is the value for val.des",{0.0,1.0,2.0}}
    or
    value = {des = "this is the value for val.des",
             {x = 0.0, y =1.0, z = 2.0}}
    or
    value = {"this is the value for val.des", {y =1.0, z = 2.0}}

Array fields

The syntax for array fields uses the C99 array initialization syntax. Some examples:

    oneD = [3] {1.0,2.0,3.0}
    #The following creates a 3x3 identity matrix
    twoD = [3,3] { {1},{[1] = 1}, {[2] = 1}}
    #The following initializes an arbitrary type, arbitrary dim matrix
    anyDanyT = int16[3,3] { {1},{[1] = 1}, {[2] = 1}}

link or device fields

The syntax is:

    field = choiceName {struct_value}

For link choiceName is one of the choices from link definitions that have compatible directions. For device choiceName is one of the choices from link and device definitions that have compatible directions. struct_value is like the value for struct fields where the structure is the configStruct from the link or device definition which choiceName selected.

Process Variable Names

A process variable name (PV) follow C syntax for specifying fields and elements of arrays. A PV can select an elemenentary field, a structure, of an array.

For example if a pvname is:

   recordname.f1.f2[ind].f3

Then:

f1 is a field in recordname which is a structure
f2 is a field of f1 that is an array of structures
ind selects a structure from the array of structures
f3 selects a field from the structure

Example: Assume that the following has been defined;

struct(s2) {
    ...
    field(f3,float64)
    ...
}
struct(s1) {
    ...
    field(f2,struct(s2) [] )
    ...
}
record(sometype) extends iocRecord {
    ...
    field(f1,struct(s1))
    ...
}
...
record(sometype,"xxx")
{
    ...
    f1 = { f2 = [3] {[1] ={f3 = 2.0}}}
    ...
}

Then:

    xxx.f1.f2[1].f3

selects the float64 value 2.0

    xxx.f1

selects the entire struct s1.

If a client accesses a struct it must know how to access the struct.