Bentley Communities
Bentley Communities
  • Site
  • User
  • Site
  • Search
  • User
  • Welcome
  • Products
  • Support
  • About
  • More
  • Cancel
MicroStation
  • Product Communities
  • More
MicroStation
MicroStation Wiki Running MDL Applications
    • Sign in

    • +MicroStation Wiki
    • +Administration Wiki
    • +Annotations Wiki
    • +Bentley View Wiki
    • +MicroStation PowerDraft
    • -Programming Wiki
      • A class to help create and modify text element
      • A Complete Example
      • A MicroStation VBA Example With Bentley ProjectWise
      • AddIn Development Using VB.NET
      • C# .NET Template with IPrimitiveCommandEvents Class
      • Capturing Graphics in Dynamic Views
      • Compiling MDL Applications
      • Database Manipulation
      • Debugging Native Code MDL Applications
      • Developing Code in VBA
      • Developing MicroStation Applications For DWG Files
      • Drag and Drop in MicroStation
      • Error: "Cannot save changes to VBA project 'Support' because it is read-only"
      • Getting And Setting Elements Using Graphic Groups In VBA [CS]
      • Getting Started with Visual Basic
      • How To Write A Recursive Routine In MicroStation VBA [CS]
      • Introducing Segment3D Methods In MicroStation V8 2004 Edition
      • Known issues in MDL and MicroStationAPI
      • Launching VBA Applications As Initapps Or Dgnapps [CS]
      • Learning MicroStation Addins Step by Step
      • MDL - Getting Started With XAttributes In MicroStation V8 XM Edition
      • MDL - Native Code Application Development
      • MDL Or MicroStation BASIC Choosing The Right Tool [TN]
      • MFC Dialog And Native Window Support
      • Microsoft Office VBA Patch Utility
      • MicroStation BASIC FAQ
      • MicroStation BASIC Limits [FAQ]
      • MicroStation Developer Documentation and Example Code
      • MicroStation Programming Advice
      • MicroStation SDK
      • MicroStation V8 Programming Tools Readme
      • MicroStation V8 VBA Programming Resources [CS]
      • MicroStation V8 XM Edition View Code Updates
      • MicroStation VBA Resources Revisited [CS]
      • Migrating Dimension Code To MicroStation V8
      • Migrating MDL Applications To Native Code
      • Mouse Wheel Events And The Visual Basic 6.0 IDE
      • Porting MDL Applications To MicroStation V8
      • Reading Elements From A Microsoft Access Database With VBA [CS]
      • Running MDL Applications
      • Scanning For MicroStation V8 Elements In VBA [CS]
      • Unleash A Workspace Wizard Automating Workspace Creation With MicroStation V8 And VBA [CS]
      • Using VBA To Detect The Current Or Last Used Command
      • Using VBA To Programmatically Export A VBA Project [CS]
      • Using VBA To Programmatically Import A VBA Projects Components And References [CS]
      • VBA -- Creating A Complex Application
      • VBA Interface Error: failed creating the comp manager - 0x80040583
      • VBA interface error: unable to get IDE
      • vba recording
      • Working With Levels In MicroStation VBA [CS]
      • Writing An MDL Application To Output Custom Placemarks To Google Earth
      • [V8i C++] PointCloud IPointCloudChannelDisplayHandler
    • +Visualization Wiki

     
     Questions about this article, topic, or product? Click here. 

    Running MDL Applications

    This section describes how an MDL program is loaded, how its commands are started, and how it is unloaded.
    MDL distinguishes between programs, application files and tasks. These terms are all defined in "MDL Applications".

    Relationships Between Terms

    The relationship between the terms can be summarized as follows:

    • MDL loads and unloads programs.
    • A program is loaded from an application file. An application file contains one or more programs.
    • When a program is loaded, MDL creates a task.
    • When a program is unloaded, MDL destroys the task.

    Loading an MDL Program

    All methods of loading an MDL program allow an application filename and task ID to be specified, but only the application filename is required.

    When the application filename is specified, only the root of the filename is required, although the full filename can be provided. When trying to locate the file, MDL looks for a file with extension .ma or .rsc. It looks for the file in the paths specified by the environment variables MS_EXE and MS_MDL. If example is specified as the root of the application filename, MDL looks for the files in the following order:

    1. example.ma in the directories specified by MS_EXE.
    2. example.ma in the directories specified by MS_MDL.
    3. example.rsc in the directories specified by MS_EXE.
    4. example.rsc in the directories specified by MS_MDL.

    If the task ID is not specified, MDL strips the file extension and path from the full file specification to derive the root filename. It converts the root filename to upper-case and uses the result as the task ID. Once MicroStation has the task ID, it uses it as follows, regardless of whether the task ID is generated or specified. MicroStation tries to load the program that has the required task ID. If the application file does not contain a program with that task ID, MicroStation then tries to load a program that does not have a constant task ID. If it finds one, it loads the program and assigns the
    task ID.

    An MDL program can be loaded by one of the following:

    • An MDL LOAD command.
    • Selecting Load from the MDL Applications menu.
    • Another MDL task calling the built-in function mdlSystem_loadMdlProgram.
    • MicroStation initialization. MicroStation loads programs specified by the MDL environment variables MS_INITAPPS and MS_DGNAPPS.
    • An application startup element (type 66) in the design file.

    The syntax for the MDL LOAD command is as follows:

    MDL LOAD [DEBUG | NODEBUG] [,task ID] [parameters]

    Any number of parameters can be specified. The parameters are separated by blanks and supplied to the MDL task started by the MDL LOAD command.

    Typically, the simplest form of the MDL LOAD key-in is used. For example, to load the example application, key in MDL LOAD .

    The environment variables MS_DGNAPPS and MS_INITAPPS specify programs to load during MicroStation initialization. Each environment variable can specify a list of programs. If a list specifies more than one program, the specifications must be separated by semicolons. The format of a program specification is as follows:

    application-file-name[,task ID][/d]
    Typically, only the application filename is used. /d tells MDL to activate the debugger after loading the program. An example of a specification is as follows:

    MS_DGNAPPS=calculat;qdim;myapps,macros/d
    MS_INITAPPS specifies MDL programs to be loaded before MicroStation opens the design file or enters graphics mode. These programs are typically "front-end" programs used to select or manage files. See "Using MS_INITAPPS Applications" for more information on these programs.

    MS_DGNAPPS specifies MDL programs to be loaded immediately before MicroStation opens the first design file. Use MS_DGNAPPS to specify MDL programs that you want loaded automatically when you use MicroStation.

    An application startup element in the design file specifies a program to be loaded when the design file is loaded. When MicroStation opens a design file, it searches for application startup elements when it looks for the TCB and other control elements. If it finds a startup element, it queues an MDL LOAD command that loads the program specified in the element with any command line arguments stored there. The MDL LOAD commands queued this way are processed immediately after the file displays. See mdlSystem_createStartupElement for more information.

    After loading an MDL program, MicroStation tries to execute the task's main function. The main function is optional and is needed only if the task needs to perform initialization. If the task does not contain a main function or if a main function does not explicitly call an exit function, the task remains resident waiting to process commands. If the task exists when the load request occurs and the task has a reload function, MDL calls the reload function. (See userSystem_reloadProgram for more information on reload functions).

    The arguments to main are similar to those for standard C. argc contains a count of the number of arguments. argv is an array of pointers to the arguments. argv[0] points to the name of the MDL application file. argv[1] points to a string specifying the source of the load request. If the program is loaded as the result of an environment variable (such as MS_INITAPPS), argv[1] points to the name of the environment variable. If the program is loaded as the result of an MDL LOAD command or from MDL Applications menu, argv[1] points to the string "USER". If the program is loaded as the result of an mdlSystem_loadMdlProgram call, argv[1] points to the string "MDLTASK". If the program is loaded as the result of an application startup element, argv[1] points to the string "STARTUP". The remaining arguments are provided as part of the load request.

     

    Unloading an MDL Program

    An MDL program can be unloaded by one of the following:

    • An MDL UNLOAD command.
    • A call to exit or mdlSystem_exit from the MDL task.
    • MicroStation shutting down.
    • A fatal error in the MDL program.
    • A call to mdlSystem_unloadMdlProgram from an MDL task.
    • The MDL debugger QUIT command.

    When unloading an MDL program, MicroStation first calls the task's unload user hook if the task has specified one. (See userSystem_unloadProgram for more information.) The user hook can reject the unload request. If the unload request is not rejected, MicroStation cleans up most of the task's resources such as open files and allocated memory. There are specific items that are not cleaned up: element descriptors and string lists. An MDL program must specifically free all of the string lists and element descriptors created for it. Use the mdlElmdscr_freeAll function to free element descriptors and the mdlStringList_destroy function to free memory allocated through string list functions.

    Once all memory is cleaned, MicroStation removes the task from memory. Finally, if the unloaded program was started by another MDL task, the other task is notified.

    The syntax for the unload command is as follows:

    MDL UNLOAD

    Using Commands in MDL Tasks

    This section describes how to declare a function as an MDL command and how to start the command. See "State Control Functions" for information on command organization.

    When a function is declared, it can be designated as a command. To designate a function as a command, specify that the function's name is available as a command name, specify a list of command numbers to be associated with the function, or both.

    To specify that a function's name is available as a command name, specify cmdName before the function name. To associate command numbers with a function, specify cmdNumber and a list of command numbers after the argument declarations for the function. The following are examples of the syntax for command declarations. For each example, the executable portion of the function would follow the function declaration, but is not shown here. Also, CMD_TEST1 and CMD_TEST2 are macros defined as integer constants.

    cmdName void testCommand(char *unparsedP)
    void testCommand () cmdNumber CMD_TEST1, CMD_TEST2
    cmdName testCommand(char *unparsedP) cmdNumber CMD_TEST1
    If a function's name is available as a command name, the command can be started with an MDL COMMAND key-in. The syntax for the MDL COMMAND key-in is:

    MDL COMMAND [task ID,]
    If multiple tasks are loaded and these tasks have commands with the same name, task ID gets the command from the intended task. Otherwise, only command name is required.

    If the task ID and command name are specified, a comma must separate them. Otherwise, MDL interprets the first string as the command name and the second string as a parameter. The key-in MDL COMMAND TASK,TESTCOMMAND attempts to start the TESTCOMMAND (that is, execute the testCommand function) in the TASK. The MDL COMMAND TESTCOMMAND PARAMS key-in starts the CMD command, supplying a pointer to PARAMS as the argument unparsedP.

    If a task has a command table loaded and the task's commands have command numbers associated with them, the task's commands can be accessed with the commands specified in the command table. When this method is used, the key-in consists entirely of keywords specified in the application command table. MDL COMMAND should not be part of the key-in. See "Compiling an Application Command Table", for more information.

     

    Aborting an MDL Task

    While a task is running, it can be aborted by pressing or . Pressing these keys lets you regain control from a hung MDL task. A task can inhibit this capability.

    See mdlSystem_userAbortEnable, mdlSystem_extendedAbortEnable and mdlSystem_extendedAbortRequested for more information.

     

    Using MS_INITAPPS Applications

    Many times an MDL application may need to present a controlled environment to the user upon startup. The application uses MicroStation's graphical user interface to let the user select a project or other preferences relating to the work session. Alternatively, an MDL application can operate MicroStation in a batch mode, where no graphics appear on the screen and no user interaction occurs. The MS_INITAPPS environment variable lets MicroStation accomplish both of these objectives.

    As described above, programs specified with the MS_INITAPPS environment variable are started when MicroStation is activated. These programs are started after MicroStation has initialized internal variables for MDL and other necessary components and before MicroStation has entered graphics mode. The MDL_INITAPPS programs are started in the order specified in the environment variable. While a list of programs are allowed as initial applications, only one is needed.

    The MS_INITAPPS program's main function is called with argv[1] pointing to MS_INITAPPS. The program uses this method of calling the function to determine that it is starting as an initial application, rather than being invoked by the user during normal MicroStation operation. argv[2] ...argv[argc-1] are the command line arguments that MicroStation was started with. Command line arguments that will be processed by the MS_INITAPPS applications (and ignored by MicroStation) start with -i.

    When the program is designed to provide a graphical front end to the user, the application should follow these steps:

    1. Put MicroStation in graphics mode by calling mdlSystem_enterGraphics.
    2. If the program will remain loaded while the user is working on the design file, it should designate a function to be called when MicroStation reloads it by calling mdlSystem_setFunction.
    3. If the front-end program will let the user specify a design file on the MicroStation command line, the program should examine the command line arguments that started MicroStation and determine whether a design file was specified. (The design file name will be the only command line argument that does not start with the `-' character). If a design file was specified, the program should skip the remaining steps and go directly to step 6, where MicroStation resumes control.
    4. Perform any other initialization code, such as setting up other user functions to be called in response to MicroStation events.
    5. Display the application's opening dialog box
    6. Return control to MicroStation by returning from main.
    The front-end program regains control when its dialog hook functions are called. Presumably, the program will let the user select a design file to work on in MicroStation. To accomplish the transition from the front-end program to MicroStation, the program follows these steps:

    1. Close its dialog box using the mdlWindow_close function.
    2. Enter the user's chosen design file using mdlSystem_newDesignFile.
    3. Either exit entirely (using exit) or relinquish control to MicroStation and wait for its reload program user function to be called. This function tells the program to reopen its dialog box and once again supervise interaction with the user.
    If the MS_INITAPPS program exits without first opening a design file, MicroStation terminates and returns to the operating system prompt.

    If, on the other hand, an MS_INITAPPS program is designed for batch processing in MDL and will not use graphics or interact with the user, it should follow these steps:
    1. Process the command line arguments that MicroStation is started with, particularly the command line switches starting with -i.
    2. Process the design file(s) as needed, using mdlSystem_newDesignFile to load them.
    3. Close the last design file using mdlSystem_closeDesignFile.
    4. Call exit without a design file active to cause MicroStation to return to the operating system prompt.

    • Share
    • History
    • More
    • Cancel
    • Dan Koval Created by Bentley Colleague Dan Koval
    • When: Thu, Sep 5 2013 4:30 PM
    • Revisions: 1
    • Comments: 0
    Recommended
    Related
    Communities
    • Home
    • Getting Started
    • Community Central
    • Products
    • Support
    • Secure File Upload
    • Feedback
    Support and Services
    • Home
    • Product Support
    • Downloads
    • Subscription Services Portal
    Training and Learning
    • Home
    • About Bentley Institute
    • My Learning History
    • Reference Books
    Social Media
    •    LinkedIn
    •    Facebook
    •    Twitter
    •    YouTube
    •    RSS Feed
    •    Email

    © 2022 Bentley Systems, Incorporated  |  Contact Us  |  Privacy |  Terms of Use  |  Cookies