如何使用函数 “SetTagMultiWait()” 来写多个 WinCC 变量?

说明：
在WinCC 全局 C 脚本中有几个默认的 "SetTagMulti()"函数用来写多个 WinCC 变量值：n

• BOOL SetTagMultiWait(const char* pszFormat, const char* pszTag, void vValue, ...)
• BOOL SetTagMultiStateWait(DWORD* pdwState, const char* pszFormat, const* pszTag, void vValue, ...)

这些函数就是所谓的“Wait”函数，他们直接将变量值写入 PLC 而不是 WinCC 的数据管理器中。这些函数参数的数量是变化的；这取决于要写的变量数量。n

参数：
以下参数被传送给“SetTagMulti()”函数：n

• DWORD* pdwState (仅用于 SetTagMultiStateWait())
  “SetTagMulti()“函数的使用必需一个双字变量类型的数组 DWORD (保留内存)，指向该区域首个元素的指针被传送给“SetTagMulti()“函数。“SetTagMulti()"“函数持续将所写 WinCC 变量的状态写入所传送的地址中。n
• const char* pszFormat
  “GetTagMulti()“函数的使用必需一个可用的字符串(保留内存)并用其存贮要写的 WinCC 变量的格式信息。指向该字符串首个元素的指针被传送给“SetTagMulti()“函数。n
• const char* pszTag
  “pszTag“是一个指向包含对应 WinCC 变量名称的字符串的指针。使用“SetTagMulti()“函数时必须为每个要写的变量传送一个“pszTag“字符串。n
• void vValue
  “vValue“是其变量值要写入 WinCC 的变量。n
• “SetTagMulti()“函数的使用必须为每个要写的变量传送该参数。n
• 该参数的实际数据类型取决于要写的 WinCC变量的数据类型。可能的数据类型请参照以下表格。n
• Return value:
  当“SetTagMulti()“函数正确完成执行则函数返回值“TRUE“。若程序运行中有错误产生，如值“ZERO“被传送给至少一个参数或格式字符串包含无效的格式，“SetTagMulti()“函数返回值“FALSE“。该函数不能检查变量值是否被正确写入。因此您不能使用该返回值检查 WinCC 变量的写入是否成功。因此您应该使用 “SetTagMultiStateWait()“函数及关联的变量状态来评估错误。

WinCC 变量的质量信息(变量状态)可在 WinCC 信息系统中的以下位置找到：n

• “通讯 > 通讯 - 诊断> 变量质量> 变量状态“

关于“SetTag()“函数如何运行的常规信息可在 WinCC 信息系统中的以下位置找到：n

“使用 WinCC > 使用 ANSI-C 创建函数和动作 > ANSI-C 函数描述 > 内部函数 >变量 >写 > SetTag 函数的功能“n

下表描述了格式字符串中可能的格式并说明了何种格式可以同何种 WinCC和 C 数据类型一起使用：

配置错误时的系统行为：
下面是对配置错误情况下的描述：n

• 访问一个未在 WinCC 变量管理器中创建的 WinCC 变量
  如果您使用“SetTagMultiWait()“ 或 “SetTagMultiStateWait()“函数来访问一个未在 WinCC 变量管理器中创建的变量，则一条“OnErrorExecute“错误消息 (“未知变量，超时或交互失败 - 未发现变量“)产生在全局脚本诊断窗口或“APDIAG”输出窗口。变量状态包含一个所产生的访问错误的信息 。n
• 使用一个小于4个字节存贮区的 C 数据类型读一个 WinCC 整数
  如果您使用一个所占存贮区小于4个字节的 C 变量(如BYTE, WORD, char 或 short)来写一个整型 WinCC 的内容，那么很可能会将一个不正确的值写入 WinCC变量，因为函数总会写4个字节。变量状态现实一个错误 ("格式超限")。
• 访问一个无符号32位 WinCC 变量值时将其最高位(31位) 被置位
  如果您要将一个“DWORD”类型的 C 变量的内容写入一个31位被置1的无符号32位(“DWORD“)类型的
  WinCC 变量，, 那么“SetTagMulti()“ 函数不会将值写入 WinCC 变量。没有“OnErrorExecute“错误消息显示在全局脚本诊断窗口或“APDIAG“输出窗口。变量状态包含已产生错误的信息 ("格式超限")。
  修正： n
  • 可能的话，确定无符号32位 WinCC 变量的31位不被设置。n
  • WinCC 变量是一个外部变量，那么您可以在 WinCC 变量管理器中为该变量配置上限：2147483648 (hexadecimal 0x80000000) 。

    
    图. 01

    违反上限组态就会反映在质量代码和变量状态中并可做进一步处理。

  • 使用函数“SetTagDWordXXX()“。n
  • 在变量管理器中创建一个有符号的32位 WinCC 变量并为 C 变量使用数据类型“DWORD”。
• 格式字符串的错误结构 n
  • 格式说明同实际使用的数据类型不一致
    下面列出了格式说明使用错误的情况，此时函数将被终止并返回“FALSE”： n
    • 格式说明“%s“或 “%f“ 被用来写一个整数。n
    • 格式说明“%s“或 “%d“ 被用来写一个浮点数。n
    • 格式说明“%f“ 被用来写一个文本变量。

    下面描述了格式说明有误且函数被终止并返回值“TRUE“的情况。然而，这时将会写入一个非期望的值。变量状态不包含所产生访问错误的信息。 n

    • 格式说明“%d“ 被用来写一个文本变量。
  • 格式字符串包含的格式说明过多
    在格式字符串参数中有些参数 (pszTag, vValue) 对所有的格式说明是必须的，如果这些参数没有被传送给“SetTagMulti()“，那么一条“OnErrorExecute“错误消息(“未知变量，超时或交互失败 - 未发现变量“)产生在全局脚本诊断窗口或“APDIAG”输出窗口。变量状态包含一个产生的访问错误的信息 。
    注意：
    如果超过格式字符串中所指定的参数(pszTag, vValue) 被传送了, 那么格式字符串所指定的值将会被正确写入。格式字符串未指定的值不会被写入。 这些变量的变量状态包含了提示已产生访问错误的消息。没有“OnErrorExecute“错误消息显示在全局脚本诊断窗口或 “APDIAG“输出窗口中。n
  • 实例组态：格式字符串的动态结构
    若要使用 SetTagMulti() 函数写入多个变量，格式字符串的结构就不那么清晰了。 这时您将很难用肉眼快速判断出在格式字符串中是否有足够的格式说明及这些格式说明对所使用的数据类型是否有效。为避免格式字符串的结构错误，您可以在运行过程中配置格式字符串，要通过 SetTagMulti() 函数写入的变量的信息可以被存储在一个区域中。在这里，每个区域元素代表了一个包含所需要信息(格式说明, WinCC 变量名称和相关的C 变量)的结构。

下面是一个可下载的关于该过程演示的脚本(PDF和文本文件)。

WinCC_SetTagMulti_c.zip ( 7 KB )

WinCC_SetTagMulti_c.pdf ( 10 KB )

下面两幅图展示了变量管理器中的外部和内部 WinCC 变量，这些变量在实例脚本中被“SetTagMultiStateWait()”函数写入。

图. 02

图. 03

脚本可以在画面中作为一个 C 动作被调用(如一个按钮的鼠标点击事件)。
下图中展示了运行时 WinCC 变量的内容。WinCC 变量通过直接变量连接到 I/O 域的“输出”属性的方式被显示在画面中，诊断工具“APDIAG”的输出窗口显示被写入的值。

图. 04

注意：
脚本使用 WinCC V6.2 创建。