There are two ways that resources can be created.
To create resources:
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.
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.
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.
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:
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. |