版本声明全系列统一口径本篇基线为AVEVA E3D Design 3.1。命令与示例代码来自官方培训材料AVEVA PML for E3D Design Instructor-Led Training 中的PML Macros Functions模块口径课程页https://learningacademy.aveva.com/courses/aveva-pml-for-e3d-design-instructor-led-training与官方文档批量改名片段的写法出自AVEVA Community 的真实帖正文已标注为社区来源。写库操作不可逆本篇所有NEW/RENAME示例必须在测试 MDB 上执行或先做备份。官方把 PML 交互入口称为Command Window命令窗口路径为Tools 标签 → Display 组 → Commands文档中没有 “PML Console” 这个名称。一句话结论PML 宏就是一串能回放的命令文本它没有参数声明、没有函数签名——你写在宏文件名后面的东西会按顺序替换进宏里的$1、$2……这就是官方培训材料里最简单的参数化机制也是所有批量作业的起点。〇认知问题PML 宏和 PML 函数到底有什么区别我该先写哪个$M/路径和$m/文件是两套语法吗大小写有讲究吗宏怎么接收参数为什么我在官方示例里找不到任何参数声明或param关键字我看见NEW $!CompType DIST $!dist这样的写法$!是什么和$1有什么区别宏能不能挂到界面上点一下就跑官方对这个做法是什么态度想一次改一批元素的名称用宏能做到吗一机制解析1.1 宏是命令回放不是程序先说一个容易走偏的认知PML1 宏的本质是把你在 Command Window 里手工敲的那几行命令存成文件之后照原样重放一遍。它没有独立的作用域、没有参数声明、没有返回值它的执行上下文就是你的交互式工作会话——所以当前元素!!ce是谁宏里的命令就作用在谁身上。这也解释了为什么宏特别适合做两件事一是一次性建模/修改手工做完存成宏下次直接复用二是批处理回放把一段确定无疑的操作在另一个元素上重放。官方培训材料给出的最小宏样例原样摘录NEW EQUIP /ABCD NEW BOX XLEN 300 YLEN 400 ZLEN 600 NEW CYL DIA 400 HEI 600 CONN P1 TO P2 OF PREV运行方式是$M/%PDMSUI%\examples\simpleMac.mac或更通用的$m/FILENAME。1.2 宏的三种调用形式形式一$M/路径大写 M。官方培训材料里给出的正是这个形态$M/%PDMSUI%\examples\simpleMac.mac。这里的%PDMSUI%是官方材料原文照录的路径变量用于指向随产品发行的示例目录。形式二$m/文件小写 m。同一份材料给出的通用写法是$m/FILENAME。两种大小写在官方材料里都出现过本系列照录原文不对大小写是否等价做推断——请在你本机的 Command Window 里各试一次把结论写进团队笔记。这类看起来装饰性、实际影响可用性的细节正是二次开发最耗时的地方。形式三做成 PML Add-in 挂到 PowerWheel。这一步不是换个调用方式而是把宏升级成一个可交付的工具。官方 PMLCG 的PML Add-ins章下有这些真实小节Defining a PML Add-in、PML Application Control Object、Create aPLOBJControl File、Create aUICFile、How to Add a PML Add-in to the PowerWheel™官方文本中还出现过一个真实 Addin 名Aveva.Core.PMLPseudoshttps://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG28.17.01.html。注意方向性区别形式一、形式二属于临时用一下形式三才进入交付范畴——它需要.plobj控制文件与 UIC 文件配置成本比写宏本身高得多。1.3 参数就是行尾多写的东西本篇最重要的机制这是从会用宏跨到会用宏做工具的关键一步也是最反直觉的一点宏里没有任何参数声明。参数就是你在调用宏时写在宏文件名后面的那些多余内容它们按出现的先后顺序分别对应宏里的$1、$2、$3……官方培训材料里的参数化版本原样摘录NEW EQUIP /$1 NEW BOX XLEN $2 YLEN $3 ZLEN $4 NEW CYL DIA $3 HEI $4 CONN P1 TO P2 OF PREV调用方式$m/file.mac FRED 300 400 500。把这两行对照着看机制就清楚了调用里FRED是第一个参数 → 宏里$1就变成FRED于是第一行实际执行为NEW EQUIP /FRED。300是第二个参数 →$2400是第三个 →$3500是第四个 →$4。所以第二行实际执行NEW BOX XLEN 300 YLEN 400 ZLEN 500第三行实际执行NEW CYL DIA 400 HEI 500。三个必须记住的推论$n是纯文本替换不是类型化参数。宏不会检查你传的第 3 个参数是不是数字。传错了不会在参数绑定阶段报错而是会变成一条语法怪异的命令在命令执行阶段才炸。参数个数没有校验。你少传一个$4就会替换成空命令变成缺参数的形态多传的则被忽略或者说根本没地方接。所以宏的调用约定必须由文档和命名习惯来保证不靠语言保证。参数顺序就是接口。一旦某个宏被别的脚本或同事调用改参数顺序等于破坏接口。这也是为什么官方建议把可复用的逻辑拆到.pmlfnc函数里——函数有类型化签名官方示例是define function !!area(!len is REAL, !wid is REAL) is REAL宏没有。1.4 变量注入$!与$1完全不是一回事$!与$1长得像但机制不同混淆这两者是新手最常见的逻辑错误$1、$2……来自调用行的文本替换。$!变量把当前会话里 PML 变量的值注入到这一行命令文本里!!变量则注入全局变量。官方培训材料给的注入示例原样摘录!CompType ELBO !dist 5600 NEW $!CompType DIST $!dist执行时$!CompType会被替换成变量里的字符串ELBO$!dist会被替换成5600于是这一行等价于NEW ELBO DIST 5600。为什么这个能力非常重要因为它把命令回放变成了可计算的回放。比如你要在一个循环里按不同尺寸建构件尺寸来自计算而不是写死就必须靠$!注入。这也是 PML1 与 PML2 分工的由来PML1 负责把这行命令拼对PML2 负责把交互界面做出来。社区宏里还能看到把注入用在数组下标上的写法社区来源见 1.5$!b[$!i]即把第!i个元素设为当前。这说明$!注入在位置参数上是通用的不局限于新建设备那类命令。1.5 关于批量宏本身不批量命令才批量一个观念要先摆正宏是循环的载体但批量往往来自命令自身的语义。你在宏里写一行命令它执行一次要执行一批得靠循环DO ... FROM ... TO或靠命令本身作用于一批的能力。社区里真实流传的一段支吊架批量复制与改名宏正是两种手段混用的例子来源AVEVA Community 的 PML and PML2 子板块真实帖属社区来源非官方结论var !supp coll all suppo for CE do !x value !supp $!x !a !!ce.namn new suppo /copy-of-$!a copy prev rename /$!a /copy-of-$!a var !b coll all suppo with matchw(name of suppo,*copy-of-*) for zone do !i from 1 to !b.size() $!b[$!i] !q !!ce.name !c !!ce.name.replace(copy-of-,).split(-) !d !c[1] - !c[2] - $!e q var !q rename all $!q $!d $!f $* destination zone include $!d enddo enddo这段代码值得现在就看一眼因为它是PML1 命令语法 集合遍历 变量注入三件事同时出现的真实样本。但不要在 03 篇就去仿写它——集合遍历coll all ... for CE、DO ... VALUE、matchw通配、size()与下标访问是后面数据访问主题的内容现在只需要认出三件事rename all $!q $!d这是社区来源的批量改名写法两个参数分别是旧名与新名本篇的扩展宏会用到它并一律标注为社区来源、需本机验证。$!x单独占一行把集合里取出的元素设为当前这是切当前元素的手段。new suppo ... copy prev rename /$!a /copy-of-$!anew命令链里可以带copy prev与rename。注意这里rename是NEW命令链中的一段与独立的RENAME ALL不是同一种用法——这正是看起来一样的词语义完全不同的典型陷阱。另外一条官方态度必须提前知道PMLCG 的 Commands 章明确写命令可以实现为PML command object或core command object通过.uic文件把工具与命令对象关联官方不建议从标签页按钮直接调用 PML 宏因为这与 command ribbon 不兼容https://help.aveva.com/AVEVA_Everything3D/3.1/PMLPUG/PMLCG24.27.01.html。所以宏研发与临时作业命令对象交付入口。二完整代码与逐行剖析2.1 SimpleMac 原样复刻官方培训材料-- 文件simpleMac.mac -- 来源官方培训材料PML Macros Functions原样复刻 -- 警告会创建元素务必在测试 MDB 上运行 NEW EQUIP /ABCD NEW BOX XLEN 300 YLEN 400 ZLEN 600 NEW CYL DIA 400 HEI 600 CONN P1 TO P2 OF PREV逐行剖析NEW EQUIP /ABCD新建名为ABCD的设备。/前缀是给出元素名的写法。执行这一行之后当前元素就变成了刚建的设备——后面几行都挂在它下面靠的就是这个副作用宏里没有显式的层级切换语句。NEW BOX XLEN 300 YLEN 400 ZLEN 600在当前元素下建长方体三边长 300 / 400 / 600。NEW CYL DIA 400 HEI 600在当前元素下建圆柱直径 400、高 600。CONN P1 TO P2 OF PREV按官方材料原样把P1连到PREV上一个元素的P2。这一行的教学价值在于展示PREV这类相对定位词——命令流里不写绝对路径而是用上一个来指代宏里非常常见。注意这一行没有做当前元素回退。四行跑完后当前元素是最后创建的那个构件不是ABCD。写更长的宏时这是跑第二遍结果不一样的常见根因。2.2 参数化版本官方培训材料-- 文件paramMac.mac -- 来源官方培训材料原样复刻 -- 调用$m/paramMac.mac FRED 300 400 500 -- 注意宏内无任何参数声明$1..$4 由调用行尾的文本按位置替换而来 NEW EQUIP /$1 NEW BOX XLEN $2 YLEN $3 ZLEN $4 NEW CYL DIA $3 HEI $4 CONN P1 TO P2 OF PREV逐行剖析第 1 行NEW EQUIP /$1调用时$1FRED实际执行NEW EQUIP /FRED。引号是调用侧的分词手段不是值的一部分。第 2 行NEW BOX XLEN $2 YLEN $3 ZLEN $4实际执行NEW BOX XLEN 300 YLEN 400 ZLEN 500。第 3 行NEW CYL DIA $3 HEI $4实际执行NEW CYL DIA 400 HEI 500。注意这里$3被用了两次第 2 行当 YLEN、这里当 DIA这是有意的同一个宽度参数复用到两个命令上说明$n替换没有用了就消耗掉的语义可以重复引用。第 4 行与 SimpleMac 相同。接口约定这个宏的隐含契约是第一个参数是元素名第二、三、四个是三个尺寸。因为语言不校验所以你必须把这条契约写在文件头注释里——本系列一律要求这么做。2.3 变量注入示例官方培训材料-- 文件injectDemo.mac -- 来源官方培训材料原样复刻三行 -- 说明从 AVEVA Community 的真实帖社区来源中可确认$! 注入也可用于位置参数 -- 例如 $!b[$!i] 这类把第 i 个元素设为当前的写法本篇不在此展开集合机制。 !CompType ELBO !dist 5600 NEW $!CompType DIST $!dist逐行剖析!CompType ELBO定义局部变量值为字符串ELBO。!dist 5600定义局部变量值为实数 5600。NEW $!CompType DIST $!dist这是本篇最需要记住的一行。$!CompType注入后变成ELBO$!dist注入后变成5600整行等价于NEW ELBO DIST 5600。反直觉点$!是行级文本替换发生在命令被解析之前。这意味着如果变量里含有空格或引号注入后会改变命令的分词。写模板宏时一定要先把变量清洗干净字符串清洗方法在下一篇展开。与$1的区别再强调一次$1来自调用行$!x来自会话里的变量。两者可以同时出现在同一行里替换顺序是先文本参数、再变量值——但这个顺序在本篇依据的材料中没有明确说明请在 Command Window 里用一个最小样例自行验证后再依赖它。2.4 扩展宏参数化批量改名社区来源 本系列改造这个宏的目标是把一批元素按同一规则改名。它用到的关键写法RENAME ALL 旧名 新名出自 AVEVA Community 的真实帖社区来源本系列只做了参数化改造。-- 文件batchRename.mac -- 来源RENAME ALL 的写法出自 AVEVA Community 的 PML 帖社区来源非官方结论 -- 本宏在其基础上做参数化改造未在本机验证属按已知写法构造。 -- 调用$m/batchRename.mac /OLD-NAME /NEW-NAME -- 契约$1 要改的旧名$2 新名均需带 / 前缀 -- 前置先只选中目标区域/层级避免误伤执行前确认可回退备份或测试 MDB -- 强烈建议先跑 rename 预检见练习 3确认命中范围后再执行本宏 P batchRename: begin P target old name $1 P target new name $2 -- 批量改名一次作用于匹配到的全部元素 rename all $1 $2 P batchRename: done, please verify in the model 逐行剖析P ...输出提示到 Command Window官方控制逻辑示例中即用P做输出例如P CE is Branch.。这一行的作用是留下审计痕迹批量改名最容易出的事故是改了但没人知道改了什么所以执行前后各打一条带参数的提示。P target old name $1把参数回显出来。虽然是多余的但对批量作业来说非常关键——它让你在日志里直接看到这次到底传了什么。rename all $1 $2核心一行。$1、$2是调用行尾的两个参数。ALL的存在意味着它作用于匹配到的全部所以这个宏的语义是批量而不是单个。三条使用纪律必须遵守否则这个宏迟早造成生产事故先确认范围再改名。RENAME ALL的作用范围与当前所在层级、以及是否配合include有关本系列后续篇章会专门讲RENAME ALL与INCLUDE的配合本篇不给出未经核实的范围规则。先检查命名冲突。新名如果与既有元素重名结果取决于实现细节不要赌。写库前必须可回退。DABACON 的写操作不可逆——在测试 MDB 上验证过、或先做备份是这个宏的前置条件不是建议。为什么不写成循环改名因为本篇尚未引入集合遍历机制。循环版的批量改名需要coll all ... for ...与DO ... VALUE那属于数据访问主题在机制没讲清之前给出看起来能跑的循环代码是本系列明确要避免的做法。三常见报错与排查症状一宏执行到某一行突然报命令语法错误但那一行看起来和手册一模一样。现象参数化宏报错报错文本里出现了奇怪的片段。原因参数没传到 / 传少了 / 传多了导致$n替换结果异常。因为宏不校验参数个数错误的参数会以缺参数或多余参数的命令的形式暴露出来。处置在宏的第一段加上P ...回显所有参数如 2.4 所示一眼就能看出替换结果同时把回调用的调用行完整抄进日志。症状二宏第一次跑正常第二次跑报名称已存在。现象NEW EQUIP /ABCD第二次执行失败。原因宏不检查名称是否存在第一次已经建了ABCD。处置把宏改成参数化用$1传名字或在宏里显式使用复制/重命名类命令构造唯一名社区宏里用copy-of-原名作为中间名的做法就是这个思路属社区来源。症状三想点个按钮直接跑宏结果按钮没反应或者报与 ribbon 相关的错。现象把宏挂到标签页按钮上行为异常。原因官方明确不建议从标签页按钮直接调用 PML 宏旧式事件/工具栏方式仍受支持但不推荐且与 command ribbon 不兼容。处置改成官方推荐路径——把功能实现为command objectPML command object 或 core command object用.uic文件把工具与命令对象关联交付级方案是 .NET Addin Command UIC。症状四$M/...能跑$m/...报找不到文件。现象大小写不同行为不同。原因本篇依据的材料中同时出现了$M/...与$m/FILENAME两种写法但没有说明大小写规则。任何关于大小写等价的说法都缺乏依据。处置在本机各试一次并记录结论路径中含变量的写法如%PDMSUI%要确认该变量在你的环境里是否有效——它是官方材料原文里的路径变量不一定在所有环境都可用。四动手练习练习 115 分钟在测试 MDB 上跑 2.1 的 SimpleMac。合格判定ABCD下出现 1 个长方体 1 个圆柱跑完后用 Command Window 查询!!ce的name与type确认当前元素是最后一个创建的构件而不是ABCD。练习 220 分钟把 SimpleMac 改成参数化版本2.2并用$m/paramMac.mac FRED 300 400 500调用。合格判定元素名为FRED长方体的三边为 300/400/500圆柱直径为 400、高为 500——四项数值全部对得上才算通过。练习 315 分钟写一个预检宏只回显参数与当前元素信息不做任何写操作。合格判定宏不产生任何模型改动执行前后元素数量不变但 Command Window 里能看到$1、$2与当前元素的name、type。这是 2.4 那个批量改名宏的强制前置步骤。练习 420 分钟在测试 MDB 上先用简单元素做一轮 2.4 的批量改名试验。合格判定能说清这次RENAME ALL的实际作用范围改了哪些、没改哪些并把结论写成两行笔记同时记录一次故意制造命名冲突时的报错原文。五小结与下一篇预告本篇钉死三件事宏是命令回放作用范围由当前元素决定宏没有参数声明$1、$2… 就是调用行尾多写的东西纯文本替换、无类型、无个数校验$!变量注入与$1参数是两套机制前者把会话里的值拼进命令行后者把调用行的文本拼进命令行。另外记住官方态度宏用于研发与临时作业交付入口应该做成 command object .uic。下一篇《PML 基础语法与错误处理》会补齐写宏之外的编程能力局部变量!var与全局变量!!var的命名限制≤16 字符、不以数字开头、不含.、define function与.pmlfnc、IF/ELSEIF/ENDIF与DO … FROM … TO … BY、字符串方法链以及PML 中最容易被忽视的机制——错误不会立即报错报不报取决于下一行输入。文末 FAQQ1PML 宏和 PML 函数到底有什么区别我该先写哪个宏是命令文本的回放执行上下文是当前交互会话作用对象是当前元素!!ce没有参数声明、没有类型化的返回值。函数写在.pmlfnc文件里define function定义有类型化签名例如官方示例define function !!area(!len is REAL, !wid is REAL) is REAL可以被反复调用并返回结果。选择标准很简单一次性的操作、需要照原样重放手工步骤 → 写宏需要被反复调用、需要参数校验与返回值 → 写函数。两者可以配合宏负责拼装与触发函数负责计算与判断。Q2$M/路径和$m/文件是两套语法吗大小写有讲究吗不是两套语法而是同一个调用形式在官方培训材料里出现的两种大小写拼写材料里既有$M/%PDMSUI%\examples\simpleMac.mac也有通用的$m/FILENAME。官方材料只给出了这两种写法并未说明大小写规则因此本系列不做推断。建议你在本机分别试一次并把结论写进团队笔记同时对%PDMSUI%这类路径变量要确认它们在你环境里是否有效。Q3宏怎么接收参数为什么我在官方示例里找不到任何参数声明或param关键字因为宏根本没有参数声明机制——参数就是你调用宏时写在文件名后面的多余内容按出现顺序对应宏里的$1、$2、$3……。官方示例中的参数化写法是NEW EQUIP /$1、NEW BOX XLEN $2 YLEN $3 ZLEN $4调用方式是$m/file.mac FRED 300 400 500。由此带来三个后果$n是纯文本替换、不做类型检查参数个数不做校验参数顺序构成了事实上的接口改动顺序等于破坏接口。所以固定下来的宏务必在文件头注释里写清参数契约。Q4我看见NEW $!CompType DIST $!dist这样的写法$!是什么和$1有什么区别$!是变量值注入把当前会话里 PML 局部变量的值拼进这一行命令文本$1是调用行参数替换把调用宏时写在文件名后面的第 1 个文本片段拼进来。$!里也可以写全局变量$!!x。两者机制不同但都是行级文本替换所以变量值里如果含有空格或引号会改变命令的分词结果——模板宏里必须先做字符串清洗。另外社区来源的真实帖中还能看到把注入用于位置参数的写法$!b[$!i]把第!i个元素设为当前属于社区经验。Q5宏能不能挂到界面上点一下就跑官方对这个做法是什么态度能挂但官方明确不建议从标签页按钮直接调用 PML 宏因为这与 command ribbon 不兼容旧式事件/工具栏方式仍受支持但不推荐。官方推荐的做法是把功能实现为command objectPML command object 或 core command object再用.uic文件把界面上的工具与命令对象关联起来。若要把宏做成可复用工具官方另有一条路径PML Add-in——PMLCG 的 PML Add-ins 章包含Defining a PML Add-in、PML Application Control Object、Create a PLOBJ Control File、Create a UIC File、How to Add a PML Add-in to the PowerWheel™等小节。Q6想一次改一批元素的名称用宏能做到吗可以但批量来自命令本身的语义而不是宏。社区来源的真实帖中使用的写法是rename all 旧名 新名一个旧名、一个新名一次作用于匹配到的全部元素本系列在此基础上给出了参数化版本rename all $1 $2。使用它必须遵守三条纪律先确认作用范围RENAME ALL的实际命中范围与当前层级、以及是否配合include有关请在本机用最小样例实测后再依赖、先检查命名冲突、写库前确保可回退DABACON 写操作不可逆。若要做循环改名需要集合遍历机制coll all ... for ...、DO ... VALUE那属于数据访问主题本篇有意不给出未经核实的循环代码。