Creating Resources

There are two ways that resources can be created.

To create resources:

  1. The MDL resource compiler rcomp generates resource .rsc files from resource source .r files. Then the MDL linker mlink links one or more object .mo files into a program .mp file. Finally, rlib merges the .mp file with .rsc files to create an executable .ma file.
  2. An MDL application can use resource manager functions to create a resource.

Resources generated with the resource compiler are generally static. Thus, they generally do not change and are just read by MDL applications. The source language for resource source files is an extension of C. It allows the following to be described:

Resources generated during MDL application execution are usually more dynamic. They are created, read, written and sometimes deleted. Examples of static and dynamic resource descriptions follow.

Error message translation: an example of static resource use

An example of resource use is an application with error messages that must be translated into a foreign language. If resources are not used, when error messages are hard-coded into the application source code, they are difficult to locate because they can be scattered over many source code modules. The task becomes particularly difficult if the human translator is not the application programmer (usually the case). But that would only be part of the problem. Once the error messages are located and changed, all affected source modules need to be recompiled, a time-consuming process for large applications. If two or more application programs are involved in the system, some error messages can be duplicated, thus increasing the amount of work.

When error messages are extracted from the application source code and placed into a separate source file, they are centralized and therefore easily located. Once translated, they can be compiled into resource file format with the MicroStation Resource Compiler. The compilation process will be much faster than it will when resources are not used, since fewer files and no C instruction code compilation is involved. Error messages such as "Sorry, that feature is not yet available" can be common to and shared by several applications.

This last example shows how static resources can be used. (A static resource is defined as an ASCII source file that is compiled into resource file format). However, some applications need to collect information and store it in a file during program execution. These resources are more dynamic.

User preferences: An example of dynamic resource use

An example of collecting and saving resource information dynamically (during program execution) is found in MicroStation's Preferences dialog box. In this dialog box, you can alter options such as the Undo Buffer size and the Drawing Compatibility mode. This information is then saved in a resource file to be reused during future MicroStation sessions. In this case, MicroStation uses the resource manager functions to create the file where the resource will be stored, to save the resources in the file, and to reload the resources during subsequent sessions.

In general, the resource manager acts as a database interface for storing and retrieving internal program variables (resources) that must be reused across multiple executions of an application, shielding the application from the actual file storage methods used. An application needs only to set up identifiers for its resources.

Predefined resources in MicroStation: Message list and table

The Message List and Table resource classes were predefined for the convenience of applications. These resource classes are defined in the system header file rscdefs.h. MessageLists are described below. For a description of command tables and the predefined resource class Table, see TO-DO "Compiling an Application Command Table".

A MessageList contains messages used by the application. Each message in the list has a corresponding message number. These message numbers must be unique and appear in ascending order in the list. The MessageList's resource identifier (referred to as resourceID) combined with a message number uniquely identifies a given message in the list. A sample MessageList follows:

MessageList TEST_LIST_ID=
{
{
{4, "Please enter your password."},
{21, "That function is not available."},
{9999, "Press any key to continue."};
}
}

An application can obtain a message in a MessageList directly using the mdlResource_loadWString function or can instruct one of several MDL built-in functions to use its MessageLists. Specifying MessageLists to MDL built-in functions enables MicroStation to display an appropriate command name and command prompt when application commands are initiated, undone and redone. These built-in functions and their relationships to MessageLists are described in the following table:

Function Used to
mdlState_registerStringIds register an application's Command Prompt MessageList and Command Name MessageList for other built-in functions to use.
mdlState_startPrimitive mdlState_startFenceCommand mdlState_startModifyCommand mdlState_startViewCommand accept prompt and command name message numbers as parameters. The message numbers are contained in the application's registered Prompt and Command Name MessageLists, respectively.
mdlOutput_rscPrintf mdlOutput_rscvPrintf accept a MessageList ID and a message number to display an application message using printf and vprintf.

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.