Package Overview
The Ima (Internal Model Access) package is a collection of Kernel Procedures that gives dynamic access to simulation entities: simulation attributes, object attributes, object commands, and process state variables.
Simulation attributes are data elements that are associated with the simulation as a whole, instead of a particular object. These attributes are declared within process models and are dynamically queried via the KPs op_ima_sim_attr_get(), op_ima_sim_attr_get_color(), op_ima_sim_attr_get_dbl(), op_ima_sim_attr_get_int32(), and op_ima_sim_attr_get_str().
Note: op_ima_sim_attr_get() supports multiple data types; however, the type-specific versions are more efficient and allow the compiler to catch potential argument errors.
Values for simulation attributes can be assigned via any of the simulation program environment mechanisms: command line flags, shell variables, environment files, or the preferences file (this last mechanism is rarely used for assigning values to dynamic attributes). If no assignment is specified for a queried attribute, a prompt is printed on the standard output device to obtain a value. If the KP op_ima_sim_attr_exists() returns OPC_TRUE, a value already resides within the simulation program environment and no prompt is needed to obtain a value.
Object attributes are data elements that belong to a specific simulation object. These attributes are either built into the definition of the object, defined by the user in a Riverbed Modeler editor, defined via an EMA program, or promoted from a lower-domain object. Values for promoted object attributes can be assigned using any of the simulation program environment mechanisms, including standard output device prompts.
During execution of a simulation, object attributes can be queried via the KP op_ima_obj_attr_get() or its type-specific versions op_ima_obj_attr_get_color(), op_ima_obj_attr_get_dbl(), op_ima_obj_attr_get_int32(), op_ima_obj_attr_get_objid(), op_ima_obj_attr_get_str(), and op_ima_obj_attr_get_toggle().
You can assign object attribute values via the KP op_ima_obj_attr_set() or its type-specific versions op_ima_obj_attr_set_color(), op_ima_obj_attr_set_dbl(), op_ima_obj_attr_set_int32(), op_ima_obj_attr_set_objid(), op_ima_obj_attr_set_str(), and op_ima_obj_attr_set_toggle().
The presence of an attribute on a particular object can be determined by calling the KP op_ima_obj_attr_exists(). Via these KPs, a process has access to the attributes of remote objects as well as those that belong to its own module. The KP op_ima_obj_hname_get() provides a quick method of obtaining the full hierarchical name of an object.
Querying an object attribute is a non-intrusive activity (that is, it does not affect the object or attribute being queried). Assigning a new value to an object attribute, however, might affect the internal operation of the object, depending on the modified attribute. In certain cases, an attribute assignment only has an effect when the object next queries the attribute’s value (that is, attribute assignments via the op_ima_obj_attr_set… KPs do not necessarily trigger actions).
In addition to object attributes, objects can also contain state information in the form of attached values or data structures. The KPs op_ima_obj_state_set() and op_ima_obj_state_get() allow such state information to be set and retrieved.
In some ways, the object attribute KPs of the Ima package are similar to procedures in the Ema package (discussed in the External Interfaces manual). The Ima procedures accept the same object attribute names that Ema does, and the same types of values passed via the void* interface. However, Ima KPs only provide access to one object attribute at a time (the ACV triplet feature of Ema is not supported). In addition, the simulation object identification scheme is different from the scheme used by Ema.
Objects generally only take actions due to interrupts (to be more precise, the Simulation Kernel generally only executes code which is associated with a particular object when that object receives an interrupt of some type). However, there are several actions that modules can perform by remote invocation not involving the standard remote interrupt facility. Since the actions supported are object-specific, and the modules that support this type of invocation don’t include the processor or queue, there is no user-visible interrupt type defined for this activity. The KP op_ima_obj_command() provides the remote action invocation facility, specifying the action to be taken via a command string.
In addition to object attributes, it is sometimes useful for a process to have remote access to the internal state variables of another process (either for querying or assignment). An alternative form of inter-process communication is available by remotely accessing state variables, a service provided by the KP op_ima_obj_svar_get().
The KP op_ima_obj_attr_get() provides a convenient interface for obtaining integer, double, and string attribute values. However, this interface is inefficient for obtaining the position of node objects, because six different attributes are involved. In addition, the relative position attributes of nodes within subnets need to be converted into the geocentric coordinate system. An alternate interface for this purpose is provided by the single KP op_ima_obj_pos_get(), which queries all six position-related attributes at once and automatically performs coordinate conversion for subnet nodes.
When you use Wireless modeling, the positions of mobile sites (nodes and subnets) can change with time. The KP op_ima_obj_pos_get_time() performs the same function as op_ima_obj_pos_get(), but for a specified time (current or future). The position obtained by these KPs is exact for mobile sites following a trajectory or vector. For other sites, the position obtained is simply the last one set for the site. The KP op_ima_obj_pos_query_proc_set() specifies a custom procedure that defines the exact position of a site that doesn’t follow a trajectory or vector. If a process model needs to know when a site changes position, the KP op_ima_obj_pos_notification_register() can set a site to generate an interrupt when its position changes.
You can set the position of a mobile site in geocentric or geodetic coordinates with op_ima_obj_pos_set_geocentric() and op_ima_obj_pos_set_geodetic().