CONNECT Edition - Configuration Tips : Reference file variables

The following tips are valid for V8i applications, the variables mentioned have not changed in CONNECT Edition.

From MicroStation help:

When MicroStation opens a DGN file, it searches for DGN files that contain attached references as follows:

  1. If the file specification contains a custom configuration variable, it searches that directory, using the relative path, if any.
  2. It searches a list of directories which consists of all of the directories for the parent files of the reference. If the reference is attached directly to the master file, the search path consists only of the directory of the master file. If the reference is nested, the path consists of the directories of each parent file, starting with the most deeply nested. The directories searched include the relative path, if any, in the file specification.
  3. It searches the directories specified by the configuration variable MS_RFDIR, again retaining the relative path, if any, in the file specification.
  4. It uses the full file specification in the reference attachment, if present.

I normally include the following section in the Standards.cfg file:

# Reference Settings

# pre-set reference attachment defaults
MS_REF_DEFAULTSETTINGS   = display=1,snap=1,locate=1,treatAsElement=0,nestMode=none,trueScale=1,synchWithSavedView=1,nestOverrides=always,scaleLineStyles=1,displayRasterRefs=1,ignoreWhenNesting=0,GlobalLSScale=Master,PrintColorAdjustment=0 


The reasons for using these are as follows:

In my view the ideal method for controlling reference files is to turn off full paths and relative reference paths so the WorkSet configuration file is the only method of specifying valid locations for reference attachments. This allows consistent folder structures to be maintained, if users cannot reference from non-standard locations they won’t be tempted to create them! I can’t see any reason to allow full paths to be saved in any well managed installation. However this approach may not be suitable for all environments.


By default MicroStation saves the full path to a reference attachment. Set this = 1 to disable this behaviour.


If it left enabled, references can be attached and retained from any location. This can result in project folders structures growing in an uncontrolled manner which can make it really difficult for project managers and team members to find, track and backup project information. I have encountered active production files referenced from individual user temp folders and even the desktop.

Additionally: if project data needs to be reorganized, a project needs to be branched to a new version or moved to a new network location, the MS_DEF and MS_RFDIR values specified in the WorkSet.cfg will simply update with the new locations.


By default MicroStation displays the option to save the relative path to a reference during attachment. Set this = 1 to disable this behaviour. The Save Relative Path check box is removed from the Attach Reference dialog. The choice of whether to do this or not is less clear cut.


Using relative references can result in attachments paths being broken if project folder structures change. Users do need to be trained in the implications of relative paths if they are used.

If you do not expect the internal folder structure of your WorkSet to change, the best way to ensure portability when attaching references is to turn on Save Relative Path in the Attach Reference dialog. This causes the relative paths to DGN files that contain attached models to be saved as attachment data in the open DGN file.

Where you are sure that the internal folder structure of your WorkSet will not change, you can set the configuration variable MS_ALWAYSRELATIVEREFPATH. When this configuration variable is set, MicroStation always turns on the Save Relative Path check box and disables it so that it cannot be turned off.


This variable and its accompanying switches will pre-set the default options for reference attachments. This will make reference attachment setting consistent at the level where the variable is applied. These options remain open for alteration at placement so user operations are not restricted.

Recognized keys and values include: display=0|1, snap=0|1, locate=0|1, treatAsElement=0|1, attachMethod=coincident|world|geoReprojected|geoAECTransform, useLights=0|1, saveRelativePath=0|1, scaleLineStyles=0|1, ignoreWhenNesting=0|1, displayRasterRefs=0|1, displayBoundary=0|1, newLevelDisplay=fromconfig|always|never, nestMode=live|copy|none, nestDepth=<value>,nestOverrides=allow|always|never, useAnnotationScale=0|1, synchWithSavedView=none|volume|allsettings, levelControlDisplay=0|1, plotAs3D=0|1.


Enabling this ensures that newly created levels in referenced files are displayed when the referencing model is attached references.

Translated German Wiki article:
CONNECT Edition - Referenzdatei Variablen