Managing Custom User Interface IDs TechNote

When MicroStation (or an MDL application) is loaded, the MicroStation Resource Manager subsystem opens its resource file. In the case of MicroStation, the resource file name is ustation.rsc, in the case of an MDL application, the resource automatically opened is the application (.ma) file itself. The MicroStation Resource Manager then automatically searches for any modification resource files that are associated with the application and opens them, as well. Modification resource files are associated to an application by their file name. A modification resource file that is associated with an application will have the application's MicroStation task identifier as its file name, and one of a prescribed set of file extensions. The Resource Manager organizes the modification resource files into a hierarchy based on this file extension, as follows:

As an example, if a user creates a new user interface from the MicroStation Manager dialog box, she will find that the user interface directory contains a file named "ustn.r01", containing the user interface description and some version information. The task identifier "ustn" indicates that this file modifies ustation.rsc, and the .r01 extension indicates that the file was created by the system.

The files are opened in the following order:

1. System level files in numerical order
2. Site level files in numerical order
3. Project level files in numerical order
4. User level files in numerical order

Note also that Customize only creates or writes to files with the .m<nn> extension. Users who wish to create files with other extensions to create the above hierarchy may either rename an existing user level (.m<nn>) modification file or use the MDL resource compiler to compile a source (.r) file to a file of a specified extension.

Each time the program requests a resource (a tool box, menu, whatever), the MicroStation Resource Manager searches all open resource files, beginning with the last one opened, for that resource. As soon as the Resource Manager finds a resource with the specified resource identifier belonging to the application, it stops looking. For example:

ustn.m01 contains a tool box with the resource identifier 1001 and a tool box with the resource identifier 1002
ustn.m02 contains a tool box with the resource identifier 1001

Since the files are opened in numerical order, ustn.m02 is opened last. If the user opens the tool box numbered 1001, it will be loaded from ustn.m02, because the Resource Manager searches the files from the last opened to first opened. If the user opens tool box 1002, it will be loaded from the file ustn.m01 because ustn.m02 does not contain a tool box with that resource identifier.

When the user creates a new custom tool box (or tool), Customize tries to avoid a conflict with existing resources. It will search all open resource files for tool boxes, find the one with the highest resource identifier number, add 1 to that number, and assign the result as the identifier of the new custom tool box.

This system breaks down when modification resource files built in one environment are copied to another, since only the build environment is searched for resource identifier conflicts. For example, take the following scenario:

1. A site administrator creates a set of custom tool boxes that are useful to everyone at her site. The tool boxes have resource identifiers 1001, 1002, 1003
2. User A at this site has created a custom tool box to group together some frequently used tools. Its resource identifier is 1001.
3. The site administrator delivers the site-specified tools to User A's user interface in a file named "ustn.s01".

Because User A has a tool box with the identifier 1001 in the ustn.m01 file in her user interface, this will mask the tool box with that identifier in the file ustn.s01.

One way to help avoid this problem is to manage the resource identifiers assigned by Customize using the configuration variable _USTN_CUSTOMIZEBASEID. When creating new resources, Customize will begin numbering their identifiers at the value of _USTN_CUSTOMIZEBASEID. The open resource files will still be searched for the highest existing resource identifier, but any numbers below _USTN_CUSTOMIZEBASEID's value will be ignored. Here's how this would work, using the example above:

1. A site administrator sets the value of _USTN_CUSTOMIZEBASEID to 10000 for all the users at a site.
2. The administrator sets her own _USTN_CUSTOMIZEBASEID to 1000.
3. The administrator creates a set of custom tool boxes that are useful to everyone at the site. The tool boxes have resource identifiers 1001, 1002, 1003.
4. User A at this site creates a custom tool box. Because of the value of _USTN_CUSTOMIZEBASEID set by the site administrator, the custom tool box has resource identifier 10001.
5. The site administrator delivers the site-specific tools to User A's user interface in a file named "ustn.s01".

Since User A's custom tool box has a much higher number than any found in ustn.s01, there is no conflict. The site administrator may create "levels" of resource identifiers by adjusting the value of _USTN_CUSTOMIZEBASEID. In the above scenario, the site administrator may set the value of _USTN_CUSTOMIZEBASEID to 5000 and create some custom tool boxes for a specific project. These tool boxes could then be delivered to User A's interface in the file ustn.p01, and there would be no conflict with the site-level or user-level tool boxes. Of course, the administrator must make sure that there is adequate "room" between the various values of _USTN_CUSTOMIZEBASEID to avoid future conflicts.

Because the configuration variable _USTN_CUSTOMIZEBASEID was introduced after modification resource files already existed, the MDL application RSCRENUM.MA was developed to re-sequence the resource identifiers in files. The application rewrites the tool and tool box resources in a given ustn.m01 file with identifiers numbered higher than the value of _USTN_CUSTOMIZEBASEID, so this configuration variable must be set before running the utility. RSCRENUM does not update the references to tool boxes that are accessed from a pull-down menu, so tool boxes must be reattached to the menu after RSCRENUM has executed.

8245 8245