2. Database Builder API

2.1. Initialisation

epicsdbbuilder.InitialiseDbd(epics_base=None, host_arch=None)

This must be called once before calling any other functions. There are two possible mechanisms for locating EPICS base libraries and dbds.

1. Using the epicscorelibs library. If epics_base is None then the epicscorelibs package will be imported and used as the source of libraries and dbds.

2. Locally install EPICS. If epics_base is provided, then it must be an absolute path to the directory containing EPICS base, in particular this directory must contain both dbd/base.dbd and lib/. This function will load the base EPICS dbd file. The host architecture can normally be computed automatically, but if this computation fails this can be specified by setting host_arch.

epicsdbbuilder.LoadDbdFile(dbdfile, on_use=None)

This can be called before creating records to load extra databases. If on_use is not None it must be a callable taking one argument, and it will be called for each record that is created using records defined by this dbd.

2.2. Record Output

epicsdbbuilder.WriteRecords(filename, header=None, alphabetical=True)

This should be called after creating all records. The generated records will be written out to the file filename. If header is left unspecified then a standard disclaimer header will be generated::

# This file was automatically generated on Fri 27 Feb 2015 15:31:14 GMT.
#
# *** Please do not edit this file: edit the source file instead. ***

Note that the leading # comments are added to any header that is passed

If alphabetical then records, their fields and aliases will be sorted alphabetically, otherwise the records and aliases will be in insertion order and fields in DBD order.

epicsdbbuilder.Disclaimer(source=None, normalise_path=True)

This function generates the disclaimer above. If a source file name is passed then it is included in the disclaimer. Unless normalise_path is set to False the source argument will normalised by calling os.path.abspath(source); this allows the caller to simply pass __file__ as the source argument with the desired result.

epicsdbbuilder.CountRecords()

Returns the number of records that have currently been created.

epicsdbbuilder.ResetRecords()

Resets the list of records to be written. This can be used to write multiple databases.

2.3. Building Databases

epicsdbbuilder.records

This instance has a method for each record type, of the form:

records.type(name, **kargs)

Here name will be used to construct the record name according to the record naming rules currently in force and any field can be given a value by assigning it in kargs.

See epicsdbbuilder.recordbase.Record for more details of these methods.

Note that fields can be assigned either in the constructor or subsequently, and fields can be used as links:

r = records.ai('NAME', INP = '@input')
r.DESC = 'This is an ai record'
r.FLNK = records.calc('NP1', CALC = 'A+1', INP = r.VAL)

class epicsdbbuilder.Parameter(name, description='', default=None)

When using TemplateRecordNames() this can be used to create template parameters with the given name. If description is given then this will be printed in the header. If a default string is given it will be used as the parameter default value, otherwise the parameter will be created with no default value.

epicsdbbuilder.ImportRecord(name)

This generates a record reference without adding an entry into the generated database. Use this when linking to records outside of the database.

epicsdbbuilder.LookupRecord(full_name)

Returns a reference to a record which has already been created.

2.4. Record Naming

Record naming works as follows. Every time a record is created with a call the appropriate method of records the name argument passed to that method is passed through the currently configured RecordName() method.

If none of the functions named here are called then the default naming convention is applied: in this case record names are used unmodified.

There is a simple “high level” API layered over a slightly more general interface.

2.4.1. High Level API

Use one of the following functions for normal configuration:

epicsdbbuilder.SetSimpleRecordNames(prefix='', separator=':')

In this case the given prefix and separator are added in front of any record name. If no arguments are given then the effect is the same as the default naming convention which is to use names unchanged.

epicsdbbuilder.SetTemplateRecordNames(prefix=None, separator=':')

This is useful for generating template databases. If prefix is not specified then a Parameter instance with name DEVICE is created and prefixed together with the separator to each record name.

epicsdbbuilder.RecordName(name)

Applies the current record name conversion to compute a full record name.

epicsdbbuilder.SetPrefix(prefix)

The currently configured prefix can be changed. This function will only work if a SimpleRecordNames or similar naming mechanism is installed.

epicsdbbuilder.PushPrefix(prefix)

epicsdbbuilder.PopPrefix()

These two functions manage a stack of record name prefixes, which will be separated by separator before being appended to the record name.

epicsdbbuilder.SetSeparator(separator)

This function can be used to change the prefix separator.

2.4.2. General Interface

More generally any callable object can be used for record name generation.

epicsdbbuilder.SetRecordNames(names)

This sets up a record naming convention. The argument passed will be called each time a new record is created. This function should take a name as argument and return the full name to be written to the generated database.

The default naming mechanism uses the record name unmodified.

When this method is called the previously establishing record naming convention is returned.

class epicsdbbuilder.SimpleRecordNames(prefix='', separator=':', check=True)

This implements a minimal naming convention. If no prefix is specified record names are generated unchanged, otherwise the given prefix and separator are contatenated to the front of the passed argument. If check is set the the resulting name is checked for length. Supports the following methods.

__call__(name)

Returns prefix + separator + name. If prefix is currently None then an error will be generated.

SetPrefix(prefix)

Allows the prefix to be modified. This can be called via the global SetPrefix() method.

PushPrefix(prefix)

PopPrefix()

These two functions manage a stack of record name prefixes, which will be separated by separator before being appended to the record name. Can be called via the corresponding global functions.

class epicsdbbuilder.TemplateRecordNames(prefix=None, separator=':')

Subclasses SimpleRecordNames to automatically add a $(DEVICE) template to the prefix stack.

epicsdbbuilder.GetRecordNames()

Returns the current record naming convention.

2.5. Helper Functions and Classes

epicsdbbuilder.CA(record)

epicsdbbuilder.CP(record)

epicsdbbuilder.CPP(record)

epicsdbbuilder.NP(record)

epicsdbbuilder.PP(record)

epicsdbbuilder.MS(record)

epicsdbbuilder.MSS(record)

epicsdbbuilder.MSI(record)

epicsdbbuilder.NMS(record)

Used for record links to add the appropriate processing annotation to the link.

Example (Python source):

other_record = records.ai('other')
my_record.INP = PP(MS(other_record))

Example (Generated DB):

field(INP, "other PP MS")

2.5.1. JSON links

EPICS base 3.16.1 (and 7.0.1) has the ability to add JSON links: https://epics.anl.gov/base/R7-0/6-docs/links.html

You can use these by passing a dictionary structure to one of the database fields or to add_info(). Note that no validation is done on the structure of these as dbVerify does not validate them:

records.ai('other', VAL={"const": 3.14159265358979})

class epicsdbbuilder.ConstArray(iterator)

Used for Constant Link Values available since EPICS 3.16.1. Constant Link Values is an EPICS feature which allows passing an list of strings or a list of numbers as a constant into a field which contains a DB link (e.g. INP): https://epics.anl.gov/base/R7-0/6-docs/RELEASE_NOTES.html#constant-link-values

ConstArray will accept any iterable (e.g. a list) which can generate a non-empty list of values of the same type. Allowed types are:

• strings and parameters (i.e. epicsdbbuilder.Parameter)

• numbers (integers, floating-point, decimal.Decimal, and booleans. Booleans will convert to 0 (False) or 1 (True) automatically.

Known limitations:

• No field type or record type check. ConstArray can be assigned to any field despite the field or the record type does not support Constant Link Values. Use it with link fields (e.g. INP) of record types stringin, stringout, lso, lsi, printf, waveform, subArray, and aai. Any other use is undefined and a warning may or may not appear while loading the DB (e.g. assigning [“1.23”] to INP of the record type ai will print a warning while assigning [1.23] to INP of the record type ai will treat it as a CA link without any warning on EPICS 7.0.3.1). Always refer to EPICS Release Notes (section “Constant Link Values”).

Example (Python source):

r = records.lsi('r', INP=ConstArray(['Plain String not DBLINK']))

Example (generated DB):

field(INP, ["Plain String not DBLINK"])

epicsdbbuilder.create_fanout(name, *records, **args)

Creates one or more fanout records (as necessary) to fan processing out to all records in records. The first fanout record is named name, for others a sequence number is appended to name.

epicsdbbuilder.create_dfanout(name, *records, **args)

Creates one or more dfanout records as necessary to fan a data output to a the list of records in records.

2.6. Record Class

class epicsdbbuilder.recordbase.Record

A subclass of this class is created for each record type and used to populate epicsdbbuilder.records: for example, records.ai is a subclass of Record used to generate ai records.

__init__(name, **kargs)

The argument name is used to construct the record name. Any field appropriate for this record type can be named in kargs, for example:

records.ai('NAME', VAL = 42, PINI = 'YES')

add_alias(alias)

This method causes an EPICS alias statement to be added to the database giving alias as an alternative name for this record. The alias argument is used unchanged.

add_comment(comment)

This adds a comment line above the created record. '# ' is prepended to the comment string. Comments are emitted in the order that they are added.

add_metadata(metadata)

This adds a metadata entry to the created record. Metadata entries are like comments, and will be emitted in the same order, but have '#% ' prepended to them. They can be used by processing tools.

add_info(name, value)

This method causes an EPICS info statement to be added to the database. Its value can be either a a dictionary structure which will be converted to JSON (e.g. for info(Q:group, {...})) or something else which will be double quoted (e.g. for info(autosaveFields, "VAL")).

2.7. Using other dbCore functions

Advanced usage may require using other functions from the dbCore library to get extra introspection information about records.

epicsdbbuilder.mydbstatic.GetDbFunction(name, restype=None, argtypes=None, errcheck=None)

This can be used to get a dbCore function by name. The other arguments are used to decribe the function in the standard ctypes way.

The other introspection functions will need a pointer to the current record and field within the currently loaded DBD. This can be done with the DBEntry utility class

class epicsdbbuilder.dbd.DBEntry(entry=None)

Create a dbEntry instance within the current DBD.

This is a stateful pointer that can be moved to different record types and fields within them with the iterate methods.

If entry is specified on init and is a DBEntry instance, it will be copied so that its position is maintained.

iterate_fields(dct_only=0)

Iterate through a record’s fields, yielding their names

iterate_records()

Iterate through the record types, yielding their names