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.

Back to top

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.

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

                
  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.

                		
‘ 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
/////////////////////////////////////////////////////////////////////////

Back to top

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

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.

                
  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
   
   
   
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"

   
   

Back to top

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.

                
  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.

Back to top

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.

                
  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() 

Back to top

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.

Back to top

Download

Information about download methods

Resources

Learn

• Visit the IBM Rational Rose Technical Developer site for technical developer content and a variety of resources.
  
  
• Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

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®.
  
  
• Download the trial version of IBM Rational Rose Technical Developer V7.0.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  
• Real-time and Embedded Development forum: Ask questions about Rational Rose Realtime.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Structured Properties in Rational Rose RealTime
• Creating logical and physical threads through the Rational Rose RealTime Extensibility Interface
• Setting the target configuration of a component through structured properties.
• Setting the top capsule of a component through structured properties
• Automating Rational Rose RealTime functionality with structured properties
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers