This document is a users manual of how to use VisualDCT and also contains some tips and ticks.
The audience of this document are all users of VisualDCT.
Table of Contents
How to Read This Document
This document's meta-information (authors, revision history, table of contents, ...) can be found above. What follows below is the body of the document. The body is composed of several sections, which may be further composed of subsections.
Typographical styles are used to denote entities of different kinds. For a full list of entities and their respective typographic conventions, please refer to the Styles section of the XML Documentation document.
When viewing the document in a non-printed form, it is possible to submit comments regarding a given section to the document's owner. This is achieved by clicking the mail icon next to the section title. For this to work, your mail must be configured to properly handle the mailto URLs.
Visual Database Configuration Tool (VisualDCT) is an EPICS database configuration tool completely written in Java
and therefore supported in various systems. It was developed to provide features missing in existing configuration tools
as Capfast and Graphical Database Configuration Tool (GDCT). Visually VisualDCT resembles GDCT; records can be created,
moved and linked, fields and links can be easily modified. But VisualDCT offers more: using hierarchical design od DBs and groups,
records can be grouped together in a logical block. Additionally indication of data flow direction using arrows makes the design
easier to understand. VisualDCT has a powerful DB parser, which allows importing existing DB and DBD files.
Output file is also DB file, all comments and record order is preserved and visual data saved as comment,
which allows DBs to be edited in other tools or manually.
VisualDCT is designed to create and maintain EPICS record instance database (.db) files. In order for VisualDCT to execute properly, a database definition (.dbd) file has to be provided which contains the specifications for the various record and device types that they intend to reference in any record instance database (.db) file to be created by VisualDCT. Once a database definition (.dbd) file has been specified, records can be created, copied, renamed, etc. using the various facilities provided by the VisualDCT. As the user interacts with the various VisualDCT windows, selections, and data entry fields, the results of these interactions are displayed on the screen. Revisions and data entry updates of record instance data displayed on the screen do not replace previously stored record instance data until the user saves currently modified record instance database (.db) file. As VisualDCT executes, it attempts to trap and display the most common situations that might lead to diminishing the integrity of the user supplied information.
In order to run VisualDCT, Java Runtime Environment 1.4 is required.
VisualDCT is distributed as a Java ARchive package (.jar file),
so there is only one file in the binary distribution.
This file has to be added to the java classpath variable
(search path for application classes and resources) to help JVM find com.cosylab.vdct.VisualDCT class,
which is the main class of the VisualDCT.
VisualDCT Java ARchive package (.jar file) is so called executable JAR file, which means it can be run as:
or if you GUI has this feature double-click on VisualDCT.jar will also do it. VisualDCT accepts two parameters which are not obligatory: database definition files and record instance database files (if this is already specified in DBs, specification of database definition file is not needed). DBD is recognised as a file with .dbd extension otherwise DB is assumed. If there is no DBDs specified an Open dialog will appear allowing you to specify DBD file. If even then there is no valid DBD specified VisualDCT will exit with the following output:
An example of running VisualDCT, using test.dbd definition database and test.db instance database file:
VDCT_DIR environment variable is used to define the default working directory.
For saving configuration data Java Preferences API is used. This means configuration is kept in a system depended configuration storage, e.g. registry when using Windows OS, ~/.java (user) and /etc/java (system) on UNIX/Linux systems..
VisualDCT searches for plugins configuration in users home directory. If there is none, it looks into the
VDCT_CONFIG_DIR directory, where VDCT_CONFIG_DIR is an environment variable is used to define the default plugins configuration directory.
Default value of VDCT_CONFIG_DIR is
You can generate flat databases also from command line, which is useful for generation from scripts or generating large databases. Same as for VisualDCT, Java Runtime Environment 1.4 is required, but the difference is you can use it on a headless terminal. To start the generation you have to add VisualDCT's jar to classpath and invoke a specific class (com.cosylab.vdct.GenerateFlatDatabase), which takes care of the generation. This command line tool basically takes two parameters: the input .vdb file (probably your main file), which is used together with all the .vdb files included as templates and the output .db file, to which the flat database is generated.
We also provided a script for running this tool, named flatdb, which can be found next to the distribution of VisualDCT.
Additionaly you can specify command line option -d or --dbd-file, followed by the name of a .dbd file. This loads a specific .dbd file before generating a flat database.
Options --enable-global-macros and --disable-global-macros respectively enable and disable global macro evaluation.
Options --enable-capfast and --disable-capfast enable and disable production of hierarhical names like CapFast.
Both of the above command line options when not specified on the command line, use the same settings as were made in VisualDCT's visual user interface (settings are automatically saved).
VisualDCT can be considered as a rapid database development tool - unintuitive database construction using ordinary text editors can be done quickly with a few simple mouse-clicks minimizing all unnecessary keyboard input. Visualization of the record instance database makes databases easier to understand, errors are much easier to find (e.g. broken links are indicated by a red cross) and helps find a better design of the databases. Allowing user to user hierarchal design and split databases into logical blocks.
VisualDCT creates and maintains only one file, the record instance database (.db or .vdb) file, and does not have any additional graphical information file avoiding any possible consistency problems when having multiple files, all necessary visual composition data is stored as comments at the end of the DB file. An example of DB file:
VisualDCT has powerful parser which has ability to parse already existing DBs, files which have been created or modified with other tool. It also detects syntax errors in databases, including DBDs. Defective visual composition data or its absence are safely handled and do not raise any critical error, VisualDCT simply automatically layouts all objects without any visual data. What is more, VisualDCT preserves comments and record/field order in the record instance database, which offers the ability to edit your databases in other tools or manually without making any harm to the databases and VisualDCT.
Figure 1: Record
Record is represented as a write square with its type and name written inside.
Below the line inside the record there is an area where all fields values are shown, selection of fields depends on its visibility property.
A multi-point wire can be drawn between any two linkable fields simply by adding connectors (moveable small squares on a link line). If a link is an inter-group link (link between two fields which are not in the same group), the link is represented as a line going in the screen with the target link name shown by side. Wherever VisualDCT detects there is a possiblity of two wire to merge, it indicates this by drawing a small dot on the wire (at the possible point of merging).
Figure 2: Group
Group is represented as a white square with its name inside. Double click over it descends into it.
Figure 3: Template Instance
Template instance is represented as a larger write square. It its body it contains: name (id) at right at the top, template description below, template ports (values to be passed out of the template) and template macors (macro definitions to be passed inside the template).
Those template fields can be reordered just by dragging them, but default (and recommended) order implies input fields on the left and output fields on the right side.
Figure 4: Links
VisualDCT distinguish several link types:
Figure 5: Line/arrow, box and textbox (plain and HTML)
There are two ways of linking:
[Matej Sekoranja] VisualDCT uses the following rule: linking destintation is the object which value contains target name, e.g. ao001.INP (source) field contains "ao002.VAL" value (target).
VisualDCT has a capability to morph (change) record and template types, i.e. to change type and preserving all common fields. Command is accessible via- menu or pop-up (context) menu.
VisualDCT supports custom defined borders (just like the borders around mechanical and
electrical engineering drawings) which have author, id, name and change
blocks. They consist of lines, rectangles and text blocks, but no
records. Once merged, the block remains as a single block with text editable.
Grouping is based on the naming,
for instance record with name grp1:ao001 belongs to group grp1 and record grp1:grp2:ao002
belongs to group grp2 which belongs to grp1, so groups can be also nested.
In previous examples : character was used as a grouping separator, which is the default,
but it can be easily changed in Settings window (
As every powerful IDE also VisualDCT provides indispensable facilities as clipboard and undo support. A great effort was given to synchronization between the record instance database and its visualization. Every change done visually is immediately reflected in the database and vice versa; all actions like moving, renaming and deletion of records which affect links are automatically fixed by the VisualDCT.
Graphical User Interface of the VisualDCT consists of 3 main windows:
Figure 6: Main window
The main window consists of:
Figure 7: Inspector window
The inspector tool provides a capability of inspecting (examining) and modifying of all objects properties.
Basically the inspector tool is already all needed to edit record instance databases - it replaces ordinary text editor.
Each field has additional property called visibility, whether the field value is shown inside the record body (see Record representation). It can be changed by clicking right mouse button over left column. Tree icons indicate the visibility state of the field:
A macro definition can be entered for any field, including menus and links. Any changes to fields take place immediately in the visual composition.
Figure 8: Console window
Console window is used to replace standard output of the JVM, which is often ignored by the user. All output is redirected to the console which pops up every time a new message appears in it and so informs user about the new message.
This section describes all commands available by the VisualDCT.
This section describes menu commands available by the VisualDCT.
Among all visually documented (on the left side of menu items) combinations there is one additional combination:
Figure 9: Plugin Manager window
To make VisualDCT more flexsible support for plugins was implemented. For detailed information about plugins refer to VisualDCT Plugins document.
Since VisualDCT is an active project, there are some features to be implemented in the future releases of VisualDCT and all bug reports, suggestions and ideas are very appriciated.
If this manual did not meet all of your expectations or if you have any questions or suggestions,
please feel free to contact the author.