Reference attachments have always been one of MicroStation's most important features. In this article we explore the variety of ways MicroStation V8 can save the file name for reference attachments and the algorithm that it uses to locate references when a DGN is opened.
When a file is attached as a reference, the master file to which it is attached must record the name of the file so it can be opened in future sessions. The way that the file name is stored has been the source of some user frustration in the past, and has undergone some refinements as MicroStation has evolved.
The most obvious way of storing the file name is to simply save the full file specification of the reference. That is, if the file is c:\activeProjects\project704\structural\steel.dgn, simply store that full string in the master file. While MicroStation/J (which we now sometimes refer to as "V7") and earlier versions gave the user a way of forcing this result, it has never been the recommended procedure.
The problem with this approach is that it is completely inflexible. If the whole project is moved to a different disk or a different directory on the same computer, then the reference file will not be found. If the project is kept on a file server, then the share point is likely to be different for different users, and the reference might be located on some computers but not others. The only solution is to go into every file and modify the reference attachments for each one.
Figure 1. A sample project directory structure.For this reason, the default behavior for graphically chosen reference files is to store only the file name and extension of references, and then rely on the user or project administrator to set the reference file search path configuration variable MS_RFDIR properly for each project. MS_RFDIR can be set to a list of directories (separated by semicolons); MicroStation searches each directory for the reference attachments.
The advantage of this approach is that moving a project, or parts of a project, does not require any changes to the DGNs. It does require changes to MS_RFDIR. A disadvantage is that MS_RFDIR has to be set differently for each project.
Another approach supported since MicroStation V4 is to define specific configuration variables and to use the configuration variable to establish the directory in which the reference file resides. For example, consider the following project directory structure shown in Figure 1. A project administrator could define configuration variables (Figure 2). The references could then be attached by either keying in reference attach P704BORDERS:border_a.dgn or using the Select Configuration Variable option in the Directory menu of the reference file selection dialog. In either case, MicroStation stores the file name as P704BORDERS:border_a.dgn.
P704BORDERS = c:\activeProjects\project704\borders\P704STRUCT= c:\activeProjects\project704\structural\P704SITE=c:\activeProjects\project704\site\Figure 2. Configuration variables.
The advantage of this approach is obvious; if the project is moved (e.g., to c:\InActiveProjects\, or to a file server), the only change needed is to redefine the configuration variables. In fact, the astute project administrator would probably set the configuration variables like as shown in Figure 3 and then would need to redefine just PROJECT704-the other configuration variables redefine themselves automatically.
An enhancement to MicroStation/J allowed reference files to be specified as "relative" to a configuration variable. Thus, given the directory structure in the example above, the project administrator could define a single configuration variable, PROJECT704, and the reference above could be attached using the key-in reference attach PROJECT704:borders\border_a.dgn.
PROJECT704=c:\activeProjects\P704BORDERS = $(PROJECT704)project704\borders\P704STRUCT= $(PROJECT704)project704\structural\P704SITE=$(PROJECT704)project704\site\Figure 3. Revised configuration variables.
The advantage to this approach is that there is only one configuration variable, so users don't have to think much to know which to use. There are two disadvantages to this method. First, there is no convenient way to get this result when selecting a reference file using the reference file selection dialog. Second, it "locks in" the project directory structure. The entire project can easily be moved to another root directory or file server, but the internal directory structure can only be changed by making changes to reference attachments. An interesting variant of using configuration variable relative file names is using the built-in configuration variable _DGNDIR, which always points to the directory of the current master file. The advantage is that there is no need to define any configuration variables, but the same disadvantages above still apply-the internal project directory structure must be stable, and there is still no way of getting this result from the graphical file selection process.
In MicroStation V8 (version 08.00.01.19 and later) there is a new capability for storing the reference file names relative to the master file. This effect is similar to that described above when file names are stored relative to the configuration variable _DGNDIR, but there is a distinct advantage when MicroStation V8's live reference nesting is used. If the master file references a file in another directory that has its references stored relative to _DGNDIR, those nested references won't necessarily be found because _DGNDIR now refers to the directory of the master file rather than the directory of the top-level reference file. MicroStation V8 stores the relative path directly to avoid that problem.
Another advantage is that it is possible to specify relative paths when using the Reference File selection dialog. The Save Relative Path toggle in the lower left of the dialog (Figure 4) tells MicroStation to store the relative path to the DGN. For system administrators who do not want to allow relative paths, the MS_DISALLOWRELATIVEREFPATH configuration variable can be set to 1 to remove the Save Relative Path option from the reference selection dialog and disallow relative paths.
Figure 4. Attach Reference dialog.
Using relative paths eliminates the need for defining project- specific configuration variables or redefining MS_RFDIR, but, as pointed out above, it limits flexibility by requiring that a project maintain an unchanged internal directory structure. Relative paths should not be used for references to DGNs in another project, or are shared between projects.
For each reference file, MicroStation stores a file specification in the reference attachment. The stored file specification is displayed to the user in the File Name column of the References dialog. When a reference is attached, MicroStation examines way the file was chosen and decides what to store for the file specification that will give the user the best results in terms of flexibility and maintainability. If a configuration variable is selected from the reference file selection dialog, or entered as part of the name in the reference attach key-in, the configuration variable is always retained as part of the file specification. The file is specified relative to a configuration variable in the reference attach key-in, the configuration variable and the relative path are always retained as part of the file specification. If a relative path is specified through the reference file selection dialog or as part of the name in the reference attach key-in, the relative path is always retained. Otherwise, only the file name is retained.
Beginning with MicroStation V8, MicroStation also saves the full file specification of where the reference file was located. This is very convenient for the user attaching the reference file, because it means that they will always be able to locate the reference file when they reopen the master file (unless, of course, they move or delete the file). However, because other project participants might not have the same directory structure or file shares, the full file specification might not enable them to locate the file. Therefore, this behavior can be prevented by setting the configuration variable MS_DISALLOWFULLREFPATH, and many project administrators choose to do so. When MicroStation opens a file, it searches for references in the following places, in order:
This search algorithm is designed to maximize the chances that each project participant will find the correct reference file.