Here are answers to questions about the MicroStation® Development Language (MDL). When implementing functionality in pure MDL, there are Windows environment variables to consider. By pure MDL, we mean an application developed using only those tools provided in the MDL Software Development Kit (SDK). Similar questions are posted by MDL developers on the Bentley Discussion Groups.

Q Have you any hints about developing an application for MicroStation using MDL?

A You may want to read about MDL project structure and consult the MDL documentation files provides with the SDK. Since MicroStation V4 was introduced in 1992, you have been able to write applications using the MicroStation Development Library (MDL) and use the MicroStation software development kit (SDK) to create an application (.ma) file. It's not always easy to understand how to configure your computer to build an MDL application. This article discusses several aspects of configuration to get you started.

You can development large MicroStation MDL applications more productively using Microsoft Visual C++ with the MDL API. For more information, consult the Bentley documentation and take a look at this C++ page.

MDL Project Structure

An MDL project contains a number of code modules and resource modules. The SDK contains compilation tools that compile those code & resource modules into binary object files. Linker tools merge your object files into an MDL executable application (.ma) file.

MDL code lives in a set of source (.h, .mc, .r & .mt) files. Source code is plain text, which you create with a suitable text editor. You could, if determined to make your life miserable, attempt to develop using Windows Notepad™, but you are well advised to find a programmer's text editor. There are some text editors mentioned here.

Bentley Tools

Bentley provides tools (executable files) for building MDL application in the
\MicroStation\mdl\bin folder. You don't normally use those tools directly: prefer to invoke them using the Bentley Make (bmake) utility.

MDL implementation code is plain old C and lives in a source code (.mc) file. Typically your code file will #include a header (.h) file that defines various constants and C macros common to all files in your project. You compile MDL source code with the Bentley mcomp tool.

MDL dialog and message list files live in resource code (.r) files. Typically your resource code file will #include a header (.h) file that defines various constants and C macros common to all files in your project. You compile MDL resource code with the Bentley rcomp tool.

The result of MDL code and resource compilation is a set of object files. To create your executable application, those files are merged together using Bentley's linker tools, rlib and mlink.

Bentley Make Tool

The tools described above are typical of the tools found in many development environments. Long ago, developers became tired of the multi-stage process required to build an application, and developed the make file to control that build process.

A make file contains all the rules necessary to build a particular application from its source files. The rules invoke the appropriate tool for each step in the process. In the world of MDL, we use the Bentley make tool (bmake) to interpret the rules in a make file that you write for your MDL project.

Your make file (.mke) includes the set of rules required for your MDL application. When you invoke the make tool, it knows how to build your application. Instead of having to invoke each tool separately, your build task is simply this …

bmake MyApp

Understanding make files is hard. The Bentley make files are especially convoluted and use many %include (*.mki) files. Although there's no definitive manual for Bentley make files, there is help elsewhere on the web. The O'Reilly press book Managing Projects with GNU Make may be helpful …

Managing Projects with GNU Make

Windows Environment Variables

The definitive source of environment variable settings for MDL development is the batch file mstndevvars.bat provided by Bentley Systems with the MicroStation SDK. See the section below for more information about that batch file.

When executed, mstndevvars.bat creates a command shell — a Windows environment — that defines a number of Windows environment variables for you. In other words, if you build an MDL project using mstndevvars.bat you don't need to define any environment variable. If you're new to MicroStation development, use the command shell to create your build environment.

For more advanced MicroStation developers, the following list attempts to describe the environment variables defined by mstndevvars.bat. If you want to build projects without the help of that command shell, you nonetheless must define these variables to persuade a project to build correctly. When you define a Windows environment variable that represents a path to a folder that will be used in your build process, pay special attention to the need for a trailing path terminator.

There are several Windows environment variables relevant to MDL development …

MicroStation V8i

Environment Variables for MDL Development with MicroStation V8i
Variable Purpose
MS Specifies the location of the MicroStation executable (ustation.exe), and the default location of the MDL tools root
PATH The location of executable and library files used by Windows
MSMDE Specifies an alternative location for the MDL tools root
BMAKE_OPT Specifies default location for MDL #include files
MLINK_STDLIB Specifies default MDL libraries for the link tool
PolicyFileMapMki Specifies location of the MdlSdkPolicyFileMap #include file
PolicyFileNamesMki Specifies location of the PolicyFileNamesMki #include file
toolspath Specifies actual location of the MDL tools files (e.g. \MicroStation\MDL\bin\

MicroStation V8 XM and earlier

Environment Variables for MDL Development with MicroStation XM & MicroStation V8 2004 Edition
Variable Purpose
MS Specifies the location of the MicroStation executable (ustation.exe), and the default location of the MDL tools root
PATH The location of executable and library files used by Windows
MSMDE Specifies an alternative location for the MDL tools root
BMAKE_OPT Specifies default location for MDL #include files
MLINK_STDLIB Specifies default MDL libraries for the link tool

Windows Path Terminators

When defining an environment variable that expands to a path, pay attention to the final path terminator. In Windows, the path terminator is the final backslash (\) character. In general, a path needs a terminator when used in a MicroStation development environment. Often, a path is used in your makefile (or in an %included Bentley makefile) as the starting point for a further path definition.

If your Windows path is terminated, then the make file can build a valid sub-folder name. Suppose you have defined a Windows environment variable MS …

MS=C:\Program Files\Bentley\MicroStation

The build process may want to create a macro that points to the \mdl\bin folder …

MSMDE=$(MS)mdl/bin/

 … which expands to …

C:/Program Files/Bentley/MicroStationmdl/bin/

Which is wrong! There is no folder MicroStationmdl! The problem is the lack of a path terminator in environment variable MS. Fix it by setting that variable with the path terminator …

MS=C:\Program Files\Bentley\MicroStation\

Now the makefile expands the variable to create a valid folder definition …

C:/Program Files/Bentley/MicroStation/mdl/bin/

Pay close attention to the definitions of Windows environment variables that are used in make files. Ensure that a trailing path terminator is included where required.


Environment Variable  MS

You should define a Windows environment variable MS. Environment variable MS points to the folder where the MicroStation executable (ustation.exe) is installed. That folder is version dependent …

MDL Folder Locations
MicroStation Version MicroStation Executable Location
MicroStation V8i C:\Program Files\Bentley\MicroStation\
MicroStation XM C:\Program Files\Bentley\MicroStation
MicroStation V8 2004 Edition C:\Program Files\Bentley\Program\MicroStation

Define MS in your computer's settings …

  1. Right-click My Computer on the Windows desktop
  2. Click Properties in the pop-up menu
  3. The System Properties dialog opens
  4. Click the Advanced tab
  5. Click the Environment Variables button
  6. The Windows Environment Variables dialog opens
Windows Environment Variables Dialog

Notice that there are two panes in this dialog. The upper pane, User variables for <USERNAME>, lists environment variables for the current Windows user. In this example, I'm logged into account V8.5. The lower pane, System variables, lists environment variables defined all users of Windows. If you don't have sufficient adminstrator privileges the lower pane may be greyed or absent from this dialog.

Use the upper pane to define your own variables. I use different logins for different MicroStation versions. I can define a unique MS value for each login, so the MDL development environment is always targetted at the right installation of MicroStation.

Use the New button to add a new environment variable. Select an environment variable and click the Edit button to change its value. In this example, I'm editing the MS variable …

Edit Environment Variable Dialog

You can't see the complete value because the text box is too short. Here's the complete string …

G:\PROGRA~1\BENTLE~1.5\Program\MICROS~1\

Notes …

Windows Short File Names

Windows supports long file names that may include spaces. However, bmake does not support paths that contain spaces. When using bmake it's best to use DOS-style short file names. You can find DOS short file names by opening a Windows command prompt and using the dir/x command.

The manual process to determine a short file name is tedious. It involves a lot of manual cut-and-paste operations.

Mangle.bat

Bentley Systems staffer Robert Hook posted a useful Windows batch file (mangle.bat) to generate the DOS path of a Windows long path. This saves those tedious manual cut-and-paste operations …

@echo off
:: Show mangled (DOS 8.3 format) path and file name of path provided,
:: or current directory if no arg provided
if /i {%1}=={} (for /f "tokens=*" %%d in ('cd') do echo %%~sd) else
  (for %%a in (%1) do echo %%~sa))

Environment Variable  MSMDE

You m define a Windows environment variable MSMDE. In a default installation, it points to the same location as MS (in other words, set MDE=MS). You can specify a different location for MDL development tools using this variable.

Environment Variable  toolspath (MicroStation V8i)

You should define a Windows environment variable toolspath for MicroStation V8i development. It points to the mdl folder.

	C:\Program Files\Bentley\MicroStation\MDL\
	

Environment Variable  BMAKE_OPT

You should define a Windows environment variable BMAKE_OPT. This defines a list of folders that contain MDL include files. In a default installation those folders are …

If you have the SDK installed in MicroStation's sub-folders (the default location on installation), then you can define the above variables in terms of the MS variable. In the Windows Environment Variables dialog, define BMAKE_OPT like this …

BMAKE_OPT=-I%MS%MDL\include -I%MS%MDL\include\stdlib

Environment Variable  MLINK_STDLIB

You should define a Windows environment variable MLINK_STDLIB. This defines a list of precompiled MDL library files that will be linked with your code by the MDL linker (mlink.exe).

You will always want to link your object files with builtin.dlo. Typically, you will additionally want to link with BentleyDgn.dlo (dgnfileio.dlo for versions prior to V8i) and toolsubs.dlo. You must specify the complete path to each library file. If your SDK installation is the default the the library folders are beneath the MicroStation folder and you can define the libraries like this …

MLINK_STDLIB=%MS%mdl\library\builtin.dlo %MS%mdl\library\BentleyDgn.dlo %MS%mdl\library\toolsubs.dlo

Environment Variable  PolicyFileMapMki

You should define a Windows environment variable PolicyFileMapMki when developing with MicroStation V8i.

Environment Variable  PolicyFileNamesMki

You should define a Windows environment variable PolicyFileNamesMki when developing with MicroStation V8i.


Environment Variable  PATH

You should define additions to the Windows environment variable PATH. PATH is likely to be defined already: it's needed by many applications so that Windows may locate their executable code and relevant DLL files. For more information about PATH, consult the Windows documentation.

It's important not to overwrite the existing definition of PATH. If you assign a value to path PATH=C:\Program Files\xxx your computer will probably not function properly. You need to define PATH by extending its existing definition, like this: PATH=%PATH%;C:\Program Files\xxx.

For MDL development, the folders to add to PATH are the MicroStation folder, which contains DLLs; the \MDL\bin folder, which contains the Bentley make tools (bmake.exe, mcomp.exe, etc.); and the \MDL\library folder, which contains precompiled object library files.

MicroStation V8i …

PATH=%MS%\mdl\bin;%MS%\mdl\library;%MS%;%PATH%

For versions of MicroStation earlier than V8i, you should also include the \JMDL\bin folder, which contains other Bentley tools.  …

PATH=%MS%\mdl\bin;%MS%\mdl\library;%MS%;%MS%\jmdl\bin;%PATH%

Visual Studio

You can use Microsoft Visual Studio with all versions of MicroStation V8. There are benefits to be gained by using code C++ compared to MDL, both in terms of performance and programmer productivity.

Visual Studio Versions

Use Visual Studio to build a Windows DLL that links to MicroStation. Alternatively, in the later versions of MicroStation you can use .NET tools to build an assembly that works with MicroStation. See this page about Visual Studio and MicroStation.


Bentley Development Shell

The development shell is a batch script that configures a Windows environment for MDL and C++ development. You can find this file in …

To use mstndevvars.bat, open a Windows command prompt and execute it. mstndevvars.bat sets up the Windows environment for you, by defining the environment variables described above. You'll find more about mstndevvars.bat in the MDL SDK documentation.

mstndevvars.bat makes it easy to set up the correct environment for compiling and linking an MDL application. The MicroStation installation process updated this batch file with the location of your MicroStation executable, and defines MS, BMAKE_OPT, and MLINK_STDLIB for you.

C++ Projects

Visual Studio

If you are using Visual Studio, then add the …\MicroStation\MDL\include path to the list of include folders in Project Properties.

If you are using the MicroStationAPI, then also add the …\MicroStation\MDL\MicroStationAPI path to the list of include folders in Project Properties.

Bentley Make (BMake)

If you are building using Bentley Make (bmake.exe), then add the path to the include list using the cincapnd.mki macro. In your make file, add something like this …

dirToSearch = $(MSMDE)mdl/MicroStationAPI/
%include cincapnd.mki

You can pass macro definitions to the compiler with the cdefapnd.mki include file …

nameToDefine = DEBUG
%include cdefapnd.mki

MicroStationAPI

The MicroStationAPI is a library of C++ interfaces. If you are writing a C++ application, then you need to tell the compiler the location of the files in the MicroStationAPI. You will find the MicroStationAPI header and impementation files in the MicroStationAPI sub-directory of the \MicroStation\MDL folder.

Pure MDL Projects

The development shell mentioned elsewhere assumes, with MicroStation XM and later, that you are have Microsoft Visual Studio installed. It doesn't use Visual Studio itself, but it does use Microsoft's C++ compiler and linker that are installed with Visual Studio. When building your project it attempts to launch the Microsoft C++ compiler (c1.exe).

This default behaviour is frustrating if you want simply to build a 'pure' MDL application — that is to say, a project written using the traditional source files and not using Visual Studio. The problem occurs because a line in mstndevvars.bat tests for the existence of Visual Studio. You may want to create a custom version of mstndevvars.bat that omits that test.

You can also add the following switches in your bmake file, or on the command line …

 -dNO_COMPILERS_MKI
 -dBUILD_USING_NoToolset

Those switches tell the Bentley build tools not to look for any native-code tools (i.e. Visual Studio).

For more information, take a look at the MDL Programmers' Guide, delivered with the MDL SDK.

Return to MDL articles index.