Chapter 5

Rose C++ Add-In (Not Available for Linux)


Note:
While Rose C++ is still supported, there are many advantages to working with the new Rose ANSI C++ add-in, and we encourage all Rose C++ users to consider using it. A model converter comes with this release, providing an easy transition from Rose C++ to Rose ANSI C++. For details, see the release note information on the Rose ANSI C++ add-in. This will be the final release of Rose C++.

Using the Rational Rose C++ add-in, you can produce C++ source code from the information contained in a Rational Rose model. The code generated for each selected model component is a function of that component's Specification and code generation properties, and the project's properties. These properties provide the language-specific information required for mapping your model onto C++, and allow you to control the code generated for each component.

The following sections provide information on the Rose C++ Add-in:


Upgrading from a Previous Rose C++ Add-In Release

When upgrading from a previous release, it is important to understand the various versioning considerations associated with the upgrade. To help you stay in control when regenerating code of a different version, Rose C++ generates a version stamp and includes it in the generated code. Refer to the Rose C++ Code Generator Versioning online help to learn more about this feature.


C++ Code Generator Versioning

The C++ code generator uses annotations (protected regions) in the code in order to support non-destructive code regeneration (code updating). The C++ Analyzer takes advantage of the annotations as well.

As the code generator advances using code generators of different versions, the same code base becomes problematic. This is the case when the annotations format changes. A code generator versioning stamp and a surrounding mechanism has been introduced to address this problem.

A particular code generator will produce a version stamp that characterizes the annotations format used and the version of the code generator relative to this annotation format. They are called annotation version and minor version. The version stamp itself has the form of a protected/preserved region. It is not meant to be modified or deleted by the user in any way because it is used differently than other preserved regions. Text added in the region will not be maintained. In addition, the preserve tag must not be set to false.

A particular code generator version will only write the newest version of annotations. However, it can read and interpret older versions of the prior annotation version. How far the backward compatibility goes depends on the kind of change introduced. The code generator will issue a warning message when an annotation upgrade occurs. Refer to the C++ Annotation Upgrade topic to read more about the implications of upgrading the annotation format. Upgrading to a higher minor version is the recommended path and does not cause any problem because it does not require any transformations. The annotation format has not changed.

Downgrading code, which is updating code produced by a higher version code generator, is a risk. The exact risk depends on the usage of newer code generator features and how models that produce the code are going to be shared. In order to allow the user to decide what downgrading risk to engage, two Boolean project properties AllowGenerateOverNewerMajorAnnotations and AllowGenerateOverNewerVersions have been introduced. The default property sets assumes that no risk should be taken. They are both set to false. If the property does not allow overwriting newer code, the code generation displays an error message and skips the module. Otherwise, it will issue a warning and continue.

There are some additional considerations when using an older code generator that is not aware of version stamps. The first version of the version stamp aware code generator is version 1.1. If it does not find a version stamp, it will assume that the file had been written by an older code generator. The behavior is as if found a stamp denoting version 0.0. The C++ version comment orphaned topic contains more information about the effects when using a version 0.0 code generator on newer version stamped code.


C++ Version Comment Orphaned

If you are using an older, version stamp unaware code generator to update version stamped code (C++ code generator versioning) the version stamp comment will end up in the orphaned section at the end of the module. This raises the same issues as described in the C++ annotation downgrade topic. The recommended action is to use the newer code generator.

It is likely that other preserved regions will also end up in the orphaned section. If you decide to undo this operation, you will have to manually revive the written backup files.


C++ Annotation Upgrade

A major annotation upgrade happens when code is updated that had been written with an older code generator that supports an older annotations format.

An annotation upgrade is introduced to put more information in the code in order to find preserved regions properly in complex situations. For example, support for recognizing the preserved regions for property generated operations (such as assignment operators) copy constructor when the class name changes.

Changing the annotation format has disadvantages, which is the reason why they occur only after careful consideration of alternatives. One disadvantage is that upgrading to a new format can create problems if the upgrade occurs at the wrong time. Whether this is true or not depends on the particular format change introduced. In addition, upgrading is in general restricted to a particular number of versions.

A particular code generator will support upgrading from the next lower annotation version under stable conditions. Stable conditions means that the upgrade should occur on code that has been successfully updated using the code generator from which to upgrade. If the current code does not fit the model, upgrading and synchronizing at the same time may fail. The steps to assure stable conditions are:

  1. Update the code with the code generator version you want to update from.

  2. Do not change the code and the model.

  3. Update the code with the target code generator version.


C++ Annotation Downgrade

A major annotation downgrade occurs when you update code that had been written with a newer code generator supporting a newer annotation format.

Refer to the C++ annotation upgrade topic for reasons why the annotations format may change. It must be expected that the older code generator may not be able to recognize the code regions with the newer annotation. It is particularly problematic to share code using code generators, which support different annotation versions. The exact risk depends on the usage of newer code generator features and how models and especially the produced code are going to be shared.

Downgrading annotations is neither recommended nor automatically supported. You may have to do manual work.

However, you may have valid reasons to dismiss all these considerations. Setting the Boolean project property AllowGenerateOverNewerMajorAnnotations to True will allow you to perform the downgrade. The code generator will still insist to issue a warning though.

The default setting is false, which makes the code generator to issue an error and to skip this module.


C++ Minor Version Downgrade

A minor version downgrade occurs when you update code that had been written with a newer code generator, which supports the same annotation format.

Minor downgrades may introduce problems if your current model/code depends on capabilities that have been introduced in the newer code generator. Note that minor upgrading will remedy those problems. Therefore minor downgrades will not raise problems which may require manual work. However, you should allow the downgrade only if you are sufficiently certain that you are not causing problems.

The capability to honor a minor version attempt can be controlled in the same way as the annotation version downgrade. So even though minor downgrading is far more reasonable, the behavior regarding error/warning messages and default setting is the same. Setting the Boolean project property AllowGenerateOverNewerVersion to True will allow you to perform the downgrade. The code generator will still issue a warning in order to make you aware of the potentially unintended downgrade. The default setting is false, which makes the code generator issue an error and skip this module.


C++ Add-In Known Problems and Limitations

The following table contains known Rose C++ problems and limitations in Rose for UNIX/Linux.

Table 5 Known C++ Defects
Defect
Description
3861

Scroll bar in Language Properties dialog box may disappear.

Workaround: If this occurs, clicking in the scroll bar area will cause the scroll bar to reappear.

3877

Having a <return> character in the language properties (Tools > Options "language tab" property fields) can create a code generation problem. In addition, it is difficult to determine if a <return> character exists in language properties as it does not display.

6707

Argument, parameter, and result type specifications are textual even when they are references to elements in the model. This gives you the impression that they will change as you change the elements referenced (like other fields in the model). Because they are just text, they do not.

145958

After a round-trip engineering update the font in Rose is changed from whatever it was to 9 pt.


Fixed defects in C++ Version 2001A.04.00

Table 6 Fixed Defects
Defect
Description
6209

The Analyzer does not handle most template specializations. How they should map to a UML model has not been determined. They probably should be put in protected regions by Action:CodeCycle, but they are not.

21233

Preserved region data not retained correctly when generating Ada83, Ada95 or C++ code.


      

Rational Support

techpubs@rational.com
Copyright © 2001, Rational Software Corporation. All rights reserved.