be very careful when overwriting core image files

WARNING: TECHNICAL DISCUSSION AHEAD!!!

(If you have made changes to your module.def files and the changes do not seem to "take hold" AND your core images may have been overwritten since you installed them from the CD, OR;
you have installed Telco TSB 47 and now notice unexpected module/product behaviour, read on...)


It is usually not good practice to overwrite any core images that are shipped by Smallworld or a 3rd party vendor. A typical build script will use a core image as its starting point but then save a new custom image with a different name or path.

But there are some rare instances where a customer needs to overwrite a core image. One such case is required by Telco TSB 47. That TSB includes a document "Upgrading PNI 4/LNI 4 to Core Schematics TSB 1". It instructs the customer to open pni40_closed.msf, update the schematics UDS dataset definition and then resave the pni40_closed.msf image with the same name. This is an efficient way of ensuring that all PNI/LNI applications will see the updated schematics UDS dataset definitions.

BUT, the instructions do not account for something subtle yet very important: the SW_PRODUCTS_PATH environment variable. If a customer has correctly used the SW_PRODUCTS_PATH environment variable then it will point to one or more product.def files which also include image/application modules unique to that customer. Typically an image or application module will "require" other modules that provide the desired functionality for the customer. A customer can add new functionality to their application by "requiring" other modules (created internally or supplied by 3rd party vendors). If someone overwrites a core image file without accounting for the SW_PRODUCTS_PATH environment variable, they run the risk of rendering future module definition changes as unreadable.

Why? Consider the following. When an image is started, its smallworld_product class has a slot that contains references to all known product.def files (and by inference, all module.def files). At image startup, the smallworld_product class augments its list of known product.def files by also looking at the %SW_PRODUCTS_PATH%. A shipped core image does not "know" about any of your custom products or modules. But if you start up your environment and then overwrite the core image, the act of opening the core image has "introduced" that core image to your custom products and modules and overwriting the core image will now save the knowledge of your custom products and modules in the core image itself.

Why is this a problem? Storing a module definition in an image makes the image a bit arrogant. That is to say, the image now thinks it knows everything there is to know about the saved module definitions and will ignore any changes you make to the actual module.def file from which it derived its information.

This is especially significant when it comes to changing a module.def in the future. Typically the change is to the "requires" stanza. Because the image already knows about a "requires" stanza for the module, it will see no need to reinitialize its definition based on the changes you entered into the module.def file. You can force a product or module to reinitialize itself, but I think the better solution is to not store custom product/module definitions in core images in the first place.

How do we fix this problem? We go back to the SW_PRODUCTS_PATH environment variable. If you will be overwriting a core image, first ensure that the SW_PRODUCTS_PATH environment variable has no value. You may need to temporarily modify your environment BAT file (or whatever BAT file you use) to accomplish this. Once you have overwritten your image, you can revert SW_PRODUCTS_PATH back to what it needs to be for your custom environment.