Migrating configuration files
Carmenta Engine 5 has a new configuration file format and old configurations stored in the old format (.p files) cannot be loaded by an application using Carmenta Engine 5. They must be migrated to the new .px format with the help of Carmenta Studio.
Using Carmenta Studio to migrate the p-file
The recommended procedure to migrate a .p file is the following:
Start Carmenta Studio and open the .p file.
If there are any problems during migration, a message box will be displayed describing the problems. Read these messages carefully! They often warn about changes to properties that can't be automatically migrated, and that you have to fix by hand. If you just go ahead and save the configuration, you might lose those properties. The migration messages are also written to the Carmenta Studio log window if you need to go back to them; select View -> Show log window so see the log.
If you get a lot of migration warnings, and the resulting configuration is hard to understand and fix, try at least to identify which objects from the .p file caused the problems. Then it is probably best to go back to the original .p file and open it with the SpaceLab tool from 4.x, and change those objects, see the section below. Then save the .p file, and try to migrate it again with Carmenta Studio.
If the migration is successful, or if you only get minor problems that you can fix directly in Carmenta Studio, save the configuration to the new file format.
Note that you will have to migrate one file at a time. If you have many configuration files you will have to repeat these steps for each file.
File references to other .p files are automatically changed to the same file, but with a .px extension. If you migrate several files with references between them, the easiest way to keep those references working is to simply save the .px files next to the original .p files, in the same directory.
Migrating a large file with many migration warnings can potentially take some time. To help in this situation, Carmenta Studio supports saving a configuration in an intermediate format, even if it contains serious errors. You won't be able to load such a configuration and run it, for instance in Carmenta Explorer, but you will be able to load it back in Carmenta Studio and fix remaining problems. This feature is automatic; if the configuration contains errors when you try to save it, you will be prompted if you wish to save it to this intermediate format.
Preparing a .p file for migration
Carmenta Studio can migrate most .p files, but a couple of constructs are problematic. If you get migration errors due to these the best way is often to open the .p file in the SpaceLab tool from 4.x and rewrite those constructs, and then try migration again.
The following table lists the elements in a .p file configuration that should be fixed before attempting to migrate the configuration with Carmenta Studio.
Carmenta Engine 4.x | Preparing for migration |
|---|---|
Block | Carmenta Engine 5 does not support code blocks inside the configuration file. If you really need to execute the code, you have to remove the block and write the corresponding code in you application instead. If the code block is merely for picking up some application setting, replace the block with a String, Path, RegistryValue, EnvironmentVariable or similar. You can also use the new ConfigurationParameters class to pass parameters from the application when the configuration is loaded. |
CompositeSymbol | CompositeSymbol and the associated classes SymbolCreator, SymbolMapping etc are not supported in Carmenta Engine 5. The same functionality can be achieved using the SvgSymbol and PointVisualizerSet classes. Carmenta Studio will automatically migrate CompositeSymbol objects to SvgSymbol instances; one for each SVG Shape found in the symbol. All layout information in the symbol will be discarded. For simple symbols with only one shape and default placement, this will work well. In more complex cases, you will have to migrate the symbol manually, replacing it with SvgSymbol and PointVisualizerSet. Unfortunately, this is hard to do in advance in 4.x since the SvgSymbol class is not available. It might actually be easier to do the migration and then fix the layout afterwards, for instance using the PointVisualizerSet class. |
AsyncView | Not supported in Carmenta Engine 5. Replace with view, possibly add a TileLayer after migration. |
Gruk | The Gruk data format is not supported in Carmenta Engine 5. Replace the dataset with some other dataset before migration. |
LandOp, WeightSumOp, OverlayOp, StochasticPointsGeneratorOp | Not supported in Carmenta Engine 5. Remove from configuration before migration, and implement functionality by other means afterwards. |
AudioOp, Auralizer, PointAur, LineAur, PolygonAur | Not supported in Carmenta Engine 5. Remove from configuration before migration. |
SplineLineStyle and related classes | Not supported in Carmenta Engine 5. Remove from configuration before migration. |
TimeOp, ProbeLayer | Not supported in Carmenta Engine 5. Remove from configuration before migration. Note that Carmenta Explorer has a built-in profiler that can be used to find the hotspots in a Carmenta Engine map configuration. It is also possible for an application to start/stop the Profiler from code. The resulting report can then be examined in Carmenta Explorer. |
SpaceWebLayer | Not supported in Carmenta Engine 5. Replace with OgcWmsLayer before migration. |
GeoEllipse, GeoRaster, GeoMesh | These objects can't be created directly in the configuration file. Remove these and create them from application code instead. |
Please note that ScriptOperator in Carmenta Engine 5 uses the Python language and that Carmenta Studio cannot migrate the script code. Also, while all custom object elements in a configuration file are migrated into a format that Carmenta Engine 5 understands, the custom objects themselves must also be migrated.
For more details see Migrating Code in ScriptOperator.