PDMS-AVEVA-E3D二次开发教程（03）：第一个 PML 程序——命令行、宏与函数的三层递进

PDMS-AVEVA-E3D二次开发教程03第一个 PML 程序——命令行、宏与函数的三层递进版本与事实声明本篇出现的 PML 语法元素!局部变量、!!全局变量、文本定界符、define function … endfunction、do … values … enddo、handle any … endhandle、write()、!!alert均取自 help.aveva.com 官方在线手册与官方 IFC 导出帮助文档中的真实示例。文件后缀字面量以官方 “Filename Extensions” 一节为准。为便于叙述本篇把宏文件写作.mac、函数文件写作.pmlf、表单文件写作.pmlfrm——这是工程现场的通行写法请在落盘前用你所用产品版本的官方后缀清单核对。各控制结构的收尾关键字enddo/endhandle/endfunction已在官方示例中出现endif等同族关键字以官方 Control Logic 一章为准。示例中的路径、位号、数值均为示例性数据不代表任何标准规定。一句话结论PML 的代码形态有三层——命令窗口里的一行命令一次性、宏可重复但对参数与复用不友好、函数define function !!名字( !参数 is 类型 ) is 返回类型可反复调用的最小复用单元判断标准只有一条这段逻辑会被调用第二次吗会就写成函数。〇、认知问题Q1命令窗口除了敲命令官方给了它什么额外能力为什么这件事直接决定了能不能做自动化Q2!x与!!x到底差在哪为什么选错了变量前缀会让脚本时灵时不灵Q3PML 的文本定界符为什么不是双引号这让写代码时少踩哪一类坑Q4宏和函数的差别不只是能不能传参吗那真正的分界线是什么Q5写好文件之后为什么还要执行一次索引重建才算装上了一、机制解析1.1 命令窗口官方为自动化留的第一道门官方命令窗口Command Window文档里有一段话是后续所有自动化的起点粘贴选项会把粘贴文本的每一行作为独立命令执行“the paste option executes each line of the copied text as a separate command as if they had been typed into the Command Window”并且官方明确建议对重复性的过程应创建宏来自动化“Create macros to automate repetitive procedures”。把这句话拆开看得到两条实用结论交互式验证的最快路径你不必先建文件、再调试、再部署——任何一行命令都可以立即在命令窗口验证验证通过后再落盘成文件。这是本篇三层递进的第一层。粘贴执行的边界既然每一行都是独立命令那么粘贴内容里混进说明性文字就会在那一行断掉。所以命令窗口适合验证不适合当交付形态。1.2 变量作用域!与!!的区别比你想的更重要官方手册把 “Local and Global Variable Names” 单列一节说明这是语言设计里被认真对待的一环。前缀名称生存范围典型用法!局部变量当前运行上下文循环计数、临时字符串、中间结果!!全局变量会话级跨宏/函数可见当前元素!!CE、表单对象如!!EntryForm、会话配置为什么这对你重要全局变量是跨调用传递状态的唯一手段也是最容易被误用成绕过参数传递的捷径。工程上的判据是如果一个值只在这次执行内有效 → 用!如果一个值代表会话当前状态当前元素、当前表单、当前项目配置→ 用!!如果只是为了把参数从 A 传到 B →用函数参数不要用全局变量。用全局变量传参的代码在批处理并发或连续调用多个函数时会互相污染且极难调试。官方还明确了 PML 的!this概念——在对象方法内部!this指向被调用的对象自身官方示例define object MAN member .Age is REAL endobject搭配define method .Man()中使用!this.GlobalName。也就是说PML 的面向对象能力是把状态绑定在对象上而不是散落在全局变量里——这才是管理复杂状态的正道第 08 篇展开。1.3 文本定界符为什么不是双引号PML 使用竖线对作为文本定界符官方 IFC 导出示例里到处可见!exporter.setVersion(|IFC2x3|)、return |Success|、write( |UUIDENTIFIER SET| )。这个设计与 E3D 的使用场景强相关工厂设计里到处是带特殊字符的字符串——位号里有#、、/、管道等级里有-描述字段里常有中文和括号。如果用双引号作定界符这些字符会频繁触发转义问题。竖线对把这类摩擦几乎降为零代价是字符串里若真要包含竖线需要另行处理规则以官方 “Text Delimiters” 一节为准。经验法则写 PML 时把文本一律用竖线对当默认动作。只有当字符串内容需要包含竖线本身时才去查官方的定界符规则而不是凭直觉套用别的语言的习惯。1.4 注释、大小写与$三个必须一次记住的语言特性特性官方章节事实工程影响注释Comments in PML Files官方示例中大量使用--作为行内注释起始如-- Create exporter object注释是团队代码评审的刚需不要省大小写无关Case IndependenceMyFunc与myfunc是同一个标识符同名冲突仅大小写不同会导致改了不生效第 02 篇的普查脚本专门检测它特殊字符$Special Character $$在 PML 中有特殊语义官方单列一节遇到$不要当成普通字符先查官方章节最佳实践在团队里强制一种命名风格例如函数名全小写下划线分隔、对象成员首字母大写把大小写无关这条语言特性带来的风险从靠运气变成靠规范。1.5 宏与函数真正的分界线官方面向宏专门设了四节Macros、Naming and Running Macros、Macros with Arguments、Using Macros and Functions Together。这说明两件事宏可以带参数不是不能传参而且官方本身就鼓励宏与函数混用。那么真正的分界线是什么答案是调用契约的清晰度维度宏函数定义方式一段命令序列官方 “Macros” 一节define function !!名字( !参数 is 类型 ) is 返回类型 … endfunction官方 IFC 示例参数有官方 “Macros with Arguments” 一节有且带类型声明返回值无返回值契约有明确返回类型如is STRING能否被别的代码当零件用弱大多是跑完就完了强可嵌套调用、可做错误返回适合一次性/线性流程、临时排查团队函数库、被反复调用、需要错误处理的逻辑判据四条按顺序问这段逻辑会被调用第二次吗→ 会函数。它需要把结果交给调用者判断吗→ 需要函数因为函数有返回类型。它需要调用者传入多个参数并校验参数吗→ 需要函数宏的参数能力在复杂场景下不够用。以上都是否且代码是一次性的现场动作→ 宏。函数定义的完整形态在官方 IFC 导出帮助文档里有一个可直接参照的真实示例define function !!IFCPreProcessing( !exporter is IFCEXPORTEROBJ ) is STRING -- Start !start !!ce -- loop through all elements to export !items !!ifcExportForm.exporter.getExportItems() handle any !!ce !start return |Failure| endhandle do !item values !items !name name !message |Unset GUID on | !name write( !message ) enddo -- Finished !!ce !start return |Success| endfunction这段官方代码信息量极大本篇先只用它说明函数的骨架define function开头 → 参数声明 → 返回类型 → 逻辑体 →return返回值 →endfunction收尾其中还藏了两个后续篇章的重点handle any … endhandle容错见第 04 篇!!ce的保存与还原见第 05 篇。1.6 落盘之后装不上就是没写写好文件不等于能用。第 02 篇讲过两个前置条件——文件在 PMLLIB 搜索路径内、索引已刷新。官方 IFC 帮助文档的原话是 “A PML REHASH ALL command might be necessary to refresh the PML index files.”铁律 3 的落地形式写 PML 的动作循环固定为四步——保存文件 → 索引重建 → 调用验证 → 记录结果。漏掉第二步你会在改了没生效和代码写错了之间浪费大量时间。二、完整代码与逐行剖析任务统计当前选中范围内的管道分支数量并输出一行汇总。我们把它写三遍。第一层命令窗口里的一行一次性验证!b 0 !!ce 在模型中选择一个元素或输入一个已知元素的路径 -- 以下为示意真实遍历语法见第 05 篇 !b !b 1 write( |branch count (demo) | !b.String() )逐行剖析!b 0创建一个局部变量。PML 的变量不需要声明类型——官方数组章节的例子里!NewArray[1] !NewValue会自动创建数组变量 “if it does not already exist”变量的存在性由赋值动作本身建立。第 2 行是占位提示而不是可以直接照抄的命令设置当前元素的方式与元素命名规则属于数据库机制第 05 篇才讲。这里先让你看到命令窗口可以直接改会话状态这件事。write( |...| )输出到命令窗口官方示例中出现过的写法。 !b.String()是文本连接运算符官方 “Concatenation” 一节数值要参与文本连接需要显式转换.String()是对象方法式转换官方 PML 2 方法风格形如!myString.Boolean()。这一层的价值三分钟内验证一个想法。但不要把它当交付形态——命令历史不可版本管理换台机器就没了。第二层带参数的宏可重复的线性流程-- 文件count_demo.mac后缀以官方 Filename Extensions 为准 -- 用途接收一个起始数值累加一个步长输出结果 -- 说明宏适合线性、一次性的流程结果通过全局变量交给调用者 !argstart !1 !argstep !2 !!demo_result !argstart !i 0 do !i from 1 to 5 !!demo_result !!demo_result !argstep enddo write( |demo result | !!demo_result.String() )逐行剖析!1/!2宏的位置参数写法官方 “Macros with Arguments” 一节专门讲宏的参数。注意这是宏的参数机制不是函数的类型化参数因此它无法声明这个参数必须是数值传错了也不会在入口就被拦住。!!demo_result结果放全局变量。这是宏的通用妥协做法——宏没有返回类型想把结果交给调用者就只剩全局变量这条路。而这正是 1.2 节说的用全局变量传参的坏味道调用方必须知道这个全局名字稍有并发或嵌套调用就互相污染。do !i from 1 to 5 … enddoPML 的DO循环官方 “DO Loops”、“DO INDEX and DO VALUES” 两节。enddo收尾。write( … )宏的执行结果只能打印出来给人看不能返回给程序判断。这一层的价值适合每天早上跑一遍、结果看一眼的线性动作。它的天花板也很清楚不可组合。第三层带签名的函数可复用的最小单元-- 文件count_demo.pmlf后缀以官方 Filename Extensions 为准 -- 用途计算等差数列前 n 项和返回结构化结果文本 -- 设计要点参数带类型声明返回值带类型错误路径也 return不用全局变量传结果 define function !!DemoSum( !start is REAL, !step is REAL, !count is INTEGER ) is STRING -- 参数校验函数的第一道防线 if ( !count 0 ) then return |Failure: count must be positive| endif !total !start !i 0 do !i from 1 to ( !count - 1 ) !total !total !step enddo -- 组装返回值类型化、可直接被调用者判断 return |Success: total | !total.String() endfunction逐行剖析签名define function !!DemoSum( !start is REAL, !step is REAL, !count is INTEGER ) is STRING这是官方 IFC 示例中函数签名的同构写法define function !!IFCPreProcessing( !exporter is IFCEXPORTEROBJ ) is STRING。三个要点① 函数名是全局标识符用!!前缀② 参数逐个声明类型③is STRING声明返回类型。参数校验放在第一段函数一旦被团队复用就一定会有人传错参数。在入口处用return一个明确的失败文本比让错误往下游扩散最后变成一条看不懂的运行时报错要好得多。do !i from 1 to ( !count - 1 )注意to的上界用的是表达式而不是常量这是 PML 的表达能力官方 “Format of Expressions”、“Operator Precedence” 两节定义了表达式规则。return |Success: total | !total.String()返回值是一个带前缀的文本调用者可以用文本判断成功与否。这是没有异常机制时把判断权交回调用者的通用做法更完整的错误处理handle any … endhandle在第 04 篇。endif收尾同族收尾关键字以官方 Control Logic 一章为准enddo、endhandle、endfunction已在官方示例中出现。没有使用任何!!变量这是函数与原宏版本最关键的区别——函数不污染会话状态。调用它两次两次互不影响。调用与部署命令窗口-- 1) 确认搜索路径取真实值 Q EVAR |PMLLIB| -- 2) 索引重建让新产品刚放进路径的文件被识别 PML REHASH ALL -- 3) 调用函数看返回文本 !r !!DemoSum( 1, 2, 5 ) write( !r )逐行剖析三步顺序不可颠倒。先 REHASH 再调用是固定动作。!r !!DemoSum( 1, 2, 5 )把返回值接进局部变量。如果直接改写成write( !!DemoSum(1,2,5) )会得到同样的屏幕输出但你丢掉了判断能力——在高阶用法里你会希望根据返回值决定下一步这是第 09 篇批处理容错的基础。函数返回的是|Success: …|或|Failure: …|调用者可以据此分支。这就是 1.5 节那条它需要把结果交给调用者判断吗判据的物理形态。三层对照总表维度命令行宏函数交付形态命令历史宏文件函数文件参数无靠全局变量位置参数类型化参数返回值无无靠全局变量有类型化返回值可复用性一次性可重复运行可被代码调用可组合会话污染高高无适合场景验证想法例行线性流程团队函数库三、常见报错与排查报错 3-1命令窗口里粘贴多行代码只跑了第一行。现象后续行未执行。根因官方文档明确——粘贴执行的语义是每一行作为独立命令因此非命令行说明文字、未注释的标题、空行中的伪代码会在那一行中断执行。解法把代码存成文件用宏/函数机制运行临时粘贴时保证每行都是合法命令说明文字要么删掉、要么用--注释。报错 3-2调用函数时提示找到同名但参数不符或直接报语法错。现象函数存在却调不通。根因按概率排序①实际生效的是另一个同名文件PML 大小写无关两个目录下的同名文件谁生效取决于搜索顺序② 参数个数或类型与签名不匹配函数签名做了类型声明传错类型不会被静默接受③ 索引未刷新调用到的还是旧版本。解法先PML REHASH ALL再用第 02 篇代码 2-1 的冲突告警输出核对同名文件最后核对调用处的实参个数与类型。报错 3-3宏跑完了但结果没传出来。现象调用方拿不到!!demo_result。根因宏的结果依赖全局变量而全局变量的可见性受运行上下文影响如果宏在某个作用域内执行、或后续执行了清理动作全局值可能不是你以为的那个。解法把宏改写成函数用返回值传递——这是本篇最想让你记住的一条改造动作。若确实必须用全局变量请把谁写、谁读、何时清理写进代码注释。报错 3-4改了函数文件调用结果没有变化。现象典型的改了没生效。根因索引未刷新官方 IFC 文档可能需要PML REHASH ALL刷新索引文件。解法索引重建后重试若仍无效检查 PMLLIB 是否包含该文件所在目录第 02 篇以及是不是存在同名文件排在前面。四、动手练习练习 1三层同题把计算等差数列前 n 项和这个任务按本篇的三层各写一遍并存成三个独立文件。判定标准三层版本对同一组输入如起点 1、步长 2、项数 5都能输出同一个数值函数版不含任何!!变量函数版对count 0返回以|Failure开头的文本而不是崩溃或输出错误结果。练习 2作用域实验写两个函数一个用!局部变量做累加器一个改用!!全局变量做累加器连续调用同一个函数三次观察输出。判定标准能写出明确结论——“局部变量版每次结果独立全局变量版结果被上一次调用污染或未污染取决于清理动作”并说明为什么这是设计缺陷而不是特性。练习 3部署闭环把你的函数文件放进 PMLLIB 路径内的一个目录完成保存 → 索引重建 → 调用 → 记录四步并在练习笔记里记录每一步的实际命令与输出。判定标准调用成功且返回值符合预期笔记中包含Q EVAR |PMLLIB|与索引重建两条命令的实际输出。练习 4重构找一个你现有的或网上找的宏判断它是否满足 1.5 节的四条判据若满足则改造成函数。判定标准改造后的函数有类型化参数与返回值原宏里的全局变量全部消失函数的返回文本能被调用方区分成功与失败两种情形。五、小结与下一篇预告PML 的代码形态是三层递进的命令行验证想法、宏承载线性例行流程、函数承载可复用的逻辑。!是局部、!!是会话级全局用全局变量传参是坏味道。文本用竖线对定界是因为工厂数据里特殊字符太多。大小写无关是语言特性也是同名冲突的根源。最后一条纪律保存 → 索引重建 → 调用 → 记录四步缺一不可。下一篇《PML 语言核心表达式、控制流、稀疏数组与容错》把本篇用到的语法补全成一套可用的语言子集——表达式的类型与单位、DO的四种变体与break/skip、PML 数组自动创建、可稀疏、无负下标、下标 0 有坑的真实行为、文件对象日志以及用handle any … endhandle把脚本崩了变成脚本报告失败。本篇认知问题回显FAQQ1命令窗口除了敲命令还有什么官方能力A官方命令窗口文档说明其粘贴选项会把粘贴文本的每一行作为独立命令执行效果等同于逐行敲入官方同时建议对重复性过程创建宏来自动化。因此命令窗口的定位是交互式验证不是交付形态——它也是二次开发里成本最低的实验场但代码必须落盘成宏或函数才能被版本管理和团队共享。Q2PML 里!x与!!x有什么区别选错会怎样A!是局部变量!!是会话级全局变量官方 “Local and Global Variable Names” 一节。全局变量适合承载会话状态如当前元素!!CE、表单对象不适合用来传递函数间的参数用全局变量传参会在连续调用或嵌套调用中互相污染且难以调试。判据是这个值是否代表会话当前状态而不是图省事。Q3PML 为什么用竖线对做文本定界符A官方 IFC 导出示例中文本一律写成|IFC2x3|、|Success|这类竖线对形式。这样设计避免了工厂数据里常见的特殊字符位号中的符号、等级中的连字符、描述中的中文与括号触发转义问题代价是字符串内容若需包含竖线本身要另按官方 “Text Delimiters” 一节的规则处理。Q4宏和函数的分界线到底是什么A不是能不能传参因为官方专门有 “Macros with Arguments” 一节宏是可以带参数的。真正的分界线是调用契约函数用define function !!名字( !参数 is 类型 ) is 返回类型 … endfunction声明类型化参数与返回类型可被别的代码当零件组合并据返回值分支宏没有返回类型结果只能靠全局变量或屏幕输出因此不可组合。判据是这段逻辑会不会被调用第二次。Q5写好文件之后为什么还要索引重建A产品为敲名字即可调用维护 PML 文件索引新增或修改文件后必须刷新索引才能被识别官方 IFC 帮助文档原文指出需要时可用 “PML REHASH ALL” 命令刷新 PML 索引文件官方手册另有 “Rebuilding All PML File Indexes” 一节。因此 PML 的标准动作循环是保存文件、索引重建、调用验证、记录结果四步漏掉索引重建就会出现改了没生效的假故障。