GDCT User's Manual

by Jim Kowalkowski

The Graphical Database Configuration Tool (GDCT) allows the user to build EPICS databases and visualize links between records and process variables. This manual describe how to use the Graphical Database Configuration Tool.

Table of Contents


".dbd": An EPICS R3.13 database definitions file.

".db": An EPICS record instances file. Built using rules in ".dbd" files.

Drawing Area: The area in the tool where records are shown graphically and links are visualized.

Hidden Records: Records that exist in the current database being edited, but are not seen graphically.

Basic Principles

GDCT creates and maintains two files: a graphical information file and a ".db" file. The ".db" file contains only the information that EPICS needs and understands to create a ".db" file. This information is basically just EPICS records and fields. The graphical information file contains the graphic representation of the records and links in the ".db" file.

This tool is designed to edit graphical files and ".db" files. When a session is saved by the user, the ".db" file is saved with a name given by the user. The graphical file is also saved with the same name as the ".db" files, but without the ".db" extension. The ".db" file is the file that is opened by the user. The graphical file is read in along with it. The tool comes up with an empty, unnamed database ready for records to be added.

GDCT can be run in any directory. The tool requires at least one EPICS ".dbd" file to be loaded in order to create and edit record instances. GDCT has several rules associated with loading dbd files at startup time.

  1. If invoked with no options, search the current directory for all dbd files and load them into the editing session.
  2. If invoked with a list of file names, then attempt to open all the files as dbd files into the editing session.
GDCT honors the EPICS dbd/db file search path environment variable EPICS_DB_INCLUDE_PATH. The variable is a space separated list of directory to search for dbd/db files. If this variable in now present, then GDCT adds it to the environment with the default search path ". ./dbd ../dbd ../../dbd ../src".

Starting the Tool

The file list has already been described above. The "-v" option informs GDCT to save records instances with all the fields showing. Normally GDCT just saves the fields that are not defaults.

Two windows will appear on the screen, one is the tool palette, the other is the main drawing area with menu bar. The tool palette contains items that act on the drawing area. Selecting a tool with the left mouse button makes it the currently active tool.

The main window contains a menu bar with file and edit operations, an information line, and the main drawing area. The information line shows the name of the current database on the left. In the lower right corner of the screen are controllers for panning around the drawing area. As mentioned previously, the tool comes up editing an empty unnamed database.


All selecting is done with the left mouse button. A tool selected from the tool palette will be used at the point where the left mouse button is pressed in the drawing area. The items found in the tool palette are as follows: When a new record graphic is to created, a dialog box appears. The dialog box lists the available record types and has a place to enter a new record name. The three buttons available are show, create, and done. The show will be explained later. Create makes the record with the name in the new name entry field. Done removes the dialog without doing anything. A object will appear similar to the one in figure one. The circle with the cross hairs on the left is a linkage point. All links will contain these nodes. The node as it appears here on the record graphic is where a forward link to the record will connect.

When a record is created, no fields are available to link to. The examine tool must be used to produce the list of available fields. Selecting fields from the field list makes them visible as part of the record object. The reason for making GDCT work this way is because records have many fields, most of which have no link information. This mechanism allows the user to see only the fields relevant to linking. Adding unnecessary fields to the graphic should be avoided, they take up a large amount of screen realestate and do not convey any important information.

The direction of flow through link is from left to right; data enters the record on the left and exits from the right. There are three types of fields that can appear as part of the record: data, in, and out fields. Data fields hold a piece of data, such as the VAL or HIHI fields of a record. Since the data fields can be populated by other record's output fields and read by other record's input fields, a connection node will appear on the left and right side of the field. Input links appear with a connection node on the left side and output links appear with a connection node on the right side. Linking a record requires that the linkage tool be selected. A multi-point wire will can be drawn between any two linkable nodes on the screen. Each time the left mouse button is hit, a new bend will be introduce on the wire. The wire is terminated by hitting the middle mouse button.

Links have attributes which can be modified with the examine tool. When the examine tool is selected and mouse is depressed anywhere on a connection wire, the user can select the edit attributes option. A dialog will appear allowing for the PP/NPP/... and MS/NMS/... to be adjusted.

Records contain attributes which can also be modified using the examine tool. A dialog box will appear showing all the fields of a record which can be modified. The current values are shown and can be modified by selecting the edit box and typing a new value. A macro definition can be entered for any field, including menus and links. Any changes to fields take place immediately in the database. The done button just dismisses the dialog. There are several very important rules which are followed regarding visible link fields and the fields which appear in the edit attributes field edit dialog box. Any link field that is linked on the record graphic will be visible and modifiable in the field editing dialog box. If you modify the information in this field, you will corrupt the information stored in the graphics file. The DTYP (device type) field is special. This is due to the fact that a change in the DTYP field implies that OUT or INP of the record be adjusted based on the type of link (VME, GPIB, etc.). To accommodate this, the DTYP field on the field edit dialog has a form button which pop's up a dialog for the device link information (such as card, signal). If a record is defined by the DTYP to be a soft record and the OUT/INP field is a process variable link (graphically linked), then updates to the DTYP field will not be applied to the database. In order to change the DTYP field in this case, the link must be deleted. To use macro definitions in the INP/OUT fields, first select the desired DTYP, then edit the string in the INP/OUT field and add macro defintions.

Editing Non-graphical db Files

Existing db files created from other tools can be opened and added to the current working database. The tool maintains two types of records: graphically defined records and hidden records. The intention here is to allow users to retain all the information they have in their current databases, not to automatically generate a graphic picture of their old databases.

A db file is read into the current session by using the the open or the import records option in the main menu bar pull down menu file. Graphical records are seen in the drawing area and all tools in the tool palette can be used on them. Hidden records are not seen at all. Records can be transferred from the hidden world to the graphical world using the record/type tool (create record tool) dialog. The top button, "show" on the create graphical record dialog box will show all the hidden records for the selected record type. One of the hidden records can be selected from the list instead of a new name being entered. When create is hit, a graphic will be created for the hidden record and it will be transferred to the graphic world, retaining it's field information.

Hidden record can be created and edited. Under the file option on the menu bar is an option called "hidden record edit". This option brings up a dialog which will perform the following functions: edit, delete, copy, and duplicate. To create a new hidden record, select a record type, enter a name in the new name edit box, and hit the "edit" button. The dialog which appears is identical to the field edit dialog of the graphic world. To copy a record, select a record type and hit "show". Select a record to be copied and enter a name in the new name entry box and press "copy". Delete and duplicate work the same way.

Menu Bar Options

The menu bar contains two pull down menus: file and edit. The file menu contains options for operating on the current database and the edit menu contains options for manipulating selected records.

The file menu contains the following options:

It is important to remember that open and save are used on the db and the dbd files, not the graphical files.

The edit menu contains the following options:

The delete operation will only delete records which are not linked. The duplicate operation will duplicate a record and append a sequence number on the end of the record name. No link information is duplicated with this operation.

Command Line Tools

A utility exists for manipulating files from the command line. The tool named "sf2db" converts short form reports from DCT to ".db" files for GDCT. The "sf2db" program acts as a filter, it is fed a short form report in from stdin (by pipe or redirection) and produces the new ".db" file to stdout (the screen).

X11 Resources