Graphical Database Configuration Tool (GDCT):
A tutorial for users of GDCT who have little or no experience with database configuration
This guide to the use of GDCT was created because when we used the program there was very little documentation available on the subject. The one manual we were able to find (entitled "GDCT User's Manual", by Jim Kowalkowski) is available online
at:
For those who are familiar with similar configuration tools such as Capfast or DCT this manual may be enough instruction; in our case, however, since neither of us had any previous experience with this type of tool, we found the manual to be too brief.
What I've tried to provide here is a supplement for those who feel the same, with a few EPICS-specific comments included.
Contents:
- Background Information
- Getting Started
- Opening a File
- A GDCT Tutorial
- Other Useful Things
- Working with the ".db" File
- Testing the Database: How to Make a Corresponding EPICS Panel
The main parts of a database are the records and the record fields. A record is an "object" in a database, the thing that you put information into and take it out of. Each record in a database must have its own unique name, but aside
from that, there are really no limitations--it can operate in binary, digital or analogue format, perform input or output, operations on record fields, etc. If you can consider a record to be an object, then the characteristics of this "object" are
referred to as fields. Fields refers to everything that determines how the record operates, including any links it has to other records, whether it's connected to hardware or software, the value of the record, precision, alarm levels, units, EPICS
scanning mode, and other attributes depending on record type. When you modify a database's records in some way, it's the records' fields that you actually change.
The program used to make our EPICS database was Graphical Database Configuration Tool, or GDCT. GDCT allows the user to create and maintain a database without ever having to do any real coding; the actual database is hidden
behind a data abstraction barrier, with all interactions with the database done in a "point-and-click" manner. This program creates a graphical interface for the database, with each record represented as a rectangle, and its fields as smaller rectangles
hanging off of the record. The links joining the various records and fields are represented as lines, making it easy to see exactly how all parts of the database are connected.
The GDCT program must be run from a directory containing the GDCT startup/defaults file "default.dctsdr"(where "dctsdr" stands for Default Device Configuration Tool Self Defining Records), as it is this file that specifies for
GDCT all of the defaults for each record type, as well as all of the constraints and prompts needed to run GDCT. It is invoked with the command "gdct"; this opens a new file, as it is not yet possible to specify on the command line a database name to be
brought up when GDCT is first implemented. Note that, like all EPICS tools, GDCT is only available for Suns right now. If the user wants to run GDCT from a directory that does not contain a "default.dctsdr" file, or if he/she wishes to use a file instead
of the "default.dctsdr" file in the current directory, then the command line to be entered when first invoking the program is:
- gdct -s file_to_be_used_as_default.dctsdr
This option comes in handy when all database files are to be kept in the same directory, but not all of them use the same hardware. This way, the user can make different "default.dctsdr" files (with each file supporting different hardware) and then
specify, using the -s option, which is to be used when first starting up. Once GDCT has been invoked, two panels will appear: a large, square panel and a smaller, skinny rectangle. The larger area is the "drawing area", and the smaller is the "tools
palette".
Notice the two groups of arrows in the bottom right corner of the drawing area. The group on the left, containing four arrows, is used to move around on the drawing area; clicking on any of the arrows will cause the screen to shift
slightly in the direction in which the triangle points. The pair of arrows to the right of this are used to enlarge or reduce the size of the objects, relative to the drawing area. Clicking on the upward- pointing arrow causes the objects to enlarge (i.e.
it "zooms in"), and clicking on the downward-pointing arrow reduces the size of the objects on the screen (i.e. it "zooms out").
Below the arrows panel is a rectangular area, which represents the whole drawing area. The small rectangle inside of it is the part of the drawing area that is currently in view. This region may be used for the same purpose as the
left group of rectangles: to shift the view of the drawing area. There are two ways to do this. One method is to click any mouse button on the small rectangle and "drag" it to the desired location. Another method is to position the mouse pointer in the
location to which the view is desired to move, and then click a mouse button. The distance moved varies with which mouse button is used; depressing the left mouse button causes the view to shift only slightly, clicking the middle button moves the view a
bit further, and the right button shifts the view the furthest with each click.
When GDCT is first invoked, the drawing area is blank, a new file is made, and no file is open. To open an existing file, click on the "File" title on the menu bar, located at the top left corner of the drawing area. A menu will
appear below that contains "File" actions, which may be implemented by clicking on the name of the desired action with the mouse. Another way to carry out an action is to use the computer keyboard. Beside the name of each action is a letter, sometimes
preceded by a "^". These are the sequences that may be typed to implement an action. The "^" character represents depressing the "Control" key while typing the appropriate letter. There are keyboard versions of every command, not just the ones in the
"File" menu; they all obey the same principles.
To open an existing file, use the "Open..." command, after which a dialogue box will appear. The large square area in this box lists all of the files in the current directory. The "../" entry on the list allows the user to move to
the parent directory. A file may be selected by either typing its name (and directory path, if appropriate) into the long rectangle above this area, or by "double-clicking" on the desired file from the list.
If you do not wish to open an existing file, but instead to start a new one, no actions need to be taken, since GDCT automatically opens with an unnamed, new file. If, however, you wish to open a new file after editing an existing
file, select the "New" command in the "File" menu. If the current file needs to be saved, you will be asked if you wish to do so; otherwise, a new file will be opened.
Some other important "File" operations that should probably be discussed before getting too deep into database-making are the various saving options. The first time you save a new file, you should probably use the "Save As..."
action. This brings up a dialogue box that lists the files in the current directory, as well as allowing you to move to other directories. To save the file, enter the desired filename in the blank located at the top of the dialogue box and click "Save".
This action not only saves the graphical GDCT file, but also its corresponding database, which carries the same name as the graphical file but with ".db" as a suffix. Once the file has been named, or if you don't want to change its name, the "Save" option
may be used to save it. Like "Save As", this option not only saves the graphical GDCT file, but the database as well.
Other alternatives for saving your work are the "Make Database" and "Rename Database" actions. Both of these simply make a binary database file, which may then be loaded into EPICS using the "dbLoad()" command. These options are
analogous to the "Save" and "Save As..." options, with "Rename Database" prompting you to enter a new name for the database, and "Make Database" just saving the work under the current file name. The two "Database" methods are useful if you want to use the
dbLoad() format to load your database; generally, the "dbLoadRecord()" or "dbLoadTemplate" formats are preferable.
If you wish to save or print your graphical file in Postscript format, the "Print..." option in the "File" menu is not yet implemented. A good substitute is the Unix "xgrab" program (just type "xgrab" on the command line to
implement), as is the Unix "xv" program (implemented with the command "xv"). Both programs allow you several saving options, including black-and- white or color, but "xv" has the added allure of allowing you to save the GDCT screen as a GIF or JPEG, some
options I found to be quite useful.
The final command that I should introduce you to at this point is the "Quit" command, which, as you might expect, exits you from the GDCT program. If your file hasn't been saved it will ask if you want to save it, also allowing you a
last chance to cancel the action. If you do opt to save the file it will save the file in both graphical and ".db" formats, under the same name as it was previously saved; if it hadn't been previously saved, it will prompt you for a name in the same
fashion as for the "Save As" feature.
I will now proceed to take you through the GDCT exercise that was my first experience with the program; I give Dr. Joe White full credit for thinking up this application. The purpose of the database we are about to create is to input two analogue
values, display them back, and then display their sum.
The functions on the tool palette are the ones you will probably use the most when making a database. The first thing you should do when making a new file is write the title and possibly a short description of what it does/documentation on the drawing
area. This is done by selecting "Text", then clicking the left mouse button on the desired location in the drawing area. Now type whatever documentation you'd like. One thing to note is that once you leave the "Text" action, you cannot return to the text
entry to modify or add things. There is no choice of coour, font or justification in any text items; you also cannot copy a portion of the text, each text entry is treated as an entity in itself. Another notable (though probably less important) fact is
that although the "Tab" button seems to work while you are still entering the text, once you exit the option all of the "tabbed" text shifts to the left, and the only remnant of the tab is a small arrow. Pressing the space bar repeatedly instead is a
permanent means of indentation.
Now that you've documented your database, the next step in making a database is to create a record. This is done by clicking on the "Type Record" option, and then clicking the left mouse button in the desired location on the
drawing area. This causes a dialogue box to appear. On the left side of this box are the three available actions: "Show", "Create", and "Done". The "Show" action deals with hidden records--something you don't need to worry about yet. This action will be
described later. "Done" dismisses the dialogue box without any actions being carried out. The "Create" option can only be performed after the record has been named and its type has been selected.
To do this, notice the scroll-able list beside these options. In this list are all of the record types supported by EPICS. They are listed in their "short names"; ai, for example, stands for analogue input. A detailed
description of what each of these names stands for, plus what the characteristics of each record type are, may be obtained from the "EPICS Input Output Controller (IOC) Record Reference Manual", by Janet B. Anderson and Martin R. Kraimer. This is an
invaluable manual for anyone creating an EPICS database. It is currently available online at:
In any case, a record type is chosen by clicking on its name with the left mouse button; the first record you should choose is an ao.
It would probably be a wise idea to give each new record a meaningful name as well. This is done by typing into the blank beside "New Name:" on the bottom right of the panel. By default, the first record that is created in a GDCT
session is given the name "test0", and the names are incremented as more records are created (i.e. the next record is named "test1", then "test2", etc). Give the new ai any name you wish, just make sure it contains NO SPACES--a mistake that cost me
several core dumps when I first started using GDCT.
Once you've named the ao, click "Create". A rectangle should appear in the drawing area, with its record type ("ao") and the name you gave it below the record type. Now repeat the process, again creating an ao, but
position this one slightly below the first, and give it a different name.
Now we're going to make the two records to which the ao's pass their signals. Again select "Type Record", this time clicking on an area to the right of one of the ao's you made. The type of record to be created this time is an ai,
or analogue input. Do this twice, positioning an ai beside each ao on the drawing area. The final record type we'll use is a calc, or calculation record; this is the record that will add the two input numbers. Create one
of these, placing it to the right of the two ai's.
These five records are all of the records needed for this small application in which we add and display two numbers. The next step is to export the relevant fields from each record. This is done with the "Examine" option from the tool palette.
After selecting "Examine", hold down the left mouse button over one of the aos. A menu will appear under the pointer, containing three options: "Field Export List", "Edit Attributes", and "Rename Record". These are the three
methods you have of modifying any record you create. The "Rename Record" option does just what it says--it allows you to change the name given to a record when it first was created, by producing a dialogue box that asks you to enter a new name for the
record selected. "Edit Attributes" creates a panel that allows you to modify the default values given to a variety of fields. Again, see the Record Reference Manual for
details on various fields. The available fields differ between record types, since each record type is only given fields that are relevant to its function. The value of some of these fields may be changed by selecting from pull-down menus, while others
allow you to type the modifications. There were a few instances when I needed to give a field a particular value that wasn't available in its menu, in which case I worked around the problem by editing the ".db" file directly. Don't worry, those are rare
occurrences, and this particular exercise doesn't require this. I will describe this method later on, though.
The third option on the menu--"Field Export List"--is the command we shall use now. Selecting the command will bring up a dialogue box which contains a scroll-able list of field names. These are the fields that may be exported from
the selected record; the purpose of exporting a field is to be able to link it to other records or their fields. It should be noted that once a record is exported, it cannot be "imported" back; that is, any exported field remains exported as long as the
record is around. This doesn't create any real problems, it just winds up cluttering up the screen a bit if it`s exported but not used. Like the "Edit Attributes" option, the fields listed here will differ between record types. The fields we want to
export from the ao's are their "OUT" and "FLNK"(forward link) fields. A field is exported by clicking on its name with the left mouse button, and then selecting "Apply". Unfortunately the field list is not alphabetized, so it might take a while to
find the particular fields you require until you learn their locations. Once you've exported these fields, select the ai's and export their "VAL" and "FLNK" fields. Finally, export the "INPA" and "INPB" fields of the calc.
The inputs and outputs of fields and records are joined together with the "PP/MS"(Process Passive/Maximize Severity) option on the tool palette. This is how the values of the aos will be output to the values of the
ais, and then how the calc will receive the values as input. To create a link, first select "PP/MS" from the tool palette. Now click the left mouse button on the cross-hairs of the "OUT" field of one of your ao's; if you move your
pointer you should see a line attached to the cross-hairs. Use this line to connect the "OUT" field's cross-hairs to the cross-hairs of the ai's "VAL" field; clicking the left mouse button causes the line to bend 90 degrees, and clicking with the
middle mouse button terminates the line. Next, connect the "FLNK" field of the ao to the cross-hairs that belong to the corresponding ai record. Now do the same with the other ao/ai pair. Next, link the "FLNK" fields of both ai's to
the calc's cross-hairs. Finally, connect the "VAL" field of each ai to one of the "INP" fields of the calc.
Now that the calc has its two inputs, we must modify the calc so it knows what to do with them. Select the calc record, then select "Examine", and "Edit Attributes". Twelve lines from the top of the "Edit
Attributes" panel is a line labeled "Calculation". It is this field that tells the calc what to do with the inputs it receives. So enter in this field "A+B"; this will cause the calc to add the value it receives from its "INPA" field to the
value from its "INPB" field.
The motivation for these links is as follows: when a value is given to an ao, the ao updates or "scans" so that its "VAL" field is now this new value. When this occurs, the "FLNK" (forward process link) causes the
ai to which it is connected also to update, i.e. its "VAL" field now contains this new value. The ai's "FLNK" connection to the calc causes the calc to process as soon as the ai does; when the calc processes, it
inputs the current values of the two ai's and adds them together. Since the calc is "FLNK-ed" to both ai's, as soon as the value of either ai changes, the calc will update.
Now that your database does everything it's supposed to, it's ready to be finished off and tested. There should be documentation on the gdct screen, including a title, brief description of what the database does, and (if necessary)
how it should be maintained. The title should be a separate "text object" (i.e. exit the text mode before entering any other text) so that it may be enlarged. This is done by selecting the title, then choosing "Scale" from the tool palette. Now the size
of the text may be increased or decreased by clicking the left mouse button on any of the eight squares, or "handles", that surround the title, and dragging the mouse outwards. A rectangle should appear during this process, which outlines the current size
of the text.
Once the title is appropriately sized, you might want to separate the documentation into different topics; this can be done by dropping either ovals or rectangles around the different areas. Either of these shapes may be created by
selecting their shape from the tool palette, then clicking on the drawing area and dragging the mouse until the shape is the desired size. If you are creating a rectangle, the location at which you first click the mouse will be the location of one of its
corners; for an oval, the location at which you first click the mouse will be its center.
The shapes needn't be horizontally aligned; if you desire a diagonally- aligned rectangle or oval, then choose "Rotate" from the tool palette. Now click on the shape, holding down the mouse button. Dragging the mouse in a circular
motion will cause the object to rotate in the same direction, with a rectangular outline to show the current alignment. You can also use this method to rotate text and records.
It also might be desirable to change the location of things on the drawing area, such as the text, or some of the records. This may be done by selecting the object, then choosing "Move" from the tool palette, and dragging the mouse
to the desired spot. You might find that after moving a record the PP/MS links aren't as you'd like them to be, whether they cross over a record, or cross each other in such a way that it's unclear as to what links where. If this is the case, select the
offending link, and delete it by choosing the "Delete" option from the "Edit" menu. Then redraw the link.
A sample version of this database is available at $BFROOT/download/dch/doc/gdctSample.
There are several other ways to create a database that performs the same function as the one you've just made. One way is not making any "FLNK" connections between the records, and instead setting the records on periodic scans.
This is done by selecting "Examine", and then "Edit Attributes". Near the top of the "Examine" panel is a line labeled "Scan Mechanism"; on the right of this line is both a pull-down menu and a text entry area. The options listed in the menu are all of
the scanning options available. Entering a scanning interval into the text entry area that is not on the menu will cause a dialogue box with a warning to appear, and the value you entered will be erased. By setting a record to periodic scan, you ensure
that the record will update, or "process", once every scanning interval.
Another method is to set only the calc on periodic scan. With this setup, when the calc scans, it then "pulls" its input from each ai; this causes the ais to process, and "pull" their inputs from the
aos. There are a whole ton of variations you can make with these basic methods; you can "FLNK" one ai/ao pair to the calc, which will then cause the calc to force the other pair to process along with it, or you can set one side
for periodic scanning, etc.
One thing you probably can't escape from doing when making a database is creating links to records in other databases. GDCT does this quite easily with its "External Link" option on the tool palette. To create an external link,
select the option, and click on the drawing area where you'd like the external link to be. This causes a dialogue box to pop up. The field in the center is where you enter the name of the field the external link is to represent. You must enter both the
record name AND the field name; if you do not enter a field name, GDCT assumes the "VAL" field by default. For example, say you wanted to link the "FLNK" field of one of your ais to the "PROC" (or processing field) of a record named "xxx", which is
located in another database; then you would type "xxx.PROC" into the entry field. The menu to the right of the field lets you specify where the cross-hairs of the external link will be; choosing "Left" results in the cross-hairs being on the left-hand
side of the external link, "Right" will put them on the right, and "Both" puts one link on each side. Once you've decided this, the only thing left to do is click "Ok", and PP/MS the external link to the field (in this case, the "FLNK" field of the
ai). It should be noted that once an external link has been created, it cannot be changed or edited. The only way to modify an external link is to delete the existing one and make a new external link, this one with the desired changes.
Some additional useful tools are the other options listed on the "Edit" menu. "Duplicate" creates an exact copy of a selected record, with the same fields exported and attributes modified. The only difference is it adds "_0" to the
name of the first record it creates in this manner, "_1" to the second one, etc. This is to avoid having two records with the same name in a database. This can also be used to duplicate recoreds that have been "grouped", although the duplicate will have
none of the links of the original group of records.. "Back" and "Front" are used when you have more than one object stacked; "Back" moves the top object to the bottom of the stack, and "Front" puts the object currently on the bottom to the top of the
stack. "Group" lets you treat several objects/records as one, allowing you to move or rotate all of them as a block. This is done by choosing "Select", then dragging the mouse so that there is a rectangle that surrounds all of the records you'd like to
group. Then select the "Group" option; you'll notice that all of the individual handles surrounding each record disappear, and instead there is one set of handles that surrounds the entire group. Unfortunately, the "group" function does not distribute one
change to all objects in the group, nor does it allow the user to align the "grouped" objects. To treat each record individually again, select the group and click "Ungroup"; this returns the objects to their normal state.
One option that I didn't use too much in GDCT is the "Hidden Records" option. A hidden record is a record that will show up in the ".db" file of the database but not on the GDCT screen. This would be one way to fit all of the records
required for a large database in one file, without having too cluttered of a graphical screen. Hidden records may be created, or they can be imported from other files. To create a new hidden record, select "Hidden Record Edit" from the "File" menu. From
the dialogue box that is produced, select a record type, enter a name for the record, and then select "Edit". This produces a dialogue box that is identical to the dialogue box created when selecting "Edit Attributes" for a normal record. Once you've
selected "Done" from the dialogue box, your record has been created. To obtain a list of the hidden records you've made for a file, go to the dialogue box for either "Edit Hidden Records" or "Type Record", select the desired record type, and then choose
"Show". Now a list of the names of all of the hidden records of this type will appear in the top right of the box; these records may be used or modified by clicking on their names and then choosing the appropriate action (i.e. Edit, Copy, Delete,
etc).
You can also import records from other files. To do this, select "Import Records" from the "File" menu. Then enter the name of the ".db" file-- WITH the ".db" suffix on the end--into the dialogue box that appears. This causes all of
the records, with their modifications, to be added to the ".db" file of the current database. Unfortunately, I couldn't get the "View" option from the hidden records menus to work for imported files, so I never found a way to edit a record once it's been
imported.
Each GDCT file has a corresponding ASCII file with the same name, but ".db" as a suffix. Once you've become fairly comfortable with the concept of fields and records, you can sidestep the whole GDCT process and simply edit this file if you wish. In the
".db" file, each database record is treated like a C++ object of type "grecord". The two parameters of each "grecord" are the record type (abbreviated) and name. Then, inside of each set of parentheses is a list of the fields that have been modified from
their default values; or, if the file is saved when GDCT was invoked with the "-v" option (i.e. gdct -v was enterd at the prompt instead of just gdct) then all of the fields of each record will be listed. The syntax for the fields is:
- field(field_name,"new_value")
Note that the new value must be entered in quotes. It is by editing this file that I managed to side-step the menu options in the "Edit Attributes" screen and instead give a field my own value. For example, in an application I was making in which the
records would be connected to different ADC's depending on whether it was set for simulation or real mode, I modified the "DTYP" field of the relevant records so that its new value was "$ADC" (where ADC is a macro for the analog-to-digital converter being
used). That way, I was able to specify at runtime what type of ADC would be providing input, be it "Soft Channel", or a model number of a real ADC module.
There is already an excellent manual on this subject, called the "OPI User's Manual", by Phillip Stanley. Its URL is:
After reading this manual over, you want to use the "edd" program to create a panel that will work with your database. You should make two "controllers" ("text entry" is a good type), one for each analogue output, and three "monitors", one for each
analogue input, and one for the calc record. An example edd screen is located at $BFROOT/download/dch/doc/exampleScreen.dl.
If you have any questions/comments, please feel free to email them...
Suzanne Komili / University of British Columbia / suzannek@slac.stanford.edu - or - suzannek@unixg.ubc.ca
|
