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属性值。