User’s Guide — RefManager for V810

Introducing RefManager for V810

Axiom is proud to announce the release of RefManager for V810 — the popular utility which solves just about any reference file problem and keeps MicroStation users in control of their reference files.

Features and Benefits

RefManager for V810 includes the popular V78 features enhanced for use with MicroStation V810:

• Modify attachments — RefManager for V810 updates and standardizes reference file attachments in drawings newly converted from V7 to V8. For example, RefManager’s “Modify Reference File Attachments” command can activate “Live Nesting” in multiple V810 files in multiple folders. This is only one of more than 70 reference file settings MicroStation users can manipulate with RefManager for V8.
• Precisely search for attachments — RefManager for V810 offers numerous different search criteria so MicroStation users can precisely identify the exact reference file attachments to be processed. These search criteria, or “filters”, can be used with most of RefManager’s actions.
• Automatically attach references —RefManager for V810 attaches a new reference file to dozens of design files at a time. The “Attach” command saves time when MicroStation users need to update project files or set up a new project.
• Discover the exact status of attachments —RefManager for V810 generates reports about the reference file attachments in one or many files — or in an entire project. The level of detail in reports is user-definable — over 30 different categories of report detail (for example, file path, model name, logical name, description, master and reference file origins, clipping information, rotation, scale, etc.) can be selected.
• Identify missing attachments — In the process of migrating projects to V810, changing project folder structures, etc. a few reference files are bound to go astray. RefManager for V8 identifies missing attachments before they interfere with production.
• Which attachments are vital and which are obsolete? — Out of those hundreds of project files, which are in use and which are obsolete? RefManager’s cross-reference report identifies those files which aren’t used anywhere.

Note: See the “New Features and Fixes” section of this guide for a complete description of the latest enhancements!

RefManager also manages Microsoft Office Importer links!

RefManager 8.10a introduces the ability to modify and report on Microsoft Office Importer links in design files! Microsoft Office Importer links are now treated like vector and raster reference attachments by RefManager.

So now you can use RefManager to modify link paths and other link settings in batch, something which previously had to be done one link at a time. You can even run a Missing Reference Attachment Report on Microsoft Office Importer links to find out if any of the XLS or DOC files linked to your DGN files are missing.

Note: RefManager’s support for Microsoft Office Importer links requires that you have Microsoft Office Importer version 8.9a or later installed — with a valid license — on the same machine as RefManager.

Some Technical Information

There are some key differences between V7 DGN and V8 DGN reference file attachments.

1. When a reference file is attached to a design file, an element is created to store information about the attachment (the reference file's name, scale, origin, etc.).
   • In V7, attachment information is stored in type 5 level 9 and type 66 level 5 elements.
   • In V8 DGNs, attachment information is stored in type 100 level 0 elements.Technically speaking,
   • RefManager for V7 is a powerful type 5 level 9 element editor.
   • RefManager for V810 is a powerful type 100 level 0 element editor.
2. V8 design files contain one or more models. Each V8 model is analogous to a V7 design file.
   • In V7, a reference file is attached directly to a master file.
   • In V810, a reference file model is attached to a master file model.
3. MicroStation V810 supports V8, V7 and DWG attachments.

Chapter — Installation

Before you install

This chapter will walk you through a typical Axiom product installation. These instructions apply to both MicroStation V8 and V10. Microsoft Office Importer for V8 and V10 are used in these examples, but you can use these instructions for other tools and multi-tool installers for both MicroStation V8/XM/V8i and V10.

To install one or more Axiom products, you need:

• The Axiom product’s downloaded setup program; and
• A license file for the product(s) you are about to install.

Please shut down all MicroStation sessions on your computer before continuing.

Typical installation

• Double-click on the Axiom product’s setup program.
• A box similar to the following will appear.

For questions about which type of installation is best for you, please call Axiom Support at 727-442-7774 or e-mail Support@AxiomInt.com.

• Choose which type of installation you want to perform. The “Typical” installation is best for most situations and asks the user to make very few decisions.

These instructions will cover only the “Typical” installation path. Choose “Typical” and click {Next}.

• Choose the license file for this installation. Click on “I have a license file somewhere else.” And press {Next}.

• Browse to the “axiom.lic” file wherever you have it saved and click {Open}.
• The licenses contained in your chosen license file will display in the next box (not shown here). Click {Next}.
• It is common for one computer to have more than one instance of MicroStation installed on it. For example, you might have two versions of MicroStation V8 installed or one V8. If prompted, click on the version of MicroStation you want to associate your Axiom tools with and click {Next}.

Note: Be sure to choose a MicroStation V8 installation if you are installing V8 Axiom tools and a MicroStation V10 installation if you are installing V10 Axiom tools.

Be sure to choose a MicroStation V8 installation if you are installing V8 Axiom tools and a MicroStation V10 installation if you are installing V10 Axiom tools.

• Since this is a “Typical” installation, all programs for which an Axiom license was found will already be “checked-on” to be installed. Other items that are also automatically “checked-on” for installation are the product User’s Guides, individual product sample files and Axiom’s MicroStation pull-down menu.

• To proceed with default selections click {Next}.

Note: Once you reach this point in the setup, you cannot go back to an earlier step. But you can press {Cancel} and start over if you need to change an earlier selection.

• The {Next} button is grayed-out unless you accept the agreement.

• If you accept the license, please choose “I accept the agreement.” And then click {Next}.
• This is the final confirmation box before the installation occurs. If everything looks okay, press {Install}. You can click {Cancel} at any time during the installation.

• Your installation is complete. By default the “View Readme.pdf” option is toggled on and will display the Readme.pdf document when you click {Finish}.

Congratulations

That’s it! You have successfully completed the installation of your Axiom tools.

Chapter 3 — Uninstalling

Uninstalling Axiom products

Axiom products can be uninstalled easily through the Windows® Start Menu.

1. Go to {Start}, Programs | Axiom.
   • Select “Uninstall V7 products”, “Uninstall V8 products” or “Uninstall V10 products”, depending on the products you want to uninstall. The uninstall process is consistent for all three MicroStation families.
   • Choose “Select all.” or “Select components to uninstall.” If you choose “Select components to uninstall.” then each product in the list can be manually checked or unchecked. This allows for any combination of products to be uninstalled. Only installed products will be shown in the list.Note: At the bottom of the list of products you also have the option to uninstall sample design files, user’s guides and even the Axiom pulldown menu.
   • Once you’ve made your selections, click the {Uninstall} button to complete the uninstall process.

That’s it! You have successfully completed the uninstallation of your Axiom tools.

Chapter 4 — Quick Start

Quick Start Objectives

The purpose of this Quick Start is to introduce you to the basic features of RefManager for V10 so that you can immediately use the program.

This Quick Start should take less than 30 minutes.

Prerequisites

1. MicroStation CONNECT Edition (version 10.00.00.25) or later.
   • RefManager for V10 must be installed on your computer. You can verify this by selecting the “Axiom” ribbon tab , then pressing the RefManager button. If RefManager for V10 does not load, follow the instructions in the Installation section of your RefManager for V10 User’s Guide.
   • You will need the sample files that are delivered with RefManager for V10. The default installation will store these sample files in the following location:C:\ProgramData\Axiom\V10\RefMgr\Sample Files\

Demonstration Version

The RefManager demonstration version works the same as the permanent version with one exception. With a demonstration license, RefManager only works on files of 100KB or less.

Needless to say, your permanent version of RefManager will not have this restriction.

When should I use RefManager?

RefManager is most commonly used to handle the following:

• Quickly correct reference attachment paths after moving files from one system to another or after reorganizing the folder structure of a project.
• Generate reports of reference file usage per master file including all attachment settings.
• Generate missing reference file reports.
• Generate cross-reference reports that list master files that each reference file is attached to.
• Attach reference files to a group of design files.
• Detach or replace reference files in bulk.
• Change the scale, shift, origin or clipping boundary of reference files in bulk.
• Change other reference file attachment settings in bulk.

Quick Start Step 1 (Restore Defaults)

First, let’s cover the basics.

1. Select RefManager from the “Axiom” menu.
2. Just in case someone worked with RefManager before you began this Quick Start, let’s restore factory defaults by choosing Settings | Restore Factory Defaults… from the main RefManager box.Tip: You want to ensure that the RefManager sample files are restored to their original state prior to continuing with this Quick Start. Open “Windows Explorer” and navigate to your RefManager “Samples” folder. There, you will find a “Samples.zip” file that contains a backup copy of RefManager’s sample files. Open this ZIP file and navigate to the RefManager “Sample” folder then click the {Extract} button. This will overwrite the existing files in this “Sample” folder with fresh copies of RefManager’s sample files. You would also do this if a colleague had previously performed this Quick Start on this same computer.
3. If you have any questions about RefManager’s features, the full User’s Guide is always available from Help | Contents.

Quick Start Step 2 (Attachment Report)

How to generate a reference file attachment report:

1. Open the sample design file, Donor.dgn. This file is typically installed to:C:\ProgramData\Axiom\V10\RefMgr\Sample Files\Donor.dgn
   • Select RefManager from the Axiom menu. RefManager’s main dialog will display:
   • Select the “Reference File Attachment Report” command as in the image above.
   • The “Change Report Settings” dialog box opens showing the default settings. This dialog allows you to select the detail to be included in your report. Click {Close} to close this dialog for now.
   • For this test the “Master Files:” field should contain the address of the active file, “Donor.dgn”.Tip: You can delete the contents of the “Master Files:” field and press {Tab} to automatically restore the active file name inside the field.
   • Enter an output report file name or click the {Select} button to select a location for your output report.
   • Click the {Start} button.
   • When report processing is complete click the {Display Report} button to view your report.

That’s all there is to it!

Use the “Change Report Settings” dialog box to control the information that is included about your reference file attachments.

To generate a report about reference file attachments in all sample files, use a wildcard in the ”Master Files:” field. For example, replace “...\Donor.dgn” with “…\*.dgn” in the ”Master Files:” field.

Quick Start Step 3 (Attachment Filter)

How to use RefManager’s reference file attachment “Filter” to select specific reference files for processing:

1. From RefManager’s main dialog box, click the {Attachments…} button:
   This displays RefManager’s “Filter” dialog box:
2. Click on the “Logical Name” category.
3. Enter “B*” in the “String” field, then, click the {Close} button.
4. From RefManager’s main dialog click {Start} to recreate a report.
5. View the report. This time the report only includes attachments when their logical name matches the specified wildcard. In this case, the logical name “Boilerplate” and “Border” matched the filter (indicated with bold text for clarity in this document only):
   Note: RefManager’s reference file attachment “Filter” can be used with most RefManager action (not just reports).
6. Before continuing to the next lesson, select “Restore Default Settings” from the “Settings” menu on RefManager’s main dialog box.

Quick Start Step 4 (Copy Attachments)

How to copy reference files from a donor file to a recipient file:

These are the steps to copy reference file attachments from a “donor” to a selected set of design files.

1. Use the {Select...} button on RefManager’s main dialog to find the sample file “Recipient.dgn”. This file is typically installed to:C:\ProgramData\Axiom\V10\RefMgr\Sample Files\Recipient.dgnFrom RefManager’s main dialog, select “Copy Reference File attachments”. The “Copy” dialog box will appear. Our “Donor File” will be the delivered sample file “Donor.dgn”:For the purposes of this Quick Start, we will copy all attachments from “Donor.dgn” to “Recipient.dgn”. You can control which attachments are copied from the donor file using {Select Attachments…}.
   • From RefManager’s main dialog, click the {Start} button.
     “Donor.dgn” attachments will be copied to “Recipient.dgn”, retaining the original attachment settings.
   • Click the {Display Report} button to see a report about the “Copy” processing.
     To copy attachments to multiple project files, just replace “Recipient.dgn” with “*.dgn” in the “Master Files:” field.
   • This is an effortless way to set up multiple sheet files at the beginning of a project.

Quick Start Step 5 (Modify Attachments)

How to make global modifications to reference file attachments:

You can use RefManager’s “Modify” command to update and standardize just about any reference file attachment parameter in one or many reference file attachments in one or multiple project master files.

In this Quick Start step we will update reference file logical names. The same procedure can be followed to make a modification using any of RefManager’s “Modify” categories.

1. Open “Donor.dgn” in MicroStation.
2. Display MicroStation’s “References” dialog. Note the logical names for the attached reference files. Leave the “Reference” dialog displayed.
3. Enter “Donor.dgn” into the “Master Files:” field on RefManager’s main dialog.
4. From RefManager’s main dialog, select the “Modify Reference File Attachments” command:
5. The “Modify” dialog will display. We will use the Modify category “Reference Location” (the default).
6. Select the attachment Component “Logical Name”.
7. Enter “Boilerplate” into the “From” field, Enter “Copyright” into the “To” field.
8. Press {Test}. A preview of the Logical Name modification should display.
9. From RefManager’s main dialog, click the {Start} button.
10. Re-examine MicroStation’s References dialog. The logical name “Boilerplate” should now be replaced by “Copyright”.

All RefManager “Modify” categories work the same way – select the desired modification and press {Start}.

Use this procedure to modify a single file’s attachments or for an entire project – just specify a wildcard in the ”Master Files:” field.

You can limit modifications to specific attachments using RefManager’s attachment “Filter”.

Quick Start Completion

Congratulations! That completes the RefManager Quick Start.

Go ahead and work with your own files. By default RefManager creates a backup of your master files before processing them, so no worries.

Remember that the full User’s Guide is always available to you from RefManager’s Help menu (select Help | Contents).

See the Frequently Asked Questions section of the full User Guide for answers to the most common questions and miscellaneous tips.

Phone info and e-mail links to Axiom Support and your Axiom MicroStation Consultant are also available from the Help menu (select Help | About). Contact us any time.

We are also very interested in requests or suggestions about RefManager. We look forward to hearing from you.

Chapter 5 — Using RefManager

RefManager’s Main Dialog Box

Push the RefManager button on your Axiom ribbon tab to start it.

Choose RefManager from the Axiom menu in MicroStation.

Action: Select the RefManager command to perform on selected master files and their reference files.

Master Files: Select one or many master files for processing.

Master Models: Select master file models to be processed. Default is all models.

Attachments: Select specific reference files for processing. Default is all vector and raster attachments.

Report File: Select name and location for RefManager’s reports.

When you change from one command to another, command-specific options will be displayed in separate windows.
Click {Start} to begin processing. Click {Display/Print Report} to view the processing report.

Action

RefManager actually consists of multiple reference file utilities. Select the tool you need from RefManager’s “Action” list.

Attach Reference Files

Attach one or more reference files to one or more master files.

Change Update Sequence

Change the update sequence for your master files and their vector and raster attachments.

Clone or Replace Reference File Attachments

Add new reference files to your master files using the settings of pre-existing attachments.

Copy Reference File Attachments

Copy selected reference files from a specified “donor” file to one or more master files.

Detach Reference Files

Detach selected reference files from specified master files.

Modify Reference File Attachments

Change just about any reference file attachment characteristic in one or more reference file attachments..

Reference File Attachment Report

This report is sorted by master file and lists details about the reference files attached to each.

Cross-Reference Report

This report is sorted by reference file and lists the master files in which each reference file is used.

Missing Reference Report

This reported is sorted by master file and lists each reference file attachment that cannot be located.

Master Files

Specify which master file or files you want to process with RefManager.

Click {Select...} to select an individual file or a list of files to be processed. For more information, see the section titled Choose Files to Process.

Tip: If you clear the contents of the Design Files field and press {Tab}, the field will be refreshed with the active design file’s name.

{Models...}

The {Models...} button takes you to the “Master Model Filter” dialog box, which allows you to specify which master file models should be processed.

Model Name field accepts a specific model name, a comma-delimited list of quoted model names, a model name wildcard or “@” followed by the full path to a file containing the names of models to be processed (one per line).

Model Description field also accepts all of the above to select specific models by description.

Note: If you are using RefManager to process the active design file, the active model is the currently displayed model. If you are using RefManager to process a master file which is not currently displayed, or perhaps “*.dgn”, the active model will be the model which was active when settings were last saved using MicroStation’s Save Settings.

{Attachments…}

By default, RefManager processes all reference files attached to selected master files.

However, using “filters” you can precisely select a subset of your reference files for processing.

Click {Attachments...} to display the Filter Reference File Attachments dialog.

When at least one filter option is active, an asterisk is displayed on the button: {*Attachments...}.

Note: some RefManager commands offer their own attachment selection features. When this is the case, the {Attachments…} button on the main dialog is disabled (gray).

Report File

RefManager suggests a processing report file name for you whenever you change from one of its commands to another.

If a report file already exists it will be overwritten each time you press {Start}.

To generate a different report file for each master file, specify a wildcard such as “*.rep” or “*.log” in the report file name field. Report file names will inherit the base name of the design file plus a “.rep” extension.

Click {Select...} to select a folder and file name for your processing report.

RefManager’s Menus

File

File | Exit

This will unload the RefManager application.

Settings

By default, RefManager settings are saved in refmgr.ini the following location:

%appdata%\Axiom\V10\RefMgr\

The active RefManager settings file name location (space permitting) are displayed in the Settings menu.

Load Settings...

Save customized RefManager settings for re-use later.

Save Settings

Save RefManager settings to the active settings file (or create refmgr.ini if it does not already exist).

Save Settings As...

Save RefManager settings to a new settings file name.

□ Save Settings on Exit

Save RefManager settings automatically when the program is unloaded.

Settings File: (file name)

This line displays the name of the active RefManager settings file.

Restore Default Settings...

Restore Default Settings removes any selections that have been made and resets RefManager to factory defaults.

Change Program Settings

???? Always preserve master file’s date and time.

This option allows you to retain master file date and time even when RefManager modifies the master file’s attachments.

???? Automatically re-open child windows.

The “Automatically Re-Open Child Windows” option controls whether or not RefManager will reopen the windows that were displayed when you last exited RefManager.

???? Backup each master file before processing

This option allows you to backup your master files before they are modified. RefManager recognizes several key words which can be used in this field to define the backup location and file name.

Any characters besides the keywords are included without alteration in the output path and filename.

Keyword

Description
<DRIVE>
The device or drive portion of the full file name including the colon “:”. For example “C:”.

<DIR>
The folder portion of the full file name. For example, “C:\MyProject\MyFile.dgn”.

<NAME>
The base filename (without drive, folder or extension).

<EXT>
The three letter extension with period. For example “.dgn”.

Note: If you change the factory default: <DRIVE><DIR><NAME>.BAK, be sure to perform a quick test to confirm your backup files are created just the way you want them.

Note: This option does not create new folders.

Here are some examples:

1. To create a backup of your drawing(s) with “.BAK” extension:
   <DRIVE><DIR><NAME>.BAK
2. To create a backup of your drawing(s) with “.BAK” extension, but also retaining original extension:
   <DRIVE><DIR><NAME><EXT>.BAK
3. To create a backup of your drawing(s) in an existing subfolder:
   SAVE\<NAME><EXT>
4. To create a backup of your drawing(s) to an existing folder on your server:
   N:\Backups\<NAME>.BAK

□ Prohibit creation of links to non-existent files.

MicroStation V8 does not allow creation of attachments to reference files that do not already exist on hard disk.

RefManager’s Copy and Modify commands may create reference file names which, at least temporarily, do not yet exist on hard disk. By default, RefManager for V8 allows this (consistent with RefManager for V7).

Activate this option to disallow creation of attachments that do not exist on hard disk.

It is useful to check this on when fixing reference attachments before moving or renaming the actual reference files.

□ Update screen during processing.

Depending upon the speed of your computer and the complexity of the views configured in the various files to be processed, you may want to speed up processing by turning this feature OFF. If, on the other hand, you want to keep an eye on the individual files as they are processed, turn this feature ON.

Change Report Settings...

Select the report detail and report options that are appropriate for your needs.

These options are described in the section “Change Report Settings”.

Help

Help | Contents

Select this to display the RefManager User’s Guide.

Help | About

Select this to display version and licensing information.

{Start}

Press the {Start} button to begin RefManager processing with the selected command.
The {Start} button displays gray (disabled) when RefManager needs more information. For example, if you select the Modification Reference File Attachments command, the {Start} button will remain gray until you specify at least one modifications to perform.

{Display Report}

Click {Display Report} to display the report file name displayed in the Report File field.

This button remains gray (disabled) until the report file has been generated.

Note that RefManager automatically renames the processing report when you change from one Command to another.

Chapter 6 — Filter Reference File Attachments in Master Files

Filtering Reference File Attachments

By default, RefManager processes all reference files attached to the master files selected for processing.

There may be times when you want to process only selected reference file attachments. To select specific reference files, click the {Attachments…} button:

This will display RefManager’s “Filter Reference File Attachments By” dialog box:

Any Filter category with an active Filter option will be flagged with an asterisk “*”.

You can use a single filter option or multiple filter options in any category in any combination.

Note: RefManager always combines Filter options with “AND”. In other words, attachments must match ALL selected Filter criteria.

Note: some RefManager commands offer their own attachment selection features. When this is the case, the {Attachments…} button (on the main dialog) is disabled (gray).

Supported Commands (RefManager processing modes)

Filters apply to all RefManager commands (processing modes) except:

• Change Update Sequence
• Attach Reference Files
• Order Reference File Slots

{Clear} and {Clear All}

Each Filter category includes {Clear} and {Clear All} buttons.

Click {Clear} to turn off Filter options for the currently displayed Filter category.

Clear {Clear All} to turn off Filter options for all Filter categories.

Compare

This option only pertains to the “File Name” filter category.

Resolved File Spec

Select this option to compare wildcard or regular expression with the location where MicroStation’s reference file location algorithm finds the attachment.

Base File Name

Select this option to compare wildcard or regular expression with the file name stored in the reference file attachment element. Stored path information is ignored.

Common Filter Options

RefManager offers the following filter options for reference file names, reference file model names, reference file logical names and reference file descriptions.

String

Enter a wildcard or regular expression or semi-colon-delimited list of strings to match.

@listfiles

As of RefManager 8.9a, the fields File Name, Model Name, Logical Name and Description support the use of an “@” followed by the full path to a file containing file names, model names, logical names or descriptions of raster reference file attachments to be processed (one per line). These “@listfiles” honor the Type value described above. They can include wildcards or regular expressions.

Type

There are two methods of matching the specified “String” with a reference file attachment name, model, logical name or description:

Wildcard — use “*” to match any string and “?” to match any single character.

Regular Expression — See “Regular Expressions” section for details.

Your “Type” selection determines the “Insert” options that are available.

Insert

When “Type” is set to “Wildcard”, the “Insert” options are set to those available for “Wildcard” (which are shown below):

When “Type” is set to “Regular Expression”, the “Insert” options are set to those available for “Regular Expression” (which are shown below):

□ Case-sensitive

This is a simple yes/no choice: Should “abc” and “ABC” be considered different when matching file names? This is effective for both Wildcard and Regular Expression comparison.

□ Ignore Leading Spaces

This field only makes sense when “Base File Name” is selected for Compare above because the full file names will never have any spaces in them, nor will any individual component of a file name. With this button activated any leading spaces are trimmed off before the comparison is made.

□ Ignore Trailing Spaces

This field is only applicable when “Base File Name” is selected for Compare above because the full file names will never have any spaces in them, nor will any individual component of a file name. With this button activated any trailing spaces are trimmed off before the comparison is made.

Slot Number Filter

Select reference file attachments by slot number — the attachment’s position in MicroStation’s “References” dialog:

Enter a single slot number such as “1”, several slot numbers separated by commas “1, 3, 5, 7”, a range of slot numbers such as “1-5” or any combination of these.

Note: The “Slot” filter only applies to vector attachments. It does not apply to raster attachment layers.

Office Link Filter Options

Automatic link

Advanced Filter Options

Reference File Display

Reference File Missing

Self-Referenced

Technical Note: This filter option only applies to V8-style self-references.
V8-style self-reference attachments maintain their self-reference even if the DGN file is renamed. V7-style self-reference attachments (including existing self-references in V7 DGNs converted to V8 DGNs) refer to themselves by name, so the self-reference is broken if the DGN file is renamed.

Reference File Types

These filter settings allow you to restrict RefManager processing to vector attachments, raster attachments, Microsoft Office Importer links or any combination of the three.

Nested References

Since RefManager 8.14a, attachment filters are applied to nested reference attachments, not just direct reference attachments. Thus it is now possible to match a nested reference attachment (for modification) but not match the direct reference under which it is nested.

Chapter 7 — Modify Reference File Attachments

Introduction

V8 master files store information about each attached reference file in a type 100 element.

RefManager does not modify the reference files themselves, only the type 100 information stored in the master file for each attachment.

RefManager specializes in modification of type 100 elements.

Modify Reference File Attachments

When you select Modify Reference File Attachments from RefManager’s main dialog, the following dialog displays:

By default, no modification options are defined.

You can select one or more modification options in one or more categories — RefManager will perform the selected modifications on all selected master files and their attached reference files.

An asterisk (*) displays next to a category when at least one of its modification options has been activated.

Press {Clear} to reset one category’s options to Factory Defaults (no modification option will be active in that category).

Press {Clear All} to reset all category options to Factory Defaults (no modification option will be active in any category).

Modification Categories

Chapter 8 — Modify Reference Locations

Modifying Reference Attachment Names and Paths

RefManager is often used to update reference attachments’ stored paths when projects are moved from one folder to another or from one server drive to another. It is also common to use RefManager to change the file name stored in a reference attachment, often as a result of users creating files with the wrong names and later renaming them.

RefManager’s file name modification tools have evolved to encompass logical names, descriptions and, in V8, model names too — all of these are strings associated with a reference file attachment.

All of these reference file attachment components can be manipulated with RefManager.

RefManager allows you to treat attachment folder paths, base file names, extensions, logical names and descriptions as simple strings of characters. You can insert characters, substitute characters or entirely replace existing characters in any of these strings. All RefManager editing Methods described in this section work exactly the same way with folder paths, base file names, extensions, logical names and descriptions.

Examples of common reference file name modifications are provided in the “Frequently Asked Questions” section of this User’s Guide.

Modifying Reference File Attachment Location

You can use the powerful features in this dialog to modify reference file attachment file paths, names, extensions, logical names, descriptions and even model. You can even modify similar aspects of Microsoft Office Importer links to XLS or DOC files.

Component

It is a good idea to read this entire section before choosing the Component you will use. This is because MicroStation V810 has so many possible reference attachment name/path combinations — far more complexity than in MicroStation V7.!Unexpected End of Formula

The fundamentals of renaming and repathing with RefManager

The “Component:” option button controls exactly which part of the reference attachment or Microsoft Office importer link RefManager will modify. For example, you might want to change just the stored file name, just the path (stored location), just the logical name or model — or even which range of Excel cells are linked to the DGN file by a Microsoft Office Importer link.

If you’re already familiar with all this and only want a quick reference, you can read just the “Technical Description” sections for each Component, when available.

Unlike V7, a V8 reference file attachment’s base file name and full path are stored separately in V8’s new type 100 reference file attachment elements. [For more information about this, see the “Modify Saved Paths” section in this document.]

RefManager can modify either the attachment’s base name, relative path or its full/absolute path (or all of these) in a single processing run.

Which reference attachment types each Component applies to

RefManager supports three types of reference file attachments: Vector reference attachments (such as DGN files), raster reference attachments (such as TIFF files) and Axiom’s Microsoft Office Importer links to XLS or DOC files. This table tells you which of those reference types each Component applies to:

Choosing the Right Component

As a general rule, use the most specific Component you can for whatever it is you want to change. For example, if you just want to change the file name stored in the reference attachment, use either the File Name or File Name + Extension Component, not Full File Spec. Full File Spec could do the job too but it has subtle characteristics that make the more specific Components a better choice.

Technical Note: In this example, File Name or File Name + Extension are indeed preferable. The reason could be important to users whose files do not have key 31 saved — because Full File Spec won’t do anything in this case but File Name will change key 3 in this case.

Full File Spec

Full File Spec applies to vector references, raster references and Microsoft Office Importer links.

Full File Spec is designed for advanced users. When dealing with vector reference attachments, it primarily applies to the contents of key 31. If key 31 is undefined, Full File Spec does nothing but if key 31 is defined, Full File Spec changes it and synchronizes the file name (if changed) with the file name in key 3.

Full File Spec is very useful for raster reference attachments and Microsoft Office Importer links. It is only marginally useful for vector reference attachments.

How Full File Spec works on raster reference attachments and Microsoft Office Importer links

Using Full File Spec to modify the path and file names stored in raster references and Microsoft Office Importer links is very straightforward. Full File Spec applies to the path, file name and extension stored in these types of references/links so it’s very useful if you need to make a change that must involve more than just one of those components. For example, let’s say you have two different reference files of the same name but in different folders and you want to rename one of them to handle that ambiguity. You can do that with Full File Spec because you can include the path in your replacement, which allows you to isolate the exact reference you want to change, leaving the other reference of the same name (but different path) unchanged.

How Full File Spec works on vector reference attachments

Here’s a breakdown of how “Full File Spec” works:

1. Changes key 31 (only when key 31 exists).
2. When key 31 path is changed, removes all but file name+extension from key 3.
3. When only file name+extension (not path) in key 31 is changed, file name+extension in key 3 is changed to match the new file name+extension in key 31.

Use Full File Spec as a means of modifying key 31 while simultaneously removing any of the relative path information and configuration variables (if any) from key 3.

If, after reading the above, you are not totally certain Full File Spec is exactly the Component you need, it probably is not the Component you need. Please check out Full File Spec’s cousin, Relative File Spec.

Tip for previous users of RefManager for V7: If you are used to Full File Spec in RefManager V7, do not expect Full File Spec in RefManager V8 to be the same — the differences in V7 vs. V8 reference attachments make each RefManager version’s “Full File Spec” tool very different.

Full Path

Full Path works like Full File Spec but ignores file name and extension.

Full Path applies to vector references, raster references and Microsoft Office Importer links.

In this context, “Full Path” includes a drive letter and subfolders preceding a file name. For example, “C:\MyProject\” in: “C:\MyProject\MyFile.dgn”.

To change an attachment’s Full Path, select the “Full Path” component and specify what you want to change “From” and what you want to change “To”.

For example:

From:
C:\OldProject\

To:
N:\NewProject\

Note: If the MicroStation configuration variable MS_DISALLOWFULLREFPATH = 1 in your workspace, full paths are not guaranteed to be present in your attachments – the full path might not be saved (no full path exists, so nothing is there to be modified).

Relative File Spec

Relative File Spec applies only to vector reference attachments.

How Relative File Spec works on vector reference attachments

Relative File Spec works on data stored in key 3, which is always at least file name+extension and sometimes contains a relative path, which is a path to the reference file relative to the master file. Sometimes that relative path consists of or includes a configuration variable in the form of the configuration variable name followed by a colon.

Technical Description: Relative File Spec works on the entire content of key 3 (relative path and file name+extension).

Here is what Relative File Spec does exactly:

1. Changes key 3.
2. When key 3 path is changed, removes key 31.
3. When key 3 file name or extension only (not path) are changed, file name+extension (both) in key 31 are changed (synchronized) to match the new file name+extension in key 3. Does not create key 31 if key 31 is not already defined.

Relative Path

Relative Path applies only to vector reference attachments.

Select this component specify a new subfolder path. This is handy for changing the folder or relative path for a reference file. For example:

From:
OldProject\

To:
NewProject\

Also select the Relative Path component to insert or change a MicroStation configuration variable. For example:

From:
MY_PHASE1:

To:
MY_PHASE2:

Note: MicroStation saves relative paths and configuration variables with the base file name (attachment string linkage 3), not with the full file path (attachment string linkage 31). “Relative Path” is listed as a separate file name component to handle the special cases of relative paths and configuration variables. For more information about this, see “Modify Saved Paths” section in this document.

Technical Description: Relative Path works on the path stored in key 3. If it changes key 3, it removes key 31.

File Name + Extension

File Name + Extension applies to vector references, raster references and Microsoft Office Importer links.

Select this component to change or replace a reference file attachment file name and its extension. For example, “MyFile.dgn” in: “C:\MyProject\MyFile.dgn”.

To change the file name “Border.dgn” to “NewBorder.bdr” select the component “File Name + Extension” and enter:

From:
Border.dgn

To:
NewBorder.bdr

Technical Description: File Name + Extension changes the data in both key 3 and, if defined, key 31.

File Name Only

File Name Only applies to vector references, raster references and Microsoft Office Importer links.

Select this component to change or replace a reference file attachment file name. In this context a “file name” does not include a folder path or extension. For example, “MyFile” in: “C:\MyProject\MyFile.dgn”.

To change the file name “Border.dgn” to “NewBorder.dgn” select the component “File Name Only” and enter:

From:
Border

To:
NewBorder

Technical Description: File Name Only changes the data in both key 3 and, if defined, key 31.

Extension

Extension applies to vector references, raster references and Microsoft Office Importer links.

A file name extension is the final period followed by (typically) three characters. For example, “.dgn” at the end of “C:\MyProject\MyFile.dgn”.

To change the extension “.dgn” to “.001”, select the component “Extension” and enter:

From:
.dgn

To:
.001

Technical Description: Extension changes the data in both key 3 and, if defined, key 31.

ProjectWise Components

RefManager’s ProjectWise components apply only to reference attachments stored in ProjectWise and which ProjectWise is managing via a logical set. You must be logged into ProjectWise using MicroStation’s iDesktop ProjectWise integration in order to use RefManager’s ProjectWise Components.

Introduction to ProjectWise “logical sets”

For an introduction to ProjectWise’s logical sets, see this web page:
http://docs.bentley.com/en/PWExplorer/pwehelp77.html

For information on how to create ProjectWise’s logical sets, see this web page:
http://docs.bentley.com/en/PWExplorer/pwehelp219.html

Safety Tip: Turn on “{Attachments} | Attachment Types | “Reference is from ProjectWise” if you are processing ProjectWise references. This prevents the processing of any other types of reference attachments, which means your reports won’t waste your attention by mentioning non-ProjectWise attachments and your modifications won’t be accidentally applied to non-ProjectWise attachments.

Log Into the Right ProjectWise Datasource Before Starting Your RefManager Job.

Be sure you are logged into the same ProjectWise datasource as the files you plan to process with RefManager. If you are logged into the wrong datasource, the most common symptom is that RefManager will be unable to resolve (find) your files in ProjectWise.

If you are not logged into any ProjectWise datasource (with MicroStation’s iDesktop ProjectWise integration), the symptoms will be similar but being logged into the wrong datasource is potentially worse because RefManager could, unlikely as it seems, actually find a few references that match anyway.

Can I create broken ProjectWise links with these “ProjectWise…” Components?

No, you cannot. The RefManager Components whose names start with “ProjectWise” will not change attachments to point to non-existent ProjectWise files. They will only change them to point to ProjectWise files (based on the output URL) that actually exist. This applies to ProjectWise URL, ProjectWise Doc Path, ProjectWise Doc Name and ProjectWise Doc Version — all of RefManager’s ProjectWise Components.

How the “ProjectWise…” Components Work

The Components whose names begin with “ProjectWise” work on ProjectWise “From” and “To” URLs but those URLs are not stored in MicroStation raster and vector reference attachments. RefManager has to look up each file in ProjectWise based on its working copy file name+folder and find the corresponding URL for each file in ProjectWise.

When making the user’s modifications, these Components then do this in reverse for the “To:” (output/destination) URL and write the modified working copy file name+folder back into the reference attachment element.

For Microsoft Office Importer links, it’s much simpler and direct because Microsoft Office Importer actually stores the ProjectWise URL in each link in the design file.

ProjectWise Document URL

Use this to change a ProjectWise reference attachment to point to a different ProjectWise reference file using their ProjectWise URLs.

This component applies to vector references, raster references and Microsoft Office Importer links.
Select this component to change or replace any part of the ProjectWise URL but note that the final URL must actually match a valid ProjectWise URL (a URL for a file that actually exists.) For example, “MyProject\MyFile.dgn” in: “pw:server\datasource\MyProject\MyFile.dgn”.

Important Note: It is not possible to change the ProjectWise server name nor the datasource with this keyword as RefManager only works on one datasource at a time.

ProjectWise Document Path

This is just like ProjectWise URL but it only deals with the path portion of the URL.

Important Note: It is not possible to change the ProjectWise server name nor the datasource with this keyword as RefManager only works on one datasource at a time.

ProjectWise Document Name

This is just like ProjectWise URL but it only deals with the document name portion of the URL. Note that document names in ProjectWise (and thus in the ProjectWise URLs) do not necessarily have to match the actual names of the files themselves and may not even have file extensions.

ProjectWise Document Version

Use this to match and change the ProjectWise version control system version number of a ProjectWise reference attachment.

Logical Name

Logical Name applies to vector and raster reference attachments.

This attachment component is the user-defined logical name specified at the time a reference is attached.

To change a logical name from “Border” to “Legal”, select the “Logical Name” component and enter:

From:
Border

To:
Legal

When a modification would create a duplicate logical name, RefManager skips the change and records the error in the report file.

Note: The maximum Logical Name length with MicroStation/J and earlier is 21 characters. The V8 limit is 90 characters (when entered through MicroStation’s Attach Reference dialog). MDL can handle up to 95 characters in a logical name with MicroStation V8.

Note: Logical names are not required in MicroStation V8, but if defined they must be unique amongst a model’s attachments.

Description

Description applies to vector and raster reference attachments.

This attachment component is the user-defined description specified at the time a reference is attached.

To replace one description with a new description, select the “Description” component and enter a new description, such as:

From:
As Built 2005-03-15

To:
As Built 2005-04-15

Note: The maximum Description length with MicroStation/J and earlier is 40 characters. The V8 limit is 250 characters (when entered through MicroStation’s Attach Reference dialog). MDL can handle up to 255 characters in a Description with MicroStation V8.

Model Name

Model Name applies only to vector reference attachments.

This attachment component is the reference file attachment model attached to a parent master file.
In V7, reference files are attached to master files. In V8, models are attached to models (even if both reference and parent models are the default model).

Modifying an attachment’s “model” actually results in the display of a different model from the same reference file, if one exists. Modifying the model stored in the attachment (an element in the master file) does not rename the model in the reference file itself.

For example, in the following illustration, the master file has a reference file attachment that points to the “Default” model in “MyRef.dgn”. If the model name in the master file’s attachment element were changed from “Default” to “Foundation”, the attachment would then link to an entirely different model (in the reference file).

To replace the “Default” model with “Foundation”, select the component “Model Name” and enter, for example:

From:
Default

To:
Foundation

Sheet NameSheet Name applies only to Microsoft Office Importer links.

Sheet Name changes the name of the Excel sheet (worksheet) to which a Microsoft Office Importer link in a design file points.

Top-Left Cell, Bottom-Right Cell

Top-Left Cell and Bottom-Right Cell apply only to Microsoft Office Importer links.

Top-Left Cell and Bottom-Right Cell change the starting and ending cells which define the range of a Microsoft Office Importer link from a design file to an Excel spreadsheet.

Method

Editing Methods in RefManager for V8

The three substitution methods require input to be in the form:

From:
old-string

To:
New-string

If old-string is found it will be replaced by new-string.

Case–insensitive Substitution

The selected component is searched for the “From” string and replaced with the “To” string, ignoring upper and lower case differences. “Case–insensitive Substitution” is the default.

Case–sensitive Substitution

The selected component is compared with the “From” string and replaced with the “To” string only if there are no upper/lower case differences.

Replace Entire String

The selected component will be replaced by the contents of the “To” field. The “From” field is not needed and is therefore disabled.

Prefix New String to Existing String

When selected, anything entered in the “To” field will be inserted at the beginning of the corresponding component.
As an example, this editing method allows you to insert a configuration variable.

The “From” field is not needed and is therefore disabled.

Regular Expression Substitution

The corresponding component string is compared against the regular expression your specify in the “From” field. If the component matches the “From” expression, the matching component substring is replaced by your entry in the “To” field.

For example, in the following example the “From” string is a regular expression which will match any series of alphabet characters followed by a number. When the selected component matches the “From” string, the matching substring will be replaced by the “To” string “My New String”:

From:
[a-zA-Z]+:d

To:
My New String

The Regular Expression Substitution editing method (as in the preceding example) can be used in the “From” field for any component.

To remove a string which matches a regular expression, enter a blank as the “To” string. The following example is similar to the preceding example, except any string which matches the regular expression will be replaced with nothing (empty string):

From:
[a-zA-Z]+:d
To:

Note: MicroStation users may be familiar with the Bentley implementation of regular expressions, characterized by the shortcuts:

If these shortcuts are present in your regular expression, RefManager uses the Bentley MDL regular expression functions.

However, RefManager supports advanced regular expression features not supported by Bentley MDL regular expressions. Specifically:

When these advanced regular expression features are detected in your regular expression, RefManager automatically assumes you want to replace the existing string with a new string built using segments. For example, the regular expression substitution defined by the following “From:” and “To” entries:

From:
\([A-Z]*\)\([0-9]*\)

To:
\2\1

will entirely replace file names such as “XYZ123” with “123XYZ”.

When you include these advanced Axiom features in your regular expression, RefManager automatically switches from “substitution” mode (default for regular expressions) to “replace entire string” mode.

See the “Regular Expression” section of this document for more information about Bentley and Axiom regular expression features.

From

The “From” field is used to specify an existing string (folder path, file name, extension, logical name, etc.) which you want to change.

The interpretation of the “From” field depends upon the selected editing Method.

For examples, see the “Methods” section in this chapter.

To

The “To” field is used to specify a new string (folder path, file name, extension, logical name, etc.) which you want to replace whatever the “From” string matches.

The interpretation of the “To” field depends upon the selected editing Method.

{Browse}

The {Browse} button helps you fill in the “From” and “To” fields.

{Browse} allows you to initialize the “From” or “To” field by selecting an existing file on a local or server drive.

The initialization value returned is dependent upon the selected Component.

For example, if the selected Component is “Extension”, only the selected file’s extension is inserted into the “From” or “To” field. If the selected Component is “Base File Name”, the selected file’s base name is inserted into the “From” or “To” field.

The behavior of the {Browse} button is dependent upon the selected Component.

The {Browse} button is disabled when you select a Component which doesn’t exist outside the MicroStation environment (logical name, description, model name).

{Match}

The {Match} button helps you fill in the “From” and “To” fields.

{Match} allows you to initialize the “From” or “To” field by selecting an existing reference file attachment from any master file.

The initialization value returned is dependent upon the selected Component.

For example, if the selected component is Extension, only the selected reference file’s extension will be inserted into the “From” or “To” field.

The behavior of the {Match} button is dependent upon the selected Component.

{Test}

The {Test} button allows you to simulate and preview file name modifications without changing any file.

RefManager displays a report which summarizes the results of the modifications you defined.

This is a fast and easy way to rehearse changes before applying them permanently to your project files.

Changes are applied only to the active design file's attachments.

RefManager always creates a backup of your master files, so you can always revert after making an unintentional change. But the {Test} button is completely safe (no files are touched) and fast.

After using the {Test} button to confirm your modification results are exactly what you want, press {Start} on RefManager’s main dialog to process your actual project master files.

Power User Tip (@Listfiles)

Perhaps you want to change multiple reference file names in multiple project master files. You could define a “From” and a “To” change for each individual reference file name, but there is another way to define multiple modifications for a single component which might work better for you.

Just create a file containing your From|To pairs, one pair per line, delimited by “|”.

For example, let’s say C:\MyProject\FromTo.txt contains:

Enter the full path to C:\MyProject\FromTo.txt in the “From” field, preceded by “@”:

From:

@C:\MyProject\FromTo.txt
To:

[When “@” is detected at the beginning of the “From:” field, the contents of the “To:” are ignored.]

Tip: When the “Regular Expression Substitution” editing method is selected, the “From” half of the pair can be a regular expression.

Chapter 9 — Modify Saved Paths

Introduction

There are some important differences between V7 and V8 reference file attachments which are related to RefManager’s Modify Saved Path and Reference Location options.

V7 Reference File Attachment Elements

Since the days of Intergraph, a V7 reference file attachment element (type 5 level 9 elements) has included space for a reference filename up to 64 characters. Into that space, you could insert:

Note: MicroStation/J and earlier do not support relative reference file attachment paths – this capability was introduced in V8.

V8 Reference File Attachment Elements

The type 5 level 9 reference file attachment element is not used in V8.

V8 reference file attachments are represented by type 100 elements.

The attachment filename string is stored as a linkage appended to the end of a type 100 (up to 255 characters). This version of the file name is portable – it does not include a drive letter. It may include a relative path or just the file name.

The attachment’s full path string is optionally stored as a linkage appended to the end of a type 100 (up to 383 characters). This version of the filename is not guaranteed to be portable. If a project is moved to a new folder or a new drive letter, the full path will no longer properly represent the file’s path and drive.

MS_DISALLOWREFFULPATH

The following summarizes the impact of this important new configuration variable:

Note: As of MicroStation 8.5, MS_DISALLOWREFFULLPATH=1 apparently only applies to vector attachments — it appears full paths are always stored in raster reference file attachment (type 90) elements.

Note: An attachment’s full path is stored as a linkage at the end of V8’s new type 100 reference file attachment elements. If the full path linkage exists, RefManager’s reports include:

V8 DGN VECTOR REF #1: C:\MyRefs\Border.dgn, 2D Model: "Default"
Attached File's Location: C:\MyRefs\Border.dgn
Saved Full Path: c:\MyRefs\Border.dgn

Note that the attached file’s location may not match the saved full path.
If the full path linkage does not exist, indicating the full path is not saved, RefManager’s reports include:

V8 DGN VECTOR REF #1: C:\MyRefs\Border.dgn, 2D Model: "Default"
Attached File's Location: C:\MyRefs\Border.dgn
Save Full Path: (not saved)

As of this writing, MicroStation’s GUI does not indicate whether or not the full path is saved for an attachment.
Without RefManager, the presence or absence of the full path linkage only becomes apparent when project files are moved to a new folder or drive – the full path represented in the linkage might not exist. To avoid surprises, run RefManager’s Reference File Attachment Report before moving your V8 project files.

V8’s References Dialog

MicroStation displays the reference’s base filename in the References dialog:

The full path pops up when you hold your mouse over the reference’s base filename:

Note: The full path popup represents the location where MicroStation found the reference file. The full path may or may not be stored in the type 100.

V8’s Attachment Settings Dialog

MicroStation displays both the reference’s base filename and full path in the Attachments Settings dialog:

Note: The full path displayed in the Attachment Settings dialog represents the location where MicroStation found the reference file. The full path may or may not be stored in the type 100.

Your Attachments Might Contain...

Because the reference’s base filename and full path are stored separately in type 100 elements, it is possible for the following combinations to exist in a V8 reference file attachment element:

Note: When MS_DISALLOWREFFULLPATH=1 at the time a reference file is attached, the reference’s full file path is not saved in the type 100 reference file attachment element. As of MicroStation V8.5, there is no toggle to “Save Full Path” (like MicroStation/J).

Note: MicroStation V8.5.2.35 vector attachment behavior:

Changing MS_DISALLOWREFFULLPATH from 0 to 1 does not remove an existing string linkage key 31 attribute (full path) from type 100 elements, but key 31 attribute (full path) is not thereafter created for new attachments.

Because MS_DISALLOWREFFULLPATH is defined in a user’s workspace, full paths might be saved during one MicroStation session but later removed by someone working at a different workstation.

Note: The full path is never saved in a type 100 element when a file is attached to itself. The location of the “master” file is always known for self-references — there is no need to waste space to save the full path. However, the master file’s model name is required and is stored in string linkage key 21 attribute for each self-referenced attachment.

Note: The ability to save a relative path can be disabled by adding the following to each user’s workmode.cfg file:
_USTN_CAPABILITY < -CAPABILITY_REF_SAVE_PATH_REL

Path Operations

Familiarity with the preceding sections about MicroStation V8’s new type 100 reference file attachment element is a prerequisite for understanding RefManager’s Path Operations. If you haven’t read the preceding sections, please do so now.

Note: As of version 8.7a RefManager can modify a base file name, relative path or full path even when MicroStation cannot locate the reference file on disk. However, RefManager’s “Saved Paths” feature cannot add nor update the saved full path (key 31) if the reference file cannot be found by MicroStation.

Note: RefManager’s Path Operations apply to type 100 vector attachments (not type 90 raster attachments).

Save Full Path

As explained in preceding sections, a reference’s base filename, such as “MyReference.dgn”, and its full path, such as “C:\Project\MyReference.dgn”, are stored separately in V8’s new type 100 reference file attachment element.

RefManager’s Save Full Path operation does not touch the reference’s base filename — it adds the full path if it does not already exist.

If your attachments display in red (missing) in MicroStation’s References dialog, you will need to temporarily add your reference file folder (or folders) to the definition of MS_RFDIR before performing RefManager’s Save Full Path operation. After RefManager Save Full Path processing is complete, you can restore MS_RFDIR to its original value.

Note: If you direct RefManager to save an attachment’s full path, it will attempt to temporarily set MS_DISALLOWREFFULLPATH = 0. RefManager honors your MicroStation configuration settings and will notify you in the event it does not have sufficient privilege to temporarily set MS_DISALLOWREFFULLPATH = 0.

Save Relative Path

This option adds the relative path to an attachment’s base filename.

The full path is not affected by Save Relative Path processing.

If your attachments display in red (missing) in MicroStation’s References dialog, you will need to temporarily add your reference file folder (or folders) to the definition of MS_RFDIR before performing RefManager’s Save Relative Path operation. After RefManager Save Relative Path processing is complete, you can restore MS_RFDIR to its original value.

Note: When a reference file resides in the same folder as the master file to which it is attached, there is no “relative” path.

Save Base Filename Only

This option removes the relative path and full path from type 100 reference file attachment elements.

Note: The “Save Base Filename Only” option also removes configuration variables from attachment filenames. For example, “MYCONFIGVAR: MyReference.dgn” will be replaced by “MyReference.dgn”.

Note: This option can temporarily break links to your reference files, but connections can be immediately restored by adding your reference file folder or folders to the definition of the MS_RFDIR config variable.

Chapter 10 — Modify Level Display

Introduction

Design details can be tailored for specific disciplines or specific recipients by turning on or off the display of specific levels. For example, an interior decorator doesn’t need to see a building’s electrical wiring details. Discipline-specific levels can be turned on or off when displaying the design in MicroStation or Bentley View or prior to plotting.

Master file levels can be displayed or not and the same is true for levels in reference file attachments. RefManager specializes in the manipulation of reference file level display.

To make things more interesting, a particular attachment level can be displayed in view 1, but not in view 2.

If your project uses 10, 20, 30 or 100 reference files and 10, 20, 30 or 100 different levels in 2, 3 or 8 different views, the possible combinations of displayed and undisplayed levels are staggering.

RefManager allows you to control and standardize the display of levels in project reference file attachments for one or all project master files.

You can save RefManager settings for re-use over and over to create discipline-specific sheet files or snapshots of project milestones as your project progresses.

How to Change Attachment Level Display

RefManager allows you to turn on or off reference file level display for each of MicroStation’s 8 views or for all 8 views at once.

RefManager first turns the specified levels off, then turns the specified levels on (working from top to bottom, views 1-8).

Levels to be processed can be specified with:

• Level number lists, for example: 3, 7-12 (not recommended for V8 – see note below).
• The name of a file that contains one level name or wildcard per line (not enclosed in quotes). Precede the filename with the ‘@’ symbol. For example:
  @c:\mylevels.lstEach quoted, comma-delimited level list is limited to 255 characters. If your level list exceeds this, use a wildcard or create a file that contains one level name per line.
• V8 only: A quoted, comma-delimited list of level names, such as “Electrical”, “Border”
• V8 only: Level name wildcards, for example:
  CAP*, AB?D

V8 Note: A level number is not guaranteed to uniquely identify a V8 level. It is possible for the same level number to be assigned to one level name in a master file and to different level names in one or more attachments. If you prefer to work with level numbers, test on a single project file before processing *.dgn.

How to Select Attachment Levels to be Modified

Click {Add} to define a new level display modification.

Click the {Select…} button to select a list of levels to be modified. This can save a great deal of typing and guarantees each level name is spelled correctly.

Display master file levels

RefManager displays all master file levels by default. To clarify which levels are only present in attachments, uncheck this option.

Display reference levels

RefManager displays all attachment levels by default. To clarify which levels are only present in the master file, uncheck this option.

Append to previous selection

Enable this option to append your selection to any pre-existing level list.

Overwrite previous selection

Enable this option to replace any pre-existing level list.

File

The File menu allows you to attach or unload a level library.

This allows you to view and select levels that are not used in the active master file and its attachments.

Level Display Modifications

For each list of levels, you can turn display on or off for each view — and you can change Global Display and Global Freeze.

You can perform different modifications for each level, if you wish, or you can specify a wildcard to represent multiple levels and activate the same level display settings for all matching levels at once.

The level display modifications you define can be saved with Settings | Save As… and re-used over and over.

Process nested references.

Use this to apply the changes defined in this category to nested references that are within the current attachment filter.

{Match…}

If you have a “perfect” example attachment where all level display settings are just the way you like them, click {Match…} to select that file. Rules will be automatically generated from the level display settings in the selected file.

Chapter 11 — Modify Level Symbology

Introduction

When a reference file is attached to a master file, the attached file can be displayed with its original symbology or new symbology.

New symbology can be defined for the attachment and saved in the master file without modifying the reference file itself.
In the following example, the reference file “Reference.dgn” is attached to the master file “Master.dgn”. The attachment is displayed using the symbology stored in Reference.dgn.

MicroStation’s Level Manager can be used to modify the symbology of both master file and reference attachments. An attachment’s level symbology can be modified at any time by clicking on its color, style or weight in MicroStation’s Level Manager box.

But what if you need to adjust the level symbology for multiple attachments in multiple project files? This can be tedious and error prone. Fortunately, you can use RefManager to change level symbology for all attachments in all project files in one processing run.

If you are dealing with large numbers of master files and reference files, manual adjustment of attachment level symbology is tedious and error prone.

To further complicate the matter, symbology can be different in each view!

Fortunately, RefManager can handle all of this for you, on projects of any size.

How to Modify Attachment Level Symbology

RefManager needs to know which levels to modify. With MicroStation/J and earlier this was pretty simple — level selection was limited to levels 1 – 63.

The story is different with V8 files. A level number may or may not exist in a V8 file, and even when it does, a level number is not guaranteed to uniquely identify the same level in multiple files. Thus, V8 levels should be specified by name.

So, RefManager for V8 allows you to create lists of level names to process.

Levels to be processed can be specified with:

• A quoted, comma-delimited list of level names, such as “Electrical”, “Border”
• Level name wildcards (unquoted), for example: CAP*, AB?D
• The name of a file that contains one level name or wildcard per line (not enclosed in quotes). Precede the filename with the ‘@’ symbol. For example: @c:\mylevels.lst
• Level number lists, for example: 3, 7-12 (see warning below).

Warning: A level number is not guaranteed to uniquely identify a V8 level. It is possible for the same level number to be assigned to one level name in a master file and to different level names in one or more attachments. If you prefer to work with level numbers, test on a single project file before processing *.dgn.

{Match...}

If you have a “perfect” example attachment where all level symbology settings are just the way you like them, click {Match...} to select that file. Rules will be automatically generated from the level display settings in the selected file.

How to Select Attachment Levels to be Modified

Click {Add} to create a new row. Enter one or more quoted, comma-delimited level names or press {Select...} to select levels from a list.

Define new ByLevel symbology or new symbology overrides for the levels in the currently highlighted row.
Only the checked options will be applied. For example, you can modify only the ByLevel color without changing the style or weight – to do so check “Color” and uncheck “Style” and “Weight”.

You can define different ByLevel symbology or symbology override changes for each row.

Click {Remove} to delete a row from the list.

Select “Settings | Save” or “Settings | Save As...” from RefManager’s main dialog to save your level modification commands.

{Select...}

Use your mouse to select the levels to be modified.

{Shift-Click} to select a range of levels.

{Ctrl-Click} to select or de-select an individual level.

Sequence of Modification Commands

RefManager applies level symbology modification commands in the order they appear in the dialog box (top to bottom).

Use the {Up} and {Down} buttons to change the position of a row in the list.

New ByLevel Symbology

RefManager allows you to redefine the ByLevel symbology with which attachment elements are displayed (only while attached to a master file). The reference file itself is not modified – the new ByLevel symbology settings for the attachment are stored in the master file.

The options are Color, Style, Weight and Line Style Scale.

Color, Style and Weight are self-explanatory.

Line Style Scale refers to the MicroStation reference level property named “Scale factor:”, as you can see in this image:

MicroStation’s Level Manager’s Level Properties Box, Styles tab, showing “Scale factor:” property of a reference attachment’s level.

The way MicroStation works, it is only possible to change this value if the level is set to a custom linestyle already. So if this level is not set (either through MicroStation or RefManager) to a custom linestyle, changes to its scale factor will not be saved in the reference level’s settings.

New Symbology Overrides

RefManager allows you to redefine the Level Symbology overrides used to display attachment elements (only while attached to a master file). The reference file itself is not modified — the new level symbology overrides for the attachment are stored in the master file.

The options are Color, Style, Weight and Line Style Scale.

Symbology Overrides are the symbology settings used in place of element symbology when the following View Attribute is selected:

Turn level symbology on or off for each view

Level Symbology overrides are activated by enabling the “Level Symbology” attribute for a view:

When the “Level Symbology” attribute is enabled for a view, elements are not displayed with their own symbology. Instead, each element is displayed with the level symbology overrides defined for the element’s level.

RefManager allows you to enable or disable the “Level Symbology” attribute for each view.

When you select “Turn On” for a view, “Level Symbology” is activated and element display will be controlled by the level symbology overrides defined for the element’s level.

When you select “Turn Off” for a view, “Level Symbology” is deactivated for that view – each element will display with its own symbology (which might be ByLevel symbology).

“No Change” does not change the existing “Level Symbology” attribute for the view.

Note: When modifying Level Symbology, RefManager will enable Global Display for a level if at least one view is turned on for that level during RefManager processing.

Process nested references.

Use this to apply the changes defined in this category to nested references that are within the current attachment filter.

Chapter 12 — Modify Raster Settings

Modify Raster Attachment Settings

You can use RefManager to change or standardize one or more raster attachment settings for one or more raster attachments in one or more of your master files.

You can process an entire project with application of RefManager’s Modify options, or use RefManager’s “Design File” selection and “Filter” features to limit processing to a specific raster attachment.

Match

Click on {Match…} to initialize Raster Settings from a specific raster attachment.

RefManager for V8 “Modify Reference File Attachments: Raster Settings

These raster settings are defined in MicroStation Help under “Raster Manager dialog box”.

Chapter 13 — Modify Raster Transformations

Transform Raster Attachments

You can use RefManager to apply one or more transformations to one or more raster attachments in one or more of your master files.

You can process an entire project with application of RefManager’s “Modify” options, or use RefManager’s “Design File” selection and “Filter” features to limit processing to a specific raster attachment.

RefManager’s “Modify Reference File Attachments: Raster Transformations” box

These raster settings are defined in MicroStation Help under “Modify Raster”.

Chapter 14 — Modify Vector Settings

Modify Vector Attachment Settings

You can use RefManager to change or standardize one or more vector attachment settings for one or more vector attachments in one or more of your master files.

You can process an entire project with application of RefManager’s “Modify” options, or use RefManager’s “Design File” selection and “Filter” features to limit processing to a specific vector attachment.

RefManager’s “Modify Reference File Attachments: Vector Settings”

These vector settings are defined in MicroStation Help under “Raster Manager dialog box”.

Note about “Display Overrides” setting: This setting appears when RefManager is run in MicroStation XM or V8i. It does not appear when RefManager is run in MicroStation V8 2004 Edition (V8.5).

Process nested references.

Use this to apply the changes defined in this group of settings (those above the horizontal line) to nested references that are within the current attachment filter.

Match

Click on {Match…} to initialize Vector Settings from a specific vector attachment.

Chapter 15 — Modify Vector Transformations

Transform Vector Attachments

You can use RefManager to apply one or more transformations to one or more vector attachments in one or more of your master files.

You can process an entire project with application of RefManager’s “Modify” options, or use RefManager’s “Design File” selection and “Filter” features to limit processing to a specific vector attachment.

RefManager for V8 “Modify Reference File Attachments: Vector Transformations”

Scale

Scaling factors greater than 1.0 increase the displayed size of an attachment.

Scaling factors less than 1.0 decrease the displayed size of an attachment.

Attachments are scaled about their origin.

Rotate

Rotation angles are specified in degrees. Positive angles result in counterclockwise rotation, negative angles result in clockwise rotation.

For 2D models only Z rotation is applied.

Transform boundaries

Use this option when you want scaling and rotation processing to include clipping boundaries and voids.

Clipping

Shift

Use these options to shift clipping boundaries and masks. The primary use for using this is when you are shifting the origins and need to move the mask or void along with the image.

For 2D models only the X and Y values apply.

Remove clipping boundary

Select this option to remove the clipping boundary.

Remove clipping masks

Select this option to remove all masks (voids).

Clip Back/Clip Front [V8 only]

Use this option to shift the front and/or back Z clipping planes. Shift is specified in UORs.

Mirroring

Mirror Horizontal

This inverts the image of the reference file, about the reference file’s origin, top to bottom.

Mirror Vertical

This inverts the image of the reference file, about the reference file’s origin, left to right.

Shift Origins

Master Origin Shift

Shift the master file’s coincident point relative to the reference file’s origin.

Shifts are specified in UORs.

Positive values shift the master file left/down. Negative values shift the master file right/up.

For 2D models only the X and Y values apply.

Note: Clipping boundaries will also move when you perform “Master Origin Shift”.

Reference Origin Shift

Shift the reference file’s coincident point relative to the master file’s origin.

Shifts are specified in UORs.

Positive values shift the reference file left/down. Negative values shift the reference file right/up.

For 2D models only the X and Y values apply.

Note: Clipping boundaries will not move when you perform “Reference Origin Shift”.

Transformation Sequence

RefManager performs transformations in the following sequence:

1. The attachment is scaled.
2. The attachment is rotated.
3. The attachment is shifted/moved.

Vector transformations can be a tricky thing. If you need any help, please call Axiom Support at 727-442-7774 or email Support@AxiomInt.com.

Chapter — Modify Office Link Settings

Overview

These settings are used to modify links to Excel spreadsheets and Word documents created in design files by Axiom’s Microsoft Office Importer. To edit these links, RefManager requires that you have Microsoft Office Importer installed and properly licensed. If you do not, you will get an appropriate error and RefManager will skip Microsoft Office Importer links.

Automatic Link

This is an important link property for Microsoft Office Importer users. If a link has this turned on, it is known as an “Automatic” link. tells Microsoft Office Importer to update that design file with any updated information from the linked XLS or DOC file whenever the design file is opened.

If a link has this turned off, the link is known as a “Manual” link. Microsoft Office Importer will only update the link when the user explicitly asks it to.

Update Links

Update all Microsoft Office Importer links

Use this to force every filtered Microsoft Office Importer link in every processed design file to be updated from its source Excel spreadsheet or Word document. As always, links that are already up to date (based on modification date of the source file) will not be updated.

Update only modified Microsoft Office Importer links (default)

Use this to update only those Microsoft Office Importer links that RefManager modifies during this job. This has an important side effect: The update ensures that the user hasn’t made any invalid changes to the link, such a pointing to a file that doesn’t exist, a sheet name that doesn’t exist, etc.

Keeping this on is generally the safest way to operate, particularly if you’re fixing broken links due to linked XLS or DOC files being renamed or moved.

This is on by default so that links will be updated after modification. Doing so ensures the Microsoft Office Importer link changes you made with RefManager were valid. It also keeps the design files up to date.

Don’t update Microsoft Office Importer links

Use this if you don’t want to update your links during RefManager’s processing — even those links RefManager modifies.

You must use this if you are using RefManager to point your Microsoft Office Importer links to Excel spreadsheets or Word documents that do not yet exist. For example, if you’re creating a new project from an old project and haven’t created all the Excel or Word files yet.

Chapter 17 — Modify Office Link Symbology

Overview

These settings are used to modify links to Excel spreadsheets and Word documents created in design files by Axiom’s Microsoft Office Importer. To edit these links, RefManager requires that you have Microsoft Office Importer installed and properly licensed. If you do not, you will get an appropriate error and RefManager will skip Microsoft Office Importer links.

Text Symbology and Border Symbology Settings

These settings are stored in Microsoft Office Importer links in design files. For more details on them, see your Microsoft Office Importer documentation.

Chapter 18 — Modify View Flags

Overview

Note: The View Flags category only appears when RefManager is running in MicroStation V8i or later as the reference attachment settings it modifies do not exist in earlier versions of MicroStation (2004 Edition and XM).

These settings are used to toggle the view flags of reference attachments on or off by view.

Double-click on an entry in the grid to toggle it. The possible states of each grid entry are

• “--”(do not change)
• “ON”
• “OFF”

The supported view flags are

• Clip Volume
• Constructions
• Default Lighting
• Dimensions
• Fast Cells
• Fill
• Level Overrides
• Line Styles
• Line Weights
• Patterns
• Tags
• Text
• Text Nodes
• Transparency

MicroStation’s Reference Presentation box (File | References, select a reference in the list, Settings | Presentation…) only allows you to see or change a reference attachment’s view flags for all views, not for individual views.

RefManager allows you to change view flags differently for each of your eight views.

Tip: Please note that MicroStation’s Reference Presentation box will display the state of each view flag for view 1 only. But you can run a RefManager Reference Attachment Report to confirm your per-view reference attachment view flag settings.

Chapter 19 — Attach Reference Files

Overview

Note: This action does not use the reference attachment filter. While this action is active, the {Attachments…} button will be deactivated.

RefManager’s “Attach” command allows you to attach one or more reference files to one or more master files.

If you have a project file already set up with reference files attached exactly the way you want them — and you now want to duplicate that file’s attachments for a new project, RefManager’s Copy command might be most appropriate for the task.

If you want to quickly attach a new collection of reference files and no prior project file has them attached in a configuration that is suitable for “cloning”, use RefManager’s “Attach” command.

The “Attach” command can also be used to attach a reference file using the same settings as a pre-existing attachment (in the same or another master file). For example, matching the scale, rotation and offset of another attachment.

Tip: A “recipient” file might already have some reference file attachments. RefManager’s “Copy” command detects logical name “collisions” and allows you to interactively rename logical names or cancel the “Copy” operation. RefManager’s “Attach” command auto-generates unique logical names (no collisions occur).

To begin, select the master files you want to add attachments to:

Second, select RefManager’s “Attach Reference Files” command.

Third, select the reference file or files you want to attach to the selected master files:

Reference files are attached coincident by default.

Fourth, select which reference file model you want attached to your master file(s). [V8 Only.]

Press {Start} on main dialog to attach!

Files to attach:

Enter the name of a reference file or use the {Select} button to select one or more reference files to attach. The selected file(s) will be attached to all selected master design files.

Attach Coincidentally

This option attaches selected reference files coincidentally.

Attach Just Like…

Use this option to attach a reference using the settings from another attachment (attached to the same or a different master file). The following attachment settings are applied to the new attachment:

• Rotation
• Scale
• Origin
• Display
• Snap
• Locate
• True Scale [V8 Only]
• Scale Line Styles
• Display Rasters
• Ignore Attachment When Live Nesting [V8 Only]
• Use Lights [V8 Only]

When you select “Attach Just Like…” the {Select Attachment…} button activates. Select the file, model and attachment whose settings you want to match.

Select Attachment

Select a donor file that already has reference files attached with the desired settings:

Select the attachment whose settings you want to match.

When you click {OK}, RefManager gathers settings from the selected attachment in preparation for the “Attach” process.

Note: Nested attachments are not included in the processing log, only their parent files.

Note: The “Attach” command does not support raster references. Use RefManager’s “Copy” command to copy raster attachments to one or more master files.

Model:

A V8 attachment is defined by file name + model name.

Note: “default model” is usually “Default” but it can be renamed. The “default model” is the only model which cannot be deleted.

The choices on this pull-down are:

• Attach default model from each reference file (Default)
• Ask for model name when multi-model reference file is encountered
• Attach all models from each reference file
• Attach specified models from each reference file (New in RefManager 8.16a!)

Model Names:

Introduced in RefManager 8.16a, this is tied to a new “Model:” choice named “Attach specified models from each reference file”.

This is a comma-separated list of model names in selected reference files to attach that are to be attached to each target master file model.

Duplicate Logical Names

The logical names of reference file attachments to a given reference file must be unique within each V8 model. If your “Attach “command settings would create a duplicate attachment, RefManager will ask you how to proceed. See “Duplicate Logical Names” in this guide for more information.

Chapter 20 — Change Update Sequence

Overview

Note: This action does not use the reference attachment filter. While this action is active, the {Attachments…} button will be deactivated.

RefManager allows you to change the update sequence in one or many master files.

Note: MicroStation requires raster reference files to appear either first or last in the sequence.

As an example, let’s say your reference file update sequence currently results in the following undesired display:

To push the raster beneath the master file and vector attachments, select the following settings:

The above RefManager settings change the update sequence in one (or many) master files as follows:

Note: MicroStation’s “Update Sequence” dialog allows you to adjust the update sequence of individual vector reference file attachments in the active design file. The purpose of RefManager’s Change Update Sequence command is to adjust the update sequence in multiple files.

Chapter 21 — Clone or Replace Reference File Attachments

The Problem

Note: This action does not use the reference attachment filter. While this action is active, the {Attachments…} button will be deactivated.

If each MicroStation project consisted of only one unchanging sheet file with one unchanging reference attached — no problem. Set it and forget it.

But MicroStation designs evolve and change. Personnel handling various project disciplines might submit new or revised reference files weeks or months after initial project design. Design files representing existing roads, drainage, topography, utilities and other disciplines can change during the course of a project — plot sheet master files must be updated with the new and revised reference files as they become available.

Let’s look at an example.

Joe works for a civil engineering firm which is contracted to upgrade a multi-mile span of a major highway. A few weeks ago, the initial layout was completed for 50 project sheet files. Joe has the ongoing responsibility of updating all project sheet files as new or updated reference files are received.

This week Joe has to update 50 project sheets with new reference files which have arrived from various sources — the city, utility companies, several subcontractors, surveyors and various colleagues at his company.

Some of the arriving reference files must be newly attached to the existing project sheet files; the remaining files must replace existing attachments. Regardless, Joe must ensure all attachments are correctly offset (if not coincident), scaled, rotated and clipped, with correct level display and level symbology.

It’s repetitive, tedious work. Joe forgets to scale and clip a few new reference files. Joe makes some mistakes. More new files will arrive tomorrow. This is a three year project! Joe starts to panic.

Sound familiar?

The Solution

RefManager’s “Clone or Replace Reference File Attachments” command makes short work of this common problem.

Your sheet files already contain attachments which are properly offset, scaled, rotated and clipped, with proper level display and level symbology settings. RefManager copies the settings from one or more of your carefully created existing attachments and uses those settings to attach new or revised reference files.

Clone

A cloned attachment is a new reference file which inherits the offset (if not coincident), scale, rotation, clipping, level display and level symbology settings of an existing attachment.

For example, say you want to update sheet1.dgn with the latest pavement details in the reference file pavement.dgn. Without clipping, this might look like:

The new reference file pavement.dgn needs to be clipped exactly like the existing reference file roadway.dgn.

Easy — just use RefManager to clone the existing roadway.dgn attachment and apply its settings to the newly added reference file pavement.dgn.

RefManager adds the new reference file pavement.dgn, properly clipped, to 50 project sheets automatically in one batch!

But so far we’ve only mentioned clipping. RefManager preserves all of the existing attachment’s settings (offset, scale, rotation, clipping, level display and level symbology settings) when creating cloned or replaced attachments in one or hundreds of project sheet files.

Replace

A replaced attachment takes the place of an existing attachment and inherits its offset (if not coincident), scale, rotation, clipping, level display and symbology settings.

This operation is similar to clone, except the existing attachment is detached (not deleted from disk) — the new reference file you specify takes the place of the old attachment.

Replace mode can also be used to rename an existing attachment. For example, RefManager can replace pavement50.dgn (design 50% complete) with pavement60.dgn (design 60% complete) in one or hundreds of project sheet files.

Cloning an Attachment — Step by Step

Let’s walk through an example. Suppose you want to add a new attachment, revisions.dgn, to all project sheet files. When revisions.dgn is attached to each sheet, you want it to be clipped, rotated, scaled, etc. like the existing attachment annotations.dgn.

Here’s how to do it:

1. Load RefManager from the Axiom menu.
2. Select the master files to be updated. You can enter a wildcard (as in the illustration) or click {Select…} to select a list of master files to be updated.
3. Use the displayed default “Report File” name or specify another folder and report file name.
4. Select the “Clone or Replace Reference File Attachments” command to display the “Clone or Replace Attachments” dialog.
5. Identify an existing attachment to clone or replace.The new reference file (defined in step 7 below) will inherit the attachment settings from the reference file you identify here.Type in the information, if known, or initialize the fields automatically with the {Match…} button.The {Match…} button allows you to identify an existing attachment by Element (use your mouse to select a reference file element in any open view) or by File (a file selection dialog displays and lists the references attached to the design file you select).

   Note: It is often sufficient to identify an existing attachment by file name or by logical name (one or the other). You can leave unnecessary fields blank. For example, leave the Slot Number field blank if slot number is not necessary to uniquely identify an existing attachment.

   Note: “By Element” requires an attachment’s Locate Lock to be ON.

6. Do you want to clone or replace the identified existing attachment?
   • Select clone to create a new attachment and preserve the existing attachment.
   • Select replace to create a new attachment which takes the place of the existing attachment.
     In either case, the new attachment inherits all attachment settings from the existing attachment identified in step 5.
7. Identify the new reference file to be added.Select the new attachment you want to clone or replace the existing attachment identified in step 5.If you don’t specify a new Logical Name, RefManager will auto-generate a Logical Name when cloning. RefManager will re-use the existing Logical Name when replacing.
   Note: A MicroStation V8 reference file attachment links a master file model to a reference file model. You must specify the new reference file model to be attached. The default new reference file model is “Default” — that might not be what you want! Master file models can be selected from RefManager’s main dialog.
8. Add a comment (optional).This comment is solely for your convenience to document this change. The comment is saved with your RefManager settings (can be re-used later). It is only used within RefManager.
9. If you are adventurous, click {Add} to define an additional clone or replace action. You can clone and replace multiple attachments at the same time.
10. Click {Start} on RefManager’s main dialog.
11. When processing completes, check your report file to verify results.
12. Open one of your master files and view the results.
13. Go home early!

Inherited Attachment Settings

RefManager ensures cloned or replaced attachments inherit the following settings:

• The settings displayed in MicroStation’s “References” dialog:

• The settings displayed in MicroStation’s “Attachment Settings” dialog:

• Attachment level display settings.
• Attachment level symbology settings.

Clone and Replace Tips

• The master sheet files to be processed are defined on RefManager’s main dialog.
• The master sheet file models to be processed are defined on RefManager’s main dialog — all models are processed by default.
• Currently, only vector attachments can be cloned or replaced.

• RefManager currently supports a maximum of 1,024 different clone and replace changes at one time — but those 1,024 changes can be made to an unlimited number of project sheet files.
• You can specify a relative path or configuration variable in the “New Reference File” field. For example:

PROJECT_REFS:border.dgn

references/border.dgn

RefManager’s report will notify you if PROJECT_REFS:border.dgn or references/border.dgn cannot be found.

• As of version 8.11d, RefManager will allow you to clone the same reference attachment more than once in the same job.

Chapter 22 — Copy Reference File Attachments

Overview

RefManager’s “Copy” command allows you to attach one or more reference files from a “donor” master file to one or more “recipient” master files.

If you have a project file already set up with reference files attached exactly the way you want them — and you now want to “clone” that file’s attachments for a new project, use RefManager’s Copy” command.

If you want to quickly attach a new collection of reference files and no prior project file has them attached in a configuration which is suitable for “cloning”, RefManager’s “Attach” command might be most appropriate for the task.

Use RefManager’s “Copy” command to automatically attach selected reference files to one or more master files while “transplanting” each attachment’s settings into the recipient master file(s).

RefManager can copy reference file attachments from a “donor” master file to a large number of “recipient” master files in a matter of seconds.

Use RefManager’s “Copy” command to standardize project files without tedious manual set up.

Tip: A “recipient” file might already have some reference file attachments.

RefManager’s “Copy” command detects logical name “collisions” and allows you to interactively rename logical names or cancel the Copy operation.

RefManager’s “Attach” command auto-generates unique logical names (no collisions occur).

To begin, select the master files you want to add attachments to:

These are the “destination” or “recipient” master files to which your selected attachments are copied.

Second, select RefManager’s “Copy Reference File Attachments” command.

Third, select the “donor” file:

Fourth, select the donor model from which attachments should be copied.

Fifth, select the reference files you want to copy to your “recipient” master files. Click {Select Attachments…} to display the files attached to the selected model.

Note: If you do not select specific attachments, the current Filter settings are applied. If no Filter settings are active and no specific attachments have been selected, all donor file attachments are copied.

Press {Start} on RefManager’s main dialog.

The donor’s attachments are copied to all files specified in the “Master Files:” field.

Note: RefManager’s “Copy” command allows you to copy selected vector and raster attachments from a donor file.

Duplicate Logical Names

The logical names of reference file attachments must be unique within each V8 model. If your “Copy” command settings would create a duplicate attachment, RefManager will ask you how to proceed:

Cancel Attachment Process

Stops “Copy” process. Allows you to adjust settings and start over.

Don’t attach this duplicate.

Skips the current duplicate. Processing continues with donor’s next attachment.

Don’t attach any duplicates.

Skips this and all subsequent duplicates. All other attachments are copied.

Cease attaching to this model.

Skip this model. Continue with the next model or next file.

Replace existing reference.

Detach the existing duplicate. Replaces it with new attachment.

Replace all duplicate references.

Detaches all duplicate attachments. Replaces them with new attachments.

Rename existing reference…

Prompts you for a new logical name and description for the existing attachment.

Attach reference with new name…

Prompts you for a new logical name and description for the new attachment.

Chapter 23 — Detach Reference Files

Detaching Reference Files

RefManager’s “Detach” command removes selected reference file attachment elements (ones that match your reference file “Filter...” settings) from your master file(s). The reference files on disk are not affected.

Attachments are removed from the master files you have selected.

Detaching reference files requires three steps:

1. Select the master files you want to detach reference files from.
2. Select the model(s) in those master files that you want to detach reference files from.
3. Select the attachments you want to detach. You do this by clicking the {Attachments...} button on the main RefManager dialog box, then setting filters or filter settings in the various categories.

Note: If you do not utilize any filters or filter settings, all detachments will be deleted. So, ensure that you utilize filters and filter settings so that you only detach the exact reference file attachments you want.

Chapter 24 — Order Reference File Slots

• Modify the order of reference file slots

The “Order Reference File Slots” command enables you to assign reference file slots to particular reference files. In fact, you can easily re-order all reference files.

The key features are:

• Use filename or logical name wildcard to identify reference attachments to move. Filename is base file name. For example, if you have c:\MyProject\MyReference.dgn, only “MyReference” will be compared to any file name wildcard.
• You can specify attachments using logical names, base file names or wildcards.
• Move selected attachments to the first slots (slots 1, 2, 3, etc.) or the last slots (higher slot numbers).
• To undo a selection, double click it.Click the magnifying glass icon to display the active design file’s attachments. You can add one master file’s reference file names or logical names to the list, then open another master file and add its reference file names to the list, etc. This way you can collect the names of relevant attachments from existing project files and apply the resulting lists to re-order the slots for large number of project files. Reference files which do not exist in one or another master file have no effect on slot re-ordering.

  This method of changing the sequence of items in a list is used so that sequence of attachments can be changed in bulk, in many files, with a single command.Note: If You have two or more equivalent wildcards in different lists, the wild card from the “Files to move to first in order” list has priority.

  For example:

  FIRST

  *myfile*

  LAST

  *m?file*

  A reference file with the name: “c:\test\dgn\dd_myfile123.dgn” will be added to the “Files to move to first in order” list.

  This option causes the update sequence (the order in which vector reference attachments are displayed) to be synchronized to the post-RefManager slot order. All vector reference attachments are affected by this checkbox, not just those whose slot order was changed during that RefManager job.

  Synchronize update sequence with new slot order.

Chapter 25 — Reports

Introduction

RefManager reports provide you with a bird’s eye view of your project’s vector and raster reference file attachments. You can quickly determine the exact status of an entire project’s attachments.

You can precisely control RefManager report content:

• By selecting specific master files to be reported.
• By using RefManager’s attachment “Filters” to select specific attachments to be reported.
• By selecting specific report details to be included about each attachment.

Reference File Attachment Report

This report lists your master files and user-selectable details about attached reference files, including nested attachments.

The master file(s) you specify in:

Cross-Reference Report

This report lists your reference files and the master files to which they are attached.

A cross-reference report is organized as follows:

Following is a brief excerpt from an actual cross-reference report. The master file(s) you specify in:

appear indented after each reference file:

The Cross-reference report does not include details, but does support the following Report options:

• Lines Per Page
• Header on the first page only.
• Files to Consider
• Nested Files

Missing Reference Report

This report lists reference files that cannot be located by MicroStation.

The reference file search algorithms for MicroStation/J and MicroStation V8 are different.

MicroStation procedure for locating reference files:

1. Folder defined by configuration variable, if it exists. Relative path, if present, is searched. For example:

MYPROJECT:MyReference.dgn

MYPROJECT:References\MyReference.dgn

1. Search folder of parent design file and, if attachment is nested, the folders of all parent files starting with the most deeply nested parent file. Relative path, if present, is included in the search.
2. Search the folders defined by MS_RFDIR. Relative path, if present, is included in the search.
3. Current working folder is searched. This will be MicroStation’s root folder or the folder of the file that was double-clicked in Windows Explorer to launch MicroStation.
4. If the full path is stored in the reference file attachment, search there.

If the file doesn’t exist in any of these locations it is “missing” and will be included in RefManager’s Missing report.

Change Report Settings

The “Change Report Settings” dialog automatically opens when you select the “Reference File Attachment Report” command or choose Settings | Report Settings…” from RefManager’s main menu.

The options in the “Change Report Settings” box apply only to the Reference File Attachment Report, not RefManager’s other reports.

Common Settings

Report Summary

Select this to include a summary of the number of master files and attachments processed.

Suppress output for files/models with no matching refs.

If you enable this, files/models with no reference attachments that pass any reference filters will not be completely omitted from the report.

Lines Per Page

Most of the time RefManager reports are displayed using {Display Report}. When viewed this way, “page breaks” are irrelevant, so the default Lines Per Page is 0 (disregard Lines Per Page).

However, if you want to print a report file, you may want to insert form feed into your report — usually “Lines Per Page” = 59.

Header on the first page only

By default, the report header (page number, title, date) prints only at the top of the first page of the report. If you want to see this report header information at the top of each page, uncheck this option.

Nested Files (V8 Only)

Do not include nested files (default) — nested reference files are skipped.

Include file names only — only report the names of nested reference files.

Include full report on nested files — all selected detail options will be output for all nested reference files.

Note on Filtering Nested Reference Attachments: As of RefManager 8.14a, a reference filter must match the direct attachment and the nested attachment in order for either of the above “Include…” options to include that nested reference in the report.

Vector Details

The choices above the horizontal line are attributes that happen to exist in both raster and vector reference attachments.

Full File Path

When this option is selected RefManager includes both of the following in each report:

Attached File’s Location: “C:\NewProject\MyDesign.dgn”

Saved Full Path: “N:\OldProject\MyDesign.dgn”

Note: Both are reported because they are not always the same! See the chapter “Modify File Path”.

Logical Name

When this option is selected RefManager includes the attachment’s logical name in each report.

Description

When this option is selected RefManager includes the attachment’s description in each report.

Origins

When this option is selected RefManager includes the master and attachment origins in the report.

Master Origin

RefManager labels the master origin “Shift from coincidence” in each report.

As of version 8.2a, RefManager outputs the shift from coincidence in master units. In previous versions of RefManager output was in units of resolution.

Technical Details: When a reference file is attached coincidentally, (0, 0) (units of resolution) in the attachment aligns with (0, 0) (units of resolution) in the master file.

If an attachment is moved, the attachment’s master origin is updated to represents the attachment’s shift from master file’s (0, 0) (units of resolution).

The master origin is also shifted from (0, 0) when scaling and rotation are applied to an attachment (unless the master origin is used as the origin of the transformation).

Attachment Origin

By default, an attachment is rotated about and scaled or moved from the attachment origin.

The attachment origin for an unclipped attachment is typically (0, 0) (units of resolution).

The attachment origin for a clipped attachment is typically the center of the clipping boundary’s range (in units of resolution).

Clipping Information

When this option is selected RefManager includes a statement such as the following in each report:

No clipping boundary defined.

No clipping masks defined.

Clipping element of type Ellipse is used.

Clipping boundary has 4 vertices

Note: As of version 8.2a, RefManager outputs clipping vertices in master units — for both direct and nested attachments. (Previous versions reported the raw data stored in the attachment element.)

Clipping Vertices

Select this option to include clipping vertices (if any) in each report.

Raster Details

The choices above the horizontal line are attributes that happen to exist in both raster and vector reference attachments.

Full File Path

When this option is selected RefManager includes both of the following in each report:

Attached File’s Location: “C:\NewProject\MyDesign.dgn”

Saved Full Path: “N:\OldProject\MyDesign.dgn”

Note: Both are reported because they are not always the same! See the chapter “Modify File Path”.

Logical Name

When this option is selected RefManager includes the attachment’s logical name in each report.

Description

When this option is selected RefManager includes the attachment’s description in each report.

Origins

When this option is selected RefManager includes the master and attachment origins in the report.

Master Origin

RefManager labels the master origin “Shift from coincidence” in each report.

As of version 8.2a, RefManager outputs the shift from coincidence in master units. In previous versions of RefManager output was in units of resolution.

Technical Details: When a reference file is attached coincidentally, (0, 0) (units of resolution) in the attachment aligns with (0, 0) (units of resolution) in the master file.

If an attachment is moved, the attachment’s master origin is updated to represents the attachment’s shift from master file’s (0, 0) (units of resolution).

The master origin is also shifted from (0, 0) when scaling and rotation are applied to an attachment (unless the master origin is used as the origin of the transformation).

Attachment Origin

By default, an attachment is rotated about and scaled or moved from the attachment origin.

The attachment origin for an unclipped attachment is typically (0, 0) (units of resolution).

The attachment origin for a clipped attachment is typically the center of the clipping boundary’s range (in units of resolution).

Clipping Information

When this option is selected RefManager includes a statement such as the following in each report:

No clipping boundary defined.

No clipping masks defined.

Clipping element of type Ellipse is used.

Clipping boundary has 4 vertices

Note: As of version 8.2a, RefManager outputs clipping vertices in master units — for both direct and nested attachments. (Previous versions reported the raw data stored in the attachment element.)

Clipping Vertices

Select this option to include clipping vertices (if any) in each report.

Office Link Details

Each checkbox controls the reporting of one or more properties stored in the link placed in your design files by Microsoft Office Importer. The choices are:

• Full File Path
• ProjectWise URL
• Link Type
• Excel Attributes
• Text Font
• Text Formatting
• Text Size
• Text Symbology
• Border Options
• Border Symbology

These checkboxes are all off by default.

Chapter 26 — Frequently Asked Questions

Renaming Reference File Attachments

Examples of the most common reference file name modifications follow.

Unless specified otherwise, these examples apply to both RefManager for V7 and RefManager for V8.

Note: Each example uses factory default settings unless indicated otherwise.

How to replace one reference file name with another

The following settings will replace “OldRef.dgn” with “NewRef.dgn”.

How to move reference files from one project folder to another

The following settings will replace “C:\Project1\AnyRef.dgn” with “C:\Project2\AnyRef.dgn”.

This change will be made to all reference file attachments that have “Project1” somewhere in their full path.

You can use RefManager’s {Attachments...} button (on main dialog) utilize filters and filter settings restrict modifications to specific reference files.

Modification of folder “Project1” to “Project2” in RefManager.

How to replace multiple attachments in multiple master files

1. Specify the master files you want to process.

You can specify a wild card, as in the example above, or press {Select} to select assorted master files in various folders.

Tip: You can add “/s” after a wild card expression to direct RefManager to search all subfolders too. For example, “C:\MyProject\*.dgn /s”.

Note: RefManager is capable of making broad changes to multiple project reference file attachments in seconds. RefManager creates a backup of your master files by default, but we still recommend testing processing of a single master file first to confirm your Modifications are satisfactory before you unleash RefManager on your entire project using a wild card. After confirming results are satisfactory for a single file, then use a wild card.

2. Specify the old and new reference file attachment names.

   If you need to replace many reference file attachments, enter the old|new pairs into a text file using NotePad or WordPad or your favorite plain text editor.

   

3. Tell RefManager the name of the file that contains your old|new pairs, preceded by an “at” sign (“@”):

   
   This picture is from RefManager V7. RefManager V8 looks different.

4. Press {Start} on RefManager’s main dialog.

How to insert a relative path V8 Only

Note: If a reference file resides in the same folder as the master file to which it is attached, there is no relative path.

How to prepare master and reference files for delivery on a CD V8 Only

The simplest way to prepare files for delivery on CD may be to replace the full path with a relative path as follows.

Note: Try this procedure on a single master file and confirm results are satisfactory before modifying an entire project!

In RefManager’s main dialog “Design Files:” field, enter a wildcard that represents all of your master files. For example:

“*.dgn /s” matches all files with .dgn extension and processes sub-folders.

To process all project files on your “C:” drive, change the wildcard to “C:\*.dgn /s”.

1. In “Modify Reference File Attachments” dialog, select “Attachment Paths” category and then set “Path Operation:” to “Save Relative Path”:

   

2. Press {Start} on RefManager’s main dialog.

Tip: You can copy a subset of your modified project files to a floppy and then write-protect it to simulate a CD (fast test).

Miscellaneous Tips

How to enable or disable display of Tool Tips V8 Only

RefManager’s pop up “Tool Tips” can be enabled or disabled from MicroStation’s Help menu. Select “Help” and check or uncheck “Tool Tips”:

Important MicroStation Configuration Variables

See MicroStation Help for complete information about the following configuration variables.

MS_RFDIR

“MS_RFDIR” defines where MicroStation looks for reference files.

MS_DISALLOWREFFULLPATH V8 Only

“MS_DISALLOWREFFULLPATH” controls whether or not an attachment’s full path is saved when the attachment is created.

_DGNDIR

When attaching reference files to V7 master files in V7 work mode, MicroStation V8 may add “_DGNDIR” to the attachment’s file name to represent the folder containing the parent file. For example:

_DGNDIR:References\MyReference.dgn

This is done to maintain compatibility with MicroStation/J and earlier versions of MicroStation which do not support relative paths.

MicroStation also adds “_DGNDIR:” to relative paths when working in V7 work mode.

MicroStation V8 in V7 work mode: attaching V7 references to V7 master file — what is displayed before file is saved.

MicroStation V8 in V7 work mode: attaching V7 references to V7 master file — what is displayed after file is saved.

Note: MicroStation configuration variables that begin with an underscore are not normally included in the displayed list of configuration variables. To activate display of these hidden configuration variables, set “_USTN_DISPLAYALLCFGVARS” to “1”.

Remote URL Attachments

When a remote URL is attached as a reference file, RefManager reports the local storage location for a persistent or permanent copy of the file. By default, the local storage location is:

...\Program\MicroStation\WebFiles\

DWG Attachments (Xrefs) V8/V10 Only

There are some differences between V8 attachments and DWG attachments that should be pointed out:

1. MicroStation will not allow RefManager to save a full path (also known as an absolute path) to a DWG master file’s xref attachment. Only relative paths can be saved in DWG master files’ xrefs.
2. AutoCAD does not support descriptions for xrefs attached to DWG master files.

RefManager’s “Modify | Raster Transform | Remove clip mask?” option is not applicable to DWG files with raster attachments as this functionality is not supported by MicroStation in DWG work mode.

Chapter — Choose Files to Process

Using Axiom’s “Choose Files to Process” box

Use Axiom’s “Choose Files to Process” box to create a list of files to process. Here is an empty list (no files chosen yet):

Tip: You can find balloon help for almost any dialog item by holding your mouse over it.

Adding files to the list

There are four ways to add files to the list:

• By browsing for them with the “Browse for files” button .
• By searching for them with the “Search for files” button , which brings up the “Search for Files” box.
• By dragging and dropping them from Windows Explorer into the “Files to Process” list. You can open a Windows Explorer window using the   button.
• By importing an existing ASCII text file with files listed in it using “File | Import File List…”

File and Edit menus

Most of the options in the “File” and “Edit” menus are duplicated along the button bar or on the right-click menu in the “Files to Process” list.

Browse for files

Click on this button or press {Ctrl+O} to open the “Browse for Files” box:

Search for files

Click on this button or press {Ctrl+F} to open the “Search for Files” box (with its “Basic” tab activated):

Search in:

Choose the folder you want to search for files in. Click the “Choose a folder to search” button   to browse to the folder you want to search.

Include subfolders.

Enable this if you want to search for files in subfolders too.

Search for files using:

Use this to restrict your search to files with certain names or extensions. Most users search by file extension, such as “*.dgn”.

Select one or more files and press {Open} to add them to your list of files to process.

Search for files by date:

Choose files to process based on their modification date. You can choose to search for files that were last changed before or after a specific date and time.

{Search Now}

Once you have made your file search choices, click {Search Now} to perform the search. When the search is done, you will see a count of the number of files found. Press {Add Files} to add the files to your list of files to process.

{Add Files}

After searching for files, press this button to add the found files to your list of files to process.

{Close}

Press this button to close the “Search for Files” box.

Search for Files: Advanced tab

If you want to search for files in more than one folder at a time, click on the “Advanced” tab of the “Search for Files” box (not pictured here).

Here you can choose any number of folders to search by checking them on in the folder tree.

Drag-and-drop files from Windows Explorer

Click this button or press {Ctrl+E} to open a Windows Explorer window from which you can drag and drop files or entire folders into your “Files to Process” list.

Dragging a folder into the list adds the files in that folder to the list, not the folders themselves.

Tip: You can drag files into your list from any Windows Explorer window, not just a Windows Explorer window opened by this button.

Dragging folders (not files) into the list

Dragging folders into the list is different than dragging files. Dragging files is direct — the files go right into your list. But since folders could include files you don’t want to process, dragging folders initiates a search of those folders. You can then fine-tune the search by adding or removing folders, choosing which types of files to include and limiting the search by file modification dates.

Once you’ve made your search choices, click {Search Now} to begin the search. When that’s done, click {Add Files} to add the found files to the list of files to process.

Tip: When dragging both files and folders into your list simultaneously, the files still get added to your list immediately and a search is initiated for the folders, as usual.

Remove selected files

Press this button to remove the selected files from the list.

Remove all files

Press this button to remove every file from your list.

Warning: This will clear your entire list of files. Use it with care.

Remove missing files

This removes any files from the list that cannot be found. This is available only from the Edit menu — there is no dedi

ated button for it.

Save list to file

Press this button or {Ctrl+S} if you want to save the currently displayed list of files to a text file that you can reuse in the future.

Tip: Import a previously saved file list using the “Import File List...” choice on the File menu or by simply dragging one or more of these .LST files into the list of files to process from Windows Explorer.

Files to Process

The object of this entire box is to put files in the “Files to Process” list.

Right-clicking on the list

Right-click anywhere in the list to see this context-sensitive menu of available actions:

Selecting files in the list

You might want to select one or more files in the list so you can remove them. There are multiple ways to select multiple files in the list.

Using {Shift-left-click}

You can select multiple adjacent files in the list by first left-clicking on the first file then holding down the {Shift} key while left-clicking on the last file in the series.

Using {Ctrl-left-click}

You can select multiple files arbitrarily by holding down the {Ctrl} while left-clicking on each one.

Removing files from the list

There are several ways to remove files from the list:

1. Select one or more files and click the {Remove selected files}   button.
2. Select one or more files and right-click on one of them, then choose a removal option from the menu which appears.
3. Select one or more files and press the {Delete} key on your keyboard.
4. Click the {Remove all files}   button.

Version

Right-click on the title bar and choose “About Axiom File List Processor” to bring up a box containing version information which is useful if you are calling Axiom for support.

{OK}

Once you have chosen all the files you want to process, press {OK} to close the “Choose Files to Process” box.

{Cancel}

If you change your mind, press {Cancel} and any changes you made to your list of files to process will be discarded.

Advanced Commands

The “Choose Files to Process” box is extremely powerful and easy to use. However, for those users who want more raw power, it is possible to create a list of files to process without even picking up your mouse.

Instead of opening the “Choose Files to Process” box, you can type wildcards and other special commands directly in the file specification field in the main dialog box of the host program (for example, FileFixer’s “Which Files:” field.)

Using these commands, your list of files to process will be created automatically when you start processing. Or you can open the “Choose Files to Process” box to view and edit your list of files before you begin processing them.

This table describes the most popular of these advanced commands.

Chapter — Infrequently Asked Questions

Does RefManager open reference files as the active DGN file in MicroStation?

No. Unless the reference file is in the list of master files to process, reference files are not directly opened by RefManager as the active DGN file in MicroStation.

Chapter 29 — Regular Expressions

What are Regular Expressions?

“Regular Expressions” are part of a powerful string matching language which originated many years ago with UNIX.

When you need more flexibility than the familiar “*” wildcard provides, Regular Expressions might be the answer.

Does RefMgr use both regexes everywhere? How can user know when it will use one type or the other type or fall through from one to the other?

MicroStation’s MDL Regular Expression Rules

For more information, search for “Regular Expressions” in the MDL help delivered with MicroStation.

Axiom Regular Expressions

A simple regular expression is also a sub-string search. The provided string is searched for an occurrence of the sub-string(s) specified by the regular expression.

Regular expression syntax supports several characters with special meanings. These are described below. All other characters are seen as literals to be matched in the target string. The special characters are:

A period (“.”) matches any alphanumeric character.

An asterisk (“*”) repeats any number of the last pattern, including zero repetitions. For example, “test*” matches any string that contains “tes” followed by any number of “t”s (including none). Note that “tes”, “testtt”, and “tesh” would all match.

Note: In a regular expression, an asterisk (“*”) behaves differently from the familiar use of an asterisk in DOS wildcards. In a regular expression, an asterisk matches zero occurrences of a pattern. For example, “A*” will match “A” or “BBB”, or “” (empty string -- zero repetitions of “A”.

Square brackets (“[ ]”) specify a limited range or variety of given characters. For example, “^[abcd0123]” matches strings that begin with any one of the specified characters (“abcd0123”).

A caret (“^”) matches the beginning of the string. For example, “^#include”” matches any string that begins with “#include”.

When a caret appears as the first character after a left square bracket, it reverses the meaning of the search. For example, “[^A-Z]$” matches any string that does not end with a capital letter.

If a caret appears anywhere but at the start of a regular expression, it will be interpreted as a literal character. For example, “This^” matches any string that contains the substring “This^”, treating the caret as a literal. More properly this expression would be written as “This\^”.

A dollar sign (“$”) matches the end of the string. For example, “}$”matches any string that ends with a close brace.

If a dollar sign appears anywhere but at the end of a regular expression, it will be interpreted as a literal character.

A hyphen (“-”) denotes a range of characters in [ ] ranges. “[A-Z0-9]$” matches any string that ends with a capital letter or a digit.

A backslash (“\”) removes the special characteristics of a character. “\$” matches a dollar sign.

Repetitions. A regular expression may also check for limited repetition of a one-character regular expression primitive (as above). It can check that a particular pattern repeats X times, X or more times, or at least X times and no more than Y times.

The formats are:

• P\{X\} Matches exactly X repetitions of P
• P\{X,\} Matches at least X repetitions of P
• P\{X,Y\} Matches any number of repetitions of P, between X and Y inclusive. X and Y must be non-negative integers less than 256. Whenever a choice exists, as many occurrences will be matched as possible.

Additional information and examples about regular expressions are widespread in most bookstores and on the Internet.

Segments

One of the powerful aspects of the regular expression code is the ability to record which sections of the target string matched particular sections of the regular expression.

The regular expression format is extended through the use of “segments” via the “\(” and “\)” operators which may be placed around any section of the regular expression.

• \( Denotes the beginning of a segment.
• \) Denotes the end of a segment.

There can be multiple segments per regular expression. They can be referenced later as numbered strings as “\#” or \1, \2, \3 etc.

Use of the caret (^) and dollar sign ($) primitives to match line beginnings and endings respectively must occur outside of any segments. The following expression will treat both the caret and dollar sign as literal characters:

“\(^This expression$\)” and will not match the string “This expression”, but it will match this string “^This expression$”.

The following will match the line terminators:

“^\(This expression\)$”

• Example 1

Given the file name

c:\myproject\myreference.001

the regular expression search string

\(.*\)\.001

and the replacement string

\1.002

the resulting string would be

c:\myproject\myreference.002

The #1 segment, represented by “\1”, contains all the text before the “.001”.

• Example 2

Given the input string

“I like cats. I love dogs.”

the regular expression 

\(.*\)cats\. \(.*\)dogs\.

and the replacement string 

\2fish. \1mice.

the resulting string would be 

“I love fish. I like mice.”.

The #1 string being all the text that comes before “cats” and #2 string all that before “dogs” being reversed in order and merged with “fish” and “mice”.