opnet 基本核心函数 －－－6 统计量函数集

2.12 统计量函数集

Stat（Statistic）函数集中所包含的核心函数将用户自定义的自动计算的统计量写入仿真中创建的数据文件。输出文件共有两类：矢量输出文件和标量输出文件。

 

1. op_stat_reg (group_dot_stat_name, stat_index, type )

此核心函数的作用是返回进程模型中节点或模块统计量（局部或全局）的句柄，其参数说明如表2-38所示。

表2-38  op_stat_reg()函数的参数说明

参数	类型	描   述
group_dot_stat_name	const char*	统计量的所在组和名称，用“．”隔开
stat_index	int	统计量的数字索引，若为一维统计量，则为OPC_STAT_INDEX_NONE
type	int	OPC_STAT_GLOBAL（全局统计量） OPC_STAT_LOCAL（局部统计量）

1）返回值

Stathandle——统计量句柄，可在函数op_stat_write()和op_stat_write_t()调用时使用。

2）详解

该函数与op_stat_obj_reg()类似，但本函数只能用在进程模块上下文中，且既可注册局部统计量，又可注册全书统计量。

仿真内核集中管理全局统计量和局部统计量，为每个统计量都保存了所属组、名称、索引、类型和输出矢量。当使用函数op_stat _reg()注册统计量时，可为其指定前面四项。如果能做到名称同步，则可允许多个进程访问相同的统计量。所有进程都可集结同一全局统计量，而同一模块的进程才可集结同一局部统计量。

多维统计量提供了一个输出统计量库，Stathandle根据索引指向库中的元素。一维统计量全用符号常量OPC_STAT_INDEX_NONE作为索引值。

使用全局统计量时，模型中的所有进程共享一个输出矢量，并记录它们测量的端到端延时。而使用局部统计量时，每个进程只记录自己的输出矢量。

注册统计量时将会在现有统计量中搜索名称和所属组。为提高效率，一个统计量只能注册一次，然后缓存统计量句柄以便使用。

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

3）目的

统计量注册提供了一种多个进程共享输出矢量的机制。进程只需要调整统计量名称就可通过注册来访问统计量，这可以比较容易地避免独立模型间的冲突。函数op_stat_write()和op_stat_write_t()可以根据该函数返回的统计量句柄，并将值写到统计量中。

4）错误

Program Abort：分段错误（由无效或畸形stat_name参数引起）。

Recoverable Error：无法注册统计量（由未声明统计量引起）。

Recoverable Error：因内存限制而无法注册统计量。

Program Abort：核心函数需要进程上下文。

Recoverable Error：统计量索引溢出。

5）相关函数

采用op_stat_obj_reg()访问任意链路、路径、模块或子模块对象统计量。

采用op_stat_write()将值写到输出统计量中，并标记当前仿真时间。

采用op_stat_write_t()将值写到输出统计量中，并标记指定的仿真时间。

采用op_stat_scalar_write() 将值写到与其他仿真中记录的标量合并的标题统计量中。

 

2. op_stat_write (stat_handle, value)

此核心函数的作用是将（时间，值）对写到指定统计量中，将写入的值通过参数传递给该函数，时间为当前仿真时间，其参数说明如表2-39所示。

表2-39  op_stat_write()函数的参数说明

参数	类型	描   述
stat_handle	Stathandle	指定统计量的统计量句柄
value	double	指定统计量将写入的值

1）返回值

void——无返回值。

2）详解

该核心函数为给定统计量的输出矢量附加一个新的（时间，值）对。统计量只能是采用函数op_stat_reg()注册的统计量。句柄使用不当将导致可恢复仿真错误。

仿真模型中的不同进程如果使用相同的统计量句柄，那么就可通过该函数将值写到同一个输出矢量中。

在同一仿真时间对函数op_stat_write()的多次调用将按序记录，而不是互相覆盖。

为了在输出矢量文件中产生数据，统计量必须使用探针编辑器中定义的探针对象探测，或在项目编辑器中通过选择统计量操作将其选中。探针文件的名称由仿真的探针属性确定。需要设置仿真的record_gstats属性来记录所有的全局统计量。

如果捕获模式是“divides by time”，且在特定时间段内统计量有效，则必须采用函数op_stat_write()在时间段结束时向统计量写入零值，以报告系统该时间段已结束。

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

3）目的

该核心函数将值写入输出矢量中，并标记当前仿真时间。

如果Stathandle指向一个与统计线相连的局部统计量，且该统计线处于解状态，那么将为统计线的目的模块预设一个中断。

4）错误

Program Abort：分段错误（由无效统计量句柄引起）。

Recoverable Error：使用未注册的统计量句柄。

5）相关函数

采用op_stat_local_read()读取输入统计量的当前值。

采用op_stat_write_t()将值写到输出统计量中，并标记指定的仿真时间。

采用op_stat_scalar_write() 将值写到与其他仿真中记录的标量合并的标题统计量中。

采用op_stat_obj_reg()访问任意链路、路径、模块或子模块对象统计量。

采用op_stat_reg()获取统计量句柄。