™

Chapter 4 - Adding State Information to the Simple ATM Example

In the previous section, you added a Test Scenario to the simple ATM protocol. The Test Scenario was captured on the ATM Test Test Sheet.

So far, the simple ATM protocol is very simple. The only operations are inserting a card and pressing the Cancel key. Further, there is no connection between the two operations; that is, one could repeatedly insert a card with no complaint from the ATM.

In this section, we will augment the design with a state machine that orders the Insert Card and Cancel operations so that a card may not be inserted before a previous card insertion (if any) is canceled.

Before starting the operations detailed below, ensure that you have loaded the design information captured and saved in the previous section.

State Machine for Simple ATM

The state machine required to support the first two operations is quite simple, as shown in Figure ???.

The state machine begins in the Init state. In this state there are two acceptable operations, Cancel and InsertCard. In the the Init state the Cancel operation is a no-op; that is, it is acceptable to issue, but leaves the state machine in the same state. The InsertCard operation on the other hand moves the state machine to the GotCard state. In the GotCard state the only acceptable operation (at this point) is the Cancel operation. This operation returns the state machine to the Init state.

The operations of the state machine are summarized in the following table. Any operations not specifically listed in the state machine description are forbidden.

We will be adding to this table as the state machine is further developed.

Maintaining State in ProtoCollum

The ATM model in this design needs to maintain information across the execution of various operations so we can remember whether or not the user's bank card has been inserted, which state the state machine is in currently, and so forth.

This information is initialized and updated by Tcl/Tk code attached to the corresponding processing entity or rule. In this particular case, the state of the ATM's state machine is initialized by the ATM PE. Transitions from one state to another are managed by the acceptCard and cancelOperation rules.

State information for an instance of a Processing Entity is kept in the State array. Each item of state information is kept in its own entry in this array. We will use the current_state entry to hold the name of the currently active state of the state machine.

The current_state entry needs to be initialized to the value "Init" when the ATM PE is first activated. When each state transition occurs, the value of the current_state entry will be updated to reflect the newly entered state.

Initialization code for a PE is entered on the PreCode tab of the Processing Entry Properties dialog box. This dialog box is activated by right-clicking on the PE in question while on the Design Sheet. Activate this dialog box for the ATM PE on the ATM Protocol sheet. (See The Simple ATM Example for step-by-step instructions on how to activate this dialog box if you have any difficulties.)

Once the dialog box is open, click on the PreCode tab. The dialog box should now appear as shown to the right. The statement already in the PreCode section is to initialize the system's message passing system for this PE. We will add our code following it.

Click in the text area and enter the code as shown in the dialog box to the right. The # character is used to start a comment line. As we add additional states to the state machine, we will document them here. The Tcl/Tk set statement is used to initialize the current_state entry in the State array to the value "Init".

Once the code is entered, click OK to register the change. Since we have already created a test scenario, the warning to the right will be shown. The changes we are making are appropriate so click Yes to acknowledge the warning and register the changes.

Now that we have a variable representing the current state of the ATM PE, we can check the value of that variable to enable or disable a rule.

In particular, we want the acceptCard rule of the ATM PE to be enabled when the state machine is in the Init state, but to be disabled when the state machine is in the GotCard state. We accomplish this by adding a Guard Expression to the acceptCard rule.

Click on the "Event Mode" button on the toolbar. The mouse cursor will change to to show that you are in Event Mode. Move the mouse pointer to the acceptCard rule beneath the ATM PE and position it over the orange bar between the Upper marker oval at the top of the rule and the event box receiving the cardInserted message. The mouse cursor will change to to show that an event may be added in this position. Left-click once. The sheet should now appear as shown to the right.

Since the acceptCard rule got bigger to accommodate the added event box, it now bumps into the cancelOperation rule lower on the ATM PE stem. We will fix this by moving the cancelOperation rule a bit lower.

Click on the "Select Mode" button on the toolbar. The mouse cursor will change back to to show that you are in Select Mode. Move the mouse pointer over the cancelOperation rule until the mouse cursor changes to , indicating that the rule may be moved. Using the left mouse button, drag the cancelOperation rule a bit lower on the ATM PE stem. When you release the left mouse button, the rule will snap to its new position. The sheet should now appear as shown to the right. (Note: The handles on the three rule marker ovals can be used to resize parts of the rule. The mouse cursor will show as when a resize operation is possible.)

Now that the new event has been added to the acceptCard rule, we have to add the corresponding guard expression to make the rule active only when the ATM PE is in the Init state.

In the next steps, we also cover an important documentation capability: the ability to display arbitrary text in an event box.

Right-click on the event box that was just added. The event properties dialog box will appear, as shown to the right. (Note: the exact event number and rule number that are shown for your design might be different from those shown here. These numbers depend on the order in which items are added to the design.)

An event box can have a description that is displayed in the box on the design sheet. Such a description can be very useful for documentation purposes in complex designs. The purpose of this event is to ensure that the ATM PE is in the Init state (and therefore ready for a card to be inserted). Click on the Description tab and enter a description as shown to the right.

The guard expression is entered using the GuardExpr tab. Click on that tab. The guard expression [cara::rcvd] that is already visible on this tab should be replaced with the $State(current_state) == "Init" expression. The default guard expression tests whether a message has arrived for the rule. This condition is taken care of by the second event box on the rule (that is, the one acting as the desitination of the cardInserted message). When you have entered the new guard expression, the dialog box should appear as shown at right.

When you have finished entering the rule's description and new guard expression, click on the OK button. The relevant part of the design sheet should now look as shown at right. Notice how the text you entered as the event's description is displayed in the event box. If necessary, move the cancelOperation rule lower on the ATM PE stem so it doesn't collide with the newly expanded acceptCard rule.

The previous steps added a guard expression to the acceptCard rule so it will not trigger unless the ATM PE is in the Init state.

Once the rule does trigger it is necessary to advance the state machine to the GotCard state. In the next steps, we will add an action event and Tcl/Tk code to accomplish this.

Use "Event Mode" to add an event to the Action section of the acceptCard rule. Remember that the Action section of a rule is between the Middle and Lower marker ovals and is colored green. After adding the event box , the relevant part of the design sheet should now look as shown at right.

Right-click on the newly added event box to activate the event properties dialog box. Click on the Description tab and enter a description for this event, as shown at right. (Remember that the exact event number shown in your design might differ from that shown here.)

After entering the event's description, click on the ActionCode tab. You will see the default action as shown on the right.

Since we are not sending a message from this action event, we will replace the default action code with the code necessary to update the current state of state machine. Replace the default cara::send code with set State(current_state) "GotCard", as shown at right. After you have entered the code, click on the OK button to register the change.

After you click the OK button, the relevant part of the design sheet should look as shown at right. Notice that the description of the action event is shown in its box. If necessary, move the cancelOperation rule lower on the ATM PE stem so it doesn't collide with the newly expanded acceptCard rule.

At this point, we have updated the acceptCard rule to 1. check whether it should be active (only if the ATM PE is in the Init state) and 2. change the state of the ATM PE from Init to GotCard once a cardInserted message is received.

We need to make corresponding changes to the cancelOperation rule so that it will work in concert with the acceptCard rule. These changes are somewhat simpler since the Cancel operation (represented by the keypressCancel message) is applicable in any state. We therefore do not need to add a guard expression to the cancelOperation rule.

We do need to add an action event to this rule, however, to reset the state machine to the Init state whenever a Cancel operation occurs. Recall from the state machine diagram above that Cancel was appropriate in either state, with the next state being Init.

Since you already have experience in adding events and changing their properties, we will summarize the steps for adding the required functionality to the cancelOperation rule in the following list. The process parallels that used above to augment the acceptCard rule.

1. Using "Event Mode", add an event box to the Action section of the cancelOperation rule.
2. Return to "Select Mode" and right-click on the newly-added event box to activate the event properties dialog box.
3. Click on the Description tab and enter an appropriate description (e.g., "Return to/Init State", where the "/" represents breaking the description into two lines).
4. Click on the ActionCode tab and replace the default action (cara::send) with set State(current_state) "Init".
5. Click on the OK button to register the changes.

At this point, the design sheet should look like Figure ??? (you may have to scroll the sheet somewhat to get the complete cancelOperation rule on screen). Save your work using the File>Save (or File>Save As...) menu item before we move on.

Using Flags on the Test Sheet

In the first part of this exercise, we made changes to the ATM PE to add a state machine. We also updated the acceptCard and cancelOperation rules to monitor the current state of the state machine and to update the current state as appropriate as the user performs certain operations.

We will now move to the Test sheet ATM Test to review how the design changes have affected the test scenario and to learn a mechanism to help observe PE functioning during a test scenario.

Click on the ATM Test tab to switch to the test sheet. It should appear as shown on the right. The lines moving to the lower left of the nodes and ending at action markers below the ATM PE instance ATM0 represent the execution of the Action event boxes that were added on the design sheet. (If you do not see the action markers, click the "Execute Events" button on the toolbar.)

The action marker indicates that an action event was triggered for the rule identified at the node above it. The action marker is red when the action event does not generate an outgoing message. If the action event did generate an outgoing message, the action marker would be instead.

In this case, the two action markers indicate the setting of the ATM PE instance ATM0 state machine's current state to GotCard and Init, respectively. We know this because that's what the code we entered on the design sheet was supposed to do. We can check that this is in fact what really happened by using ProtoCollum's Flag capability.

Using Flags to Display State Information

A Flag is used on a Test Sheet to display some portion of a PE Instance's state information. In particular, we would like to display the current_state entry from the ATM PE instance ATM0.

While on the ATM Test test sheet, click on the "Flag Mode" button on the toolbar. The mouse cursor will change to to show that you are in Flag Mode. Move the mouse pointer over the "+" sign between the ATM PE instance ATM0 box and the node labeled acceptCard. When the mouse pointer is in the correct position, the mouse cursor will change to to indicate that a flag may be added. Left-click and the flag dialog box as shown at right will appear.

We wish to display the current_state entry in this flag, so click on that entry in the right-hand side of the dialog box. It will move to the left-hand side of the dialog box, which will now appear as shown at right.

Click the OK button on the flag dialog box to register the change and the sheet will be updated to appear as shown to the right. The flag box shows the name of the displayed entry from the state information but no value since the test sheet has not been re-evaluated yet.

Click on the "Evaluate Events" button on the toolbar and the sheet will be updated as shown at right. The flag is now showing not only the name of the state information entry but also its value at that point in the test scenario, that is, after the ATM PE instance ATM0 has been initialized, but before any messages have been received.

While still in "Flag Mode", add two more flags displaying the value of the state entry current_state. Place the first of these at the "+" sign below the acceptCard node and above the cancelOperation node . Place the second of these at the "+" sign below the cancelOperation node . Click the "Evaluate Events" button button on the toolbar to refresh the sheet and it should appear as shown at right.

The text in the flag boxes may be too small to be read easily. This text can be made larger by means of the Flag Properties dialog box. Click on the "Select Mode" button on the toolbar. The mouse cursor will change back to to show that you are in Select Mode. Right-click on the first flag you added and the Flag Properties dialog box will appear, as shown at right.

The original size of the text in the flag box is 8 points. This can be changed to a larger size by changing the font entry from Helvetica -8 to Helvetica -12, as shown at right. After you have changed the entry, click OK to register the change. Change the font size of the other two flags similarly.

At this point, the test sheet should look like Figure ???. The value of the ATM PE instance ATM0 state entry current_state is displayed at each point in the Simple ATM test scenario.

Save your work using the File>Save (or File>Save As...) menu item before we move on.

Where to Go Next

???