..  currentmodule:: epicsdbbuilder

EPICS Database Builder
======================

The EPICS database builder is a support library designed to make it easy to
create EPICS databases from a Python script.  To create a script the following
steps should be followed:

1.  After importing :mod:`epicsdbbuilder` it must be initialised by calling
    :func:`InitialiseDbd`.  This function can either be called without any
    arguments if the epicscorelibs_ module is installed, or passed an absolute
    path to an EPICS base directory where the ``dbd`` directory containing
    ``base.dbd`` can be found.

2.  Next any other dbd files needed can be loaded by calls to
    :func:`LoadDbdFile`.

3.  Optionally a naming convention can be installed by calling
    :func:`SetRecordNames`, or template naming can be set up by calling
    :func:`SetTemplateRecordNames`.

4.  Records can be freely generated by calls to record generation methods of
    :data:`records`.  The loaded dbd files will be used to ensure that all
    values written to fields are valid.

5.  Finally the generated database should be written out by calling
    :func:`WriteRecords`.


A simple example follows::

    from epicsdbbuilder import *
    InitialiseDbd('/dls_sw/epics/R3.14.12.3/base/')
    SetTemplateRecordNames()

    a = records.ao('TEST')
    c = records.calc('CALC', CALC = 'A+B', SCAN = '1 second', INPA = a.VAL)
    c.INPB = c

    WriteRecords('output.db')

Running this Python script will generate the following database file::

    # This file was automatically generated on Mon 02 Mar 2015 12:57:13 GMT.
    #
    # *** Please do not edit this file: edit the source file instead. ***
    #
    #% macro, DEVICE, Device name

    record(calc, "$(DEVICE):CALC")
    {
        field(CALC, "A+B")
        field(INPA, "$(DEVICE):TEST.VAL")
        field(INPB, "$(DEVICE):CALC")
        field(SCAN, "1 second")
    }

    record(ao, "$(DEVICE):TEST")
    {
    }

Note that record fields can be given values when the record is constructed, or
can be assigned a new value at any time.