2. Database Builder API¶
2.1. Initialisation¶
-
epicsdbbuilder.
InitialiseDbd
(epics_base, host_arch=None)[source]¶ This must be called once before calling any other functions. epics_base must be an absolute path to the directory containing EPICS base, in particular this directory must contain both
dbd/base.dbd
andlib/
. 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.
2.2. Record Output¶
-
epicsdbbuilder.
WriteRecords
(filename, header=None)[source]¶ 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
-
epicsdbbuilder.
Disclaimer
(source=None, normalise_path=True)[source]¶ 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 callingos.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.
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)[source]¶ 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)[source]¶ 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='')[source]¶ 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.
prefix can be set to
None
, in which case name creation will fail untilSetPrefix()
is used to change it.
-
epicsdbbuilder.
SetTemplateRecordNames
(prefix=None, separator=':')[source]¶ This is useful for generating template databases. If prefix is not specified then a
Parameter
instance with nameDEVICE
is created and prefixed together with the separator to each record name.
-
epicsdbbuilder.
RecordName
(name)[source]¶ Applies the current record name conversion to compute a full record name.
-
epicsdbbuilder.
SetPrefix
(prefix)[source]¶ The currently configured prefix can be changed. This function will only work if a
SimpleRecordNames
or similar naming mechanism is installed.
2.4.2. General Interface¶
More generally any callable object can be used for record name generation.
-
epicsdbbuilder.
SetRecordNames
(names)[source]¶ 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)[source]¶ 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)[source]¶ Returns prefix + separator + name. If prefix is currently
None
then an error will be generated.
-
SetPrefix
(prefix)[source]¶ Allows the prefix to be modified. This can be called via the global
SetPrefix()
method.
-
2.5. Helper Functions¶
-
epicsdbbuilder.
CP
(record)[source]¶ -
epicsdbbuilder.
MS
(record)[source]¶ -
epicsdbbuilder.
NP
(record)[source]¶ -
epicsdbbuilder.
PP
(record)[source]¶ Used for record links to add the appropriate processing annotation to the link.