简介《WINCC-C脚本大全.pdf》面向西门子WinCC组态开发人员与SCADA/HMI工程师聚焦C脚本标准函数的查阅与套用适合需要自定义报警控件工具栏、扩展画面交互的初中级开发者。文档以Alarm组函数为主线逐条给出AcknowledgeMessage、AXC_OnBtnArcLong、AXC_OnBtnMsgFirst等函数的返回值、参数含义与调用示例并解释lpszPictureName、pszMsgWin等参数与画面名、控件对象名的对应关系示例中包含GetTagWord读取消息号等实用写法方便照搬修改。压缩包仅含1个PDF文件约58KB体量轻巧、便于随查随用。目前已有2411人学习下载可作为WinCC C脚本开发时的函数速查手册与排错参考。1. 弹窗关一次就再也打不开WinCC C 脚本真正解决的场景现场最典型的开场是这样的画面窗口里的确认弹窗第一次能弹出来关掉之后再点按钮就没反应了重启运行系统又正常。翻组态按钮上挂的是一段 WinCC C 脚本关闭时把画面窗口里的画面卸载了第二次打开时窗口对象还在但里面已经空了。这类问题用 VBS 也能写但 WinCC 的 C 脚本在批量变量读写、周期任务、直接改对象属性这三件事上更贴近底层通讯执行路径更短也更容易被误用成把运行系统拖死的元凶。围绕 WINCC-C脚本大全这个关键词下面讲的是画面组态里那些重复劳动怎么用 C 动作收掉动作挂在哪里、GetTag 和 SetTag 家族的类型怎么对齐、Wait 与非 Wait 的区别、报表和趋势场景怎么落地以及从脚本诊断到跨版本移植的排错路径。适合已经在做 WinCC 画面、手上有几十个按钮动作想统一整理的工程师。2. WinCC C 脚本的运行机制动作、触发器与选型边界2.1 画面脚本与全局脚本同一个 C 动作挂在哪里WinCC 里的 C 动作只有两个落脚点。一个是画面内的对象事件比如按钮的鼠标动作、对象属性的动态对话框另一个是全局脚本编辑器里的动作按模块组织运行系统启动后就在后台跑。很多人把采集逻辑写在按钮的鼠标动作里结果画面一关计算就断事后排查半天。正确的分法是跟人操作绑定的逻辑放画面对象跟时间或数据变化绑定的逻辑放全局脚本。两者在调试和改动成本上的差别很大选错位置后期维护会很痛苦。对比项画面对象里的 C 动作全局脚本里的 C 动作存放位置画面文件内跟着对象走全局脚本编辑器的项目模块、标准模块生命周期画面打开期间有效画面关闭即停止运行系统启动后持续有效复用方式复制到别的对象要重新挂一遍多个画面、多个触发点共用一份典型用途按钮命令、对象属性动态周期采集、跨画面计算、状态机改动风险改画面就要重新验证该画面改一处影响所有调用方需回归入口函数的形态也不一样。画面按钮的鼠标动作由编辑器生成固定原型函数体自己写#include apdefap.h /* 画面按钮按左键事件参数由运行系统传入不要改签名 */ void OnLButtonDown(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { /* lpszObjectName 就是被点击的按钮对象名可用来做对象自识别 */ SetTagBit(Line1/Cmd_Start, 1); }全局脚本的 C 动作入口一般长这样函数名和返回类型由模板给出照模板填函数体即可#include apdefap.h /* 全局脚本 C 动作入口由脚本编辑器模板生成 */ int gscAction(void) { /* 这里放周期性的计算、汇总、状态判断 */ return 0; }参数上要留意一点lpszPictureName是运行系统传进来的当前画面名用它配合SetPropXXX系列改本画面对象的属性最省事比写死画面名更稳。2.2 触发器定时器、变量触发与循环脚本的真实含义现场说的循环脚本绝大多数不是指某段循环语句而是指把动作挂到周期触发器上反复执行。全局脚本的触发器通常有两类定时器常见档位有 250ms、500ms、1s、1min、1h 等和变量触发变量变化时执行、变量到达指定值时执行。选择哪一档取决于被采集信号的变化速度和期望的响应延迟。真正有害的是在动作里写自循环动作永远不返回图形更新线程被占满#include apdefap.h int gscAction(void) { /* 反例动作不返回画面刷新和通讯处理会被拖住 */ while (1) { SetTagFloat(Tank/Avg, GetTagFloat(Tank/Avg) 1.0f); /* 没有退出条件、没有休眠运行系统表现为画面卡死 */ } return 0; }把循环交给触发器动作内只做一轮处理这才是运行系统能承受的写法#include apdefap.h /* 挂在 1s 定时器上每轮只处理一次立刻返回 */ int gscAction(void) { static double dSum 0.0; /* static 变量在动作周期内保持 */ static int iCnt 0; dSum GetTagDouble(Tank/Level); iCnt; SetTagDouble(Tank/Avg, iCnt 0 ? dSum / iCnt : 0.0); return 0; }这段代码里有两个要点。static修饰的局部变量在全局脚本动作里能跨触发周期保持数值但运行系统重启后会清零班次统计这类需要断电保持的量应该落到内部变量或 PLC 里。定时器档位决定了采样密度1s 触发意味着脚本一旦被阻塞这段时间的采样就丢了做趋势和报表时要接受这个精度上限。2.3 C 还是 VBS按任务类型选不要按习惯选同一件事两种脚本都能做但成本差得远。变量批量读写、位运算、数值累加这类偏计算的活儿C 脚本更直接控件属性控制两者都行VBS 的属性访问写法更接近面向对象读起来顺写关系数据库做报表VBS 用CreateObject建 ADO 连接几行就够C 脚本走 COM 需要手工处理接口指针投入产出比不高。任务类型更省事的选择原因多变量读取与数值运算C类型明确位运算和格式化直接可用趋势图、在线表格时间范围设置VBS 或 C两者都是改控件属性VBS 可读性更好把统计结果写进自建 SQL 库VBSADO 连接对象一句话建好C 需手工调 COM归档历史值查询归档控件绑定脚本只负责设时间段别去手写查询大量字符串拼接、编号生成Csprintf 格式化比字符串连接高效一个常见组合是C 脚本挂在周期触发器上做采集和计算结果写进内部变量同一触发周期里由 VBS 读这些变量并落库。分工清楚两边都不憋屈。2.4 授权与运行环境脚本不执行时先查这两处脚本写得好好的却没有任何反应先看两处。一是运行系统的授权状态全局脚本的运行属于运行系统授权范围授权不满足时运行系统会进入受限或演示状态并给出提示脚本的表现会变得不可预期具体授权名称以本机授权管理器里列出的条目为准。二是脚本诊断开关很多机器默认没打开动作里的输出全部进了黑洞从现象上看就像脚本没跑。这两点确认过之后再去怀疑代码。3. WinCC C 脚本最小可跑示例变量读写、Wait 语义与字符串处理3.1 GetTag/SetTag 家族类型错一位读出来的数就是乱的WinCC 的 C 函数按数据类型分成一整套函数名后缀直接对应变量表里的数据类型。用错函数的后果不是报错而是数值悄悄变样把一个 32 位浮点变量用 16 位函数去读得到的是一段毫无意义的位模式。变量数据类型读取函数写入函数返回值/入参形式二进制BOOLGetTagBitSetTagBit0 / 18 位无符号GetTagByteSetTagByte0~25516 位有符号GetTagSWordSetTagSWord-32768~3276732 位无符号GetTagDWordSetTagDWord0~429496729532 位浮点GetTagFloatSetTagFloatfloat64 位浮点GetTagDoubleSetTagDoubledouble文本变量GetTagStringSetTagStringchar 数组一段最小的可跑动作如下读两个变量按条件写两个变量#include apdefap.h void OnLButtonDown(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { float fLevel 0.0f; short sMode 0; fLevel GetTagFloat(Tank/Level); /* 变量路径按变量管理树层级用 / 分隔 */ sMode GetTagSWord(Tank/Mode); /* 对应有符号 16 位 */ if (fLevel 80.0f sMode 1) { SetTagBit(Tank/LevelHigh, 1); /* BOOL 只有 0 和 1 */ SetTagFloat(Tank/Sp, fLevel 5.0f); /* 写回设定值 */ } else { SetTagBit(Tank/LevelHigh, 0); } }参数说明函数第一个参数是变量名按变量管理里的层级路径写分隔符用/SetTag系列没有返回值可供判断成功GetTag系列返回的是数值本身。这里有个容易忽略的边界单值读取函数读失败时返回 0 或空串调用方分不清值真的是 0还是根本没读到。需要区分数据质量时一般用多值版本带出的状态字或者在画面上通过变量的质量属性间接判断别用if (GetTagFloat(x) 0)这种写法做通讯判断。3.2 Wait 与非 Wait写变量的同步代价写入函数有两套差别在同步还是异步。SetTagXXX把写请求交给后台的写任务队列就立刻返回脚本继续往下跑SetTagXXXWait会等写入真正完成才返回。什么时候必须用 Wait写完立刻要基于新值做判断的时候。#include apdefap.h void OnLButtonDown(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { /* 先同步写入模式位再读状态做互锁判断 */ SetTagBitWait(Line1/Cmd_Auto, 1); if (GetTagBit(Line1/Status_Block) 1) { /* 读到的可能是写请求生效前的旧值因此这里只作提示不作安全联锁 */ SetTagBit(Line1/Alarm_CmdFail, 1); } }函数形态行为适用场景风险SetTagXXX异步入队立即返回连续大量写、状态刷新紧随其后的读可能拿到旧值SetTagXXXWait同步等待写入完成写完即读、互锁相关在周期动作里大量使用会累积阻塞选择原则很直白画面按钮动作里用 Wait 基本没代价用户点击本来就稀疏周期触发器里就要克制250ms 档位里塞十几个 Wait 调用累积起来就是画面响应变慢的直接原因。另外要记住一点脚本这边的同步只保证写请求生效PLC 侧的响应时间和互锁判断不能依赖 HMI 脚本安全逻辑该在 PLC 里做还在 PLC 里做。3.3 多值读写与结构变量一次触发里少往返几趟结构变量按数据类型分组同组变量在物理上落在相邻地址逐个用GetTagFloat读会分成多次调用。多值版本的存在意义就是把这些调用合并一次触发里读出整组值或写回整组值。它的参数形式是重复的变量名—接收指针或者变量名—状态字—接收缓冲组合具体原型以本机 WinCC 信息系统的 ANSI-C 函数说明为准不同版本在状态字的传递方式上略有差异写之前先把原型抄一遍。用法上有几条实践经验。第一多值版本适合一次取 5 个以上的相关变量低于 3 个时合并收益不明显代码反而难读。第二接收缓冲的类型必须和变量类型严格对应用double的缓冲去接 16 位整型变量得到的是垃圾数据。第三结构变量在变量管理里改名后脚本里的字符串路径不会自动跟着改这是移植事故的高发点工程上一般约定变量名一旦投用就不再改或者把变量路径集中定义在一处。3.4 字符串与格式化sprintf 的边界组态里常见的需求是把数值和文字拼成一条消息写进文本变量用sprintf最直接。#include apdefap.h int gscAction(void) { char szMsg[256]; /* 缓冲区要留结束符位置 */ double dTemp GetTagDouble(Reactor/Temp); sprintf(szMsg, 反应釜1 温度 %.1f 度超限, dTemp); SetTagString(HMI/MsgText, szMsg); /* 文本变量的长度上限以变量定义为准 */ return 0; }参数说明格式串里的每个%占位符都要有对应的实参%.1f表示保留一位小数缓冲区尺寸要大于最终字符串长度加结束符写死 256 字节是常见做法但前提是内容确实不会超。两个坑要记住缓冲区小于实际内容会造成越界写轻则消息乱码重则运行系统直接退出中文内容在经典 WinCC 项目里默认走单字节字符集工程从别处复制过来时字符集不一致会出现方框或截断写消息前先在画面上用一个 I/O 域回显验证一下。4. WinCC C 脚本的三个真实场景弹窗失活、报表取数、位置动态4.1 画面弹窗关一次就打不开根因与修法这个现象的根因通常不在按钮而在关闭动作做了什么。如果关闭时调用了卸载画面的函数把画面窗口里的画面实例清掉了第二次打开时窗口对象还在但没有重新指定要显示的画面表现出来就是点了没反应或者弹出个空白框。稳妥的做法是让画面实例常驻只切换可见性确实需要换画面时严格按先设画面名、再置可见的顺序来。#include apdefap.h /* 打开弹窗先指定画面再显示顺序反了会闪一下空白窗口 */ void OnLButtonDown(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { SetPropChar(lpszPictureName, PWin_Popup, PictureName, Popup_Confirm); SetPropWord(lpszPictureName, PWin_Popup, Visible, 1); } /* 关闭弹窗只关可见性不卸载画面实例下一次才能再打开 */ void OnLButtonDown_Close(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { SetPropWord(lpszPictureName, PWin_Popup, Visible, 0); }参数说明lpszPictureName用运行系统传入的当前画面名别写死PWin_Popup是画面窗口对象名要和对象属性窗口里的名字完全一致PictureName、Visible是属性名拼写按属性窗口给出的英文名抄不要凭记忆写。如果修完还是打不开按顺序查三处画面窗口的更新属性是不是被设成了否导致画面不刷新该对象的某条可见性动态是不是被写成了常量画面窗口尺寸是不是被脚本改成了 0窗口在但看不见。更省事的替代方案是给可见性挂一个内部位变量的动态脚本只负责翻转这个位属性名对不对的问题就不存在了。4.2 循环脚本取数做报表周期触发与自建报表库报表有两条路。只是想看归档趋势用在线表格和趋势控件直接绑归档变量脚本负责设时间段即可不需要写库。需要做班次统计、导出 Excel、给上层系统取数就要落到关系数据库这时要强调一句不要往 WinCC 自己的归档库里写表那个库的结构由运行系统维护升级和归档整理都会动到它。在自己建的库里建表结构自己说了算。/* 建在自建库上按班次存统计结果不碰 WinCC 归档库 */ CREATE TABLE dbo.ProdReport ( Id INT IDENTITY(1,1) PRIMARY KEY, ShiftDate DATE NOT NULL, ShiftName NVARCHAR(16) NOT NULL, TagName NVARCHAR(64) NOT NULL, AvgValue FLOAT NULL, MaxValue FLOAT NULL, MinValue FLOAT NULL, SampleCount INT NULL, InsertTime DATETIME DEFAULT GETDATE() ); CREATE INDEX IX_ProdReport_Shift ON dbo.ProdReport (ShiftDate, ShiftName, TagName);采集侧由 C 脚本在周期触发器里完成班次结束时把结果写进内部变量落库交给 VBS 或外部程序#include apdefap.h /* 挂在 1s 定时器上做班次累加结果写入内部变量供落库 */ int gscAction(void) { static double dSum 0.0; static double dMax 0.0; static int iCnt 0; double dVal GetTagDouble(Tank/Level); dSum dVal; iCnt; if (dVal dMax) { dMax dVal; } if (GetTagBit(Shift/End) 1) { SetTagDouble(Report/Level_Avg, iCnt 0 ? dSum / iCnt : 0.0); SetTagDouble(Report/Level_Max, dMax); SetTagDWord(Report/Level_Cnt, (DWORD)iCnt); SetTagBit(Report/Ready, 1); /* 交给落库侧判断 */ dSum 0.0; dMax 0.0; iCnt 0; /* 班次复位 */ } return 0; }触发周期怎么选直接影响报表精度和运行系统负担触发档位适用数据代价注意250ms快速波动量、联锁监视运行系统负担最高动作必须极短别放字符串和写库1s温度、液位、压力等常规量中等班次统计的常用档位1min电耗、累计量、报表汇总最低缺失点靠归档补不要用它做控制4.3 趋势图与在线表格的时间范围控制趋势控件的时间范围可以靠脚本切。相对时间用秒数设绝对起止时间用字符串设属性名随控件类型不同先在属性窗口里手动改一次记下属性名的确切拼写再写进脚本。#include apdefap.h /* 把趋势控件切到最近 8 小时 */ void OnLButtonDown(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int x, int y) { SetPropDouble(lpszPictureName, Trend_1, TimeRange, 8 * 60 * 60); }比脚本硬改属性更稳的做法是把控件的起始和结束时间挂到两个内部变量上脚本只负责给这两个变量赋值属性名对不对的问题一次性解决后期换控件也不用重写逻辑。VBS 在这方面写法更直观ScreenItems拿对象再点属性可读性好很多人趋势画面用 VBS、采集计算用 C就是一个很实用的分工。4.4 静态文本位置 X 的动态属性是怎么被脚本改的属性窗口里几何 → 位置 X右边那个小图标作用是把这一项从常量改成动态可以绑变量也可以挂 C 动作。它等价于让脚本去写对象的Left属性。#include apdefap.h /* 让文字随液位横向移动Left 基准 比例 × 行程 */ int gscAction(void) { double dRatio GetTagDouble(Tank/Level) / 100.0; int iLeft 50 (int)(dRatio * 300.0); SetPropDouble(lpszPictureName, Txt_Level, Left, (double)iLeft); return 0; }参数说明Left是相对父对象画面或分组的像素坐标不是屏幕绝对坐标写在分组里的对象要按分组原点算。驱动方式上有个选择属性动态绑变量时由变量变化触发开销小挂在周期触发器上时每轮都重算一遍画面对象多的时候重绘压力明显。做动画类效果优先用变量触发而不是定时器。5. WinCC C 脚本排错与跨版本移植诊断输出、阻塞失控与移植顺序5.1 让脚本说话脚本诊断窗口与消息框脚本不按预期跑第一步是让它能输出。运行系统所在计算机的启动列表里勾上全局脚本诊断动作里的printf才会把内容送到诊断窗口没勾的时候输出全部丢弃现场表现就是脚本像是没执行。第二步是插桩临时加一句消息框#include apdefap.h int gscAction(void) { printf(gscAction enter, level%.2f\n, GetTagDouble(Tank/Level)); /* 临时插桩用弹框会阻塞图形处理验证完立刻删掉 */ return 0; }消息框MessageBox能确认动作有没有被触发但它会阻塞图形处理线程只能用在单点调试绝对不要留在周期动作里。更安全的一种插桩方式是把中间值写进一个内部变量再在画面上放个 I/O 域盯着看既不影响节拍也能看到趋势。现场现象常见原因处理动作动作完全不执行触发器没配、脚本诊断未开、授权受限先看触发器再看诊断输出和授权状态画面周期性卡顿周期动作里大量 Wait 调用或字符串操作拆动作、降低触发频率、把计算移到低频档运行系统内存持续上涨反复新建画面实例未释放、大缓冲越界改成切可见性检查 sprintf 缓冲长度数值明显不对读写函数类型与变量类型不匹配核对函数后缀与变量表数据类型换机器后脚本报错变量路径改名、字符集不一致逐条核对变量名确认工程字符集5.2 跨版本带上多少变量路径与脚本语言的现实差距把经典 WinCC 项目往博途体系迁移时C 动作能原样带走的比想象中少。变量从结构变量、变量组变成 HMI 变量表和连接脚本里的字符串路径要同步改改漏一个就是运行期读失败而不是编译期报错。脚本语言上更要注意博途里的部分运行版本只提供 VBS 脚本能力经典项目的 ANSI-C 动作搬过去需要改写或者选用支持 C 的运行版本具体支持范围以所用版本的功能说明为准不要按老项目的经验想当然。移植顺序建议按改动量从小到大推进先搬变量读写类动作这类逻辑基本不变只需要核对变量名再搬属性控制类动作属性名在版本之间常变必须逐个在属性窗口核对最后处理写库和报表类动作这类多半要重写成 VBS 或挪到外部程序工作量最大放在最后做前面稳定了再动。收尾时做一件事就够了建一个脚本自检画面把每个周期动作的心跳位、执行次数和最近一次执行时间摆上去现场点开一眼就能看出哪个动作已经停了。本文还有配套的精品资源点击获取