Original Article Date: July 1, 1998
This very old article first appeared in the Client Server way back in 1998. Authored by Bentley's Tom Glebas, it discusses the how path from chaos to organization requires attention to details before the project even starts.
1998-07-01 Original publication date in the Client Server.
2006-03-01 Aquired and posted on AskInga.
There are two basic ways to approach a job. The first, which I call the “Myopic Method,” is to use brute force—face each task head on, get it done, and move on to the next one. The second approach, herein named “Einstein,” (just go with me on this, besides, it works well with the title) is to look for efficiencies, plan ahead, and then, as they say, “work the plan.” As a project’s complexity increases, so does the likelihood that using the Einstein approach will result in greater productivity and success. Now, where on the “complexity” continuum do you suppose most engineering projects lie?
Design files, cell libraries, settings groups, line style resources (and a hundred other items) in engineering projects are made up of lots and lots of data, and are often “engineered” by numerous people working on a variety of complex systems in diverse environments. Wouldn’t it be nice if every time you wanted to open a file, attach a reference file, or open a web page, the right default was presented to you (or anyone else working on the project)? MicroStation’s workspaces are designed for that very purpose, but if you want to benefit from them, you have to put forth a little effort before you join the race to the project finish line.
It seems as though there are as many ways to organize engineering projects as there are projects and the environments in which they are completed. The good news is there is no singular right way. The bad news is there are probably as many poor or inadequate ways to do it, as there are right ones. For the sake of argument I’ll presume you have developed a “workable” project organization and workflow. If not, consider it your homework assignment.
MicroStation’s workspace modules present a nice model for organizing your data. Look at the directory structure of wsmod/ in MicroStation’s root directory and see if you think you have similar data. Ask yourself, “What types of files do I have?” And, “How should they be grouped for easy access and maintenance?”
Although workspaces are highly dependent upon the environment they are intended to support, there are often many common practices and implementation strategies that make it possible to offer good, sound advice on their development. Perhaps the most concise presentation of this “advice” can be found in the workspace files delivered with MicroStation. Start by examining “ustation/config/msconfig.cfg” and follow it through. As you examine it, consider the following points.
Use one file set for many products. You may have noticed the many product references in these files. This allows a single source and easy administration. Consider using this approach for multiple platforms or other environmental or user variations. For example, create a variable, SysRoot, and set it to usr/ on Unix systems, or c:/ on PCs. You can determine the platform and appropriate definition to assign using, %if defined (_winNT), and, %if defined (_unix). Now, whenever you need to refer to the root directory of the system MicroStation is running on, the same file can be used regardless of platform. You’ve just cut your development and maintenance in half.
ProjectRoot could be defined in a site configuration file. With this method of double indirection (using a variable in a variable), every project file is very simple, and you only have to administer one file when it comes to the details. To add a new file, all you have to do is create the new project’s directory structure and copy a project file template, changing the name in the ProjectName = line. If this project organization applies to the entire site, the contents of ProjectBase.cfg could be included in the site.cfg file. These assignments will work even though site.cfg is read before the project file. That’s because the variables aren’t expanded until they need to be resolved. (You could eliminate the %include …ProjectBase.cfg line in the project files in this case.)
Always use forward slashes, / to delimit directories, even on PCs. And, always include a trailing /. Use %include statements to break up your files into manageable components, and use variables to pass information from one file to the next. For example, suppose you have organized your project directories in a common location and they all have a similar structure. By creating a base project configuration file with all the detailed definitions, and using a variable for the project’s name, you can simplify the management of many project files and the addition of new ones. The following example illustrates this technique. Design your project file as a simple naming and calling device:
#Set the project name
ProjectName = abc
#Call the detailed project definition file
In ProjectBase.cfg the project variables can be defined in such a way as to work for all projects:
#Set the details
MS_RFDIR > $(ProjectRoot)$(ProjectName)/ref/
MS_CELL > $(ProjectRoot)$(ProjectName)/cell/
New configuration variable:
There is also a new configuration variable to support a variation of this organizational structure. Suppose you have your projects organized such that each project’s main directory contains DGN files and subdirectories of supporting data (reference files, plotter settings files, archive files, etc.). You can use _dgndir as a pointer to the current project directory, and no matter what project you are working on, the location of the supporting data is determined by the open DGN. The above assignments can then be made like this:
#Set the details
MS_RFDIR > $(_dgndir)/ref/
MS_CELL > $(_dgndir)/cell/
An important principle of configuration maintenance and integrity is that of segregation. As evidenced by the latest trends of three-tier client/server technology, segregation of applications and data (and presentation in three-tier systems) is considered a good thing. With workspaces, you should consider segregating two components from MicroStation. The first refers to the configuration files, the second to your actual data. MicroStation presents a good model for organizing both of these within its structure, but for ease of backups, system integrity, maintenance and upgrades it is best to follow this model “outside” of MicroStation’s directories. There are several techniques you can employ to accomplish these ends. Once again, the best approach depends upon your specific organization and workflow.
To segregate your workspace files, you can either use operating system variables to redirect MSADMIN and MSLOCAL to directories outside of MicroStation’s, or you can use a simple calling device in the SITE.CFG file. Both approaches have their advantages and drawbacks. I’ll leave the determination of the advantages to you, but we’ll touch on the pitfalls since it’s nicer to learn from someone else’s mistakes than to blindly repeat them yourself. In the first approach, you need to be careful of third party application level configuration files, that are probably created in MicroStation’s config/appl/ directory when installed. MicroStation’s msconfig.cfg file refers to this directory using $(MSADMIN). If you redirect MSADMIN but don’t move the application level files, your applications may stop working. You also need a way to ensure that the operating system variables are properly set on each machine. In the latter approach, you need to install a SITE.CFG file in MicroStation’s config/site/ directory. This file is used to redirect the processing to your independent location. The penalty is that your segregation is never really 100% complete, and you now have two locations to administer (MicroStation’s and your own). This approach also doesn’t address segregating your data, which is accomplished when using the first method.
In order to preserve the base workings of MicroStation or other levels of your configuration, you should attach values to paths or search lists using, > or <. This way you will always have access to the base data. The new definition will supplement or extend the existing one, not replace it.
Redirecting MSADMIN and MSLOCAL provides good coverage of most items including your configuration files and your data, but forces you to copy many of the delivered resources to your new location if you want to continue to use them. An alternative is to model something like wsmod/ in your own location and redirect _USTN_WSMOD in a site file. But there are more files to consider than what _USTN_WSMOD covers. Look through the delivered configuration files, particularly config/system/msdirs.cfg and config/system/msfiles.cfg and you will find entries for _USTN_OUT, MS_DEF, MS_FKEYMNU and several others that you’ll have to decide how you want to handle.
Segregating your data involves quite a few details due to the many resource files that are delivered with MicroStation. You most likely want to continue to access those resources as you add your own.
Once you’ve designed your workspace, you become responsible for administering it. In organizations with many seats of MicroStation, this task can get out of control. If you are operating in a network environment, many of the above principles can be applied to ease the burden. Move your configuration files to a location on the network and try to create a single file set that can be accessed by all, but managed in a single place. Use variables and %if statements to set them according to variations from system to system or user to user. With a little inspiration and perspiration, you should be able to design an effective, yet manageable configuration.
Ultimately, productivity comes from being able to alter your environment. Make the environment suit your purposes, you don’t need to be a slave to default settings. After all, if we had no control over our working environment, we wouldn’t need any approach other than the “Myopic Method.” Taking the time in advance to organize the workspace will offer paybacks through more efficient and productive operations. While we didn’t get to address Einstein’s most famous equation of the space and time continuum, I hope you have learned, Workspace = Shorter Work Time.
Understanding pointers, variables and redirection:
Our everyday lives are filled with examples of redirection and the use of variables. Consider speed dialing, where a short dialing sequence directs the telephone to a longer one. Clothes dresser drawers can also serve as example of redirection. If you dedicate a different drawer to each type of clothing, then rearrange the order of the drawers, you have created an analog version of redirection.
In a sense, with workspaces, you are telling MicroStation which drawer is your sock drawer or which phone number is for pizza delivery. Instead of socks and pizza, the redirection variables point to design files, reference files, cell libraries and other resources. MicroStation offers three redirection options to be used alone or in combination:
1. MicroStation defines its own default locations.
2. You can define your own default locations by site, user and/or project criteria.
3. You can specify files and resources explicitly.
You could use option 3 in every case, but explicit is not necessarily efficient. So options 1 and 2 are recommended, and they both rely on redirection, or, as it’s referred to in MicroStation’s workspace terminology, configuration variables. When MicroStation needs information, it refers to a look-up table of configuration variables stored in memory. For example, to find what Settings file to use, MicroStation looks in its table for the value of MS_SETTINGS.
MicroStation learns about MS_SETTINGS and other configuration variables through configuration variable files, which MicroStation reads when it starts. Once MicroStation has started, the variables can also be modified through a menu selection, using Workspace > Configuration. Changes made through this interface can be temporary, lasting only for the current session, or can be written to the current user’s configuration file for continued operation in the current and subsequent sessions.
Configuration variables files are stored in subdirectories of the config/ directory, which is under MicroStation’s root directory. These subdirectories create a hierarchy that allows options 1 and 2 to coexist in an orderly and predictable fashion. There are actually more than just two levels to this hierarchy. User level variables are given priority over project variables, which in turn have priority over site variables that supersede application specific variables, and finally MicroStation’s system variables.
Essentially, these files are read at each level, and the look-up table (a matrix five levels deep) is formed. Usually, the same set of system files, application files and site files are always used and read every time MicroStation starts, but the user and project files can vary, and are selected through the MicroStation Manager opening dialog (or by using the -wu or –wp command line switches). The information contained in these latter files is specific to the requirements of a particular user and project, and is often tailored to create the most productive environment.
Each configuration file is a text file containing assignments and other processing instructions that are used to populate the look-up table. Assignments are defined in a typical programming format, as if it were a mathematical expression, where:
EXPRESSION becomes the value of VARIABLE as defined by an OPERATOR.
# Engineering Links home page for startup can be set to any valid URL
MS_WEBPAGE_HOME = www.mycomany.com/projects/index.htm
MS_CELL : $(_USTN_WSMOD)/default/cell/
# directory for cell libraries
In these examples, a # signifies that the remainder of the line is a comment (which you should use liberally when you create your own files). The first example is a direct assignment. The second one is a little more complex. The colon (:, the operator) in place of the equals sign indicates that if MS_CELL (the variable) does not already have a value, set it equal to $(_USTN_WSMOD)/default/cell/ (the expression). If it does have a value, maintain the existing value and ignore the expression.
The expression contains some interesting syntax as well. _USTN_WSMOD is a variable itself, and the surrounding $ (“ and ”) instructs MicroStation to substitute the value of _USTN_WSMOD when it needs to determine the value of MS_CELL, an example of double redirection.
Even experts can make mistakes when developing configuration files, so MicroStation comes prepared to help you diagnose the source of errors. The debug command line switch instructs MicroStation to report on the results of configuration file processing. Adding, –debug=n to the command line generates a text file, MSDEBUG.TXT, in the working directory. The value of n specifies the level of detail in the report. Valid values for n are 1 (minimum detail) through 5 (maximum detail) with 4 being the default.
While developing configuration files may require some creativity and programming skill, operating MicroStation becomes so much easier as a result.
AskInga Article #284