An IOC database is created on a Unix system via a Database Conﬁguration Tool and stored in a Unix ﬁle. EPICS provides two sets of database access routines: Static Database Access and Runtime Database Access. Static database access can be used on Unix or IOC database ﬁles. Runtime database requires an initialized IOC database. Static database access is described in this chapter, runtime database access in the next chapter.
Static database access provides a simpliﬁed interface to a database, i.e. much of the complexity is hidden. DBF_MENU and DBF_DEVICE ﬁelds are accessed via a common type called DCT_MENU. A set of routines are provided to simplify access to link ﬁelds. All ﬁelds can be accessed as character strings. This interface is called static database access because it can be used to access an uninitialized as well as an initialized database.
Before accessing database records, the menus, record types, and devices used to deﬁne that IOC database must be read via dbReadDatabase or dbReadDatabaseFP. These routines, which are also used to load record instances, can be called multiple times.
Database Conﬁguration Tools (DCTs) should manipulate an EPICS database only via the static database access interface. An IOC database is created on a host system via a database conﬁguration tool and stored in a host ﬁle with a ﬁle extension of “.db”. Three routines (dbReadDatabase, dbReadDatabaseFP and dbWriteRecord) access the database ﬁle. These routines read/write a database ﬁle to/from a memory resident EPICS database. All other access routines manipulate the memory resident database.
An include ﬁle dbStaticLib.h contains all the deﬁnitions needed to use the static database access library. Two structures (DBBASE and DBENTRY) are used to access a database. The ﬁelds in these structures should not be accessed directly. They are used by the static database access library to keep state information for the caller.
Multiple memory resident databases can be accessed simultaneously. The user must provide deﬁnitions in the form:
NOTE: On an IOC pdbbase is a global variable, which is accessable if you include dbAccess.h
A typical declaration for a database entry structure is:
Most static access to a database is via a DBENTRY structure. As many DBENTRYs as desired can be allocated.
The user should NEVER access the ﬁelds of DBENTRY directly. They are meant to be used by the static database access library.
Most static access routines accept an argument which contains the address of a DBENTRY. Each routine uses this structure to locate the information it needs and gives values to as many ﬁelds in this structure as possible. All other ﬁelds are set to NULL.
Each database ﬁeld has a type as deﬁned in the next chapter. For static database access a simpler set of ﬁeld types are deﬁned. In addition, at runtime, a database ﬁeld can be an array. With static database access, however, all ﬁelds are scalars. Static database access ﬁeld types are called DCT ﬁeld types.
The DCT ﬁeld types are:
A DCT_STRING ﬁeld contains the address of a NULL terminated string. The ﬁeld types DCT_INTEGER and DCT_REAL are used for numeric ﬁelds. A ﬁeld that has any of these types can be accessed via the dbGetString, dbPutString, dbVerify, and dbGetRange routines.
The ﬁeld type DCT_MENU has an associated set of strings deﬁning the choices. Routines are available for accessing menu ﬁelds. A menu ﬁeld can also be accessed via the dbGetString, dbPutString, dbVerify, and dbGetRange routines.
The ﬁeld type DCT_MENUFORM is like DCT_MENU but in addition the ﬁeld has an associated link ﬁeld.
DCT_INLINK (input), DCT_OUTLINK (output), and DCT_FWDLINK (forward) specify that the ﬁeld is a link, which has an associated set of static access routines described in the next subsection. A ﬁeld that has any of these types can also be accessed via the dbGetString, dbPutString, dbVerify, and dbGetRange routines.
This routine allocates and initializes a DBBASE structure. It does not return if it is unable to allocate storage.
Most applications should not need to call this routine directly. The dbReadDatabase and dbReadDatabaseFP routines will call it automatically if pdbbase is null. Thus an application normally only has to contain code like the following:
However the static database access library does allow applications to work with multiple databases simultaneously, each referenced via a diﬀerent DBBASE pointer. Such applications may need to call dbAllocBase directly.
dbFreeBase frees the entire database reference by pdbbase including the DBBASE structure itself.
These routines allocate, initialize, and free DBENTRY structures. The user can allocate and free DBENTRY structures as necessary. Each DBENTRY is, however, tied to a particular database.
dbAllocEntry and dbFreeEntry act as a pair, i.e. the user calls dbAllocEntry to create a new DBENTRY and calls dbFreeEntry when done.
The routines dbInitEntry and dbFinishEntry are provided in case the user wants to allocate a DBENTRY structure on the stack. Note that the caller MUST call dbFinishEntry before returning from the routine that calls dbInitEntry. An example of how to use these routines is:
The routine dbCopyEntry allocates a new entry, via a call to dbAllocEntry, copies the information from the original entry, and returns the result. The caller must free the entry, via dbFreeEntry when ﬁnished with the DBENTRY.
The routine dbCopyEntryContents copies the contents of pfrom to pto. Code should never perform structure copies.
dbReadDatabase and dbReadDatabaseFP both read a ﬁle containing database deﬁnitions as described in chapter ”Database Deﬁnitions”. If ⋆ppdbbase is NULL, dbAllocBase is automatically invoked and the return address assigned to ⋆pdbbase. The only diﬀerence between the two routines is that one accepts a ﬁle name and the other a ”FILE *”. Any combination of these routines can be called multiple times. Each adds deﬁnitions with the rules described in chapter “Database Deﬁnitions”.
The routines dbPath and dbAddPath specify paths for use by include statements in database deﬁnition ﬁles. These are not normally called by user code.
Each of these routines writes ﬁles in the same format accepted by dbReadDatabase and dbReadDatabaseFP. Two versions of each type are provided. The only diﬀerence is that one accepts a ﬁlename string and the other a FILE ⋆ pointer. Thus only one of each type will be described.
dbWriteMenu writes the description of the speciﬁed menu or, if menuName is NULL, the descriptions of all menus.
dbWriteRecordType writes the description of the speciﬁed record type or, if recordTypeName is NULL, the descriptions of all record types to the named ﬁle.
dbWriteDevice writes the description of all devices to the named ﬁle.
dbWriteDriver writes the description of all drivers to the named ﬁle.
dbWriteRegistrarFP writes the list of all registrars to the given open ﬁle (no ﬁlename version is provided).
dbWriteFunctionFP writes the list of all functions to the given open ﬁle (no ﬁlename version is provided).
dbWriteVariableFP writes the list of all variables to the given open ﬁle (no ﬁlename version is provided).
dbWriteBreaktable writes the deﬁnitions of all breakpoint tables to the named ﬁle.
These routines write record instance data. If precordTypeName is NULL, then the record instances for all record types are written, otherwise only the records for the speciﬁed type are written. level has the following meaning:
This routine returns the number of record types in the database.
dbFindRecordType locates a particular record type. dbFirstRecordType locates the ﬁrst, in alphabetical order, record type. Given that DBENTRY points to a particular record type, dbNextRecordType locates the next record type. Each routine returns 0 for success and a non zero status value for failure. A typical code segment using these routines is:
This routine returns the name of the record type that DBENTRY currently references. This routine should only be called after a successful call to dbFindRecordType, dbFirstRecordType, or dbNextRecordType. It returns NULL if DBENTRY does not point to a record description.
The routines described here all assume that DBENTRY references a record type, i.e. that dbFindRecordType, dbFirstRecordType or dbNextRecordType have returned success or that a record instance has been successfully located.
Returns the number of ﬁelds for the record instance that DBENTRY currently references.
These routines are used to locate ﬁelds. If any of these routines returns success, then DBENTRY references that ﬁeld description.
This routine returns the integer value for a DCT ﬁeld type. See Section 14.2.3 for a description of the ﬁeld types.
This routine returns the name of the ﬁeld that DBENTRY currently references. It returns NULL if DBENTRY does not point to a ﬁeld.
This routine returns the default value for the ﬁeld that DBENTRY currently references. It returns NULL if DBENTRY does not point to a ﬁeld or if the default value is NULL.
The dbGetPrompt routine returns the character string prompt value, which provides a short description of the ﬁeld. dbGetPromptGroup returns the ﬁeld’s group key.
Conversion between the group key and the group name as a string is provided by two functions: dbGetPromptGroupNameFromKey returns a pointer to a static string containing the name of the group, NULL for an invalid key. dbGetPromptGroupKeyFromName returns the numerical key related to the speciﬁed group name string, 0 if the string does not match an existing group name.
A record attribute is a psuedo-ﬁeld deﬁnition attached to a record type. If a attribute value is assigned to a psuedo ﬁeld name then all record instances of that record type appear to have that ﬁeld with the deﬁned value. All attribute ﬁelds are DCT_STRING ﬁelds.
Two ﬁeld attributes are automatically created: RTYP and VERS. RTYP is set equal to ,the record type name. VERS is initialized to the value “none speciﬁed” but can be changed by record support.
This creates or modiﬁes the attribute name of the record type referenced by pdbentry to value. Attribute names should be valid C identiﬁers, starting with a letter or underscore followed by any number of alphanumeric or underscore characters.
Looks up the attribute name of the record type referenced by pdbentry and sets the the ﬁeld pointer in pdbentry to refer to this string if it exists. The routine dbGetString can be used subsequently to read the current attribute value.
With the exception of dbFindRecord, each of the routines described in this section need DBENTRY to reference a valid record type, i.e. that dbFindRecordType, dbFirstRecordType, or dbNextRecordType have been called and returned success.
Returns the total number of record instances and aliases for the record type that DBENTRY currently references.
Returns the number of record aliases for the record type that DBENTRY currently references.
These routines are used to locate record instances and aliases. If any of these routines returns success, then DBENTRY references a record or a record alias (use dbIsAlias to distinguish the two). dbFindRecord may be called without DBENTRY referencing a valid record type. dbFirstRecord only works if DBENTRY references a record type. The dbDumpRecords example given at the end of this chapter shows how these routines can be used.
dbFindRecord also calls dbFindField if the record name includes a ﬁeld name, i.e. it ends in “.XXX”. The routine dbFoundField indicates whether the ﬁeld was found or not. If it was not found, then dbFindField must be called before individual ﬁelds can be accessed.
This routine only works properly if called after dbFindRecord, dbFirstRecord, or dbNextRecord has returned success. If DBENTRY refers to an alias, the name returned is that of the alias, not of the record it refers to.
This routine only works properly if called after dbFindRecord, dbFirstRecord, or dbNextRecord has returned success. If DBENTRY refers to an alias it returns a non-zero value, otherwise it returns zero.
dbCreateRecord, which assumes that DBENTRY references a valid record type, creates a new record instance and initializes it as speciﬁed by the record description. If it returns success, then DBENTRY references the record just created. dbCreateAlias assumes that DBENTRY references a particular record instance and creates an alias for that record. If it returns success, then DBENTRY references the alias just created. dbDeleteRecord deletes either a single alias, or a single record instance and all the aliases that refer to it. dbDeleteAliases ﬁnds and deletes all aliases that refer to the current record. dbFreeRecords deletes all record instances.
This routine copies the record instance currently referenced by DBENTRY (it fails if DBENTRY references an alias). Thus it creates a new record with the name newRecordName that is of the same type as the original record and copies the original records ﬁeld values to the new record. If newRecordName already exists and overWriteOK is true, then the original newRecordName is deleted and recreated. If dbCopyRecord completes successfully, DBENTRY references the new record.
This routine renames the record instance currently referenced by DBENTRY (it fails if DBENTRY references an alias). If dbRenameRecord completes successfully, DBENTRY references the renamed record.
These routines are intended for use by graphical conﬁguration tools.
Calling dbVisibleRecord makes the record referenced by DBENTRY visible. dbInvisibleRecord makes the record invisible. dbIsVisibleRecord returns TRUE if the record is visible, FALSE otherwise.
Given that a record instance has been located, dbFindField ﬁnds the speciﬁed ﬁeld. If it returns success, then DBENTRY references that ﬁeld. dbFoundField returns FALSE if no ﬁeld with the given name could be found, TRUE if the ﬁeld was located.
These routines are used to get or change ﬁeld values. They work on any database ﬁeld type except DCT_NOACCESS. dbVerify returns NULL if the string contains a valid value for this ﬁeld or an error message if not. Note that the strings returned are owned by the DBENTRY, so the next call passing that DBENTRY object that returns a string will overwrite the value returned by a previous call. It is the caller’s responsibility to copy the strings if the value must be kept.
DCT_MENU, DCT_MENUFORM and DCT_LINK_xxx ﬁelds can be manipulated via routines described in the following sections. If, however dbGetString and dbPutString are used, they do work correctly. For these ﬁeld types dbGetString and dbPutString are intended to be used only for creating and restoring versions of a database.
These routines should only be used for DCT_MENU and DCT_MENUFORM ﬁelds. Thus they should only be called if dbFindField, dbFirstField, or dbNextField has returned success and the ﬁeld type is DCT_MENU or DCT_MENUFORM.
This routine returns the number of menu choices for menu.
This routine returns the address of an array of pointers to strings which contain the menu choices.
NOTE: These routines do not work if the current ﬁeld value contains a macro deﬁnition.
dbGetMenuIndex returns the index of the menu choice for the current ﬁeld, i.e. it speciﬁes which choice to which the ﬁeld is currently set. dbPutMenuIndex sets the ﬁeld to the choice speciﬁed by the index.
dbGetMenuStringFromIndex returns the string value for a menu index. If the index value is invalid NULL is returned. dbGetMenuIndexFromString returns the index for the given string. If the string is not a valid choice -1 is returned.
dbFindMenu is most useful for runtime use but is a static database access routine. This routine just ﬁnds a menu with the given name.
Links are the most complicated types of ﬁelds. A link can be a constant, reference a ﬁeld in another record, or can refer to a hardware device. Two additional complications arise for hardware links. The ﬁrst is that ﬁeld DTYP, which is a menu ﬁeld, determines if the INP or OUT ﬁeld is a device link. The second is that the information that must be speciﬁed for a device link is bus dependent. In order to shelter database conﬁguration tools from these complications the following is done for static database access.
Each link is one of the following types:
Database conﬁguration tools can change any link between being a constant and a process variable link. Routines are provided to accomplish these tasks.
The routines dbGetString, dbPutString, and dbVerify can be used for link ﬁelds but the form routines can be used to provide a friendlier user interface.
These are routines for manipulating DCT_xxxLINK ﬁelds. dbGetNLinks and dbGetLinkField are used to walk through all the link ﬁelds of a record. dbGetLinkType returns one of the values: DCT_LINK_CONSTANT, DCT_LINK_PV, DCT_LINK_FORM, or the value -1 if it is called for an illegal ﬁeld.
These routines should be used for modifying DCT_LINK_CONSTANT or DCT_LINK_PV links. They should not be used for DCT_LINK_FORM links, which should be processed via the associated DCT_MENUFORM ﬁeld described above.
This routine returns the ﬁeld name of the related ﬁeld for a DCT_MENUFORM ﬁeld. If it is called for any other type of ﬁeld it returns NULL.
Information items are stored as a list attached to each individual record instance. All routines listed in this section require that the DBENTRY argument refer to a valid record instance.
There are two ways to locate info items, by scanning through the list using ﬁrst/next, or by asking for the item by name. These routines set pdbentry to refer to the info item and return 0, or return an error code if no info item is found.
Returns the name of the info item referred to by pdbentry, or a NULL pointer if no item is referred to.
These routines provide access to the currently selected item’s string value. When changing the string value using dbPutInfoSting, the character string provided will be copied, with additional memory being allocated as necessary. Developers are advised not to make continuously repeated calls to dbPutInfoString at IOC runtime as this could fragment the free memory heap. The Put routine returns 0 if Ok or an error code; the Get routine returns NULL on error.
Each info item includes space to store a single void⋆ pointer as well as the value string. Applications using the info item may set this as often as they wish. The Put routine returns 0 if Ok or an error code; the Get routine returns NULL on error.
A new info item can be created by calling dbPutInfo. If an item by that name already exists its value will be replaced with the new string, otherwise storage is allocated and the name and value strings copied into it. The function returns 0 on success, or an error code.
When calling dbDeleteInfo, pdbentry must refer to the item to be removed (using dbFirstInfo, dbNextInfo or dbFindInfo). The function returns 0 on success, or an error code.
It is common to want to look up the value of a named info item in one call, and dbGetInfo is provided for this purpose. It returns a NULL pointer if no info item exists with the given name.
This routine returns the address of the speciﬁed breakpoint table. It is normally used by the runtime breakpoint conversion routines so will not be discussed further.
These routines are used to dump information about the database. The routines dbDumpRecord, dbDumpMenu, dbDumpDriver, dbDumpRegistrar and dbDumpVariable just call their corresponding dbWriteXxxFP routine, specifying stdout for the ﬁle to write to. dbDumpRecordType, dbDumpField, and dbDumpDevice give internal information useful on an ioc. These commands can be executed via iocsh, specifying pdbbase as the ﬁrst argument.
This example is like the dbExpand utility, except that it doesn’t allow path or macro substitution options. It reads a set of database deﬁnition ﬁles and writes all deﬁnitions to stdout. All include statements appearing in the input ﬁles are expanded.
NOTE: This example is similar but not identical to the actual dbDumpRecords routine.
The following example demonstrates how to use the database access routines. The example shows how to locate each record and display each ﬁeld.