opnet 核心函数 －－－－3 接口控制信息函数集

2.8接口控制信息函数集

ICI（Interface Control Information）函数集是与ICI仿真实体相关的核心函数的集合。ICI是内部进程通信所传递的数据的结构化集合。若进程在中断发生之前建立ICI，则ICI就与中断关联起来了。ICI主要用于分层协议的接口连接，也可用于关联复杂的自中断或点到点远程中断的信息。

1. op_ici_create(fmt_name)

此核心函数的作用是创建一个具有预定义ICI格式的ICI，其参数说明如表2-19所示。

表2-19  op_ici_create ()函数的参数说明

参数	类型	描   述
fmt_name	const char*	被创建ICI的格式名称（该值必须为已定义的ICI格式名称，否则将出错。）

1）返回值

Ici*——指向新创建的ICI的指针。若发生可恢复错误，则返回常量OPC_NIL。

2）详解

新的ICI由仿真内核分配，该函数返回它的指针并允许原始进程指定ICI属性。ICI格式是预先定义的固定结构，由一系列属性名称和类型按序组成。除非调用函数op_ici_install()，否则新创建的ICI不会自动影响预设中断。

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

3）目的

该核心函数为进程模型提供了一种创建新的ICI与邻居进程进行通信的机制。如果进程模型每次预设中断时都改变ICI的属性，并且在传递中断前又预设新的中断，那么它应为每个预设中断创建一个新的ICI。换句话说，如果两个进程模型采用一系列未延迟的ICI-bearing中断进行通信，那么中需要在开始仿真时为单向通信创建一个ICI（或为双向通信创建两个ICI）。

4）错误

Program Abort：内存分配失败（由于内存不足以满足新创建的ICI或其属性而引起）。

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

Recoverable Error：ICI格式不可识别

5）相关函数

采用op_ici_destroy()销毁ICI。

采用op_ici_attr_set()为ICI属性赋值。

采用op_ici_install()创建一个与输出中断相关联的ICI。

采用op_ici_format_print_set()打印给定格式ICI的指定结构字段。

 

2. op_ici_destroy(iciptr)

此核心函数的作用是解除已分配的ICI，并释放相应的内存资源，其参数说明如表2-20所示。

表2-20  op_ici_destroy ()函数的参数说明

参数	类型	描   述
iciptr	Ici*	指向给定ICI的指针（可以通过两个核心函数来获取ICI指针：在ICI发送进程中，函数op_ici_create()返回新创建ICI的指针：在ICI接收进程中，函数op_intrpt_ici()返回与输入中断相关的ICI指针）

1）返回值

Void——无返回值。

2）详解

当不再使用某个ICI时，就应当释放分配给它的内存资源，以用来创建新的ICI。若在仿真内核心释放ICI内存资源时出错，将导致无用的ICI持续占用虚拟内存。虚拟内存被完全占用后，将无法满足创建其他新对象的需要，则仿真异常结束。

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

3）目的

该核心函数提供了一种重复利用分配给无用ICI的内存的机制。仿真内核可自由地按需将内存分配给其他动态对象。调用该函数后，给定ICI的指针就应视为无效。

4）错误

Program Abort：分段错误（由无效ICI指针或畸形ICI数据结构引起）。

Recoverable Error：ICI指针为NIL。

5）相关函数

采用op_ici_create()创建ICI。

采用op_intrpt_ici()获取与输入中断相关的ICI指针。

采用op_ici_attr_set()为ICI属性赋值。

采用op_ici_install()创建一个与输出中断相关联的ICI。

 

3. op_ici_attr_get(iciptr, attr_name, value_ptr)

此核心函数的作用是获取给定ICI的某属性值，其参数说明如表2-21所示。

 

表2-21  op_ici_attr_get ()函数的参数说明

参数	类型	描   述
iciptr	Ici*	指向给定ICI的指针
attr_name	const char*	属性名
value_ptr	Vartype*	指向变量的指针，该变量中存储了将赋给指定属性的值。

1）返回值

Compcode­——表示是否成功获取ICI属性值的完整代码，如果发生可恢复错误，则返回OPC_COMPCODE_FAILURE。

2）详解

给定的属性名必须是ICI引用的格式中定义过的属性。注意，函数返回的是属性的当前内容，而不是创建ICI或预设相关中断时的属性内容。

进程模型是通过指针和不同的包来操作ICI的，并没有ICI所有权的概念。也就是说，几个进程模型可能同时访问同一ICI数据结构，因此可能会互相干扰。当多个事件都处理同一ICI时，修改ICI将影响ICI在之前事件中的使用。例如，如果一个进程创建了一个ICI，为其属性赋值，将其安装，接着发送了一个包，并在包收到之前修改了ICI的一个属性，那么值将是进程模型收到包时通过函数op_ici_attr_get()访问ICI获取的值。

在声明参数value_ptr时必须注意，value_ptr不仅要具有正确的数据类型，还必须是指向可用内存的有效指针，因此该参数通常都使用C语言的地址操作符“&”。

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

3）目的

该核心函数提供了一种进程收到与ICI相关的中断并确定ICI属性值的机制。由于一个ICI可被多个进程共享，因而它可用于多路通信。这里进程收到一个中断，从ICI中获取控制信息，并能过在ICI中设置属性来返回信息。因为返回值可立即被初始进程访问，所以通常可与强制中断结合使用。

4）错误

Program Abort：分段错误（由无效ICI指针、畸形ICI数据结构或声明出错的value_ptr参数引起）

Recoverable Error：属性名称在ICI格式中不可识别

5）相关函数

采用op_intrpt_ici()获取与输入中断相关的ICI指针。

采用op_ici_attr_exists()确定在ICI格式中是否存在某属性。

采用 op_ici_attr_set()设置ICI属性值。

采用op_ici_destroy()销毁无用ICI。

采用 op_ici_print()在标准输入设备上打印ICI内容。

 

4. op_ici_attr_set(iciptr,attr_name, value)

此核心函数的作用是为给定ICI某属性赋值，其参数说明如表2-22所示。

表2-22  op_ici_attr_set ()函数的参数说明

参数	类型	描   述
iciptr	Ici*	指向给定ICI的指针
attr_name	const char*	给定属性的名称
value	Vartype*	为给定属性所赋的值

1）返回值

Compcode­——表示ICI属性值是否成功修改的完成代码，如果发生可恢复错误，则返回OPC_COMPCODE_FAILURE。

2）详解

给定的属性名必须是ICI引用的格式中定义过的属性。通过该函数所赋的值将覆盖之前分配的值，而任何具有该ICI指针的进程都可访问新的属性值。

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

3）目的

该核心函数提供了进程中设置ICI内容并与其他进程进行通信的机制。新创建的ICI和已经发送到目的进程的ICI都可以进行属性设置。ICI通过强制中断来执行双向通信，这样初始进程就可立即获取结果。

4）错误

Program Abort：分段错误（由无效ICI指针、畸形ICI数据结构或声明出错的value_ptr参数引起）

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

Recoverable Error：属性名称在ICI格式中不可识别

5）相关函数

采用 op_ici_attr_get()获取ICI属性值。

采用op_ici_create()创建ICI。

采用 op_ici_install()建立一个与输出中断相关的ICI。

采用 op_ici_attr_exists()确定在ICI格式中是否存在某属性。

 

5. op_ici_install(iciptr)

此核心函数的作用是建立一个ICI，使其自动与调用进程预设的输出中断相关联，其参数说明如表2-23所示。

表2-23  op_ici_install ()函数的参数说明

参数	类型	描   述
iciptr	Ici*	指向给定ICI的指针

1）返回值

Ici*——建立的ICI，如果为空则返回 OPC_NIL。

2）详解

任何时候，最多只能为一个进程建立一个ICI。队列/处理器模块中的进程各自维持自己建立的ICI。建立ICI将通知仿真内核所有调用进程预设中断都应标记给定ICI的指针，这使得很多预设中断不需要打标记并创建一个新的ICI就可自动与ICI关联。

在中断预设到中断传递这段时间内，不管ICI发生什么变化（包括修改ICI内容或销毁ICI），预设中断都将始终维持与ICI的关联。在这种情况下，进程在收取中断时可能还将收到其他额外信息。为了避免这种情况，通常发送进程为每个中断都创建并建立一个ICI，而接收进程就应当担负起销毁进程的责任。

即使处理中断并不需要与之相关的ICI，但将ICI与中断保持关联也不会产生什么坏处，因此并没有显式提供解除建立ICI的函数。直到需将输出中断与另一个ICI关联时，才需要解除建立的当前ICI。不过通过将常量OPC_NIL传递给参数iciptr，可以用来解除ICI的建立，从而阻止与输出中断的关联。

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

3）目的

该核心函数提供了一种将预设ICI与输出中断相关联的机制。每个进程都维持一个指向被建立ICI的内部指针，则建立的ICI在非强制状态及多处理机调用中都是有效的。

4）错误

Program Abort：分段错误（由无效ICI指针或畸形ICI数据结构引起）

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

5）相关函数

采用op_ici_create()创建ICI。

采用op_ici_attr_get()获取ICI属性值。

采用op_ici_attr_set()设置ICI属性值。