IBM Rational Rose Realtime Extensibility Interface

Creating and using structured properties

The IBM® Rational Rose® RealTime extensions to basic scripting allow you to automate Rational Rose RealTime-specific functions, and in some cases perform functions that are not available through the Rational Rose RealTime user interface. This article explains how you can use the Rational Rose RealTime Extensibility Interface to add, remove, or modify any structured property. Note: IBM Rational Rose RealTime is a component of IBM® Rational® Technical Developer.

Share:

Introduction

The IBM® Rational Rose® RealTime Scripting language is an extended version of the IBM® Summit® Basic Script language. The Rational Rose RealTime extensions to basic scripting allow you to automate Rational Rose RealTime-specific functions, and in some cases perform functions that are not available through the Rational Rose RealTime user interface. This article explains how you can use the Rational Rose RealTime Extensibility Interface to add, remove, or modify any structured property.


Structured Properties in Rational Rose RealTime

Structured properties are text properties with the following format:

   [<section-name1> {section-default-value1}{section-default-value2}{...}
<field-name1>=<value1>
<field-name1>=<value2>
...]

You can see a typical example of a structured property in Listing 1 (a petal file) following.

Listing 1. A typical structured property
(object Attribute
tool "OT::CppExec"
name "PhysicalThreads"
value (value Event
	[MainThread
	Priority='DEFAULT_MAIN_PRIORITY'
	StackSize='20000'
	ImplementationClass='RTPeerController']
	[TimerThread
	Priority='DEFAULT_TIMER_PRIORITY'
	StackSize='20000'
	ImplementationClass='RTTimerController']
	[CapPhysicalThread1{ CapLogicalThread1 }
	StackSize='20000'
	Priority='101'
	ImplementationClass='RTPeerController']
))

In this example, there are three structured properties: MainThread, TimerThread, and CapPhysicalThread1. MainThread and TimerThreads are defaults and are provided by Rational Rose Realtime. CapPhysicalThread1 is a physical thread that you create. In the code snippet shown in Listing 1, MainThread, TimerThread, and CapPhysicalThread1 are the section names. Priority, StackSize, and ImplementationClass are the fields with their respective values. For the thread MainThread, the fields Priority, StackSize, and ImplementationClass have the values DEFAULT_MAIN_PRIORITY, 20000, and RTPeerController, respectively. The Priority field is used to decide the priority of the physical thread. StackSize determines the stack size of the physical thread at runtime, and the Implementation Class is the type of controller associated with the thread.

In the Rational Rose RealTime model, each thread has its own controller. Individual capsules will run in the context of the controller on the physical thread to which they are assigned. This can be RTPeerController, as shown, an RTCustomController if you adjust it, or an RTTimerController for the timing thread.

Declaring a structured property

You declare a structured property by declaring a variable of type RoseRT.StructuredProperty. In Listing 2, OT::CppExec is a structured property. The value of the property is set calling the function SetFieldValue. In example 1, SetFieldValue is used to associate CapLogicalThread1 (a logical thread) to the physical thread CapPhysicalThread.

Listing 2. Declaring a structured property
  Dim	theStructuredProperty As RoseRT.StructuredProperty
 Set theStructuredProperty =    
    theBuildComponent.GetToolProperties("OT::CppExec").GetFirst("PhysicalThreads")

theStructuredProperty.SetFieldValue "CapPhysicalThread" 
    "{ CapLogicalThread" & " }", "Priority", Priority

To get a handle to the C++ Executable tab of the Component Specification dialog box, you have to use the OT::CppExec property. For C Executable, you need to use the OT::CExec property. Listing 3 shows you sample code that you can use as a reference to get the handle to all the tabs of the Component Specification dialog box.

Listing 3. Code to pass a handle to different tabs
‘ Script to list all the structured properties associated with the
‘ Component Specification dialog box. 

  Set  TheToolNames  =  TheTxRxComponent.GetToolNames()
  For count = 1 To TheToolNames.count
	   RoseRTApp.writeerrorlog  TheToolNames.getat(count)
  Next count


Result obtained
/////////////////////////////////////////////////////////////////////////
OT::CExec 
OT::CExtLib
OT::CLib
C Generation
C Compilation
OT::CppExec
OT::CppExtLib
OT::CppLib
C++ Generation
C++ Compilation
CORBA
RTJava External Project
RTJava Project
/////////////////////////////////////////////////////////////////////////

Creating logical and physical threads through the Rational Rose RealTime Extensibility Interface

It is possible to associate one or more logical threads to a single physical thread. This is fairly easy to do through the User Interface (UI) in C models. In C++ models, you typically use an optional capsule role, and then specify the correct parameters in the frame.incarnate() call to create the capsule instance. Figure1 shows the Structure Diagram of the Top capsule that has two optional capsule roles: /Rec1:Reciever and /Sen1:Sender.

Figure 1. Structure Diagram with capsule and capsule roles
model window with frames

Figure 2 shows the State Diagram of the Top capsule and the action associated with the Initial transition. For complete information on the frame.incarnate() and its parameters, please refer to the Rational Rose RealTime Online Help.

Figure 2. State Diagram with capsule and transition
stacked Transition Specification window

Figure 3 shows how the different elements that appear in the UI get associated and used in the frame.incarnate() calls. The figure also shows, in detail, how a LogicalThread gets associated with a PhysicalThread. The biggest problem that you face is a way to automate the association of a LogicalThread to a PhysicalThread. You can easily accomplish this by using structured properties

Figure 3. UI elements in frame.incarnate() calls
windows with lines showing associations

All the physical threads that get used or created during the lifetime of a component appear in the Component Specification dialog box. In Figure 3, the logical thread CapLogicalThread1 is associated with the physical thread CapPhysicalThread1. You can create a component through the Rational Rose RealTime Extensibility Interface code shown in Listing 4, which adds a new component named TxRxComponent to the model.

Listing 4. Creating a component
  Dim theBuildComponent As RoseRT.Component
  Set theBuildComponent = theComponentPackage.AddComponent("TxRxComponent")

In order to create a physical thread in the TxRxComponent component, you first have to access the C++ Executable tab through the Rational Rose RealTime Extensibility Interface. You can easily do this by performing the following steps.

  1. Declare a structured property by declaring a variable of type RoseRT.StructuredProperty.
  2. To access the C++ Executable tab of a component (in the Component Specification dialog box), invoke theBuildComponent.GetToolProperties("OT::CppExec"), as shown in Listing 5.
    Listing 5. Accessing the C++ Executable tab
    	Dim	theStructuredProperty As RoseRT.StructuredProperty
     Set theStructuredProperty = 
         theBuildComponent.GetToolProperties("OT::CppExec").GetFirst("PhysicalThreads")

    Figure 4 shows that it is necessary to get access to the C++ Executable tab because it contains the physical thread information.
    Figure 4. Physical thread information in the tab
    stacked Edit Physical Thread window
  3. In order to set the physical thread priority value (in this example, 5), declare a variable as shown in Listing 5 (Priority = "5"). The code in Listing 5 shows that the name of the physical thread is CapPhysicalThread1, and the name of the logical thread is CapLogicalThread1. It is important to notice the braces "{" and "}" within which the logical thread is included. This ensures that the logical thread is associated to the physical thread.
  4. A similar approach is used to set the stack size and the controller, respectively.
    Listing 6. Setting priority, stack size, and controller values
    	Dim	Priority As String
    	Priority = "5"
    
     theStructuredProperty.SetFieldValue "CapPhysicalThread1" 
         & "{  CapLogicalThread1" & " }", "Priority", Priority
     theStructuredProperty.SetFieldValue "CapPhysicalThread1" 
         & "{ CapLogicalThread1" & " }", "StackSize","20000" 
     theStructuredProperty.SetFieldValue "CapPhysicalThread1" 
         & "{ CapLogicalThread1" & "}","ImplementationClass","RTPeerController"

Setting the target configuration of a component through structured properties.

One of the important things you may want to do during the automation of creating and running a model through the Rational Rose RealTime Extensibility Interface is to be able to select or set the Target Configuration of a component. You can use structured properties under such circumstances. The code snippet in Listing 7 shows how you can accomplish this.

Listing 7. Selecting the Target Configuration
  Dim theStructuredProperty1 As RoseRT.StructuredProperty
 Set theStructuredProperty1 = 
   theBuildComponent.GetToolProperties("C++ Compilation").GetFirst("TargetConfiguration")
 theStructuredProperty1.SetFieldValue "event_ui","caption",  "Select..."
 theStructuredProperty1.SetFieldValue "event_ui","description",
     "NT40T.x86-VisualC++-6.0"

In this example, in order to set the target configuration, you need to get a handle to the C++ Compilation tab of the component. To do this, invoke the theBuildComponent.GetToolProperties("C++ Compilation") call. theBuildComponent is the component, and GetToolProperties gets the handle to the C++ Compilation tab. Once the handle is obtained, you can easily set the target value (in this example, to "NT40T.x86-VisualC++-6.0") by using the SetFieldValue function. You can find the entire existing target configurations list in the C++ Compilation tab of the Component Specification dialog box for a component.


Setting the top capsule of a component through structured properties

Listing 8 shows you how to set the top capsule of a component. you need to get a handle to the C++ Executable tab of the component using theBuildComponent.GetToolProperties("OT::CppExec"). Once the handle is obtained, you can easily set the top capsule of the component to Top using the SetFieldValue function.

Listing 8. Setting the top capsule
  Set TheTopCapsuleStructuredProperty = 
       TheTxRxComponent.GetToolProperties("OT::CppExec").GetFirst("TopCapsule")
 
  TheTopCapsuleStructuredProperty.SetFieldValue "event_ui", "caption", "Select..."
  TheTopCapsuleStructuredProperty.SetFieldValue 
     "event_ui","description", TheTopCapsule.Name
  TheTopCapsuleStructuredProperty.SetFieldValue "", "", TheTopCapsule.GetQualifiedName()

Automating Rational Rose RealTime functionality with structured properties

This article has shown you how to use structured properties to automate Rational Rose RealTime functionality. Using the Rational Rose Realtime Extensibility Interface, you can add, remove, or modify any structured property. You can create logical and physical threads, and associate them. You can also set the target configuration and top capsule of a component.


Download

DescriptionNameSize
Supporting script for this articlePublisherSubscriber.zip6KB

Resources

Learn

Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=259624
ArticleTitle=IBM Rational Rose Realtime Extensibility Interface
publish-date=10092007