IBM Support

Customize code generation using IBM Rational Rhapsody for C++

White Papers


Abstract

This white paper helps you understand IBM Rational Rhapsody properties and understand which ones are related to code generation.

Content

Author: Shinji Kanai

There are thousands of properties exist in Rhapsody for C++ (RiC++). Currently, there is no easy way for users to navigate through properties and understand which ones are related to code generation and how code will be altered as result of the property modification performed. This white paper aims to ease this particular concern, targeting C++ users in mind. Also, this white paper provides a way for other code customization techniques which you can use in conjunction with the property based modification.




Click to collapse or expand all sections (Provided to print the entire page.)
Table of Contents
Segment
OverviewDocumentation Overview, Code Generation Architecture, Scope of this documentation
CommentsComment Style (i.e. C vs C++), Comment for auto-generated functions, Requirements as comments, Description Template Usage, Header/Footer manipulation, General Techniques
General FormattingLineLength, Tab/Space/Font, Brace Position, Indentation, Multi-Line, Advanced Code Formatting using WriterTemplate
NamingFile Name, Naming Convention, Prefix/Postfix adjustment
ScopeVisibility (Public, Protected or Private), Namespace
Class/FileGeneral Class Structure, Include Statement, Include Guard, Forward Declaration and Dependency, Conditional Compilation (i.e. #ifdef), Macro declaration (i.e. #define), Global declaration, Constant declaration, Generate only H vs CPP, Vendor-Specific Modifier, Constructor/Destructor, Nested Class, Duplicate Class, Inlining Technique, Copy Constructor, Template Usage (instantiation and specialization), Friend Class, Use Struct instead of Class, Generalization
Operation/FunctionConst member function, Default Argument, Call by Value vs Reference, Vendor-Specific Modifier, Naming Manipulation, Inlining Technique, Template Function, Accessor/Mutator, Variable Length Argument, Void Argument, Operator Overloading, Function Pointer, Friend Function, Argument Manipulation, Return Type, Unnamed Argument
InterfacePort
RelationshipUser Container, Use template to define relationship, Container Usage, Relation Configuration
InitializationConstructor Initialization, Initialization Technique, Array & Struct, Global/Static Variable
DependencyPath delimiter, Header inclusion, #include ordering, #include style, Variant Handling, Implicit Dependency
Ordering/SortingGeneral ordering technique, #include ordering, Struct and Union member, Constructor Initializer List
OptimizationPort Multicast, Code Size, Parallel Code Generation
OthersDBCS/Unicode, External File Management, Exception Handling, C++11 Standard, Backward Compatibility, Execution Frameworks


Overview





    Documentation Overview

      Systems engineers and software developers use IBM Rational Rhapsody to create either embedded or real-time systems. Rhapsody goes beyond just defining requirements and designing a software solution, but actually implements the solution designed using formal specifications (e.g. UML/SysML) as front-end to system modelling and automatically transform it into ANSI-compliant code that is optimized for the most widely used target environments, allowing you to customize how the code is generated by setting existing properties or create whole sets of new ones.

      In Rhapsody, you can think of each element (metaclass) as having its own set of properties and many of which are being referenced by Rhapsody code generator. Rhapsody properties are classified according to subject and metaclass with the individual property names listed under each metaclass. If you want to see it, you can simply open the Feature window of any element, go to Properties tab. Only properties that are relevant for a particular element are accessible from that element. Many of properties related to code generation are categorized under CG and CPP_CG subject. Most of properties you see under CG and CPP_CG subject are covered in this documentation and their practical usage are explained in relevant topics navigable through Table of Contents. Selecting a subject, metaclass, or property name listed in the Features window displays the definition of the selected item.

      Although the scope of this documentation is only limited to property based code modification, there are also others techniques that affect the code generation process at various level. These techniques can be summarized as below:

      Lightweight customization
      • Generation Property (parametric)
        • (1) Stereotype
        • (2) Standard Operation
      • Post Processor

      Heavyweight customization
      • Simplifier Manipulation
      • Rules Composer (*requires additional license)

      To understand where exactly each of techniques fits in the process of code generation, see "Table of Contents > Overview > Code Generation Architecture" section. Also, an introductory WebCast is available on this topic. If you want to understand those techniques better, go to Rational Rhapsody Enlightenment Webinar Series page and look for the topic called "Software Development: Code Generation: Basics, Customizations & Advanced Customization". A similar topic was also covered in Rational Support Technical Exchange Open Mics held in 2013 and available in Japanese. You can access the material from OpenMic Web Seminar Reply page.









    Code Generation Architecture

      Rhapsody is an application development tool that supports MDA (Model Driven Architecture) approach which was launched and standardized by Object Management Group (OMG). The first step of constructing a MDA-based application is to create a platform-independent model (PIM). This general model can then be transformed into a platform-specific model (PSM) before converted to programming languages such as CORBA, ADA, JAVA, C/C++, etc. Rhapsody accommodates this two step approach nicely by carried out the entire code generation process in 2 steps; simplification phase and code writing phase. For example, if the target programming language is C++, then the simplification step transforms a user model (PIM) to a simplified model (PSM), and the witting phase generates C++ source code based on the intermediate model created in the prior step. This is the basic flow of Rhapsody code generation engine. Apart from properties, there are 3 key techniques that could go into the generation flow and affect the final source code to be produced. These techniques are Simplifier, Writer and Post Processor, see the image below showing how each of them fits in the big picture:



      For additional information about Post Processor and Simplifier Helper, see "Table of Contents > Overview > Scope of this documentation" section. To customize at writing phase, you need to purchase Rules Composer separately. If you are interested in Rules Composer, contact your local rational sales representative.








    Scope of this documentation


Comments





    General Techniques

      Most of elements in Rhapsody (e.g. class, attribute, package) have Description tab accessible from Feature window, and you can use this tab to enter comments. The entered description is then generated in the header file where the selected element is defined (Since v8.0.3, you can choose to generate it in the implementation file). See the image below that illustrates how comments are entered through GUI and generated in the code.

      Apart from adding comments through Description tab, there are also other ways you can enter comments. See below to learn other comment generation techniques to meet your specific needs.

      • Add comments through ImplementationProlog properties (click to collapse or expand)
      • Add comments through RoundTrip (click to collapse or expand)
      • Add comments through the use of requirement element (click to collapse or expand)
      • Add comments through GenerateDescriptionInImplementation/DescriptionInImplementation properties (available since v8.0.3) (click to collapse or expand)
      • Moving the comment inside the operation body using WriterTemplate (available since v8.0.6) (click to collapse or expand)


      Related Properties (searching for properties):
      CPP_CG::File::ImplementationFooter

      CPP_CG::File::ImplementationHeader

      CPP_CG::File::SpecificationFooter

      CPP_CG::File::SpecificationHeader
      CPP_CG::Configuration::DescriptionBeginLine
      CPP_CG::Configuration::DescriptionEndLine
      CPP_CG::<metaclass>::DescriptionTemplate
      CPP_CG::Requirement::DescriptionTemplateForImplementation
      CPP_CG::Operation::GenerateDescriptionInImplementation
      CPP_CG::Operation::DescriptionInImplementation

      Related Technotes:


      Technote 1642601 describes how to generate operation description to implementation file from Rhapsody model.
      Technote 1670578 describes how to move the comment inside the operation body using WriterTemplate feature introduced in Rhapsody v8.0.6.
      Technote 1664437 describes how to get the same description having macro in both specification and implementation files in Rational Rhapsody.
      Technote 1700742 describes how to use WriterTemplate property to have a comment included in implementation file instead of in the header.
      Technote 1883791 describes how to add comments to Guard field of Statechart in IBM Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Comment Style

      There are various alternatives available when considering how comments should appear in source code. In Rhapsody, there are two types of commenting styles are pre-set out of the box; C style multi-line comment (/* ... */) and C++ style single-line comment (//). These comment prefixes are stored in DescriptionBeginLine and DescriptionEndLine property, and your preferred prefix can be set. Note that, even though you are working on C++ project, if the language setting for the unit file is set to C language, C style comment is automatically applied. Note that DescriptionBeginLine and DescriptionEndLine property affects only the code that is generated for descriptions of model elements; other auto-generated comments are not affected.

      For example, see the following code that shows the use of C style comment in C++ file:


      Important: DescriptionBeginLine and DescriptionEndLine property can be set on configuration level only. If you want to know the reason for such restriction, refer to PM72824 in Permanent Restrictions section for details..

      If you want to change the comment style for auto-generated comments, you might consider using a post processing script. However, these automatically generated "comments", so called annotations, are used by RoundTrip feature and other code related functionalities like error highlighting or code navigation also may not work correctly if annotations are inserted wrongly; as long as annotations are “correctly” (as assumed by RoundTrip) positioned in the code, RoundTrip and other code related functionalities can be expected to work. It is possible to strip annotations completely using Post Processor or related properties such as CPP_CG::ModelElement::SimplifyAnnotations. In this case, round-tripping operates in a restricted mode, and perhaps you'd better off by simply avoid using RoundTrip (e.g. Code > Dynamic Model Code Associativity > Code Generation). To find more information about Post Processor, see "Table of Contents > Overview > Scope of this documentation" section.


      Related Properties (searching for properties):
      CPP_CG::Configuration::DescriptionBeginLine
      CPP_CG::Configuration::DescriptionEndLine
      CPP_CG::ModelElement::SimplifyAnnotations
      CPP_CG::WriterTemplates::OperationImp

      Related Technotes:
      Technote 1632630 describes how "auto-generated" annotation is differently used in comparison to other annotations.
      Technote 1649175 describes how to remove Rational Rhapsody generated Annotations and its consequence.
      Technote 1701541 describes how to avoid annotations generated in model source file by IBM Rational Rhapsody.

      Related Permanent Restrictions:
      PM57357 : "problems defining Implementation/Specification Header"
      PM63076 : "There is a limitation of the Rhapsody Doxygen support for namespace and idl module"
      PM72824 : "DescriptionBeginLine has no effect on package in Rational Rhapsody"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Comment for auto-generated functions






    Requirements as comments






    Description Template Usage

      Text entered in the Description field of the Features window for elements are generally generated into a comment that appears in the specification file for the element. In case of object, its comment will be generated in the specification file for the package that owns the object. For example, if you enter the description "this is my comment" in the Features window for a class MyClass, the following comment line appears in the MyDefault.h.

      // this is my class
      class MyClass {
      ...
      }

      Now, if you want to apply a pattern in the comment generation for a group of same elements, you can use CPP_CG::Class::DescriptionTemplate property. The DescriptionTemplate property specifies how to generate the element description in the code. An empty MultiLine tells Rational Rhapsody to use the default description generation rules.

      • Sample DescriptionTemplate usage for Class (click to collapse or expand)
      • Sample DescriptionTemplate usage for Operation (click to collapse or expand)


      DescriptionTemplate property is also available for various model elements. For the list of supported elements, you can simply search into properties. For the basic information about DescriptionTemplate property, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Comment template properties"
    • Topic "Predefined keyword variables"


    • The following link show a practical example how DescriptionTemplate property can be used to produce Doxygen-compatible comments.

    • Topic "Using code-based documentation systems"
    • Topic "Sample Usage"

    • If you're using Rhapsody version 8.0.3 or higher, you can include a description of an operation in the implementation file (.c or cpp) with template description applied. For more information see Technote 1642601.



      Related Properties (searching for properties):
      CPP_CG::<mataclass>::DescriptionTemplate

      Related Technotes:
      Technote 1664437 describes how to get the same description having macro in both specification and implementation files in Rational Rhapsody.
      Technote 1700742 describes how to use WriterTemplate property to have a comment included in implementation file instead of in the header

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Header/Footer manipulation

      Rhapsody provides several properties (See Related Properties section) that help you to enforce the style of Header/Footer as you like. You can apply a common header/footer once you set those properties globally at component, configuration or project level. Setting it at component level results in applying the common header across all the classes within component scope. For more information about Header/Footer customization, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Comment template properties"
    • Topic "Customizing file headers and footers"

    • The following link shows you a practical example to produce Doxygen-compatible comments using properties you see in Related Properties section.



    • Topic "Using code-based documentation systems"


    • Related Properties (searching for properties):
      CPP_CG::File::ImplementationFooter

      CPP_CG::File::ImplementationHeader

      CPP_CG::File::SpecificationFooter

      CPP_CG::File::SpecificationHeader

      Related Technotes:


      Technote 1664437 describes how to get the same description having macro in both specification and implementation files in Rational Rhapsody.

      Related Permanent Restrictions:
      PM58039 : "Comment specified in ImplementationHeader/SpecificationHeader gets generated repeatedly"
      PM57357 : "Problems defining Implementation/Specification Header"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





Naming





    Naming Convention

      Having a defined naming conventions is a good practice in term of assisting all members of your team in understanding the purpose of individual items in your model. These conventions help team members to read the diagram quickly and remember the model element names easily. There are some articles available how Rhapsody can help you on this topic. See the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Rhapsody guidelines and references"
    • Topic "Guidelines for naming model elements"


    • Related Properties (searching for properties):
      <none>

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>








    Prefix/Postfix adjustment

      You can use Prefix property to add prefix for model elements as listed below, but there no property exists allowing the addition of postfix:

      • Attribute (including static)
      • Relation
      • Type

      The image below illustrates how prefix related properties can be used:



      Some of auto-generated prefix is not possible to control using properties. An example of such is "its" prefix used to define role names. To change or remove the prefix of "its", which is added by Rhapsody automatically, one might open the feature window for the association and edit the role name directly. Another might prefer using Post Processor or CG SDK to adjust these names in order to make the generated code comply with your own coding guide line. For Post Processor, you might consider using it once when generating a final production code instead of every code generation. This way, you can avoid any inconvenience the added prefix might cause upon round-trip. For CG SDK, see the image below that will illustrate how you can add prefix without using Model::Attribute::Prefix property.

      UserSimplifiers_attribute.png

      NOTE: In CppUserSimplifiersSample sample, you will see more than one simplifier are registered and called uniquely depending on element type. What's peculiar about "AttributeSimplifier" simplifier is that it is implementing at "Simplify" (By User) hook instead of "PostSimplify" (Post Default) hook. Unlike "PostSiimplify" hook, implementing "Simplify" hook is difficult because it will completely replace the internal behavior of Rhapsody's code generation engine, meaning you need to insert annotations manually. "Simplify" hook is recommended only for advanced users who has a strong understanding of simplification process. For most scenarios, "PostSimplify" hook should be suitable. Creation of CG SDK is outside the scope of this document. To learn more about CG SDK, refer to ..\Samples\CustomCG samples. Also, take a look at "Overview of model simplification process" section at "Table of Contents > Overview > Scope of this documentation".


      Related Properties (searching for properties):
      Model::Attribute::Prefix
      Model::Attribute::PrefixForStatic
      Model::Attribute::UsePrefix
      Model::Type::PrefixForAttribute
      Model::Relation::Prefix
      Model::Relation::UsePrefix
      Model::Type::PrefixForAttribute


      Related Technotes:
      Technote 1609708 (Japanese). describes how to change the prefix for associations using Post Processor.
      Technote 1649175 describes how to remove Rational Rhapsody generated Annotations and its consequence.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    File Name

      In Rhapsody, the name of generated files is derived from the class/package name you specify in the model. To change the default name, you can use FileName property. This property is provided to specify the name of the file to which code is generated for a class or package. For more information, check the property description for FileName property.

      Although the use FileName property is encouraged if you want to change the default file name, you can also change the name of generated file by manipulating Source Artifact. This approach can be of benefit if you want the file name to be in upper case or lower case. See the example below how to control the case sensitivity for generated files using Source Artifacts.


      Important:
      SourceArtifact is created manually, or automatically at the time of round-tripping. It is used for ordering and various manipulations, serving the role of information holder. Note that SourceArtifact created by RE/RT are signed as synthesized (the small 's' on the SourceArtifact image in the Browser). If you make a change to the SourceArtifact, it stops to be synthesized ('s' is removed). If it is not synthesized, Rhapsody will treat the particular SourceArtifact more carefully, same as it was not automatically added by RE/RT, and thus RT will not change its location nor delete it automatically. Ideally, SourceArtifact should be managed by Rhapsody. For more information about Source Artifact, read the Technote below for additional information:

      Technote 1640396 describes what is Source Artifact in IBM Rational Rhapsody.

      Related Properties (searching for properties):


      CG::Class::FileName

      Related Technotes:
      Technote 1641772 describes how to name a package with spaces in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




Dependency





    Path delimiter

      The PathDelimiter property specifies an alternative path separator for code generation. By default, the back slash ("\") for windows, the slash ( "/") for other environments (e.g. Cygwin, VxWorks). Some operating systems may use a different delimiter, so you need to adjust this property to meet the requirement of your specific target or cross-compiler.

      Related Properties (searching for properties):
      CPP_CG::<Environment>::PathDelimiter

      Related Technotes:
      Technote 1421960 describes how to change the back slashes to forward slashes for include statements in code.

      Related Permanent Restrictions:
      <none>








    Header inclusion

      Rhapsody provides various ways to manage dependencies. There are 5 common approaches to add #include line to the generated code:

      1. Property: CPP_CG::Class::ImpIncludes & CPP_CG::Class::SpecIncludes
      2. Configuration: Configuration > Standard Headers
      3. RoundTrip:
        1. Add #include statement directory to your code.
        2. Run the round-trip.
        3. A component file be generated under Component > Files.
      4. RoundTrip in combination with Preserve annotation. You can avoid the generation of component files.
      5. ≪Usage≫ dependency

      See below how ≪Usage≫ dependency can be used effectively connecting external files into your model.

      • How to include stdio.h into your model (click to collapse or expand)

      To disable generation of #include statements in implementation file, use CPP_CG::Class::GenerateIncludeForHeaderFile.

      The SpecIncludes & ImpIncludes property specifies the names (including full paths) of header files to include at the top of specification/implementation files generated for classes, objects, and packages. Separate multiple file names by using commas, without spaces.

      Also check the following topic to understand how implicit and explicit dependencies are understood and generated by Rhapsody.

    • Topic "Code generation for relations"

    • To learn how to change the order of explicit include statement, see "Table of Contents > Ordering/Sorting > #include ordering" section.

      Related Properties (searching for properties):
      CPP_CG::Class::ImpIncludes
      CPP_CG::Class::SpecIncludes
      CPP_CG::Class::GenerateIncludeForHeaderFile

      Related Technotes:
      Technote 1323496 describes how to automatically generate #include statements for a class.
      Technote 1323620 describes how do you include standard C++ headers (i.e. iostream, cstdio) be used with Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    #include Style

      Rhapsody provides IncludeStyle property to allow you control the style of #include statements, either Quotes or AngledBrackets. When you use this property, you can control the include style of a specific dependency, or the entire configuration/component/project. To set the style for include for files that are synthesized based on associations between model elements (for example, setting the type of some attribute to a class), add a ≪Usage≫ dependency between the elements and set this property to the appropriate value. The possible values are as follows:

      • Default - Use angle brackets for include statements for external elements, and quotes for include statements for other elements.
      • Quotes - Enclose include files in quotation marks. For example:


      • #include "A.h"
      • AngledBrackets - Enclose include files in angle brackets. For example:


      • #include <A.h>

      Another property related to this topic is the IncludeScheme property which specifies whether the path information is included within #include statement. The possible values are as follows:

      • RelativeToConfiguration - Include the relative path from the configuration directory in the include files.
      • LocalOnly - The name of the include file is generated without the path information.

      The property is first evaluated by the target file in the component model, if the file exists. If the file does not exist, the value is taken from the active configuration. This behavior specifies the generation defaults for elements without files.

      Note that IncludeScheme property affects only the files defined in the component, not the class. Therefore, you should define this property on the project, component, configuration, or individual file level.

      Related Properties (searching for properties):
      CPP_CG::Dependency::IncludeStyle
      CG::File::IncludeScheme

      Related Technotes:


      Technote 1589210 describes how to control the style of include statements in Rational Rhapsody.
      Technote 1589063 describes how to prevent path information from being included in an include statement in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Variant Handling

      Rhapsody supports the creation of variant and variant point in C++ classes. It means if you model a family of products or a product line, you can use variation points to differentiate products within the model, and able to generate each product by selecting which class variant to implement for each variation point and appropriate headers are automatically included for the targeted product. With regard to how Rhapsody can help you to manage variants in general, refer to the following article on developerWorks.

    • Topic "Product Design for Variants"

    • To implement a software product line management capability in Rhapsody, you have to do 3 things.

        1. Identify variation points
        2. Define variants
        3. Select a variant into build

      For the basic usage information about defining variant/variantpoint in your model, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Designing software product lines"

    • The attached sample demonstrates the basic usage of Variant and Variant Points. In this particular example, ≪Static≫ stereotype (on inheritance) was applied to duplicates all features of the base class into the static derive class including operations, attributes, behavior and links.

      Disclaimer

      All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.



      example_80.zip

      • How to use the sample to run simulation (click to collapse or expand)


      Other Related Articles:
    • Topic "Product Design for Variants"

    • Related Properties (searching for properties):
      <none>

      Related Technotes:
      Technote 1506328 describes how to choose between classes or objects in Class Diagram at runtime based on a set condition in Rational Rhapsody.

      Related Permanent Restrictions:
      PM45436 : "Typedef is incorrectly generated when working with variants in Rhapsody"
      PK93665 : "RFE COMPONENT VARIATION PROBLEM WITH SYNCHRONOUSFRAMEWORK"
      PM23114 : "The property(C_CG:Operation:PublicName) has no effect when variation point is applied to a file"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Implicit Dependency

      When you provide code for the declaration of a "Language" type, or specify the type of an element such as an attribute by providing your own code in the C++ Declaration field (rather than selecting a type from the list of existing types), Rhapsody cannot know with 100% certainty what type your declaration is dependent upon.

      In such cases, Rhapsody parses the code you entered, and searches the model for the type referenced in the declaration. Rhapsody takes the first type it encounters with this name, and the code that is generated includes a dependency upon this type. This type of #include line automatically generated is called Implicit Dependency. Similar dependency can be generated for associations and generalizations as forward declarations and #include statement.

      In cases where you have defined types with the same name in different packages, this type-searching behavior by Rhapsody might result in #include statements that do not reflect what you had intended. To avoid this, you can set the value of the CG::Type::GenerateDeclarationDependency property to False, and Rational Rhapsody does not generate any dependency in the code to reflect your declaration. You can then explicitly create the correct dependency in the model so that the generated code includes all the necessary dependencies.

      For example:

      If you have defined an enum called "color" in the package Basic_types, and then have a package called Vehicles with a class named Car, and that class contains an attribute named exterior_color of type "color", Rational Rhapsody by default generates the necessary #include in the code for class Car:

      #include "Basic_types.h"

      If, however, you set the value of the CG::Type::GenerateDeclarationDependency property to False, the generated code does not include the necessary dependency and you have to provide it directly.

      Keep in mind that the property is displayed under the metaclass Type, but in terms of code generation it affects the code that is generated for specific attributes that are of a given type. So you have to open the features window for the relevant attributes and change the value of the property there.

      Related Properties (searching for properties):
      CG::Type::GenerateDeclarationDependency

      Related Technotes:
      Technote 1323643 describes how CreateImplicitDependency affect the generation of dependencies.

      Related Permanent Restrictions:
      PM55868 : "'ImplicitDependencyToPackage' does not work in rhapsody"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




General Formatting





    Line Length

      To adjust the length of generated code, you might consider taking one of following two options:

      Solution 1 - CG::Configuration::LineWrapLength (click to collapse or expand)

      Solution 2 - Implement word wrap feature using post-processor (click to collapse or expand)


      Related Properties (searching for properties):
      CG::Configuration::LineWrapLength

      Related Technotes:
      Technote 1587341 describes how to implement word wrap feature for Rational Rhapsody comments using C++ COM API.
      Technote 1323703 describes how to control the length of auto generated code.
      Technote 1649175 describes how to remove Rational Rhapsody generated Annotations and its consequence.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Tab/Space/Font

      You can right-click in the implementation editor and set the tab size, fonts, line numbering and even you can turn on the option to convert tabs to spaces while typing.



      For more information, see Technote 1621397 which also explains how to apply such changes per installation instead of model.

      Alternatively, you can either write your own Post Processor or use a third-party beautifier program like GNU Indent to extend your indentation control over the entire generated code. Unfortunately, GNU Indent is designed for C code, however you will find a number of beautifier programs on the internet that support C++ language. Perhaps, you might try GNU emacs as a beautifier which is highly configurable using LISP language and is well known as offering various styling features. Regardless which option you choose, remember that there is always a risk that Rhapsody will raise a parser error from the modified code. It is highly recommended to keep the modification simple and only limited to those general formatting such as tab and brace, indentation, padding and so forth. With regard to Post Processor, refer to the related links in "Scope of this documentation" section, and take a look at the description of CG::File::InvokePostProcessor property.

      If you're using Rhapsody v8.0.6 or newer, see "Table of Contents > General Formatting > Advanced Code Formatting using WriterTemplate" section for another approach.

      Related Properties (searching for properties):
      CG::File::InvokePostProcessor


      Related Technotes:
      Technote 1621397 describes how to set the tab size for the code editors per the IBM Rational Rhapsody install (globally) instead of per model.
      Technote 1700742 describes how to use WriterTemplate property to have a comment included in implementation file instead of in the header.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Brace Position

      To accommodate various coding styles, Rhapsody allows you to specify where curly braces should be placed for namespaces, classes, operations, enums, structs, and unions.

    • Topic "Curly Brace Style"

    • Related Properties (searching for properties):
      CPP_CG::Operation::OpeningBraceStyle
      CPP_CG::Class::OpeningBraceStyle
      CPP_CG::Type::OpeningBraceStyle
      CPP_CG::Package::OpeningBraceStyle

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>








    Indentation

      You can specify the number of spaces that should be used for indentation when Rhapsody generates code.

    • Topic "Controlling indentation"

    • Note the CPP_CG::Configuration::Indentation property does not affect the indentation used in operation bodies since they consist of user-provided code. To control indentation within operation body, follow the steps below:

        1. Select an operation.
        2. Open Feature window.
        3. Navigate to implementation tab.
        4. Go to Right-Click > Properties.
        5. Adjust settings in Language/Tabs tab to suit your needs.


        6. Press OK and save the change.

      Alternatively, you can either write your own Post Processor or use a third-party beautifier program like GNU Indent to extend your indentation control over the entire generated code. Unfortunately, GNU Indent is designed for C code, however you will find a number of beautifier programs on-line that support C++ language. Perhaps, you might try GNU emacs as a beautifier which is highly configurable using LISP language and is well known offering various styling features. Regardless which option you choose, remember that there is always a risk that Rhapsody will raise a parser error from the modified code. It is highly recommended to keep the modification simple and only limited to those general formatting such as tab and brace, indentation, padding and so forth. With regard to Post Processor, refer to the related links in "Scope of this documentation" section, and take a look at the description of CG::File::InvokePostProcessor property.

      If you're using Rhapsody v8.0.6 or newer, see "Table of Contents > General Formatting > Advanced Code Formatting using WriterTemplate" section for another approach.

      Related Properties (searching for properties):
      CPP_CG::Configuration::Indentation
      CG::File::InvokePostProcessor

      Related Technotes:


      Technote 1468918 describes Parsing error when round tripping code changes in IBM Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Multi-Line

      When generating code for operations, you can use CPP_CG::Operation::MultiLineArgumentList property to have each operation argument generated on a separate line.

    • Topic "Generating operation arguments on separate lines"

    • Rhapsody supports multi-lining on Operation, Constructor, Destructor, Triggered Operation and Reception.


      Since Rhapsody v8.0.4, a new property CPP_CG::Class::MultiLineInitializerList was introduced. This new property allows the initialization of class data members on multi-lines as below:


          class_0::class_0() : 
          attribute_0(0), 
          attribute_1(1), 
          attribute_2(2), 
          attribute_3(3), 
           XXX,
           ......


      If you're using Rhapsody v8.0.6 or newer and want to change the ordering of initializer list, see "Table of Contents > Ordering/Sorting > Constructor Initializer List" section.

      Related Properties (searching for properties):
      CPP_CG::Operation::MultiLineArgumentList
      CPP_CG::Class::MultiLineInitializerList

      Related Technotes:
      Technote 1591346 describes how to generate the argument list of an operation in multiple lines.
      Technote 1649299 describes how to make Rhapsody generate class constructor parameters on multiple lines.

      Related Permanent Restrictions:
      PM57357 : "problems defining Implementation/Specification Header"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Advanced Code Formatting using WriterTemplate

      WriterTemplate was introduced in Rhapsody v8.0.6 to make the task of applying different formatting (e.g. multi-lining, spacing, indentation, positioning, etc) more flexible and customizable. This feature is not provided to replace conventional formatting options already available in Rhapsody described in previous topics. Several examples of code formatting you can do using Writer Template are presented in Technote 1670578.

      For additional information, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Further customization of code formatting"

    • Related Properties (searching for properties):
      CPP_CG::WriterTemplates::ClassSpecElement
      CPP_CG::WriterTemplates::ProtectionGroup
      CPP_CG::WriterTemplates::OperationImp

      Related Technotes:
      Technote 1670578 describes how to use WriterTemplate for advanced code formatting.

      Related Permanent Restrictions:
      <none>

      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





Class/File





    General Class Structure






    Include Guard






    Forward Declaration and Dependency

      The reason you want a forward declaration for the class is to avoid adding includes when possible. To avoid unnecessary #includes, Rhapsody will try to generate forward declarations for various scenarios, unless it is not possible or not needed. There are also several properties available that controls Rhapsody's internal behavior of generating forward declarations. See the case study below as an example:

      Case Study -How to prevent implicit forward declaration from generated for an argument referencing an external type? (click to collapse or expand)


      Below are 4 known examples when forward declarations will be generated:

      1. A class has an operation and argument type to another class.
      2. A class has more than 2 nested classes.
      3. Implicit Dependency is in use; auto-generated dependencies on a class or package.
      4. Dependency: UsageType in use.

      Forward declaration can not be created for a nested class.

      For the specific information about how to manage #include and forward declarations for external files, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "External element code access"
    • Topic "Code generation for external elements"
    • Topic "Code generation for relations"


    • Although not directly related to this topic, you can gain additional control over forward declaration and dependency using PropagateImplementationToDerivedClasses and SynthesizeClassDependencies property. Check out Related Properties section below if you are interested in how these properties work visibly.


      Related Properties (searching for properties):
      CG::Dependency::UsageType
      CG::Configuration::GenerateForwardDeclarations (depreciated in v8.0)
      CPP_CG::Dependency::GenerateForwardDeclarations (v8;0 or above)
      CG::Argument::UsageType
      CG::Class::GenerateImplicitDependencies
      CG::Class::CreateImplicitDependencies
      CG::Type::GenerateDeclarationDependency
      CG::Package::GenerateImplicitDependencies
      CG::Relation::Dependency
      CG::Class::ImplicitDependencyToPackage
      CG::Dependency::PropagateImplementationToDerivedClasses (click to collapse or expand) CG::Package::SynthesizeClassDependencies (click to collapse or expand)
      Related Technotes:
      Technote 1396612 describes CG:Configuration:GenerateForwardDeclarations
      Technote 1323687 describes how to control the forward declarations of class in the package.
      Technote 1396612 describes scenarios where UsageType generates forward declarations even if set to implementation.
      Technote 1323771 describes how to manage forward declarations with containers.
      Technote 1323643 describes how CreateImplicitDependency affect the generation of dependencies.


      Related Permanent Restrictions:
      PM92950 : "DISCREPANCIES IN THE CODE GENERATION FOR USAGETYPE PROPERTY"
      PM60890 : "Rhapsody creates #include when a user type matches attribute declaration"
      PM41492 : "Avoid forward declaration on Usage for Implementation"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.









    Conditional Compilation (#ifdef)

      C++ directives like #if, #ifdef, #ifndef, #else and #endif are used for conditional compilation, which allows the compiler to produce differences in the executable produced by passing parameters using those directives. Conditional compilation is commonly used when these differences are needed to run the software on different platforms, or with different versions of required libraries or hardware. To know how you are supposed to define conditional compilation in Rhapsody, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Wrapping code with #ifdef-#endif"

    • See the example below:

        #ifdef MY_HEADER_A
        #include "my_header_a.h"
        #endif
        #ifdef MY_HEADER_B
        #include "my_header_b.h"
        #endif
      In general, you use CPP_CG::Class::SpecIncludes or CPP_CG::Class::ImpIncludes to specify the names of header files to be included at the top of generated code. However, the property accepts only the name of files to include and you can't enter multi-lined conditional compilation like above. In this case, you would use SpecificationProlog or ImplementationProlog instead.

      Note that SpecificationProlog, SpecificationEpilog, ImplementationProlog, and ImplementationEpilog properties are available for configurations, packages, classes, operations, attributes, dependency, relation, and type. It means that essentially you can apply conditional compilation to any model elements that support these properties. All you need to do is to wrap those model elements with an #ifdef #endif pair, or perhaps you might add a compiler-specific keyword, or add a #pragma directive. For detailed definitions of properties, see the property definitions displayed in the Features window.

      As an advanced usage of conditional compilation, see the example below that shows how to define platform independent data type in Rhapsody.

      • Manage platform independent type using type element (click to collapse or expand)
      • Manage platform independent attribute in the model (click to collapse or expand)

      In terms of good modeling practice, use of following techniques instead of conditional compilation is encouraged:

      • Use Abstract Pattern
      • Use Variant Control

      You can access more information about variant control in Rhapsody, referring to "Table of Contents > Dependency > Variant Handling" section.

      Related Properties (searching for properties):
      CPP_CG::Class::SpecIncludes
      CPP_CG::Class::ImpIncludes
      CPP_CG::<metaclass>::ImplementationProlog
      CPP_CG::<metaclass>::SpecificationProlog
      CPP_CG::<metaclass>::ImplementationEpilog
      CPP_CG::<metaclass>::SpecificationEpilog

      Related Technotes:
      Technote 1605330 describes How to add predefined compilation macros in the code to identify the compilers in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Global declaration

      To define global functions and variables, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Creating global functions"
    • Topic "Creating global variables"
    • Topic "Declaring #define preprocessor directives"

    • If you want to define a global constant variable, follow the steps below:

      • How to define a global constant/static variable in H or CPP (click to collapse or expand)
      • How to declare and define a global function in different files (click to collapse or expand)

      Or, simply create a type as below and put it somewhere accessible globally.





      Related Properties (searching for properties):
      CPP_CG::Attribute::ConstantVariableAsDefine
      CPP_CG::Attribute::VariableInitializationFile
      CPP_CG::Attribute::AttributeInitializationFile

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Constant declaration

      Constant modifier specifies whether the attribute is read-only (check box is selected):



      You can apply Constant to any model elements that support it on its Feature window. To know more about it, see the related Technotes and topics in he IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version:

    • Topic "Creating global variables"


    • Related Properties (searching for properties):
      CPP_CG::Attribute::ConstantVariableAsDefine
      CPP_CG::Class::InstanceDeclaration

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      PK63360 : "Rhapsody does not support const association".


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Nested Class






    Duplicate Class

      In general, the same name should not be used for different elements in the model because it will cause code generation problems. For example, no two elements, such as a class, an interface, and a package, should not have exactly the same name. It is possible to generate the code for duplicate class by setting the checking the GenerateDirectory and DefineNameSpace properties. To generate separate directory for the *.h and *.cpp files we use the following properties:

      CPP_CG::Configuration::DefaultImplementationDirectory for implementation files
      CPP_CG::Configuration::DefaultSpecificationDirectory for specification files

      For more information about generating code into different directories, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Customizing directory structure for generated code"

    • The image below shows an example of designing a directory structure using various properties.




      The below is the directory structure you will get:

      C:.
      ├─pkg_A
      │ ├─include
      │ │ XX.h
      │ │
      │ └─src
      │ XX.cpp

      └─pkg_B
      ├─include
      │ XX.h

      └─src
      XX.cpp

      Some users might prefer having the folder structure as below, then use CodeGenerationDirectoryLevel property to "Top".

      C:.
      ├─include
      │ ├─pkg_A
      │ │ XX.h
      │ │
      │ └─pkg_B
      │ XX.h

      └─src
      ├─pkg_A
      │ XX.cpp

      └─pkg_B
      XX.cpp

      Note:
      CodeGenerationDirectoryLevel property exists in the pre-72 compatibility profiles for C and C++. To enable the property in your project, you will likely need to modify site.prp as below.

      Subject CPP_CG
      Metaclass Configuration
      Property CodeGenerationDirectoryLevel Enum "Top, Bottom", "Bottom"
      end
      end
      end
      // An empty site.prp file must contain the keyword 'end' at the end of the file

      After the change made, you have to restart Rhapsody and set the property value to "Top" to see its effect.

      Related Properties (searching for properties):
      CPP_CG::Configuration::DefaultSpecificationDirectory
      CPP_CG::Configuration::DefaultImplementationDirectory
      CPP_CG::Configuration::CodeGenerationDirectoryLevel
      CPP_CG::Package::GenerateDirectory
      CPP_CG::Package::DefineNameSpace

      Related Technotes:
      Technote 7023613 describes how to control output location by mapping elements to files and mapping files to folders.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Generalization

      Rhapsody provides various features and properties to help you automatically realize the implementing interfaces and synchronize the changes in the interface to the realizing classes. There are a lot of information available regarding the implementation of base classes. If you are interested in base class implementation, inheriting external classes, specifying inheritances and realization relationships between classes and any other relevant topics, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Implementation of the base classes"


    • Related Properties (searching for properties):
      <none>

      Related Technotes:
      Technote 1437552 describes how to activate Auto Inheritance of Descriptions in Operations of the child class in Rational Rhapsody.
      Technote 1643345 describes how to get Attribute declaration generated in Interface Header of Rational Rhapsody.
      Technote 1655118 describes why a child class always inherits a state chart from its parent class.
      Technote 1968317 describes how to use inheritance with new term stereotypes with IBM Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements,sign in developerWorks first then navigate to the detailed page at RFE Community.








    Template Usage (instantiation and specialization)

      Rational Rhapsody allows you to include generic design elements in your models. Specifically, you can:

      • Create and use template classes
      • Create template functions/operations
      • Create full/partial template specialization
      • Use template classes as relationships

      To understand their usage in details, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Modelling by using template classes and generic classes"

    • To use template classes as relationships such as generalization or association ends, see "Table of Contents > Relationship > Use template to define relationship" section for more information.

      The attached sample will demonstrate how to use template instantiation and specialization.

      Disclaimer

      All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.



      TemplateCollection.zip

      This sample consists of following samples: 
      1. TemplateFunctionOverloading - Demonstrate the effective use of template instantiation by overloading functions.
      2. TemplateImplementationInCPP - Demonstrate Queue implementation using template.
      3. TemplateInstantiation - Demonstrate the effective use of template instantiation by overloading Queue template.
      4. TemplateNonDefaultConstructor - Demonstrate the effective use of template instantiation by calling template constructor.
      5. TemplateSpecialization – Demonstrate the implementation of template specialization.


      Limitation:
      The following limitations apply for templates:
      • If there is a template parameter named “T” in an operation/function, the user cannot assign a class named “T” to the owner of the operation/function.
      • If there are more than one operation/function with a template parameter of the same name under the same owner, renaming the created nested class renames all of the parameters with this name.
      • If a nested class or attribute is marked as a template parameter, it is not generated.
      • Currently, there is no known way to separate template implementation to a separate file from its specification file.
      • Rhapsody doesn't support moving template definitions to implementations file (e.g. xyz.inl). However, you might define those definition in a separate component file or a class (CPP_CG::File::Generate=Implementation, CG::File::ImpExtension=.inl) as a workaround in order to increase the readability of template header.
      • The creation of templates and specializations are supported in code generation. If both the template and its specialization are in the same package, they are generated into the same file. In the file, the template is generated before its specialization to ensure that the code runs as expected. A check is added to warn that the template and template specialization are in different packages.
      • Rhapsody does not support RoundTrip & Reverse Engineering of implementation operations of template specification.
      • Rhapsody CG supports only "inline" operations of template specification either (in header or in declaration. Still you can generate code without "inline" keywords, but RoundTrip may produce a parser error if you do so.

      Related Properties (searching for properties):
      CPP_CG::Configuration::ContainerSet
      CG::File::ImpExtension

      CPP_CG::File::Generate


      Related Technotes:
      Technote 1323750 describes how you can use Template Class Specialization in Rational Rhapsody.
      Technote 1591512 describes how you can use the bind stereotype to instantiate a Template class in Rational Rhapsody.

      Related Permanent Restrictions:
      PM10157 : "Rhapsody should generate this _required_ template parameter by itself"
      PM94186 : "Rhapsody generated code for friend functions that holds template parameters produces compilation error"
      PM04746 : "WRONG BEHAVIOR TEMPLATE INSTANTION IS ON CLASS WITH ATTRIBUTE"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.









    Generate only H vs CPP

      A new enhancement was introduced in v7.6.1 to CPP_CG::File::Generate property, which now allows you to control the code generation of specification and implementation files by either selecting "specification" or "implementation". The value of "specification" results in the generation of only an *.h file, and the "implementation" value generates only a *.cpp file. The default value of "True" generates both.


      There are 3 known approaches to achieve this requirement:


      1. Use CPP_CG::File::Generate property (available in v7.6.1 or higher) (click to collapse or expand)

      2. Use Source Artifact (click to collapse or expand)

      3. Use Component file (click to collapse or expand)



      Related Properties (searching for properties):
      CPP_CG::File::Generate

      Related Technotes:


      Technote 1324154 describes how to configure Rhapsody to generate a *.h file (where some variables can be declared).
      Technote 1640396 describes what is Source Artifact in IBM Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Inlining Technique

      The inline specifier tells the compiler to expand a function's code inline (embedded) rather than calling the function:

        inline void myfunc(int i)
        {
        // ...
        }

      To produce inlined code in Rhapsody, you will flag the inline check box located on Feature window. When you turn the flag on, the associated Inline property will be activated. The property takes 3 different values and depending on the value specified, inline operations will be generated either in header or implementation. You can apply inlining for the following 3 model elements.

      * Attribute - Applies only to operations that handle attributes (such as accessors and mutators)
      * Operation - Applies to all operations
      * Relation - Applies only to operations that handle relations

      The possible values for the Inline property are as follows:

      * none - The operation is not generated inline.
      * in_header - The operation is generated inline in the specification file.
      * in_source - The operation is generated inline in the implementation file.
      * in_declaration - A class operation is generated inline in the class declaration. A global function is generated inline in the package specification file



      Note:
      Inlining an operation in the header might cause problems if the function body refers to other classes. For example, if the inlined code refers to another class (by way of a pointer such as itsRelatedClass), inlined code that is generated in a header might not compile. The implementation file for the class would have an #include for RelatedClass, but the specification file would not. The workaround is to create a Usage dependency of the class with the inlined function on the related class. This forces an #include of the related class to be generated in the header of the dependent class with the inlined function.

      As you can see in the example below, Rhapsody allows you to inline some of auto-generated code like Accessor/Mutator. There may be a case when you want to inline other auto-generated code like cleanUpRealtions() in the example. You can still inline them by following the steps below:

      • How to inline operations managed by Rhapsody (click to collapse or expand)


      Related Properties (searching for properties):
      CPP_CG::Operation::Inline
      CPP_CG::Attribute::Inline
      CPP_CG::Relation::Inline

      Related Technotes:
      Technote 1324180 describes how to avoid generation of Inline function when a global function is reverse engineered from a C/CPP file.
      Technote 1671899 describes how to generate virtual accessor (getter) in Rational Rhapsody.

      Related Permanent Restrictions:
      PM01670 : "Adding argument to auto-generated function doesn't unflag it as auto-generated"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Copy Constructor

      A copy constructor is a special constructor in C++ for creating a new object as a copy of an existing object. In Rhapsody, you can create a copy constructor by following the steps below:

      1. Add a new constructor to the class you want to create the copy constructor.
      2. From the Constructor Arguments dialog box, click on "New" button.
      3. From the Argument Dialog box, un-check the "Use Existing Type" box.
      4. Enter "const <classname> &" in the C++ declarations text box (e.g. const CopyTest&).
      5. Click OK to save it.
      6. Implement each constructors as below.
      7. Add test code in Initialization code section of your configuration.
      8. Run GMR to see the output like below.

      There is also an article mentioning about the creation of a copy constructor in Rhapsody. For more information, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Generating standard operations"


    • Related Properties (searching for properties):
      <none>

      Related Technotes:
      Technote 1323721 describes how to declare a copy constructor but not define it.

      Related Permanent Restrictions:
      PM35131 : "OMList copy constructor doesn't explicitly call base constructor"
      PM00655 : "Rhapsody - Char* as event param prints junk values on console"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.









    Friend Class

      In general, you will use a ≪friend≫ dependency to make a friendship with other classes, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Code generation for friend classes and functions"

    • Alternatively, you can use CPP_CG::Class::Friend property that is used to specify friends to be added to class declarations. For example, if you specify “int t(); class x”, the following lines is generated in the public section of all class declarations. Separate multiple friends with semicolons.

      Sample A:

      Sample B:


      Limitations:
      No code is generated for a ≪friend≫ dependency to the template class.

      Related Properties (searching for properties):
      CPP_CG::Class::Friend

      Related Technotes:
      Technote 1599964 describes how to solve the issue of applying ≪friend≫ along with usage(Implementation) stereotype on the same dependency.


      Related Permanent Restrictions:
      PK85126 : "COMPILER ERROR WHEN USING FRIEND CLASS TO ACCESS PROTECTED MEMB ERS OF A CLASS"
      PK83716 : "COMPILER ERROR WHEN USING FRIEND CLASS TO ACCESS PROTECTED MEMB ERS OF A CLASS"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Use Struct instead of Class

      C++ specification allows you to define structure as class, and the class having class behavior is created using the keyword "struct". In Rhapsody, structure is supposed to be modeld using Type (Kind=Structure). But with Type, you can't add operations or attributes to it. If you want to generate a structure with class behavior, set the property CPP_CG::Class::GenClassAsStruct to be True on the class you want to convert, then in the code you will see "struct" keyword is generated instead of "class". You can also define a new term for such class-like structure to give a special meaning to it. The only difference between structure and class in C++ is that, by default, members of structure are public, otherwise the two are almost used interchangeably at code level. For more information about generating classes as structs, see IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Generating classes as structs in C++"


    • Related Properties (searching for properties):
      CPP_CG::Class::GenClassAsStruct

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Macro declaration (i.e #define)

      In C++, macro substitutions is defined using #define keyword at the upper section of header files. The general form of the directive is:

      #define macro-name character-sequence

      At preprocessing stage, the compiler will substitute each macro names encountered with the specified character sequence. That's how macro works. The common property to define macro in Rhapsody is CPP_CG::Class::SpecificationProlog to define in header file, and CPP_CG::Class::ImplementationProlog to define in implementation file.

      Example of defining macros in SpecificationProlog property:

      //#[ ignore
      #define true 1
      #define false 0
      //#]

      class class_0
      { ..}

      If you want to define a macro with parameters as you see in the code below, refer to Technote 1324301.

      #define %s(a,b) if(a<b)\
      printf("%d",a);\
      else\
      printf("%d",b)

      Else, you might use preserve annotation to define macros and position it in your preferred location in the code:

      //#[ preserve
      <Add your macro statements here>
      //#] preserve

      The code inside the preserve section is modeled as a text fragment and maintained inside Source Artifact, thus it is preserved in forward code generation. If you are not familiar with preserve annotation, see the related technotes below:

      Technote 1632630 describes difference among "ignore", "preserve" and "auto-generated" annotation used in the code generated by Rhapsody.
      Technote 1640085 describes a parsing error when round tripping "preserve" block containing macro statements without line terminator.
      Technote 1640396 describes what is Source Artifact in IBM Rational Rhapsody.

      In order to include C legacy library/resource into RiC++ model, syntax extern "C" is required. To enter "extern" statements, you can use CPP_CG::Class::SpecificationProlog or set properties according to the following image:




      Related Properties (searching for properties):
      CPP_CG::Attribute::MarkPrologEpilogInAnnotations
      CPP_CG::Class::ImplementationProlog
      CPP_CG::Class::SpecificationProlog
      CPP_Roundtrip::General::PredefineMacros
      CPP_CG::Class::MarkPrologEpilogInAnnotations
      CPP_ReverseEngineering::Parser::Defined

      Related Technotes:
      Technote 1468918 describes Parsing error when round tripping code changes in IBM Rational Rhapsody.
      Technote 1632630 describes difference among "ignore", "preserve" and "auto-generated" annotation used in the code generated by Rhapsody.
      Technote 1640085 describes a parsing error when round tripping "preserve" block containing macro statements without line terminator.
      Technote 1649175 describes how to remove Rational Rhapsody generated Annotations and its consequence.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.









    Vendor-Specific Modifier

      There are many compiler vendors (e.g. GNU-GCC) now support their own language extension so called modifiers. The __declspec keyword is an example of Vendor-Specific modifier available in Microsoft compiler. There are two of attributes commonly used together with __declspec, they are dllimport and dllexport. These keywords indicates to the compiler that a class/function/object is imported or exported from a DLL. See the code example below:


      class __declspec( dllexport ) class_0 {
      int i;
      virtual int func( void ) { return 1; }
      };

      In order to get Rhapsody generate a class declaration with a modifier, you can use CPP_CG::Class::DeclarationModifier property. Just adds a modifier to the property, and the keyword will be inserted between the class keyword and the class name in the generated code. This property is also available for event, argument, attribute, operation, and type metaclass.

      There are also property called PostDeclarationModifier and PreDeclarationModifier. These properties are used in conjunction with DeclarationModifier property. Modifiers you add to these properties are displayed in the corresponding section in the generated code:


      foo.h
      //## operation Operation_0()
      <PreDeclarationModifier> void <DeclarationModifier> Operation_0() <PostDeclarationModifier>;

      foo.cpp
      <PreDeclarationModifier> void <DeclarationModifier> foo::Operation_0() <PostDeclarationModifier> {
      //#[ operation Operation_0()
      //#]
      }

      For more details, see the property description of DeclarationModifier/PostDeclarationModifier/PreDeclarationModifier property.

      Related Properties (searching for properties):
      CPP_CG::<metaclass>::DeclarationModifier
      CPP_CG::<metaclass>::PostDeclarationModifier
      CPP_CG::Argument::PreDeclarationModifier

      Related Technotes:
      Technote 1323631 describes how to prevent RoundTrip issues caused by an added modifier using the PreDefineMacros property.

      Related Permanent Restrictions:
      PM18478 : "C++ incorrectly treats relations with const modifier as attributes rather than associations"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Constructor/Destructor



Scope





    Visibility (Public, Protected or Private)

      In C++, there are 3 types of visibility (Public, Protected or Private) exists. You can specify visibility for attributes, operations, type, relation and port. Visibility can be changed from the Visibility area in Feature window. By default, the visibility you specify in the visibility area only affects the type of access for the accesor/mutator generated for the selected model element. See below:

      Given you have the following model.

      Change the default visibility of colored elements to "Private".

      The below image show how the appearance of code change (Left: "Public", Right: "Private").


      You see that visibility change for operation and type are reflected in the generated code. Have looking at "myAttribute", only the visibility of accessor (get) method and mutator (set) method had changed, but the data member itself remains protected. In Rhapsody, data members are always protected, regardless of the visibility setting you select on Feature window. If you want to change the visibility of data member itself rather than changing the visibility of the accessor and mutator methods, you have to change CPP_CG::Attribute::Visibility property. If you set CPP_CG::Attribute::Visibility property to "From Attribute", the visibility you specify on Feature window becomes the visibility of the data member. CPP_CG::Class::Visibility property applies only to nested classes, which are defined inside of other classes. See the below image illustrating the usage of CPP_CG::Relation::DataMemberVisibility property (Left: "Protected", Right: "Private").


      To change the visibility of accessor/mutator individually, you can use CPP_CG::Attribute::AccessorVisibility and CPP_CG::Attribute::MutatorVisibility.
      For more information about visibility setting, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Visibility of operations"
    • Topic "About accessing attributes"

    • Note:


      From release 8.1.1 onward, Rhapsody shows visibility icon for Type on browser and diagrams.


      Related Properties (searching for properties):
      CPP_CG::Relation::Visibility (will be depreciated)
      CPP_CG::Attribute::Visibility
      CPP_CG::Class::Visibility
      CPP_CG::Package::Visibility
      CPP_CG::Type::Visibility
      CPP_CG::Relation::DataMemberVisibility
      CPP_CG::Attribute::MutatorVisibility
      CPP_CG::Attribute::AccessorVisibility

      Related Technotes:
      Technote 1427962 describes how to change the visibility of the auto generated methods.
      Technote 1591041 (Japanese) describes how to sort attributes within visibility groups as in pre-7.4.0.1 releases.
      Technote 1323547 describes why the visibility radio button doesn't affect attributes visibility.
      Technote 1640715 describes how to change visibility for an Associations in Rational Rhapsody.

      Related Permanent Restrictions:
      PM54240 : "Rhapsody attribute visibility discrepancy"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Namespace

      In C++, it is possible to create a local scope using the namespace keyword. To declare a namespace in Rhapsody, you can use CPP_CG::Package::DefineNameSpace property to define it, and use CPP_CG::Package::NameSpaceName property to name it. See the image below how namespace is generated in Rhapsody:



      To gain the direct access to elements within a defined namespace, you will need to include the following using statement, normally which will be shown right after necessary #include statements. The statement looks like below:

      using namespace NSTest;

      To generate using statement in Rhapsody, you can choose one of two following options:

      1. Generate using Dependency and UseNameSpace property
      2. Generate using SpecificationProlog/ImplementationProlog property

      In the case of using dependencies and UseNameSpace property, if you want to generate using statement into the implementation file instead, simply choose "Implementation" from Usage pull-down field and invoke code generation.

      Related Properties (searching for properties):
      CPP_CG::Package::DefineNameSpace
      CPP_CG::Dependency::UseNameSpace
      CPP_CG::Relation::DataMemberVisibility (depreciated in v8.0)
      CPP_CG::Package::NameSpaceName
      CPP_CG::Dependency::NamespaceAlias

      Related Technotes:
      Technote 1323659 describes Namespaces and Inheritances.
      Technote 1641456 describes a property to control display of namespace containment in Rational Rhapsody.
      Technote 1645128 describes how to create unnamed namespace in Rational Rhapsody.

      Related Permanent Restrictions:
      PM17569 : "Implementation Prolog/Epilog generated inside namespace"
      PK93248 : "Applying property UseNameSpace on the class level does not generate 'using namespace X'"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




Operation/Function





    Const member function

      A constant member function can not modify any non-static data members or call any member functions that aren't constant. To create a const member function in Rhapsody, you can simply flag Constant modifier on Feature window:


      As result, the following code will be generated:


      void foo (int a) const {
      ...
      }


      Related Properties (searching for properties):
      <none>

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Call by Value vs Reference

      C/C++ allows you to pass arguments either by value or reference. In the method of passing by value, arguments are passed as copy, thus altering arguments within the called function has no effect on variables used to call it. On the contrary, altering arguments passed by reference results in affecting the value of actual variables in the calling function. Pass by reference is achieved in two ways either using pointer symbol (*) or reference parameter (&). In Rhapsody, you can control how you want to pass arguments by adjusting directions (in/out/inout) of individual arguments and relevant properties.

    • Introduction to directions usage (click to collapse or expand)
    • Specify directions for a user-defined type (click to collapse or expand)

    • Since Rhapsody v8.0.3, you can use the Code pattern field to fine-tune the code that is generated for the arguments of a specific operation or event. If you want to modify the code generated when a given class, type, or event is used as an operation or event argument anywhere in your model, you can set the value of the relevant In, Out, or InOut property at the class, type, or event level. See below to understand how Code pattern field works.


      For more information about Code Pattern feature, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Fine-tuning code generated for arguments"


    • Related Properties:


      CPP_CG::Type::In
      CPP_CG::Type::Out
      CPP_CG::Type::InOut

      Related Technotes:
      Technote 1423290 describes about default value for property CPP_CG:Type:ReferenceImplementationPattern.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.







    Accessor/Mutator

      Accessors and mutators are automatically generated for each attribute and relation of the class. To learn the basic of its usage, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Accessors and mutators for attributes and relations"
    • Topic "About accessing attributes"

    • To understand visibility setting for accessor and mutator, see "Table of Contents > Scope > Visibility (Public, Protected or Private)" section.

      In general, auto-generated code like accessor/mutator is being placed under strict control of Rhapsody, thereby you may not be able to make every changes you want to make on user code. For example, you won't be able to remove the pointer "*" from the code below, which will be generated from the attribute with a class chosen as its data type:


      //## auto_generated
      class_0* getAttribute_0() const;


      In this case, manipulating CPP_CG::Type::ReturnType (Default: "$type*") of class_0 won't help. One workaround will be to create a new typedef (e.g. typedef class_0 myType) and put "myType" in the place of class_0 to generate code like "myType getAttribute_0() const;". Another workaround is to pull the accessor out of Rhapsody control using CG::CGGeneral::GeneratedCodeInBrowser property, modify it by hand and maintain it. For more information, see "How to inline operations managed by Rhapsody" section at "How to inline operations managed by Rhapsody".


      Related Properties (searching for properties):
      CG::Attribute::Mutator
      CG::Attribute::Accessor
      CPP_CG::Attribute::MutatorGenerate
      CPP_CG::Attribute::AccessorGenerate
      CPP_CG::Type::ReturnType
      CG::CGGeneral::GeneratedCodeInBrowser
      CPP_CG::Type::In
      CPP_CG::Type::Out
      CPP_CG::Type::InOut

      Related Technotes:
      Technote 1454820 describes how to enable Accessor and Mutator for an attribute in Rhapsody.
      Technote 1323495 describes how to turn off the accessor (get) and mutator (set) for an attribute.
      Technote 1638637 describes how to generate different qualifiers for arguments in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Default Argument

      In C++, you can assign a function argument a default value, which will be used automatically when no corresponding argument is specified when the function is called. In Rhapsody, you can assign default values from the Arguments tab of Function Feature window:



      The below is the actual code generated from function_0, and you will see specified default values are assigned to corresponding arguments in the function declaration:



      If you are interested in how directions (In/Out/Inout) work, see the "Introduction to directions usage" section in "Table of Contents > Operation/Function > Call by Value vs Reference" section.

      Related Properties (searching for properties):
      <none>

      Related Technotes:
      Technote 1423290 describes about default value for property CPP_CG:Type:ReferenceImplementationPattern.
      Technote 1638637 describes how to generate different qualifiers for arguments in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>








    Variable Length Argument

      To define a function that takes a variable number of arguments, use three periods(...) at the point where the variable number of arguments take place as you see below:

      void testA(int i, ...);

      For more information about how to specify a variable-length argument list, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Generating variable-length argument lists"


    • Related Properties (searching for properties):
      CG::Operation::VariableLengthArgumentList

      Related Technotes:
      Technote 1324162 describes how to generate argument of a function with a void keyword.
      Technote 1323502 describes if Rhapsody understand the syntax "..." in a variable length argument list.
      Technote 1323702 describes how to add variable length argument list for the function or operation in Rhapsody.

      Related Permanent Restrictions:
      PM15400 : "Test Conductor: VariableLengthArgumentList is not supported"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Void Argument

      In C++ Standard/Specification, you are allowed to include void in the argument list where the operation doesn't take in any arguments. To generate an empty argument list, you can use CPP_CG::Configuration::EmptyArgumentListName property. For more information, refer to Technote 1324162.


      Related Properties (searching for properties):
      CPP_CG::Configuration::EmptyArgumentListName

      Related Technotes:
      Technote 1324162 describes how to generate argument of a function with a void keyword.

      Related Permanent Restrictions:
      <none>








    Operator Overloading






    Argument Manipulation

      Since Rhapsody v8.0.3, you can use the Code pattern field to fine-tune the code that is generated for the arguments of a specific operation or event. If you want to modify the code generated when a given class, type, or event is used as an operation or event argument anywhere in your model, you can set the value of the relevant In, Out, or InOut property at the class, type, or event level. See below to understand how Code pattern field works.


      For more information about Code Pattern feature, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
    • Topic "Fine-tuning code generated for arguments"

    • Related Properties (searching for properties):
      CPP_CG::Type::In
      CPP_CG::Type::Out
      CPP_CG::Type::InOut

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Return Type






    Unnamed Argument

      C++ allows the use of unnamed arguments in the operation signature. An example of named/unnamed argument generated is shown below:

      void foo (int a) {//example of a named argument}
      void foo (int) {//example of a unnamed argument}

      This style of code generation is useful to avoid a certain type of compilation error such as "variable xyz is not used". For additional information, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Specify that argument names should not be included in the operation signature"

    • Related Properties (searching for properties):
      CPP_CG::Argument::PrintName

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>

      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Function Pointer

      Function Pointer is a type that points to the address of a function. To implement a function pointer in Rhapsody, you can simply create a "Type" and set the kind as "Language". See below as an example to model Function Pointer in Rhapsody:

      1. Create a new class and "Language" type as shown below.
      2. Define a function pointer by editing Description tab of "plus" type.
      3. Implement the body of "addition" operation.
      4. Add code to assign the address of "addition" operation to "plus" type.
      5. Generate code and see the result similar to below.
      6. See the output on command prompt.


      Related Properties (searching for properties):
      CG::Class::AdditionalInitializationCode
      CPP_CG::Class::SpecIncludes

      Related Technotes:
      Technote 1414320 describes a compilation problem caused by round-tripping a function pointer types in C++ template.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Friend Function






    Naming Manipulation

      The ImplementationName property enables you to give an operation one model name and generate it with another name. It was originally introduced as a workaround that enables you to generate const and non-const operations with the same name. See the example below:

      1. Create a class A.
      2. Add a non-const operation f().
      3. Add a const operation f_const().
      4. Set CPP_CG::Operation::ImplementationName property for f_const() to “f.”
      5. Generate the code.

      The resulting code is as follows:

      class A {
      ...
      void f(); /* the non const f */
      ...
      void f() const; /* actually f_const() */
      ...
      };


      Related Properties (searching for properties):
      CPP_CG::Operation::ImplementationName
      CPP_CG::Attribute::ImplementationName
      CPP_CG::Type::ImplementationName

      Related Technotes:
      Technote 1423443 describes how to customize generation of names for user defined operations.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.








    Template Function



Interface



Relationship





    Relation Configuration

      Rhapsody allows you to implement relations in various ways depending on the value you specify at CG::Relation::Implementation property. The property default value is set to "Default", meaning that Rhapsody will decide what kind of implementation is the most appropriate for a specific relation. When the value of the Implementation property is set to "Default", Rhapsody determines what category of properties to use (e.g. Scalar or BoundedUnordered) based on several criteria, including:

      * Is the multiplicity specified?
      * Is the attribute was defined as ordered?
      * Is the attribute is of a predefined type?

      For example, if multiplicity is set to * or 1..*, code generation for the attribute or relation will be based on the values of the properties contained in the UnboundedUnordered metaclass. If the Ordered check box is also selected, then Rhapsody will use the values of the properties in the UnboundedOrdered metaclass.

      Usually in case of a non-multiply relation, if the related class is an embeddable component, the implementation is set to "Embedded Scalar", or else the implementation scheme will be set to "Scalar". In a multiply relation, the relation will be implemented as either Qualified, UnboundedOrdered, UnboundedUnordered, Embedded Fixed, Static Array, or Fixed. If you would prefer manually specifying what category of properties Rhapsody should use for a specific relation, you can do so by selecting one of the other possible values for the CG::Relation::Implementation property.

      • List of values available for CG::Relation::Implementation (click to collapse or expand)


      The value of "User" can be used to define your own implementation scheme and setting the desired implementation scheme properties located under <Container Set>::User property.



      Container Set is a place holder that define a collection of ways to implement relations. You are able to define what kind of containers will be used to contain the model relations by setting the CPP_CG::Configuration::ContainerSet property. For more detail, see following sections:
    • "Table of Contents > Relationship > User Container"
    • "Table of Contents > Relationship > Container Usage"

    • For additional information, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Associations implementation"


    • Related Properties (searching for properties):
      CG::Relation::Implementation
      CPP_CG::Configuration::ContainerSet
      CPP_CG::Relation::ScalarContainment

      OMContainers
      OMUContainers
      STLContainers
      ├───BoundedOrdered
      ├───BoundedUnordered
      ├───EmbeddedFixed
      ├───EmbeddedScalar
      ├───Fixed
      ├───Qualified
      ├───Scalar
      ├───StaticArray
      ├───UnboundedOrdered
      ├───UnboundedUnordered
      ├───User
      ├────────Add
      ├────────Create
      ├────────CreateByValue
      ├────────CreateStatic
      ├────────CType
      ├────────Find
      ├────────FullTypeDefinition
      ├────────Get
      ├────────GetAt
      ├────────IncludeDirective
      ├────────IncludeFiles
      ├────────Init
      ├────────InitInCtorBody
      ├────────IterCreate
      ├────────IterCreateByValue
      ├────────IterGetCurrent
      ├────────IterIncrement
      ├────────IterIncrementForCleanUp
      ├────────IterIncrementForInit
      ├────────IterReset
      ├────────IterReturnType
      ├────────IterTest
      ├────────IterType
      ├────────RelationTargetType
      ├────────Remove
      ├────────RemoveAll


      Related Technotes:
      Technote 1324166 describes how is FIFO ordering taken care of in relationships between classes.
      Technote 1323475 describes how to use the STL Container with IBM Rational Rhapsody.
      Technote 1323771 describes how you can use forward declarations with containers.
      Technote 1423290 describes about default value for property CPP_CG:Type:ReferenceImplementationPattern.
      Technote 1405221 describes how to initialize one-to-many association relation with named Objects.
      Technote 1638652 describes how an alternative to have pointers for non-composition Association in Rational Rhapsody.l

      Related Permanent Restrictions:
      PK83598 : "COMPOSITION AGGREGATION SHOULDN'T AFFECT CG:RELATION:ORDERED PROPERTY"
      PK63360 : "Rhapsody does not support const association".


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    User Container

      Model elements in Rhapsody are all connected via "relation" such as association, aggregation, dependency and so forth. Those relations are implemented into code level by using a set of Containers (e.g. OMContainer, OMUContainer, STLContainer) already available in Rhapsody. Not only "relations" but a data member in a class can be also considered as "has-a" relationship and Scalar or EmbeddedScalar will be used to implement such "relation". Relations in Rhapsody must be implemented based on the information defined in the Container Set you choose at CPP_CG::Configuration::ContainerSet property. For each type of Containers, there is a group of sub properties defined which will be applied for different type of relations. For more details about how Container Set should be used in Rhapsody, see "Table of Contents > Relationship > Container Usage" section.

      You can also define your own Container if the existed ones doesn't satisfy your specific requirements. Unfortunately, there is not much materials available explaining how you can develop your own container. The current best approach would be to copy the existing Container Set, extend it by referring the relevant topics in help manual, and test it through trial and error.

      Important:
      You should implement all container types (e.g. Scalar, EmbeddedScalar, etc) you find in the existing Container Set you refer to. Code Generation, Reverse Engineering, RoundTrip are all tightly coupled with Container Set, and use of a premature container could cause problems to those code related functionalities. To verify your container you can generate various code using your own container, and validate them through experiments, tests, trial and error, and a lot of observation over the generated code. In the end, the quality of container will directly impact the quality of application you produce. It is always worth testing it before deploying it.

      To create a new property subject for your container, see IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Customizing existing properties"


    • Related Properties (searching for properties):
      CPP_CG::Configuration::ContainerSet

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Use template to define relationship



    Container Usage

      Rhapsody uses containers for managing all "1 to many" and "many to many" relations which is normally set on UML relationships such as association and aggregations, but can also be applied to define how attributes, classes, or objects are related with the owning class, for example. The container is a collection of object implemented using template classes, this is called OMContainers. Rhapsody also support 2 additional containers. OMUContainers and STLContainers. OMUContainers is similar to OMContainers except that templates are not used, this can help reduce code size considerably but may cause significant type casting operations. If your target/cross-compiler (e.g. eC++) doesn't support template-based containers, then you might consider to use OMUContainers instead and rebuild OXF with OM_NO_TEMPLATES_USAGE option.

      • OM_NO_TEMPLATES_USAGE option (click to collapse or expand)


      STLContainers is implemented using Standard Template Library (STL). The relation implementation with STL containers is supported out-of-the-box. You can also configure Rhapsody to use an off-the-shelf container library such as RogueWave™ or you can define your own Container Set. For more information about defining your own container, see "Table of Contents > Relationship > User Container" section.

      For the list of container types available, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Containers package"


    • Which type of container is used to implement a relationship is decided based on the type of relation you're implementing and the multiplicity you specify. The following image and table shows how Rhapsody implements a simple association below using OMContainer set:



      Container Type CommentDialog settingExample code
      ScalarUse CPP_CG::Relation::ScalarContainment if you want the reference (& ) sign is generated for the association rather than the pointer symbol.B* itsB;
      Array
      B* itsB[10];
      B* itsB[n];
      OMCollection A type-safe, dynamically sized array. OMCollection<B*> itsB;
      OMHeap A type-safe, fixed size heap implementation. Used internally within framework, but can be used directly by the client application.Not Applicable
      OMIterator A type-safe iterator over an OMAbstractContainer (and derived containers). An iterator is a friend class to a container, that is used to keep a pointer to the current element in the container.Rhapsody provides an OMIterator class that can be used as follows to iterate through a container:Not Applicable
      OMList A type-safe, linked list. OMList<B*> itsB;
      OMMap A type-safe map, based on a balanced binary tree (log(n) search time). OMMap<int, B*> itsB;
      OMQueue A type-safe, dynamically sized queue. It is implemented on a cyclic array, and implements a FIFO (first in, first out) algorithm. .Used internally within framework, but can be used directly by the client application.Not Applicable
      OMString A string class. This class allows operations such as:
      stringA=StringB;
      stringA += stringB;
      length=string.GetLength();
      character=string[5];
      Not Applicable
      OMStack A type-safe stack that implements a LIFO (last in, first out) algorithm. Used internally within framework, but can be used directly by the client application.Not Applicable
      OMStaticArray A type-safe, fixed-size array.

      For more information about using various relation types in Rhapsody, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Using relations"

    • In UML models, a relationship is a connection between model elements. A UML relationship is a type of model element that adds semantics to a model by defining the structure and behavior between the model elements. Rhapsody use information defined in Container Set to implement a relationship including attribute, association, aggregation, composition, and so on. You can apply a specific type that exists in the specified Container Set by changing relation properties. For example, Scalar container is used by default to implement "1 to 1" association relation, but you can apply OMList container for the particular relation by setting CG::Relation::Implementation to "BoundedOrdered".

      For your additional reference, see below for the comparisons table for OMList, OMCollection and OMMap.

      • OMList vs OMCollection vs OMMap (click to collapse or expand)


      Related Properties (searching for properties):
      CPP_CG::Configuration::ContainerSet
      CG::Attribute::Implementation
      CG::Relation::Implementation

      Related Technotes:
      Technote 1323475 describes how to use the STL Container with IBM Rational Rhapsody.
      Technote 1423617 describes how to change relation type from OMCollection to OMList.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




Initialization


    Constructor Initialization

      There are two ways to initialize data members of class:

      • Use of initialization body section
      • Use of initial value for attributes

      If you want to add initialization code in the constructor body, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Adding initialization code in the constructor body"


    • Below are examples for initializing data members with using the initialization body and initial value:

      • Follow the steps to initialize attributes using initialization body (click to collapse or expand)
      • Follow the steps to initialize attributes using initial value (click to collapse or expand)


      Related Properties (searching for properties):
      CPP_CG::Operation::DisableAutoGeneratedInitializer

      Related Technotes:
      Technote 1323679 describes how to turn off initialization of pointers to NULL in constructor.
      Technote 1472395 describes how to initialize the parent class before attribute initialization in Rational Rhapsody.
      Technote 1324337 describes how to create multiple objects of the same class with different attribute values.
      Technote 1670515 describes how to change the order of initializer members for a constructor.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Initialization Technique

      This section introduces various initialization techniques based on scenarios:

      • How to initialize class members in the constructor (click to collapse or expand)
      • How to initialize a global constant/static variable in H or CPP (click to collapse or expand)
      • How to make a group of classes invoke the same initialization call (click to collapse or expand)
      • How to initialize array of structure (click to collapse or expand)
      • How to initialize association pointer using a specified value (click to collapse or expand)


      To disable class members being automatically initialized by Rhapsody, you can use CPP_CG::Operation::DisableAutoGeneratedInitializer property. This property can be set either on constructor or class itself. Once the automatic-initializer is disabled, then you are free to initialize class members in any order you want.

      Related Properties (searching for properties):
      CPP_CG::Attribute::InitializationStyle
      CPP_CG::Event::InitializationStyle
      CPP_CG::Relation::InitializationStyle
      CPP_CG::Attribute::AttributeInitializationFile
      CG::Class::AdditionalInitializationCode
      CG::Package::AdditionalInitialization
      CG::Operation::UseDefaultAttributeValues
      CPP_CG::Operation::DisableAutoGeneratedInitializer
      CG::Relation::SafeInitScalar

      Related Technotes:
      Technote 1409548 describes how to disabling relation initialization in the constructor.
      Technote 1323474 describes how to disable code generation of the Default Constructor.
      Technote 1323679 describes how to turn off initialization of pointers to NULL in constructor.
      Technote 1472395 describes how to initialize the parent class before attribute initialization in Rational Rhapsody.
      Technote 1324099 describes how to get the "equal to" format for assigning values to variables.

      Related Permanent Restrictions:
      PM17185 : "The initializer list place parent class constructor after the class data member"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




    ] Array & Structure The array is modeled as a variable or attribute. See the image illustrating how to create and initialize arrays in Rhapsody. NOTE: Following changes are added to each variables: CPP_CG::Attribute::InitializationStyle=ByAssignment CPP_CG::Attribute::VariableInitializationFile=Specification For more information about %s usage, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
  • [Topic "Using %s"




  • Global/Static Variable

      You can create global variables visible to all classes in the same package. For details, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Creating global variables"

    • See the code below is declaring a constant global variable in package header and initialize it in the implementation file:

      global.h:
      //## attribute global_variable
      extern const int global_variable;

      global.cpp:
      //## attribute global_variable
      const int global_variable = xyz;


      To produce the code similar to above, refer to "How to initialize a global constant/static variable in H or CPP" topic.

      There exists 3 types of modifier for variable and attribute:



      • Constant specifies whether the attribute is read-only or modifiable.
      • Reference specifies whether the attribute is referenced as a reference, such as a pointer (*) or an address (&) in C++.
      • Static creates a static attribute, which belongs to the class as a whole rather than to individual objects.

      The static modifier may also be applied to global variables. When this is done, it causes that variable's scope to be restricted to the file in which it is declared. If you select the Static check box on the Features window for an attribute, use the Initial Value box to enter an initial value. You can open a text editor for entering initialization code by clicking
      the "..." button associated with the box.

      When you generate code for a static attribute of a class, the initial value entered is generated into a statement that initializes the static attribute outside the class constructor. Consider the following initial values for three static attributes:



      When you generate code, these values cause the following statements to be generated in the specification file A.h:


      //-------------------------------------------------
      // A.h
      //-------------------------------------------------
      class A {
      //// User explicit entries ////
      protected:
      //## attribute attr3
      static OMString attr3;
      //## attribute attr1
      static int attr1;
      //## attribute attr2
      static OMBoolattr2;
      ...
      };


      In the implementation file, A.cpp, the following initialization code is generated:


      #include "A.h"
      //-------------------------------------------------
      // A.cpp
      //-------------------------------------------------
      // Static class member attribute
      OMString A::attr3 = "Shalom";
      // Static class member attribute
      int A::attr1 = 5;
      // Static class member attribute
      OMBoolean A::attr2 = true;
      A::A() {



      Check the property description for PP_CG::Attribute::EnableInitializationStyleForStaticAttributes and Model::Attribute::PrefixForStatic for advance users who wants to control how static variables should be initialized (assignment vs initializer) and be named.

      Related Properties (searching for properties):
      CPP_CG::Attribute::EnableInitializationStyleForStaticAttributes
      Model::Attribute::PrefixForStatic

      Related Technotes:
      Technote 1468918 describes Parsing error when round tripping code changes in IBM Rational Rhapsody.
      Technote 1421127 describes that CPP_CG:Attribute:EnableInitializationStyleForStaticAttributes becomes nonfunctional for attributes if set to False above in hierarchy.

      Related Permanent Restrictions:
      <none>




Ordering/Sorting


    General Ordering technique

      Consider the case where your model has variables defined directly in a package. These variables define various constants. Some of these variables are defined in terms of others, such that the dependent variable must be declared before the others for the application to compile. In pre-7.5 releases, Rhapsody did not allow you to override the default alphabetical order of the variable declarations.

      To learn ordering technique for various model elements, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Changing the order of operations in generated code"
    • Topic "Changing the order of types in the generated code"
    • Topic "Changing the order of struct or union members in generated code"
    • Topic "Editing the declaration order of objects"
    • Topic "Reordering elements in the browser"
    • Topic "Changing the order of usage dependencies in generated code"


    • Apart from mentioned above, there is another way to accomplish the same goal if you use Rhapsody v7.5 or higher. You can simply change the order of the code elements in the file and then invoke Roundtrip to reflect changes done in the code into the model. Order information is preserved in Source Artifact and will be taken into account in forward code generation. Source Artifact is hidden by default. You can see it by choosing View > Browser Display Options > Show Source Artifacts (do so when focus is on the Browser). You can create such Source Artifacts manually in the model. You can then map certain model elements into Source Artifact and arrange the order as you link. Code Generation will use this information.

      If you want to change the order of elements, the “code respect” option must be activated (CPP_Roundtrip::General::RoundtripScheme = "Respect"). In "code respect" mode, Rhapsody will preserve the order of the following elements during RountTrip and maintain ordering information for the next code generation and onward:

      – Global elements
      – Class elements
      – #includes and forward declarations
      – Auto-generated operations (excluding statechart and instrumentation code)

      Another customization can be done by CG SDK. To learn more about CG SDK, refer to ..\Samples\CustomCG samples. Also, take a look at "Overview of model simplification process" section at "Table of Contents > Overview > Scope of this documentation".


      Related Properties (searching for properties):
      CG::<metatype>::AttributesAutoArrange
      CPP_Roundtrip::General::RoundtripScheme

      Related Technotes:
      Technote 1323568 describes how to reorder variables in pre-7.5 format.
      Technote 1601109 describes how to control order of include statements in Rational Rhapsody.
      Technote 1323558 describes how to change the order of object initialization in Configuration Main file.
      Technote 1640713 describes how to change the order of types generated in the code in Rational Rhapsody.

      Related Permanent Restrictions:
      PM57357 : "problems defining Implementation/Specification Header"
      PM63076 : "There is a limitation of the Rhapsody Doxygen support for namespace and idl module"
      PM72824 : "DescriptionBeginLine has no effect on package in Rational Rhapsody"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    #include ordering

      In Rhapsody the easiest way to force order of include statements is to directly edit the generated code itself and change the order of statements. After round-tripping, the information regarding the order is kept in the model and in next Code Generation the order is preserved. You can manually edit Source Artifact to reposition elements, but modifying it through RoundTrip is recommended. Note that the code preserving feature is working when the value of the property CPP_Roundtrip::General::RoundtripScheme is the default value of Respect.

      Since Rhapsody v8.0.3, you can control the order of an include statement created from dependencies you defined within the generated code. The Edit Dependencies Order operation allows you to specify the order of the files to include.


      For additional information about "Edit Dependencies Order" feature, see the property definition for CPP_CG::Class::DependenciesAutoArrange and also check out the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Changing the order of usage dependencies in generated code"


    • Related Properties (searching for properties):
      CPP_Roundtrip::General::RoundtripScheme
      CPP_CG::Class::DependenciesAutoArrange

      Related Technotes:
      Technote 1627219 describes how to ensure your header gets included before any other headers Rhapsody generates.

      Related Permanent Restrictions:
      PM81096 : "Rhapsody CG generates the include statements in reverted order"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Struct and Union members

      The order of elements within struct, enumeration and union body is controlled via Feature window:



      The AttributesAutoArrange property controls the order of struct and union members in the code generated for your model. When set to False, the order of the members in the code is the same as the order displayed on the Attributes tab of the features dialog. By default, the property value is False. When set to True by either manually or by changing ordering using Up&Down arrow key from Feature window, members will appear in alphabetic order in the code regardless of the order displayed on the Attributes tab. This property can be set from the project level downward.

      Prior to release 7.5.3, you could control the order of struct and union members in generated code only by modifying the value of the CG::Class::AttributesAutoArrange property, which controlled both the order of class attributes and the order of struct and union members. In 7.5.3, the CG::Type::AttributesAutoArrange property was added to allow users to control the order of struct and union members in generated code regardless of the setting used for class attributes. The UseClassOrderSetting property was therefore added to the compatibility profile for 7.5.3 in order to provide the previous code generation behavior for older models. When UseClassOrderSetting is set to True, the order of struct and union members is controlled by the value of the CG::Class::AttributesAutoArrange property rather than the value of the CG::Type::AttributesAutoArrange property.

      For additional information, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

    • Topic "Changing the order of struct or union members in generated code"


    • Related Properties (searching for properties):
      CG::Type::UseClassOrderSetting
      CG::Class::AttributesAutoArrange
      CG::Type::AttributesAutoArrange

      Related Technotes:
      Technote 1323701 describes how to preserve the order of attributes when performing a roundtrip.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.









    Constructor Initializer List

      In Rhapsody 8.0.6, the ordering capability of constructor's initializer list was improved. As result, you can now sort the order of initialized members (e.g. members, association ends , user code) as you wish to be by moving up and down elements mapped inside Source Artifact. This enhancement was introduced aiming to prevent potential compiler warnings For more information, refer to Technote 1670515.

      Related Properties (searching for properties):
      CPP_CG::Operation::DisableAutoGeneratedInitializer
      CPP_CG::Operation::OrderedConstructorInitializer

      Related Technotes:
      Technote 1670515 describes how to change the order of initializer members for a constructor.

      Related Permanent Restrictions:
      <none>

      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.



Optimization


    Port Multicast

      Rhapsody provides the ability to multicast event/data from a single port/flowport to multiple ports/flowports that are connected to with links. This multicasting capability is available only for flow ports and rapid ports (ports with no contracts/interfaces which relay only events, this is Rhapsody-specific concept). As of Rhapsody v8.1 multicasting through regular ports are supported only in direct 1 hop.



      For more information about Port multicasting in general, refers to the following articles:

    • Topic "Port multicasting"
    • Topic "Using rapid ports"
    • Topic "Rapid prototyping with ports"


    • Also note that in situations where multicasting is required, if you are manually specifying event-sending code in a statechart (as opposed to using a Send Action element), then you must use special multicasting syntax rather than the usual event-sending syntax. For example, instead of OUT_PORT(PORT)->GEN(EVENT), you would use RiC_MULTICAST_GEN_PORT(PORT, EVENT) for C code, or MULTICAST_GEN(PORT, EVENT) for C++ code. See "Rapid Port Multicast" example below.

      • Flowport Multicast

      • Controlled via CPP_CG::flowPort::SupportMulticast property. By default, it will be enabled (For legacy models, this property is disabled). The key point is to define attributes with the same name as the flow ports.


      • Rapid Port Multicast

      • Rapid ports are ports that have no provided and required interfaces. These ports relay any events that come through them. The multicasting ability is controlled via CPP_CG::Port::SupportMulticast property. The new Macro "MULTICAST_GEN(PORT, EVENT)" was introduced in order to invoke multicast GEN. The conventional invocation "OUT_PORT(PORT)->GEN(EVENT)" is still supported, and will generate an event on the first link. If you don't want to mess up with the code, you should use the 'Send Action' node to send a multicast event via a port.

      Related References:
      " What's new in IBM Rational Rhapsody: Version 7.5"

      Related Properties (searching for properties):
      CPP_CG::flowPort::SupportMulticast
      CPP_CG::Port::SupportMulticast

      Related Technotes:
      Technote 1390801 describes how to mutlicast in IBM Rational Rhapsody 7.5 Broadcasting of events works (Being Revised)
      Technote 1645412 describes how to send a constant data through FlowPort using Rational Rhapsody.
      Technote 1660183 describes support status of FlowPort in Rhapsody with regard to its depreciation in SysML v1.3.
      Technote 1676891 describes how to relay an event to multiple ports inside a composite class in Rhapsody C++ and C.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Code Size



    Parallel Code Generation

      Rational Rhapsody is often used for the development of large and complex applications. You can now use multiple cores of the computer when generating applications that consist of multiple components. This helps code generation performance. The CG::General::ParallelCodeGeneration property is used to activate parallel processing and control the number of parallel processes to launch in conjunction with the CG::General::UserDefinedParallelProcesses property. To enable full code generation output, set CG::Configuration::PrintParallelCodeGenerationOutput to True. The code generation command that is launched is specified in the CG::General::ParallelCodeGenerationCommand property. By default, a Rhapsody command line (RhapsodyCL.exe) is launched, but it is possible to customize the command that is invoked to, for example, run code generation on another machine or on a server farm. Parallel code generation provides the benefit of allowing you to continue working in Rhapsody GUI while code is being generated.

      For more information about Rhapsody CG mechanism, refers to the following articles:

    • Topic "Parallel code generation"
    • Topic "Generating code from a Rational Rhapsody model"


    • Related References:
      " What's new in IBM Rational Rhapsody 8.0 and Rhapsody Design Manager 4.0"

      Related Properties (searching for properties):
      CG::General::ParallelCodeGenerationCommand
      CG::General::ParallelCodeGeneration
      CG::Configuration::PrintParallelCodeGenerationOutput
      CPP_CG::Configuration::ClassesPerCGCall

      Related Technotes:
      Technote 1612696 describes how to speed up build process using /MP option of VS compiler (Japanese).
      Technote 1567337 describes how to avoid memory allocation failure during heavy code generation.
      Technote 1677491 describes Rhapsody Code Generation with dependencies takes longer on single processor.
      Technote 1692364 describes how to enable full code generation output with Parallel Code Generation enabled in Rational Rhapsody.

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.




Others


    DBCS/Unicode

      Rhapsody supports following languages and character sets in the bracket.

        • English (iso-8859-1)
        • Japanese (Shift-JIS)
        • Korean (euc-kr)
        • Simplified Chinese (GB2312)
        • Traditional Chinese (big5)

      Rhapsody currently doesn't support Unicode. However, RFE 28034 has been submitted to enable Unicode support in Rhapsody.

      Related Properties (searching for properties):
      <none>

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      PM82432 : Use of LineWrapLength property on non-English OS causes incorrect code generation due to lack of unicode support.


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    External File Management

      Rhapsody enables you to not only visualize frozen legacy code but also edit external code as external elements. This external code is code that is developed and maintained outside of Rhapsody. Conventionally, to include those external files into build process, you had to map them to component files. In recent versions, you can take several options. The Technote 1621937 explains how you can effectively control the inclusion of external files into MakeFile using Source Artifact.

      For more information about using external elements, see the following topic for your reference:

    • Topic "Visualization of external elements"

    • Related Properties (searching for properties):
      CG::<metaclass>::UseAsExternal
      CG::File::AddToMakefile

      Related Technotes:


      Technote 1621937 describes how to include external source files into build process using Source Artifact instead of component files.
      Technote 1575542 describes how to use the property AddToMakefile in Rational Rhapsody.
      Technote 1642094 describes how to generate code in a specific path in Rational Rhapsody.

      Related Permanent Restrictions:
      PM26628 : "Rhapsody does not generate proper make files"


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Exception Handling

      An embedded system is expected to be fault-tolerant when it is operating in a mission critical environment. If you are planing to develop an application which has to continue operating properly in the event of the failure, you might find the following Q&A useful.

      (1) Question: How OXF handles if an expected event internally rises?

      Answer: Rhp C++ OXF contains OMReactive::handleNotConsumed callback function, which is called, when event consumption failed. You can define your own operation in reactive class, which will override this function. Another case is timeout failure. This scenario also can be handled by overriding OMReactive::TimeoutSetFailure operation. In addition, there is CPP_CG::Operation::ThrowExceptions property, which can be used to specify the exceptions that an operation can throw.

      (2) Question: Does OXF pass control back to user code somehow so that user's exception handler can be triggered?

      Answer: OXF doesn't contain any exception handlers, but by modifying and recompiling the bundled OXF model, you can add exception handlers anywhere in OXF you want it to be. That is a reason why Rhapsody supply OXF model and its source code. In addition since version 7.5.1, it is possible to create a master exception handler in main function. By default, it is created only if your model contains C++ MISRA profile. But if you have no intentions to use MISRA C++ profile, then you can force code engine to generate it by adding CPP_CG::Configuration::MasterExceptionHandlerGenerate, CPP_CG::Configuration::MasterExceptionDeclaration and CPP_CG::Configuration::MasterExceptionHandler property to siteC++.prp file. Then main function will be generated like the following:



      (3) Question: Any tips to develop fault-tolerant systems?

      Answer: Most of adapters call OM_NOTIFY_ERROR macro, when some system call fails. This macro is defined in Share/LangCpp/osconfig/<adapter>/omosconfig.h file and usually empty. You can modify it and process these failed calls. Some failure such as semaphore failure may not produce an exception.

      If you're looking for how to develop safety critical software in Rhapsody, you should read the following topics for your reference:

    • Topic "Agile analysis practices for safety-critical software development"
    • Topic "Safety Critical Software Development: ISO 26262, IEC 61508 and DO-178B"

    • (4) Question: Does Rhapsody support Function-Try block as seen below?


      class Sample {
        int m_a;
      pubic:
        Sample(int a)
        try
        : m_a(a)
        {
          //
        }
        catch (...) {
          //
        }
      };


      Answer: No. But RFE 38422 is submitted.

      Related Properties (searching for properties):
      CPP_CG::Operation::ThrowExceptions
      CPP_CG::Configuration::MasterExceptionHandlerGenerate
      CPP_CG::Configuration::MasterExceptionDeclaration
      CPP_CG::Configuration::MasterExceptionHandler

      Related Technotes:
      <none>

      Related Permanent Restrictions:
      <none>

      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    C++11 Standard

      Rhapsody doesn't support C++11 Standard yet. Following C++11 extensions are not supported:

      • Strongly typed enum (click to collapse or expand)

      • example:

        typedef enum : long long {
        A = 0x1LL,
        B = 0x2LL,
        } XXX;

  • Move constructor & assignment (click to collapse or expand)

  • You will likely encounter a parsing error when you roundtrip the code in above examples, or any other C++11 standard Rhapsody doesn't support today.

    Related Properties (searching for properties):
    <none>

    Related Technotes:
    Technote 1468918 describes parsing error when round tripping code changes in IBM Rational Rhapsody.
    Technote 1632630 describes difference among "ignore", "preserve" and "auto-generated" annotation used in the code generated by Rhapsody.
    Technote 1640085 describes a parsing error when round tripping "preserve" block containing macro statements without line terminator.
    Technote 1649175 describes how to remove Rational Rhapsody generated Annotations and its consequence.

    Related Permanent Restrictions:
    <none>


    To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Backward Compatibility

      Backward Compatibility (BC) properties are provided to enable the generation of code that is consistent with older releases. BC properties listed under "Related Properties" section are ones introduced after the release of Rhapsody v8.0 and affect code generation. You see those properties are defined in the BC profile for a corresponding version (e.g. properties tagged with [8.0] are defined in CGCompatibilityPre80Cpp). BC profiles are automatically loaded when you migrate your model to a newer version. If you want to generate older code, you can either leave the BC profile in your current model, or explicitly override them within your model (thus permanently applied) and remove BC profiles no longer needed. Alternatively you can manually add them to your site.prp or factory.prp depending on the needs.

      For certain properties, their usage and the reason for addition were explained in "Migration to Rational Rhapsody 8.0 and later"


      Related Properties (searching for properties):
      CG::Class::GenerateDependencyToExternals [8.0]
      CG::Statechart::RootPrefixInStateAnnotations [8.0]
      CPP_CG::Statechart::AddAnnotationToAllTransitions [8.0]
      C_CG::Statechart::AddAnnotationToAllTransitions [8.0]
      CPP_CG::Statechart::AddDescriptionToActions [8.0]
      C_CG::Statechart::AddDescriptionToActions [8.0]
      CPP_CG::Statechart::SortAttributesByType [8.0]
      CG::Statechart::UsePre80StatechartCG [8.0]
      CG::Statechart::GenerateMisraCompliantEventProcessingCode [8.0]
      CPP_CG::Attribute::GenerateAttributeImplementationForInterface [8.0]
      CG::Class::ForceInDeclarationForNestedTemplate [8.0.3]
      CG::Dependency::UsePre80Dependencies [8.0.3]
      CG::Relation::InlineRelationForcesAnInclude [8.0.3]
      CG::Dependency::AutoGenAnnotationsForImplicitDependencies [8.0.4]
      CPP_CG::Operation::GenerateDescriptionForFlowchartActions [8.0.6]
      CPP_CG::Operation::GenerateDescriptionForFlowchartFlows [8.0.6]
      CG::Configuration::UsePre806PrologEpilogCG [8.0.6]
      CG::Relation::UsePre806AssociationCG [8.0.6]
      CG::Statechart::GenerateEnterAndExitOnStateContainingEnterExitPoint [8.0.6]
      CPP_CG::Configuration::UsePre81GlobalAttributeLocation [8.1]
      CPP_CG::Class::GenerateClassDescriptionInSpecification [8.1]
      CG::Configuration::SortAssociationEndsAndPartsTogether [8.1.3]
      CPP_CG::State::EncloseFlowchartActionDescriptonTemplate [8.1.3]


      Related Technotes:
      Technote 1631766 describes a compilation issue related to GenerateAttributeImplementationForInterface.
      Technote 1323652 describes considerations when upgrading a Rhapsody application with CM

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Execution Frameworks

      An execution framework provides the set of run-time services that provide a framework in which Rhapsody model can run. Rhapsody comes with various execution frameworks. Table 1 compares the capabilities of some of known C++ execution frameworks.


      OXF (Object Execution Framework)IDF (Interrupt-driven Framework)NoF (No-Framework)SXFC++ (Simplified C++ execution framework)
      ArchitectureDynamic ArchitectureDynamic or Static Architecturenot applicableStatic Architecture
      Memory ManagementStatic memory manager NoNoStatic memory manager (only BaseNumberOfInstances)
      MISRA C++ 2008 complianceNoYesnot applicableYes
      Animation/Tracing SupportYesNoNoNo
      Timers (time events)YesYes (Only Real Time mode)NoYes (Only Real Time mode)
      Container SupportContainers No containers (can be added) No containers (can be added) No containers (can be added)
      Supports statecharts Flat or reusable statecharts Flat statecharts NoFlat statecharts
      Multi-core SupportYesNoNoNo
      UML Ports SupportYesNoNoNo
      Binary SizeFull execution frameworkSmallNoneSmall
      Supported Messagingsynchronous/asynchronous synchronous/asynchronousSynchronous onlysynchronous/asynchronous
      Required OS?YesNoNoYes
      Build Framework on 64 bitYesConfigurableConfigurableYes only for MSVC
      Supported by IBM?YesNo (Only supported in C)NoYes
      Additional Note:An OXF-based model can be configured to support static memory allocation, but dynamic memory allocation will still be invoked within OXF unless the framework is customize and the model is carefully designed to support the static nature (e.g. always set multiplicity to none-asterisk)IDF is a light weight framework that can be used in place of the standard OXF in situations where there is no need for an operating system.NoF generates OXF-free code for your Classes, Operations, Attributes, Types etc, retaining minimal behavioural functionality.You can find a sample that uses the SXF framework in the Samples directory (under \CppSamples\SXF).


      For more information about frameworks, see the following topic at IBM Rational Rhapsody Knowledge Center documentation:

      Comparison for C execution frameworks is available at Tables 1. in the link below:

      Related Properties (searching for properties):
      <none>

      Related Technotes:
      Technote 1903700 describes how to extend OMEvent abstract class defined in the IBM Rational Rhapsody framework.
      Technote 1567357 describes considerations as to redistributing Object Execution Framework (OXF).
      Technote 1662617 describes how to start work with Rhapsody Interrupt-Driven Framework.
      Technote 1324332 describes how to use "No Framework" with Statechart implementation in Rational Rhapsody.
      Technote 1324333 describes how to use Rhapsody with No-Framework.
      Technote 1323613 describes what is a static architecture.
      Technote 1461528 describes how to utilize Static Memory Allocation in IBM Rational Rhapsody.

      Related White Paper:
      WP 7043154 describes how to implement a C/C++ "NoFramework" adaptor for IBM Rational Rhapsody.
      Title: How to start work with Rhapsody Interrupt-Driven Framework

      Related Permanent Restrictions:
      <none>


      To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.





    Change History Table (click to collapse or expand)


    Disclaimer

    THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENT, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENT OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS DOCUMENT IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REDOCUMENTS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM PRODUCTS OR SOFTWARE.

    Internal Use Only

    This technote contents need to be reviewed deeper before publishing externally as a White Paper.
    Until all contents to be checked and concluded, this technote remains Internal Use (Intranet) marked in Distribution field. Technical Review was performed by David Arbel from Rhapsody Development.

    RFE Coverage: Covered up to 1 December 2014 (RFE community)
    DCF Coverage: Covered all technotes sent via My Notification up to 2015/12/01.
    DFT Coverage: Covered all up to v8.1.3
    http://www-01.ibm.com/support/docview.wss?uid=swg27028569

    Advanced Topic Candidate:

    1. UML vs Rhapsody
    2. Creation of Property Perspective based on "Table of Content" (related: Technote #1410878).
    3. Forward development by disabling Annotation (1586784) and RoundTrip.
    4. List of stereotype affect CGs: friend/singleton
    5. Advance Indentation Technique using third party tools like BCPP, Uncrustify, UniversalIndentGUI.
    6. Advance Styling Technique using Emacs; Apply Google C++ standard (google-c-style.el).
    7. Implement SmartPointer using User-Defined container.
    8. How to substitute #ifdef usage using Inheritance and Abstract Pattern
      http://sourcemaking.com/design_patterns/abstract_factory/cpp/1
    9. Standard Operation
    10. MISRA-C++ enabled-code
    11. Framework collection (IDF, NoF, etc)
      http://www.ibm.com/support/docview.wss?uid=swg27043154&myns=swgrat&mynp=OCSS7P9W&mync=E
    12. Association Class
    13. IoT/Bluemix/IoT workbench

    Discovery:
    1. There are totally 11,275 properties have been categorized into 69 subjects/metaclasses according to individual function scope.

    API usage

    http://www.ibm.com/developerworks/wikis/download/attachments/121930141/whats_the_deal.pdf .

    [{"Product":{"code":"SS7P9W","label":"Rational Rhapsody"},"Business Unit":{"code":"BU005","label":"IoT"},"Component":"Documentation","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"7.6;7.6.0.1;7.6.1;7.6.1.1;7.6.1.2;7.6.1.3;7.6.1.4;8.0;8.0.1;8.0.2;8.0.3;8.0.4;8.0.5;8.0.6;8.1;8.1.1;8.1.2;8.1.3","Edition":""}]

    Document Information

    Modified date:
    17 June 2018

    UID

    swg27039283