Sunday 29 March 2020

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.

Sunday 22 March 2020

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.

Friday 20 March 2020

Monday 16 March 2020

Rational Rhapsody Tip #74 - State Machine Diagrams in Rational Rhapsody (Intermediate)

This is my 5th in a series of videos on the different diagram types in UML and SysML, and focuses on state machines, a type of behavior diagram that can be created under classes, blocks and actors in IBM Rational Rhapsody. Rhapsody has long had a strong association with state machines, having grown from the origins of work done by Prof. David Harel at the Weizmann Institute of Technology and at I-Logix (which had a tool called Statemate also at the time). This resulted in the incorporation of executable syntax into the first version of Rhapsody in 1996, around the time that Harel statechart notation was subsumed into the UML. Having a common understanding and interest can be a useful way to explain things, so in this video I build a state machine model of the UK government's response plan to the COVID-19 virus outbreak from scratch and use this to cover basic syntax related to event triggered, guard and time-based transitions, as well as OR, parallel or orthogonal regions, and nested states.

Here's the transcript:

This is my 5th in a series of extended videos about diagrams in the UML and SysML graphical languages. In this I’m going to cover state machine diagrams and it’s a natural follow on from my previous videos about class diagrams and composite structure diagrams.

Whereas Composite Structure and Class Diagrams are types of structure diagram in UML, state machine diagrams are a type of behavior diagram, and there is a relationship between the two, in that classifiers shown on a structure diagram may have behavior that is described using a state machine. SysML inherits all its state machine syntax directly from UML without modification, hence state machine diagrams also apply to Blocks, a stereotyped class in SysML.

It probably doesn’t take a genius to know what type of behavior state machine diagrams show, however it’s worth reviewing what we mean by state-based behavior and some of the history here, not least because Rhapsody has had a part to play in it. If you google David Harel and Rhapsody then you’ll probably find this paper. If you google History and David Harel then you may find this. At the very least this paper will teach you that nothing is new and if you build something with strong foundations then it will last. It will also help us to understand why Rhapsody’s state machines are the way they are and how they might differ from other UML/SysML tools, as while they both had the same father, they have grown up with different pressures. Some things like the mapping to generate readable C++ code that executes on embedded targets is not part of the UML or SysML standard.

So let’s have a quick look at some of those fundamentals. In this example I’m going to model the emergency response of the UK government to COVID-19 as a Harel statechart. I'll use this to cover the syntax for triggered and guard-based transitions, OR, nested and orthogonal regions, and time events. The thing that I like about Harel-based statecharts is that the notation is that it’s a small language with clearly defined rules. The adage that don’t need something complex to describe something complex applies.

You need to draw a state machine for a classifier. I can’t right click a package and create one, rather it needs to be an element such as a class or block. Note that the term used by Rhapsody for the diagram is Statechart, rather than State Machine Diagram. I’m going to build the model completely from scratch and I’m building this example by reading a newspaper article written by the Independent newspaper on the 4 phases of UK governments response to the COVID-19 virus outbreak.

The first state in the Government response is called a Containment phase. In the Containment phase you rapidly identify anyone who has the virus and quickly get them to a specialist infectious disease unit where they can be quarantined to prevent the virus spreading. At the same time, you identify anybody they’ve been in contact with and isolate them.

The fundamental goal here is to stop the disease from spreading. Here we can see the basic syntax of an event-based transition. The event we react to is shown before the forward slash, and the action or actions performed as a result of taking the transition are shown after the slash. The action I’ve put here is actually assumed to be the invocation of an operation, hence I need to create the operation, under the class, if I want the state-machine to execute.

To do this I’ll just copy the text I typed and create a new element in the browser by pasting in a name that matches it. The statechart has the same scope as the class that owns it. This means that we can also create attributes for the class and use them in the action and guard fields of transitions. What I’ll do is to add an attribute to keep a track of the number of infections. I can then use this attribute in the action field of the transition, and I’ll get it to increment in value each time a new infection is detected.

The second phase of the Government’s response is called the Delay phase and starts when the virus has taken root in the UK and is freely spreading. This is where the government shifts to delaying the epidemic. The shift to the Delay phase occurs when the number of infections exceeds a particular threshold and we could show this will a guard-based transition. Firstly, I’ll create a constant to represent the threshold and set it to an arbitrary value for illustration purposes. The purpose of the delay phase is to reduce the number of people who become severely ill at the same time to prevent it from overwhelming the NHS - which does not have enough critical care beds for everyone who may need them.

A guard is a Boolean condition that evaluates to true or false and is shown in square brackets. In this case this is a null-triggered transition which has no event. This will be tested on entry to the owning state, hence it’s important that transition that changes the number of infections exits and re-enters here, as it will cause the number of infections to be tested each time the attribute changes. The delay strategy is designed to soften that peak of epidemic. When this transition occurs the government will postpone or cancel large events and it will close schools.

This allows me to illustrate a key aspect of Harel state machine notation, which is that and that states are persistent conditions of existence where the system reacts to certain events or stimulus, and actions are performed on transitions rather than in the states. Rhapsody has an Intellivisor feature that can be used to auto-populate a correct name by starting to type something and pressing the Ctrl plus Space key.

For a state machine like this where there is more than one state to be valid, I need to say which state the classifier will start in. I must do this using a default transition. State machines in Rhapsody are fully executable, so what I’m going to do is to drop a couple of panel widgets on to the diagram. One that will allow me to inject an event. What I’ll do is bind this to the identify infections event that is stimulating the state machine. The panel widgets here are related to the panel diagram which is licensed by the tools and utilities add-on currently. I’ll also add another another widget that will allow me to inspect values of attributes, and bind this to the number of infections attribute owned by the Government Response class. I’m then going to build and run the state machine, so I’ll get Rhapsody to create an executable with an instance of the class running inside it.

Rhapsody actually generates the C++ for this statemachine and then invokes the compiler to build and link it with something called the object execution framework. The object execution framework handles additional capabilities such as threading, timers, and the queues associated with asynchronous events sent between reactive classes.

Once you run something then you immediately spot issues. We can also see here that the number of infections attribute was not initialised and, if I look at the animated statechart, I can start to see what happens when I interact with it. For example, w’re not reacting to the identification of infections when in the Delay phase, because we did not put this event as an outgoing transition in the Delay state so let’s stop the execution and make some corrections to the model. Firstly, by initialising the number of infections to zero and then getting the Delay state to react to the same event and in the same way as the containment state.

This allows me to illustrate a key part of the syntax which is nested states. If I have two or more states that react to the same events in the same way then I can put them inside of a parent state and draw the common transitions from that. Note that if I exit and re-enter the parent state here, then the state machine will re-take the default transition and re-enter the Containment state. This is not something that I want to happen and therefore I need to make a further change to the model to correct this.

Conveniently, this allows me to illustrate another syntax called a reaction in state. A reaction in state is used where we want a classifier to react to an event, without exiting and re-entering. In Rhapsody this can be entered in the Feature’s dialog of the state. Once we’ve done this, we can toggle the display of it on the diagram by clicking the icon in the top-right of the states graphical element. Before building and running, I’m just going to create a sequence diagram with the classifier as a lifeline and also the system border. I’ll then choose Close all but this and run again.

An animated sequence diagram like this allows us to visualise a linear view of the state of the classifier over time and how it reacts to events. As we go over the threshold therefore we can see that the government response moves from the Containment to the Delay phase. Once in the delay state we cannot return. It’s what is essentially a dead state. However, it does give me an opportunity to demonstrate two further aspects of state machine syntax, parallel or orthogonal states, and time events.

We can draw a parallel or orthogonal state using an AND line, so I’ll firstly resize the owning state and then draw an AND line from the top line to the bottom. In that I’ll put a Monitoring state and then show that over a certain period of time, people will recover (peopleRecover). Notice that this is a time event. In UML the syntax for this would be the word after and then the brackets, whereas Rhapsody using the keyword tm. In the brackets is the time interval that you want to set the timer for in milliseconds.

I’m implemented the decrementing of the number of infections using an operation. While I could access the attribute directly on a transition, two benefits of an operation are that they can be reused and also that it will be visible on an animating sequence. Note that the action syntax I’m using here is the C++ syntax. Rhapsody also has a abstract action language syntax but the C++ syntax is much more widely known and hence I just use that. Let’s put the return transition in. Which occurs if the number of infections is less than or equal to the delay threshold. When writing guard-based transitions you need to make sure that they don’t overlap with incoming transitions.

I’ll also expand the two states to the third, more serious phase, which the UK government has called the Mitigate phase. This is the final phase of the government’s strategy and is effectively triggered once the disease is widespread and unable to be stopped or even slowed. At that stage, the emphasis will shift to saving as many lives as possible and maintaining public order and the continuation of public services. I’ll add an attribute called the mitigate threshold and set this to be an arbitrary value for the purposes of simulation, like the transition from the Containment to the Delay state, I’ll add a guard-based transition that will cause the response to transition into the Mitigate phase if the higher threshold value is exceeded.

It's at this stage that we would see some of the most extreme measures be taken by the government to try and keep the country going. Hospitals will cancel operations and in extreme cases doctors will be forced to ration care to those most likely to benefit. The British Army could be deployed onto the streets, and the government could enforce work from home to prevent movement of people.

When using operations as actions it’s often easier to enter them first in the browser, and then use Rhapsody’s Intellivisor feature to auto-populate. As well as speeding up model creation, this reduces the chance of typos. Note that I’m adding semi-colon here as this text is going to put directly into the C++ that is generated.

This gives us a much more complete model. We now have 3 clear phases of the government response modeled, together with guard, time and event-based transitions that are occurred. The state machine therefore starts to get a bit more interesting when we execute it. At this stage, let’s run the statechart again.

With the introduction of a time element we can now see a more continuous form of behavioral model in addition to the reactive behavior that comes from injecting events. We can see the impact of the class reacting to external events, and changing state as a result. We can also see the impact of time events in an orthogonal region causing guard based transitions to be taken in the main region.

This brings us to a 4th phase of the government response, which is called Research. The research phase is a wonderful example of an orthogonal region. It’s something that runs concurrently in parallel to the states that we’ve already identified. Again, I can draw another parallel region by adding an AND line. In this parallel or orthogonal region I might define a simple OR state machine with a Research state that has two nested states.

The research phase might be categorized by a period where we look for drugs followed by a period where we deploy the drugs. It may be that we cannot find a vaccine, however, deployment of drugs may reduce the severity and prevalence of infections, and therefore act to reduce the overall number of infections.

I’ll model this by adding a time event that acts to reduce the number of infected people. I’ll put a slightly smaller time interval and re-use the people recover operation that I created earlier. Before running, I’ll just add a button to stimulate the drugs found event. The easiest way to do this in Rhapsody is to copy and paste an existing button, as it’ll pick up the existing display options and bound element, which is then easy to change.

Let’s do a final run then, to see how the state machine behaves. The great thing about state machines when you execute them is that they come alive. Watching how a clock move is a lot different to viewing a static picture of one.

Of course, these different regions do have an influence on each other. If we can delay the spread of the virus for longer then this gives more opportunity to develop a cure or ways of lessening the impact on vulnerable people in society. There are of course other elements to consider, however this concludes the demonstration. In this we covered event, guard and time-based transitions, as well as or, parallel and nested states.

For me, the key thing about state machines is the succinct and intuitive nature of their syntax. and power of the notional to express quick powerful behavioural constructs that are quite commonly described. They also quickly come alive when you have the ability to run them and interact with them, hence are fundamentally designed for modeling reactive event based behaviour..

My name is Fraser Chadburn and I specialist in tool-based training and consulting in IBM products and, in particular, in setting up Rhapsody using domain-specific profiles. Using Java automation I can simplify and speed up modeling tasks so that users can focus on creative and fun systems and software engineering. If you do have any questions then feel free to contact me.

Saturday 14 March 2020

IET Coventry and Warwickshire Annual Dinner

Had a fantastic evening on Thursday at the IET Coventry and Warwickshire Annual Dinner, having been invited as a result of giving an MBSE talk last year.

The food was beautifully prepared by students from Stratford-upon-Avon college. and it was inspiring to listen to the talk by students from WMG Academy, in Coventry, talk about their experiences winning a Robot Race engineering competition.

Many thanks to the Institute of Engineering and Technology - Coventry and Warwickshire who have clearly done inspirational work in the area of STEM engagement, Derrick Willer especially!

Online Rational Rhapsody and IBM Jazz training - a reflection on the shift

Just wanted to emphasise that almost all my training's in Rhapsody last year were actually web-based and online, and mostly to clients outside of the UK. This was done by moving my training into Island Training's virtual training environment, a USA-based company that's been around since 1999 and is probably the biggest deliverer of Rational Jazz-based training to IBM customers worldwide.

This was a completely new experience for me, as a trainer who really likes to use a white board to get people collaborating. That said, I found that using their environment I am able to provide collaborative and interactive training with an even stronger tool-focus.

Key benefits seemed to be:

1. Flexibility. Anytime-anywhere.
- Removal of geographical boundaries (in one case I did half day training with participants in USA, China, and India).
- Half-day option: Ability to deliver half-day training so that participants can continue with normal work on the side.
- No need to book rooms or catering: People can connect to virtual machines from home (don't even need VPN access).
- Team sizes of 20 seemed manageable.

2. Extended topics:
- Training image doesn't just have Rhapsody, it has full Jazz install and DOORS 9.x, hence we can cover topics that involve the integrations that Rhapsody has, without requiring local teams to try and get their IT department to install things.
- I also increased focus of my material for existing Rhapsody user-base after engaging with more clients that have already deployed Rhapsody but are struggling with deeper tools knowledge.

3. Increased tool-focus.
- Rather than white-board, I found it easier on line to show my desktop with tool running and answer questions this way.

With regard to engaging my training services there are different options.

A) Engage with a local business partner (such as Island Training, if you're USA-based, or Nohua Solutions AB, in Scandinavia) who can then subcontract me, or
B) Engage directly.

Often the first options works well because different companies in different geographies will already have business and personal relationships with the client. I want to support this. I'm also open to new channels in new territories. I guess, in the world of COVID-19 there are benefits to working from home and companies who might benefit from on-line training in the next 6 months!