You can develop an application for MicroStation CONNECT using several different programming languages. Here are answers to questions about using the MicroStationAPI C++ Software Development Kit (SDK) and Microsoft Visual Studio.
Q Have you any hints about developing an application for MicroStation using the MicroStationAPI?
MicroStationDeveloperShell.bat
project, I get an error Attempting to build with VS 2015 but location is undefined!
What should I do to fix this? mdl.h
What should I do to fix this? A You may want to read about application project structure and consult the MicroStationAPI documentation files provides with the SDK. It's not always easy to understand how to configure your computer to build a MicroStation application. This article discusses several aspects of configuration to get you started.
A MicroStationAPI project contains a number of header files, implementation code files and resource data files.
The SDK provides tools that compile those code & resource modules into binary object files.
Linker tools merge your object files into an executable application (.dll
) file.
MicroStationAPI code lives in a set of source (.h
, .cpp
, .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.
Of course, Visual Studio is an excellent source code editor, as well as integrating the build tools (compiler, linker etc) into a single environment.
Some people like to use Visual Studio as a code editor and use bmake to buid their project. That may seem a curious approach, but it has some merit, especially when your project contains a lot of MicroStation resources as well as C++ code.
Bentley provides tools (executable files) for building MicroStation applications in the
\MicroStation\SDK\bin
folder.
You don't normally use those tools directly: prefer to invoke them using the Bentley Make (bmake
) utility.
A native application (.dll
) for MicroStation is delivered in two files …
.ma
extension. It contains …
.dll
extension. It contains …
MicroStationAPI implementation code is plain old C++
and lives in a source code (.cpp
) file.
Typically your code file will #include
a header (.h
) file
that defines various constants and C++
preprocessor macros common to all files in your project.
You compile MicroStationAPI source code with the Visual Studio C++ compiler.
Application dialog and message list files live in resource code (.r
) files.
Type resource definitions live in resource type (.mt
) 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 MicroStation resource code (.r
and .mt
files) with the Bentley rcomp
tool.
The result of MicroStationAPI code and resource compilation is a set of object files.
To create your executable application, those files are merged together using Visual C++ linker tools.
MicroStation message lists and dialogs are linked using the Bentley Systems resource linker
rlib
.
The Bentley Systems linker mlink
is used to create a resource binary file.
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 MicroStation, 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 C++ 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 …
The definitive source of environment variable settings for MDL development is the batch file MicroStationDeveloperShell.bat provided by Bentley Systems with the MicroStation SDK. See the section below for more information about that batch file.
When executed, MicroStationDeveloperShell.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 MicroStationDeveloperShell.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 MicroStationDeveloperShell.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 MicroStation CONNECT development …
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 the location for the SDK tools root |
BMAKE_OPT | Specifies default location for MicroStationAPI #include files |
WindowsSdkDir | Specifies root location for Windows Win32 header and library files |
WindowsSDKVersion | Specifies version of the Windows Win32 header and library files |
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\SDK\
Now the makefile expands the variable to create a valid folder definition …
C:/Program Files/Bentley/MicroStation/SDK/
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.
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 …
MicroStation Version | MicroStation Executable Location |
---|---|
MicroStation CONNECT | C:\Program Files\Bentley\MicroStation\SDK\ |
Define MS
in your computer's settings …
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 …
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 …
G:
, not the default drive C:
dir/x
command
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.
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))
MSMDE
You should define a Windows environment variable MSMDE
.
It points to the SDK location, which by default is
C:\Program Files\Bentley\MicroStation CONNECT\SDK
You can specify a different location for MicroStation development tools using this variable.
WindowsSdkDir
This variable points to the root folder that contains Windows platform SDK header and library files. The folder is created when you choose all options during Visual Studio installation.
The variable is set in a Windows shell by the MicroStation CONNECT tool
MicroStationDeveloperShell.bat
.
It is typically something like
C:\Program Files (x86)\Windows Kits\10\
WindowsSDKVersion
This variable is the name of a sub-folder in the root Windows platform SDK folder. The folder is created when you choose all options during Visual Studio installation.
The variable is set in a Windows shell by the MicroStation CONNECT tool
MicroStationDeveloperShell.bat
.
It is typically something like
10.0.10586.0\
The location of the Windows SDK header and library files is found by concatenating
WindowsSdkDir
, WindowsSDKVersion
and some text strings.
For example, the folder containing header files is …
%WindowsSdkDir%Include\%WindowsSDKVersion%\um
which, when expanded, turns out to be
C:\Program Files (x86)\Windows Kits\10\Include\10.0.10586.0\um
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 …
C:\Program Files\Bentley\MicroStation\MDL\include C:\Program Files\Bentley\MicroStation\MDL\include\stdlib
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%MSMDE%include\
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 C++ development, the folders to add to PATH
are the MicroStation folder, which contains DLLs;
the \SDK\bin
folder, which contains the Bentley make tools (bmake.exe
, mcomp.exe
, etc.);
and the \SDK\library
folder, which contains precompiled object library files.
PATH=%MSMDE%\bin;%MSMDE%\library;%MS%;%PATH%
You can use Microsoft Visual Studio to build a MicroStation CONNECT application. You can also use the Bentley make tool, bmake, which invokes the C++ compiler and linker provided with Visual Studio.
Use Visual Studio to build a Windows DLL that links to MicroStation. You must use the correct version of Visual Studio to ensure that your app. is compatible with MicroStation.
Visual Studio 2017 is not currently supported by the MicroStation CONNECT SDK.
Installing Visual Studio for C++ development is not as straightforward as it used to be. Please read these notes about Visual Studio installation
The development shell is a batch script that configures a Windows environment for C++ development. You can find this file in …
%MSMDE%MicroStationDeveloperShell.bat
To use MicroStationDeveloperShell.bat
, open a Windows command prompt and execute it.
MicroStationDeveloperShell.bat
sets up the Windows environment for you,
by defining the environment variables described above.
You'll find more about MicroStationDeveloperShell.bat
in the MicroStationAPI SDK documentation.
MicroStationDeveloperShell.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.
If you are using Visual Studio,
then add the …\MicroStation\SDK\include
path to the list of include folders in
Project Properties.
Your source implementation (.cpp
) file should have a list of MicroStationAPI headers beginning something like this …
#include <Mstn/MdlApi/mdl.h>
That #include
statement assumes that the compiler has a directive to find the root
include folder, which is ..\SDK\include
.
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)include/ %include cincapnd.mki
You can pass macro definitions to the compiler with the cdefapnd.mki
include file …
nameToDefine = DEBUG %include cdefapnd.mki
The MicroStation Development Language (MDL) was part of MicroStation V4 released in 1993. MDL was a C-style language, supported on versions of MicroStation up to V8i.
With MicroStation CONNECT you can write a project using one of several languages. You can't, however, write a C-style implementation using MDL. MDL is not supported by MicroStation CONNECT.
Return to programming articles index.
Post questions about MicroStation programming to the MicroStation Programming Forum.