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
Overview	Documentation Overview, Code Generation Architecture, Scope of this documentation
Comments	Comment Style (i.e. C vs C++), Comment for auto-generated functions, Requirements as comments, Description Template Usage, Header/Footer manipulation, General Techniques
General Formatting	LineLength, Tab/Space/Font, Brace Position, Indentation, Multi-Line, Advanced Code Formatting using WriterTemplate
Naming	File Name, Naming Convention, Prefix/Postfix adjustment
Scope	Visibility (Public, Protected or Private), Namespace
Class/File	General 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/Function	Const 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
Interface	Port
Relationship	User Container, Use template to define relationship, Container Usage, Relation Configuration
Initialization	Constructor Initialization, Initialization Technique, Array & Struct, Global/Static Variable
Dependency	Path delimiter, Header inclusion, #include ordering, #include style, Variant Handling, Implicit Dependency
Ordering/Sorting	General ordering technique, #include ordering, Struct and Union member, Constructor Initializer List
Optimization	Port Multicast, Code Size, Parallel Code Generation
Others	DBCS/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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
Scope of this documentation
- The purpose of this document is to introduce properties that are commonly known to customize code generation. There could be many more properties which are not covered in this technote but being available to use. All the available properties for RiC++ are defined in factoryC++.prp and factory.prp. To understand the basic of property usage in Rhapsody, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
  - Topic "Configuring Rational Rhapsody with properties"
  This document doesn't cover following topics:
  - Post Processor
  - CG SDK (Simplifier, Hooks, etc) (*1)
  - Rules Composer
  - Others
    - Code customization in C/Java/ADA language
    - Code generation semantic for behavioral diagrams (e.g. Statechart diagram)
    - Code customization related to animation and reverse engineering
  (*1) CG SDK - Code Generation Software Development Kit
  
  Using Post Processor, it is possible to manipulate the syntax or semantic of programming language but doing so is quite erroneous and should be avoided whenever possible. Also, altering auto-generated annotations would likely cause parser fail to understand your code correctly and thus you will see a parsing error during round-tripping. Therefore, Post Processor should be used only to format the look of code or adjust styling. Below are just examples so that you have an idea how Post Processor should be used.
  Using CG SDK, you can achieve a high level of code customization. CG SDK provides all the mechanism ("Simplify" Properties and Hooks) required to perform code customization at the transformation (simplification) level (see "Table of Contents > Overview > Code Generation Architecture" section). The overview of simplification process is illustrated in the following image.
  
  Overview of model simplification process
  
  Rhapsody provides you with sample projects that demonstrate how you should use "Simplify" properties and implement hooks and "simplify" interface in order to manipulate the code generation in various manners. Look in the <Rational Rhapsody installation path>\Samples\CustomCG Samples path. For example, see the sample projects provided in the CppSimplifiers or VisibilityGrouping subfolder. If you require more information on this topic, you should 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.
  
  Other Related Articles:
  - Topic "Writing Code Simplifiers"
  - Technote "How to use Rhapsody properties CG::Class::EnableWritingFilesWhenReady & CG::Configuration::DeleteTemporaryCGClassData"
  Back to "Table of Contents"

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)
    
    Rhapsody provides several properties related to comment generation (e.g. CPP_CG::Operation::ImplementationProlog). The following link takes you to the page explaining all related properties you should know about commenting through properties, and show a practical usage showing how those properties should be used to produce Doxygen-compatible comments as an example.
    
    Topic "Using code-based documentation systems"
  - Add comments through RoundTrip (click to collapse or expand)
    
    RoundTrip is a powerful feature Rhapsody provides. RoundTrip refers to an activity to reflect changes (e.g ordering, rename function, etc) you made to the source code back into model, and vice versa. When you make a change to source code, Rhapsody will analyze the source code and determine the type of change you made, and model it correctly. If the change was considered as something that is not appropriate to be modelled, for example a comment, Rhapsody will store that information as a textual information in Source Artifact. Source Artifact is normally created at the time of round-tripping and used for ordering and various manipulations. See also the Technote below for additional information.
    
    Technote 1640396 describes what is Source Artifact in IBM Rational Rhapsody.
    
    Once you understand how RoundTrip and Source Artifact work, you are ready to take advantage of it, and use it to place your comment at a desired location in the code by simply typing/copying the description text into the relevant section of the source code itself, and invoke round-tripping. The added text/comment will be preserved in Source Artifact, and thus remain in the code generation onward. Changing the comment description will result in updating the corresponding text in the Source Artifact.
    
    Steps to place your comments via RoundTrip:
    
    1. Add an operation to class. You will see below code generated in the cpp file.
    
    2. Enter your comment directly in the cpp file as below:
    
    3. Invoke round-tripping. As result, the added comment will be preserved in Source Artifact.
    
    4. Generate code. .
    5. You still see the comment in the generated code as below:
  - Add comments through the use of requirement element (click to collapse or expand)
    This approach is only applicable to operation elements. Using Rhapsody version 8.0 or higher, you can generate the requirement description as a comment. With this approach, you can control generation of comments in either specification or implementation file. Follow the steps below:
    
    1. Open a new model.
    2. On active Configuration, "Settings" tab, check "Include Requirements as Comments in Code".
    3. Create a new Class "C".
    4. Create a new operation "op" in "C".
    5. Create a new requirement "R".
    6. Create a Dependency between "op" and "R".
    7. Add ≪trace≫ stereotype to the dependency from step 6.
    
    8. Select either "specification" or "Implementation" at "Show In" field depending on where you want to see the requirement generated.
    9. Generate the code and check the effect.
    
    Note: CPP_CG::Requirement::DescriptionTemplate and CPP_CG::Requirement::DescriptionTemplateForImplementation can be used to specify the text of the comments that are generated in the specification or implementation files respectively.
  - Add comments through GenerateDescriptionInImplementation/DescriptionInImplementation properties (available since v8.0.3) (click to collapse or expand)
    In previous releases, description was generated only to specification file. Sometimes you want to be able to include a description of an operation in the implementation file (.c or cpp). The new GenerateDescriptionInImplementation property allows you to repeat the specification description from the header file (.h) in the implementation file or define the implementation description with the new DescriptionInImplementation property. For more information see Technote 1642601 and the following articles in IBM Rational Rhapsody Knowledge Center:
    
    Topic "Generating operation descriptions in implementation files"
  - Moving the comment inside the operation body using WriterTemplate (available since v8.0.6) (click to collapse or expand)
    See Example 3 in Technote 1670578.
  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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
Comment for auto-generated functions
- To satisfy your code analyzer's requirement, you may also want to ensure all auto-generated code to have proper comments. Unfortunately, there is no easy way to modify comments generated for auto-generated functions. However, you can consider below options:
  
  Option 1 - Convert auto-generated code to user-managed code (click to collapse or expand)
  
  1. Turn on CG::CGGeneral::GeneratedCodeInBrowser property.
  
  2. Run Code Generation.
  3. Confirm auto-generated functions (e.g. constructor/destructor) are visible in the Browser.
  4. Modify the function as you wish (e.g. add your comment) .
  
  Although this approach will allow you to have more control over commenting auto-generated code, the modified auto-generated operation become a user operation. Therefore, you have to manually maintain those user functions onward, rather than being managed by Rhapsody.
  
  Option 2 - Requirements generation into the auto-generated code (click to collapse or expand)
  
  This option is only available for the project with SafetyCriticalforC++Developers setting.
  
  See how comments are generated for auto-generated function below:
  
  Figure 1. a simple reactive class having a statechart in SafetyCriticalforC++Developers project.
  
  Figure 2. Generated implementation code (*.cpp) from the statechart above.
  
  For more information, refer to "Requirements generated into code " section in " What's new in IBM Rational Rhapsody 8.0 and Rhapsody Design Manager 4.0".
  
  Also read "Table of Contents > Comments > Comment Style" section for changing comment style for auto-generated code.
  
  Related References:
  " What's new in IBM Rational Rhapsody 8.0 and Rhapsody Design Manager 4.0"
  
  Related Properties (searching for properties):
  CG::CGGeneral::GeneratedCodeInBrowser
  CPP_CG::ModelElement::SimplifyAnnotations
  
  Related Technotes:
  <none>
  
  Related Permanent Restrictions:
  <none>
  
  To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
Requirements as comments
- To have a better traceability between requirements to code and vice verse, you can configure Rhapsody to include requirements as comments in the generated code. For more information, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
- Topic "Including requirements as comments in generated code"
- Topic "Including requirements as comments in statechart code"
- Topic "Including requirements as comments in auto-generated code"
- Apart from approaches mentioned in topics above, you can relate a requirement to a class by adding $Requirements keyword to DescriptionTemplate property. Not only class, but also possible to apply this method for other elements as long as the intended model element has DescriptionTemplate property as part of its property list.
  
  If you're using Rhapsody version 8.0 or higher, you have an option to generate requirements as comments for operations. For more information, see "Add comments through the use of requirement element" section in "Table of Contents > Comments > General Techniques".
  
  If you're using Rhapsody version 8.0.3 or higher, you can include $Requirement keyword as a part of a description and generate it as a comment for an operation in the implementation file (.c or cpp). For more information see Technote 1642601.
  
  Related Properties (searching for properties):
  CG::Configuration::IncludeRequirementsAsComments
  CPP_CG::<metaclass>::DescriptionTemplate
  
  Related Technotes:
  Technote 1624065 describes a problem when using macro in requirement comments.
  
  Related Permanent Restrictions:
  <none>
  
  To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
Description Template 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.
- 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.
  
  Property: CPP_CG::Class::DescriptionTemplate
  
  // class $(Name) // @brief $Description // @see $See // @warning $Warning
  
  Output A:
  
  //## class MyClass // class MyClass // @brief This is my test // A // B // C // @see REF. 123 // @warning <Write warning for this class>
  
  Property: CPP_CG::Operation::DescriptionTemplate
  
  //FULLNAME - $FullName //Argumenents // $Arguments
  
  Output B:
  - 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"
- 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.
  
  Back to "Table of Contents"
Header/Footer manipulation
The following link shows you a practical example to produce Doxygen-compatible comments using properties you see in Related Properties section.
- 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"
- 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.
  
  Back to "Table of Contents"

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>
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"

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>

Back to "Table of Contents"

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.

You can add it by setting the CPP_CG::Class::ImpIncludes property. This approach works, but there is a better visual way to do this. Add to your model, a package from another model that contains the classes that you want to include, for example, stdio.

Note: «external» stereotype indicating that you do not want to generate code for this class.

In a similar way, you can import a collection of header files from any external code through Reverse Engineering feature. Then, add them as a reference to your project.
- 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.

Back to "Table of Contents"

#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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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)
  
  The LineWrapLength property specifies the length of the code line generated during code generation. For example, if this property has the value 250, the generated code lines are wrapped to 250 characters. A value of 0 means that lines of code are not wrapped.
  
  Note that code for the following elements is not wrapped, regardless of this property setting:
  
  * User code such as statechart actions and operation bodies
  * The comments generated for element descriptions
  * Element annotations
  * Makefiles
  Default = 0
  
  Solution 2 - Implement word wrap feature using post-processor (click to collapse or expand)
  
  You would like to use a C++ script to modify the generated code as per your specific requirement, which is not possible using the GUI.
  For more information, see Technote 1587341.
  
  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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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>
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"

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.
  
  Back to "Table of Contents"

Class/File

General Class Structure

To learn basics of class structure, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

Topic "Class header file"
Topic "Class implementation file"
Topic "Creating classes and types"

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.

Back to "Table of Contents"

Include Guard

In C/C++ programming, all header files should have #define guards to avoid double inclusion. Rhapsody will automatically add include guard statement when you create class or package.

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

Related Technotes:

Technote 1627219 describes how to include user headers before #include guard automatically generated by Rhapsody.

Related Permanent Restrictions:
<none>

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

Back to "Table of Contents"

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)

Question:
I have a function in a package that takes an argument referencing a type defined in an external package. I do not want the #include of the external package to be generated in the code. I tried to set the CG::Argument::UsageType to None, but the #include statement still shows up.

Answer:
Disable CG::Class::CreateImplicitDependencies. The CreateImplicitDependencies property is a boolean value that prevents analysis of language types used by the class and its aggregates (as if all the types used by the class have their GenerateDeclarationDependency property set to Cleared).

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)

By default, Rational Rhapsody generates forward declarations to the classes owned by a package in the package specification file, and generates the includes in the package implementation file. The possible values are as follows:

* All - By default, Rational Rhapsody generates forward declarations to the classes owned by a package in the package specification file, and generates the includes in the package implementation file.
* ByUsage - Rational Rhapsody generates forward declarations and include files only for the classes to which the package has an explicit dependency (with the Usage stereotype).

example)

Value=All

MyPack.h	MyPack.cpp
//## auto_generated #include <oxf\oxf.h> //## auto_generated class A; //## auto_generated class B; //## auto_generated class C;	//## auto_generated #include "MyPack.h" //## auto_generated #include "A.h" //## auto_generated #include "B.h" //## auto_generated #include "C.h"

Value==ByUsage

MyPack.h	MyPack.cpp
//## auto_generated #include <oxf\oxf.h> //## dependency B class B;	//## auto_generated #include "MyPack.h" //## classInstance object_2 #include "object_2.h" //## dependency B #include "B.h"

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.

Back to "Table of Contents"

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)
  
  Desired Code:
  
  #ifdef Platform_16 // 16 bit code typedef unsigned long Integer32; #else // 32 bit code typedef unsigned int Integer32; #endif
  
  Possible Solution:
  1. Create a package named "OSType" and add a type called as "Int32Type" of kind = "Language".
  2. Copy the code above into Declaration tab.
- Manage platform independent attribute in the model (click to collapse or expand)
  
  This section explains how to define conditional class members with the same name, and still maintain it in a visible manner.
  
  Desired Code:
  
  class Foo { public: #if defined(_MSC_VER) && (_MSC_VER >= 1600) long long value; #else long value; #endif ・・・ };
  
  Possible Solution:
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.

Back to "Table of Contents"

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:

1. Add a variable to a package.

2. Make the variable global constant.

3. Override properties as you see in the image below.

NOTE: If you set VariableInitializationFile property to "Implementation", the assignment of initial value is done in CPP. It is only possible to initialize the attribute in specification when they are either global constant or if within a classes then the attribute should be marked as static const.

4. The code below will be generated in the package header.

Although it's not common usage, you might want to declare a global function and implement it in a different source code. As suggested by RT, adding a dependency to global function (with <<Usage>> stereotype applied) will result in generating a declaration in either H or CPP depending on the value specified in "Usage" field, and it works regardless where the dependency is placed either under SA or Class XYZ. See the example below:

1. Create a global function under a package.
2. Create Class A and Class B.

3. Add a <<usage>> dependency to those classes and set the target to global function.

Alternatively, you might draw dependencies from Source Artifact directly created under those classes, as it will likely be done by round-tripping. This way, you have more control over positioning the declaration statement within the code by moving the element up and down from Elements tab. In conclusion, the illustrated approach would be more preferable if you want to see those dependencies on the model, rather than hidden somewhere in Source Artifact.
- 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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

Nested Class

You can easily create a nested class in Rhapsody. Simply add classes to any existing class, the added class will appears nested in the generated code.

Related Properties (searching for properties):
<none>

Related Technotes:
<none>

Related Permanent Restrictions:
PM69534 : "INCORRECT CODE GENERATION WITH NESTED CLASSES WITH 7.6.1.2"

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

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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)
Read the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
- Topic "Generating only specification or implementation files"
2. Use Source Artifact (click to collapse or expand)
1. Add a new class.

2. Do either RoundTrip against class_0 or add SourceArtifacts (H + CPP).

3. Do code generation, and see that class_0.h and class_0.cpp are generated.
4. Delete class_0.cpp under SourceArtifacts.

5. Open Feature window of class_0.h under SourceArtifacts.
6. Change Element Type of class_0 to "Specification+Implementation" as shown below:

7. Press OK to save the change.
8. Do code generation, and see both header and implementation are generated into H file.

There are some articles available about Source Artifact, read the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
- Topic "SourceArtifacts in the browser"
- Topic "Manually adding SourceArtifacts"
- See also the Technote below for additional information.
  
  Technote 1640396 describes what is Source Artifact in IBM Rational Rhapsody.
3. Use Component file (click to collapse or expand)

This method has been commonly used before the enhancement was introduced to CPP_CG::File::Generate property. The attached image will illustrate what needs to be changed in your model to apply this method.

CG_Control_byCompFile.png

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.

Back to "Table of Contents"

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
- Example of inlined code (click to collapse or expand)
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:

The following's are given as extension to the scenario illustrated at "Example of inlined code" section, and allows you to inline cleanUpRelations() operation you see in the example. However, the steps involves a manual task of pulling cleanUpRelations() operation out of Rhapsody's control so to be managed by users, thus you can gain a better control over the operation at the expense of convenience.

1. Set CG::CGGeneral::GeneratedCodeInBrowser property at package level.
2. Run code generation, you will get the following model structure.

3. Open the Feature window of cleanUpRelations() operation.
4. Turn "Inline" flag on.

5. Generate code again, you will see the code something like below.

6. Now, turn off GeneratedCodeInBrowser property to get remaining unmodified operations back into Rhapsody control.
- 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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

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.

Back to "Table of Contents"

Constructor/Destructor

To get familiar with Constructor/Destructor creation and definition in Rhapsody, see IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:

Topic "Constructors and destructors"
Topic "Creating Constructor"
Topic "Defining constructor features"

To learn various ways to initialize data members in a class, see "Table of Contents > Initialization > Constructor Initialization" section.

Related Properties (searching for properties):
CPP_CG::Class::Destructor
CPP_CG::Class::GenerateDestructor
CG::Class::GenerateImplicitConstructors

Related Technotes:
Technote 1323474 describes how to disable code generation of the Default Constructor.
Technote 1649299 describes how to make Rhapsody generate class constructor parameters on multiple lines.

Related Permanent Restrictions:
<none>

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

Back to "Table of Contents"

Scope

Visibility (Public, Protected or Private)

Note:
- 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"
- 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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"

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.
  
  Back to "Table of Contents"
Call by Value vs Reference

1. Create a new operation named "Operation_0".
2. Open the Feature window from the operation.
3. Navigate to Arguments tab.
4. Do settings as below.

5. Run CG and check the generated code similar to below:

//## operation Operation_0(int,int,int) void Operation_0(int arg1_in, int*& arg2_out, int& arg3_inout); [

1. Create a new type called "myType". 2. Open the Feature window of "myType". 3. Navigate to Properties tab. 4. Change the following directions as you wish: CPP_CG::Type::In CPP_CG::Type::Out CPP_CG::Type::InOut 5. The specified setting will take place as you specify the type for arguments. Alternatively, you can customize the argument properties directly using the Argument Dialog - Properties.
- 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.
  - Code Pattern Field (available in v8.0.3 or higher) (click to collapse or expand)
  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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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>
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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>
  
  Back to "Table of Contents"
Operator Overloading
- You can overload operators for classes created in Rhapsody. For example, for a Stack class, you can overload the "+" operator to automatically perform a push() operation, and the "‑" operator to automatically perform a pop() operation. For more information, refers to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
  - Topic "Overloading Operators"
  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.
  
  Back to "Table of Contents"
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.
  - Code Pattern Field (available in v8.0.3 or higher) (click to collapse or expand)
  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.
  
  Back to "Table of Contents"
Return Type
- Since Rhapsody v8.0.3, you can use the Code pattern field to fine-tune the code that is generated for the return type of a specific operation. If you want to modify the code that is generated when a given class, type, or event is used as the return type of an operation anywhere in your model, you can set the value of the ReturnType property at the class, type, or event level. See below to understand how Code pattern field works.
  - Code Pattern Field (available in v8.0.3 or higher) (click to collapse or expand)
  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 return types"
  Related Properties (searching for properties): CPP_CG::Type::ReturnType Related Technotes: <none> Related Permanent Restrictions: <none> To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
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.
Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
Friend Function
- The CPP_CG::Class::Friend property specifies friends to be added to class declarations. For example, if you specify “int xyz()”, the following lines is generated in the public section of class declarations: friend int xyz(); Regarding Friend Class, see "Table of Contents > Class/File > Friend Class" section. Related Properties (searching for properties): CPP_CG::Class::Friend Related Technotes: <none> Related Permanent Restrictions: <none> To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
Template Function
- The template keyword is used to create generic functions and classes. The type of data operated upon by a generic function or class is specified as a parameter. The general form of a template function definition is shown here: template <class data-type> ret-type func-name(parameter list) { // body of function } For more advanced template usage, go to "Table of Contents > Class/File > Template Usage (instantiation and specialization)" section and check out TemplateCollection.zip sample. 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.
  
  Back to "Table of Contents"

Interface

Port

`Name`	`Specification`	`Type`	`Behavioral/Conjugated support`	`Interface(s)`	`Multiplicity`	`Samples/References`	`Multicast Support`	`Limitation/Consideration`
`Port`	`UML 2.0`	`Rapid`	`X/X`	`X`	`O`	`Relay (1), Multicast,HomeAlarmWithPorts`	`O`	`Multicast restriction by 1-hop.` `Multiplicity must be identical.`
	`n/a`	`Non-rapid`	`O/O`	`O`	`O`	`General, Behavioral, Multiplicity(1/2/3), Dynamic Link,`	`X`	`Multiplicity must be identical.` `IS_PORT macro do not work with Trigegered operations.`
`Flow Port`	`UML/SysML1.2`	`Atomic`	`X/X`	`X`	`X (not supported)`	`Use setX. See Port Multicast section, Multicast,`	`O`	`Depreciated since SysML 1.3 but continuously supported by Rhapsody.` `Can’t be bi-directional.`
	`SysML1.2`	`Non-atomic`	`X/O`	`X`	`X (not supported)`	`n/k`	`O`	`Available only in models with SysML profile.`
`Standard Port`	`SysML 1.2`	`n/a`	`O/O`	`O`	`O`	`Multicast, Multiplicity`	`O`	`Multicast restriction by 1-hop.` `Depreciated in Rhapsody v.8.0.x.` `Can be treated same with non-rapid port.`
`Proxy Port`	`SysML 1.3`	`n/a`	`O/O`	`O`	`O`	`n/k`	`X`	`Nested Ports is supported from v8.1.3.` `Multicast can not be supported due to the lack of enhancement.`
`Full Port`	`SysML 1.3`	`n/a`	`X/X`	`O`	`O`	`n/k`	`X`	`Nested Ports is supported from v8.1.3.` `Multicast can't be supported due to the lack of enhancement.`

*n/a = Not Applicable

	*n/k = Not Known

	

	

	Related Technotes:

	Technote 1678130 describes how to use RiCGEN_PORT_I and OUT_PORT macro in Rhapsody C.

	Technote 1676891 describes how to relay an event to multiple ports inside a composite class in Rhapsody C++ and C.

	Technote 1959735 describes how to use multicasting with SysML1.2 standard ports in Rhapsody.

	Technote 1959822 describes how to use multiplicities with SysML1.2 standard ports in Rhapsody.

	

	Related Permanent Restrictions:

	PK00067 : "Rhapsody - C portsError 'outbound' is not a member of 'portName'".

	

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

Back to "Table of Contents"

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.

* Default - Rational Rhapsody determines what category of properties to use * Scalar - Implement a to-one relation as a pointer to a single object * StaticArray - Implement a to-many relation as a static array of fixed size * Fixed - Implement a to-many relation whose multiplicity is a number greater than 1, as a container of fixed size * BoundedOrdered - Implement a to-many relation whose multiplicity is a number greater than 1 and whose "Ordered" check box is selected, as a list * BoundedUnordered - Implement a to-many relation whose multiplicity is a number greater than 1 and whose "Ordered" check box is not selected, as a collection * UnboundedOrdered - Implement a to-many relation with an upper limit of * and whose "Ordered" check box is selected, as a list * UnboundedUnordered - Implement a to-many relation with an upper limit of * and whose "Ordered" check box is not selected, as either a list or a collection, depending on the language * EmbeddedScalar - Implement a to-one composite relation as an embedded object (C and C++ only) * EmbeddedFixed - Implement a to-many composite relation as an array of embedded objects (C and C++ only) * User - This option instructs Rational Rhapsody to use the values you have provided for the properties under the "User" metaclass for the property subject that is relevant for you, for example OMContainers * Qualified (for relations only) - Implement a to-many qualified relation as a map or hashtable, depending on the language
- 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.

Back to "Table of Contents"



	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.

Back to "Table of Contents"



	Use template to define relationship

This section provides how you can implement relations using template with Association and Generalization as examples.
- Implement Association End using template (click to collapse or expand)
- Implement Generalization using template (click to collapse or expand)
For more information, see the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics:
- Topic "Using template classes as generalizations"
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.

Back to "Table of Contents"



	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.

Version 7.4 of Rhapsody includes an option for using a C++ framework that does not use templates. To use this option, define OM_NO_TEMPLATES_USAGE in the file Share\LangCpp\osconfig\<Adapter>\omosconfig.h, and rebuild the framework. To make this option possible, a number of classes have been modified, and a number of new classes have been added.

		

		Note: 

		When using the template-less framework, the framework memory manager cannot be used. To avoid compilation errors, you should define the following macro:

		

		#ifdef OM_NO_TEMPLATES_USAGE

		#define OM_NO_FRAMEWORK_MEMORY_MANAGER

		#endif // OM_NO_TEMPLATES_USAGE

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`	`Comment`	`Dialog setting`	`Example code`
`Scalar`	`Use 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`	`OMCollection`	`OMMap`
`Advantage`	`Efficient use of memory` `Order is specified` `Safe, will dynamically allocate more memory if needed`	`Fast access to a particular element` `Adding elements is fast, since memory pre-allocated` `Safe, will dynamically allocate more memory if needed`	`Lookup of an element using the key is fast` `Efficient use of memory` `Order is specified according to the value of the key` `Safe, will dynamically allocate more memory if needed`
`Disadvantage`	`Access to a particular element is slow` `Adding elements is slow since memory must be allocated` `Uses templates, which some compilers handle inefficiently`	`The order is not specified` `By default pre-allocates 20 pointers (Default can be changed)` `Uses templates, which some compilers handle inefficiently`	`Adding elements is slow since memory must be allocated and the map rebalanced` `Uses templates, which some compilers handle inefficiently`

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.

Back to "Table of Contents"

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:
  
  In the Initializer box you enter code if you want to initialize class attributes or super classes in the constructor initializer. To access the text editor, click the Ellipses button . For example, to initialize a class attribute called a to 5, type the following code: a(5) Note: In C++, this assignment is generated into the following code in the class implementation file to initialize the data member in the constructor initializer rather than in the constructor body: //------------------------------------------------------- // A.cpp //------------------------------------------------------- A::A() : a(5) { //#[operation A() //#] }; Note: You must initialize const data members in the constructor initializer rather than in the constructor body.
  
  Adding multiple attributes with initial value to a class, the related code generated from Rhapsody is with the following style: InitializerList::InitializerList() : m0(0), m1(1), m2(2) { ... } All the attributes definition are arranged in one line. You may want to initialize attributes in the following style instead: InitializerList::InitializerList() : m0(0), m1(1), m2(2) { .... } If you want to initialize attributes in multi-line, follow the steps below: 1. Add constructor to the class. 2. Open Feature window of InitializerList() constructor. 3. Enable CPP_CG::Operation::DisableAutoGeneratedInitializer to define your own default constructor. 4. Add attributes to initializer section. 5. Run CG, you will see a desired code generated.
  - 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.
  
  Back to "Table of Contents"
Initialization Technique
- This section introduces various initialization techniques based on scenarios:
  
  C++ provides a way of initializing class members that allows you to initialize member attributes at the time of creation. This is done through the use of either initialization list or direct assignment, and the below shows how they can be achieved in Rhapsody along with code output: 1. Initialization list (Static) Code Output: 2. Initialization list (Dynamic) Code Output: 3. Direct Assignment Code Output: To disable the default behavior of Rhapsody automatically assigning specified initial value to member attributes, you can simply turn off CG::Operation::UseDefaultAttributeValues property. By doing so, it will become your responsibility to ensure that those attributes having a initial value are initialized properly, however, you will have more control over the way how class attributes should be initialized to meet your specific requirement.
  
  1. Add a variable to a package. 2. Make the variable global constant. 3. Override properties as you see in the image below. NOTE: If you set CPP_CG::Attribute::VariableInitializationFile property to "Implementation", the assignment of initial value is done in CPP. It is only possible to initialize the attribute in specification when they are either global constant or if within a classes then the attribute should be marked as static const, the code below will be generated in the package header.
  
  Sometimes, you want to apply the same initialization value/call to all classes in a particular component or package, or individual classes or a set of related classes. CG::Class::AdditionalInitializationCode property will help to achieve the goal by allowing you to set the same initialization routine to a group of classes at once. There is also some information available in the help related to AdditionalInitializationCode property. For more information, refer to the IBM Rational Rhapsody Knowledge Center documentation for your installed Rhapsody version in the following topics: Topic "Cross-package initialization"
  
  Expected Code: //## type XYZ struct XYZ { int x; //## attribute x int y; //## attribute y int z; //## attribute z }; const XYZ ArrayOfStructure[3] = {{1,2,3}, {4,5,6}, {7,8,9}}; Solution:
  
  With the default setting, the association drawn between classes is realized using a pointer symbol (*) and initialized with NULL value in the constructor. But, may be, you want to initialize the association pointer with non-NULL value by constructor's initialization list. By turning on "Reference" modifier for the association, Initial Value filed becomes activated, and you can set an initial value. However, doing so will convert the pointer symbol to reference parameter (&) and remove the link initialization to NULL in class constructor. Actual: At this stage, the easiest solution for this problem is to add your initialization code in the initialize body of X's constructor, and set CG::Relation::SafeInitScalar property off to disable "itsY=Null".
  - 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.
  
  Back to "Table of Contents"
] 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"
- Related Properties (searching for properties): CPP_CG::Attribute::InitializationStyle CPP_CG::Attribute::VariableInitializationFile Related Technotes: Technote 1405221 describes how to initialize one-to-many association relation with named Objects Technote 1323741 describes how do you initialize a static array by assignment. Related Permanent Restrictions: <none> To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
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>
  
  Back to "Table of Contents"

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:
  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.
  
  Back to "Table of Contents"
#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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"

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:
  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.
  
  Back to "Table of Contents"
Code Size
- There are many things you can do to reduce the size of binaries produced. To know how Rhapsody can help you to achieve the goal, take a look at Technote 1424940 and Technote 1323628 describing various options that might interest you. Related Properties (searching for properties): CG::Class::ComplexityForInlining Related Technotes: Technote 1424940 describes how to reduce size of the generated code in Rational Rhapsody. Technote 1323628 describes how to optimize IBM Rational Rhapsody in C/C++ generated applications. Technote 1641771 describes how to reduce the complexity of generated code in Rational Rhapsody. Related Permanent Restrictions: <none> To see related enhancements, sign in developerWorks first then navigate to the detailed page at RFE Community.
  
  Back to "Table of Contents"
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.
  
  Back to "Table of Contents"

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.

Back to "Table of Contents"



	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.

Back to "Table of Contents"



	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.

Back to "Table of Contents"



	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)
  X(X&& x); //Move constructor X& operator=(X&& x); // move assignment operator
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.

Back to "Table of Contents"



	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.

Back to "Table of Contents"



	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)`
`Architecture`	`Dynamic Architecture`	`Dynamic or Static Architecture`	`not applicable`	`Static Architecture`
`Memory Management`	`Static memory manager`	`No`	`No`	`Static memory manager (only BaseNumberOfInstances)`
`MISRA C++ 2008 compliance`	`No`	`Yes`	`not applicable`	`Yes`
`Animation/Tracing Support`	`Yes`	`No`	`No`	`No`
`Timers (time events)`	`Yes`	`Yes (Only Real Time mode)`	`No`	`Yes (Only Real Time mode)`
`Container Support`	`Containers`	`No containers (can be added)`	`No containers (can be added)`	`No containers (can be added)`
`Supports statecharts`	`Flat or reusable statecharts`	`Flat statecharts`	`No`	`Flat statecharts`
`Multi-core Support`	`Yes`	`No`	`No`	`No`
`UML Ports Support`	`Yes`	`No`	`No`	`No`
`Binary Size`	`Full execution framework`	`Small`	`None`	`Small`
`Supported Messaging`	`synchronous/asynchronous`	`synchronous/asynchronous`	`Synchronous only`	`synchronous/asynchronous`
`Required OS?`	`Yes`	`No`	`No`	`Yes`
`Build Framework on 64 bit`	`Yes`	`Configurable`	`Configurable`	`Yes only for MSVC`
`Supported by IBM?`	`Yes`	`No (Only supported in C)`	`No`	`Yes`
`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:

Topic "Frameworks and operating systems"

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

Topic "What's new in IBM Rational Rhapsody 7.6.1 and Rhapsody Design Manager 3.0.1"

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.

Back to "Table of Contents"

Change History Table (click to collapse or expand)

`Change History`
`19/11/2015`	`Updated "Port" topic. Fixed broken links to RFE community. Added "Execution Frameworks" topic. Updated "Backward Compatibility" topic.`	`S.K`
`15/06/2015`	`Clarify ambiguity in Port table. Add samples to Port section.`	`S.K, C.S`
`26/05/2015`	`Fixed sign-in problem to RFE community.`	`S.K`
`20/01/2015`	`Updated with info for v8.1.1 and v8.1.2`	`S.K`
`22/07/2014`	`Updated "Port Multicast" topic. Added a new segment "Interface" Updated "Parallel Code Generation" topic. Updated with info for v8.1.`	`S.K`
`16/04/2014`	`Added "Unnamed Argument" topic Added "Constructor Initializer List" topic Added "Advanced Code Formatting" topic`	`S.K`
`15/04/2014`	`Broken links are fixed.`	`S.K`
`04/09/2013`	`Added "Backward Compatibility" topic.`	`S.K`
`16/07/2013`	`Updated with info for v8.0.3.`	`S.K`
`01/07/2013`	`Updated with info for v8.0.2 and lower.`	`S.K`

`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.

Related Information

Generating code from a Rational Rhapsody model

[{"Product":{"code":"SSB2MU","label":"IBM Engineering Systems Design Rhapsody"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"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":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Product Synonym

Rational Rhapsody

Was this topic helpful?

Document Information

Modified date:
27 May 2022

UID

swg27039283

Tips

Customize code generation using IBM Rational Rhapsody for C++

White Papers

Abstract

Content

Related Information

Product Synonym

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?