This page will guide you through the modernization of the service layer of your COBOL modernization project.
This reference guide does not explain the COBOL procedure logic in COBOL environment. We assume that readers have enough knowledge in COBOL to understand the equivalents between legacy behaviors and the ones computed by the transmodeling process.
In your COBOL legacy inputs, the service layer you will be able to modernize is located into the PROCEDURE division of your cblmf files.
The Outline view can be helpful to describe the hierarchy of this section.
The service modernization relies on the following requirements :
- An UML model must be opened in order to trigger a transmodeling;
- Modernizing the business layer of your cblmf file is strongly advised as a previous step. The service layer mostly relies on references to data fields and the transmodeling won't be able to make the right connections (mappings) if you don't already have an associated model business layer.
For more information about the business modernization, please refer to the COBOL Bean Modernization page.
For more information about the mappings, please refer to the COBOL Mappings page.
Service modernization selection
You can modernize the PROCEDURE division of your cblmf by multiple actions, depending on the level of granularity you want to adopt.
Global modernization selection
You can modernize the entire PROCEDURE division by following these steps. Right-click on the cblmf file and select the Transmodel to UML2 entry.
You can also open the cblmf file with the Cobol Annotation Editor, select all its contents (or at least all the PROCEDURE division), then right-click on it and select the Transmodel to UML2 entry.
Precise modernization selection
You can also modernize only a specific part of your code by using the following steps. Open the cblmf file with the Cobol Annotation Editor, select the lines you want to modernize, then right-click on it and select the Transmodel to UML2 entry.
NOTES : If you want to transmodel a specific section or paragraph, you can just select the name of this section/paragraph in the Cobol Annotation Editor. More generally, selecting a container statement will trigger the transmodeling of its contents, typically the whole content of an if statement if you only select the IF keyword. The transmodeling by selection triggers the annotation of the transmodeled legacy code with Modernized as annotations, which is not possible in global transmodeling.
After clicking on the Transmodel to UML2 entry, the following wizard appears :
The wizard is divided in two layers :
The top layer (1) carries information about the operations which have been computed based on the selection you have made. In case of a global modernization, it splits each section and paragraph as an operation, and in case of a selection located within a paragraph, it will automatically create an operation to carry the information you selected. This layer can be hugely customized :
- You can select which operation you want to keep/ignore by selecting the desired checkboxes as shown in (2). You can check/uncheck all operations by clicking on the column header. All operations are by default selected;
- The legacy name corresponding to the computed operations is shown in (3). In this example it binds the main section of the cblmf program and its paragraph. This column is indeed not editable;
- The modernized name which has been computed based on the legacy name is shown in (4). You can edit this information by clicking on a cell if the default name doesn't suit your needs;
Operation parameters are provided by the (5) column. You can edit the list of parameters by clicking on a cell. The following page appears :
You can add/remove parameters using corresponding button on the right. Adding a parameter will create a new line in the table, which you can then edit by clicking on each cell to modify the parameter name, its UML type and optionally its legacy type name.
Once the parameters have been set, click on OK. It will update the corresponding cell of the specified operation with the number of arguments you set, and spread these arguments through all operations which correspond to paragraphs of the section if you set the arguments for a section operation;
TODO : Purpose of the legacy type name ?
The return name can be specified in the (6) column. This information is not needed in case of a void return type but can be edited otherwise;
- Related to the return name is the return type, which can be specified in the (7) column. You can choose an other UML type by clicking on the cell, which triggers an UML type picker;
- The last column (8) only appears when the Activity Type preference has been checked in the Blu Age transmodeling preferences. It allows you to specify the type of process operation to generate for each operation between a process-operation/activity couple and a ProcessOperation-activity. You can also change the behavior for all operations by clicking on the column header and selecting the desired behavior.
For more information about the Blu Age transmodeling preferences, please refer to the Transmodeling preferences section.
For more information about process operation types, please refer to the Service Modeling page.
- The Use Reference Signature checkbox (9) allows you to speed up the configuration of your operation prototypes by using an existing UML operation as template for your arguments, return type and return name. You can select the template operation by clicking on the Choose Operation... button, which will trigger an UML operation picker. The information will then be updated through all operations based on the operation you selected, as shown in the following example :
- The Ignore "modernized as" annotations checkbox (10) allows you to ignore already existing modernized operations that are applied on the legacy code you have selected. When unchecked, if a piece of code is annotated with a Modernized as annotation, the transmodeling will not try to transmodel the underlying code and will simply call the already transmodeled operation. Otherwise, it will compute everything regardless of the Modernized as annotations, and will not annotate the code with a resulting annotation as well in a selection transmodeling.
The bottom layer (11) carries information about the mappings related to the code you have selected, by displaying all missing mappings, ie. all data fields that are used in computations which don't have any corresponding UML property.
- We strongly recommend to clear this table before trying to transmodel, otherwise COBOL statements related to these data fields won't be correctly transmodeled. To do so, if missing mappings appear in the table, you can map the legacy fully qualified name to an UML property on-the-fly by clicking on the UML2 Element cell, which will trigger an UML property picker. When the property has been selected, the information is displayed in the cell and you can click on Apply Mappings, which will persist the mapping for future transmodelings and clear the line from the table.
The table is related to the operations you have selected in the top layer (1) : if you check/uncheck an operation which contains missing mappings, these missing mappings will appear/disappear from the table, allowing you to micro-manage each operation independently.
If you work with local mappings instead of global ones, meaning that your COBOL mappings have the scope of a single cblmf file, you can check the Show missing local mappings checkbox (12). It will display all references to data fields which don't have a corresponding local mapping in the UML model. These local mappings can also be mapped on-the-fly the way described above.
For more information about the mappings, please refer to the COBOL Mappings page.
For more information about how to use local mappings, please refer to the COBOL Bean Modernization page.
You can finally access global Transmodeling Preferences (described in the Transmodeling preferences section) by clicking on the Preferences... link.
When all configuration has been made and the transmodeling is ready to be started, click on Finish. The resulting elements will appear under the transmodeled folder of your UML model.
Transmodeling preferences can be found in the Window -> Preferences Eclipse menu, in the Blu Age -> Blu Age Reverse -> Transmodeling entry menu.
The following table describes each transmodeling preference :
|Annotate transmodeled code with operation call||Whether or not to annotate transmodeled code with corresponding Modernized As annotations during selection transmodeling.||True|
|Comment conditions||Whether or not to comment the generated opaque action holding the condition before if/for/while blocks.||False|
|Optimize conditions||Whether or not to prevent getter call duplication when a generated condition
references the same field multiple times.
This optimization is only relevant in non-BAGS mode.
|Fill commented opaque actions with corresponding full legacy code||Whether or not to truncate the commented opaque actions body to 30 characters (for readability purpose) or to keep the full corresponding legacy code.||False|
|Generate BAGS accessors||Whether or not to use BAGS expressions in the transmodeled code. This is the strongly recommended behavior. For more information about BAGS language, see here.||True|
|Enable mapping to operation||Whether or not to enable mapping to synthetic getters/setters if possible.||False|
|Choose Activity type to generate on transmodeling wizard||Allows to specify the type of process operation to generate for each
operation between a process-operation/activity couple and a
When unchecked, all operations are generated as process-operation/activity couple. When checked, the transmodeling wizard adds a column to specify the generation choice for each operation, with a default choice corresponding to the selected radio button.
|Add Comment for conditions||Whether or not to generate a comment for each decision/merge node holding the condition : if ( condition ) on the decision node and endif ( condition ) on the merge node.||True|
|Disable Intermediate variable for Array Index||Whether or not to inline the index used in a BAGS array access or to create and use an intermediate int variable holding the value.||False|
|Optimization of activity diagrams||Whether or not to apply an optimized layout to all generated activity diagrams. For more information about the effects of this optimization, see here.||False|
|Print start and end lines from DSL file||Whether or not to add DSL operation line start and end information in the Javadoc of generated operations.||False|
|Use StringUtils for String comparisons||Whether or not to generate simple == comparisons between Strings or calls to @StringUtils.areEqual() which can be overridden with specific implementation.||False|
Some legacy languages have their own specific transmodeling preferences.
The following table describes each COBOL-related transmodeling preference :
|Handle precision and scale in arithmetic operations||Whether or not to generate calls to BigDecimalUtils helpers to handle the precision and scale of calculations or to simply generate arithmetic operations.||False|
|Generate flush structure services||Whether or not to generate a service which will initialize each property of an entity in INITIALIZE statements, base on legacy initial values. If false, the initialization is up to the developer (for instance by manually creating a new instance of the object).||True|
|Use fixed-size mode||Whether or not to generate fixed-size operations. For instance, when moving SPACES to a String, fixed-size mode will fill the String with spaces depending on its legacy size, but will only clear the String otherwise.||False|