Original Article Date: June 1, 2000
MicroStation Configuration Variables help you define the way in which you want MicroStation to operate. They let you specify—among many other things—where MicroStation should look to find design and reference files, where MDL applications are to be found and which cell library to use. There are a large number of variables, which are documented in the chapter Working with Configuration Variables in the MicroStation Administrator’s Guide, which is delivered with MicroStation. 2000-06-01 Originally published on MSMonline 2006-03-20 Aquired and posted on AskInga
Configuration Files Configuration Variables (CfgVars) are defined when MicroStation starts up. It processes the files found in the config sub-directory of the root installation directory. For a typical installation of MicroStation SE on Windows 95, for example, the configuration directories are to be found in C:\win32app\ustation\config. There are five or six sub-directories off this directory, each of which contains one or more configuration files. Bentley changed the rules with MicroStation/J. For a default installation, you will find the project configuration files in C:\Bentley\Workspace\projects\ and user configuration files in C:\Bentley\Workspace\projects\. There are some system and database configuration files in C:\Bentley\Program\MicroStation\config\, which are best left alone. MDL application configuration files \Program\MicroStation\config\appl\*.cfg Database configuration files (not present in PowerDraft or PowerScope) \Program\MicroStation\config\Database\*.cfg Site configuration files \Site (MicroStation SE and earlier) System configuration files \Program\MicroStation\config\System\*.cfg Project workspace configuration files \Workspace\Projects\*.pcf User workspace configuration files \Workspace\Users\*.ucf Each of these files contains plain text. You can edit them with a plain-text editor such as Windows Notepad, or something more useful, such as the Programmer’s File Editor. If you use Windows Notepad, please be warned that it has an unfortunate habit of changing a file extension to txt, even when you want it to be something different, such as ucf. The result, in the case of a configuration file, is that MicroStation won’t find it, and you will become very annoyed. The files we are concerned with here are the Project and User configuration files. The configuration statements they contain instruct MicroStation to create a CfgVar with a certain value. When specifying variables that define files or directories, the separator character is always a forward-slash (/): MicroStation converts this to the appropriate separator for the operating system which you are using, making your configuration files platform-independent. For example, the following line tells MicroStation to look in a particular directory for reference files: MS_RFDIR = c:/la/maps/landline/dgn/ Subsequently, when you use the Reference File dialog to attach a file, MicroStation by default looks in the directory specified by $(MS_RFDIR). CfgVars can inherit their value from other CfgVars; that is, a configuration file may include nested definitions. Suppose you have defined a variable $(MAPS), and want to specify that reference files are relative to the path it defined. The following two statements first define $(MAPS) and then define $(MS_RFDIR) relative to $(MAPS): MAPS = c:/la/maps/landline/ MS_RFDIR = $(MAPS)dgn/ The resulting definition of $(MS_RFDIR) is identical to the previous example. Evaluating CfgVars in BASIC Macros When you write a MicroStation BASIC macro, you may want to evaluate CfgVars during the execution of your code. Your code could include hard-coded directory paths, which will work until your files are moved to a different device. Using a CfgVar instead of a hard-coded path makes your code portable and less likely to break as conditions change. For example, you might want to check that a certain file is present, or is not present, in a directory before you perform some operation on it. Using standard BASIC syntax you might write a statement like this: If (FileExists ("c:\la\maps\landline\dgn\vicinity.dgn") Then ‘ Execute some code when vicinity.dgn is present End If But, when this project is moved to a different directory your macro will break. Standard BASIC syntax doesn’t understand CfgVars [i.e. writing FileExists (“MS_DEF”) will not work]. Luckily, Bentley has thoughtfully provided some extensions to BASIC, which assist in file operations. These extensions do a lot of work that is difficult to achieve in standard BASIC. Try using MicroStation BASIC CfgVar extension functions to find a file: Dim sPath As String ‘ Get MicroStation’s reference file path sPath = MbeGetConfigVar ("MS_RFDIR") ‘ Concatenate a file name sPath = sPath & “vicinity.dgn” ‘ Check to see if it exists If (FileExists (sPath) Then ‘ Execute some code when vicinity.dgn is present End If As an alternative, you can use the function MbeFindFile provided by MicroStation BASIC, which assembles a file name and checks to see if the file exists. Dim iStatus As Integer Dim sFileName As String iStatus = MbeFindFile (sFileName, "vicinity", "MS_RFDIR", ".dgn") If (iStatus = MBE_FileNotFound) Then ' Execute some code when vicinity.dgn is not present End If MbeFindFile not only shrinks your code, but also is more versatile than the file functions provided by standard BASIC. What happens if your reference files are located in multiple directories? It is not uncommon to find that $(MS_RFDIR) specifies several paths: MS_RFDIR = c:/la/maps/landline/dgn/ MS_RFDIR > c:/la/maps/landline/scale_1250/ MS_RFDIR > c:/la/maps/landline/scale_2500/ This instructs MicroStation to search each of three directories to find a particular reference file. Using standard BASIC syntax to search multiple directories is not straightforward, but by using MbeFindFile, the code example works without modification. Defining CfgVars in BASIC Macros Now you know how to find the value of a CfgVar using MicroStation BASIC. How about specifying a new value for a CfgVar in your macro? You can examine the MicroStation BASIC manual for a long time before you discover how to accomplish this—it’s not documented (Remember folks, you read it here first!). For example, suppose your macro needs to change the default location where MicroStation looks for design files. When you open a file using MicroStation’s File Open dialog, it initially looks in the directory indicated by $(MS_DEF). If you want MicroStation to change directories, you could write some code with explicit paths, but—as explained above—this makes your code rather fragile. Instead, modify the $(MS_DEF) CfgVar so that MicroStation automatically looks in the place you want: Dim sPreviousMSDef As String, sNewMSDef As String Dim iStatus As Integer, iUpdateCfgFile As Integer ‘ You can choose to update the configuration file if ‘ iUpdateCfgFile = 1 iUpdateCfgFile = 0 ‘ It’s polite to save the current value of MS_DEF so ‘ we can restore it later sPreviousMSDef = MbeGetConfigVar (“MS_DEF”) sNewMSDef = "k:\projects\new_project\dgn\" iStatus = MbeDefineConfigVar ("MS_DEF", sNewMSDef, iUpdateCfgFile) ‘ ‘ Do things with new MS_DEF ‘ ‘ Restore the previous MS_DEF when finished iStatus = MbeDefineConfigVar ("MS_DEF",sPreviousMSDef, _ iUpdateCfgFile) Inheriting Environment Variables from the Operating System Sometimes, you want to find the value of an operating system environment variable. Bentley has made this very easy to accomplish through CfgVars. If a MicroStation variable is not defined, then MicroStation will search the operating system environment table. For example, the operating systems that most of us use define an environment variable %USERNAME% that contains the log-on name of the current computer user. On a Windows NT computer, you can see its value by opening a command window (or Start|Run…) and typing SET USERNAME. The operating system responds with its expanded value, for example clintonw. You can refer to an environment variable in a configuration file or BASIC macro in just the same way you refer to a configuration variable. For example, to copy the USERNAME into a BASIC variable you could do this: ‘ Declare a BASIC string variable to hold %USERNAME% Dim sUserName As String ‘ Obtain the operating system and copy it into our local variable sUserName = MbeGetConfigVar (“USERNAME”) ‘ sUserName now contains the value of %USERNAME% Now you can both evaluate and define CfgVars in MicroStation BASIC macros. If this helps your understanding of MicroStation BASIC, let us know! The MicroStation Community will also be interested to hear your comments, as macros become better understood and more popular amongst MicroStation users.
AskInga Article #293