当前位置:首页 >> 计算机硬件及网络 >>

citect函数


?
?? ??

?

v7.10

技术参考

?? ?? ??

November 2008 ?

法律声明
免责条款
Schneider Electric SA 不对本手册以及法律所允许的最大延伸做任何陈述或担保,将其因违反任何可能默示的 保证之责任,明确限制为对本手册予以更换。此外,Schneider Electric SA 保留在不承担任何通知义务的情况 下随时修改此出版物的权利。

版权
? Copyright 2008 Schneider Electric SA 保留所有权利。

商标
Schneider Electric SA 已经尽最大努力提供了在本手册中提及的有关公司名称、产品和服务的商标信息。 Citect、CitectHMI 和 CitectSCADA 是 Citect Pty.Ltd. 的注册商标。 IBM、IBM PC 和 IBM PC AT 是国际商业机器有限公司的注册商标。 MS-DOS、Windows、Windows NT、Microsoft 和 Excel 是 Microsoft Corporation 在美国和/或其他国家/地 区的注册商标或商标。 DigiBoard、PC/Xi 和 Com/Xi 是 Digi International Inc. 的商标。 Novell、Netware 和 Netware Lite 是 是 Novell, Inc. 在美国和其他国家的注册商标或商标。 dBASE 是 dataBased Intelligence, Inc. 的商标。 本文档中提及的其他商标和产品都是其相应所有者的商标或注册商标。

一般声明
本手册中使用的一些产品名称仅用于识别的目的,它们可能是其相应公司的商标。 November 2008 版,适用于 Vijeo Citect 版本 v7.10 手册修订版本 v7.10。

请注意
只有合格的技术人员才能安装、操作、维修和维护电气设备。Schneider Electric SA 对使用本材料所产生的任 何后果概不负责。? 2008 Schneider Electric SA。保留所有权利。

有效性注意事项
本文档供负责实施、操作和维护所述产品的合格技术人员使用。它包含产品正确使用所必需的信息。尽管如 此,对于希望更“高级”使用我们产品的技术人员,可能会发现很有必要咨询我们离您最近的分销商,以便获取 其他信息。 本文档的内容不是合同规定的保修条款,不得将其解释成保修合同条款的延伸或限制。

有关更多信息,请联系您本地的 Schneider Electric 代表。

内容
法律声明 ............................................................................... 2

技术参考 .............................................................................. 6
Chapter: 1 参数 ................................................................. 7
参数使用规则 ..........................................................................7 在网络中使用参数 .................................................................8 参数对话框 ..............................................................................8 参数属性 ......................................................................9

Chapter: 2

Citect.ini 文件参数 ...................................... 10
参数语法 ....................................................................10 设置参数值 ................................................................11 参数优先级 ................................................................13 分级参数 ....................................................................14 citect.ini 中的注释 ......................................................15

Chapter: 3

参考信息 ...................................................... 17
规格 .........................................................................................17 图形 .............................................................................17 I/O 设备数据类型......................................................19 保留 AN.......................................................................19 预定义模板 ................................................................21 预定义命令 ................................................................23 预定义字符集 ...........................................................25 预定义字体 ................................................................25 预定义设备 ................................................................27 预定义Cicode文件.....................................................28 预定义颜色名称和代码 ..........................................29 预定义键盘键代码...................................................30

3

Contents

预定义标签 ................................................................36 ASCII/ANSI 字符代码列表........................................44 格式字段.................................................................................54 报警显示字段 ...........................................................54 报警汇总字段 ...........................................................57 使用命令字段 ........................................................................58 错误消息.................................................................................59 协议普通错误 ...........................................................60 一般驱动程序错误...................................................63 协议特定错误 ...........................................................65 标准驱动程序错误...................................................68

Chapter: 4

CtAPI 函数 .................................................... 72
I/O 点数 ...................................................................................72 CtAPI 同步操作 ......................................................................73 使用 CTAPI 函数读取数据 ..................................................74 I/O 标签接口 ..............................................................74 标签函数 ....................................................................74 列表函数 ....................................................................75 数组支持 ....................................................................75 读取数字量数组时位移 ..........................................75 来自 Vijeo Citect 或 Vijeo Citect 驱动程序的 CTAPI ...........75 错误代码.................................................................................76 调试跟踪.................................................................................77 函数参考.................................................................................77

Chapter: 5

CSV_Include 参考 ...................................... 127
CSV_Include 参数 .................................................................127 [报警] 区域参数 ...................................................................127 [MultiMonitors] 参数 ...............................................................129 [Page] 参数 ............................................................................131 [Navigation] 参数 ...................................................................131 [TrendX] 参数.........................................................................136 [Privilege] 参数.......................................................................137 CSV_Include 函数 .................................................................138

Chapter: 6

图形编辑器自动化接口 .......................... 230
错误处理...............................................................................231 自动化事件 ..........................................................................232 函数分类...............................................................................232 排列和定位函数 .................................................................233

4

Contents

事件函数...............................................................................238 PasteGenie.................................................................239 PasteSymbol ..............................................................240 特定函数...............................................................................241 可见 ...........................................................................241 动态属性函数 ......................................................................242 PropertiesInputTouchGet ...........................................264 PropertiesInputTouchPut............................................265 PropertiesShowDialog ................................................266 PropertiesSymbolSetGet ............................................266 PropertiesSymbolSetPut ............................................267 PropertiesTransformationGet .....................................268 PropertiesTransformationPut......................................269 库对象函数 ..........................................................................278 其它函数...............................................................................288 对象绘制与属性函数.........................................................290 对象函数...............................................................................334 画面函数...............................................................................336 页面属性函数 ......................................................................356 工程函数...............................................................................367 文本属性函数 ......................................................................376

Chapter: 7

常见问题 .................................................... 384
画面 .......................................................................................384 图形 .......................................................................................385 运行时 ...................................................................................385 趋势 .......................................................................................386 控制 .......................................................................................387 报警 .......................................................................................387 其它 .......................................................................................388

词汇表 ................................................................................ 391 索引 .................................................................................... 422

5

Contents

技术参考
本节包含以下技术参考信息和 Vijeo Citect 词汇表: Citect.ini 文件参数 Vijeo Citect 参考信息 CtAPI 函数 图形编辑器的自动化 词汇表

6

Chapter: 1

参数

参数决定每台 Vijeo Citect 计算机在 Vijeo Citect 配置和运行时环境中的运行方式。例如, 某个参数允许用户在 Citect 工程编辑器中对工具栏进行显示或隐藏,某个参数决定了主报 表服务器以及冗余报表服务器是否在运行期间互相发送状态信号。 用户可以在下列数据库或文件中设置运行参数: ? 工程数据库。 ? 从 v7.10 起,Vijeo Citect 预定将 Citect.ini 文件存放在安装期间选择的 Vijeo Citect 用 户和数据文件夹的 config 文件夹中。如果在该位置未找到文件,它将不搜索其他位置 而将返回一个错误。如果需要将 INI 文件存储在其他位置,应在启动 citect32.exe 和 ctexplor.exe 时在命令行中指定其路径。有关详细信息,请参见 文本编辑器。 ? 工程数据库和 citect.ini 文件。

参数使用规则
使用参数时必须遵守以下规则: ? 在 citect.ini 文件中设置的参数优先于在工程数据库中设置的参数。 ? 如果在工程数据库中设置或更改参数,则必须在使用参数设置之前重新编译该工程。 ? 某些 citect.ini 文件参数要求使用之前重新启动 Vijeo Citect,在应用到的进程重新启 动后会使用其它参数。例如,警报服务器的 Events 参数将在重新启动特定警报服务器 后使用。 ? 在数据库中设置的参数对于特定 Vijeo Citect 工程为本地参数。在 citect.ini 文件中设 置的参数应用到所有 Vijeo Citect 工程(如果要使用多个 Vijeo Citect 系统)。 如何在工程数据库中设置参数: 1. 2. 3. 4. 5. 选择系统 | 参数。 输入参数的部件名称。 输入参数的名称。 输入参数的值。 将记录添加到数据库。

如何在本地 citect.ini 文件中设置参数: 1. 在帮助中查找参数。 2. 使用按钮(缺省值下方)编辑参数值。 注意:参数的当前值显示在对话框中。(如果对话框空白,则参数将被设置为缺省参数 值) 或者 3. 使用文本编辑器编辑 citect.ini 文件。

7

Chapter: 1 参数

4. 按以下格式输入参数:
[SECTION NAME] Parameter=<value>

在网络中使用参数
如果在网络中使用 Vijeo Citect,则可以使用全局、本地(对每台服务器和客户机为本地) 或既是全局又是本地的参数。在工程数据库中设置的任何参数都会应用到所有客户机,除 非也在控制客户机的 citect.ini 中设置了参数。本地 citect.ini 文件中设置的参数值优先 于仅用于该客户机的工程数据库。例如:

此处,参数(参数 x)在工程数据库(在文件服务器中)中设置为参数值 n。系统运行时, 此参数值 (n) 会应用到报警服务器以及两种客户端。相同的参数在 I/O 服务器和趋势服务 器设置为不同的参数值(在各自 citect.ini 文件中本地设置)。系统运行时,I/O 服务器 使用参数值 p,趋势服务器使用参数值 m。

参数对话框
可以使用“参数”对话框为参数指定属性。

8

Chapter: 1 参数

参数属性
参数具有下列属性: 部件名称 参数所在的部分。输入一个不超过 48 个字符的值。 名称 要为其定义值的参数的名称。输入一个不超过 32 个字符的值。 参数值 该参数的值。输入一个不超过 254 个字符的值。 注释 任何有用的注释。输入一个不超过 48 个字符的值。

9

Chapter: 2

Citect.ini 文件参数

参数概述 Vijeo Citect 有一个用来配置工程的可操作设置以及每台计算机如何连接到 Vijeo Citect 网 络的全面参数集。 用户可以在下列数据库或文件中设置运行参数: ? 工程数据库 在工程数据库中设置的参数是属于特定 Vijeo Citect 工程局部的。 ? citect.ini 文件 在 citect.ini 文件中设置的参数适用于运行在 citect.ini 文件所在机器上的所有 Vijeo Citect 工程。 本章包括下列主题: ? 参数语法 citect.ini 文件的语法。 ? 设置参数值 提供了在 Vijeo Citect 中设置参数值的各种工具。 ? 参数优先级 在 citect.ini 文件及参数数据库中设置值时使用参数值的规则概括。 ? 分级参数 如何很好地调整特定集群或服务器过程的参数设置。 ? citect.ini 中的注释 如何将注释添加到 citect.ini 文件。 要获取所有系统参数的完整列表,请参阅“参数”帮助文件。

参数语法
参数根据其用途分为几个部分。
citect.ini

文件中用来定义一个部分的语法如下:

[Section Name] <parameter name1> = <parameter value1> <parameter name2> = <parameter value2> <parameter nameX> = <parameter valueX>

例如:
[Alarm] SavePeriod = 600

10

Chapter: 2 Citect.ini 文件参数

SaveSecondary = ScanTime = 500

参数的最大长度为 254 个字符。 与服务器组件(报警、趋势、报表、IO 服务器)相关的部分还支持分级继承,这样就可以 很好地对参数进行调整,使其适合集群或服务器组件级别。所使用的语法如下:
[Section Name.ClusterName.ServerName] <parameter name1> = <parameter value1> <parameter name2> = <parameter value2> <parameter nameX> = <parameter valueX>

例如:
[Alarm.Cluster1.Server1] SavePeriod = 600 ScanTime = 500

有关详细信息,请参见 分级参数。

设置参数值

不希望的设备操作 - 无论什么情况,请勿更改或删除任何隐含的 citect.ini 参数。 - 在删除 citect.ini 文件的区段之前,请确认不会删除任何隐含参数。 忽视这些说明可能导致死亡、严重人身伤害或设备损坏。 注意: 有关隐含功能的信息,始终应咨询 Citect 支持人员。

在 Vijeo Citect 中创建或编辑参数值有多种方法: ? Citect 工程编辑器 用于在工程数据库中创建或更改值。 ? 计算机设置向导 用于设置每台机器上的基本及常用 citect.ini 参数。此向导会通过一系列页面引导用户 提供设置参数值所需的信息。 ? 计算机设置编辑器 用于创建或修改 citect.ini 文件中的参数。此工具通过将图形界面与上下文相关帮助参 考相结合,为用户提供了一种快速可靠的机制来设置特定参数的值。 ? 文本编辑器

11

Chapter: 2 Citect.ini 文件参数

文本编辑器可用来修改 citect.ini 文件,由于存在系统配置包含错误的风险,因此不建 议采用此方法。 如果设置(或更改)citect.ini 文件中的参数,则必须在使用新参数设置之前重新启动 Vijeo Citect。在以规则的时间间隔读取 citect.ini 参数并且可以在运行期间进行更改时, 此规则有一些例外情况。如果是这种情况,参数会相应地进行记录。 Citect 工程编辑器 在工程数据库中创建或更改参数唯一可用的方法是使用 Citect 工程编辑器。 在工程数据库中设置参数: 1. 2. 3. 4. 5. 从系统菜单中,选择参数以调出“参数”对话框。 输入参数的部件名称(不超过 16 个字符)。 输入参数的名称(不超过 16 个字符)。 输入参数的值(不超过 254 个字符)。 将该记录添加到数据库。

注意:要定位现有某个参数,请使用滚动条(在窗体右侧)在每条参数记录之间移动。记 录号显示在窗体的左下角。 如果在工程数据库中设置(或更改)参数,则使用新的参数设置之前,必须重新编译工 程。 计算机设置向导 计算机设置向导为用户提供了简单的界面,用于配置基本和常用的系统参数。此向导通过 一系列画面引导用户完成设置步骤: ? 利用存储在工程数据库中的配置向用户提供上下文信息; ? 使用户无需理解 citect.ini 文件或参数的语法; ? 修改其行为以反应之前在此向导中设置的任何相关值。 该向导在对运行 Vijeo Citect 的机器进行初始设置时使用,日后可以在机器上重新使用它来 修改参数设置。通过向导界面从用户处收集来的参数值将被写入本地 citect.ini 文件。 有关详细信息,请参见“使用计算机设置向导”。 计算机设置编辑器 计算机设置编辑器向用户提供了一个用于配置 citect.ini 参数的图形接口,这使其成为可 以快速、可靠地查找和更改特定参数值的工具。编辑器包括: ? 一个图形接口,将 citect.ini 文件中的参数显示为每部分包含一个节点的可扩展树; ? 所有 citect.ini 参数的内置帮助参考; ? 在两个单独 citect.ini 文件间生成比较报表的能力; ? 针对 citect.ini 文件生成分析报表,以检查参数值有效性的能力。

12

Chapter: 2 Citect.ini 文件参数

有关计算机设置编辑器使用方法的说明,请参见计算机设置编辑器中帮助菜单下的计算机 设置编辑器帮助。 注意:如果计算机设置编辑器是使用 等级参数在组件或服务器级配置的,则不能将其用于 维护或设置服务器参数。 文本编辑器
citect.ini

文件是存储 Vijeo Citect 运行参数的文本文件。安装期间,此文件的一个默认版 本被复制到安装时选中的 Vijeo Citectv7.10 用户和数据文件夹内的 config 文件夹中。启 动时,Vijeo Citect 读取值并确定其运行方式。

从 v7.10 起,Vijeo Citect 预定将 Citect.ini 文件存放在安装期间选择的 Vijeo Citectv7.10 用户和数据文件夹的 config 文件夹中。如果在该位置未找到文件,它将不搜索其他位置 而将返回一个错误。如果需要将 INI 文件存储在其他位置,应在启动 citect32.exe 和 ctexplor.exe 时在命令行中指定其路径。 注意:调用 Vijeo Citect 浏览器或 Citect32 Runtime 时,可以使用 -i"file_path.INI" 选项 更改 citect.ini 文件的文件名和位置。 如何在本地 citect.ini 文件中设置参数: 1. 使用文本编辑器打开 citect.ini 文件。 2. 按以下格式输入参数:
[SECTION NAME] Parameter=<value>

3. 将更改保存到 citect.ini 文件。

参数优先级
在同时于工程数据库和 citect.ini 文件中设置某个参数的计算机上,该机器将使用 citect.ini 中包含的值。 例如,在下图中,parameterX 的工程值(存储在工程数据库中)为 n。此值将用于除 I/O 服务器和趋势服务器的全部服务器和客户机,而 I/O 服务器和趋势服务器均使用在它们本 地的 citect.ini 文件中设置的值(分别为 p 和 m)。

13

Chapter: 2 Citect.ini 文件参数

因此,应该在可以集中管理和控制的工程数据库中定义对工程来说是全局的,并且将应用 于运行工程的大多数服务器的参数。然后,可通过修改例外所应用计算机上的 citect.ini 文件来管理此全局值的例外。 对于没有在工程数据库或 citect.ini 文件中设置某个参数的情况,系统将使用该参数的缺 省值。

分级参数
利用 Vijeo Citect 支持集群和在一台机器上运行多个同一类型服务器的功能,有时需要将服 务器组件参数(报警、报表、趋势和 IOServer)调整至比机器层更细的层次。因此,这些 参数是可以在多个层次上实现的分级参数。 ? 组建类型层 最宽的范围,此参数值将应用于所有服务器类型实例。 ? 集群层 此参数值将应用于在指定集群内运行的所有服务器实例。 ? 服务器层 此参数值将应用于在指定机器上的指定集群内运行的所有服务器实例。 这些参数支持分级继承,即参数将: 1. 应用在服务器层为其设置的值; 2. 如果未指定此值,应用在集群层为其设置的值; 3. 如果未指定此值,应用在组件层为其设置的值; 4. 如果为指定此值,应用该参数的缺省值。 范例 以下 citect.ini file 被用于 Server1 和 Server2(二者都位于 Cluster1 中),以及 Server3 和 Server4(二者都位于 Cluster2 中)。

14

Chapter: 2 Citect.ini 文件参数

[Alarm]SavePeriod = 500 [Alarm.Cluster1]SavePeriod = 600 [Alarm.Cluster1.Server1]SavePeriod = 1000

下图对此进行了说明。

在 [Alarm]SavePeriod 内应用于每一服务器的值如下所示:

集群名称 Cluster1 Cluster1 Cluster2 Cluster2

计算机名 Server1 Server2 Server3 Server4

SavePeriod 值 1000 600 500 500

注意:可以在参数数据库中设置分级参数。这种情况下,将优先应用正常规则。有关详细 信息,请参见 参数优先级。

citect.ini 中的注释
可以使用以下特殊字符将注释置于 citect.ini 文件中: ? 在要添加注释的新行开头使用“#”,其后添加注释文本。注释应与以下 INI 元素(段 或参数)相关。评论中不能包含等于号。 ? 在参数的开头使用“!”表明该参数已被禁止,应用的是默认值。 注意:所有含有“=”的行都将被视为参数,无论该行以什么字符开头。 例如:

15

Chapter: 2 Citect.ini 文件参数

[LAN] #Disable Networking Disable=1

16

Chapter: 3
规格

参考信息

本节包含 Vijeo Citect 的参考信息,包括:

格式字段 错误消息

规格
本节定义 Vijeo Citect 规格的参考信息。 ? 图形 ? 工程 ? I/O 设备数据类型 ? 保留的 AN ? 预定义模板 ? 预定义命令 ? 预定义字符集 ? 预定义字体 ? 预定义设备 ? 预定义 Cicode 文件 ? 预定义颜色名称和代码 ? 预定义键盘键代码 ? 预定义标签 ? ASCII/ANSI 字符代码列表

图形
下表定义了 Vijeo Citect 图形规格。

高分辩率颜色显示 调色板中的颜色 可从调色板中选择的用户可定义的颜色 自由格式的图形/显示画面 每个画面上的对象动点 (AN) 数 屏幕更新时间

VGA、SVGA、XGA、SXGA(任何分辩率) 255 1680 万 65000* 32000 500 毫秒(参见注释)

17

Chapter: 3 参考信息

注意:屏幕更新时间取决于使用的 I/O 设备协议和您的系统设计。最低的更新速度为 1 毫 秒,仅在 PLC 能尽可能快地提供数据时实现。Vijeo Citect 通过按需读取和动态优化保持 尽可能快的屏幕更新速度。这些技术使 Vijeo Citect 可以只从 PLC 读取所需数据,充分利 用了 I/O 设备的通信通道。实际安装的具有 100,000 个点的系统提供的性能测试可保持 400 毫秒的屏幕更新速度。

工程
下表定义 Vijeo Citect 工程规格:

配置工程数 在 Vijeo Citect 中定义的变量数

1022* 4,194,303 (但是建议的最大数为 500,000) 重要的:最大数取决于变量的位长。例如,一个 32 位的数字量可以将可能的变 量数减少 32(即如果工程中只包括 32 位的数字量,最多可以有 131,072 个)。 数字量的位的大小取决于使用的驱动。如果没有对驱动设置位的大小,那么它的 缺省值为 16。

包含工程数 同时登录的用户 报表数 报警监视的 I/O 设备地址的数目 历史趋势数 显示于同一图上趋势的数目 报警数 显示于同一页面上趋势的数目 用户函数的数目 可提供的标准内置函数的数目 系统的操作员命令的数目 与 Vijeo Citect 连接的 I/O 设备的 数目 同时多协议的数目 区域的数目

240 (包括包含工程) 250* 1000* 150000* 32000* 16* 每个报警类型 65,535 个 16000 4500* 700 3000* 16383

4095 255

18

Chapter: 3 参考信息

报警类别的数目 最大的多任务线程

16376 512

*对这些值并没有实际的限制;它们只是最大的建议值。但是,超过此值可能影响到趋势服 务器的性能(CPU 装载)和客户端(显示过程分析器)的 CPU 装载。

I/O 设备数据类型
下表显示数据类型、大小和允许的参数值。

数据类型 BCD 字节 数字量 整型 无符号整型 长整型 长型 BCG 浮点(实型) 字符串

大小 2 字节 1 字节 1 位或 1 字节 2 字节

允许的参数值 0 到 9,999 0 到 255 0或1 -32,768 到 32,767

4 字节 4 字节 4 字节 256 字节(标签和 Cicode 函数) 128 字节(全局 Cicode 变量) ASCII(空结尾)

保留 AN
下表描述了所有的保留 AN:

AN 1

描述 键盘输入 行 提示符行

注释 操作员的键盘输入回显(显示)的地方。

2

提示符行用于向操作员传递重要的消息。可以使用 Prompt() 函数显示提示符帮助操作员进行 处理,或者使用 DspError() 显示报警信息。必须使用 Cicode 函数来显示提示符消息。

19

Chapter: 3 参考信息

AN

描述

注释

下列 AN 只在第 2.xx 版类型的模板(或者从 2.xx 版升级的页面)中保留: 3 4 5 保留 保留 未确认的 报警 硬件报警 如果一个报警未被确认,就会显示“未确认的报警”。然后就可以选择一个报警画面来显示报警 的详细内容。 如果 Vijeo Citect 发现了一个硬件报警,就会显示“硬件报警”消息。然后就可以选择一个报警 画面来显示报警的详细内容。 如果报警被禁用了,就会显示“禁用的报警”。然后就可以选择一个报警画面来显示报警的详细 内容。

6

7

禁止的报 警 保留 时间

8 9

显示当前的系统时间。要设定要显示的时间格式,请使用 Windows 主程序组中的控制面板, 或者设定一个 Vijeo Citect 参数。 显示当前的系统日期。要设定要显示的日期格式,请使用 Windows 主程序组中的控制面板, 或者设定一个 Vijeo Citect 参数。 最后一个活动报警显示的地方

10

日期

11

最后一个 报警 画面标题 画面名称 命令帮助 按钮 按钮 按钮 上一个画 面按钮 后一画面 按钮 前一画面 按钮

12 13 14 15 16 17 18

显示图形画面标题的地方。 显示图形画面名称的地方。 与按钮或动画对象相关的帮助文件显示的地方。 从属于画面的按钮。 从属于画面的按钮。 从属于画面的按钮。 此按钮用于选择显示于当前画面之前的图形画面。

19

此按钮用于选择画面序列中的下一个图形画面。

20

此按钮用于选择画面序列中的前一个图形画面。

20

Chapter: 3 参考信息

预定义模板
以多种风格提供了以下模板。这些模板中的大多数已进行了完全配置,几乎不用进行自定 义即可用来创建页面。

模板名称 标准

描述 基本图形显示页面的模板。这个模板包括基本页面控制的按钮(例如显示 报警和菜单页面)以及一个用来绘制工厂布局的大空白区域,控制按钮 等。 完全空白的模板。使用此模板配置一个完整的页面。 用于创建简单菜单页面的模板。在您开发工程时,Vijeo Citect 会自动生 成一个菜单页面(基于此模板)。用户可以根据特定的需要修改菜单页面 以满足其特定需要。 创建选择菜单页面的模板(以书的形式)。操作员可以通过点击相应的选 项标签在菜单页面中移动。要使用这些模板,向菜单页面添加按钮以根据 需要显示其它的图形页面。 用与模板同样的名称创建页面以避免多余的配置。如果页面没有链接,则可 以修改菜单以接受任意的页面名称。

空白 PageMenu

Book1Menu .. Book5Menu

Tab1Menu .. Tab6Menu

创建选择菜单页面的模板(以制表的形式)。操作员可以通过点击相应的 选项标签在菜单页面中移动。要使用这些模板,向菜单页面添加按钮以根 据需要显示其它的图形页面。 用与模板同样的名称创建页面以避免多余的配置。如果页面没有链接,则可 以修改菜单以接受任意的页面名称。

SingleTrend

通过一个趋势视窗创建趋势页面的模板。配置趋势笔有下列几种方法: 1. 双击此视窗。 2. 使用 PageTrend() 函数打开趋势笔,然后将趋势笔作为参数传入。 3. 在运行时手动选择笔(从页面) 可以通过周期或者周期事件类型的趋势变量标签配置单趋势页面。

DoubleTrend

通过两个趋势视窗创建趋势页面的模板。要对每一个视窗分别配置趋势笔, 双击视窗,或者在运行时手动选择笔(从页面)。向菜单页面添加一个按 钮以显示每一个趋势页面。 可以通过周期或者周期事件类型的趋势变量标签配置双趋势页面。

CompareTrend

用两个趋势视窗创建趋势页面的模板 - 其中的一个覆盖另一个。要对每一 个趋势配置趋势笔(每个趋势最多可配置 4 个),双击趋势视窗,或者在 运行时从页面手动选择笔。向菜单页面添加一个按钮以显示每一个趋势页 面。比较趋势页面可以通过周期或者周期事件类型的趋势变量标签配置。 通过一个事件趋势视窗创建趋势页面的模板。配置趋势笔有下列几种方 法: 1) 双击此视窗 2) 使用 PageTrend() 函数打开趋势笔,然后将趋势笔作为参数传入。 3) 在运行时手动选择笔(从页面)

EventTrend

21

Chapter: 3 参考信息

模板名称

描述 事件趋势页面只能通过事件类型的趋势变量标签配置。

ZoomTrend

用一个趋势视窗和一个缩放视窗创建趋势页面的模板。要配置趋势笔,请 双击这个视窗,或者在运行时从页面手动选择笔。 可以通过周期或者周期事件类型的趋势变量标签配置缩放趋势页面。

PopTrend

用来创建小的趋势页面以显示为一个快捷趋势的模板。要配置趋势笔,使 用 PageTrend() 函数打开趋势页面并将趋势笔作为参数传入,或在运行时 选择笔(从页面)。 快捷趋势页面可以通过周期或者周期事件类型的趋势变量标签来配置。

平均图表 范围图表 标准图表 SPCCPK

用两个平均视窗创建 SPC 页面的模板。 用一个平均和范围视窗模板创建 SPC 页面的模板。 用平均和标准偏移视窗创建 SPC 页面的模板。 创建 SPC 功能图表的模板。要配置趋势笔,双击此视窗,或在运行时从页 面手动选择笔。 SPCCPK 页面可以通过周期或者周期事件类型的趋势变量标签配置。

SPCPareto

创建 SPC Pareto 图表的模板。要配置变量标签(非趋势标签),双击视 窗。 用平均,范围和标准偏移视窗创建 SPC 控制图表的模板。要配置趋势笔, 双击此视窗,或在运行时从页面手动选择笔。 SPCXRSChart 页面可以通过周期或者周期事件类型的 SPC 变量标签配 置。

SPCXRSChart

EventSPCXRS

通过一个事件 SPCXRS 视窗创建趋势页面的模板。要配置趋势笔,双击此 视窗,或在运行时从页面手动选择笔。 EventSPCXRS 页面只能通过事件事件类型的 SPC 变量标签配置。

报警

创建报警显示页面的模板。必须创建一个基于此模板的名为“报警”的页面, 以使报警显示按钮(在其它页面如菜单页面上)运行正常。(报警显示按 钮调用 PageAlarm() 函数。)可以通过此模板直接创建“报警”页面(不加 修改),或者修改这个页面以满足用户的需要。 创建报警摘要页面的模板。必须创建一个基于此模板的名为“摘要”的页面, 以使报警显示按钮(在其它页面如菜单页面上)运行正常。(报警汇总按 钮调用 PageSummary() 函数。)可以通过此模板直接创建“摘要”页面 (不加修改),或者修改这个页面以满足用户的需要。 创建硬件报警页面的模板。必须创建一个基于此模板的名为“硬件”的页面, 以使报警显示按钮(在其它页面如菜单页面上)运行正常。(硬件报警按 钮调用 PageHardware() 函数。)可以通过此模板直接创建“硬件”页面 (不加修改),或者修改这个页面以满足用户的需要。 创建禁用报警页面的模板。如果使用 PageDisabled() 函数,则必须基于 此模板创建一个的名为“禁用”的页面。可以通过此模板直接创建“禁用”页面

汇总

硬件

禁止

22

Chapter: 3 参考信息

模板名称

描述 (不加修改),或者修改这个页面以满足用户的需要。

文件

创建文件-至-屏幕显示页面的模板。可以使用此页面显示任何 ASCII 文件 (例如报表或其它信息)。如果使用 PageFile() 函数,则必须基于此模板 创建一个名为“文件”的页面。可以通过此模板直接创建“文件”页面(不加修 改),或者修改这个页面以满足用户的需要。 创建工厂设备的组的状态表页面的模板。 创建页面显示趋势统计表的模板。必须创建一个基于此模板的名为 “!TrendStats”的页面。当它从趋势视窗被调用时,它会显示在这个视窗中 用到的趋势笔的统计数据(例如最小、最大、平均等)。通过显示的 TrnPopStat 视窗,您还可以圈定一个趋势区域,该区域的统计数据将显示 出来。

GroupStatus TrnPopStat

预定义命令
本节介绍包含工程中预定义的系统键盘命令(系统键盘命令对计算机屏幕上显示的任何图 形画面均有效)。 ? 系统键盘命令数据库 ? 预定义键盘键码 ? 键盘键码数据库 系统键盘命令数据库 下表提供了与命令及其函数关联的键序列。

键序列 *BS DOWN PGDN PGUP RIGHT UP

命令 KeyBS() KeyDown() PagePrev() PageNext() KeyRight() KeyUp()

描述 退格 下移光标 显示上一页 显示下一页 右移光标 上移光标

通常,可以通过在工程中用相同的键序列配置新命令来覆盖预定义的命令。唯一不能覆盖 的是 *BS 命令,因为这个序列是用来删除命令行的最后一个键的热键。

23

Chapter: 3 参考信息

注意:不要修改包含工程。在重新安装 Vijeo Citect 或将其升级到新版本时,对包含工程进 行的更改会丢失。 预定义键盘键码 包含工程中预定义了下述键盘键码。可以在任何键顺序字段中使用这些键;例如,为对象 定义键盘命令。 键盘键码数据库 下表定义了键的名称、代码和描述。

键名称 BS DOWN ENTER LBUTTON_DN LBUTTON_UP LBUTTON_CMD_DN LBUTTON_CMD_UP LEFT MBUTTON_DN MBUTTON_UP PGDN PGUP RBUTTON_DN RBUTTON_UP RBUTTON_CMD_DN RBUTTON_CMD_UP RIGHT UP

键代码 KEY_BACKSPACE KEY_DOWN KEY_ENTER KEY_LBUTTON_DN KEY_LBUTTON_UP KEY_LBTN_CMD_DN KEY_LBTN_CMD_UP KEY_LEFT KEY_MBUTTON_DN KEY_MBUTTON_UP KEY_PGDN KEY_PGUP KEY_RBUTTON_DN KEY_RBUTTON_UP KEY_RBTN_CMD_DN KEY_RBTN_CMD_UP KEY_RIGHT KEY_UP

描述 回格键 光标向下 回车键 鼠标左键向下 鼠标左键向上 鼠标左键向下(命令光标) 鼠标左键向上(命令光标) 光标向左 鼠标中键向下 鼠标中键向上 下页键 上页键 鼠标右键向下 鼠标右键向上 鼠标右键向下(命令光标) 鼠标右键向上(命令光标) 光标向右 光标向上

24

Chapter: 3 参考信息

注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义字符集
下列字符集预定义为包含工程中的标签:

标签 DEFAULT_CHARSET SHIFTJIS_CHARSET HANGEUL_CHARSET GB2312_CHARSET CHINESEBIG5_CHARSET JOHAB_CHARSET HEBREW_CHARSET ARABIC_CHARSET GREEK_CHARSET TURKISH_CHARSET VIETNAMESE_CHARSET THAI_CHARSET EASTEUROPE_CHARSET RUSSIAN_CHARSET BALTIC_CHARSET

参数值 1 128 129 134 136 130 177 178 161 162 163 222 238 204 186

描述 使用缺省 Windows 字符集 日文字符集 韩文字符集 中文字符集 中文字符集

注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义字体
包含工程中预定义了下列字体:

25

Chapter: 3 参考信息

字体名称 AlmAccOffFont AlmAccOnFont AlmDisabledFont AlmUnAccOffFont AlmUnAccOnFont ButtonFont Casanova ControlLimits DefaultFont DisabledFont FontOP FontPV FontSP FontTune GraphBigFont GraphColour GraphColourBig GraphColourSmall GraphFont GraphSmallFont HardwareFont Pen1SpcFont Pen1TrendFont Pen2SpcFont Pen2TrendFont Pen3SpcFont

字体类型 Arial Arial Arial Arial Arial Arial Arial Times New Roman Courier New Arial Courier New Courier New Courier New Courier New Arial Arial Arial Courier New Arial Courier New Arial Courier Courier New Courier New Courier New Courier New

大小 10 10 10 10 10 10 -10 14 14 10 14 14 14 14 60 32 60 20 32 20 10 10 14 14 14 14

颜色 白 青 白 褐 黄 黑 黑 黑 白 白 浅青 浅绿 浅红 黄 黑 蓝 红 黑 黑 黑 浅红 白 浅绿 浅绿 黄 浅青

26

Chapter: 3 参考信息

字体名称 Pen3TrendFont Pen4SpcFont Pen4TrendFont Pen5TrendFont Pen6TrendFont Pen7TrendFont Pen8TrendFont PromptFont SpcFont TextFont TimeFont TrendFont TrendHistFont TrendSHistFont TrendSFont UnacceptedFont Vanuatu System TrendSCentreFont PopFont

字体类型 Courier New Courier New Courier New Courier New Courier New Courier New Courier New Arial Courier New Arial Arial Courier New Courier New Arial Arial Arial Arial Arial Arial Arial

大小 14 14 14 14 14 14 14 10 14 10 10 14 14 -10 -10 10 -9 10 -10 9

颜色 浅红 浅蓝 浅青 浅品红 白 浅蓝 灰 白 白 白 黑 白 黄 品红 黑 黄 黑 黑 黄 黑

可以通过向工程中添加新的相同名称的字体一个覆盖预定义字体。 注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义设备
本节介绍包含工程中预定义的设备。

27

Chapter: 3 参考信息

设备数据库 下表列出了 Vijeo Citect 支持的设备。

设备名称 ASCII_DEV PRINTER_DEV dBASE_DEV SQL_DEV AlarmDisk AlarmPrint KeyDisk KeyPrint Printer1 Printer2 SummaryPrint SummaryDisk _Trend Scratch

类型 0 1 2 4 0(ASCII 文件) 0(ASCII 文件) 0(ASCII 文件) 1(打印机) 1(打印机)LPT1: 1(打印机)LPT2: 0(ASCII 文件) 0(ASCII 文件) 3 (dBASE) 0(ASCII 文件)

描述 Ascii 设备号 打印机设备号 dBASE 设备号 SQL 设备号 缺省的报警记录文件 缺省的报警打印设备 缺省的键盘记录文件 缺省的键盘打印记录 打印机设备 1 打印机设备 2 缺省的报警摘要打印设备 缺省的报警摘要记录文件 趋势 RDB 设备 用于 DevModify 函数的设备

注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义Cicode文件
下列 Cicode 文件是包含工程的部分:

文件名 Citect.ci debug.ci

描述 通用工具函数 用户 Cicode 调试函数

28

Chapter: 3 参考信息

文件名 export.ci graph.ci info.ci numpad.ci page.ci pareto.ci spc.ci spcplus.ci statpop.ci tag.ci trend.ci trninfo.ci zoom.ci

描述 信息函数 趋势数据导出函数 信息函数 数字输入键区函数 图形画面工具函数 Pareto 图表函数 缺省的 SPC 函数 SPC 扩展函数 趋势统计函数 变量标签分配和操作函数 缺省的趋势函数 趋势信息收集函数 趋势缩放函数

注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义颜色名称和代码
十六种标准颜色可用于 Vijeo Citect 系统。它们已经在包含工程中预定义。应按名称引用这 些颜色,这样可以使它们更容易理解,无论在何处使用该代码值:

颜色标签 黑 蓝 绿 青 红

代码 0x000000 0x000080 0x008000 0x008080 0x800000

29

Chapter: 3 参考信息

颜色标签 品红 褐 灰 灰黑 浅蓝 浅绿 浅青 浅红 浅品红 黄 白 透明

代码 0x800080 0x808000 0xBFBFBF 0x7F7F7F 0x0000FF 0x00FF00 0x00FFFF 0xFF0000 0xFF00FF 0xFFFF00 0xFFFFFF 0XFF000000

注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义键盘键代码
Vijeo Citect 包含工程中预定义了下列有意义的键代码标签。当您定义键盘键时,可以将它 们作为键代码输入,因此不必记住与每个键相关联的十六进制值。

键代码(Vijeo Citect 标签) KEY_LBUTTON KEY_RBUTTON KEY_MBUTTON KEY_LBUTTON_UP KEY_RBUTTON_UP KEY_MBUTTON_UP

键代码(十六进制值) 0x0001 0x0002 0x0004 0x0201 0x0202 0x0204

键描述 鼠标左键 鼠标右键 鼠标中键 鼠标左键向上 鼠标右键向上 鼠标中键向上

30

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_LBUTTON_DBL KEY_RBUTTON_DBL KEY_MBUTTON_DBL KEY_LBUTTON_DN KEY_RBUTTON_DN KEY_MBUTTON_DN KEY_LF KEY_VT KEY_FF KEY_RETURN KEY_ENTER KEY_ESCAPE KEY_ESC KEY_DELETE KEY_PGUP KEY_PGDN KEY_END KEY_HOME KEY_LEFT KEY_UP KEY_RIGHT KEY_DOWN KEY_INSERT KEY_HELP KEY_F1 KEY_F2 KEY_F3

键代码(十六进制值) 0x0401 0x0402 0x0403 0x0801 0x0802 0x0804 0x000A 0x000B 0x000C 0x000D 0x000D 0x001B 0x001B 0x012E 0x0121 0x0122 0x0123 0x0124 0x0125 0x0126 0x0127 0x0128 0x012D 0x012F 0x0170 0x0171 0x0172

键描述 鼠标左键双击 鼠标右键双击 鼠标中键双击 鼠标左键向下 鼠标右键向下 鼠标中键向下 换行 垂直制表键 换页 回车 Enter(与上面相同) 退出 退出(与上面相同) Delete PageUp PageDown End Home 光标向左 光标向上 光标向右 光标向下 Insert Help F1 F2 F3

31

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_F4 KEY_F5 KEY_F6 KEY_F7 KEY_F8 KEY_F9 KEY_F10 KEY_F11 KEY_F12 KEY_F13 KEY_F14 KEY_F15 KEY_F16 KEY_F1_SHIFT KEY_F2_SHIFT KEY_F3_SHIFT KEY_F4_SHIFT KEY_F5_SHIFT KEY_F6_SHIFT KEY_F7_SHIFT KEY_F8_SHIFT KEY_F9_SHIFT KEY_F10_SHIFT KEY_F11_SHIFT KEY_F12_SHIFT KEY_F13_SHIFT KEY_F14_SHIFT

键代码(十六进制值) 0x0173 0x0174 0x0175 0x0176 0x0177 0x0178 0x0179 0x017A 0x017B 0x017C 0x017D 0x017E 0x017F 0x1170 0x1171 0x1172 0x1173 0x1174 0x1175 0x1176 0x1177 0x1178 0x1179 0x117A 0x117B 0x117C 0x117D

键描述 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 Shift F1 Shift F2 Shift F3 Shift F4 Shift F5 Shift F6 Shift F7 Shift F8 Shift F9 Shift 10 Shift F11 Shift F12 Shift F13 Shift F14

32

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_F15_SHIFT KEY_F16_SHIFT KEY_F1_CTRL KEY_F2_CTRL KEY_F3_CTRL KEY_F4_CTRL KEY_F5_CTRL KEY_F6_CTRL KEY_F7_CTRL KEY_F8_CTRL KEY_F9_CTRL KEY_F10_CTRL KEY_F11_CTRL KEY_F12_CTRL KEY_F13_CTRL KEY_F14_CTRL KEY_F15_CTRL KEY_F16_CTRL KEY_A_SHIFT KEY_B_SHIFT KEY_C_SHIFT KEY_D_SHIFT KEY_E_SHIFT KEY_F_SHIFT KEY_G_SHIFT KEY_H_SHIFT KEY_I_SHIFT

键代码(十六进制值) 0x117E 0x117F 0x2170 0x2171 0x2172 0x2173 0x2174 0x2175 0x2176 0x2177 0x2178 0x2179 0x217A 0x217B 0x217C 0x217D 0x217E 0x217F 0x1041 0x1042 0x1043 0x1044 0x1045 0x1046 0x1047 0x1048 0x1049

键描述 Shift F15 Shift F16 Ctrl F1 Ctrl F2 Ctrl F3 Ctrl F4 Ctrl F5 Ctrl F6 Ctrl F7 Ctrl F8 Ctrl F9 Ctrl F10 Ctrl F11 Ctrl F12 Ctrl F13 Ctrl F14 Ctrl F15 Ctrl F16 Shift A Shift B Shift C Shift D Shift E Shift F Shift G Shift H Shift I

33

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_J_SHIFT KEY_K_SHIFT KEY_L_SHIFT KEY_M_SHIFT KEY_N_SHIFT KEY_O_SHIFT KEY_P_SHIFT KEY_Q_SHIFT KEY_R_SHIFT KEY_S_SHIFT KEY_T_SHIFT KEY_U_SHIFT KEY_V_SHIFT KEY_W_SHIFT KEY_X_SHIFT KEY_Y_SHIFT KEY_Z_SHIFT KEY_A_CTRL KEY_B_CTRL KEY_C_CTRL KEY_D_CTRL KEY_E_CTRL KEY_F_CTRL KEY_G_CTRL KEY_H_CTRL KEY_I_CTRL KEY_J_CTRL

键代码(十六进制值) 0x104A 0x104B 0x104C 0x104D 0x104E 0x104F 0x1050 0x1051 0x1052 0x1053 0x1054 0x1055 0x1056 0x1057 0x1058 0x1059 0x105A 0x2041 0x2042 0x2043 0x2044 0x2045 0x2046 0x2047 0x2048 0x2049 0x204A

键描述 Shift J Shift K Shift L Shift M Shift N Shift O Shift P Shift Q Shift R Shift S Shift T Shift U Shift V Shift W Shift X Shift Y Shift Z Ctrl A Ctrl B Ctrl C Ctrl D Ctrl E Ctrl F Ctrl G Ctrl H Ctrl I Ctrl J

34

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_K_CTRL KEY_L_CTRL KEY_M_CTRL KEY_N_CTRL KEY_O_CTRL KEY_P_CTRL KEY_Q_CTRL KEY_R_CTRL KEY_S_CTRL KEY_T_CTRL KEY_U_CTRL KEY_V_CTRL KEY_W_CTRL KEY_X_CTRL KEY_Y_CTRL KEY_Z_CTRL KEY_A_ALT KEY_B_ALT KEY_C_ALT KEY_D_ALT KEY_E_ALT KEY_F_ALT KEY_G_ALT KEY_H_ALT KEY_I_ALT KEY_J_ALT KEY_K_ALT

键代码(十六进制值) 0x204B 0x204C 0x204D 0x204E 0x204F 0x2050 0x2051 0x2052 0x2053 0x2054 0x2055 0x2056 0x2057 0x2058 0x2059 0x205A 0x4041 0x4042 0x4043 0x4044 0x4045 0x4046 0x4047 0x4048 0x4049 0x404A 0x404B

键描述 Ctrl K Ctrl L Ctrl M Ctrl N Ctrl O Ctrl P Ctrl Q Ctrl R Ctrl S Ctrl T Ctrl U Ctrl V Ctrl W Ctrl X Ctrl Y Ctrl Z Alt A Alt B Alt C Alt D Alt E Alt F Alt G Alt H Alt I Alt J Alt K

35

Chapter: 3 参考信息

键代码(Vijeo Citect 标签) KEY_L_ALT KEY_M_ALT KEY_N_ALT KEY_O_ALT KEY_P_ALT KEY_Q_ALT KEY_R_ALT KEY_S_ALT KEY_T_ALT KEY_U_ALT KEY_V_ALT KEY_W_ALT KEY_X_ALT KEY_Y_ALT KEY_Z_ALT

键代码(十六进制值) 0x404C 0x404D 0x404E 0x404F 0x4050 0x4051 0x4052 0x4053 0x4054 0x4055 0x4056 0x4057 0x4058 0x4059 0x405A

键描述 Alt L Alt M Alt N Alt O Alt P Alt Q Alt R Alt S Alt T Alt U Alt V Alt W Alt X Alt Y Alt Z

要用以下键定义一个键: ? Shift 键,向键值中添加 0x1000。 ? Ctrl 键,向键值中添加 0x2000。 ? Alt 键,向键值中添加 0x4000。 上述键定义都是标准的 IBM 兼容键。 注意:请不要修改包含工程。当您重新安装或升级 Vijeo Citect 时,对包含工程的更改将会 丢失。

预定义标签
本节介绍在包含工程中预定义的标签。 标签数据库 下表定义在包含工程中预定义的名称和表达式。

36

Chapter: 3 参考信息

名称 @<edtsp.cii>

表达式 _ExecuteDTSPkg(sFile,s1,s2,s3, s4,s5,s6,s7,s8,s9,s10,s11) _ObjectServerInvoke(sp,sf,s1,s2, s3,s4,s5,s6,s7,s8,s9,s10) $1 $4 $6 $2 $3 $5 $0

注释 执行 DTS 包缺省值宏 命令 调用对象服务器函数

@<obsvinv.cii> __DATE__ __DB__ __FIELD__ __FILE__ __LINE__ __RECORD__ __TIME__ _BLANK_

编译日期 编译器数据库名 编译器域名 编译器文件名 编译器行数 编译器记录数 编译时间 NULL 定义

AlarmDsp(hAn,count,type=1,scope=0) AlarmDspLast(hAn,count=1,type=1)

_AlarmDsp(hAn,count,type,scope) _AlarmDsp(hAn,count,type,1) _AlarmQueryFirstRec (hCat,nType,hArea,0) _AlarmQueryFirstRec (hPri,nType,hArea,1) _AlarmGetFieldRec (nRID,sField,nVER) _AlarmQueryNextRec (hRec,hCat,nType,hArea,0) _AlarmQueryNextRec (hRec,hPri,nType,hArea,1) _AlarmSetQuery(hAN,sQF,sArg)

显示报警列表

显示最后一个警报。 通过区域获得报警 Cat Rec 通过区域获得报警 Pri Rec 报警获得域记录宏

AlarmFirstCatRec(hCat,nType,hArea=1) AlarmFirstPriRec(hPri,nType,hArea=1)

AlarmGetFieldRec(nRID,sField,nVER=0 ) AlarmNextCatRec(hRec,hCat,nType,hA rea=-1) AlarmNextPriRec(hRec,hPri,nType,hAr ea=-1) AlarmSetQuery(hAN,sQF,sArg="")

通过区域获得报警 Cat Rec 通过区域获得报警 Pri Rec

为定义的用户设置报警 过滤器函数 显示模式 2 阵列模式下的动画符号

ANIMATE ANM_ARRAY

2 16

37

Chapter: 3 参考信息

名称 ANSI_CHARSET Arg1 Arg2 Arg3 Arg4 Arg5 Arg6 Arg7 Arg8 ArgValue1 Assert(arg) BAD_HANDLE BORDER BORDER_3D

表达式 0 GetGlbStr(0) GetGlbStr(1) GetGlbStr(2) GetGlbStr(3) GetGlbStr(4) GetGlbStr(5) GetGlbStr(6) GetGlbStr(7) StrToValue(Arg1) IF NOT (arg) THEN _Assert(#arg, __FILE__, __LINE__); END -1 2 1 _CreateControlObject (sCls,sName,x1,y1,x2,y2, sEventCls) _TimeSub(time,3) _TimeSub(time,10) _TimeSub(time,5) _TimeSub(time,4) _DDERead (sApp,sTopic,sItem,bAdvise) 000 _DevClose(hDev,iMode) DevSeek(hDev,0)

注释 ANSI 字符集 键盘参数 1 键盘参数 2 键盘参数 3 键盘参数 4 键盘参数 5 键盘参数 6 键盘参数 7 键盘参数 8 获得参数 1 的值 处理声明

不良句柄 仅边界 3D 透明按钮 CreateControlObject 缺省事件类型

CreateControlObject(sCls,sName,x1,y 1,x2,y2,sEventCls="") DateDay(time) DateDayMonth(time) DateMonth(time) DateWeekDay(time)

从时间中获得日 获得月的最后一天 从时间中获得月 从时间中获得工作日 具有可选建议的 DDE 读取

DDERead(sApp,sTopic,sItem,bAdvise= 1) DELETE_ANM DevClose(hDev,iMode=0) DevFirst(hDev)

删除动画 设备关闭,用户模式 偏移量=0 的 DevSeek 设备打开,共享模式

DevOpen(sName,iMode=0)

_DevOpen(sName,iMode)

38

Chapter: 3 参考信息

名称 DspAnCreateControlObject(hAn,sCls,w ,h,sEventCls="")

表达式 _DspAnCreateControlObject (hAn,sCls,w,h,sEventCls)

注释 DspAnCreateControl Object 缺省事件类 显示按钮

DspButton(hAn,UK=0,sText,hFont=0, nW=0, nH=0,DK=0,RK=0,nM=0) DspButtonFn(hAn,UF=0,sText,hFont= 0, nW=0,nH=0,DF=0,RF=0,nM=0) DspChart(hAn,sTrn,v1,v2=0,v3=0,v4 =0, v5=0,v6=0,v7=0,v8=0) DspGetAnFromPoint(x,y,hPrevAn=0)

_DspButton(hAn,UK,sText, hFont,nW,nH,DK,RK,nM)

_DspButtonFn(hAn,UF,sText, hFont,nW,nH,DF,RF,nM)

显示按钮

_DspChart(hAn,sTrn,v1,v2, v3,v4,v5,v6,v7,v8)

趋势显示宏

_DspGetAnFromPoint (x,y,hPrevAn) _DspSetTooltipFont (sName,nSize,sAttribs) _DspSym(hAn,sSym,mode) _DspSymAnm (hAn,s1,s2,s3,s4,s5,s6,s7,s8,0,"")

可以获得一个点上的所 有 AN 工具提示字体宏

DspSetTooltipFont(sName,nSize=12,s Attribs="") DspSym(hAn,sSym,mode=0)

显示符号 显示多个符号

DspSymAnm(hAn,s1,s2=0,s3=0,s4=0 , s5=0,s6=0,s7=0,s8=0) DspSymAnmEx(hAn,mode,s1,s2=0,s3 =0,s4=0, s5=0,s6=0,s7=0,s8=0,s9=0) DspTrend(hAn,sTrn,v1=0,v2=0,v3=0, v4=0, v5=0,v6=0,v7=0,v8=0) DspTrendInfo(sName,nType,hAn=-1) ErrGetHw(nDevice,nType=-1) ErrSetHw(nDevice,nError,nType=-1) EVEN_P Exec(sText,mode=1)

_DspSymAnm(hAn,s1,s2,s3,s4, s5,s6,s7,s8,mode,s9)

具有模式的 DspSymAnm

_DspTrend(hAn,sTrn,v1,v2,v3, v4,v5,v6,v7,v8)

趋势显示宏

_DspTrendInfo (sName,nType,hAn) _ErrGetHw(nDevice,nType) _ErrSetHw(nDevice,nError,nType) 2 _Exec(sText,mode)

获得趋势信息,带 AN

获得硬件错误宏 设置硬件错误宏 事件奇偶校验 执行程序,缺省为正常

39

Chapter: 3 参考信息

名称 FALSE FlashColourState()

表达式 0 StrToInt(PageInfo(18)) _FormComboBox (Col,Row,Width,Height,sBuf,mode) _FormGroupBox (Col,Row,Width,Height,sText) _FormListBox (Col,Row,Width,Height,sBuf,mode) _FormSaveAsFile (sTitle,sDefault,sFilters,sDefExt) ((PackedRGB / 65536) BITAND 255)

注释 布尔值 False 闪烁颜色状态为布尔值 具有模式的表格组合框

FormComboBox(Col,Row,Width,Height ,sBuf,mode=0) FormGroupBox(Col,Row,Width,Height, sText="") FormListBox(Col,Row,Width,Height,sB uf,mode=0) FormSaveAsFile(sTitle,sDefault,sFilters ,sDefExt="") GetBlueValue(PackedRGB)

带文本的组框

具有模式的表格列表框

获得填充 RGB 颜色的 蓝色组件 获得填充 RGB 颜色的 绿色组件 获得填充 RGB 颜色的 红色组件 获得变量域数据 获得变量域数据(如果 已定义) 按 str 获得变量域数据 按 str 获得变量域数据 (如果已定义) 将整个按钮变灰 隐藏被变灰的对象 减弱或增强文本/符号的 灰色 减弱文本/符号的颜色 内嵌已定义 IF 宏 动画中周期为布尔值 通信中周期为布尔值

GetGreenValue(PackedRGB)

((PackedRGB / 256) BITAND 255)

GetRedValue(PackedRGB)

(PackedRGB BITAND 255)

GetVar(sTag,sField) GetVarDef(sTag,sField,sDefault)

$7 $10

GetVarStr(sTag,sField) GetVarStrDef(sTag,sField,sDefault)

$8 $11

GRAY_ALL GRAY_HIDE GRAY_PART

3 4 2

GRAY_SUNK IFDEF(sTag,sTrue,sFalse) InAnimationCycle() InCommunicationsCycle()

1 $9 StrToInt(PageInfo(19)) StrToInt(PageInfo(20))

40

Chapter: 3 参考信息

名称 KeyDown() KeyLeft() KeyReplay() KeyReplayAll() KeyRight() KeyUp() NONE NORMAL ObjectAssociatePropertyWithTag (Obj,sPName,sTName,sEvName="")

表达式 KeyMove(4) KeyMove(1) _KeyReplay(1) _KeyReplay(0) KeyMove(2) KeyMove(3) 0 0

注释 向下移动光标 向左移动光标 键重播 - 最后一个键 键重播所有 向右移动光标 向上移动光标 无奇偶校验 正常按钮

_ObjectAssociatePropertyWithTag(Obj,sP Name,sTName,sEvName) 1 1 (Red + Green * 256 + Blue * 65536)

ObjectAssociatePrope rtyWithTag 缺省事件 奇同位校验 显示模式 1 通过 RGB 颜色组件创 建一种压缩的 RGB 颜色 获得关于绘图系统的信 息 设备的打印输出 设备的打印输出,新行 搏动变量

ODD_P OVERLAP PackedRGB(Red,Green,Blue)

PlotInfo(hPlot,nType,sInput="")

_PlotInfo(hPlot,nType,sInput)

Print(sText,nMode=0) PrintLn(sText) Pulse(arg) RAboveUCL RBelowLCL ROutsideCL Shutdown(sDest="",sProject="",nMod e=1) SOFT TableMath(Table, Size, Command, mode=0) TARGET

DevPrint(DevCurr(),sText,nMode) DevPrint(DevCurr(),sText,1) arg = TRUE; Sleep(2); arg = FALSE; 8192 16384 4096 _Shutdown(sDest,sProject,nMode)

关闭宏

0 _TableMath(Table, Size, Command,mode) 3

显示模式 0 对标签进行的数学运算

屏幕目标

41

Chapter: 3 参考信息

名称 TaskHnd(sName="")

表达式 _TaskHnd(sName) _Wave(4,p,lo,hi,off)

注释 获得任务句柄 测试随机波

TestRandomWave(p=60,lo=0,hi=100, off=0) _Wave(3,p,lo,hi,off) TestSawWave(p=60,lo=0,hi=100,off= 0) _Wave(0,p,lo,hi,off) TestSinWave(p=60,lo=0,hi=100,off=0 ) _Wave(1,p,lo,hi,off) TestSquareWave(p=60,lo=0,hi=100,o ff=0) _Wave(2,p,lo,hi,off) TestTriangWave(p=60,lo=0,hi=100,of f=0) TimeHour(time) TimeMidNight(time) TimeMin(time) TimeSec(time) TimeSecond(time) TimeYearDay(time) Toggle(arg) TRN_EVENT TRN_PERIODIC TRN_PERIODIC_EVENT _TimeSub(time,0) _TimeSub(time, 7) _TimeSub(time,1) _TimeSub(time,2) _TimeSub(time, 2) _TimeSub(time, 8) arg = NOT arg; 2 1 3 _TrnGetTable (Name,time,period,len, Buf,mode,msec) _TrnNew(hAn,sTrn,s1, s2,s3,s4,s5,s6,s7,s8) _TrnScroll (hAn,hPen, nScroll,nMode) _TrnSetTable 趋势新宏 切换变量 事件趋势 周期性趋势 周期性事件趋势 从时间中获得小时 在午夜抽取时间 从时间中获得分钟 从时间中获得秒 从时间中获得秒 测试 Triag 波 测试方波 测试正弦波 测试锯齿波

TrnGetTable(Name,time,period,len,Buf ,mode,msec=0) TrnNew(hAn,sTrn,s1="",s2="",s3="", s4="",s5="",s6="",s7="",s8="") TrnScroll(hAn,hPen,nScroll,nMode=1)

42

Chapter: 3 参考信息

名称 TrnSetTable(Name,time,period,len,Buf ,msec=0) TRUE UnitControl(IODev,Type,Data) UnitInfo(IODev,Type) UnitStats() UserCreate(s1,s2,s3,s4,s5="",pG="", p1="",p2="",p3="",p4="",p5="",p6=" ",p7="",p8="") UserPassword(sUser,sNewPassword,s OldPassword="") UserPasswordExpiryDays(sUser,sPass word="") WinCopy(cx=1,cy=1,sPal="") WinFile(sFile,cx=1,cy=1,sPal="")

表达式 (Name,time,period,len,Buf,msec) 1 IODeviceControl(IODev,Type,Data) IODeviceInfo(IODev,Type) IODeviceStats() _UserCreate(s1,s2,s3,s4,s5, pG,p1,p2,p3,p4,p5,p6,p7,p8) _UserPassword(sUser, sNewPassword,sOldPassword) _UserPasswordExpiryDays (sUser,sPassword) _WinCopy(cx,cy,sPal) _WinFile(sFile,cx,cy,sPal) _WinPrint(sPort,cx,cy,sPal)

注释

布尔值 True

创建具有各种权限的新 用户

设置用户密码

获得用户密码到期日

打印宏 打印文件宏 打印宏

WinPrint(sPort,cx=0,cy=0,sPal="[run] :printer.pal") WinPrintFile(sFile,sPort,cx=0,cy=0,sPa l="[run]:printer.pal") WRITE_ON_DRAG WRITE_ON_DROP XAboveUCL XBelowLCL XDownTrend XErratic XFreak XGradualDown XGradualUp XMixture _WinPrintFile(sFile,sPort, cx,cy,sPal) 1 0 4 8 64 512 1 256 128 2048 打印文件宏

滑钮的写入模式 滑钮的写入模式

43

Chapter: 3 参考信息

名称 XOutsideCL XOutsideWL XStratification XUpTrend

表达式 2 16 1024 32

注释

注意:不要修改包含工程。对包含工程的更改将在重新安装或升级 Vijeo Citect 时丢失。

ASCII/ANSI 字符代码列表
下列的代码表指示了 ANSI 拉丁 1 字符集。代码 0 到 31 是控制代码。标准的 ASCII 代码是 从 32 到 127(十进制)的通用代码,与使用的 ANSI 字符集无关。从 160 到 255(十进 制)的保留代码根据所使用的 ANSI 字符集的语言而异。

图符 {NUL} {SOH} {STX} {ETX} {EOT} {ENQ} {ACK} {BEL} {BS} {HT} {LF} {VT} {FF} {CR} {SO}

十进制 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14

十六进制 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E

44

Chapter: 3 参考信息

图符 {SI} {DLE} {DC1} {DC2} {DC3} {DC4} {NAK} {SYN} {ETB} {CAN} {EM} {SUB} {ESC} {FS} {GS} {RS} {US} {SPC} ! " # $ % & ' ( )

十进制 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

十六进制 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 29

45

Chapter: 3 参考信息

图符 * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D

十进制 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68

十六进制 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43 44

46

Chapter: 3 参考信息

图符 E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _

十进制 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95

十六进制 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F

47

Chapter: 3 参考信息

图符 ` a b c d e f g h i j k l m n o p q r s t u v w x y z

十进制 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122

十六进制 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77 78 79 7A

48

Chapter: 3 参考信息

图符 { | } ~ {Delete}

十进制 123 124 125 126 127 128 129

十六进制 7B 7C 7D 7E 7F 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F 90 91 92 93 94 95

? ? ? ... ? ? ? ‰ ? < ?

130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

` ' " " ·

145 146 147 148 149

49

Chapter: 3 参考信息

图符 ? ? ? > ?

十进制 150 151 152 153 154 155 156 157 158

十六进制 96 97 98 99 9A 9B 9C 9D 9E 9F A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB

? {NBSP} ? ? ? ¤ ? ? § ¨ ? ? ? 172 ? ? ? °

159 160 161 162 163 164 165 166 167 168 169 170 171 AC 173 174 175 176

AD AE AF B0

50

Chapter: 3 参考信息

图符 ± ? ? ? ? 182 · ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

十进制 177 178 179 180 181 B6 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

十六进制 B1 B2 B3 B4 B5

B7 B8 B9 BA BB BC BD BE BF C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB

51

Chapter: 3 参考信息

图符 ? ? ? ? ? ? ? ? ? ? ? × ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

十进制 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230

十六进制 CC CD CE CF D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF E0 E1 E2 E3 E4 E5 E6

52

Chapter: 3 参考信息

图符 ? ? ? ? ? ì í ? ? ? ? ò ó ? ? ? ÷ ? ù ú ? ü ? ? ?

十进制 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255

十六进制 E7 E8 E9 EA EB EC ED EE EF F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF

53

Chapter: 3 参考信息

格式字段
本节说明下列内容: ? 报警显示字段 ? 报警汇总字段 ? 命令字段

报警显示字段
您可以使用下列任何字段或 报警摘要字段来设置报警显示(请参阅 报警类别)和报警记录 设备(请参阅 设置报警显示格式)的格式:

域名 {Tag,n}

描述 报警标签 注意:如果将标签字段配置为支持长名称(最多为 79 个字符),可能会导致报警 显示出现重叠情况。如果预计使用长名称,请使用较小的显示字段。

{TagEx,n}

带有群集名称前缀的报警标签 注意:如果将 TagEx 字段配置为支持长名称(最多为 79 个字符),可能会导 致报警显示出现重叠情况。如果预计使用长名称,请使用较小的显示字段。

{AlarmType,n}

报警类型(字符串),未本地化。值为:数字量、模拟量、高级、多-数字量、多 状态模拟量、带时间戳的、带时间戳的数字量、带时间戳的模拟量。 报警类型编号(改用 AlarmType 获取字符串值)。值为: -1 无效 0 数字量 1 模拟量 2 高级 3 多-数字量 4 多状态模拟量 5 用户事件 6 带时间戳的 7 硬件 8 带时间戳的数字量 9 带时间戳的模拟量

{TypeNum,n}

{AlmComment,n} {Cluster,n} {CUSTOM1,n} {CUSTOM2,n} {CUSTOM3,n} {CUSTOM4,n} {CUSTOM5,n} {CUSTOM6,n} {CUSTOM7,n} {CUSTOM8,n}

在报警属性对话框的“注释”字段中输入的文本信息。 集群名称 配置的报警自定义字段。

54

Chapter: 3 参考信息

域名 {Name,n}

描述 报警名称 注意:如果将名称字段配置为支持长名称(最多为 79 个字符),可能会导致报警 显示出现重叠情况。如果预计使用长名称,请使用较小的显示字段。

{Native_Name,n}

表达式中的报警名称 注意:如果将 Native_Name 字段配置为支持长名称(最多为 79 个字符), 可能会导致报警显示出现重叠情况。如果预计使用长名称,请使用较小的显示字 段。

{Desc,n} {Native_Desc,n} {Category,n} {Help,n} {Area,n} {Priv,n} {Priority,n} {Type,n}

报警描述 报警描述采用本地语言 报警分类 帮助页面 区域 权限 报警分类的优先级 报警或条件的类型: ACKNOWLEDGED CLEARED DISABLED UNACKNOWLEDGED 采用以下格式的报警日期和时间:“yyyy-mm-dd hh:mm:ss[.ttt]” 报警状态更改的时间 (hh:mm:ss)。(设置 [Alarm]SetTimeOnAck 参数以 便在确认报警的时间内使用此字段。) 报警状态更改的日期 (dd:mm:yyyy)。请注意,您可以通过参数 [ALARM]ExtendedDate 来更改使用的格式。 采用扩展格式的报警状态更改的日期。 报警的当前状态。该字段只能用于报警显示。而不适用于报警汇总。 ON OFF 向 {Time,n} 字段中添加毫秒数 高限报警触发值 高高限报警触发值 低限报警触发值 低低限报警触发值

{LocalTimeDate,n} {Time,n}

{Date,n}

{DateExt,n} {State,n}

{Millisec,n} {High,n} {HighHigh,n} {Low,n} {LowLow,n}

55

Chapter: 3 参考信息

域名 {Rate,n} {Deviation,n} {Deadband,n} {Format,n} {Value,n} {State,n}

描述 触发值的变化速率 偏差报警触发值 死区 变量标签的显示格式 模拟量变量的当前值 报警的当前状态。该字段只能用于报警显示。而不适用于报警汇总。 DEVIATION RATE LOW LOWLOW HIGH HIGHHIGH CLEARED 与某种协议(通讯)错误相关联的文本字符串。该字段仅与硬件错误相关联并且 包含与该错误相关联的额外信息(例如,如果该错误与某个设备相关联,将返回该 设备的名称;如果该错误与某个 Cicode 函数相关联,将返回该函数的名称;如果 该错误与某个 I/O 设备相关联,将返回该 I/O 设备的提醒信息)。 与该报警相关联的页面、设备等。 报警所经过的上一个状态。(将报警记录到某个设备时,此状态非常有用。) 特定状态的配置描述(例如,运行状况或已停止)。配置多-数字量报警属性时输 入此描述 指示是否应该呼叫该报警。如果其值为 TRUE,则呼叫该报警。缺省参数值为 FALSE。请参见 报警呼叫属性。 指示报警所属的呼叫组。最大长度为 80 个字符。

{ErrDesc,n}

{ErrPage,n} {LogState,n} {State_desc, n}

{Paging,n}

{PagingGroup, n}

n 指定显示字段的大小。 注意: ? 任何类型的报警都可显示上述任一字段。对于不适用的特殊 报警类型,则会显示零或空白字符。 ? 当某个报警值的长度大于要在其中显示的字段长度(例如. n )时,它将会被截断或者用 #OVR(“格式宽度溢出”)提醒信息来 替代。 ? 对于汇总页面,则应使用 {SumState}。要将状态记录到某个 设备,使用 {LogState}。State 是报警的当前状态,SumState 是报警 发生时的状态,Log State 是报警在过渡时期的状态。

56

Chapter: 3 参考信息

另请参见 报警汇总字段

报警汇总字段
可以使用下面列出的任何字段(或组合)来对报警汇总显示以及报警汇总设备的格式进行 设置。 通过在“报警分类属性”对话框中的摘要格式字段中指定字段名称,对整个报警分类的报警 汇总进行格式设置。 还可以使用 [Alarm]DefSumFmt 参数来设置报警汇总的格式,尤其是在所有的报警汇总格式 都相同的时候。

字段名 {UserName,n}

描述 已登录并对报警执行了某些操作(例如确认报警或禁用报警等)的用户的名称(用户名 称)。请注意,当报警第一次被激活时,用户名被设置为“系统”(因为操作人员未对报 警实施跟踪)。 已登录并对报警执行了某些操作(例如确认报警或禁用报警等)的用户的全名(用户全 名)。请注意,当报警第一次被激活时,用户名被设置为“系统”(因为操作人员未对报 警实施跟踪)。 与用户事件相关联的文本。 报警被激活的日期 报警被激活的日期(采用扩展的格式 dd/mm/yyyy) 报警返回到其正常状态的日期 报警返回到其正常状态的日期(采用扩展的格式 d/mm/yyyy) 报警被激活的时间 报警返回到其正常状态的时间 OnDate/OnTime 与 OffDate/OffTime 之间的时间差(秒) 向报警激活时间中添加毫秒数。 向报警返回到其正常状态的时间中添加毫秒数。 报警被确认的时间 报警被确认的日期 报警被确认的日期(采用扩展的格式 dd/mm/yyyy) 对报警发生时的状态进行描述

{FullName,n}

{UserDesc,n} {OnDate,n} {OnDateExt,n} {OffDate,n} {OffDateExt,n} {OnTime,n} {OffTime,n} {DeltaTime,n} {OnMilli,n} {OffMilli,n} {AckTime,n} {AckDate,n} {AckDateExt,n} {SumState,n}

57

Chapter: 3 参考信息

字段名 {SumDesc,n} {SumType,n}

描述 对报警汇总的描述 报警汇总类型(类似于报警“类型”)。值为 ACKNOWLEDGED、CLEARED、 DISABLED、UNACKNOWLEDGED 报警汇总描述(采用本地语言) 操作人员在运行时间向“报警汇总”条目中添加的注释。该注释是使用 AlarmComment() 函数来指定的。 操作人员在运行时间向“报警汇总”条目中添加的本地语言注释。

{Native_SumDesc,n} {Comment,n}

{Native_Comment,n} 其中 n 指定显示字段的大小。

注意:您还可以在“报警汇总”中包含状态之外的其它任何报警显示字段。 另请参见 更改报警汇总显示的顺序

使用命令字段
可以使用以下字段(或组合)格式化命令记录设备:

字段名称 {UserName,n} {FullName,n} {Time,n} {TimeLong,n} {Date,n} {DateLong,n} {DateExt,n} {Page,n} {MsgLog,n}

描述 命令发出时登录的用户的名称(用户名)。 命令发出时登录的用户的全名(全名)。 命令发出的时间(短格式,hh:mm)。 命令发出的时间(长格式,hh:mm:ss)。 命令发出的日期(短格式,dd:mm:yy)。 命令发出的日期(长格式,日月年)。 命令发出的日期(扩展格式,dd:mm:yyyy)。 命令发出时显示的页面。 作为命令记录的消息日志属性发送的消息。

以下字段(在命令字段中)仅对键盘命令适用: {Arg1,n} 第一个键盘命令参数(如果有)。

58

Chapter: 3 参考信息

字段名称 {Arg2,n} ... {Arg8,n} {Native_MsgLog,n} 其中 n 指定显示字段的大小。

描述 第二个键盘命令参数(如果有)。

第八个键盘命令参数(如果有)。 作为命令记录的消息日志属性发送的消息本地语言版本。

例如,可以按以下方式配置设备:

名称 格式

KeyLog {Date,9} {MsgLog,27} {Arg1,3} by {FullName,11}

然后会借助以下配置创建键盘命令(对象、页面或系统):

日志设备 键序列 日志消息

KeyLog ### ENTER 密度设置点改为

导致以下类型的输出:“Timothy Lee 于 1999 年 1 月 1 日将密度设置点改为 123”。

错误消息
Vijeo Citect 有两种协议驱动程序错误: ? 通用 ? 特定于驱动程序 通用错误是硬件错误 0-31,并且是所有协议共有的。 驱动程序有自己的特定错误,它是唯一的,因此不能被硬件报警系统识别。驱动程序转换 特定错误为 I/O 服务器可以识别的通用错误。 例如,当驱动程序有错误时,通常既有驱动程序特定错误也有相应的通用错误。

59

Chapter: 3 参考信息

注意:有关设备驱动程序实施的参考信息,包括驱动程序提醒消息,请参考驱动程序参考 帮助。 另请参见 一般驱动程序错误 特定于驱动程序的错误 使用驱动程序参考帮助

协议普通错误
Vijeo Citect 有两种协议驱动程序错误:普通错误和 协议特定错误。通用错误是硬件错误 031,并且是所有协议共有的。 协议驱动程序也有自己的特定错误,它是唯一的,因此不能被硬件报警系统识别。驱动程 序转换特定错误为 I/O 服务器可以识别的通用错误。例如,当驱动程序有错误时,通常既 有协议特定错误也有相应的通用错误。 一般错误 下表描述一般协议错误。

错误代 码 1

错误标题

描述 请求并不存在的设备地址。例如,在 I/O 设备中只有 200 个寄存器时尝试读取寄存器编号 4000。请检查变量标签数据库以查找出错的变量。 服务器取消了正在由驱动程序处理的命令。驱动程序可能已经花费了太多时间去处理命令。如果驱 动程序未能在指定的时间限制内响应,Vijeo Citect 将取消此命令。时间限制是超时期间和每次超 时之后重试命令的次数。你可以在协议的超时和重试参数中更改这些值。还应该检查 WatchTime 参数,以确定驱动程序链接到 I/O 设备的频率。同时检查通信错误。 请求指定协议不支持的数据类型。该错误应该不会在正常操作中出现。请尝试重启计算机,以重新 设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。如果您已写入了自己的协 议驱动程序,此错误是由编译器规格和驱动程序的数据库不匹配引起的。 写请求包含无效数据,例如,尝试写入具有无效浮点数的浮点地址。检查 Vijeo Citect 数据库。

地址超界

2

命令被取 消

3

未知的数 据类型

4

未知的数 据格式 命令未知

5

服务器发送了一个驱动程序不能识别的命令。该错误应该不会在正常操作中出现。请尝试重启计算 机,以重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。 通信通道存在的问题,导致了数据传输错误。检查通信通道硬件设置。例如,传送器和接收器之间 的奇偶校验、波特率、停止位或数据位可能不匹配。检查 I/O 设备的设置与 Vijeo Citect 端口和 板卡表中的域数据是否相同。 I/O 设备未响应读请求或写请求。驱动程序向 I/O 设备发送了一个命令,I/O 设备未在超时期间

6

响应错误 或混淆

7

I/O 设备

60

Chapter: 3 参考信息

错误代 码

错误标题 未响应

描述 内响应。这通常是通信故障的第一个显示。检查 I/O 设备与服务器连接是否正确并且已打开。如果 超时期间太短也会发生此错误。请尝试增加协议超时参数的超时期间。还可以增加延时参数,从而 增加接收响应与发送下一个命令之间的延时时间。 Vijeo Citect 已经建立了与 I/O 设备之间的通信,然而,I/O 设备检测到协议中存在错误。此错误 可能是由通信链接中的故障或梯形逻辑(I/O 设备中)中的错误引起的。 解决方法: 1. 检查 I/O 设备是否正常运行。 2. 检查通讯电缆是否已正确连接(在两端)。 3. 使用通信快速向导检查 I/O 设备的配置(特别是地址和特殊选项域)是否与推荐的设置和 I/O 设备中的设置相一致。 4. 如果使用的是串行通信,使用通信快速向导检查端口配置(特别是波特率、数据位、停止位和奇 偶校验位)是否与推荐的设置和 I/O 设备中的设置相一致。 5. 显示硬件报警画面,注意显示的协议错误。 6. 使用 I/O 设备、网络和通讯板卡随附的文档来查找错误。 7. 检查 I/O 设备中的梯形逻辑是否存在错误。 8. 运行计算机设置向导。 9. 重新编译工程并启动 Vijeo Citect 运行期。

8

一般错误

9

写位置受 保护 硬件错误

尝试对已进行未授权修改保护的位置执行写操作。要允许写操作,请更改这一位置的访问权限。

10

通信通道、服务器、或 I/O 设备硬件存在问题。检查所有硬件组件。尚未处理命令或数据请求。 服务器的运行可能已不再可靠。 服务器与 I/O 设备之间的通信链接正常发挥作用,但 I/O 设备有一些警告条件被激活,例如 I/O 设备处于编程模式下。检查 I/O 设备是否处于正确的模式下。 I/O 设备处于离线模式,不能进行任何外部通信。 解决方法: 1. 检查 I/O 设备是否正常运行。 2. 检查通讯电缆有无破损。 3. 检查通讯电缆是否已正确连接(在两端)。 4. 如果使用的是串行通信,检查通信电缆与帮助系统中的图表是否一致。 5. 使用通信快速向导检查 I/O 设备的配置(特别是地址和特殊选项域)是否与推荐的设置和 I/O 设备中的设置相一致。 6. 如果使用的是串行通信,使用通信快速向导检查端口配置(特别是波特率、数据位、停止位和奇 偶校验位)是否与推荐的设置和 I/O 设备中的设置相一致。 7. 运行计算机设置向导。 8. 检查 citect.ini 文件的以下设置: [IOSERVER] Server=1

11

I/O 设备 警告 I/O 设备 离线,无 法通信

12

61

Chapter: 3 参考信息

错误代 码

错误标题

描述 Name=<name> 其中: <name> 是在 Vijeo Citect 工程中配置的服务器名称。(使用自定义设置检查服务器名称。) 9. 重新编译工程并启动 Vijeo Citect 运行系统。 注意:如果您配置了备用 I/O 设备,该错误将导致所有备用 I/O 设备被激活。I/O 设备离线时的 命令或数据请求尚未完成。

13

驱动程序 软件错误 用户访问 冲突 内存耗尽 - 严重 没有缓冲 区,不能 继续 缓冲区不 足警告 向驱动程 序发送了 过多命令 驱动程序 不响应 打开的通 道过多

驱动程序内部发生软件错误。该错误应该不会在正常操作中出现。请尝试重启计算机,以重新设置 所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。 未被授权的用户试图访问信息。请检查用户的访问权限。

14

15

服务器内存耗尽,无法继续运行。最大限缩小缓冲区和队列分配的大小,或扩展服务器计算机的内 存。尚未处理命令或数据请求。 没有可以分配的通信缓冲区,或是计算机内存耗尽。服务器性能可能会下降,但它可以继续运行。 增加内存。

16

17

该错误可能发生在高速瞬间加载期间,没有坏的影响。如果这个错误频繁发生,请增加通信缓冲区 的数量。 向驱动程序发送了过多命令。

18

19

服务器无法接收来自驱动程序的任何响应。该错误应该不会在正常操作中出现。请尝试重启计算 机,以重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。 每个驱动程序只能支持几个通信通道。您已经超过了这个限制。该错误通常发生在非正常终止并重 启服务器时。请尝试重启计算机,以重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。命令或数据请求未完成。 通信通道当前处于离线状态,禁止了通信。服务器无法初始化通信通道或通道在运行时离线。检查 通道硬件是否存在故障。该错误发生时,与此通道连接的所有 I/O 设备都被认为已离线,备用 I/O 设备被激活。命令或数据请求未完成。 服务器试图与未打开的通道通信。请尝试重启计算机,以重新设置所有驱动程序和硬件。如果问题 仍然存在,请联系 Citect 技术支持。命令或数据请求未完成。 服务器试图与尚未初始化的通道通信。该错误应该不会在正常操作中出现。请尝试重启计算机,以 重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。命令或数据请求未完 成。 通道具有太多与之相连的 I/O 设备。该错误应该不会在正常操作中出现。命令或数据请求未完 成。请尝试重启计算机,以重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术 支持。 被请求的数据仍在被处理,将在适当的时候返回。此错误只发生在必须建立复杂的通信以从 I/O

20

21

通道离 线,不能 通讯 通道尚未 被打开 通道尚未 被初始化

22

23

24

每个通道 的 I/O 设 备数过多 数据尚未

25

62

Chapter: 3 参考信息

错误代 码

错误标题 有效

描述 设备中检索数据的驱动程序中。请忽略此警告。 服务器试图取消某个命令,但驱动程序找不到该命令。该错误应该不会在正常操作中出现。请尝试 重启计算机,以重新设置所有驱动程序和硬件。如果问题仍然存在,请联系 Citect 技术支持。 通讯已经从主 I/O 设备切换到备用 I/O 设备。服务器会在出现“紧急”转换时返回此消息。修正主 I/O 设备中的故障。

26

无法取消 命令 备用 I/O 设备被激 活 消息溢出

27

28

响应的长度超过了响应缓冲区。如果该错误发生在串行通信驱动程序中,可能会收到乱码。检查通 讯链接和驱动程序的波特率。 存在配置错误,例如设置了无效的特殊选项。

29

错误的用 户参数 备用 I/O 设备错误 I/O 服务 器请求超 时

30

备用 I/O 设备中存在错误。修正备用 I/O 设备中的错误。

31

一个或多个发送到 I/O 服务器的请求未在超时期间内完成。I/O 服务器离线或 I/O 服务器用于完 成请求的时间过长。请检查 PLC 通信链接、PLC 超时、PLC 重试次数和网络通信。即使您没有网 络(即,如果 I/O 服务器与控制客户机是同一台计算机),此错误也可能发生。如果错误仍然存 在,请增加 [LAN] TimeOut 参数。缺省超时值为 8000 毫秒。

一般驱动程序错误
以下错误是所有 Vijeo Citect 驱动程序的一般性错误。必须先将驱动程序错误映射到一般错 误,然后 Vijeo Citect 才能解释它。

错误 GENERIC_ADDRESS_RANGE_ERROR (0x0001 | SEVERITY_ERROR) GENERIC_CMD_CANCELED (0x0002 | SEVERITY_ERROR) GENERIC_INVALID_DATA_TYPE (0x0003 | SEVERITY_ERROR) GENERIC_INVALID_DATA_FORMAT (0x0004 | SEVERITY_ERROR) GENERIC_INVALID_COMMAND (0x0005 | SEVERITY_ERROR)

描述 请求一个并不存在的设备地址。例如,在设备中只有 200 个寄存器时尝试读取寄存器编号 4000。 服务器取消了正在被驱动程序处理的命令。如果驱动程 序处理命令的时间过长,这就可能发生。检查驱动程序 的超时值和重试次数。 请求指定协议不支持的数据类型。该错误应该不会在正 常操作中出现。 请求包含无效数据;例如,写入具有无效浮点数的浮点 地址。检查 Vijeo Citect 数据库。 服务器向未能识别的驱动程序发送了命令。该错误应该 不会在正常操作中出现。

63

Chapter: 3 参考信息

错误 GENERIC_INVALID_RESPONSE (0x0006 | SEVERITY_ERROR) GENERIC_UNIT_TIMEOUT (0x0007 | SEVERITY_ERROR) GENERIC_GENERAL_ERROR (0x0008 | SEVERITY_ERROR) GENERIC_WRITE_PROTECT (0x0009 | SEVERITY_ERROR) GENERIC_HARDWARE_ERROR (0x000A | SEVERITY_UNRECOVERABLE) GENERIC_UNIT_WARNING (0x000B | SEVERITY_WARNING) GENERIC_UNIT_OFFLINE (0x000C | SEVERITY_SEVERE) GENERIC_SOFTWARE_ERROR (0x000D | SEVERITY_SEVERE) GENERIC_ACCESS_VIOLATION (0x000E| SEVERITY_ERROR) GENERIC_NO_MEMORY (0x000F | SEVERITY_UNRECOVERABLE) GENERIC_NO_BUFFERS (0x0010 | SEVERITY_ERROR) GENERIC_LOW_BUFFERS (0x0011| SEVERITY_WARNING) GENERIC_TOO_MANY_COMMANDS (0x0012| SEVERITY_WARNING) GENERIC_DRIVER_TIMEOUT (0x0013 | SEVERITY_ERROR) GENERIC_NO_MORE_CHANNELS (0x0014 | SEVERITY_SEVERE) GENERIC_CHANNEL_OFFLINE

描述 通信通道非正常工作,并在所传输的数据中产生错误。

设备不响应读请求或写请求。驱动程序向设备发送了命 令,设备在超时期间内没有响应。 特定于未映射驱动程序的错误通常会被报告为一般错 误。请参阅随所使用协议列出的特定于协议的错误。 尝试对已进行未授权修改保护的位置执行写操作。要允 许写操作,请更改这一位置的访问权限。 通信通道、服务器或设备硬件非正常工作。检查所有硬 件组件。还必须检查服务器的操作是否正确。 服务器和设备之间的通信链接正常发挥作用;但设备正 处于错误发生的状况下或处于不可操作状态,例如设备 处于编程模式下。 设备处于离线模式,导致所有外部通信都无法进行。此 错误将导致所有备用设备被激活。Vijeo Citect 将尝试 重新初始化设备。 驱动程序内部发生软件错误。该错误应该不会在正常操 作中出现。 未被授权的用户试图访问信息。请检查用户的访问权 限。 服务器或驱动程序的内存用尽,无法继续执行。最大限 度缩减缓冲区和队列分配的大小,或扩展服务计算机的 内存(物理或虚拟内存)。 没有足够的通讯缓冲区可用于分配。服务器的性能可能 降低,但仍将继续运行。增加通信缓存区的数量。 该错误可能发生在高速瞬间加载期间,没有坏的影响。 如果这个错误频繁发生,请增加通信缓冲区的数量。 向驱动程序发送了过多命令。

服务器无法接收来自驱动程序的任何响应。该错误应该 不会在正常操作中出现。 每一个驱动程序只支持固定数量的通信通道。你已经超 过了这个限制。命令或数据请求未完成。 通信通道当前处于离线状态,禁止了通信。服务器无法

64

Chapter: 3 参考信息

错误 (0x0015 | SEVERITY_SEVERE)

描述 初始化通信通道或通道在运行期间离线。所有使用此通 道连接的设备将被认为处于离线状态,这将导致备用设 备被激活。Vijeo Citect 将尝试重新初始化通道。 服务器试图使用未打开的通道进行通信。

GENERIC_BAD_CHANNEL (0x0016| SEVERITY_SEVERE) GENERIC_CHANNEL_NOT_INIT (0x0017 | SEVERITY_SEVERE) GENERIC_TOO_MANY_UNITS (0x0018 | SEVERITY_SEVERE) GENERIC_INVALID_DATA (0x0019 | SEVERITY_ERROR) GENERIC_CANNOT_CANCEL (0x001A | SEVERITY_WARNING) GENERIC_STANDBY_ACTIVE (0x001B | SEVERITY_WARNING) GENERIC_MSG_OVERRUN (0x001C | SEVERITY_ERROR) GENERIC_BAD_PARAMETER (0x001D | SEVERITY_ERROR) GENERIC_STANDBY_ERROR (0x001E| SEVERITY_WARNING) GENERIC_NO_RESPONSE (0x001F | SEVERITY_ERROR) GENERIC_UNIT_REMOTE (0x0020 | SEVERITY_ERROR) GENERIC_GENERAL_WARNING (0x0024 | SEVERITY_WARNING)

服务器试图与尚未初始化的通道通信。该错误应该不会 在正常操作中出现。命令或数据请求未完成。如果问题 仍然存在,请联系技术支持。 某通道具有过多与之相连的设备。该错误应该不会在正 常操作中出现。 请求的数据格式无效或并非预期的类型。

服务器试图取消某个命令,但驱动程序找不到该命令。 该错误应该不会在正常操作中出现。 通信已经从主设备切换到备用设备。服务器会在出现紧 急转变时返回此信息。 响应的长度超过了响应缓冲区。如果该错误发生在串行 通信驱动程序中,可能会收到乱码。检查通讯链接和驱 动程序的波特率。 存在配置错误,例如设置了无效的特殊选项。

备用设备中存在错误。

通信服务器没有响应。

无法与远程设备(如拨号 I/O 设备)通信。仅用于排定 的 I/O 设备。 驱动程序正在执行请求的动作,但需要通告潜在问题。 例如,某些驱动程序可能将其用于过期数据提醒。

协议特定错误
尽管每一个协议都有多种唯一的错误,但最初的 34 个协议特定错误是所有协议的标准。报 告的所有协议特定错误的错误号必须在 1 到 31。尽管这些错误有自己的错误号(以 16 进 制显示),但它仅作为一个符号使用。

65

Chapter: 3 参考信息

注意: 协议特定错误显示在每个协议的协议特定错误帮助主题下。如果您不能确定错误种 类,请参考 I/O 设备随附的文档。

错误代码 1 (0x01)

错误标题 处理接收字符的速度不够快

描述 处理接收字符的速度不够快。波特率较 低或使用计算机的速度较快。如果错误持 续存在,请联系 Citect 支持。 接收到的信息有奇偶校验错误。检查在 Citect 端口表中是否指定了正确的波特 率、奇偶校验、停止位和数据位。此错误 可能是由连接到 I/O 设备的电缆故障所 引起,也可能是由通讯链接的额外噪音所 引起。 检测到接收线路发生中断。此错误可能 是由连接到 I/O 设备的故障电缆所引 起,也可能是由通讯链接的额外噪音所引 起。 指定的波特率可能错误。检查是否在 Citect 端口表中定义了正确的波特率。 从 I/O 设备中接收的消息太长。此错误 可能是由连接到 I/O 设备的故障电缆所 引起,也可能是由通讯链接的额外噪音所 引起。如果错误持续存在,请联系 Citect 支持。 接收到的消息中的校验和与计算值不 符。检查在 Citect 端口表中是否指定了 正确的波特率、奇偶校验、停止位和数据 位。此错误可能是由连接到 I/O 设备的 电缆故障所引起,也可能是由通讯链接的 额外噪音所引起。您也可以尝试增加协议 的重试参数数值。 接收到的消息中没有正文起始(STX) 字符。检查在 Citect 端口表中是否指定 了正确的波特率、奇偶校验、停止位和数 据位。此错误可能是由连接到 I/O 设备 的电缆故障所引起,也可能是由通讯链接 的额外噪音所引起。 接收到的消息中没有正文终止(ETX) 字符。检查在 Citect 端口表中是否指定 了正确的波特率、奇偶校验、停止位和数 据位。此错误可能是由连接到 I/O 设备 的电缆故障所引起,也可能是由通讯链接

2 (0x02)

奇偶校验错误

3 (0x03)

检测到接收线路中断

4 (0x04)

帧错误

5 (0x05)

消息太长

6 (0x06)

校验和无效

7 (0x07)

正文起始丢失

8 (0x08)

正文结束丢失

66

Chapter: 3 参考信息

错误代码

错误标题

描述 的额外噪音所引起。

10 (0x0A)

不能传输消息

Vijeo Citect 不能传输消息。此错误可能 是由连接到 I/O 设备的故障电缆所引 起,也可能是由通讯链接的额外噪音所引 起。 串行驱动程序(COMxI、PCXI 或 COMx)发生故障。请尝试重启计算机, 以复位所有驱动程序和硬件。 请求长度与驱动程序的要求不一致。 服务器命令无效。请联系 Citect 支持。 不能为驱动程序分配计时器资源。请联 系 Citect 支持。 为设备指定了太多通道。请联系 Citect 支持。 服务器的通道号不能打开。请联系 Citect 支持。 驱动程序命令不能被取消。请联系 Citect 支持。 通道离线。如果超时,可能发生这个错 误。此错误可能是由连接到 I/O 设备的 故障电缆所引起,也可能是由通讯链接的 额外噪音所引起。 在指定的超时时间内没有收到来自 I/O 设备的响应。此错误可能是由连接到 I/O 设备的电缆故障所引起,也可能是由通讯 链接的额外噪音所引起。您可以增加协议 重试参数的数值。 来自服务器的 I/O 设备号不能激活或超 界。请联系 Citect 支持。 检查在 Citect I/O 设备表中指定的 I/O 设备地址是否与在 I/O 设备中配置的相 同。 驱动程序不能识别服务器的数据类型。 请联系 Citect 支持。 服务器的 I/O 设备类型不能被驱动程序 识别。请联系 Citect 支持。 为通道指定的 I/O 设备太多。请联系

11 (0x0B)

不能复位串行驱动程序

12 (0x0C) 15 (0x0F) 16 (0x10)

请求长度不一致 服务器命令无效 不能为驱动程序分配计时器资源

17 (0x11)

为驱动程序指定了太多通道

18 (0x12)

服务器的通道号不能打开

19 (0x13)

命令不能取消

20 (0x14)

通道离线

21 (0x15)

超时错误

22 (0x16)

来自服务器的 I/O 设备号不能激活或超 界 I/O 设备离线

23 (0x17)

24 (0x18)

服务器的数据类型不能被驱动程序识别

25 (0x19)

服务器的 I/O 设备类型不能被驱动程序 识别 为通道指定的 I/O 设备太多

26 (0x1A)

67

Chapter: 3 参考信息

错误代码

错误标题

描述 Citect 支持。

27 (0x1B)

向驱动程序发送的命令太多

向驱动程序发送的命令太多。请联系 Citect 支持。 读取的数据无效。请联系 Citect 支持。 驱动程序命令被取消。请联系 Citect 支 持。 试图访问的地址的数据类型无效或超 界。检查您使用的数据类型或地址范围是 否对 I/O 设备有效。 来自服务器的数据长度错误。请联系 Citect 支持。 Vijeo Citect 不能读取来自 I/O 设备的 数据。请联系 Citect 支持。 指定的设备不存在。请联系 Citect 支 持。 指定的 I/O 设备不支持中断处理。您已 经在板卡表上或通过将 PollTime 参数设 置为 0 的方式,为不支持中断的硬件设 备指定了一个中断。检查是否在板卡上设 置了中断,或设置了协议的 PollTime 参 数。

28 (0x1C) 29 (0x1D)

读取的数据无效 命令被取消

30 (0x1E)

地址无效或超界

31 (0x1F)

来自服务器的数据长度不正确

32 (0x20)

不能从设备读取数据

33 (0x21)

指定的设备不存在

34 (0x22)

指定的设备不支持中断

标准驱动程序错误
以下错误是通用于所有驱动程序的底层错误。这些错误都将映射到通用错误,以便 Vijeo Citect 识别它们。大多数驱动程序除了这些错误之外也有自己特殊的错误。

错误 0 (0x00000000) NO_ERROR 1 (0x00000001) DRIVER_CHAR_OVERRUN 2 (0x00000002) DRIVER_CHAR_PARITY 3 (0x00000003)

描述 没有错误。

传输的字符不能很快的收到。这一错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 在接受的字符中有奇偶校验错误。这一错误将映射到通用错 误 GENERIC_INVALID_RESPONSE。 在接受线上检测到一处断行。这一错误将映射到通用错误

68

Chapter: 3 参考信息

错误 DRIVER_CHAR_BREAK 4 (0x00000004) DRIVER_CHAR_FRAMING 5 (0x00000005) DRIVER_MSG_OVERRUN 6 (0x00000006) DRIVER_BAD_CRC 7 (0x00000007) DRIVER_NO_STX 8 (0x00000008) DRIVER_NO_ETX 9 (0x00000009) DRIVER_NOT_INIT 10 (0x0000000A) DRIVER_BAD_TRANSMIT 11 (0X0000000B) DRIVER_CANNOT_RESET 12 (0X0000000C) DRIVER_BAD_LENGTH 13 (0X0000000D) DRIVER_MSG_UNDERRUN 15 (0X0000000F) DRIVER_INVALID_COMMAND 16 (0X00000010) DRIVER_NO_TIMER 17 (0x00000011) DRIVER_NO_MORE_CHANNELS 18 (0x00000012) DRIVER_BAD_CHANNEL 19 (0x00000013) DRIVER_CANNOT_CANCEL 20 (0x00000014)

描述 GENERIC_INVALID_RESPONSE。 帧错误。检查波特率。这一错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 从设备接收的信息太长。这一错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 接收到的消息中的校验和与计算值不符。错误将映射到通用 错误 GENERIC_INVALID_RESPONSE。 文字字符的开头未出现。错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 文字字符的结尾未出现。错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 驱动程序尚未被初始化。这一错误将映射到通用错误 GENERIC_UNIT_OFFLINE。 不能传输信息。这一错误将映射到通用错误 GENERIC_UNIT_OFFLINE。 不能重设串行驱动程序。这一错误将映射到通用错误 GENERIC_CHANNEL_OFFLINE。 响应长度不正确。这一错误将映射到通用错误 GENERIC_GENERAL_ERROR。 信息太短。这一错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 服务器命令无效。这一错误将映射到通用错误 GENERIC_INVALID_COMMAND。 不能为驱动程序分配定时器资源。这一错误将映射到通用错 误 GENERIC_HARDWARE_ERROR。 为设备指定了太多通道。这一错误将映射到通用错误 GENERIC_NO_MORE_CHANNELS。 服务器的通道数并未打开。这一错误将映射到通用错误 GENERIC_BAD_CHANNEL。 命令不能被取消。这一错误将映射到通用错误 GENERIC_CANNOT_CANCEL。 通道没有再线。这一错误将映射到通用错误

69

Chapter: 3 参考信息

错误 DRIVER_CHANNEL_OFFLINE 21 (0x00000015) DRIVER_TIMEOUT 22 (0x00000016) DRIVER_BAD_UNIT 23 (0x00000017) DRIVER_UNIT_OFFLINE 24 (0x00000018) DRIVER_BAD_DATA_TYPE 25 (0x00000019) DRIVER_BAD_UNIT_TYPE 26 (0x0000001A) DRIVER_TOO_MANY_UNITS 27 (0x0000001B) DRIVER_TOO_MANY_COMMANDS

描述 GENERIC_CHANNEL_OFFLINE。 在用户配置时间未收到任何响应。这一错误将映射到通用错 误 GENERIC_UNIT_TIMEOUT。 服务器的设备号没有激活或超出范围。这一错误将映射到通 用错误 GENERIC_UNIT_OFFLINE。 设备没有在线。这一错误将映射到通用错误 GENERIC_UNIT_OFFLINE。 驱动程序不能识别服务器的数据类型。这一错误将映射到通 用错误 GENERIC_INVALID_DATA_TYPE。 驱动程序不能识别服务器的设备类型。这一错误将映射到通 用错误 GENERIC_INVALID_DATA_TYPE。 为通道指定了太多设备。这一错误将映射到通用错误 GENERIC_TOO_MANY_UNITS。 向驱动程序发送的命令太多。如果运行的是受限制的驱动程 序版本(即要在有限时间内运行的驱动程序),此错误代码也 可能针对所有已发出的读写命令出现。这一错误将映射到通用 错误 GENERIC_TOO_MANY_COMMANDS。 命令被取消。这一错误将映射到通用错误 GENERIC_COMMAND_CANCELLED。 地址/长度超界。这一错误将映射到通用错误 GENERIC_ADDRESS_RANGE_ERROR。 来自服务器的数据长度错误。这一错误将映射到通用错误 GENERIC_INVALID_RESPONSE。 不能读设备数据。这一错误将映射到通用错误 GENERIC_INVALID_DATA。 设备定义不存在。这一错误将映射到通用错误 GENERIC_HARDWARE_ERROR。 指定的设备不支持中断。这一错误将映射到通用错误 GENERIC_HARDWARE_ERROR。 端口数据库中的特殊选项无效。这一错误将映射到通用错误 GENERIC_BAD_PARAMETER。 无法写入变量。这一错误将映射到通用错误 GENERIC_GENERAL_ERROR。

29 (0x0000001D) DRIVER_CMD_CANCELED 30 (0x0000001E) DRIVER_ADDRESS_RANGE_ERROR 31 (0x0000001F) DRIVER_DATA_LENGTH_ERROR 32 (0x00000020) DRIVER_BAD_DATA 33 (0x00000021) DRIVER_DEVICE_NOT_EXIST 34 (0x00000022) DRIVER_DEVICE_NO_INTERRUPT 35 (0x00000023) DRIVER_BAD_SPECIAL 36 (0x00000024) DRIVER_CANNOT_WRITE

70

Chapter: 3 参考信息

错误 37 (0x00000025) DRIVER_NO_MEMORY

描述 驱动程序已用尽了所有内存空间,无法继续执行。最大限度 缩小缓冲区和队列分配,或扩展计算机的内存(物理或虚拟内 存)。这一错误将映射到通用错误 GENERIC_NO_MEMORY。

71

Chapter: 4

CtAPI 函数

Vijeo Citect API 在 CTAPI 中,可以通过 DLL 界面访问 Vijeo Citect I/O 标签变量。这样,第三方开发人员 可以用 C 语言(或其它语言)创建应用程序来读取或写入 I/O 设备。 所需的文件有 ctapi.dll、ctapi.lib 和 ctapi.h,它们位于 [bin] 目录。 在远程计算机中使用 CTAPI 要在不安装 Vijeo Citect 的情况下在远程计算机上使用 CTAPI,需要将以下文件从 [bin] 目 录复制到远程计算机中:ctapi.dll、ct_ipc.dll、cteng32.dll、ctres32.dll、ctutil32.dll 和 CiDebugHelp.dll。请注意,从远程计算机连接到 CTAPI 之前,必须在工程中定义用户。 在 Windows 2000 中使用 CTAPI 在使用 CTAPI 的 Windows 2000 中运行应用程序时,需要将以下文件从 [bin] 目录复制到 应用程序所在的同一目录:ct_ipc.dll、cidebughlp.dll、dbghelp.dll 和 ctutil32.dll。 向后兼容问题 未归档的 API 以 Vijeo Citect 16 位版本的方式提供。由于 16 位 API 与 32 位环境不兼容, 因此实现了新的 API 来替换旧版本。CTAPI 与以前的 CT_VAR 及 CTUSER API 不兼容。 由于需要对 32 位环境进行更改,因此无法兼容 CTAPI。将应用程序从较早的 API 转换为 新的 CTAPI 所需的更改很少。 另请参见 I/O 点数 CtAPI 同步操作 使用 CTAPI 函数读取数据 来自 Vijeo Citect 或 Vijeo Citect 驱动程序的 CTAPI 错误代码 调试跟踪 函数引用

I/O 点数
使用 CTAPI 读取或写入的物理 I/O 设备标签是作为动态 Vijeo Citect 点进行计算的。如果 对此接口的调用超过点数限制,则该调用将失败,并且不会再为 Vijeo Citect 分配动态点。 如果 I/O 设备标签已作为静态点计算,则系统不会再次计算它们,也不会添加到动态点 数。

72

Chapter: 4 CtAPI 函数

注意:Vijeo Citect 的许可证以使用的点数为基准。系统中的每个标签都有可能添加到点数 中。记住这一点并正确计划系统非常重要,否则可能会超过点数限制。有关更多详细信 息,请参见 Vijeo Citect 许可点数。 点数限制是可以读取的 I/O 设备地址(变量标签)的最大数量,由 Vijeo Citect 许可证指 定。Vijeo Citect 会在运行时动态计算所有 I/O 设备地址。其中包括报警、趋势、报告、事 件、页面中使用的所有标记,超级精灵中的所有标记,使用 TagRead() 和 TagWrite() Cicode 函数的所有标记或者使用 DDE、ODBC 或 CTAPI 读取或写入的所有标记。 系统不会在编译时静态计算任何点。 当系统运行时,任何通过超级精灵、DDE、ODBC 或 CTAPI 最新使用的标记都有可能添 加到动态点数中。 另请参见 Vijeo Citect API 同步操作

CtAPI 同步操作
Vijeo Citect CTAPI 既支持同步操作也支持异步(或重叠)操作。ctCicode()、ctListRead() 和 ctListWrite() 函数可以同步或异步执行。ctTagRead() 和 ctTagWrite() 函数只能同步执 行。 同步执行函数时,操作完成前它不会返回。这意味着,调用线程会在等待耗时的操作完成 时无限期地被阻止执行。为重叠操作调用的函数可以立即返回,即使操作尚未完成也无 妨。这使得耗时的 I/O 操作可以在后台执行,同时调用线程可以自由地执行其他任务。例 如,单一线程可以对不同句柄同时执行操作,或者对同一句柄同时执行读取和写入操作。 为了将其执行与重叠操作的完成同步,调用线程使用 ctGetOverlappedResult() 函数或其 中一个等待函数来确定重叠操作的完成时间。也可以使用 ctHasOverlappedIoCompleted() 宏来查询是否完成。 要调用函数来执行重叠操作,调用线程必须指定指向 CTOVERLAPPED 结构的指针。如 果此指针为 NULL,则函数返回参数值可能会不正确地指示操作完成。CTOVERLAPPED 结构必须包含指向手动重置而非自动重置事件对象的句柄。当对 I/O 函数的调用在操作完 成之前返回时,系统会将事件对象的状态设置为未发出信号。当操作完成时,系统会将事 件对象的状态设置为已发出信号。 当调用函数来执行重叠操作时,操作有可能在函数返回之前完成。如果出现这种情况,结 果会得到处理,就像操作已经同步完成一样。不过,如果操作未完成,则函数的返回参数 值为 FALSE,且 GetLastError() 函数会返回 ERROR_IO_PENDING。 线程可通过下列两种方法中的任意一种管理重叠操作: ? 使用 ctGetOverlappedResult() 函数等待重叠操作完成。 ? 在其中一个等待函数中指定一个指向 CTOVERLAPPED 结构的手动重置事件对象的 句柄,然后在等待函数返回后调用 ctGetOverlappedResult()。

73

Chapter: 4 CtAPI 函数

ctGetOverlappedResult() 函数返回已完成重叠操作的结果,而且对于此类信息适当的 函数,它会报告传输的实际字节数。 执行多个同时的重叠操作时,调用线程必须为每个操作指定一个与手动重置事件对象不同 的 CTOVERLAPPED 结构。为了等待任何一个重叠操作完成,线程在多对象等待函数的 其中一个中将所有手动重置事件句柄指定为等待标准。该多对象等待函数的返回参数值指 明已为哪个手动重置事件对象发出了信号,以便线程可以确定是哪个重叠操作促使等待操 作完成的。 可以使用 ctCancelIO() 函数取消待决异步操作。调用 ctClose() 时,会取消所有待决异步操 作。 使用 CTAPI 函数读取数据

使用 CTAPI 函数读取数据
? ? ? ? ? I/O 标签接口 标签函数 列表函数 阵列支持 读取数字量阵列时位移

另请参见 函数参考

I/O 标签接口
Vijeo Citect I/O 服务器是根据读取的需要在客户机上设计的。Vijeo Citect I/O 服务器会在 客户机发出请求时从 I/O 设备读取 I/O 标签。这样会减少 I/O 设备的负荷并提高系统整体 性能。 实时数据的客户机接口比较复杂,有位客户机必须在能够使用数据之前等待物理 I/O 周期 完成。客户机必须从 I/O 服务器请求所需的数据,然后在 I/O 服务器读取所有请求的数据 时等待几秒。此设计反映在 CTAPI 接口的操作中。使用 CTAPI 读取标记需要花费几秒钟 完成。这取决于调用此接口时允许在其设计中使用此标记的调用方。 如果需要使用服务的轮询类型,请使用 ctList 函数。 另请参见 标签函数

标签函数
读取数据的最简单方法是通过 ctTagRead() 函数。此函数读取单独变量的值,作为特定格 式的工程字符串返回结果。

74

Chapter: 4 CtAPI 函数

列表函数
List 函数提供了比基于标签的接口级别更高级别的数据读取性能,还提供了对重叠操作的 支持。 可通过列表函数定义一组标签,然后作为一个请求读取。这些函数针对以特定工程数据格 式提供的数据提供一个基于标签的简单接口。可以创建数个列表并单独控制每个列表。 标签可以动态地添加到列表或从列表中删除,即使列表中有待执行的读操作也不例外。 另请参见 数组支持

数组支持
数组在标签函数 ctTagWrite() 和 ctTagRead() 中受支持。这些函数可以将单个标签名视为 "PV123",也可以将数组语法用作 "Recipe[10]"。在 "Recipe[10]" 示例中使用数组语法时, 可以读取或写入单个值,而不是整个数组。 另请参见 读取数字数组时的位移

读取数字量数组时位移
读取数字量类型时,Vijeo Citect 可能会调整第一点的起始位置。这样做是为了提高数字量 读取的性能。例如,如果开始读取一组数字量数值,Vijeo Citect 可能会读取数组起始前的 几个数字量,然后将数据偏移。当 Vijeo Citect 作位移时,将会从 I/O 设备读取额外的数 据。Vijeo Citect 可能最多位移 15 位,结果需要额外 2 个字节的读取缓冲区空间。因此, 应始终使用包含 2 个额外字节的数字量缓冲区。

来自 Vijeo Citect 或 Vijeo Citect 驱动程序的 CTAPI
CTAPI 设计为从外部应用程序进行调用。此 API 未设计为从 Vijeo Citect Cicode DLL 函数 或从 Vijeo Citect 协议驱动程序调用。从 Cicode DLL 函数或 Vijeo Citect 协议驱动程序调 用 CTAPI 可能会引起死锁情况的发生,从而导致 Vijeo Citect 和协议驱动程序死机。如果 需要从协议驱动程序调用 CTAPI,则必须创建新的 Win32 线程调用 API。不能从 Cicode DLL 接口调用 CTAPI。 另请参见 函数引用 错误代码

75

Chapter: 4 CtAPI 函数

错误代码
从 CTAPI 函数返回的错误代码为 Microsoft WIN 32 错误代码。这些错误代码都在 Microsoft SDK 中说明。如果错误代码是一个特殊的 Vijeo Citect 错误代码,则该错误代码 将被添加到值 -ERROR_USER_DEFINED_BASE。 注意:如果 CTAPI 函数返回错误 233,通常表示未建立与客户端的连接。但是,也可能表 示该客户端未正确登录。因此,您应该对这两种可能都进行确认。 范例
int bRet = ctTagWrite(hCTAPI, "SP123", "12.34"); if (bRet == 0) { dwStatus = GetLastError(); if (dwStatus < ERROR_USER_DEFINED_BASE) { // Microsoft error codes see ERROR.H } else { short status; // status is theVijeo Citect error codes, see Vijeo Citect help status = dwStatus - ERROR_USER_DEFINE_BASE; } }

以下定义使得此检查更为简单:
IsCitectError(dwStatus) // test if Vijeo Citect error WIN32_TO_CT_ERROR(dwStatus) // Convert to Vijeo Citect status

例如:
if (IsCitectError(dwStatus)) { short status; // status is the Vijeo Citect error codes, see Vijeo Citect help status = WIN32_TO_CT_ERROR(dwStatus); }

如果您的应用程序与 Vijeo Citect 间的连接断开,则您必须关闭该连接,然后再重新打开。 返回的 Microsoft 错误代码将显示连接故障。如果返回一个 Vijeo Citect 状态错误,则表示 连接完好。请求的命令无效,且无需关闭并重新打开连接。
int bRet = ctTagWrite(hCTAPI, "SP123", "12.34"); if (bRet == 0) { dwStatus = GetLastError(); if (dwStatus < ERROR_USER_DEFINED_BASE) { ctClose(hCTAPI); hCTAPI = ctOpen(NULL, NULL, NULL, 0); while (hCTAPI == NULL) { Sleep(2000); // wait a while hCTAPI = ctOpen(NULL, NULL, NULL, 0);

76

Chapter: 4 CtAPI 函数

} } }

当您的应用程序与 Vijeo Citect 间的连接断开时,任何等待完成的重叠命令将会超时,并将 被 CTAPI 取消。您必须销毁所有与连接有关的句柄。 在 5.10 版本中,CT_OPEN_RECONNECT 模式被添加到 ctOpen() 中。当启用此模式时, 如果发生故障,CTAPI 将会重新建立与 Vijeo Citect 的连接。连接中建立的所有句柄在重 建的连接中仍是有效的。当连接失败时,所有函数也会失败,并含有错误状态。 另请参见 调试追踪

调试跟踪
已将 CTAPI 的调试跟踪添加到内核中。可以在主内核窗口中用命令 CTAPI 1 启用调试跟 踪。CTAPI 0 将禁止调试跟踪。还可以通过设置 CITECT.INI 参数启用调试跟踪:
[CTAPI] Debug=1

调试跟踪会将每个客户机 CTAPI 流量显示到 Vijeo Citect。如果出现大量通讯,此跟踪可 能会降低 Vijeo Citect 和 CTAPI 客户机的性能。 调试跟踪显示在主 Vijeo Citect 内核窗口中,并记录在 syslog.dat 文件中。

函数参考
在 CTAPI 函数中,可以通过 DLL 界面访问 Vijeo Citect I/O 标签变量。这样,第三方程序 员就可以用 C 或其它语言创建应用程序,以便读写 I/O 设备。

函数 ctCancelIO

参数 hCTAPI、pctOverlapped

类型 布尔

描述 取消等待的重 叠 I/O 操作。 执行 Cicode 函数。 关闭与 Vijeo Citect API 的 连接。 将工程缩放变 量转换为原始 的 I/O 设备刻

ctCiCode

hCTAPI、sCmd、hWin、nMode、sResult、dwLength、 pctOverlapped hCTAPI

布尔

ctClose

布尔

ctEngToRaw

pResult、dValue、pScale、dwMode

布尔

77

Chapter: 4 CtAPI 函数

函数

参数

类型

描述 度大小。

ctFindClose

hnd

布尔

关闭一个由 ctFindFirst() 启动的搜索。 搜索指定数据 库中能满足过 滤字符串的第 一个对象。 搜索指定数据 库中能满足簇 指定的过滤字 符串的第一个 对象。 检索由 ctFindFirst() 启动的搜索中 的下一个对 象。 检索由 ctFindFirst() 启动的搜索中 的上一个对 象。 滚动到由 ctFindFirst() 启动的搜索中 需要的对象。 返回覆盖操作 的结果。 检索对象属 性。 检查未完成的 I/O 操作是否 已完成。 向列表添加标 签。 向具有指定轮 训周期的列表 添加标签。 获取列表上标

ctFindFirst

hCTAPI、szTableName、szFilter、pObjHnd、dwFlags

句柄

ctFindFirstEx

hCTAPI、szTableName、szFilter、szCluster、pObjHnd、 dwFlags

句柄

ctFindNext

hnd、pObjHnd

布尔

ctFindPrev

hnd、pObjHnd

布尔

ctFindScroll

hnd、dwMode、dwOffset、pObjHnd

句柄

ctGetOverlappedResult

hCTAPI、lpctOverlapped、pBytes、bWait

布尔

ctGetProperty

hnd、szName、pData、dwBufferLength、 dwResultLength、dwType lpctOverlapped

布尔

ctHasOverlappedIoCom pleted

布尔

ctListAdd

hList、sTag

句柄

ctListAddEx

hList、sTag、bRaw、nPollPeriodMS、dDeadband

句柄

ctListData

hTag、pObjHnd、dwLength、dwMode

布尔

78

Chapter: 4 CtAPI 函数

函数

参数

类型

描述 签的值。

ctListDelete

hTag

布尔

释放 ctListAdd() 创建的标签。 返回自上一次 用 ctListRead() 函数读取后状 态改变的元素 列表。 释放 ctListNew() 创建的列表。 创建新列表。 读取列表上的 所有标签。 写入列表上的 一个标签。 打开与 Vijeo Citect API 的 连接。 使用给定的客 户端实例建立 与 CtAPI 服务 器的连接。 将原始的 I/O 设备刻度变量 转换为工程标 度。 获取给定标签 的给定属性。 读取给定 I/O 设备标签变量 的当前值。 将给定值写入 I/O 设备标签 变量。 同步将给定值 写入 I/O 设备

ctListEvent

hCTAPI、dwMode

句柄

ctListFree

hList

布尔

ctListNew ctListRead

hCTAPI、dwMode hList、pctOverlapped

句柄 布尔

ctListWrite

hTag、sValue、pctOverlapped

布尔

ctOpen

sComputer、sUser、sPassword、nMode

句柄

ctOpenEx

sComputer、sUser、sPassword、nMode、hCTAPI

句柄

ctRawToEng

pResult、dValue、pScale、dwMode

布尔

ctTagGetProperty

hCTAPI、szTagName、 szProperty、pData、dwBufferLength、dwType hCTAPI、sTag、sValue、dwLength

布尔

ctTagRead

布尔

ctTagWrite

hCTAPI、sTag、sValue

布尔

ctTagWriteEx

hCTAPI、sTag、sValue、pctOverlapped

布尔

79

Chapter: 4 CtAPI 函数

函数

参数

类型

描述 标签变量。

ctCancelIO
取消等待的重叠 I/O 操作。取消 I/O 命令时,将向事件发出信号以显示命令已完成。状态 将被设置为 Vijeo Citect 错误 CT_ERROR_CANCELED。如果命令在取消之前完成,则 ctCancelIO() 将返回 FALSE,GetLastError() 将返回 GENERIC_CANNOT_CANCEL。 交叠操作的状态将变为命令的完成状态。 CTAPI 接口将在调用 ctClose() 时自动取消所有等待的 I/O 命令。 语法 ctCancelIO(hCTAPI,pctOverlapped) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 pctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:指向要取消的交叠 I/O 操作的指针。如果指定 NULL,则接口中的所有等 待交叠 I/O 操作将被取消。 返回参数值 如果函数成功,则返回参数值为 TRUE。如果函数失败,则返回参数值为 FALSE。要获得 扩展错误信息,请调用 GetLastError。 相关函数 ctOpen、ctClose 范例
char sVersion[128]; CTOVERLAPPED ctOverlapped; ctOverlapped.hEvent = CreateEvent(NULL, TRUE, TRUE, NULL); ctCicode(hCTAPI, "Version(0)", 0, 0, sVersion, sizeof(sVersion), &ctOverlapped); ctCancelIO(hCTAPI, &ctOverlapped);

80

Chapter: 4 CtAPI 函数

ctCiCode
在连接的 Vijeo Citect 计算机中执行 Cicode 函数。通过此操作,可以控制 Vijeo Citect 或 获取从 Cicode 函数返回的信息。可以调用内置或用户定义的 Cicode 函数。取消等待的重 叠 I/O 操作。 函数名称和该函数使用的参数作为单个字符串传递。标准 Vijeo Citect 转换适用于将数据从 字符串类型转换为函数期望的类型。传递字符串时,字符串应置于 Vijeo Citect 字符串分隔 符之间。 不支持期望使用指针或数组的函数。期望使用指针或数组的函数是用于更新参数的函数。 其中包括 DspGetMouse()、DspAnGetPos()、StrWord() 等函数。不支持期望使用要传递 或返回的数组的函数,如 TableMath()、TrnSetTable()、TrnGetTable()。通过调用 Cicode 包装函数并依次调用所需函数,可以解决这些限制。 如果调用的 Cicode 函数执行时间过长、被抢占或停滞,则函数的结果无法在 sResult 参数 中返回。但 Cicode 函数会正确执行。 语法 ctCiCode(hCTAPI,sCmd,hWin,nMode,sResult,dwLength,pctOverlapped) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 sCmd 类型:String 输入/输出:输入 描述:要执行的命令。 vhWin 类型:Dword 输入/输出:输入 描述:执行函数的 Vijeo Citect 窗口。这是逻辑 Vijeo Citect 窗口(0、1、2、3 等),不是 Windows 句柄。 nMode 类型:Dword 输入/输出:输入 描述:Cicode 调用的模式。将其设置为 0(零)。 sResult 类型:LPSTR 输入/输出:输出

81

Chapter: 4 CtAPI 函数

描述:存放函数调用结果的缓冲区,始终作为字符串返回。如果不需要函数的结 果,则可以为 NULL。 dwLength 类型:Dword 输入/输出:输入 描述:sResult 缓冲区的长度。如果 Cicode 函数的结果大于这个数值,则不返回 结果且函数调用失败,但 Cicode 函数仍然执行。如果 sResult 为 NULL,则此长 度必须为 0。 pctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:CTOVERLAPPED 结构。此结构用于控制重叠通知。如果希望同步函数调 用,则将其设置为 NULL。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 可获得扩展错误信息。 相关函数 ctOpen 范例
char sName[32]; ctCicode(hCTAPI, "AlarmAck(0,0)", 0, 0, NULL, 0, NULL); ctCicode(hCTAPI, "PageInfo(0)", 0, 0, sName, sizeof(sName), NULL); /* to call the Prompt function with the string "Hello Citect", the C code would be: */ ctCicode(hCTAPI, "Prompt(\"Hello Citect\")", 0, 0, NULL, 0, NULL); /* If the string does not contain any delimiters (eg spaces or commas) you may omit the string delimiters. For example to display a page called "Menu" the C code would be: */ ctCicode(hCTAPI, "PageDisplay(Menu)", 0, 0, NULL, 0, NULL);

ctClientCreate
ctClientCreate 为新的 CtAPI 客户机实例初始化资源。调用 ctClientCreate 后,可以传递返 回到 ctOpenEx 的句柄来建立与 CtAPI 服务器的通讯。 设想这样一种情况,我们尝试与 CtAPI 服务器通讯,但服务器响应时间过长(或根本不响 应)。如果只调用 ctOpen,则无法将句柄分配给 CtAPI 实例,也无法通过调用 ctCancelIO 取消 ctOpen。但如果使用 ctClientCreate 然后调用 ctOpenEx,则可以使用 ctClientCreate 返回的句柄取消 ctOpenEx。

82

Chapter: 4 CtAPI 函数

语法 ctClientCreate 返回参数值 如果函数成功,则返回参数值指定一个句柄。如果函数失败,返回参数值为 NULL。使用 GetLastError() 可获取扩展错误信息。 相关函数 ctOpen、ctOpenEx、ctClose、ctCloseEx、ctClientDestroy 范例
DWORD dwStatus = 0; HANDLE hCtapi = ctClientCreate(); if (hCtapi == NULL) { dwStatus = GetLastError(); // An error has occurred, } else { if (TRUE == ctOpenEx(NULL, NULL, NULL, 0, hCtapi)) { ctTagWrite(hCtapi, "Fred", "1.5"); if (FALSE == ctCloseEx(hCtapi, FALSE)) { dwStatus = GetLastError(); // An error has occurred, } } else { dwStatus = GetLastError(); // An error has occurred, } if (FALSE == ctClientDestroy(hCtapi)) { dwStatus = GetLastError(); // An error has occurred, } }

trap it.

trap it.

trap it.

trap it

ctClientDestroy
清除给定 CtAPI 实例的资源。与 ctClose 不同,ctClientDestroy 不会关闭到 CtAPI 服务器 的连接。 调用 ctClientDestroy 之前必须调用 bDestroy 等于 FALSE 的 ctCloseEx。 语法 ctClientDestroy(hCTAPI) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 可获取扩展错误信息。

83

Chapter: 4 CtAPI 函数

相关函数 ctCloseEx、ctClose、ctClientCreate、ctOpen、ctOpenEx 范例 有关范例,请参见 ctClientCreate。

ctClose
关闭应用程序与 CtAPI 之间的连接。调用此函数时,所有等待的命令都将被取消。调用 ctClose() 之前必须释放任何分配的句柄。调用 ctClose() 后将无法释放这些句柄。应用程序 应在关闭或连接出现致命错误时调用此函数。 语法 ctClose(hCTAPI) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 可获取扩展错误信息。 相关函数 ctOpen 范例 请参见 ctOpen() 的范例。

ctCloseEx
针对给定 CtAPI 实例关闭到 CtAPI 服务器的连接。关闭连接的方式与 ctClose 方法的关闭 方式相同,但前者提供是否破坏 ctCloseEx 函数调用内 CtAPI 实例的选项,而后者始终破 坏 ctCloseEx 函数调用内 CtAPI 实例。 例如,设想这样一种情况:我们尝试关闭到 CtAPI 服务器的连接,但响应时间过长(或根 本不响应)。如果调用 ctClose,则无法通过调用 ctCancelIO 取消 ctClose,因为无法保证 CtAPI 实例是否正处于被破坏的过程中。但如果调用带有不破坏 CtAPI 实例选项的 ctCloseEx,则可以调用 ctCancelIO 取消 ctCloseEx。 调用 bDestroy 等于 FALSE 的 ctCloseEx 时,随后必须调用 ctClientDestroy 释放 CtAPI 客 户机实例。

84

Chapter: 4 CtAPI 函数

语法 ctCloseEx(hCTAPI,bDestroy); hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 bDestroy 类型:boolean 输入/输出:输入 描述:如果为 TRUE,则破坏 ctCloseEx 函数调用内的 CtAPI 实例。缺省值为 FALSE。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 可获取扩展错误信息。 相关函数 ctClientDestroy、ctClose、ctClientCreate、ctOpen、ctOpenEx 范例 有关范例,请参见 ctClientCreate。

ctEngToRaw
将工程缩放变量转换为原始的 I/O 设备刻度大小。这对于 Tag 函数不是必需的,因为 Vijeo Citect 将进行缩放。无需对数字、字符串进行缩放,如果 I/O 设备中的值或工程值之间未 出现缩放,也不需要进行缩放。必须了解对 Vijeo Citect 标签变量表格中指定的每个变量的 进行缩放。 语法 ctEngToRaw(pResult,dValue,pScale,dwMode) pResult 类型:Double 输入/输出:输出 描述:结果原始缩放变量。 dValue 类型:Double 输入/输出:输入 描述:要缩放的工程值。 pScale

85

Chapter: 4 CtAPI 函数

类型:CTSCALE* 输入/输出:输入 描述:变量的缩放属性。 dwMode 类型:Dword 输入/输出:输入 描述:缩放的模式: CT_SCALE_RANGE_CHECK:范围检查结果。如果变量超出范围,则产生错 误。pResult 仍包含原始缩放值。 CT_SCALE_CLAMP_LIMIT:将限制钳位在最大或最小刻度。如果结果超出客 户范围,则将结果设置为最小或最大客户(以最接近的值为准)。如果钳 位刻度,则不会产生错误。不能与 CT_SCALE_RANGE_CHECK 或 CT_SCALE_NOISE_FACTOR 选项配合使用。 CT_SCALE_NOISE_FACTOR:允许将噪音系数用于对限制的范围检查。如果 变量超出范围小于 0.1 %,则不会产生范围错误。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 可获得扩展错误信息。 相关函数 ctOpen、ctRawToEng、ctTagRead 范例
CTSCALE Scale = { 0.0, 32000.0, 0.0, 100.0}; double dSetPoint = 42.23; double dRawValue; ctEngToRaw(&dRawValue, dSetPoint, &Scale, CT_SCALE_RANGE_CHECK);

ctFindClose
关闭由 ctFindFirst 发起的搜索。 语法 ctFindClose(hnd) hnd 类型:Handle 输入/输出:输入 描述:要查找的句柄,由 ctFindFirst() 返回。

86

Chapter: 4 CtAPI 函数

返回参数值 如果函数成功,则返回参数值非零。如果函数失败,则返回参数值为零。要获得扩展错误 信息,请调用 GetLastError()。 相关函数 ctOpen、ctFindNext、ctFindPrev、ctFindScroll、ctGetProperty 范例 请参见 ctFindFirst。

ctFindFirst
在指定表格、设备、趋势或报警数据中搜索满足过滤字符串的第一个对象。找到的对象通 过 pObjHnd 返回一个句柄。对象句柄用于检索对象属性。要查找下一个对象,请通过返 回的搜索句柄调用 ctFindNext 函数。 如果在使用 ctFindFirst() 时遇到服务器性能问题,则应引用 CPULoadCount 和 CpuLoadSleepMS。 语法 ctFindFirst(hCTAPI,szTableName,szFilter,pObjHnd,dwFlags) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 szTableName 类型:LPCTSTR 输入/输出:输入 描述:要搜索的表格、设备、趋势或报警数据。可以搜索以下表格和字段: ? Trend - 趋势标签 CLUSTER、NAME/TAG、RAW_ZERO、RAW_FULL、ENG_ZERO、ENG_FULL、 ENG_UNITS、COMMENT、SAMPLEPER、TYPE ? DigAlm - 数字量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT ? AnaAlm - 模拟量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、DEADBAND、 RATE、DEVIATION、ALMCOMMENT ? AdvAlm - 高级报警标签

87

Chapter: 4 CtAPI 函数

CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT ? HResAlm - 带时间标签的报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、 MILLISEC、DATE、AREA、ALMCOMMENT ? ArgDigAlm - 多状态数字量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT、PRIORITY、STATE_DESC、OLD_DESC ? ArgAnaAlm - 多状态模拟量报警标签 CLUSTER、TAG、NAME、HELP、ALMCOMMENT、CATEGORY、STATE、 TIME、DATE、AREA、VALUE、PRIORITY、HIGH、LOW、HIGHHIGH、 LOWLOW、DEADBAND、RATE、DEVIATION ? TsDigAlm - 带时间标签的数字量报警标签 CLUSTER、TAG、NAME、DESC、CATEGORY、AREA、ALMCOMMENT ? TsAnaAlm - 带时间标签的模拟量报警标签 CLUSTER、TAG、NAME、DESC、CATEGORY、AREA、ALMCOMMENT ? ArgDigAlmStateDesc - 多状态数字量报警标签状态描述 CLUSTER、TAG、STATE_DESC0、STATE_DESC1、STATE_DESC2、 STATE_DESC3、STATE_DESC4、STATE_DESC5、STATE_DESC6、STATE_DESC7 ? Alarm - 报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT、VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、 DEADBAND、RATE、DEVIATION、PRIORITY、STATE_DESC、OLD_DESC、 ALARMTYPE ? AlarmSummary - 报警汇总 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、TIME、DATE、AREA、 VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、DEADBAND、RATE、 DEVIATION、PRIORITY、STATE_DESC、OLD_DESC、ALARMTYPE、 ONDATE、ONDATEEXT、ONTIME、ONMILLI、OFFDATE、OFFDATEEXT、 OFFTIME、OFFMILLI、DELTATIME、ACKDATE、ACKDATEEXT、ACKTIME、 ALMCOMMENT、USERNAME、FULLNAME、USERDESC、SUMSTATE、 SUMDESC、NATIVE_SUMDESC、COMMENT、NATIVE_COMMENT ? Accum - 累积器 PRIV、AREA、CLUSTER、NAME、TRIGGER、VALUE、RUNNING、STARTS、 TOTALISER ? Tag - 标签变量 ? LocalTag - 本地标签 ? Cluster - 集群 有关字段的信息,请参见 浏览函数字段引用。

注意:Vijeo Citectv7.10 中的迁移工具将单独表格的本地标签变量中的所有内存 PLC 变量
转换为标签变量。调用 szTableName 为“Tag”的 ctFindFirst 不会返回本地标签变量。为了

88

Chapter: 4 CtAPI 函数

返回本地标签变量,必须调用 szTableName 为“LocalTag”的 ctFindFirst。本地变量不包含 集群,并只包含一对零刻度/满刻度(与用于标签变量的原始刻度及工程标度相反)。 本地标签变量的字段名称为: NAME、TYPE、ASIZE(数组大小)、ZERO、FULL、UNITS、COMMENT。 数字大小字段仅在本地标签中可用。 szFilter 类型:LPCTSTR 输入/输出:输入 描述:过滤标准。这是基于以下格式的字符串: "PropertyName1=FilterCriteria1;PropertyName2=FilterCriteria2" 通配符 * 可用作匹配多个条目的一部分过滤标准。使用空字符串或 "*" 可以作为 匹配所有条目的过滤字符串。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。 dwFlags 此参数不再使用,应为此参数传递的值为 0。 如何搜索表格: 在 szTableName 中指定表格的名称。 如何搜索设备: 在 szTableName 中将名称指定为 Vijeo Citect 设备表中定义的名称(如 Example 工程中的 "RECIPES"。 如何搜索趋势数据: 在 szTableName 中使用以下格式(包括括号)指定趋势: `TRNQUERY,Endtime,EndtimeMs,Period,NumSamples,Tagname,Displaymode,Datamode' 有关语法的详细信息,请参见 TrnQuery。 如何搜索报警数据: 在 szTableName 中使用以下格式(包括括号)指定报警数据: `ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period' 有关语法的详细信息,请参见 AlmQuery。

89

Chapter: 4 CtAPI 函数

返回参数值 如果函数成功,返回参数值为随后调用 ctFindNext() 或 ctFindClose() 时使用的搜索句柄。 如果函数失败,返回参数值为 NULL。要获得扩展错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctFindNext、ctFindClose、ctGetProperty、ctFindFirstEx 范例
HANDLE hSearch; HANDLE hObject; HANDLE hFind; // Search the Tag table hSearch = ctFindFirst(hCTAPI, "Tag", NULL, &hObject, 0); if (hSearch == NULL) { // failed no tags found } else { do { char sName[32]; // Get the tag name ctGetProperty(hObject, "Tag", sName, sizeof(sName), NULL, DBTYPE_STR); } while (ctFindNext(hSearch, &hObject)); ctFindClose(hSearch); } // Get Historical Trend data via CTAPI // Get 100 samples of the CPU trend at 2 second hFind = ctFindFirst(hCTAPI, "CTAPITrend(\"10:15:00 \", \"11/8/1998\", 2, 100, 0, \"CPU\")", &hObject, 0); while (hFind) { char sTime[32], sDate[32], sValue[32]; ctGetProperty(hObject, "TIME", sTime, sizeof(sTime), NULL, DBTYPE_STR); ctGetProperty(hObject, "DATE", sDate, sizeof(sDate), NULL, DBTYPE_STR); ctGetProperty(hObject, "CPU", sValue, sizeof(sValue), NULL, DBTYPE_STR); // do something with the trend data. if (!ctFindNext(hFind, &hObject)) { ctFindClose(hFind); hFind = NULL; break; } }

ctFindFirstEx
执行的操作与 ctFindFirst 相同,但包含其它新的参数。在指定表格、设备、趋势或报警数 据中搜索满足过滤字符串的第一个对象。找到的对象通过 pObjHnd 返回一个句柄。对象 句柄用于检索对象属性。要查找下一个对象,请通过返回的搜索句柄调用 ctFindNext 函 数。 如果在使用 ctFindFirst() 时遇到服务器性能问题,则应引用 CPULoadCount 和 CpuLoadSleepMS。 如果调用的是 ctFindFirst 而不是 ctFindFirstEx,则 szCluster 的缺省值为 NULL。

90

Chapter: 4 CtAPI 函数

语法 ctFindFirstEx(hCTAPI,szTableName,szFilter,szCluster,pObjHnd,dwFlags) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 szTableName 类型:LPCTSTR 输入/输出:输入 描述:要搜索的表格、设备、趋势或报警数据。可以搜索以下表格和字段: ? Trend - 趋势标签 CLUSTER、NAME/TAG、RAW_ZERO、RAW_FULL、ENG_ZERO、ENG_FULL、 ENG_UNITS、COMMENT、SAMPLEPER、TYPE ? DigAlm - 数字量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT ? AnaAlm - 模拟量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、DEADBAND、 RATE、DEVIATION、ALMCOMMENT ? AdvAlm - 高级报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT ? HResAlm - 带时间标签的报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、 MILLISEC、DATE、AREA、ALMCOMMENT ? ArgDigAlm - 多状态数字量报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT、PRIORITY、STATE_DESC、OLD_DESC ? ArgAnaAlm - 多状态模拟量报警标签 CLUSTER、TAG、NAME、HELP、ALMCOMMENT、CATEGORY、STATE、 TIME、DATE、AREA、VALUE、PRIORITY、HIGH、LOW、HIGHHIGH、 LOWLOW、DEADBAND、RATE、DEVIATION ? TsDigAlm - 带时间标签的数字量报警标签 CLUSTER、TAG、NAME、DESC、CATEGORY、AREA、ALMCOMMENT ? TsAnaAlm - 带时间标签的模拟量报警标签 CLUSTER、TAG、NAME、DESC、CATEGORY、AREA、ALMCOMMENT ? ArgDigAlmStateDesc - 多状态数字量报警标签状态描述 CLUSTER、TAG、STATE_DESC0、STATE_DESC1、STATE_DESC2、 STATE_DESC3、STATE_DESC4、STATE_DESC5、STATE_DESC6、STATE_DESC7

91

Chapter: 4 CtAPI 函数

? Alarm - 报警标签 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、STATE、TIME、DATE、 AREA、ALMCOMMENT、VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、 DEADBAND、RATE、DEVIATION、PRIORITY、STATE_DESC、OLD_DESC、 ALARMTYPE ? AlarmSummary - 报警汇总 CLUSTER、TAG、NAME、DESC、HELP、CATEGORY、TIME、DATE、AREA、 VALUE、HIGH、LOW、HIGHHIGH、LOWLOW、DEADBAND、RATE、 DEVIATION、PRIORITY、STATE_DESC、OLD_DESC、ALARMTYPE、 ONDATE、ONDATEEXT、ONTIME、ONMILLI、OFFDATE、OFFDATEEXT、 OFFTIME、OFFMILLI、DELTATIME、ACKDATE、ACKDATEEXT、ACKTIME、 ALMCOMMENT、USERNAME、FULLNAME、USERDESC、SUMSTATE、 SUMDESC、NATIVE_SUMDESC、COMMENT、NATIVE_COMMENT ? Accum - 累积器 PRIV、AREA、CLUSTER、NAME、TRIGGER、VALUE、RUNNING、STARTS、 TOTALISER ? Tag - 标签变量 ? LocalTag - 本地标签 ? Cluster - 集群 有关字段的信息,请参见 浏览函数字段引用。 szFilter 类型:LPCTSTR 输入/输出:输入 描述:过滤标准。这是基于以下格式的字符串: "PropertyName1=FilterCriteria1;PropertyName2=FilterCriteria2"\. "*" 作为获得同样结果的过滤器。 szCluster 类型:LPCTSTR 输入/输出:输入 描述:指定应首先执行的集群。如果保留为 NULL 或空,则会对当前集群执行 ctFindFirst(如果只有一个集群)。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。 dwFlags 此参数不再使用,应为此参数传递的值为 0。 如何搜索表格:

92

Chapter: 4 CtAPI 函数

在 szTableName 中指定表格的名称。 如何搜索设备: 在 szTableName 中将名称指定为 Vijeo Citect 设备表中定义的名称(如 Example 工程中的 "RECIPES")。 如何搜索趋势数据: 在 szTableName 中使用以下格式(包括括号)指定趋势: `TRNQUERY,Endtime,EndtimeMs,Period,NumSamples,Tagname,Displaymode,Datamode' 有关语法的详细信息,请参见 TrnQuery。 如何搜索报警数据: 在 szTableName 中使用以下格式(包括括号)指定报警数据: `ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period' 有关语法的详细信息,请参见 AlmQuery。 返回参数值 如果函数成功,返回参数值为随后调用 ctFindNext() 或 ctFindClose() 时使用的搜索句 柄。如果函数失败,返回参数值为 NULL。要获得扩展错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctFindNext、ctFindClose、ctGetProperty、ctFindFirst

ctFindNext
在由 ctFindFirst 发起的搜索中检索下一个对象。 语法 ctFindNext(hnd,pObjHnd) hnd 类型:Handle 输入/输出:输入 描述:要查找的句柄,由 ctFindFirst() 返回。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。

93

Chapter: 4 CtAPI 函数

返回参数值 如果函数成功,则返回参数值为 TRUE (1)。如果函数失败,则返回参数值为 FALSE (0)。 要获得扩展错误信息,请调用 GetLastError()。如果到达搜索末端,GetLastError() 将返回 CT_ERROR_NOT_FOUND。通过搜索末端后,将无法使用 ctFindNext() 或 ctFindPrev() 命令滚动搜索。必须通过使用 ctFindFirst() 或 ctFindScroll() 函数将指针移至有效位置来创 建新搜索,从而重置搜索指针。 相关函数 ctOpen、ctFindFirst、ctFindPrev、ctFindClose、ctGetProperty 范例 请参见 ctFindFirst。

ctFindPrev
在由 ctFindFirst 发起的搜索中检索上一个对象。 语法 ctFindPrev(hnd,pObjHnd) hnd 类型:Handle 输入/输出:输入 描述:要查找的句柄,由 ctFindFirst() 返回。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。 返回参数值 如果函数成功,则返回参数值为 TRUE (1)。如果函数失败,则返回参数值为 FALSE (0)。 要获得扩展错误信息,请调用 GetLastError()。如果到达搜索末端,GetLastError() 将返回 CT_ERROR_NOT_FOUND。通过搜索末端后,将无法使用 ctFindNext() 或 ctFindPrev() 命令滚动搜索。必须通过使用 ctFindFirst() 或 ctFindScroll() 函数将指针移至有效位置来创 建新搜索,从而重置搜索指针。 相关函数 ctOpen、ctFindFirst、ctFindNext、ctFindClose、ctGetProperty 范例 请参见 ctFindFirst。

94

Chapter: 4 CtAPI 函数

ctFindScroll
滚动至由 ctFindFirst 发起的搜索中的所需对象。 要查找当前滚动指针,可以使用偏移量 0 来滚动相对值 (dwMode = CT_FIND_SCROLL_RELATIVE)。要查找搜索中返回的记录号,请滚动至搜索的末尾。 语法 ctFindScroll(hnd,dwMode,dwOffset,pObjHnd) hnd 类型:Handle 输入/输出:输入 描述:要查找的句柄,由 ctFindFirst() 返回。 dwMode 类型:DWORD 输入/输出: 描述:滚动模式。支持以下模式: CT_FIND_SCROLL_NEXT:滚动至下一条记录。dwOffset 参数将被忽略。 CT_FIND_SCROLL_PREV:滚动至上一条记录。dwOffset 参数将被忽略。 CT_FIND_SCROLL_FIRST:滚动至第一条记录。dwOffset 参数将被忽略。 CT_FIND_SCROLL_LAST:滚动至最后一条记录。dwOffset 参数将被忽略。 CT_FIND_SCROLL_ABSOLUTE:滚动至绝对记录号。记录号在 dwOffset 参 数中指定。记录号是搜索中返回的记录从 1 到最大数目的数值。 CT_FIND_SCROLL_RELATIVE:滚动相对记录。要滚动的记录数目由 dwOffset 参数指定。如果偏移量为正,则此函数将滚动至下一条记录;如 果为负,将滚动至上一条记录。如果为 0(零),则不滚动。 dwOffset 类型:LONG 输入/输出:输入 描述:滚动偏移量。此参数的意义取决于滚动操作的 dwMode。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。 pObjHnd 类型:HANDLE 输入/输出:输出 描述:指向找到的对象句柄的指针,用于检索属性。

95

Chapter: 4 CtAPI 函数

返回参数值 如果函数成功,则返回参数值非零。如果函数失败,则返回参数值为零。要获得扩展错误 信息,请调用 GetLastError()。如果无法找到匹配的对象,GetLastError() 函数将返回 CT_ERROR_NOT_FOUND。返回参数值是搜索中的当前记录号。记录号从 1(第一条记 录)开始并逐条递增,直到达到搜索的末尾。请记住,0(零)是无效记录号,它表示函数 失败。 相关函数 ctOpen、ctFindFirst、ctFindNext、ctFindPrev、ctFindClose、ctGetProperty 范例
HANDLE hSearch; HANDLE hObject; DWORD dwNoRecords; // Search the Tag table hSearch = ctFindFirst(hCTAPI, "Tag", NULL, &hObject, 0); // Count number of records dwNoRecords = ctFindScroll(hSearch, CT_FIND_SCROLL_LAST, 0, &hObject); // scroll back to beginning ctFindScroll(hSearch, CT_FIND_SCROLL_FIRST, 0, &hObject); do { char sName[32]; // Get the tag name ctGetProperty(hObject, "Tag", sName, sizeof(sName), NULL, DBTYPE_STR); } while (ctFindScroll(hSearch, CT_FIND_SCROLL_NEXT, 0, &hObject)); ctFindClose(hSearch);

ctGetOverlappedResult
返回重叠操作的结果。ctGetOverlappedResult() 函数报告的结果是指定句柄的最后 CTOVERLAPPED 操作,可为该操作提供指定 CTOVERLAPPED 结构,并等待操作的结 果。等待操作是在启动操作的函数返回 FALSE 并且 GetLastError 函数返回 ERROR_IO_PENDING 时表明的。I/O 操作处于等待状态时,启动操作的函数会将 CTOVERLAPPED 结构的 hEvent 成员重置为未发出信号状态。然后,等待操作完成时, 系统会将事件对象设置为已发出信号状态。 如果 bWait 参数为 TRUE,则 ctGetOverlappedResult() 决定是否通过等待处于已发出信 号状态的事件对象来完成等待操作。 在 CTOVERLAPPED 结构中指定手动重置的事件对象。如果使用的是自动重置事件对象, 则不得在启动 CTOVERLAPPED 操作和调用 ctGetOverlappedResult() 之间的间隔的任何 其它等待操作中指定事件句柄。例如,事件对象有时在某个等待函数中指定,用来等待操 作的完成。等待函数返回时,系统将自动重置事件的状态设置为未发出信号,随后对设置 为 TRUE 并带有 bWait 参数的 ctGetOverlappedResult() 的调用会导致函数无限期地停 滞。

96

Chapter: 4 CtAPI 函数

语法 ctGetOverlappedResult(hCTAPI,lpctOverlapped,pBytes,bWait) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回到 CTAPI 的句柄。 lpctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:重叠操作开始时使用的 CTOVERLAPPED 结构的地址。 pBytes 类型:DWORD* 输入/输出:输入 描述:传输实际字节的地址。对于 CTAPI,此置未定义。 bWait 类型:BOOL 输入/输出:输入 描述:指定函数是否应等待要完成的等待交叠操作。如果为 TRUE,则函数不返 回任何值,直到操作完成。如果为 FALSE 且操作仍然处于等待状态,则函数返 回 FALSE,并且 GetLastError 函数返回 ERROR_IO_INCOMPLETE。 返回参数值 如果函数成功,则返回参数值为 TRUE。如果函数失败,则返回参数值为 FALSE。使用 GetLastError() 可获得扩展错误信息。 相关函数 ctOpen、ctHasOverlappedIoCompleted 范例
DWORD Bytes; char sVersion[128]; CTOVERLAPPED ctOverlapped; ctOverlapped.hEvent = CreateEvent(NULL, TRUE, TRUE, NULL); ctCicode(hCTAPI, "Version(0)", 0, 0, sVersion, sizeof(sVersion), &ctOverlapped); //.. // do something else. //.. // wait for the ctCicode to complete ctGetOverlappedResult(hCTAPI, &ctOverlapped, &Bytes, TRUE);

97

Chapter: 4 CtAPI 函数

ctGetProperty
检索对象属性或对象的图元数据。此函数应与 ctFindFirst() 及 ctFindNext() 函数结合使 用。即首先查找对象,然后检索其属性。 要检索诸如类型、大小等属性图元数据,请对 szName 参数使用以下语法: ? object.fields.count - 记录中字段的数目 ? object.fields(n).name - 记录中第 n 个字段的名称 ? object.fields(n).type - 记录中第 n 个字段的类型 ? object.fields(n).actualsize - 记录中第 n 个字段的实际大小 语法 ctGetProperty(hnd,szName,pData,dwBufferLength,dwResultLength,dwType) hnd 类型:Handle 输入/输出:输入 描述:要查找的句柄,由 ctFindFirst() 返回。 szName 类型:LPCTSTR* 输入/输出:输入 描述:要检索的属性的名称。支持以下属性: Name - 标签的名称。 FullName - cluster.tagname 表中标签的全名。 Network - 唯一的 I/O 设备号。 BitWidth - 数据类型宽度(以比特为单位)。例如,数字量是 1,整型是 16,长 型是 32 等。 UnitType - 特定于协议的单位类型。 UnitAddress - 特定于协议的单位地址。 UnitCount - 特定于协议的单位数目。 RawType - 点的原始数据类型。返回以下类型:0(数字量)、1(整型)、2 (实型)、3 (BCD)、4(长型)、5(长型 BCD)、6(长实型)、7(字 符串)、8(字节)、9(空)、10(无符号整型)。 Raw_Zero - 原始零刻度。 Raw_Full - 原始满刻度。 Eng_Zero - 工程零刻度。 Eng_Full - 工程满刻度。 pData

98

Chapter: 4 CtAPI 函数

类型:VOID* 输入/输出:输出 描述:存储读数据的结果缓冲区。数据是原始二进制数据,不执行数据转换或缩 放。如果此缓冲区不够大,无法接收数据,数据将被截断,并且函数会返回 false。 dwBufferLength 类型:DWORD 输入/输出:输入 描述:结果缓冲区的长度。如果结果缓冲区不够大,无法接收数据,数据将被截 断,并且函数会返回 false。 dwResultLength 类型:DWORD* 输入/输出:输出 描述:返回结果的长度。如果希望忽略此参数,则可以传递 NULL。 dwType 类型:DWORD 输入/输出:输入 描述:期望的返回类型如下:


DBTYPE_UI1 DBTYPE _I1 DBTYPE _I2 DBTYPE _I4 DBTYPE _R4 DBTYPE _R8 DBTYPE _BOOL DBTYPE_BYTES DBTYPE _STR

意义
UCHAR 1 字节 INT 2 字节 INT 4 字节 INT 4 字节 REAL 8 字节 REAL BOOLEAN 字节流 NULL 终止的 STRING

返回参数值 如果函数成功,则返回参数值非零。如果函数失败,则返回参数值为零。要获得扩展错误 信息,请调用 GetLastError()。

99

Chapter: 4 CtAPI 函数

相关函数 ctOpen、ctFindFirst、ctFindNext、ctFindPrev、ctFindClose 范例 另请参见 ctFindFirst()。
// get the property of the TAG field ctGetProperty(hObject, "TAG", sName, sizeof(sName), NULL, DBTYPE_STR); // Use the meta property fields to enumarate the entire row of data // first get number of fields in the row ctGetProperty(hObject, "object.fields.count", &dwFields, sizeof(dwFields), NULL, DBTYPE_I4); for (i = 0; i < dwFields; i++) { sprintf(sObject, "object.fields(%d).name", i + 1); // get name of field if (ctGetProperty(hObject, sObject, sName, sizeof(sName), NULL, DBTYPE_STR)) { // get value of field if (ctGetProperty(hObject, sName, sData, sizeof(sData), NULL, DBTYPE_STR)) { printf("%8.8s ", sData); } } }

ctHasOverlappedIoCompleted
提供高性能测试操作,可用于查询未完成的 I/O 操作是否完成。 语法 ctHasOverlappedIoCompleted(lpctOverlapped) lpctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:重叠操作开始时使用的 CTOVERLAPPED 结构的地址。 返回参数值 如果 I/O 操作已完成,则返回 TRUE,否则返回 FALSE。 返回参数值 ctOpen、ctGetOverlappedResult

ctListAdd

100

Chapter: 4 CtAPI 函数

将标签添加到列表。将标签添加到列表后,可以使用 ctListRead() 读取和使用 ctListWrite() 写入。如果读取处于等待状态,则下次调用 ctListRead() 之前不会读取标签。完成 ctListAdd() 函数后可以立即调用 ctListWrite()。 语法 ctListAdd(hList、sTag) hList 类型:HANDLE 输入/输出:输入 描述:指向列表的句柄,从 ctListNew() 返回。 sTag 类型:LPCSTR 输入/输出:输入 描述:要添加到列表的标签。 返回参数值 如果函数成功,则返回参数值指定一个句柄。如果函数失败,返回参数值为 NULL。要获 得扩展错误信息,请调用 GetLastError()。 如果使用此函数指定当前未在系统中定义的标签,则返回参数值将指定有效句柄。调用 ctListRead 能够辨认标签的真正状态。将空标签传递给此函数将导致函数立即失败并返回 NULL。 相关函数 ctOpen、ctListNew、ctListFree、ctListRead、ctListWrite、ctListData、ctListAddEx 范例 请参见 ctListNew

ctListAddEx
执行与 ctListAdd 相同的参数,但新增了 2 个参数。向列表中添加了一个标签。一旦被添 加到列表,标签可以使用 ctListRead() 读取,使用 ctListWrite() 写入。如果已有一个读命 令处于待执行状态,下次调用 ctListRead() 前不会读取此标签。ctListWrite() 可能会在完成 ctListAdd() 函数后立即被调用。 如果调用了 ctListAdd 而非 ctListAddEx,标签的缺省轮询周期为 500 毫秒,缺省 bRaw 标志为工程值 FALSE。 语法 ctListAddEx(hList, sTag, bRaw, nPollPeriodMS, dDeadband)

101

Chapter: 4 CtAPI 函数

hList 类型:HANDLE 输入/输出:输入 描述:列表的句柄,作为 ctListNew() 的返回参数值。 sTag 类型:LPCSTR 输入/输出:输入 描述:要添加到列表的标签。 bRaw 类型:BOOL 输入/输出:输入 描述:指定是否使用原始模式(如果值为 TRUE)或工程模式(如果值为 FALSE)订阅列表中的给定标签。 nPollPeriodMS 类型:INTEGER 输入/输出:输入 描述:指示针对标签创建的订阅中使用的轮询周期(以毫秒为单位)。 dDeadband 类型:DOUBLE 输入/输出:输入 描述:变量标签的工程范围百分比,要使更新能通过系统发送,变量必须以此范 围为依据进行更改。值 -1.0 表示要使用由标签定义指定的缺省死区。 返回参数值 如果函数成功,返回参数值将指定一个句柄。如果函数失败,返回参数值为 NULL。要获 得详细的错误信息,请调用 GetLastError() 如果使用此函数指定了系统中当前未定义的标签,那么返回参数值将指定一个有效句柄。 通过调用 ctListRead,可以标识标签的 True 状态。向此函数传递空标签将导致函数立即失 败并返回 NULL。 相关函数 ctOpen、ctListNew、ctListFree、ctListRead、ctListWrite、ctListData 范例 参见 ctListNew

ctListData
获得列表中的标签的值。应在为添加的标签完成 ctListRead() 后调用此函数。可以在随后 的 ctListRead() 函数等待调用期间调用 ctListData(),将返回最新的读数据。

102

Chapter: 4 CtAPI 函数

语法 ctListData(hTag, pBuffer, dwLength, dwMode) hTag 类型:HANDLE 输入/输出:输入 描述:标签的句柄,作为 ctListAdd() 的返回参数值。 pBuffer 类型:VOID* 输入/输出:输入 描述:指示缓冲区返回数据的指示器。数据作为已经过缩放的特定格式字符串返 回。 dwLength 类型:Dword 输入/输出:输入 描述:原始数据缓冲区的长度(以字节为单位)。 dwMode 类型:DWORD 输入/输出:输入 描述:数据的模式。支持以下模式: 0(零) - 此值使用在 Vijeo Citect 工程中指定的刻度进行缩放,并使用在 Vijeo Citect 工程中指定的格式进行格式化。 FMT_NO_FORMAT - 此值不会被设定为在 Vijeo Citect 工程中指定的格式。将 使用缺省格式。如果在 Vijeo Citect 工程中指定了刻度,则将使用该刻度缩 放此值。 dwMode 参数不再支持可用于从列表中动态获取标签原始值或工程值的选项 FMT_NO_SCALE。如果要获取标签的原始值,应调用 ctListAddEx 并指 定 bRaw = TRUE,使用此模式将其添加到列表中。 返回参数值 如果函数成功,返回参数值为 TRUE。如果函数失败,返回参数值为 FALSE。要获得详细 的错误信息,请调用 GetLastError()。 如果在从 I/O 设备中读取数据时出现错误,返回参数值将为 FALSE,GetLastError() 将返 回相关的 Vijeo Citect 错误代码。 相关函数 ctOpen、ctListNew、ctListFree、ctListAdd、ctListRead、ctListWrite

103

Chapter: 4 CtAPI 函数

范例 参见 ctListNew

ctListDelete
释放用 ctListAdd 创建的标签。可以在其它线程中有待执行的读命令或写命令时安全地调 用 ctListDelete()。ctListWrite() 和 ctListRead() 将在标签被删除后返回。 语法 ctListDelete(hTag) hTag 类型:HANDLE 输入/输出:输入 描述:标签的句柄,作为 ctListAdd() 的返回参数值。 返回参数值 如果函数成功,返回参数值为 TRUE。如果函数失败,返回参数值为 FALSE。要获得详细 的错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctListNew、ctListFree、ctListAdd、ctListRead、ctListWrite、ctListData 范例
HANDLE hList; HANDLE hTagOne; HANDLE hTagTwo; hList = ctListNew(hCTAPI, 0); hTagOne = ctListAdd(hList, "TagOne"); hTagTwo = ctListAdd(hList, "TagTwo"); ctListRead(hList, NULL); // read TagOne and TagTwo ctListData(hList, hTagOne, sBufOne, sizeof(sBufOne), 0); ctListData(hList, hTagTwo, sBufTwo, sizeof(sBufTwo) , 0); ctListDelete(hTagOne); // delete TagOne; ctListRead(hList, NULL); // read TagTwo only ctListData(hList, hTagTwo, sBufTwo, sizeof(sBufTwo) , 0);

ctListEvent
在列表中返回自上次用 ctListRead() 函数读取后状态改变的元素。必须已在 ctListNew() 函 数中用 CT_LIST_EVENT 模式创建了列表。 语法 ctListEvent(hCTAPI, dwMode)

104

Chapter: 4 CtAPI 函数

hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 dwMode 类型:Dword 输入/输出:输入 描述:列表事件的模式。在更改模式前,必须为所有 ctListEvent() 调用使用相同 模式,直至返回 NULL。支持以下模式: CT_LIST_EVENT_NEW - 标签被添加到列表时获得通知。使用此模式时,一旦 有新标签被添加到列表,您就会获得事件消息。 CT_LIST_EVENT_STATUS - 获得状态更改通知。I/O 设备离线时,标签的状态 将发生改变。使用此模式时,您会在标签进入 #COM 时得到一个通知,在 它离开 #COM 时得到另一个通知。可以在从标签的 ctListData() 中返回错 误时验证该标签是否位于 #COM 中。 返回参数值 如果函数成功,返回参数值将向上次调用 ctListRead 后状态改变的标签指定一个句柄。如 果函数失败或状态未改变,返回参数值为 NULL。要获得详细的错误信息,请调用 GetLastError()。 相关函数 ctListAdd、ctListDelete、ctListRead、ctListWrite、ctListData 范例
HANDLE hList; HANDLE hTag[100]; hList = ctListNew(hCTAPI, CT_LIST_EVENT); hTagArray[0] = ctListAdd(hList, "TagOne"); hTagArry[1] = ctListAdd(hList, "TagTwo"); and so on... while (TRUE) { ctListRead(hList, NULL); hTag = ctListEvent(hList, 0); while (hTag != NULL) { // hTag has changed state, do whatever you need hTag = ctListEvent(hList, 0); } }

ctListFree
释放用 ctListNew 创建的列表。添加到列表的所有标签都将被释放,无需为每一标签调用 ctListDelete()。不应在读操作等待执行期间调用 ctListFree()。等待读操作完成,然后再释 放列表。

105

Chapter: 4 CtAPI 函数

语法 ctListFree(hList) hList 类型:HANDLE 输入/输出:输入 描述:列表的句柄,作为 ctListNew() 的返回参数值。 返回参数值 如果函数成功,返回参数值为 TRUE。如果函数失败,返回参数值为 FALSE。要获得详细 的错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctListNew、ctListAdd、ctListDelete、ctListRead、ctListWrite、ctListData 范例 参见 ctListNew

ctListNew
创建新列表。CTAPI 提供了两种从 I/O 设备中读数据的方法。每个级别根据其复杂性和性 能的不同而有所不同。读取数据的最简单方法是通过 ctTagRead() 函数。此函数读取单独 变量的值,作为特定格式的工程字符串返回结果。 List 函数提供了比基于标签的接口级别更高级别的数据读取性能,还提供了对重叠操作的 支持。 可通过 List 函数定义一组标签,然后作为一个请求读取。这些函数针对以特定工程数据格 式提供的数据提供了一个基于标签的简单接口。可以创建数个列表并单独控制每个列表。 标签可以动态地添加至列表或从列表中删除,即使列表中有待执行的读操作也不例外。 语法 ctListNew(hCTAPI, dwMode) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 dwMode 类型:DWORD 输入/输出:输入 描述:列表创建模式。支持以下模式:

106

Chapter: 4 CtAPI 函数

CT_LIST_EVENT - 在事件模式下创建列表。此模式支持 ctListEvent() 函数。 返回参数值 如果函数成功,返回参数值将指定一个句柄。如果函数失败,返回参数值为 NULL。要获 得详细的错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctListFree、ctListAdd、ctListDelete、ctListEvent、ctListRead、ctListWrite、 ctListData 范例
HANDLE hList; HANDLE hTagOne; HANDLE hTagTwo; hList = ctListNew(hCTAPI, 0); hTagOne = ctListAdd(hList, "TagOne"); hTagTwo = ctListAdd(hList, "TagTwo"); while (you want the data) { ctListRead(hList, NULL); ctListData(hTagOne, sBufOne, sizeof(sBufOne), 0); ctListData(hTagTwo, sBufTwo, sizeof(sBufTwo) , 0); } ctListFree(hList);

ctListRead
读取列表中的所有标签。此函数可读取附加到列表的所有标签。在从 I/O 设备中读取数据 后,可以调用 ctListData(),以获得标签的值。如果读取失败,ctListData() 将针对失败的 标签返回失败。 在 ctListRead() 等待执行期间,可以向列表中添加或从中删除标签。如果在 ctListRead() 等待执行期间从列表中删除了某标签,该标签仍会被读取一次。下次调用 ctListRead() 时 将不再读取此标签。如果在 ctListRead() 等待执行期间向列表中添加了标签,下次调用 ctListRead() 前,该标签将不会被读取。只要添加了该标签,就可以为其调用 ctListData()。在此情况下,ctListData() 将失败,GetLastError() 将返回 GENERIC_INVALID_DATA。 每个列表中将只能有一个 1 待执行读命令。如果再次为同一列表调用 ctListRead(),此函数 将失败。 在释放列表前,应确保没有仍在等待执行的读命令。应等待任何当前的 ctListRead() 返 回,然后将列表删除。 语法 ctListRead(hList, pctOverlapped) hList

107

Chapter: 4 CtAPI 函数

类型:HANDLE 输入/输出:输入 描述:列表的句柄,作为 ctListNew() 的返回参数值。 pctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:CTOVERLAPPED 结构。此结构用于控制重叠通知。如果希望同步函数调 用,将其设为 NULL。 返回参数值 如果函数成功,返回参数值为 TRUE。如果函数失败,返回参数值为 FALSE。要获得详细 的错误信息,请调用 GetLastError()。 如果在从 I/O 设备中读取列表数据时出现错误,返回参数值将为 FALSE,GetLastError() 将返回相关的 Vijeo Citect 错误代码。由于列表可能包含来自多个数据源的标签,某些标签 可能在其它标签失败的情况下被正确读取。如果任一标签失败,ctListRead() 将返回 FALSE,但其它标签将包含有效数据。可以调用 ctListData(),以检索列表中每一标签的值 和具体的错误状态。 相关函数 ctOpen、ctListNew、ctListFree、ctListAdd、ctListWrite、ctListData 范例 参见 ctListNew 如何使用 ctListRead 读取“呼叫报警”属性:
HANDLE hList; HANDLE hAlarmOne; HANDLE hAlarmTwo; hList = ctListNew(hCTAPI, 0); hTagOne = ctListAdd(hList, "AlarmOne.Paging"); hTagTwo = ctListAdd(hList, "AlarmTwo.Paging"); while (you want the data) { ctListRead(hList, NULL); ctListData(hAlarmOne, sBufOne, sizeof(sBufOne), 0); ctListData(hAlarmTwo, sBufTwo, sizeof(sBufTwo) , 0); } ctListFree(hList);

ctListWrite
向列表中写入单个标签。

108

Chapter: 4 CtAPI 函数

语法 ctListWrite(hTag, sValue, pctOverlapped) hTag 类型:HANDLE 输入/输出:输入 描述:标签的句柄,作为 ctListAdd() 的返回参数值。 sValue 类型:LPCSTR 输入/输出:输入 描述:作为字符串写入标签的值。为便于写入标签,此值将被转换并缩放至正确 的格式。 pctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:CTOVERLAPPED 结构。此结构用于控制重叠通知。如果希望同步函数调 用,将其设为 NULL。 返回参数值 如果函数成功,返回参数值为 TRUE。如果函数失败,返回参数值为 FALSE。要获得详细 的错误信息,请调用 GetLastError()。 相关函数 ctOpen、ctListNew、ctListFree、ctListAdd、ctListDelete、ctListRead、ctListData 范例
HANDLE hTagOne; HANDLE hList; hList = ctListNew(hCTAPI, 0); hTagOne = ctListAdd(hList, "TagOne"); ctListWrite(hTagOne, "1.23", NULL); // write to TagOne

ctOpen
打开与 Vijeo Citect API 的连接。CTAPI.DLL 将被初始化,并会创建一个指向 Vijeo Citect 的连接。如果 Vijeo Citect 并未运行,此函数将失败。此函数必须在其他任何 CTAPI 函数 要初始化指向 Vijeo Citect 的连接之前被调用。 如果使用 CT_OPEN_RECONNECT 模式,此连接将丢失,CTAPI 将尝试重新连接到 Vijeo Citect。重新建立连接后,可以继续使用 CTAPI。但是,在连接断开期间,所有函数 都将返回失败。如果无法在首次调用 ctOpen() 时创建连接,仍将返回有效的句柄;但 GetLastError() 将指示失败。

109

Chapter: 4 CtAPI 函数

如果不使用 CT_OPEN_RECONNECT 模式,并且指向 Vijeo Citect 的连接丢失,必须释放 从 CTAPI 返回的所有句柄并调用 ctClose() 以释放连接。随后,必须调用 ctOpen() 以重新 建立连接并重新创建句柄。 注意:要在不安装 Vijeo Citect 的情况下在远程计算机上使用 CTAPI,需要将以下文件从 [bin] 目录复制到远程计算机中:CTAPI.DLL、CT_IPC.DLL、CTENG32.DLL、 CTRES32.DLL、CTUTIL32.DLL 和 CIDEBUGHELP.DLL。 如果要从远程计算机中调用此函数,必须使用有效的用户名和非空密码。 语法 ctOpen(sComputer, sUser, sPassword, nMode) sComputer 类型:LPCSTR 输入/输出:输入 描述:要通过 CTAPI 与之通讯的计算机。对于本地连接,指定 NULL 作为计算 机名。Windows 计算机名是在 Windows 控制面板“网络”部分下的“标识”标签中 指定的名称。 sUser 类型:LPCSTR 输入/输出:输入 描述:在要连接到的计算机上运行的 Vijeo Citect 工程中定义的用户名。仅当要 从远程计算机中调用此函数时才需要该参数。它在本地计算机上是可选的。 sPassword 类型:LPCSTR 输入/输出:输入 描述:在要连接到的计算机上运行的 Vijeo Citect 工程中定义的密码。仅当要从 远程计算机中调用此函数时才需要该参数。必须使用非空密码。它在本地计算机 上是可选的。 nMode 类型:DWORD 输入/输出:输入 描述:Cicode 调用的模式。将其设为 0(零)。支持以下模式: CT_OPEN_RECONNECT - 失败时重新打开连接。如果指向 Vijeo Citect 的连接 丢失,CTAPI 将继续重试连接到 Vijeo Citect。 CT_OPEN_READ_ONLY - 在只读模式下打开 CTAPI。这允许对数据进行只读 访问 - 无法向 Vijeo Citect 中写入变量或调用任何 Cicode 函数。 CT_OPEN_BATCH - 出现错误时禁止显示消息框。

110

Chapter: 4 CtAPI 函数

返回参数值 如果函数成功,返回参数值将指定一个句柄。如果函数失败,返回参数值为 NULL。使用 GetLastError() 获得详细的错误信息。 相关函数 ctCiCode、ctClose、ctEngToRaw、ctGetOverlappedResult、 ctHasOverlappedIoCompleted、ctRawToEng、ctTagRead、ctTagWrite、ctTagWrite 范例
HANDLE hCTAPI; hCTAPI = ctOpen(NULL, NULL, NULL, 0); if (hCTAPI == NULL) { dwStatus = GetLastError(); // failed, get error } else { ctTagWrite(hCTAPI, "SP123", "1.23"); ctClose(hCTAPI); } // example of open for remote TCP/IP connection. hCTAPI = ctOpen("203.19.130.2", "ENGINEER", "CITECT", 0);

ctOpenEx
使用给定客户机实例建立指向 CtAPI 服务器的连接。应在调用 ctOpenEx 前使用函数 ctClientCreate 创建客户机实例。 ctOpenEx 可提供与 ctOpen 完全相同的连接功能,唯一的区别是 ctOpen 还可创建 CtAPI 客户机实例。有关连接机制和相关参数的详细信息,请参见 ctOpen。 语法 ctOpenEx(sComputer, sUser, sPassword, nMode, hCTAPI); sComputer 类型:LPCSTR 输入/输出:输入 描述:要通过 CTAPI 与之通讯的计算机。对于本地连接,指定 NULL 作为计算 机名。Windows 计算机名是在 Windows 控制面板“网络”部分下的“标识”标签中 指定的名称。 sUser 类型:LPCSTR 输入/输出:输入 描述:在要连接到的计算机上运行的 Vijeo Citect 工程中定义的用户名。仅当要 从远程计算机中调用此函数时才需要该参数。它在本地计算机上是可选的。 sPassword

111

Chapter: 4 CtAPI 函数

类型:LPCSTR 输入/输出:输入 描述:在要连接到的计算机上运行的 Vijeo Citect 工程中定义的密码。仅当要从 远程计算机中调用此函数时才需要该参数。必须使用非空密码。它在本地计算机 上是可选的。 nMode 类型:Dword 输入/输出:输入 描述:Cicode 调用的模式。将其设为 0(零)。 hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 获得详细的错误信息。 相关函数 ctClientCreate、ctOpen、ctClose、ctCloseEx、ctClientDestroy 范例 参见 ctClientCreate

ctRawToEng
将原始的 I/O 设备刻度变量转换为工程标度。这对于 Tag 函数不是必需的,因为 Vijeo Citect 将进行缩放。无需对数字、字符串进行缩放,如果 I/O 设备中的值或工程值之间未 出现缩放,也不需要进行缩放。必须了解对 Vijeo Citect 标签变量表格中指定的每个变量的 进行缩放。 语法 ctRawToEng(pResult, dValue, pScale, dwMode) pResult 类型:Double 输入/输出:输出 描述:最终的原始缩放变量。 dValue 类型:Double 输入/输出:输入 描述:要缩放的工程值。

112

Chapter: 4 CtAPI 函数

pScale 类型:CTSCALE* 输入/输出:输入 描述:变量的缩放属性。 dwMode 类型:Dword 输入/输出:输入 描述:缩放模式。支持以下模式: CT_SCALE_RANGE_CHECK - 范围检查结果。如果变量超出范围,就会产生 错误。pResult 仍包含原始缩放值。 CT_SCALE_CLAMP_LIMIT - 将限制钳位在最大或最小刻度上。如果结果超出 刻度,则将结果设置为最小或最大刻度(以最接近的值为准)。如果刻度 被钳定,则不会产生任何错误。无法与 CT_SCALE_RANGE_CHECK 或 CT_SCALE_NOISE_FACTOR 选项一起使用。 CT_SCALE_NOISE_FACTOR - 允许范围的噪音因素检查限制。如果变量超出 范围的量不超过 0.1%,则不会产生范围错误。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 获得详细的错误信息。 相关函数 ctOpen、ctEngToRaw 范例
// SP123 is type INTEGER and has raw scale 0 to 32000 and Eng scale 0 to 100 HANDLE hList = ctListNew(s_hCTAPI, 0); HANDLE hTag = ctListAddEx(hList, "SP123", TRUE, 500, -1); CTSCALE Scale = { 0.0, 32000.0, 0.0, 100.0}; CHAR valueBuf[256] = {0}; double dRawValue = 0.0; double dSetPoint = 0.0; ctListRead(hList, NULL); ctListData(hTag, valueBuf, sizeof(valueBuf), 0); dRawValue = strtod(valueBuf, NULL); ctEngToRaw(&dSetPoint, dRawValue, &Scale, CT_SCALE_RANGE_CHECK); // dSetPoint now contains the Engineering scaled setpoint.

ctTagGetProperty
获得给定标签的给定属性。

113

Chapter: 4 CtAPI 函数

语法 ctTagGetProperty(hCTAPI, szTagName, szProperty, pData, dwBufferLength, dwType) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 szTagName 类型:LPCSTR 输入/输出:输入 描述:标签的名称。要指定集群,在标签前面添加“ClusterName.”。例如 Cluster1.Tag1(注意集群名称末尾的句点)。 szProperty 类型:LPCSTR 输入/输出:输入 描述:要读取的属性。属性名称区分大小写。支持以下属性: ArraySize:关联标签的数组尺寸。针对非数组类型返回 1。 DataBitWidth:用于存储值的位数。 描述:标签描述。 EngUnitsHigh:最大缩放值。 EngUnitsLow:最小缩放值。 格式:格式位字符串。格式信息以整数形式存储,如下所示: ? 位 0-7 - 格式宽度 ? 位 8-15 - 小数位数 ? 位 16 - 以零填充 ? 位 17- 左对齐 ? 位 18 - 显示工程单位 ? 位 20 - 指数(科学的)计算法 FormatDecPlaces:默认格式的小数位数。 FormatWidth:默认格式中使用的字符数。 RangeHigh:最大未缩放值。 RangeLow:最小未缩放值。 类型:数字形式的标签类型: ? 0 = Digital ? 1 = Byte ? 2 = Integer16 ? 3 = UInteger16 ? 4 = Long

114

Chapter: 4 CtAPI 函数

? ? ? ?

5 = Real 6 = String 7 = ULong 8 = Undefined

单位:工程单位,如 %、mm、Volt。 pData 类型:VOID* 输入/输出:输出 描述:检索到的属性值的输出数据缓冲区。 dwBufferLength 类型:DWORD 输入/输出:输入 描述:输出数据缓冲区的长度(以字节为单位)。 dwType 类型:DWORD 输入/输出:输入 描述:要返回的数据的类型。

参数值 DBTYPE_U11 DBTYPE_I1 DBTYPE_I2 DBTYPE_I4 DBTYPE_R4 DBTYPE_R8 DBTYPE_BOOL DBTYPE_BYTES DBTYPE_STR

意义 UCHAR 1 字节 INT 2 字节 INT 4 字节 INT 4 字节 REAL 8 字节 REEAL BOOLEAN 字节流 NULL 已终止的 STRING

返回参数值 如果函数成功,将返回非零值。如果函数失败,返回参数值为零。要获得详细的错误信 息,请调用 GetLastError()。

115

Chapter: 4 CtAPI 函数

ctTagRead
读取单独的标签值。数据将以字符串格式返回,并使用 Vijeo Citect 标度缩放。 此函数将请求 Vijeo Citect I/O 服务器中的给定标签。如果此标签位于 I/O 服务器设备缓存 中,数据将从缓存中返回。如果此标签不在设备缓存中,则将从 I/O 设备中读取此标签。 完成此函数所花费的时间将取决于 I/O 设备的性能。在读操作完成前,调用线程将被阻 断。 语法 ctTagRead(hCTAPI, sTag, sValue, dwLength) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 sTag 类型:LPCSTR 输入/输出:输入 描述:要写入的标记名称。可以使用数组语法 [] 选择数组的元素。 sValue 类型:LPCSTR 输入/输出:输出 描述:用于存储读数据的缓冲区。数据以字符串格式返回。 dwLength 类型:Dword 输入/输出:输入 描述:读缓冲区的长度。如果数据大于 dwLength,此函数将失败。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 获得详细的错误信息。 相关函数 ctOpen、ctTagWrite、ctTagWrite 范例
char sProcessValue[20]; short sFlour[20]; char sBuf[128]; char sPagingGroup[24]; ctTagRead(hCTAPI, "PV123", sProcessValue, sizeof(sProcessValue)); ctTagRead(hCTAPI, "Recipe[10]", sFlour, sizeof(sFlour));

116

Chapter: 4 CtAPI 函数

ctTagRead(hCTAPI, "PLCMsg", sBuf, sizeof(sBuf)); ctTagRead(hCTAPI, "Alarm_1.PagingGroup", sPagingGroup, sizeof(sPagingGroup));

ctTagWrite
写入给定的 Vijeo Citect I/O 设备标签变量。此值将转换为正确的数据类型,进行缩放,然 后写入标签。如果写入数组元素,将只有一个数组的元素被写入。此函数将生成一个对 I/O 服务器的写请求。完成此函数所花费的时间将取决于 I/O 设备的性能。在写操作完成 前,调用线程将被阻断。 语法 ctTagWrite(hCTAPI, sTag, sValue) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 sTag 类型:LPCSTR 输入/输出:输入 描述:要写入的标记名称。可以使用数组语法 [] 选择数组的元素。 sValue 类型:LPCSTR 输入/输出:输入 描述:作为字符串写入标签的值。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 获得详细的错误信息。 相关函数 ctOpen、ctTagWrite、ctTagRead 范例
ctTagWrite(hCTAPI, ctTagWrite(hCTAPI, ctTagWrite(hCTAPI, ctTagWrite(hCTAPI, ctTagWrite(hCTAPI, True "CV123_Start", "1"); // write digital "SP123", "12.34"); // write real "Recipe[3]", "42"); // write int "PLCMsg", "Message"); // write string "Alarm_1.Paging", "TRUE"); // set Paging property of Alarm_1 to

ctTagWriteEx

117

Chapter: 4 CtAPI 函数

执行与 ctTagWrit 相同的参数,但新增了 2 个参数。写入给定的 Vijeo Citect I/O 设备标签 变量。此值将转换为正确的数据类型,进行缩放,然后写入标签。如果写入数组元素,将 只有一个数组的元素被写入。此函数将生成一个对 I/O 服务器的写请求。完成此函数所花 费的时间将取决于 I/O 设备的性能。 如果 pctOverlapped 的值为 NULL,此函数的运行方式与 ctTagWrite 相同,在写操作完 成前,调用线程将被阻断。如果 pctOverlapped 的值不是 NULL,写操作将异步完成,调 用线程不会被阻断。 语法 ctTagWriteEx(hCTAPI, sTag, sValue, pctOverlapped) hCTAPI 类型:Handle 输入/输出:输入 描述:从 ctOpen() 返回的 CTAPI 的句柄。 sTag 类型:LPCSTR 输入/输出:输入 描述:要写入的标签名称。可以使用数组语法 [] 选择数组的元素。 sValue 类型:LPSTR 输入/输出:输入 描述:作为字符串写入标签的值。 pctOverlapped 类型:CTOVERLAPPED* 输入/输出:输入 描述:在重叠结构中传递,以便 ctTagWriteEx 异步完成。如果 pctOverlapped 结构是 NULL,此函数将被阻断,进而实现异步完成。 返回参数值 成功时为 TRUE,否则为 FALSE。使用 GetLastError() 获得详细的错误信息。 相关函数 ctOpen、ctTagRead

AlmQuery
提供了一个从外部应用程序进入报警汇总归档中的接口,取代了原来的 CtAPIAlarm 查 询。AlmQuery 的性能远远优于 CtAPIAlarm。

118

Chapter: 4 CtAPI 函数

AlmQuery 通过与 CtAPIAlarm 相同的机制得以执行。要建立查询并返回第一个记录,可 以调用 ctFindFirst。然后,要浏览其余的记录,可以调用 ctFindNext。要访问当前记录的 数据,可以针对记录的每个字段调用 ctGetProperty。 ctFindFirst 使用以下参数进行调用: ? hCtapi: 有效 CtAPI 客户机实例的句柄。 ? szTableName: almquery 的命令字符串,请参见下文。 ? szFilter: 不用于 Almquery。仅在 NULL 中传递。 ? hObject: 针对查询检索的第一个记录的句柄。 ? dwFlags: 不用于 Almquery。仅在 0 中传递。 szTableName 是查询的命令字符串,且包含查询的所有参数。 语法 `ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period' 注意:参数必须用逗号分隔。位于参数之间的空格受支持,但不是必需的。建议不要在参 数之间加空格,因为空格需要更多处理,且在查询字符串中会占用更多空间。 Database: 报警所在的报警数据库(报警类型)。支持以下数据库:DigAlm(数字量)、 AnaAlm(模拟量)、AdvAlm(高级)、HResAlm(带有时间戳)、 ArgDigAlm(多-数字量)、ArgAnaAlm(多状态模拟量)、TsDigAlm(带有 时间戳的数字量)、TsAnaAlm(带有时间戳的模拟量)。 TagName: 作为字符串的报警标签。此查询仅支持在报警数据中一次检索一个报警。尽管它 受 Vijeo Citect 支持,但您不应声明具有相同标签和相同类型的两个不同的报 警。您无法在报警数据中检索这两个报警,因此此查询预计报警类型(数据库) 和标签的组合是唯一的。 Starttime: 自 1970 年以来的趋势查询的开始时间(在 UTC 时间中以整数表示)。 StarttimeMs: 开始时间的毫秒部分(以整数表示)。预计为 0 到 999 之间的数字。 Endtime: 自 1970 年以来的趋势查询的结束时间(在 UTC 时间中以整数表示)。 EndtimeMs: 结束时间的毫秒部分(以整数表示)。预计为 0 到 999 之间的数字。 Period: 采样返回之间的时间段(秒,以浮点值表示)。支持的唯一十进制分隔符为“.”。

119

Chapter: 4 CtAPI 函数

返回参数值 返回的采样的最大数目是时间范围除以该期间,再加上 3 得出的结果(一个代表结束时的 实际采样,两个代表上一个采样和下一个采样)。 注意:该期间应该平均分布于时间范围,否则可能会返回一个额外的采样。 AlmQuery 永远不会在没有报警采样期间返回内插采样。但是,要确认强制实施返回的采 样最大数目,则在一个期间内出现多个采样时将压缩原始报警采样。 执行此压缩时,返回的采样被标记为多重采样。然后,时间戳就成为该期间内的所有采样 的平均值。返回的值和注释始终反映该期间最后一个采样的情况。 系统会针对查询的每个数据记录返回以下属性。 ? DateTime: 自 1970 以来趋势采样的时间(秒,以整数表示)。此时间采用 UTC(通用 时间坐标系)表示。 ? MSeconds: 趋势采样时间的毫秒组成部分(以整数表示)。此值介于 0 到 999 之间。 ? Comment: 与报警采样关联的注释(以字符串形式表示)。 ? Value: 采样的报警值(以不带符号的整数表示)。有关报警值的详细描述,请参见下 文。报警值包含用于描述采样时的报警状态的所有重要信息: bGood(位 0)- 仅供将来使用,用于显示报警数据质量变差的时间。此时每个 采样的此位都被设置为 1,说明采样良好。 bDisabled(位 1)- 如果在采样时禁用了报警,则为 1,否则为 0。 bMultiple(位 2)- 如果报警采样基于多个原始采样,则为 1;如果仅基于 1 个 原始采样,则为 0。 bOn(位 3)- 如果在采样时启用了报警,则为 1,否则为 0。 bAck(位 4)- 如果在采样时确认了报警,则为 1,否则为 0。 state(位 5 - 7)- 包含采样时报警的状态信息。 报警状态表示不同报警类型的不同状态。状态仅包含报警启用时的相关信息。 对于模拟量、多状态模拟量和带有时间戳的模拟量报警,状态可以如下所示: ? 已过期 (0)- 报警状态信息已过期。我们不再了解报警的状态,我们只 知道报警此时处于启用状态。如果将 citect.ini 参数 [Alarm]SumStateFix 设 置为 0,则将丢失状态。 ? 偏离高限 (1)- 报警比设置点至少高出指定的阈值。 ? 偏离低限 (2)- 报警比设置点至少低出指定的阈值。 ? 变化率 (3)- 报警变化的速率高于预期速率。 ? 低 (4)- 报警进入较低的报警值范围。 ? 高 (5)- 报警进入较高的报警值范围。 ? 低低限 (6)- 报警进入低低限报警值范围。 ? 高高限 (7)- 报警进入高高限报警值范围。 对于多-数字量报警,状态可以如下所示:

120

Chapter: 4 CtAPI 函数

? ? ? ? ? ? ? ?

000 (0)- 报警的所有数字量标签都处于关闭状态。 00A (1)- 标签 A 处于打开状态,B 和 C 处于关闭状态。 0B0 (2)- 标签 B 处于打开状态,A 和 C 处于关闭状态。 0BA (3)- 标签 B 和 A 处于打开状态,C 处于关闭状态。 C00 (4)- 标签 C 处于打开状态,B 和 C 处于关闭状态。 C0A (5)- 标签 C 和 A 处于打开状态,B 处于关闭状态。 CB0 (6)- 标签 C 和 B 处于打开状态,A 处于关闭状态。 CBA (7)- 报警的所有数字量标签都处于打开状态。

对于其余的报警类型,应忽略对应的状态信息。

TrnQuery
提供从外部应用程序进入趋势归档中的强大接口,取代了原来的 CtAPITrend 查询。 TrnQuery 的性能明显好于 CtAPITrend。 TrnQuery 通过与 CtAPITrend 相同的机制得以执行。要建立查询并返回第一条记录,可以 调用 ctFindFirst。然后,要浏览其余记录,可以调用 ctFindNext。要访问当前记录的数 据,可以针对记录的每个字段调用 ctGetProperty。 ctFindFirst 使用以下参数进行调用: ? ? ? ? ? hCtapi:有效 Ctapi 客户机实例的句柄。 szTableName:Trnquery 的命令字符串,请参见下文。 szFilter:不用于 Trnquery。仅在 NULL 中传递。 hObject:针对查询检索的第一条记录的句柄。 dwFlags:不用于 Trnquery。仅在 0 中传递。

szTableName 是用于查询的命令字符串。它包含用于查询的所有参数。 语法 TRNQUERY,Endtime,EndtimeMs,Period,NumSamples,Tagname,Displaymode,Datamode' 注意:参数必须用逗号分隔。参数之间的空格受支持,但不是必需的。建议不要在参数之 间加空格,因为空格需要更多处理,并在查询字符串中占用更多空间。 Endtime: 自 1970 以来趋势查询的结束时间(秒,以整数表示)。此时间应为 UTC 时间 (协调世界时)。 EndtimeMs: 结束时间的毫秒部分为整数,此值应介于 0 到 999 之间。 Period:

121

Chapter: 4 CtAPI 函数

采样返回之间的时间段(秒,以浮点值表示)。注意,支持的唯一十进制分隔符 为“.”。 NumSamples: 所请求的采样数为整数。请求的开始时间的计算方法为:Period * (NumSamples - 1),然后用 EndTime 减去这个结果。 实际返回采样的最大数量为 NumSamples + 2。因为,我们返回了所请求范围之 前和之后的前一个及下一个采样。这一点非常有用,因为您可以了解到您所请求 数据位置之前或之后的下一个数据位置。 TagName: 趋势标签的名称(字符串)。此查询仅支持在趋势数据中一次检索一个趋势。 DisplayMode: 指定将查询采样作为未指定的整数进行格式化并计算的不同选择。有关信息,请 参见 显示模式。 DataMode: 请求模式为整数。如果要以完全精确的形式返回时间戳,则使用 1。模式 1 不会 在没有参数值的位置内插采样。如果要按周期计算时间戳,一周期一个,则使用 0。模式 0 会在没有参数值的位置内插采样。 返回值 有关返回值,请参见 返回数据。 显示模式 根据 TrnQuery 的显示模式,返回的数据将存在很大的差异。显示模式可分为下列互斥选 项: 排序趋势样本选项 ? 0 - 按照最旧到最新的顺序对返回的样本进行排序。 ? 1 - 按照最新到最旧的顺序对返回的样本进行排序。当“行”数据选项被指定时不支持此 模式。 压缩方法选项 ? 0 - 设置压缩方法以使用样本的平均值。 ? 4 - 设置压缩方法以使用样本的最小值。 ? 8 - 设置压缩方法以使用样本的最大值。 ? 12 - 设置压缩方法以使用样本的最新值。 拉伸方法选项 ? 0 - 为单步设置拉伸方法。 ? 128 - 设置拉伸方法以使用比率。 ? 256 - 设置拉伸方法以使用行样本(无查询)。 间隙填充常量选项

122

Chapter: 4 CtAPI 函数

? n - 用户希望进行间隙填充的丢失的样本数量 x 4096。 最近有效数值选项 ? 0 - 将给定值保留为质量最差的样本时,此值为 0。 ? 2097152 - 将质量最差的样本设置为最近有效数值(没有最近有效数值时则为 0)。 行数据选项 ? 0 - 不返回行数据时,例如,将使用压缩和拉伸模式对数据进行压缩和采样。 ? 4194304 - 返回总的行数据时,例如,无压缩或无采样。只有指定了 query = 1 的 DataMode 时才支持此模式。在使用此模式时,如果在时间范围内存在的行样本超过最 大值,则将返回比指定的最大数量更多的样本。 返回的数据 系统会针对查询的每个数据记录返回以下属性。 ? DateTime:自 1970 年以来的趋势采样时间(以秒计),该时间在 UTC(通用时间坐 标系)中以整数表示。 ? MSeconds:趋势采样时间的毫秒组成部分(以整数表示)。此参数值介于 0 到 999 之 间。 ? Value:采样的趋势参数值(以双精度值表示)。 ? Quality:与趋势采样关联的质量信息(以无符号的整数表示)。Quality 属性无符号 整数的位数不同,包含的信息也不同,如下所述: 参数值类型(0 - 3 位) ? ValueType_None (0):给定采样中不包含任何参数值。采样参数值、时间和 质量都应被忽略。 ? ValueType_Interpolated (1):已通过参数值周围的数据内插了参数值。 ? ValueType_SingleRaw (2):参数值基于一个原始采样。 ? ValueType_MultipleRaw (3):参数值已通过多个原始采样进行计算。 参数值质量(4 -7 位) ? ValueQuality_Bad (0):采样的参数值应被忽略,因为没有要依据的原始数 据。 ? ValueQuality_Good (1):采样的参数值有效,并基于某些原始数据。 最后一个参数值质量(8 -11 位) ? LastValueQuality_Bad (0):采样的参数值应被忽略,因为没有要依据的原始 数据。 ? LastValueQuality_Good (1):周期内最后一个原始采样的参数值质量完好。 ? LastValueQuality_NotAvailable (2):周期内最后一个原始采样的参数值质量 不可用。 ? LastValueQuality_Gated (3):周期内最后一个原始采样的参数值质量被阻 挡。 部分标志(12 位) 将“部分标志”设置为 1,表明可以在下次读取采样时对其进行更改。恰好在当前时刻获 取采样时会出现上述情况,但返回的采样不必非常完整,因为此周期内可以获得更多采 样。

123

Chapter: 4 CtAPI 函数

CtAPIAlarm
提供从外部应用程序进入报警汇总归档中的接口。要提高性能,请转而使用 AlmQuery 函 数。 要建立查询并返回第一条记录,可以调用 ctFindFirst。然后,要浏览其余记录,可以调用 ctFindNext。要访问当前记录的数据,可以针对记录的每个字段调用 ctGetProperty。 ctFindFirst 使用以下参数进行调用: ? hCtapi:有效 CtAPI 客户机实例的句柄。 ? szTableName:almquery 的命令字符串,请参见下文。 ? szFilter:不用于 Almquery。仅在 NULL 中传递。 ? hObject:针对查询检索的第一条记录的句柄。 ? dwFlags:不用于 Almquery。仅在 0 中传递。 szTableName 是查询的命令字符串,且包含查询的所有参数。 语法 CTAPIAlarm(Category,Type,Area) 注意:参数必须用逗号分隔。参数之间隔空格受支持,但不是必需的。建议不要在参数之 间加空格,因为空格需要更多处理,并在查询字符串中占用更多空间。 Category: 要匹配的报警分类或组合编号。将 Category 设置为 0(零)可与所有报警分类匹 配。 Type: 要查找的报警的类型: 非硬件报警 ? 1. 所有未确认的报警,ON 和 OFF。 ? 2. 所有确认的 ON 报警。 ? 3. 所有禁止的报警。 ? 4. 所有组态报警,即类型 0 至 3,另加确认的 OFF 报警。 如果不指定类型,则缺省值为 0。 Area: 从中搜索报警的区域。如果不指定区域,或将 Area 设置为 -1,则只搜索当前区 域。 要简化此参数的传递,可以先将 CTAPIAlarm() 函数作为字符串传递,然后将该字符串用 作 szTableName 参数(无需引号)。

CtAPITrend

124

Chapter: 4 CtAPI 函数

提供从外部应用程序进入趋势归档中的接口,取代了原来的 CtAPITrend 查询。要提高性 能,请转而使用 TrnQuery 函数。 要建立查询并返回第一条记录,可以调用 ctFindFirst。然后,要浏览其余记录,可以调用 ctFindNext。要访问当前记录的数据,可以针对记录的每个字段调用 ctGetProperty。 ctFindFirst 使用以下参数进行调用: ? hCtapi:有效 Ctapi 客户机实例的句柄。 ? szTableName:Trnquery 的命令字符串,请参见下文。 ? szFilter:不用于 Trnquery。仅在 NULL 中传递。 ? hObject:针对查询检索的第一条记录的句柄。 ? dwFlags:不用于 Trnquery。仅在 0 中传递。 szTableName 是用于查询的命令字符串。它包含用于查询的所有参数。 语法 CTAPITrend(sTime,sDate,Period,Length,Mode,Tag) 注意:参数必须用逗号分隔。参数之间的空格受支持,但不是必需的。建议不要在参数之 间加空格,因为空格需要更多处理,并在查询字符串中占用更多空间。 sTime: 趋势的起始时间。将时间设置为空字符串可搜索最近的趋势采样。 sDate: 趋势的日期。 Period: 希望搜索的周期(以秒为单位)(此周期可与实际趋势周期不同)。 CTAPITrend() 函数用作针对 EVENT 趋势查询的 ctFindFirst() 的参数时,该函 数中使用的 Period 参数必须为 0(零)。 Length: 数据表格的长度,即要搜索的采样的行数。 Mode: 要使用的格式模式: 周期趋势 ? 1 - 搜索日期和时间,后跟标签。 ? 2 - 只搜索时间,后跟标签。 ? 3 - 忽略任何无效或门限值。(只有周期趋势支持此模式。) 事件趋势 ? 1 - 搜索时间、日期和事件号,后跟标签。 ? 2 - 搜索时间和事件号,后跟标签。 Tag:

125

Chapter: 4 CtAPI 函数

要搜索的数据的趋势标签名称。 要简化此参数的传递,可以先将 CTAPITrend() 函数作为字符串传递,然后将该字符串用 作 szTableName 参数(无需引号)。

126

Chapter: 5

CSV_Include 参考

本节提供关于以下方面的信息: CSV_Include citect.ini 参数 CSV_Include Cicode 函数

CSV_Include 参数
下表显示了 citect.ini 文件内各区域的参数信息。

区域 [Alarm] 区域参数 [MultiMonitors] 参数 [Page] 参数 [Navigation] 参数 [TrendX] 参数 [Privilege] 参数

[报警] 区域参数
[报警] 区域包含以下参数: ? [Alarm]Soundn ? [Alarm]SoundnInterval ? [Alarm]LastAlarmFmt ? [Alarm]LastAlarmCategories ? [Alarm]LastAlarmPriorities ? [Alarm]LastAlarmType

[Alarm]Soundn
根据报警的优先级 (n) 确定报警响起时使用的 wav 文件。例如,[Alarm]Sound1 可标识在触 发优先级为 1 的报警时将响起的 .wav 文件。

127

Chapter: 5 CSV_Include 参考

允许的值:任何有效的 wav 文件名,包括完整的目录路径。 可以使用 Vijeo Citect 的预定义替换路径来查找 wav 文件,例如:
Sound1=[RUN]:Alarm1.wav.

缺省值:(无声音) 另请参见 [报警] 区域参数

[Alarm]SoundnInterval
根据报警的优先级 (n),确定报警持续响起的时间。例如,[Alarm]Sound1Interval 可确定 在触发优先级为 1 的报警时听的见的报警持续的时间。 允许的值:250 - 30000 毫秒 缺省值:2000 另请参见 [报警] 区域参数

[Alarm]LastAlarmFmt
指定用于报警工具栏上的最新报警列表的列和格式。 注意:此参数对于每个 Vijeo Citect 工程都可用;但是,根据 CSV_Include 模板作为工程 的一部分实施时,其缺省值是不同的。 允许的值:报警显示字段的任意组合。 缺省值:{Time,12}{Date,12}^t{Name,15}^t{Desc,35}^t{State,9} 另请参见 [报警] 区域参数

[Alarm]LastAlarmCategories
根据类型,确定哪些报警显示在报警工具栏上。例如,如果要让报警列表仅显示类别 1 的 报警,则可以将此参数设置为 1。 允许的值:1 - 16376 缺省值:0(所有报警) 另请参见 [报警] 区域参数

128

Chapter: 5 CSV_Include 参考

[Alarm]LastAlarmPriorities
根据优先级,确定哪些报警显示在报警工具栏上。例如,如果要让报警列表仅显示优先级 1 的报警,则可以将此参数设置为 1。 允许的值: 1 - 255 缺省值:0(所有报警) 另请参见 [报警] 区域参数

[Alarm]LastAlarmType
根据类型,确定哪些报警显示在报警工具栏中。 允许的值: 0 - 14 非硬件报警 ? 0 - 所有活动报警,即类型 1 和 2 ? 1 - 所有未确认的报警,ON 和 OFF ? 2 - 所有已确认的 ON 报警 ? 3 - 所有已禁用的报警 ? 4 - 所有已配置(非硬件)报警,即类型 0 到 3,外加已确认的 OFF 报警。 硬件报警 ? 5 - 所有活动报警,即类型 6 和 7 ? 6 - 所有未确认的报警,ON 和 OFF ? 7 - 所有已确认的 ON 报警 ? 8 - 所有已禁用的报警 ? 9 - 所有已配置的报警,即类型 5 到 8 报警汇总 ? 10 - 所有的汇总报警 通用报警 ? 11 - 所有的 ON 报警 ? 12 - 所有的 OFF 报警 ? 13 - 所有的 ON 硬件报警 ? 14 - 所有的 OFF 硬件报警 缺省值: 0 另请参见 [报警] 区域参数

[MultiMonitors] 参数
[Mu

赞助商链接
相关文章:
更多相关标签: