op_ima_obj_attr_get()
Abstract
Obtains the value of an attribute in the specified object.
Syntax
op_ima_obj_attr_get (objid, attr_name, value_ptr)
| 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 in the specified object, or an error will occur.] |
value_ptr |
void* |
pointer to a variable to be filled with the specified attribute’s value [This argument can accept a character string or a pointer to an integer, a double, a PrgT_Color, or an object ID that refers to a compound attribute value. In the case of a character string, the array of characters must be large enough to contain the attribute’s value. The data type of the argument pointer must match the data type of the specified attribute, or an error will occur. If the attribute is of type toggle, the return value will either be OPC_BOOLINT_ENABLED or OPC_BOOLINT_DISABLED. If the attribute is of type profile, the return value is a profile specification (PrgT_Profile_Spec) that contains the information necessary to access the profile using the function prg_profile_load().]. |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.
If you are dealing with merged compound attributes that are equal (see Note), value_ptr is set to the object ID of one of the merged compound attributes (which one is not specified) and OPC_COMPCODE_SUCCESS is returned. If the merged compound attributes are not equal, OPC_COMPCODE_FAILURE is returned.
Note: In the context of merged compound attributes, “equal” means that all attributes on the compound attribute object have the same name, type, and value, and all the child objects of the compound attribute are equal as well.
Example
/* determine id of own processor to use in finding attrs */
my_id = op_id_self ();
/* determine address range for uniform destination assignment */
op_ima_obj_attr_get (my_id, "low dest address", &low_dest_addr);
op_ima_obj_attr_get (my_id, "high dest address", &high_dest_addr);
/* determine object id of connected ’mac’ layer processor */
mac_objid = op_topo_assoc (my_id, OPC_TOPO_ASSOC_OUT,
OPC_OBJTYPE_QPS, MAC_LAYER_OUT_STREAM);
/* determine the address assigned to it */
/* which is also the address of this station */
op_ima_obj_attr_get (mac_objid, "station_address", &station_addr);
/* setup a distribution for generation of addresses */
dest_dist_ptr = op_dist_load ("uniform_int", low_dest_addr, high_dest_addr);
Additional example—obtaining and using a character string variable:
/* Obtain the process name (the "process model" attribute of the module. */
/* Assumes proc_model_name is declared in the temporary variable block as: */
/* char proc_model_name [128]; */
op_ima_obj_attr_get (op_id_self (), "process model", proc_model_name);
Details
Object attribute values can be obtained from 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 of attributes that have been promoted may be obtained from objects which hierarchically contain the defining object (for example, an attribute automatically promoted from a processor’s root process can be obtained from 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, obtaining 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 obtained.
Not all object attributes are accessible by calling op_ima_obj_attr_get() 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_get().
Note: When getting a string attribute, make sure *value_ptr is large enough to hold the expected attribute value. String attributes can be any length; however, a maximum of 2048 characters are displayed to the user.
Purpose
Provides a mechanism to dynamically obtain object attributes during the course of the simulation. This facility can be used by a processor (or queue) to determine the values of its own attributes, or those of any other object in the network. For example, the pointing direction of an antenna can be queried, or the power of a transmitter’s channel. This KP, in conjunction with op_ima_obj_attr_set(), can also provide a method of remote inter-process communication without involving packet, ICI, or interrupt delivery.
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_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().
Errors
- Program Abort: Segmentation violation (due to an invalid value pointer, pointer to an insufficient amount of memory, or invalid address for
attr_name) - Recoverable Error: Attribute name (
<attr_name>) is unrecognized for object (<objid>). - Recoverable Error: Object ID (
<objid>) is out-of-range. - Recoverable Error: Object ID (
<objid>) refers to a restricted object. (due to the object-of-interest located within a protected model)
Reference
- Use the KPs op_ima_obj_attr_set(), 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() to assign a value to 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