Questions similar to this appear on the Bentley Discussion Groups. These problems appeared in the MDL discussion group.

Q   MDL developers often want to trace the variables in an application during development …

• How do I show the state of my MDL application?
• How do I capture the value of a variable?
• I can see the text from mdlOutput_status (msg) but I can't copy it.
• Can I ask my application's user to provide more information as my program executes?
• Can I show a dockable information window?
• How do I open the Message Center programmatically?

A  MicroStation's NotificationManager (also known as the Message Center) provides a way for you to communicate with your user. You can create terse and verbose messages with various priorities: simple messages, warning, or alerts. Your user can copy messages (which they could never do with the old DMSGS message window). You can write messages that are only seen when the user has enabled Debug in the Message Center.

MicroStation/J and earlier provide a programmer's DMSGS message window to which you send text using mdlDialog_dmsgsPrint (msg). In normal MicroStation operation the user doesn't see the DMSGS window.   MicroStation V8 continues to support the DMSGS window.

MicroStation Message Center for Developers

MicroStation V8 sends many messages to the  Message Center.  Status and message information are sent there.   As a developer, you should investigate the Message Center: it has a number of useful features …

• The Message Center is resizeable
• The Message Center is dockable
• The horizontal splitter in the Message Center can be moved
• When you select a message in the Message Center its content is copied to the lower panel
• You can select & copy text in the lower panel
• If you right-click the Message Center, you pop a settings dialog
• You can specify the number of lines captured by the Message Center
• You can specify whether the Message Center displays debug messages
• You can save the content of the Message Center to a text file

Sending a Message

You send a message to the Message Center using the mdlOutput_messageCenter () function. The function takes four arguments  …

1. Message priority: MESSAGE_ERROR, MESSAGE_WARNING, MESSAGE_INFO,and MESSAGE_DEBUG
2. Brief message
3. Long message
4. Pop alert dialog

The message priority constants are #defined in <msdef.h>.  The two messages are typically char* buffers.   The final argument is a BoolInt flag that tells MicroStation to pop a modal dialog with your message.

Here's an example  …

void messageCenter_showFile (char const* fileSpec, BoolInt debug, BoolInt alert)
{
    char terse   [MAXNAMELENGTH]; // buffer for brief message 
    char verbose [MAXQUOTEDFILELENGTH]; // buffer for long message 
    char title   [MAXNAMELENGTH];
    char ext     [MAXEXTENSIONLENGTH];
    char name    [MAXNAMELENGTH];

    int  priority = debug? MESSAGE_DEBUG: MESSAGE_INFO;

    mdlFile_parseName (fileSpec, NULL, title, ext);
    mdlFile_buildName (name, NULL, NULL, title, ext);

    // Format brief and long messages 
    sprintf (terse, "File '%s'", name);
    sprintf (verbose "File path '%s', fileSpec);

    // Send to Message Center: pop dialog if 'alert' is TRUE 
    mdlOutput_messageCenter (priority, terse, verbose, alert);
}

The difference between the brief and long messages is that the brief message is always displayed in the Message Center, but the long message is shown in the lower panel only when the user selects the brief message in the top panel.

MicroStation messages are sent with one of the first three priorities: error, warning, or information. Each has a distinctive icon.  The final priority is debug, available exclusively to you as an MDL (or VBA) developer.  Debug messages are shown only when the debug option is checked in the Message Center's option dialog.

Message Center Properties

When the user right-clicks the Message Center the properties modal dialog opens. She can specify …

1. Whether or not to see debug messages
2. How many lines of text the Message Centershould buffer
3. A save file for the Message Center text content

The Message Center's line buffer size (Number of Messages setting) is a little idiosyncratic.  When you change Number of Messages, the buffer size changes immediately.  However, when you exit and restart MicroStation, the buffer always starts with 50 lines, irrespective of how many lines you specified. The trick is to modify this number before attempting to capture a large amount of text.

Open the Message Center Programmatically

The Message Center is a MicroStation dialog box. Whether using MDL or the MicroStationAPI, you can open it with this one-liner …

    	mdlDialog_open (NULL, DIALOGID_MessageCenter);

If writing VBA, then you must declare that MDL function before calling it …

Declare Function mdlDialog_open Lib "stdmdlbltin.dll" ( _
	ByVal rFileH As Long , _
	ByVal resourceId As Long ) As Long
Const DIALOGID_MessageCenter As Long = -401	'	From <dlogids.h>
    	…
    	mdlDialog_open 0, DIALOGID_MessageCenter

Saving Messages

Another option you have when you right-click the Message Center is to Save Messages.

When you choose this option, you see a File Save dialog, which lets you copy the entire message buffer to a text file.

Debug Messages

Your code can place messages in the Message Center using the MESSAGE_DEBUG priority. Your users won't see MESSAGE_DEBUG messages unless they have enabled the Message Center's debug option. Therefore you can use MESSAGE_DEBUG messages to get more information from your users. Suppose, let's say, your code is using a material table file but the user is seeing incorrect results. You can provide additional debug messages in your code that confirm the location of the file being used. Ask the user to right-click the Message Center and enable the Display Debug Messages option to see diagnostic information, such as the genuine location of the file being used.

Bentley::Ustn::NotificationManager

The MicroStationAPI (a C++ interface) provides the NotificationManager class (really a struct). This class has a single static method: OutputMessage (NotifyMessageDetails const &message).

#include <NotificationManager.h>

The NotifyMessageDetails struct provides methods to set your message contents and priority.

Return to MDL articles index.