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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com