Print Text Substitution

(Portions of this article apply to MicroStation V8i)

Setting aside the more sophisticated capabilities of ProjectWise InterPlot design scripts and ProjectWise title blocks, there are four main techniques in standard MicroStation to replace design file text at print time. Common reasons for wanting to do this include placing the user name, the design file name, the current date & time, the date & time the design file was last saved, and/or other information about the sheet on the printed output.

The primary methods for print text substitution are:

• Simple pen table text substitution
• Fields
• Named expressions in conjunction with a pen table
• BASIC macros in conjunction with a pen table

In this article I am going to discuss the pros and cons of each method, and provide examples on how to use them.

Simple Pen Table Text Substitution

Pen table text substitution is the simplest method to replace text when printing. This feature is described in the product documentation under "Working with Complete Designs / Printing / Print Resymbolization and Pen Tables / Modifying Pen Tables / Text substitutions".

To perform pen table text substitution, you place unique text in your design that, when printing or print previewing, the pen table application searches for and replaces with new text that you specify. The replacement text can be the value of one of several tokens provided by the pen table, or a literal text string, or the value(s) of one or more environment variables in conjunction with literal text. The replacement string is printed using the same text attributes (i.e. font, justification, character spacing) defined in the original text element.

For example, if you want the user name and the current date to appear on the printed output, the first step is to place two text elements in your design containing $USER$ and $DATE$. The strings you use to identify the elements to be replaced can be anything you like, but they need to be unique. The second step is to create a pen table, go to the pen table "Text Substitutions..." dialog, and use the "Edit / Insert New" menu command to insert two replacement pairs. Then for each replacement pair, enter both the original string to be replaced and the desired replacement string.

In this example, I've shown two techniques for the replacement string. For the date, I've used one of the many tokens provided under the pen table's Edit menu:

These tokens are easy to use, but have some limitations. The main limitation is that only one token may be used in the replacement string, and it may not be used in conjunction with literal text or environment variables. The formatting of the replacement string is also less flexible than other techniques. By default, the formatting of the _DATE_ and _TIME_ tokens are controlled by the Windows regional settings, but may be overridden via the MS_PENTABLE_DATE_FORMAT and MS_PENTABLE_TIME_FORMAT configuration variables respectively (see the product documentation for explanations of these variables). Since global configuration variables control this formatting, there is no way to, say, have two replacement strings both use the _DATE_ token but have one resolve to the full date and the other resolve to the year only.

For some values, the pen table offers different tokens for formatting variations. For example, each file name value (design file, pen table, printer driver configuration file) has separate tokens for the fully-qualified file name, the base file name only, or an abbreviated version of the full-qualified file name. There are also long and short versions of the print scale.

For the user name, there is no replacement token available, so I've used the environment variable USERNAME, which is defined by Windows. I also included some literal text in the replacement string to demonstrate the capability. If I had wanted to, I could have used multiple environment variables in the replacement string, such as "$(USERDOMAIN)/$(USERNAME)" to yield "Bentley/Andrew.Edge".

You may also use any of the print accounting variables in the replacement string. These variables are listed in the product documentation under "Working with Complete Designs / Printing / Tracking Printer Usage / Printing Accounting Variables". The values of many of these variables are redundant with the pen table replacement tokens, but have the advantage being able to use more than one in a single text replacement string. For example, "Sheet $(MS_PLT_DOCSET_CURRENT_SETDOC) in $(MS_PLT_DOCSET_NUMSETDOCS)" may evaluate to "Sheet 1 of 20" when printing from Print Organizer or Batch Print.

When using a pen table to perform text substitution, the contents of the design file are never modified. This means that pen table text substitution can be performed even when printing read-only design files, or inside references (where title blocks often reside).

One downside to pen table text substitution is that the pen table file must be provided to everyone printing the designs. If another site is already using a different pen table for resymbolization, they would have to merge their pen table with your text substitution instructions.

Fields

Another technique to accomplish text substitution is to use Fields.  You can find information about Fields in the product documentation under "Composing Drawings / Annotations / Placing Text / Fields - derived content in text". For example, here are the field choices available from the active file properties:



Fields offer a rich set of properties that you can insert in your text elements, and have them dynamically update when needed. There is not a complete overlap of functionality between Fields and pen table text substitution; for example, there is no way to insert the value of the current Windows user name. However, you can pick the design file author or the user who last saved the design file, which in many cases is the information you really want on the print output -- not the name of the user who's running the print jobs.

There are many formatting options for the date and time fields, and each field may be formatted independently of each other.

Starting in MicroStation 8.11, the value of the 'Date Plotted' field is set at the beginning of the print job, instead of at the end, so that the field is equivalent to the pen table _DATE_ and _TIME_ replacement tokens.

The advantage to using fields for print text substitution is that you don't need a separate pen table file just for text substitution, you can insert and edit fields using the standard MicroStation text tools, and that the evaluated results are saved in the design file for later reference.

The downsides to using fields for print text substitution are (1) reference issues, (2) read-only issues, and (3) performance.

(1) When updating fields, only text elements in the master model are searched. Text elements inside references that contain fields are never modified.

(2) Fields are never updated when the design file is opened in read-only mode. By default, both Print Organizer and Batch Print open design files in read-only mode when printing. If you wish fields in the master model to update prior to printing, you need to change the Print Organizer or Batch Print preferences to open files in read-write mode. Of course, this only helps if you have write access to the physical files on your computer or over the network.

(3) Fields can be simple or complicated. A "Date Plotted" field in the master model is simple, and can be updated quickly without any performance concerns. However, you may also have "placeholder" fields in the design that are derived from link targets in other files. Updating those fields requires that the other files be opened in the background, which may be a very time-consuming activity. With this in mind, Bentley has taken care to give you control on when fields are automatically updated. You may control this on a per-model basis, via the 'Update Fields Automatically' checkbox in the Model Properties dialog, or you may control it globally via the MS_AUTO_UPDATE_FIELDS configuration variable. If you are only using simple fields, then you may wish for all fields in all models to update all the time. However, if you are using placeholder fields whose values rarely change, then you may wish to only update fields by hand, when you need to.

The printing system does not know in advance what kinds of fields you are using, or how long they might take to update. Thus, by default, fields are not updated prior to printing. If you wish, you can enable updating of fields prior to printing in MicroStation 8.11 and later by setting the configuration variable MS_PLT_UPDATE_FIELDS to "1" or "2". If set to "1", fields are updated prior to printing only. If set to "2", fields are updated prior to both printing and previewing. Keep in mind that the thumbnail preview in the Print dialog updates frequently, so you would not want to set MS_PLT_UPDATE_FIELDS=2 if you had any placeholder fields that referenced other files.

Bentley has investigated providing printing properties such as print scale, paper size, printer name, pen table file name, print set information, etc. through the Fields system as an alternative to traditional pen table text substitution. Our conclusion was that given the typical pen table text substitution workflows, the restrictions that would be imposed outweighed the few new benefits the feature would provide. To reliably provide text substitution of print properties without regard to master model vs. reference, read-only vs. read-write access, or performance concerns, pen table text substitution is still the better solution. Especially since pen tables are still essential to many customers for print resymbolization. That said, I would definitely like to hear your opinions on the subject. Would you use print properties in Fields even if you were limited to placing them in the master model and having them update only when printing in read-write mode?

Named Expressions in Conjunction with a Pen Table

One of the significant new features in MicroStation 8.11 is named expressions. Information about them may be found in the product documentation under "Programming Customizations / Named Expressions". Named expressions have many uses in MicroStation, and one of them is to extended the capabilities of basic pen table text substitution.

For a simple tutorial of how to define and use a named expression, please read this article showing how to automatically insert the current date into the print output file suggested by the Print dialog. I'm not going to try to repeat that background information here. In particular, note the <expr?name=...> token that can be inserted into the printer driver configuration's 'Default Print File Name' property.

The <expr> token may be inserted into a pen table text substitution replacement string just like a reference to an environment variable. This offers a number of advantages over pen table replacement tokens and environment variables. In a named expression, you can use any number of symbols (many of which are not available as environment variables), and take advantage of superior formatting capabilities and even 'if else' conditional logic.

For an example, I'm going to revisit the date and user name example I showed earlier. Only this time I want to print the author of the design file, not the current Windows user. I want the date to be formatted "day month, year". I also want to add the page number within the print set, total number of pages in the print set, the print scale in the format 'paper units : master' with three digits of precision, and either the model's sheet name or sheet number (whichever is defined). For the new strings I'm adding, I'm going to search for and replace text elements containing $SETPOSITIONANDSCALE$ and $SHEETNAME$ respectively.

The first step is to create the named expressions in my design library. Here are screenshots of the four expressions I need (the names are immaterial; I used a leading underscore simply to group them together in the list):

This "_Author" named expression demonstrates use of a property value that is not available from the pen table replacement tokens, printing accounting variables, or other environment variables.

This "_Date" named expression demonstrates the advanced date/time formatting capabilities of System.String.Format, as well as the ability to independently format separate date / time replacement strings.

This "_SheetName" named expression demonstrates the ability to use conditional logic in pen table text substitution. In my example, the Sheet Name and Sheet Number values in my Model Properties dialog are set to "My Sheet Name" and "5" respectively. Thus, this expression evaluates to "My Sheet Name". If I clear out the sheet name, this expression evaluates to "5".

 

This "_SetPositionAndScale" named expression demonstrates the advanced decimal number formatting capabilities of System.String.Format, as well as the ability to use multiple symbols and literal strings in a single text element replacement.

My pen table text substitution dialog looks like this:

Note when using the <expr?name=...> token, the "..." should be the 'Internal Name' of the named expression.

Also note that I'm able to use the <expr> token in conjunction with environment variable references and literal text.

For my example, the print preview output with the replaced strings looks like this:

The advantage to using named expressions in pen table text substitution is the flexibility they provide. They permit constructing replacement text at print time from a variety of sources, without the restrictions that come with Fields. The downsides are that expressions are not particularly easy to write (but not as hard as BASIC macros), and that the design libraries containing the expressions must be provided along with the pen table file to everyone who needs to print.

Be aware that the <expr?name=...> token may also be used in the print border text string.

BASIC Macros in Conjunction with a Pen Table

I'm not going to go into a detail about using BASIC macros in a pen table because it's a complicated feature that is not commonly used. I include it here because it is another method in which to perform text replacement when printing. For more information, refer to the product documentation under 'Working with Complete Designs / Printing / Print Resymbolization and Pen Tables / Modifying Pen Tables / Element output actions / Element Output Actions tab / BASIC", and in the MicroStation BASIC Help under "Concepts and Procedures / Macro Interactions with MicroStation / Using Macros to Specify Pen Table Output Actions".

The screenshot below shows a pen table output action configured to run the BASIC macro shown in the background. The macro simply checks to see if the current element is a text element containing the text "$USER$", and if so replaces the text with the current Windows user name. Obviously, much more sophisticated logic could be programmed into the macro.

The benefit of print text substitution using BASIC macros is that there are very few limitations to what you can do. The disadvantages are they can be difficult to write and maintain, and the macro file along with the pen table file must be provided to everyone who prints.