[转贴]：一篇关于MDL的FAQ(全英文)

风过花零

Building MDL Applications
-------------------------------------------------
Question 1: How do I compile an MDL application for MicroStation 95 on Windows 3.1 with Win32s?

Answer: You need to compile the application with the MicroStation NT MDL tools running on either the Windows NT or the Windows 95 operating system.
History: With MicroStation V5, MDL applications developed in DOS could be used in either DOS or Windows 3.1x, since the same 32-bit DOS executable was used for operation in DOS and Windows 3.1x, the latter using "Windows Connection."
MicroStation 95 for Windows uses the same executable for operation in Windows 3.1x, Windows 95, and Windows NT. Therefore, MDL applications compiled for Windows 95/NT will run on all Intel-based Windows platforms. MDL applications compiled specifically for DOS will run only on the DOS platform and not in MicroStation 95 running under Windows 3.1x. Although the same MicroStation 95 executable runs in Windows 3.1x, Windows 95, and Windows NT, the MDL compilation environment will only work in Windows 95 and Windows NT. Therefore, you need to compile your MDL applications with the MicroStation 95 NT MDL tools running on either Windows NT or Windows 95.


Question 2: How can I conditionally compile my code based on the MicroStation version?
Answer: You can use the MicroStation variable MSVERSION to conditionally compile code for a specific version of MicroStation.
For example:

    #if defined (MSVERSION) && (MSVERSION >= 0x551)
        /* code new to MicroStation 95 (Version 5.5.1) and higher */
   #endif
    #if defined (MSVERSION) && (MSVERSION >= 0x550)
        /* code new to MicroStation PowerDraft (Version 5.5.0) and higher */
    #endif

See the delivered MDL example V551NEW for a sample usage of MSVERSION. V551NEW is delivered in the \ustation\mdl\examples\V551new\ subdirectory.
See also Question 23 for a discussion of run-time version checking.

Question 3: How do I resolve a "different levels of indirection" error message output by the MDL compiler?
Answer: This error message means that the MDL compiler found a mismatch of the levels of indirection between variables in:

an assignment statement
a function's call and declaration
a comparison statement

Example 1:
The following lines of code will produce this error:
        int color;
             int *colorTest;
             colorTest = color;

In this case, assume that we want to save the address of a memory area which contains a color value. We can resolve this error by putting a "&" in front of color in the assignment statement.
For example:

            colorTest = &color;

Example 2:
I am getting this error on the line of source code with the function call to mdlParams_setActive after I have included the msmisc.fdf to remove compiler warnings.

            #include <msmisc.fdf>
             int color = 1;
             mdlParams_setActive(color, ACTIVEPARAM_COLOR);

To resolve the error message with mdlParams_setActive, you need to cast the color parameter to the type expected in the FDF file. The address of the color variable should not be used because the MDL Function Reference manual states that the parameter type is int for parameter name ACTIVEPARAM_COLOR.
Function declaration from MSMISC.FDF:

            int        mdlParams_setActive
             (
             void        *param,
             int        paramName
             );

In the FDF file, the type of the first parameter to this function is "void *" and therefore, you must cast the color variable as type "(void *)" as shown below.

        #include <msmisc.fdf>
             int color = 1;
             mdlParams_setActive((void *)color, ACTIVEPARAM_COLOR);
See your standard ANSI C manual for information about the cast operator.

Question 4: How do I eliminate compiler warnings I get when recompiling my MicroStation V5 MDL application with MicroStation 95/MicroStation SE?
Answer: There are a number of problems which may cause compiler warning or error messages:

Called functions do not have function declarations or prototypes before they are called.
See question 5 for a discussion of resolving this message.
A user defined function is missing a return statement.
This warning message is output when a function with a non-void return type does not have a return statement. To resolve this problem, go to the function near the line number specified in the compiler warning, and add a return statement as the last statement of the function. Ensure that you are returning the proper type and value to the caller of this function. Alternatively, if the function does not need to return a value to the caller, change the function's return type to void.
Note: Any function that does not have a return type is assumed to have an int return type.
A function's type does not match its return type.
To resolve this problem, change either the function type or the types of values being returned.
Function parameter type does not match the parameter type specified in the function's declaration.
See question 3 above for a discussion of this problem.
An alternative to changing source code as discussed above is to use MCOMP compiler pragmas to turn off detection and reporting of these warnings and errors. For more information on these compiler pragmas, see the "Pragmas" subtopic in chapter 5 of the "MDL Help" (\ustation\help\english\mdehelp.hlp or mdehelp.hc) online help file delivered with MicroStation 95.

Question 5: What does the warning message "XXXX does not have an ANSI function declaration" mean?
Answer: This message means that the MDL compiler (MCOMP) did not find a function declaration or prototype for a function that was called in the source file (*.MC).
This function can be either:

a standard C function
In this case, you need to include the standard C header file which contains the function declaration for the C function. Consult your C manual to determine the header file which contains a specific C function. Alternatively, perform a file search (such as grep.exe) for the C function in question in the \ustation\mdl\include\stdlib\ subdirectory.
For example, assume that "XXXX" above is strcpy. To find the header file (*.H) which contains strcpy, submit the following grep command line from the DOS prompt:
             c:\ustation\mdl\include\stdlib\> grep strcpy *.h
The output of this command is:
             File STDLIB\STRING.H:
             char    *strcpy (char *, char *);
To resolve this warning, you need to include STRING.H in you MDL source file (*.MC).
For example:
             #include <string.h>
a standard MDL function
In this case, you need to include the MDL function declaration file (*.FDF) which contains the function's declaration. The FDF files are located in the \ustation\mdl\include\ subdirectory when installed with the MDL environment. You can use a file search utility such as grep.exe to find the FDF file which contains a given function.
For example, assume that "XXXX" above is mdlParse_loadCommandTable. To find the FDF file which contains mdlParse_loadCommandTable, submit the following grep command line from the DOS prompt:
             c:\ustation\mdl\include\> grep mdlParse_loadCommandTable *.fdf
The output of this command is:
             File MSPARSE.FDF:
             void *mdlParse_loadCommandTable /* <= Pointer to command table */
             void *mdlParse_loadCommandTableByNumber /* <= Pointer to command table */
To resolve this warning, you need to include MSPARSE.FDF in you MDL source file (*.MC).
For example:
             #include <msparse.fdf>
a user defined MDL function In this case, you need to either:
Add a function declaration or prototype at the top of the source file in which the function is called.
Include a user defined FDF file which contains the function's declaration.
Reorder the function calls and declarations in the source file so that the function declaration appears above or before a call to the function.

--------------------------------------------------------------------------------
Graphical User Interface (GUI)

Question 6: What new GUI features were introduced in MicroStation 95?
Answer: There are several new GUI features which were added to MicroStation 95 and MicroStation PowerDraft:

Tool boxes
Tool tips and descriptions
List box enhancement for displaying icons
Newstyle file open/create dialog boxes
Newstyle message dialog boxes
Busy and track bar items for use with mdlDialog_busyBarXXX and mdlDialog_trackBarXXX
Command item list resource (CmdItemListRsc) to tie a command's popdown items to the command number and not to its icon resource.

Question 7: Is the tab folder item in the "Modify Pen Table" dialog box a new dialog item?
Answer: No, the tab folder in this dialog box is implemented with a generic item. A standard tab item may be available in the future.

Question 8: Why aren't tool tips and descriptions displayed for the icons in my icon command palette?
Answer: Tool tips and descriptions are only supported for icons and other dialog items which are in a tool box or an icon command frame. Assuming that you have updated your icon command resource or dialog item's resource to add the necessary extended attributes for tool tips and descriptions, you need to convert you icon command palettes to icon command frames or tool boxes in order to get tool tips and descriptions. For more information on converting icon command palettes to tool boxes, see the section "Converting Icon Palettes to Tool Boxes" in the MicroStation 95 MDL Supplement. For more information on adding tool tips and descriptions to icon commands and dialog items, see the "Incorporating tool tips and descriptions" section in the MicroStation 95 MDL Supplement.

Question 9: How do I send the focus to the key-in area?
Answer: You can use the command "FOCUS COMMAND" (CMD_FOCUS_COMMAND from cmdlist.h) to send focus to the key-in area.
Alternatively, you can use mdlDialog_keyinWindowGet to get a dialog pointer of the dialog box which contains the key-in area. The mdlDialog_keyinWindowGet function call will return a pointer to the command window in the command window style interface. It will return a pointer to the key-in browser in the MicroStation 95/MicroStation SE and PowerDraft status bar interfaces if the dialog is open and will return NULL otherwise. You can then send focus to an item in the dialog box using mdlDialog_focusItemIndexSet.

Question 10: Will I need to change any prompt or error messages to account for different user interface styles?
Answer: The current command name and prompts are handled the same way in either interface style. The mdlOutput_xxx calls recognize the interface style automatically. However, the MicroStation 95/MicroStation SE and PowerDraft status bar interface only has 4 distinct message regions (instead of 5 with the command window). The MESSAGE and STATUS fields overlay each other so it is possible to have a message overwritten. See the V550NEW delivered MDL example for a demonstration of the locations of various message fields.

Question 11: What is the proper way of finding the main MicroStation menu so that my application can dynamically insert its menu?
Answer: Use mdlDialog_menuBarGetCmdWinP which returns that RawItemHdr of the main menu. This pointer can then be utilized by mdlDialog_menuBarInsMenu. Alternatively, use mdlDialog_menuBarAddCmdWinMenu to insert into the "Applications" menu.

Question 12: How do I get the current user interface style?
Answer: Compare the return value of mdlDialog_statusAreaGet to NULL. mdlDialog_statusAreaGet will return a pointer in the MicroStation default and PowerDraft status bar style interfaces and will return NULL in the command window style interface.
Alternatively, check the value of the userPrefsP->extFlags.useCommandWindow preference.

Question 13: My application uses mdlDialog_find with userPrefsP->cmdWindowID as the dialog ID. How will this affect my application?
Answer: Existing applications that directly manipulated the command window using this method may only work properly in the V50 workspace until they are updated.

Question 14: My application customizes the command window via MS_CMDWINDRSC. Will this still be supported?
Answer: There is no command window in the MicroStation 95/MicroStation SE or PowerDraft status bar interfaces so this cannot be supported. This will still be supported in the V50 workspace for MicroStation 95. MS_CMDWINDRSC will probably not be supported post-MicroStation 95.
Note: If this configuration variable is not set, MicroStation will not even attempt to open the command window with the identifier specified in the user preference variable userPrefsP->cmdWindowID.

Question 15: In MicroStation V5, the pointer to the command window dialog box was passed to the SYSTEM_CMD_WINDOW_OPEN asynchronous function. What happens now?
Answer: The pointer to the overall title bar (which contains the main menu bar) dialog is passed. The "timing" of the asynchronous call is still the same regardless of whether or not the user actually chooses the command window style interface.


Question 16: What dialog attributes are necessary to make a dockable icon command frame?
Answer: To make an icon command frame dockable, you at least need the dialog attribute DIALOGATTR_DOCKABLE.
Here are the dialog attributes that MicroStation uses for its dockable icon command frames:

DIALOGATTR_DEFAULT | DIALOGATTR_NORIGHTICONS | DIALOGATTR_AUTOOPEN |
DIALOGATTR_DOCKABLE | DIALOGATTR_BOTHVIRTUAL
-------------------------------------------------------------------------------
Miscellaneous

Question 17: What does the error message "Not an MDL Application for this platform" mean?
Answer: This message means that the MDL application that you are attempting to load was compiled on a different MicroStation platform than the platform on which you are currently running. You will need to recompile the application with the compilers of the currently running platform.

Question 18: Can an MDL application communicate with a BASIC macro or vice versa?
Answer: No two-way messaging interface is available, but an MDL application and a BASIC macro may communicate by:

sharing information through a global memory area. This technique is demonstrated in the MDL example \ustation\mdl\examples\mdlbasic\ and \ustation\macros\mdlbasic.ba*.

executing an MDL application's commands from the BASIC macro.
executing a start macro command from the MDL application.
sending a message to an MDL application from a BASIC macro using the BASIC function call MbeSendAppMessage.

Question 19: Will MDL applications built with MicroStation V5 run in MicroStation 95/MicroStation SE?
Answer: Yes, but with the following possible restrictions:

The application must have been compiled for the same MicroStation platform.
Applications which rely on the command window being present may fail in the MicroStation 95/MicroStation SE default interface since the command window is not available by default.
Applications which use the PlotStat plotting structure or the user preferences structure to save user preferences may fail since these structures have changed in size since MicroStation V5 and MicroStation PowerDraft.
Fixes in MDL Libraries for bugs found when running an application in MicroStation 95/MicroStation SE will not be available until the application is rebuilt with the MDL Library which contains the fix.

Question 20: Has the MDE Environment been enhanced?
Answer: Yes. The Resource Development Environment (RDE) tool was added to MicroStation 95. RDE is a tool for creating and modifying resource source files (*.R) and header source files (*.H). In previous versions of MicroStation the BUILDER application only allowed the creating and editing binary resource files (*.RSC) which were then decompiled into resource source files (*.R) using the SOURCER application. RDE eliminates the need to use SOURCER to decompile source code since resource modifications can be made directly to a resource source file.


Question 21: What new functions were introduced in MicroStation 95?
Answer: There are a few new function groups added to MicroStation 95. Most of the new functions were added to existing function groups.

mdlBasic_xxx - MicroStation BASIC Interface Functions
mdlHview_xxx - Sectioning and Hidden Line Viewing Functions
mdlLicense_xxx - License Management Functions
mdlRastRef_xxx - Raster Reference Functions
For more information on new MDL functions in MicroStation 95, see the MDL help file (mdehelp.hlp or mdehelp.hc). Once the help file is opened in the help viewer and the table of contents are displayed, choose "MicroStation 95 Supplement" followed by "New MDL Functions".

Question 22: Was MicroStation BASIC designed to replace MDL?
Answer: No. MicroStation BASIC was designed to replace User Commands (UCMs). MDL is still the programming language of choice for MicroStation application developers. In the "MicroStation 95 BASIC Guide", see chapter 6, titled "The MDL Alternative" for a discussion of the use of BASIC and MDL.


Question 23: How can I determine the MicroStation version at run-time so that I can execute different code based on the version number?
Answer: You can use the MicroStation TCB variable tcb->ustn_version to determine the currently running version of MicroStation.
For example:
     if (tcb->ustn_version >= 0x551)
             {
             /* code to execute in MicroStation 95 (Version 5.5.1) and higher version */
             }
See the delivered MDL example V551NEW for a sample usage of tcb->ustn_version. V551NEW is delivered in the \ustation\mdl\examples\V551new\ subdirectory.
See also Question 2 for a discussion of compile-time version checking.

Question 24: How can I determine whether an application is currently running in MicroStation, PowerDraft, or MicroStation Review?
Answer: You can look for a MicroStation configuration variable to determine the product which is currently running.

Configuration Variable Meaning if variable is set
_MICROSTATION Running in MicroStation
_MSDRAFT Running in PowerDraft
_MSREVIEW Running in MicroStation Review

For example:
/* running MicroStation? */
if (SUCCESS == mdlSystem_getCfgVarAtLevel (NULL, "_MICROSTATION", 0, CFGVAR_LEVEL_PREDEFINED))
            {
             /* running MicroStation */
             }
/* running MicroStation PowerDraft? */
else if (SUCCESS == mdlSystem_getCfgVarAtLevel (NULL, "_MSDRAFT", 0, CFGVAR_LEVEL_PREDEFINED))
        {
             /* running MicroStation PowerDraft */
             }
/* running MicroStation MicroStation Review? */
else if (SUCCESS == mdlSystem_getCfgVarAtLevel (NULL, "_MSREVIEW", 0, CFGVAR_LEVEL_PREDEFINED))
             {
             /* running MicroStation MicroStation Review */
             }