op_topo_child()
Abstract
Obtains the object ID of an object’s child having the requested type and index.
Syntax
op_topo_child (parent_objid, child_type, child_index)
| Argument | Type | Description |
|---|---|---|
parent_objid |
Objid |
object ID of the parent object [An object ID can be obtained from several KPs in the Id package: op_id_self(), op_id_from_userid(), and op_id_from_name(). In addition, object IDs can be obtained from prior invocations of the Topo package KPs op_topo_parent(), op_topo_child(), op_topo_assoc(), and op_topo_connect().] |
child_type |
int |
meta-type of the child-of-interest [This value is an integer code that specifies the object type of the child-of-interest (see Table 69 “Object Type Symbolic Constants“ on page 19).] |
child_index |
int |
numeric index of the child-of-interest [Child indices start at 0 and increment by one, up to the number of children of that object type less one.] |
Return Type
Objid
Object ID of the specified child object. The special value represented by the symbolic constant OPC_OBJID_INVALID will be returned if a recoverable error occurs.
Example
/* Set unique user ID's of the nodes in parent subnet. */
/* First obtain the subnet object ID. */
node_id = op_topo_parent (op_id_self ());
subnet_id = op_topo_parent (node_id);
/* Determine the number of children that are nodes. */
node_count = op_topo_child_count (subnet_id, OPC_OBJMTYPE_NODE);
/* Loop through the child nodes and set unique user ID's. */
for (i = 0; i < node_count; i++)
{
node_id = op_topo_child (subnet_id, OPC_OBJMTYPE_NODE, i);
op_ima_obj_attr_set (node_id, "user id", i);
}
Details
A child object is contained within the parent object. Children of subnets are other subnets, nodes, links, and bus taps. Children of nodes are modules, streams and statistic wires. Children of queue modules are subqueues. Children of transmitters and receivers are channels.
Two arguments are required to specify the child-of-interest:
- the type of the child object
- the numeric index of the child object within the set of all children of the specified type
Successive calls to this KP can be used to move down the object hierarchy. In an example simulation with five levels of objects, the “top” subnet (object ID = 0) could be converted into a subqueue object ID using five successive calls to this KP, as shown below:
subnet_objid = op_topo_child (top_subnet_objid, OPC_OBJTYPE_SUBNET_FIX, 0);
node_objid = op_topo_child (subnet_objid, OPC_OBJTYPE_NODE_FIX, 0);
queue_objid = op_topo_child (node_objid, OPC_OBJTYPE_QUEUE, 0);
subq_comp_attr_objid = op_topo_child (queue_objid, OPC_OBJTYPE_COMP, 0);
subqueue_objid = op_topo_child (subq_comp_attr_objid, OPC_OBJTYPE_SUBQ, 0);
Note that subq_comp_attr_objid is a built-in type of compound attribute. For user-defined compound attributes:
generic_objid = op_topo_child (comp_attr_objid, OPC_OBJTYPE_GENERIC, 0);
Paths have no children and do not belong to any subnet; hence this function returns an empty handle if parent_obj_hndl references a path object or child_type equals OPC_OBJTYPE_PATH.
Purpose
Provides a mechanism to move down the object tree when the ID of a higher-level object is known, and an operation needs to be performed on a lower level object. This KP is often used to obtain the object ID of a channel contained within a known transmitter or receiver, in order to obtain or assign the value of channel attributes via the KPs op_ima_obj_attr_get() or op_ima_obj_attr_set(). An alternative application is obtaining the object ID of a module contained within a known node using this KP, but this is usually performed via the KP op_id_from_name(), which identifies a child object by its name instead of its numeric index. This KP is also used to obtain the object IDs for a user-defined compound attribute and its subobjects.
Errors
- Recoverable Error: Object ID (<parent_objid>) is out-of-range.
- Recoverable Error: Object meta-type (<child_type>) is unrecognized.
- Recoverable Error: Object (<parent_objid>) has no children.
- Recoverable Error: Child index (<child_index>) is out-of-range.
- Recoverable Error: Child index (<child_index>) exceeds children of specified type.
- Recoverable Error: Object ID (<parent_objid>) refers to a restricted object.
Reference
- Use the KP op_topo_child_count() to determine the number of children an object has
- Use the KP op_ima_obj_attr_get() to obtain the value of an object’s attribute
- Use the KP op_ima_obj_attr_set() to assign the value of an object’s attribute
- Use the KP op_topo_object() to obtain the object ID of an object
- Use the KP op_topo_parent() to obtain the object ID of an object’s parent
- Use the KP op_id_from_name() to obtain the object ID of a child object from its name