2.7 拓扑函数集

Topo(Topology)函数集是确定节点和网络模型拓扑结构的核心函数的集合。利用这类核心函数，进程模型在被写入时可以自动配置以符合其所属环境。

1. op_topo_parent (child_objid)

此核心函数的作用是获取给定对象的父对象ID，其参数说明如表2-12所示。

表2-12 op_topo_parent()函数的参数说明

1）返回值

Objid——父对象ID。如果参数child_objid为最高级别的子网ID，则返回符号常量OPC_OBJID_NULL；如果发生可恢复错误，将返回符号常量OPC_OBJID_INVALID。

2）详解

连续调用该核心函数可用于提示对象层次结构。例如在一个五级对象仿真中，可利用子队列对象ID，通过连续五次调用该函数来获取最高级别的子网（对象ID=0），程序如下所示：

subq_comp_attr_objid=op_topo_parent(subqueue_objid);

queue_objid=op_topo_parent(subq_comp_attr_objid);

node_objid=op_topo_parent(queue_objid);

subnet_objid=op_topo_parent(node_objid);

top_subnet_objid=op_topo_parent(subnet_objid);

注意：subq_comp_attr_objid是复合属性的嵌入类型。对于用户自定义的算命属性有：comp_attr_objid= op_topo_parent(generic_objid)

path没有父对象，因此若child_obj_hndl指向一个path对象，则该函数将返回一个无效句柄。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了一种已知低层对象ID，需要对高层对象进行操作时，提升对象层次结构的机制。通常，该核心函数用于获取包含运行调用进程的处理器或队列的节点（或子网）ID。在获取了节点或子网的对象ID后，就可通过op_ima_obj_attr_get()获取它们的属性值。

4）错误

Recoverable Error：对象ID溢出。

Recoverable Error：对象ID指向受限对象。

5）相关函数

采用op_id_self()获取所属处理器或队列模块的对象ID。

采用op_topo_child()获取另一对象的子对象ID。

采用op_ima_obj_attr_get()获取对象属性值。

采用op_ima_obj_attr_set()设置对象属性值。

 

2. op_topo_child_count (parent_objid, child_type)

此核心函数的作用是获取给定父对象中指定类型的子对象的数目，其参数说明如表2-13所示。

表2-13  op_topo_child_count ()函数的参数说明

1）返回值

int——给定父对象中指定类型的子对象的数目。如果父对象不支持指定类型的子对象或父对象ID无效，则将返回符号常量OPC_OBJID_INVALID。

2）详解

仿真对象通常包含的子对象如表2-14所示。

表2-14  op_topo_child_count ()函数的参数说明

通常仿真对象并不包含以下子对象：单工和双工方式的点到点链路、总线链路、总线链路接头、处理器和天线。

path没有子对象，也不属于任何子网，因此如果参数parent_object指向一个path对象或参数child_type等于OPC_OBJTYPE_PATH，则该核心函数将返回零。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了一种确定父对象包含的子对象数目的机制。可利用父对象ID、定义对象类型的符号常量和环路索引来调用函数op_topo_child()，以获取每个子对象的对象ID。

4）错误

Recoverable Error：对象ID溢出。

Recoverable Error：对象类型不可识别。

Recoverable Error：对象ID指向受限对象。

5）相关函数

采用op_topo_child()根据索引来获取子对象ID。

采用op_topo_object_count()确定特定类型对象的数目。

采用op_topo_assoc_count()获取输入和输出关联的数目。

 

3. op_topo_child (parent_objid, child_type, child_index)

此核心函数的作用是获取具有指定类型和索引的子对象ID，其参数说明如表2-15所示。

表2-15  op_topo_child ()函数的参数说明

参数	类型	描   述
parent_objid	Objid	父对象ID
child_type	int	子对象类型
child_index	int	子对象索引（子索引从零开始逐一递增，最大不超过本类子对象的总数减一）

1）返回值

Objid——子对象ID。如果发生可恢复错误，将返回符号常量OPC_OBJID_INVALID。

2）详解

确定子对象需要两个参数：子对象类型和子对象索引。连续调用该函数可降低对象的层次结构。例如在一个五级对象仿真中，可能过连续五次调用该函数将最高级别的子网（对象ID=0）转换为子队列对象ID，程序如下所示：

subnet_objid=op_topo_child(top_subnet_objid, OPC_OBJTYPE_SUBNET_FIX, 0);

node_objid=op_topo_child(subnet_objid, OPC_OBJTYPE_NDFIX, 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);

注意，subq_comp_attr_objid是复合属性的嵌入类型。对于用户自定义的复合属性有：

Generic_objid=op_topo_child(comp_attr_objid, OPC_OBJTYPE_GENERIC, 0);

path没有子对象，也不属于任何子网，因此若parent_obj_hndl指向一个path对象或child_type等于OPC_OBJTYPE_PATH，则该核心函数将返回一个空句柄。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了一种已知高层对象ID，需要对低层对象进行操作时，降低对象层次结构的机制。该函数通常用于获取已知发信机或收信机的信道ID，从而通过函数op_ima_obj_attr_get()或op_ima_obj_attr_set()来获取信道属性值或为其赋值。该函数还可用于获取节点中的模块ID，但通常使用名称而不是索引值来确定子对象的函数op_id_from_name()。该函数也可用于获取用户自定义的复合属性和其子对象ID。

4）错误

Recoverable Error：对象ID溢出。

Recoverable Error：对象类型不可识别。

Recoverable Error：对象无子对象。

Recoverable Error：对象索引溢出。

Recoverable Error：子索引超过指定类型子对象。

Recoverable Error：对象ID指向受限对象。

5）相关函数

采用op_topo_child_count()确定对象的子对象数目。

采用op_ima_obj_attr_get()获取对象属性值。

采用op_ima_obj_attr_set()设置对象属性值。

采用op_topo_object()获取对象ID。

采用op_topo_parent()获取父对象ID。

采用op_id_from_name()通过名称获取子对象ID。

 

4. op_topo_assoc (objid, direction, objmtype, index)

此核心函数的作用是获取具有指定类型、方向和索引的对象关联ID，其参数说明如表2-16 所示。

表2-16  op_topo_assoc ()函数的参数说明

参数	类型	描   述
objid	Objid	对象ID
direction	int	关联的方向： OPC_TOPO_ASSOC_IN：输入关联 OPC_TOPO_ASSOC_OUT：输出关联 OPC_TOPO_ASSOC_THROUGH：吞吐率关联
objmtype	int	关联的对象meta-type
index	int	关联的数值索引（从零开始，逐一递增）

1）返回值

Objid——输入/输出关联的对象ID。如果发生可恢复错误，则返回符号常量OPC_OBJID_INVALID。

 

2）详解

所谓对象的输入/输出关联，就是直接与输入/输出端口或在节点处开始/结束的路径相连的对象。表2-17列出了有效的对象和关联类型。

 

表2-14  对象和关联类型

对象类型	输  入	输  出	经  由
site(fixed subnet; fixed node)	site, link, path	site, link, path	path
link(bus;simplex; duplex; pt-pt link)	site receiver	site receiver	path
path	site (head/tail)	site(head/tail)	all attached nodes/links, all demands flowing through
demand	site(destination)	site(source)	all path used
module(processor, queue, and so on)	module connection	module connection	none
connection(stream, statistic wire)	module	module	none
transmitter(pt-pt, bus, radio)	module connection	link receiver	none
receiver(pt-pt, bus, radio)	link transmitter	module connection	none
tap	bus, bus transmitter	bus,bus receiver	none
bus transmitter	none	tap	none
bus receiver	tap	none	none
bus	tap	tap	none

在无线建模中，移动站点和卫星站点不能与点到点链路或总线链路相连，因此只能是中由关联和需求关联。同样，无线域也没有关联。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了一种已获取与输入/输出对象相关联的对象关联的对象ID的机制。该函数主要用于进程需要获取钷设置邻近对象属性的情况下，如在发信机相连的处理器上运行的进程，可能需要周期性地改变发信机信道的频率；或进程可能质询输出点到点链路的属性。

4）错误

Recoverable Error：对象ID溢出。

Recoverable Error：关联方向不可识别。

Recoverable Error：对象meta-type不可识别。

Recoverable Error：关联索引溢出。

Recoverable Error：对象类型不支持关联。

Recoverable Error：对象不支持关联方向。

Recoverable Error：关联索引超过关联类型。

Recoverable Error：对象ID指向受限对象。

5）相关函数

采用op_topo_assoc_count()确定对象拥有的关联数目。

采用op_ima_obj_attr_get()获取对象属性值。

 

5. op_topo_assoc_count (objid, direction, objmtype)

此核心函数的作用是获取具有特定类型和和对象的关联数目，其参数说明如表2-18所示。

表2-18  op_topo_assoc_count ()函数的参数说明

参数	类型	描   述
objid	Objid	对象ID
direction	int	关联的方向： OPC_TOPO_ASSOC_IN：输入关联 OPC_TOPO_ASSOC_OUT：输出关联
objmtype	int	关联的对象meta-type

1）返回值

Objid——特定方向和类型的关联数目。若发生可恢复错误，则返回符号常量OPC_OBJID_INVALID。

2）详解

对象的输入/输出关联，是直接与输入/输出端口相连的对象，参看表2-17。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了一种确定对象拥有的输入/输出关联的数目的方法。这对于设置关联对象的环路范围很有用。可根据对象ID和环路索引调用函数op_topo_assoc()来获取每个关联的对象ID。

4）错误

Recoverable Error：对象ID溢出。

Recoverable Error：关联方向不可识别。

Recoverable Error：对象meta-type不可识别。

Recoverable Error：对象类型不支持关联。

Recoverable Error：引用对象不支持关联方向。

Recoverable Error：对象ID指向受限对象。

5）相关函数

采用op_topo_assoc ()获取输入/输出关联的对象ID。

采用op_ima_obj_attr_get()获取对象属性值。

采用op_ima_obj_attr_set()设置对象属性值。

采用op_topo_child_count()确定子对象数目。

采用op_topo_object_count()确定特定类型的对象数目。