op_ima_obj_attr_set()
Abstract
Assigns the value of an attribute in the specified object.
Syntax
op_ima_obj_attr_set (objid, attr_name, value)
| Argument | Type | Description |
|---|---|---|
objid |
Objid |
object ID of the object-of-interest [An object ID can be obtained from several KPs in the Topo and Id packages: op_id_self(), op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
attr_name |
const char* |
name of the attribute-of-interest [This value must be a defined attribute of the specified object.] |
value |
void* |
new value for the specified attribute [This argument can accept an integer, a double, a PrgT_Color, or a character string value. The data type for this argument must match that of the attribute referenced by attr_name; otherwise the attribute may be assigned an incorrect value. If the attribute is of type profile, the new value must be a profile specification that contains the information necessary to access the profile. The specification is obtained using the function prg_profile_spec_get().] |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the attribute value was successfully set; OPC_COMPCODE_FAILURE otherwise.
Example
Excerpt from: example model (models/std/jammers); process model (jam_sweep_proc); state (TX_ON); enter execs.
/* begin a new transmission */
double freq_tx;
/* compute the frequency of transmission */
freq_tx = freq_base + freq_slot * freq_interval;
/* advance the frequency slot for next transmission */
freq_slot = (freq_slot + 1) % num_intervals;
/* assign the selected frequency to the transmitter channel */
op_ima_obj_attr_set (txch_objid, "min frequency", freq_tx);
Details
Object attribute values can be assigned to network-domain objects (subnets, nodes, and links), node-domain objects (modules) and compound attributes, provided that the attributes have been previously defined using the Network, Node, Process or Link Editors (or via an Ema program). In addition, values can be assigned to attributes that have been promoted to objects which hierarchically contain the defining object (for example, an attribute automatically promoted from a processor’s root process can be assigned via a subnet which hierarchically contains the processor). Referencing promoted attributes entails the addition of a dot-separated prefix to the attribute name for every hierarchically intermediate object; i.e., the attribute name is specified as it would appear in the menu of the referenced object. For example, assigning a process attribute at the node level requires that the attribute name be preceded by the name of the module which “contains” the process instance. Regardless of the modeling level used to reference an attribute, the same common attribute memory cell is found and assigned.
Not all object attributes are accessible by calling op_ima_obj_attr_set() during a simulation. Chapter 3 “Network Reference” on page 60 covers link and node attributes in detail. Any attribute whose Simulation/Access field is marked N/A cannot be accessed by calling op_ima_obj_attr_set().
Purpose
Provides a mechanism to dynamically assign object attributes during the course of a simulation. This facility can be used by a processor (or queue) to control other modules. This KP, in conjunction with op_ima_obj_attr_get(), can also provide a method of remote inter-process communication without involving packet, ICI, or interrupt delivery; in this application, it should be noted that remotely changing the value of another object’s attribute will not cause an interrupt, and will thus only have an effect when the modified object next queries its attribute value via the KP op_ima_obj_attr_get().
Data-type-specific versions of this KP exist. These alternate KPs are more efficient than this variable argument version. In addition, they allow the compiler to catch argument errors that are missed with this KP. For details, refer to 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().
Errors
- Program Abort: Segmentation violation. (due to an invalid value pointer, invalid address for
attr_name, or value of incorrect type) - Recoverable Error: Attribute name (
<attr_name>) is unrecognized for object (<objid>). - Recoverable Error: Object ID (
<objid>) is out-of-range. - Recoverable Error: Attribute (
<attr_name>) of object (<objid>) is read-only. - Recoverable Error: Value is invalid for attribute (
<attr_name>). - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KPs op_ima_obj_attr_get(), 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() to obtain the value of an object attribute
- Use 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() to obtain the value of a simulation attribute
- Use the KP op_ima_obj_svar_get() to obtain the value of a process state variable
- Use the KP op_ima_obj_command() to issue a command to an object
- Use the KP op_id_self() to obtain the object ID of the surrounding processor or queue
- Use the KP op_id_from_name() to obtain the object ID of an arbitrary object