op_ima_obj_pos_notification_register()
Abstract
Enables process models to be notified whenever a site moves.
Syntax
op_ima_obj_pos_notification_register (site_objid, code, options)
| Argument | Type | Description |
|---|---|---|
site_objid |
Objid |
object ID of the site-of-interest (node or subnet) [A site object ID can be obtained from several KPs in the Id and Topo packages: op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
code |
int |
code for remote interrupt. |
options |
int |
notification options (see Details section). |
Return Type
Compcode
OPC_COMPCODE_FAILURE if an error occurs (see Errors section); OPC_COMPCODE_SUCCESS otherwise.
Example
/* set the site to generate an interrupt whenever the parent node's */
/* position is updated */
op_ima_obj_pos_notification_register (op_topo_parent (op_id_self ()),
1, OPC_IMA_NOTIFY_ONLY_WHEN_CHANGED);
Details
This KP cannot execute outside of a processor or queue.
The available options are:
OPC_IMA_NOTIFY_NO_OPTS– an interrupt is delivered whenever the site position is recomputed by the Simulation Kernel for the current time.OPC_IMA_NOTIFY_ONLY_WHEN_CHANGED– an interrupt is delivered only if the recomputation yields a different position from the previous computation (thus, stationary nodes will not trigger events).
Purpose
This KP is useful for sites that follow trajectories, since a node's position isn’t updated until something needs its position (for example, sending or receiving radio packets). Using this KP, a process model can request that a remote interrupt be delivered whenever the site position is updated. The remote interrupt will have the code specified in the KP.
Errors
- Program Abort: KP requires process context.
- Recoverable Error: Object ID (
<site_objid>) is out-of-range. - Recoverable Error: Object ID (
<site_objid>) refers to a restricted object. Recoverable Error: Unable to set position notify callback for object (<site_objid>) because it is not a site (<type_name>)
Reference
- Use the KP op_ima_obj_pos_get() to get the global position-related attributes of a site.
- Use the KP op_ima_obj_attr_get_dbl() to obtain a single position-related attribute of a site.