op_ima_sim_attr_get()
Abstract
Obtains the value of a simulation attribute.
Syntax
op_ima_sim_attr_get (attr_type, attr_name, value_ptr)
| Argument | Type | Description |
|---|---|---|
attr_type |
int |
type of the attribute-of-interest [This value is an numeric code which specifies the attribute type; the acceptable values of this argument are OPC_IMA_INTEGER, OPC_IMA_DOUBLE, OPC_IMA_TOGGLE, OPC_IMA_STRING, or OPC_IMA_COLOR.] |
attr_name |
const char* |
name of the attribute-of-interest [This value must specify an attribute defined in the simulation environment, or a prompt will be issued for the attribute’s value.] |
value_ptr |
void* |
pointer to a variable to be filled with the specified attribute’s value [This argument can accept a pointer to an integer, a double, a PrgT_Color, or a character string. In the last case, 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.] |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the attribute value was successfully obtained; OPC_COMPCODE_FAILURE otherwise.
Example
Excerpt from: example model (models/std/fddi); process model (fddi_mac); state (INIT); enter execs.
/* Obtain the station latency for tokens and frames. */
op_ima_sim_attr_get (OPC_IMA_DOUBLE, "station_latency", &Fddi_St_Latency);
/* Obtain the propagation delay separating stations. */
/* This value is given in seconds. */
op_ima_sim_attr_get (OPC_IMA_DOUBLE, "prop_delay", &Fddi_Prop_Delay);
/* Derive the Delay for a ’hop’ of a freely circulating packet. */
Fddi_Tk_Hop_Delay = Fddi_Prop_Delay + Fddi_St_Latency;
example output of a simulation attribute prompt as it appears on the standard output device:
-------------------- Unset Environment Attribute ---------------------
* station_latency: <double>
* Desc:
* Press <return> to select default: 0.0
Enter Value> 4.5
Details
Simulation attributes are not defined during the model specification phase, which distinguishes them from subnet, node, module, and process attributes. Instead, these attributes are dynamically defined at simulation runtime. These values are assigned via an environment attribute mechanism: either the simulation’s command line, the preferences file (<HOME>/op_admin/opnet-<rel>.prefs), a shell variable, or an environment file (see Chapter 2 “Preferences” on page 31 for more information on environment attributes).
This KP causes the simulation’s internal preferences file to be scanned for possible values. If this KP cannot find a value for the simulation attribute in the existing program environment, then it will print a prompt on the standard output device, requesting a value (an example of such prompting is displayed in the example on the previous page). User prompting can be disabled using the noprompt environment attribute of simulations. When a prompt is issued, a default value for the attribute is printed as a suggested possibility.
Note: This default value is the value referenced by the passed value_ptr argument when the KP was invoked. It is NOT taken from the default initial value shown in the process model attribute table. For this reason, the value stored at the address that value_ptr references should be well-defined prior to invoking this KP, in order to have a clean prompt (if necessary).
This KP is considered to be successful, and returns the value OPC_COMPCODE_SUCCESS, if the specified attribute can be located within the simulation program’s environment or if the value is entered explicitly when prompted. If the Kernel must resort to using the value stored at the address referenced by value_ptr, OPC_COMPCODE_FAILURE is returned.
Purpose
Provides a mechanism to obtain simulation attributes that have been assigned values at simulation runtime. The combination of this KP and the assignment of simulation attribute values using environment attributes is a useful technique for getting key network-wide parameters down to the process level, where the parameters affect the operation of process logic. For example, a simulation attribute might be the number of retransmissions that data link protocols perform before giving up on a packet.
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_sim_attr_get_color(), op_ima_sim_attr_get_dbl(), op_ima_sim_attr_get_int32(), and op_ima_sim_attr_get_str().
Errors
- Program Abort: Segmentation violation. (due to an invalid value pointer, a pointer to an insufficient amount of memory, or a malformed attr_name argument)
- Program Abort: Allocation of memory failed.
- Recoverable Error: Attribute type (
<attr_type>) is unrecognized.
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_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 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