Configuration File


Configuration File Location
Schematic and Symbol File Locations
Creating a Configuration File
Configuration File Format
     Windows vs Linux
     Path Definitions
Keywords
[include]
[options]
    Alphabetical List of Options
    Options Reference
        Debugging and Revision Control
        Application Limits
        Application Behaviour
        Warning Message Control
        On-line Options
        Gemini Options       
[color]
[printcolor]
[edbdef]
[epicslib]
[defaultlib]
[userpath]
[dbpath]
[helppath]
[startup]
[dbdpath]
[EPICS ports]
[dbdfile]
[epicsmenuname]
[epicsmenu]
[endcfg]
Environment Variables

Configuration File Location

On program start, tdct looks for a configuration file tdct.cfg  in the sub-directory .tdct of the user's home  directory.
If tdct.cfg is not found, tdct asks the user if it should generate a template tdct.cfg file in the user's home directory. This file can then be edited to reflect the user's configuration.

Unix and Linux
On Unix type systems, the user's home directory is reached with the cd ~ command.

Windows
On Windows XP systems, the user's home directory is C:\Document and Settings\<user>.
On Windows Vista and Windows 7 systems, the user's home directory is c:\Users\<user>.
NOTE: The .tdct sub-directory cannot be created with Windows Explorer. Use the DOS box and type
          mkdir .tdct
from your home directory. Once created, the .tdct directory can be accessed with Windows Explorer.

Schematic and Symbol File Locations

The configuration file contains several directives which point to file locations:


Creating a Configuration File

The tdct menu item Help >> write tdct_example.cfg can be used to write an example configuration file which uses the current configuration parameters.

This file is fully commented  and contains all configuration options even if they equal the default values. This allows conversion of legacy configuration files.

Configuration File Format

The configuration file consists of  configuration directive lines and comment lines.

A configuration directive line starts with  a keyword which is followed by one or more parameters, all separated by white space.
The keyword is enclosed in square brackets.

Any line not starting with a directive keyword is considered a comment.

Windows vs. Linux (or Unix)

For project development teams with both Linux and Windows users it is usually desirable to use a common configuration file.
To facilitate this, tdct can read configuration files where paths are specified in windows format
  e.g.  c:\mydirectory;d:\myotherdirectory
or in Linux format
   e.g. /usr1/project1/mydirectory:/usr2/project2/myotherdirectory

The mapping of Windows drive letters to Linux mount points can be specified in one or more directives of the form

[win2linux] <windows drive> <linux mount point>

For the path examples given above, the following mapping directives would be required

[win2linux] c: /usr1/project1
[win2linux] d: /usr2/project2

Please note that the windows drive lettes and Linux mount points are case sensitive.

Path directives

The following directives define paths:
[edbdef]
[epicslib]
[defaultlib]
[userpath]
[dbpath]
[helppath]
[startup]
[dbdpath]

NOTE: the sequence of directive keywords is important!

The following directive keywords are available (keywords followed by ....  may appear more than once) and should be placed in the sequence shown below:

[options]
....
[color]
....
[edbdef]
[epicslib]
[defaultlib]
[userpath]
....
[dbpath]
[startup]
[dbdpath]
[dbdfile]
....
[epicsmenu]
....
[endcfg]

Keywords

[include]

This keyword can appear more than once. Format:
[include] <include file name>

With this directive, the configuration file can load other files.
NOTE:  be careful to check your actual configuration (with  Help >> View Configuration) . The keyword sequence is important and tdct may not catch all errors.

[options]

This keyword can appear more than once. Generic format:

[options] <option name> [<option value>]

For options, which have possible values of true or false, the option value need not be specified. In this case the option is evaluated to true. If the option is not present in the configuration file, the option evalutes to the default, which is listed below with the specific option.


Options reference

Options are loosely grouped by functionality.

Application Mode

[options] dbdmode
[true | false]
This option controls the compatibility mode. If true "Dbd" mode is on, if false "Compatibility mode" is on.
Important: See the help item on "Capfast Compatibilty".
This option defaults to false.



Debugging and Version Control Options

[options] add_cvs_tags [true | false]
If this option is true CVS $Revision$ and $Date$ tags are added to the [comments] section of schematics and symbols.
This option defaults to true.

[options] cvsframe [true | false]
If this option is true, a CVS revision tag is added to the frame.
Note that this option requires TRIUMF versions for all frame symbols.
This option defaults to false.


[options] debug [true | false]
This option enables the menu item  Options >> Debug print.
The option defaults to false.

[options] switchcfg [true | false]
This option enables the menu item  Options >> Change config file.
The option defaults to false.

Application Limit Options

[options] gridthreshold <float>
This option specifies the minimum display scale above which the display grid is shown. The option defaults to 0.7.
Note: The display grid spacing can be changed from the Options >> Grid menu.
Note: The display grid is independent of the snap grid. The snap grid cannot be changed by the user.


[options] recent <integer>
This option specifies the maximum number of entries in the File >> Open recent menu.
The option defaults to 10.


Application Behaviour Options

[options] add_instance_property [true | false]
This option enables the addition of instance properties, which are not defined on the corresponding
library symbol, to an instance of a symbol on a schematic.
Note: in Capfast compatiblity mode the record fields which are listed in the edb.def file determine which
          fields are written to the database.
This option defaults to true.


[options] backup_files [true | false]
This option controls the back-up of schematic and user symbol files before a modified version is saved to disk.
The backup files have .bak appended to the extension.
The option defaults to true.

[options] copy_paste_with_name [true | false]
This option controls the behaviour of a copy/paste operation for EPICS records.
If the option is true, EPICS record names will be retained during a copy/paste operation.
If the option is false, EPICS record names will be dropped during a copy/paste operation.
This option defaults to false..


[options] cut_paste_with_name [true | false]
This option controls the behaviour of a cut/paste operation for EPICS records.
If the option is true, EPICS record names will be retained during a cut/paste operation.
If the option is false, EPICS record names will be dropped during a cut/paste operation.
This option defaults to false..


[options] dbsuffix <string>
This option specifies the database suffix, which is appended to the EPICS database file name. The option defaults to _tdct.db.
Example:  
If the schematic name is  myschematic.sch, the database will be written to the file myschematic_tdct.db.


[options] display_changed_properties [true | false]
This option controls the automatic display of a dialog box for rearranging / modifying the display of
EPICS record properties after the Ok or Apply buttons of a record property sheet are pressed.
This option defaults to true.

[options] duplicate_connectors [true | false]
This option enables the placement of more than one hierarchy connector with the same name.
This option defaults to false.

[options] empty_macrotwoquotes [true | false]
If the option is true, a macro value consisting of two consecutive double-quotes is replaced
with an empty string.
This option defaults to false.

[options] empty_macrovalues [true | false]
This option allows macros to have an empty value.
If the option is false, an empty macro value causes a warning message and no macro substitution is done.
If the option is true, an empty macro value results in macro substitution with an empty string. If the option
  empty_macrovalues_warn is true, a warning message is issued.
This option defaults to false.

[options] empty_unresolved_macros [true | false]
If the option is true and a database (not a template) is built, macros which are unresolved when record names
or field names are resolved are replaced with an empty string and a warning message is shown.
This option defaults to false.

[options] empty_unresolved_macros_on_registration [true | false]
If the option is true and a database (not a template) is built, macros which are unresolved when a
sub-schematic is intered are replaced with an empty string and a warning message is displayed.
This option defaults to false.

[options] functionality_notebox [none | always | noauto]
If this option is always, a functionality notebox is added in the top-right corner of a schematic when
the schematic is saved.
If this option is noauto, a functionality notebox is added in the top-right corner of a schematic when
the schematic is saved only if the file-path does not contain /auto/.
Note that this option assumes all frame symbol names starting with the letter b followed by the drawing size (a, b, ..., e)
This option defaults to none.

[options] ignore_connector_direction [true | false]
This option is obsolete. It is parsed for backward compatibility.

[options] import_vdb [true | false]
This option controls the importing of vdb files.
If the option is true, VisualDct files can be imported and dbdmode will be set to true.
If the option is false, VisualDct files cannot be imported
This option defaults to false..
NOTE: this option is experimental an not properly tested.

[options] property_dialog_with_parent [true | false]
This option controls the behaviour of property dialogues.
If the option is true, property dialogues will always be on top of the canvas
If the option is false, the canvas will move to top if it receives focus.
This option defaults to false..

[options] record_aliases [true | false]
If this option is true, a tdct allows the adding of aliases for EPICS record names.
This option defaults to false.

[options] record_info [true | false]
If this option is true, a tdct allows the adding of info nodes to EPICS records.
This option defaults to false.

[options] single_property_dialog [true | false]
This option controls the behaviour of property dialogues.
If the option is false, multiple (non-modal) property dialogues can be opened simultaneously
If the option is true, only one (non-modal) property dialogue can be open at any given time. When the selection on a schematic is changed, the dialog is updated.
This option defaults to false..


Warning Message Control Options

[options] add_instance_property_warn [true | false]
This option controls warnings, if an instance property, which is not defined on the corresponding
library symbol,  has been added to a an instance of a symbol on a schematic.
This option defaults to false.

[options] batch_warnings [true | false]
This option controls warning messages from schematic load during batch database building.
This option defaults to true.


[options] duplicate_connector_warn [true | false]
This option controls warnings, if duplicate hierarchy connectors are placed or connected to.
This option defaults to true.

[options] 
empty_macrovalues_warn [true | false]
This option controls warnings, if option empty_macrovalues is true.This option can be modified interactively.
This option defaults to true.


[options] macro_in_menu_warn [true | false]
This option controls warnings, if an EPICS record field of type DBF_MENU contains a macro
This option defaults to true.

[options] warn_on_connector_direction [true | false]
If this option is obsolete. It is parsed for backward compatibility

[options] warn_on_unassigned_id [true | false]
If this option is true, a warning is issued if a record has no id assigned.
This option defaults to true.


[options] warn_on_incomplete_wires [true | false]
If this option is false, warnings about wireswith a free end or hierarchy connectors
without wires are suppressed during database building.
This option defaults to true.



On-line Options

[options]
write_to_ioc [true | false]
This option allows writing to EPICS process variables from the record property sheet. This option defaults to false.


Gemini Options

The following options were added to achieve compatibility with Gemini Capfast usage:

[options] addnppnms [true | false]
This option explicitly adds  the default .NPP.NMS to non-empty record links.
This option defaults to false.


[options] immediate_macro_use[true | false]
This option governs the substitution of macros.
If true  and  a macro value is redefined for a symbol instance, the redefined value of the macro is immediately used for resolution of further symbol instance properties.
If false, and a  macro value is redefined for a symbol instance,  the redefined value of the macro is not used for resolution of other symbol instance properties.
In both cases the redefined macro value is passed on to the corresponding schematic.
It is recommended to set this option to false to avoid unexpected side-effects. (see also help on Building EPICS Databases)
This option was implemented for backward compatibility with Capfast use at Gemini.
This option defaults to true.


[options] overridename [true | false]
This option allows overriding of record names with a name property in an EPICS record symbol. The name property can contain macros. $(I) is treated as a special macro, which gets resolved to the symbol ID on the capfast schematic.
This option defaults to false.


[options] pproc_wireonly [true | false]
This option controls the usage of the pproc and palrm properties when building an EPICS database.
If true, the pproc and palrm properties modify only wired PV links.
If false
This option was introduced, because the Gemini version of e2db resolved pproc and palrm properties differently than the newer TRIUMF version..
This option defaults to true.






[color]

This keyword can appear more than once.

The color keyword allows the configuration of functional colors.
 
There are three variation of this directive:
[color] <function> <color name>
[color] <function> <red>,<green>,<blue>    where <red> ... are decimal values in the range 0 .. 255
[color] <function> <hex color value>       e.g.   0xFF0000

Here <function> is the functional name of the color. The following table gives the available functional colors and their default values, which result in the Capfast look-and-feel on Windows.

functional name default comment
background black
foreground yellow
grid light gray
select red
symbol yellow
symbol_label white
wire white
comment magenta
hierarchy_connector 215,215,215
problem blue
area_select green
highlight red
loose_wire red
connect blue
drag_point green
junction white
pvvalue 100,100,255
minor yellow
major red
invalid white
onlinediff dark gray


[printcolor]

This keyword can appear more than once.

The printcolor keyword allows the configuration of functional print colors. It uses the same set of functional colors as the color keyword.

The default value for all print colors is black, with the following exceptions

functional name default comment
background white
problem blue



[edbdef]

The edbdef keyword is used to define the location of the edb.def file or the specification of and edb.def equivalent file.
Note that edb.def files may contain [include] directives for other edb.def files.



[epicslib]

This keyword can appear more than once.

Theepicslibkeyword is used to define an EPICS library directory. This directory contains symbol files for EPICS records. Since release 2.17.3 this directory may also contain user-defined symbols and schematics.

[epicslib_compat]

This keyword can appear more than once.

Theepicslib_compatkeyword is used to define a EPICS library directory for a secondary EPICS library. The secondary EPICS library is used when tdct operates in dbd mode and reads a schematic which was saved in Capfast compatibility mode.


[defaultlib]

This keyword can appear more than once.

The defaultlib keyword is used to define a default library directory. This directory contains symbol files for frames and hierarchical inputs. This keyword is available for compatibility with Capfast installations. Instead of [defaultlib] the directive [epicslib] may be used.



[userpath]

This keyword can appear more than once.

The userpath keyword defines one directory where user schematics and symbols are stored.Since release 2.17.3 this directory may also contain EPICS record symbols.

[dbpath]

The dbpath keyword defines one directory where generated EPICS database files are written to.

[helppath]

The helppath keyword defines a URL which points to the location of the index file of  web-based help. You can
On-line help requires the environment variable TDCT_BROWSER to contain the startup command for a web-browser.

[startup]

The startup keyword defines the directory where tdct starts up.

[dbdpath]

The dbdpath keyword defines one ore more directories where dbd files are stored.

[dbdfile]

This keyword can appear more than once.

The dbdfile keyword defines one dbd file to be used by tdct.

keyword: [Epics ports]

The EPICS ports keyword defines the EPICS repeater and server ports in on-line mode

[EPICS ports] <CA repeater port>  <CA server port>

By default, there are no ports defined.

[epicsmenuname]

This keyword can appear more than once.

The epicsmenuname keyword defines the name of a sub-menu for EPICS records. Format:

[epicsmenuname] menuSymbolEpics<submenu id>  <submenu label>

By default the submenus menuSymbolEpics1 and menuSymbolEpics2 are provided. The first [epicsmenuname] keyword in the configuration file removes the default submenus.


[epicsmenu]

This keyword can appear more than once.

The epicsmenu keyword defines one EPICS record symbol to be placed onto the Symbol >> Epics primitives menu.  Each epicsmenu entry consists of two lines with the following format:

[epicsmenu] <submenu name>  <menu item text>
<record symbol name>  [<record type>]

<submenu name> must be one of the defined submenu names (see keyword [epicsmenuname] above)

Example without record type definition (edb.def file is required):

[epicsmenu] menuSymbolEpics1 analog in (small)
 eais

Example withrecord type definition (in dbd mode no edb.def file would be required):

[epicsmenu] menuSymbolEpics1 analog in (small)
 eais ai



[endcfg]

The endcfg keyword terminates the configuration file




Environment Variables

The following directives resolve environment variables in the directive parameters.

[edbdef]
[epicslib]
[defaultlib]
[startup]
[dbpath]
[userpath]
[dbdpath]

Example:
[dbdpath] $(PROJECT1)/dbd/

In addition, the Channel Access variables

EPICS_CA_REPEATER_PORT
EPICS_CA_SERVER_PORT
EPICS_CA_ADDR_LIST
EPICS_CA_AUTO_ADDR_LIST

may be used to set up the Channel Access configuration. The environment variables for the repeater and server ports override the values from the configuration file.

The online help system recognizes the environment variable TDCT_BROWSER.
If TDCT_BROWSER provides a command to start a web-browser and the directive [helppath] sets a URL, the help files will be shown in the browser. This may provide superior indexing of help topics.