IBM Rhapsody Tip #78 - Keeping user code consistent using Refactor: Rename

This short (silent) tips and tricks video takes a quick look at the Refactor: Rename dialog, available in IBM Rational Rhapsody when you right-click elements generated into code like types and classes. The key thing is that Refactor: Rename does more than just update references; it's a form of search and replace dialog and will do an update inside user code sections as well. Using the dialog you can review both before and after the rename. This helps you keep user code sections consistent when refactoring names of elements such as classes, operations, types and attributes.

Rhapsody 9.0 usability enhancements in the Transition features window

While doing the last video, here's a few things I noticed in the Rhapsody 9.0 release related to usability enhancements (the IBM Engineering Systems Design Rhapsody covers both systems and software engineering).

Firstly, the Guard edit frame on the Transition features window is bigger:

This is 8.4:

This is 9.0:

This is simple, but useful (I don't know about you but I often put a return in the guard so that it shows on a different line in the Statechart).

Secondly, the trigger selection now incorporates an active search capability.

This is 8.4:

This is 9.0:

This new pick-list capability is also present in other dialog's, i.e. it's been working its way through the Rhapsody UI for a releases now.

There's further information on the 9.0 release here.

This bit comes under the "Further enhancements to Combo boxes for model selection: active search on all elements selected" bullet point.

It's nice to see that usability features continue to be thought about, even in the old areas of the UI.

IBM Rhapsody Tip #77 - How to animate user-defined types in sequence diagrams (serialization)

With thousands of properties to explore IBM Rational Rhapsody is a powerful and configurable tool for both systems and software engineering. This short silent tips and tricks video comes at subscriber request!

In the video I use IBM Engineering Systems Design Rhapsody 9.0 but the same works for (most) earlier versions.

Here's the transcript:

This silent video covers how to get Rhapsody to show the value of user-defined types in an animated sequence diagram.Let's first have a look at the model. It's a C++ one I created that sends a couple of argument-carrying events to control a traffic light sequence. These events have arguments typed by an enum type and a struct type.

By default, when we animate these in a sequence diagram then raw, rather than type-aware values are shown. Fortunately, this is can be fixed. Let's look at the easy way first. On the properties for the Type we can set the property CPP_CG::Type::GenerateSerializationFunctions.

With this property set, Rhapsody will automatically generate the magic code needed to show meaningful text values when animating. Serialize is just a fancy way of saying 'convert this type to text'. Unserialize is the opposite, i.e. 'convert text (a char *) to a type value'. An unserialize function is used when you type text into the Generate Event dialog.

With the GenerateSerializationFunctions property set to SerializationAndUnserialization, Rhapsody automatically generates global serialize and unserialize functions into the .h/.cpp files for the application. Let's have a peek! Here is the auto-generated serialize function.

This is an auto-generated unserialize function.












Note the function's signatures. We need to match these when creating our own. Any user-defined functions would need to take the same argument and return types.

Here are some user-defined serialize/unserialize functions. They are global functions, i.e. contained by a package.

It's important that animation is turned off.

In this user-defined serialization function, I'm converting the enum type to a char * of Y(es), N(o), F(lash), or E(rror). My user-defined unserialization function does the opposite, i.e. converts a char * to the enum type.

We can tell Rhapsody to use these with the properties CPP_CG::Type::AnimSerializeOperation and CPP_CG::Type::AnimUnserializeOperation. We also need to turn off the auto-generation of serialization functions.

When we rebuild and run we can now see the user-defined serialization in play on the sequence diagram.

The user-defined unserialization is also in play!











In summary, you can easily get Rhapsody to auto-generate serialize and unserialize functions for types by setting the GenerateSerializationFunctions property, or (less easily) you can also create your own serialize/unserialize functions for animation, and tell Rhapsody to use them via properties. Just make sure the arguments and return values match and be careful about releasing memory ;-)

Useful cookbook of different code generation properties for Rhapsody in C++

Rhapsody's usage for generation of C++ for embedded real-time software targets is over 20 years old now. Of course, both it and language have moved on. There's an old IBM tech specialist adage that if Rhapsody doesn't do what you want out-of-the-box then there's probably a property you can set! Of course, find the right property can be a challenge (there are even properties that work that are not in the factory prp's related to backwards compatibility). For those doing code generation with IBM Rhapsody in C++ I thought I'd share a link. This IBM support white paper provides an accumulation of information related to questions that IBM support have had, and hence provides a useful reference of ideas and inspiration:
https://www.ibm.com/support/pages/customize-code-generation-using-ibm-rational-rhapsody-c

Rational Rhapsody Tip #76 - Using Visual Studio source-code debugger with Rhapsody (Advanced)

This 7' 35" Rhapsody advanced tips video came from some recent work helping a client migrate a project created with a really old iLogix Rhapsody version (5.02) to a later Rhapsody version (8.3.1). Because the framework has changed quite bit, it proved useful to be able to step-through the executing framework code at source-level to get a real handle on what was happening. Many thanks to Hartmut W at BTC Embedded Systems AG in Germany who produce and support the Rhapsody TestConductor add-on. He provided some of the advanced tips here (they are experts in formal testing of code afterall ;-). I particularly like the trick to recompile the framework with USE_PDB=TRUE, and setting programmatic breakpoints so that you can add them directly in Rhapsody. Hope it helps someone!

Here's a transcript:

This silent video covers 3 tips on source-code level debugging a model-driven Rhapsody application with the Visual Studio IDE.

Many thanks to Hartmut W @ BTC (maker of Rhp TestConductor add-on) for a couple of advanced tips.

This model has a configuration with animation enabled. We can generate and build the code from Rhapsody (model-driven). I've modified Rhapsody 8.4's MSVC environment to use the Visual Studio 2019 compiler here but these tips apply equally to earlier versions. This results in an exe. With animation enabled, it talks back to Rhapsody via a port so that you can interact with it, e.g., in a panel or animated statechart. This is model-level debugging and can help correct "the bigger picture". Often, however, we also want to step through and debug at code-level. Well, this is surprising easy to do with Visual Studio ;-)

Suppose, for example, we want to set a code-level break point in this transition? Firstly, we open up the Visual Studio IDE. Choose to open a project or solution, and browse to select the executable (.exe) that Rhapsody generated. Now, open up the source file, e.g., .cpp, that you want to step through in Visual Studio. This is the folder where the source code is generated by Rhapsody for this configuration. We can now locate where we want to set the breakpoint and set a breakpoint in the code (e.g. F9).

Now, when we run the .exe from Visual Studio, it will break when it gets to this line. Voilà !! We can now debug at code level.

Oh dear, we've stepped into a Framework (OxF) class here. Time for the second tip!

The application object files are linked with a library that contains base classes for many elements such as statecharts, events and threads. This is known as the OxF (Object eXecution Framwork). The OxF model/code/libraries are in the installation OMROOT/Share folder. To step through OxF code we need to recompile it with a change to one of the switches. Locate the config's CPP_CG::MSVC::buildFrameworkCommand property and change USE_PDB=FALSE to USE_PDB=TRUE. Choose Code > Build Framework to rebuild the OxF libraries using the active configuration's settings. This may take a couple of minutes.

Let's rebuild and link the application now. We can now debug again using the new PDB info available for the OxF. We're now able to step into the source code that is part of the OxF framework. e.g. OMReactive is the base class for classifiers that have statecharts and OMThread is the base class that iterates over the event queue. We can also set breakpoints in the Framework code (if we want).

Time for the final tip! With Visual Studio Professional we can also set breakpoints programmatically in Rhapsody. To programmatically add a breakpoint, we first add crtdbg.h to the config's include or additional sources path. We can now add a _CrtDbgBreak(); directly into code in the model.

Optionally, if we run from Rhapsody then we could Attach to Process... in Visual Studio. However, I first want to remove all non-programmatic breakpoints. Visual Studio will break itself when it gets to the _CrtDbgBreak(); in the code. Ta-dah! ;-)

That's it then, 3 tips for source-level debugging Rhapsody applications using Visual Studio:
1. Open .exe/source files and run from VS
2. Recompile OXF with USE_PDB=TRUE to code-level debug framework (optional)
3. Using programmatic breakpoints by including crtdbg.h and using _CrtDbgBreak(); (requires VS Pro)

Rational Rhapsody Tip #75 - Installing IBM Rhapsody 9.0 with Cygwin C/C++ (Intermediate)

In this 12'32" min video I show how I normally install IBM Rhapsody for my software and systems training. In 9.0 IBM Rational Rhapsody was renamed IBM Engineering Systems Design Rhapsody. I've included the steps for downloading and installing the minimal gcc compiler and GNU make tools (using Cygwin's setup-x86_64.exe). I suggest to install Developer which also installs Designer for Systems Engineers and Architect for Systems Engineers Edition shortcuts but not Architect for Software Engineers.

At the end I also show how to verify that the compiler environment is installed and working by creating running application (which highlights how Rhapsody now builds the framework libraries automatically if they don't exist, as pre-compiled library files are no longer shipped). I also show the use of the TELELOGIC_LICENSE_FILE system environment variable to configure license being used. One thing to note: Unless you have admin privileges on your machine and are a power user, if you're upgrading I generally recommend to uninstall previous Rhapsody first (otherwise the uninstall of earlier version may affect the registration of the COM component used for add-ins). It's possible fix an install if this happens, but this is not something most users will realize has happened.

Observations from installing Rhapsody 9.0 for first time

As well as the closing of all bars, restaurants, cafes and (unfortunately) my swimming pool, the 20 Mar 2020 marked the release of Rhapsody 9.0. Here’s a few notes on things that I noticed when first installing (a good way of exercising social isolation since my partner really doesn’t care for conversations about it 😉).

New Systems Engineering Design pre-fixed name

As well as being very long, you’ll probably notice that the name is different.

The Rhapsody name is kept but the Rational prefix is dropped (IBM stopped organising people under this brand a few years ago), replaced instead with the rather long Engineering Systems Design pre-fix. Of course, ‘Systems’ is a heavily overloaded term in IBM, hence the Engineering bit on the front. This is all aligned with the Jazz platform renaming in 7.0 (Engineering Requirements is now the pre-fix for DOORS® Next). At the very least this will help with educating people in IBM which - to be fair - has it's own heritage to deal with.

Installation wizard is different

The name changes permeate through to the install, of course.

Under the hood the development team have also upgraded their own dev development environment, so you’ll notice that the Microsoft Visual C++ 2017 re-distributables are installed as a pre-requisite.

Install defaults to all users

The install is actually very different. The install now defaults to the All Users option which it most most IT departments want anyway (previously, it defaulted to install for single user with the Share folder going under C:/Users//).

This means that a proportion of the install will still go into the C:\ProgramData\IBM\... folder but the executable components will go into C:\Program Files\IBM\... (for 64 bit).

Don’t forgot that ProgramData folder is hidden by default and hence on new machines you may need to show hidden folders to find it).

New MinGW adaptor

When you install as well as noticing that the Wizard is a bit different, Rhapsody 9.0 has a new MinGW adaptor (for both 32 and 64 bit applications).

‘Min’ in MinGW stands for minimal and hence is considered a lighter weight alternative to the use of Cygwin (which can be difficult to pick the right bits from). Mingw-w64 is a port of the GNU Compiler Collection (GCC) compiler chain for windows. I've not tried it yet but will probably give feedback once I have.

MinGW-w64 v.6.3 and 8.1.0 are the supported versions, I believe. MinGW is supported with Eclipse Integrations. For Simulink Integration, IBM is suggested to use the MinGW version supported by the installed MATLAB version.

New Share and UserShare folders structure

To align with some IT department requirements, the Rhapsody deployment (install) structure has undergone significant re-alignment in v9.0.

AppLocker is a Microsoft administration component that restricts programs users can execute based on the program's path. For example, with default rules users are not allowed to execute anything outside of program files folders, which Rhapsody previously allowed because the Share folder contained framework libraries and profiles/plugins and was not under the Program Files.

Significantly, the Share folder is no longer in ProgramData. There is instead a UserShare folder the location of which can be changed in the install wizard, but which would default to C:\ProgramData\IBM\Rhapsody\9.0x64\UserShare\ for an All User install:

With an all user install the rhapsody.ini file is still in this C:\ProgramData\IBM\... area of the install, which the user needs to make sure is given read/write permissions (as Rhapsody will read/write to this file and store settings in).

The UserShare folder does not contain the shipped Profiles, however, nor does it contain the pre-compiled framework libraries (more about this coming up).

Framework libraries no longer shipped so will be compiled when first used

The framework libraries (e.g. for the Object eXecution Framework or OxF) are a set of libraries that provide common capabilities used when you build state-machines, animate models, and make use of event-queues and the like. Previously, for some of the adaptors, a compiled version of the libraries was shipped. This is no longer the case.

As such, first time you build something with v9.0 then it will try to compile the framework library (i.e. automatically execute the Code > Build Framework operation).

This can take a while, and is initiated by default, and hence might confuse some users as to why there model is taking a long time to build. It does mean that the library you're linking with will be built with the same compiler version and settings are your application though (which at least gets rid of the annoying linker errors you may have seen with animation libraries and Cygwin).

Note the location of the framework libraries built on demand is, by default: C:/ProgramData/IBM/Rhapsody/9.0x86/UserShare.

Share folder (and Profiles) are now under C:\Program Files\IBM\...

Assuming a 64 bit install the previous Share folder (at least most of it) is now moved under C:\Program Files\IBM\....

Profiles do contain executable libraries and plugins and Windows wants these to be protected and not in a read-write section.

I was re-assured by the fact that the profiles and plugins that I have written did seem work if I put them in the Profiles folder, but it does mean that you will need admin rights to do this:

Shortcuts now have different names

Finally, you may notice that the shortcuts have full-names now.  Gone are the Folders in the start menu (which worked really badly with Windows 10 and caused a bit of confusion if you want to give users the choice of Developer or Architect for Systems with a single install).

The above were the shortcuts I get with a Developer installation of C and C++. There's no Rhapsody 9.0 Architect for Software Engineers shortcut but there is an Architect for Systems shortcut. Interestingly, the Architect for Software Engineers shortcut is now only added if that's the only choice in the Install Wizard.

More to come, but I thought I'd post these initial comments.