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".
The relationship between the terms can be summarized as follows:
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:
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.
An MDL program can be unloaded by one of the following:
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
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.
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.
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.