op_ima_obj_svar_get()
Abstract
Obtains a pointer to a state variable within the specified object (a processor or queue).
Syntax
op_ima_obj_svar_get (objid, svar_name)
| Argument | Type | Description |
|---|---|---|
objid |
Objid |
object ID of the object-of-interest [A processor or queue object ID can be obtained from several KPs in the Topo and Id packages: op_topo_assoc(), op_topo_child(), op_id_self(), and op_id_from_name().] |
svar_name |
const char* |
name of the state variable-of-interest [This value must be the name of a defined state variable in the process model of the specified processor or queue, or an error will occur. Note that the backslash character (used to delimit state variable names in the Process Editor state variable block) should not be included in this value.] |
Return Type
void*
Pointer to the specified state variable. OPC_NIL will be returned in case of a recoverable error. Because state variables can have any data type, the value returned by this KP is declared as void* (a pointer to a variable data type). To access the state variable through the returned pointer, it should be cast into a pointer of the appropriate data type.
Example
/* determine the object ID of a remote queue */
rem_node_objid = op_id_from_name (0, OPC_OBJTYPE_NODE_FIXED, "frnt_end");
rem_queue_objid = op_id_from_name (rem_node_objid, OPC_OBJTYPE_QUEUE, "qbs");
/* obtain key state variables of queueing process */
prio_thresh_ptr = (int *) op_ima_obj_svar_get (rem_queue_objid, "prio_thresh");
protocol_version = (char *) op_ima_obj_svar_get (rem_queue_objid, "proto_ver");
/* modify the state variables */
*prio_thresh_ptr = 44;
sprintf (protocol_version, "Ver 5.1");
Details
This KP can only be successfully applied to queue and processor objects, since only these objects run processes with user-accessible state variables. Applying it to other object types will cause an error to occur.
A processor or queue can contain child processes in addition to the root process. The state variables of the root process will be the variables obtained by op_ima_obj_svar_get(). The state variables of the child processes can be obtained using op_pro_svar_get().
Although this KP is MT safe (as described in “Multi-Threading Safety“ on page 11), it must be used with care if multiple clients are accessing or modifying shared svar information.
Purpose
Provides an alternative mechanism for interprocess communications (in addition to packets, ICIs, remote interrupts, statistics wires, global variables, and remotely setting attributes using the KP op_ima_obj_attr_set()). By having access to another process’ state variables, a process can communicate via semaphores, monitor execution status, or modify the operation of the remote process. The programming paradigm for remote state variables is similar to the concept of shared registers on a memory-mapped bus-interfaced computer peripheral.
Errors
- Program Abort: Segmentation violation. (due to a malformed svar_name argument)
- Recoverable Error: Object ID (
<objid>) is out-of-range. - Recoverable Error: Object (
<objid>) has incorrect type. Queue or processor objects are expected. - Recoverable Error: State variable (
<svar_name>) is not defined in root process model. - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KP op_pk_deliver() to deliver a packet to a remote module
- Use the KP op_intrpt_schedule_remote() to interrupt a remote module
- Use the KP op_stat_write() to write a value to a statistic wire connected to another module
- Use the KPs op_ima_obj_attr_set(), 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 the value of an attribute of a remote module