Animation in Rhapsody Developer for Ada

Enabling Animation

Animation is enabled by setting the Instrumentation Mode in the Configuration to “Animation”.

Figure 232 :Enabling Animation in the Configuration.

Warning :

If you come back to none animation in Instrumentation Mode, after having generating code, you may have some troubles when compiling the project, because some files are generated in animation mode and not in release mode. To avoid this, you may delete generated files before doing a code generation in none animated mode.

After animation has been enabled, the “Initialize” procedure for any instance to be animated needs be called.This will register the instance with the animation framework.

Animation can be disabled for individual packages, classes, operations, and attributes by setting the corresponding property to “False”.

For attributes, arguments, and events that are not standard Ada types, the address of the element will be used for animation.The user can enable the animation of the value by defining an Add_Attribute operation on his class for his particular type.Then, by setting the animation property to “Force”, the value of the type will be used instead.For events of user-defined types, it is also necessary to define a Get_Attribute operation as well.

Animation of a user defined type

In order to animate attributes or arguments, animation instrumentation uses Serialize/Unserialize operations in order to pass values to Rhapsody. Predefined operations are used to animate predefined types (Integer, Float, Character).

If user defines its own types, then specific operations must used. Two methods can be used to define these operations:

• creating manually new operations inside the model
• setup the user type properties to generate automatically the new operations

Creating manually Serialize/Unserialize operations

User needs to add some new functions and update some properties manually, in order to support those new types.

After having defined this type, two new operations (called for example Add_Attribute() and Get_Attribute()) must be declared in the type’s package. Operations’ signature and implementation are described further on. Some properties must be set on those 2 new operations :

The property CG:Operation:Animate must be unchecked.

The property Ada_CG:Operation:IsAnimationHelper must be checked

Some properties must be updated on the type :

Ada_CG:Type:AnimSerializeOperation must be set to : <type_package>.Add_Attribute

Ada_CG:Type:AnimUnserializeOperation must be set to : <type_package>.Get_Attribute

If a class has an attribute of this user type, then the attribute’s property CG:Type:Animate must be set to “Force”.

If an event has a parameter of this user type, then the parameter’s property CG:Type:Animate must be set to “Force”.

If an operation has an argument of this user type, then the argument’s property CG:Type:Animate must be set to “Force”.

Here are some examples of serialize/unserialize operations :

Case I : type Integer

type My_Integer is
    range 1..10;

Function:Add_attribute()

procedure Add_Attribute (	
    	udtName : in String;	
    	udtValue : in My_Integer;	
    	udtAttrList : in System.address	
    ) is	
    begin	
    	RhpAnim.Add_Attribute( udtName,	
				User_Type_Pkg.My_Integer'Image(udtValue),	
				udtAttrList	
				);	
end Add_Attribute;

Function:Get_attribute()

procedure Get_Attribute (	
	data : in out My_Integer;	
	address : in System.address;	
	position : in System.address	
    ) is	
	value : integer;	
    begin	
    	rhpanim.get_attribute(value,address,position);	
    	data := User_Type_Pkg.My_Integer(value);	
    end Get_Attribute;

Case II : enumerated type :

type type_0 is
    (	
    	ONE,	
    	TWO,	
    	THREE,	
    	FOUR,	
    	NULL_NULL	
    );

Function:Add_attribute()

procedure Add_Attribute (	
    	udtName : in String;	
    	udtValue : in type_0;	
    	udtAttrList : in System.address	
    ) is	
    begin	
    	RhpAnim.Add_Attribute(udtName,	
			user_type.type_0'Image(udtValue),	
			udtAttrList);	
    end Add_Attribute;

Function:get_attribute()

procedure Get_Attribute (	
    	data : in out type_0;	
    	address : in System.address;	
    	position : in System.address	
    ) is	
    		value : string(1..10);	
    begin	
    	rhpanim.get_attribute(value, address, position);	
    	if (value = "ONE") then	
    		data := User_Type.ONE;	
    	elsif (value = "TWO") then	
    		data := User_Type.TWO;	
    	elsif (value = "THREE") then	
    		data := User_Type.THREE;	
    	elsif (value = "FOUR") then	
    		data := User_Type.FOUR;	
    	else	
    		data := User_Type.NULL_NULL;	
    	end if;	
    end Get_Attribute;

Setup user type properties to generate automatically Serialize/Unserialize operations

A shorter method allows generating Serialize/Unserialize operations by simply updating properties on the type.

A serialize operation will be automatically generated if the property Ada_CG:Type:AnimSerializeOperationImpl is not empty. The operation signature will be automatically generated with respect of the user type. The operation implementation will be filled with the property content. For the first example described above, the property should have the value:

begin
    	RhpAnim.Add_Attribute( udtName,	
				%s'Image(udtValue),	
				udtAttrList	
				);	
     

The name of this operation is still controlled by the property Ada_CG:Type:AnimSerializeOperation. This property should contain the full qualified name which will be used when calling the operation.

An Unserialize operation will be automatically generated if the property Ada_CG:Type:AnimUnserializeOperationImpl is not empty. The operation signature will be automatically generated with respect of the user type. The operation implementation will be filled with the property content. For the first example described above, the property should have the value:

        value : integer;	
    begin	
    	rhpanim.get_attribute(value,address,position);	
    	data := %s(value);
     

The name of this operation is still controlled by the property Ada_CG:Type:AnimUnserializeOperation. This property should contain the full qualified name which will be used when calling the operation.

Animation of operations

In animation mode, it is possible to invoke manually an operation with some arguments. In order to enable this feature, an option in configuration settings can be set. This option will update the property Ada_CG::Operation::AnimAllowInvocation of the whole project for this configuration.

Animation can be set/reset individually for each operation by setting this property on the operation. The value of this property can be

• All - Enable all operation calls, regardless of visibility.
• None - Do not enable operation calls.
• Public - Enable calls to public operations only.
• Protected - Enable calls to protected operations only.

Limitation :

If the type of an argument is an unconstrained type, the code generator will create a wrong code for the animation of the operation. For example :

    Procedure operation_0(a : in out integer; b : in out string);

The argument b is of unconstrained type string. In this case the operation operation_0 cannot be animated. The property Ada_CG::Operation::AnimAllowInvocation of this operation should be set to “None”.

Animation on Remote Host

The remote host address and port can be setup in the file RiA_CG.ini. This file is located in <Rhapsody_Install_Dir>\Sodius\RiA_CG folder. To update this file, you must first copy it into the read/write folder <Rhapsody_USER_SHARE>\Sodius\RiA_CG.

The following properties must be set in this file.

• animationAddress=<RemoteHostIPAddress>
• animationPort=<RemoteHostPort>

Alternatively, one can use the Ada_CG.<Compiler>.UseRemoteHost and Ada_CG.<Compiler>.RemoteHost properties to setup the remote host address.

Limitations

Animation of string

An attribute of type string, wide_string or wide_wide_string cannot be animated if its mutator is automatically generated (Ada_CG::Attribute::MutatorGenerate = true). In this case an "unconstrained subtype" error occures in an autogenerated operation.

The animation of this attribute should be disabled (CG::Attribute::Animate = false).

Animation of Wide_Wide_String and Wide_Wide_Character

Wide_Wide_String and Wide_Wide_Character are new types, that are introduced in Ada 2005. The Ada FWK is created and compiled with Ada 95. For this reason, Wide_Wide_String and Wide_Wide_Character types cannot be animated.

The animation of attributes or arguments which have one of these types must be disabled (CG::Attribute::Animate = false or CG::Argument::Animate = false).