版本声明：本篇基线为AVEVA E3D Design 3.1（文档版本线存在 1.1 / 2.1 / 3.1，教程统一以 3.1 为准）；前代产品AVEVA PDMS 自 2024 年 4 月 1 日起不再销售、不再提供支持。文中出现的 PML 命令名、属性名、对象类型名与文档 URL，均可在官方帮助站
help.aveva.com的 PML 定制手册（PMLCG）、软件定制对象参考（SCRM）与官方社区真实帖中查到出处。凡标注"按官方 PML 语法构造"的代码，均需在本地 E3D Design 环境验证后再用于生产。
一句话结论
模型巡检与批量改写的难点不在"遍历"，而在只读与写入必须分成两个脚本、写入前必须把命中集合钉死、改名后必须重新纳入——把这三件事做成流水线，批量改写才可回退。
〇、认知问题（读完本篇你应该能回答）
- 为什么"巡检"和"批量改写"不能写在同一个脚本里？
!!CE在遍历里到底扮演什么角色？为什么循环体第一行往往是$!xxx[$!i]？VAR … COLL ALL … FOR CE与… WITH MATCHW(name of …, '…')分别在筛选什么？RENAME ALL之后为什么必须紧跟INCLUDE？不跟会发生什么？- 批量改名最容易踩的坑是"命名冲突"，它从哪来、怎么提前挡住？
- PML 的错误处理机制为什么不支持"立刻抛异常"的写法？
一、机制解析
1.1 巡检与改写必须是两个脚本
工程上最常见的翻车方式是"边遍历边改库"：循环走到第 37 个元素时改错了，前面的 36 个已经落库，DABACON 的写操作不可逆，你连"改之前长什么样"都说不清。
正确的组织方式是三段式：
- 只读巡检：只建集合、只读属性、只输出，不写任何东西。产物是一份"变更前后对照表"里的"前"。
- 预检：把巡检结果按业务规则筛一遍，检查是否存在目标名冲突、命名不符合企业规范、层级归属异常。
- 写入：只对预检通过的项执行
RENAME ALL/ 属性写回，并把每一项的旧值记录下来，形成"可回退清单"。
本篇的两段代码就是这个结构：08-01-audit.mac属于第 1 段，08-02-rename.mac属于第 3 段，第 2 段由第 1 段的输出在外部（Excel 或脚本）完成。
1.2!!CE是遍历的"游标"
官方口径下，!!CE是一个跟踪当前元素的全局DBREF：你在界面上点选一个元素，!!CE就指向它；PML 命令作用于"当前元素"时，作用的也是它。
这一点决定了遍历的写法：集合本身不改变!!CE，只有把集合元素"执行"一次才会移动游标。所以在DO … VALUE循环里，第一行永远是形如$!x或$!brans[$!i]的语句——它的作用是把集合的当前项变成!!CE，之后!!ce.name、!!ce.type、!!ce.flnn这些属性读取才有意义。少了这一行，你会在循环里反复读同一个元素，输出一列完全相同的值，这是巡检脚本最经典的静默错误。
1.3 集合、DO … VALUE与索引访问
PML 里有两类"集合"实现，官方在社区回复中给出过它们的文档坐标：PML1 风格的数组式VAR … COLLECT，与 PML2 的集合对象。官方同时强调：PML 中的 collection 与界面上的 “My Collections” 不是一回事——后者实为 GPWL / GPSET / GPITEMS 体系（可用GADD PIPE /name之类的方式添加）。写脚本时不要指望这两者互操作。
两种遍历姿势：
do !x value !coll … enddo：直接把集合项逐个执行，写法最短，适合"遍历即处理"。社区真实宏用的就是这种。do !i from 1 to !coll.size() by 1 … $!coll[$!i] … enddo：显式拿索引，适合需要序号、需要跳步、需要BREAK/SKIP的场景。
size()是集合的成员方法，返回条目数。巡检脚本第一件事就是打印size()：如果它是 0，说明你的!!CE层级选错了（比如把 CE 设在了 ZONE 而不是 ZONE 下的 PIPE），后面所有循环都会静默地什么都不做。
1.4MATCHW：把"上一轮的产物"筛出来
MATCHW是按通配模式匹配属性值的筛选器，写法是MATCHW(name of <类型>, '<模式>')，模式里用*做通配。社区真实宏里出现过两种用法：
var !b coll all suppo with matchw(name of suppo,'*copy-of-*') for zone这一句的含义是：在当前 zone 范围内，把所有名称里含有copy-of-的支吊架挑出来——也就是"上一轮复制动作产生的那批新元素"。
在批量改写的语境下，MATCHW的价值在于把命中集从"人脑记忆"变成"数据库查询"。你不需要记住改了哪几个，只需要让命名规则本身可被模式匹配：想改的元素统一带_OLD后缀，那么MATCHW(name of BRAN,'*_OLD')就是你的靶子。
1.5RENAME ALL与INCLUDE：改名必须成对出现
RENAME ALL <旧名> <新名>是把当前作用范围内的元素改名。社区宏中的真实写法是：
rename all $!q $!d注意这里用了$!变量的形式——把 PML 变量的值直接注入命令串，这是 PML1 命令语法与 PML2 变量体系之间的"接缝"，也是为什么 PML 宏能干那么多事的原因。
改名的关键坑在于：名称是元素的身份标识之一，改名之后，之前用来定位它的查询串就失效了。所以社区宏在rename all之后紧跟一句：
include $!dINCLUDE把改名后的元素重新纳入当前的选择集合，后续命令才能继续对它生效。如果你改完名就继续用旧名的查询串去取元素，会得到"取不到"或"取到一个空集合"的结果——而 PML 在很多情况下不会报错，只会安静地什么都不做。
1.6 命名冲突：批量改名的头号杀手
改名的本质是替换名称串。如果新名与同层级已有元素重名，DABACON 层的唯一性约束会让这条改名失败。批量改名时最容易出现两种冲突：
- 规则性冲突：
前缀 + 旧名的规则本身就会撞——比如旧名BRAN-1001与新名BRAN-1001-OLD在同一个 owner 下若已存在，就会撞。 - 批量内自撞：如果过滤规则过宽（例如把已经改过名的元素又选进来了），第二轮改名会把这批元素改成"带两层后缀"的怪名字。
挡住冲突的办法只有一条：先跑只读巡检，把"目标名列表"整列拉出来，在外部做一次重复检测。本篇的巡检脚本因此专门输出"当前名"和"拟改名"两列（见 2.1 的!row拼接），这件事必须在写库之前做完，而不是写在写库脚本的异常处理里。
二、完整代码与逐行剖析
2.1 脚本一：属性快照巡检（只读，不改库）
-- ============================================================ -- 08-01-audit.mac —— 模型数据巡检（只读，不写库） -- 调用方式：先把 !!CE 设到目标 ZONE（或 ZONE 上一层），再执行 -- $m/08-01-audit.mac -- 说明：宏没有参数声明，行尾多写的内容就是参数 $1、$2… -- 代码来源性质：按官方 PML 语法与 API 构造，需在本地 E3D Design 环境验证 -- ============================================================ -- 步骤 1：确认 CE 是什么类型，避免在错误的层级上开遍历 !tyCE = !!ce.type P 当前元素类型 = $!tyCE -- 步骤 2：在 CE 之下建立 BRAN 集合（只取直接归属的 BRAN） var !brans coll all BRAN for CE -- 步骤 3：取集合大小。为 0 说明层级选错，后面的循环会静默空转 !total = !brans.size() P 命中 BRAN 数量 = $!total -- 步骤 4：逐个遍历，读出关键属性 !i = 0 do !i from 1 to !total by 1 $!brans[$!i] -- 把集合第 !i 项设为当前元素（移动 !!CE 游标） !nm = !!ce.name -- 名称 !flnn = !!ce.flnn -- 全名（含全部拥有者路径），定位用 !owner = !!ce.namn -- 拥有者名称属性 -- 步骤 5：按企业命名规则算出"拟改名"，用于外部做冲突预检 !new = '/A-OLD-' + !nm -- 步骤 6：拼成一行，逗号分隔，便于外部按 CSV 解析 !row = !nm + ',' + !flnn + ',' + !owner + ',' + !new q var !row -- 输出到 Command Window，人工逐行核对 enddo P 巡检结束，未对数据库做任何写入。逐行剖析
!tyCE = !!ce.type：type读的是元素的类型名。先打印类型再建集合，是因为集合建立语句本身不校验层级——你在错误的层级上COLL ALL BRAN FOR CE，得到的只是一个空集合，而不是错误。var !brans coll all BRAN for CE：VAR声明变量，COLL建立集合，ALL BRAN指定类型，FOR CE指定归属范围。这里BRAN是类型名，大小写按环境习惯写即可。!brans.size()：集合的成员方法，返回条目数。空集合不报错，所以必须自己判断。do !i from 1 to !total by 1 … enddo：PML 的计数循环。索引从 1 开始，这是 PML 与多数编程语言的第一处反直觉。$!brans[$!i]：方括号取第!i项并"执行"它——等价于把!!CE移到这一项。这一行是整个巡检脚本的引擎。!!ce.name/!!ce.flnn/!!ce.namn：三个属性读取。flnn是全名，批量改名后用于重新定位最可靠；namn在社区宏里被用来构造新元素名。!new = '/A-OLD-' + !nm：字符串拼接。PML 的字符串用+连接，这一点与社区宏中!c[1] + '-' + !c[2] + '-' + '$!e'的写法一致。q var !row：把变量内容输出到 Command Window。社区宏里用q var !q做过同样的事。注意q var是显示，不是写文件——巡检的第一版就该只显示，不要急着落盘。- 结尾的
P …：P是打印命令，社区真实代码中就用P CE is Branch.做输出。
2.2 巡检结果落成 CSV（文件对象）
PML 的文件读写由FILE 对象承担——SCRM 的对象类型清单里明确列有FILE，官方文档站也给出了文件对象的独立页面。但构造参数与方法签名需以 SCRM 的 Object Type Details 章节与本机为准，下面的封装按官方 API 签名构造，标注为待验证：
-- 【需在本地 E3D Design 环境验证】 -- 目的：把巡检行追加写入 CSV；FILE 对象的构造与方法名以 SCRM 为准 define function !!csvAppend(!path is STRING, !line is STRING) is BOOLEAN !ok = FALSE !f = object FILE(!path) -- 构造文件对象（签名待本机核对） !f.write(!line) -- 写入一行（方法名待本机核对） !f.close() -- 关闭句柄 !ok = TRUE return !ok endfunction -- 调用示例：把巡检行追加到指定 CSV !path = 'C:\E3D_AUDIT\branch_audit.csv' !row = 'BRAN-1001,/ZONE-A/PIPE-1/BRAN-1001,PIPE-1,/A-OLD-BRAN-1001' !ok = !!csvAppend(!path, !row)工程建议：如果本机验证时发现 FILE 对象的写入行为与预期不符，不要硬扛——巡检结果完全可以先用q var输出到 Command Window，再手工或外部脚本转 CSV。巡检的正确性比落盘方式重要得多。
2.3 脚本二：批量改名 + INCLUDE（写操作）
-- ============================================================ -- 08-02-rename.mac —— 批量改名与重新纳入（写库，必须先备份） -- 调用方式：$m/08-02-rename.mac <新前缀> -- $1 = 新前缀（行尾多余内容即参数） -- 前置条件：已在测试 MDB 上验证通过；已完成目标名冲突预检 -- 代码来源性质：按官方 PML 语法与 API 构造，需在本地 E3D Design 环境验证 -- ============================================================ !prefix = $1 P 本次改名前缀 = $!prefix -- 步骤 1：只在 CE 之下建立集合，把作用范围钉死 var !brans coll all BRAN for CE !total = !brans.size() P 待处理 BRAN 数量 = $!total -- 步骤 2：逐项改名。旧名与新名都先落成变量，便于生成对照日志 !i = 0 do !i from 1 to !total by 1 $!brans[$!i] -- 移动 !!CE 游标到第 !i 项 !old = !!ce.name -- 改名前的名称 !new = $!prefix + !old -- 改名后的名称（前缀 + 旧名） q var !old -- 记录"变更前" q var !new -- 记录"变更后" rename all $!old $!new -- 在当前作用范围内按名称改名 P 已改名：$!old -> $!new enddo -- 步骤 3：改名之后必须重新定位——名称变了，旧查询串已失效 !j = 0 do !j from 1 to !total by 1 $!brans[$!j] -- 仍按集合索引取项（集合本身不受改名影响） !now = !!ce.name -- 此时读到的是新名 include $!now -- 把改名后的元素重新纳入当前选择集合 enddo P 批量改名完成：共 $!total 项，请与预检清单逐条核对。逐行剖析
!prefix = $1：宏参数。宏没有define function那样的参数声明，行尾多写的内容就是参数，按位置对应$1、$2……var !brans coll all BRAN for CE：与巡检脚本完全一致。同一个作用范围、同一个类型过滤，这样"巡检看到的"与"改到的"才是同一批。!old = !!ce.name：必须在rename all之前取旧名。改名后再取!!ce.name，拿到的是新名，你就永远失去了"变更前"。!new = $!prefix + !old：拼接规则越简单越好。复杂的规则（截断、替换、大小写转换）建议用字符串方法链在巡检阶段先算好并人工确认，别在写库脚本里现算。rename all $!old $!new：RENAME ALL的语义是"在当前作用范围内，把名为!old的元素改名为!new"。社区宏的使用方式与此一致：rename all $!q $!d。- 步骤 3 的
include $!now：社区宏在rename all之后紧接include $!d，作用就是把改名后的元素重新纳入当前集合。这一步看起来多余，其实决定了改名后元素还能不能被后续命令（$* destination zone之类的移动/归属操作）继续作用。 - 收尾的
P …：输出汇总数。批量脚本的输出必须"首尾都有数字"，前一个是"待处理数"、后一个是"已处理数"，两个数不一致就说明中途出过事。
2.4 社区真实宏：支吊架批量复制与重命名
下面这段是 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可确认的机制点（其余如$!e、$!f、$*属原帖调用上下文中的参数占位，本文按原样转载，不作改写）：
var !supp coll all suppo for CE+do !x value !supp：外层遍历当前元素下的全部支吊架。new suppo … copy prev rename …：把选中的支吊架复制一份，名称为/copy-of-<原名>——复制在前、改名在后，所以新元素的名称一定带copy-of-。coll all suppo with matchw(name of suppo,'*copy-of-*') for zone：在 zone 范围内把刚生成的副本筛出来。MATCHW在这里承担的是"找回上一轮产物"的角色。!!ce.name.replace('copy-of-','').split('-')：字符串方法链。replace做替换、split按分隔符切分，切分结果用!c[1]、!c[2]取第 1、2 段——数组下标从 1 开始，与集合一致。!d = !c[1] + '-' + !c[2] + '-' + '$!e'：拼接出新名。注意最后一段直接写了'$!e'，这是把调用上下文里的参数拼进字符串。rename all $!q $!d+include $!d：改名 + 重新纳入，成对出现，与本篇 2.3 的写法完全同构。
从这段真实宏能学到的最关键一件事：批量改写的可靠性来自"命名规则可被模式匹配"（copy-of-）和"改名后立刻重新纳入"（include），而不是来自任何高级 API。
2.5 变更前后对照表的结构
巡检脚本与改写脚本各自输出一半，合起来就是对照表。建议固定四列：
| 列 | 来源 | 说明 |
|---|---|---|
| 变更前名称 | 巡检脚本的!nm/ 改写脚本的!old | 必须在改名之前取 |
| 变更后名称 | 巡检脚本的!new/ 改写脚本的!new | 两边规则必须完全一致 |
全名（flnn） | 巡检脚本 | 改名后全名会变，但它记录的是"变更前的完整位置" |
| 处理结果 | 改写脚本 | 成功 / 冲突 / 跳过 |
四列齐了才叫对照表。只有"变更后名称"一列的那种，出了事没法回退。
三、常见报错与排查
3.1 循环输出一列完全相同的值
- 现象：巡检输出的每一行
name都一样，且等于!!CE本身的名称。 - 原因：循环体里漏了
$!coll[$!i]（或$!x），!!CE游标没移动。 - 排查：在循环体第一行临时插入
P 当前项索引 = $!i与q var !!ce.name，确认游标确实在动。
3.2 循环一次都不执行，且没有任何报错
- 现象：脚本正常跑完，
P 命中 BRAN 数量 = 0，之后什么都不输出。 - 原因：
!!CE的层级选错（例如选在了 ZONE，而 BRAN 的归属是 PIPE），集合为空。 - 排查：先打印
!!ce.type，再把类型过滤放宽一级验证（例如先建for CE的子元素集合，看有没有东西）。
3.3rename all之后取不到元素
- 现象：改写脚本后半段用旧名去查元素，得到空集合；或后续命令"没反应"。
- 原因：改名后未执行
INCLUDE，元素未纳入当前选择集合。 - 排查：按社区宏的写法，
rename all后立刻include <新名>；并检查新名是否与预期一致（打印出来核对）。
3.4 改名失败但没有任何提示
- 现象：脚本跑完，部分元素名称没变。
- 原因：新名与同层级已有元素重名，唯一性约束导致改名被拒；而 PML 的错误处理机制决定了它不会在此刻立刻抛出。
- 机制：官方说明，PML 宏/函数中的错误不会立即报错，报不报取决于下一行输入——如果下一条是匹配的
handle命令，错误不输出，转而执行匹配的 handle 块；elsehandle用于 handle 块不匹配的情形。 - 排查：在写入脚本里把可能失败的语句集中处理，给出一条尾随的 handle 骨架（写法以 PMLCG「Errors and Error Handling」章节为准）：
-- 【需在本地 E3D Design 环境验证】handle 的匹配写法以 PMLCG 为准 rename all $!old $!new handle -- 匹配到错误：错误不输出，转而执行这里 P 改名被拒（疑似重名）：$!old -> $!new elsehandle P 改名成功：$!old -> $!new endhandle3.5 变量名过长导致定义失败
- 现象：脚本报变量定义失败，或行为异常。
- 原因：官方限制——PML 变量名最长 16 字符、不能以数字开头、不能含
.。 - 排查：把
!targetBranchNameNew这类"好读但超长"的名字压缩到 16 字符内（如!nmNew）。
3.6 把界面上的 “My Collections” 当成 PML 集合
- 现象：以为在界面上建的集合（My Collections）能在脚本里用
COLL直接引用。 - 原因：官方在社区回复中明确：PML 中的 collection 与界面上的 “My Collections” 不是一回事；Shared Collections 实为 GPWL / GPSET / GPITEMS 体系。
- 排查：脚本里一律用
VAR … COLL …现场建集合，不要依赖界面集合。
四、动手练习
只读巡检 + 数量校验
在一个测试 MDB 的 ZONE 下设!!CE，运行08-01-audit.mac的巡检逻辑，输出该 ZONE 下 BRAN 的数量与每个 BRAN 的名称。
判定标准：Command Window 中"命中 BRAN 数量"与界面上该 ZONE 下的 BRAN 目视计数一致；输出中不存在两行完全相同的名称。命名冲突预检
把巡检输出的"拟改名"列导出到表格，用表格的重复值检测找出重复项，并说明这些重复是"与库内已有元素冲突"还是"两行拟改名互相冲突"。
判定标准：能给出重复条目数（可能为 0），并对每一条重复说出归属类型。在测试 MDB 上做一次可回退的批量改名
用08-02-rename.mac给某个 ZONE 下的全部 BRAN 加统一前缀。
判定标准：改名后"待处理数"与"已处理数"两个数字相等；随机抽 3 个元素，其新名 = 前缀 + 旧名；用反向前缀规则再跑一次巡检，能把这批元素全部枚举回来。反向练习：把
do … value …改写成索引循环
把 2.4 中社区宏的外层do !x value !supp … enddo改写成do !i from 1 to !supp.size() by 1 … $!supp[$!i] … enddo。
判定标准：改写前后输出行数与内容完全一致。
五、小结与下一篇预告
本篇把前面几篇的零件拼成了一条流水线：只读巡检 → 外部预检 → 写入改名 + 重新纳入 → 对照表。真正需要背下来的只有三件事：
- 遍历引擎是
$!coll[$!i]这一行，漏了它一切都不一样； - 命中集必须由
MATCHW这类可重复的筛选规则产生，而不是靠记忆； - 写库脚本必须"先备份、后写入、留下变更前后对照"——DABACON 的写操作不可逆。
下一篇09 .NET Addin 开发：换一条完全不同的路——不再写 PML，而是用 C# 写一个实现IAddin接口的类，让它在模块启动时被 CAF 通过反射找到并调用，从而把 .NET 的能力（复杂算法、外部库、企业系统对接）带进 E3D Design。
FAQ
Q1：为什么"巡检"和"批量改写"不能写在同一个脚本里？
因为 DABACON 的写操作不可逆。同一个脚本里边遍历边改，一旦循环中途出错，前面已经改掉的部分无法用"回退脚本"恢复，你连"改之前是什么样"都拿不出证据。分成两个脚本后，第一个脚本只读、只输出，产物是"变更前快照"；第二个脚本只做写入，且每一项的旧值都已经被第一个脚本记录下来；两段之间插一次人工/外部的命名冲突预检，才能在出问题时说清"哪一项没改、哪一项改错了"。
Q2：!!CE在遍历里到底扮演什么角色？为什么循环体第一行往往是$!xxx[$!i]？!!CE是跟踪当前元素的全局DBREF，PML 的属性读取（!!ce.name等）与命令作用对象都以它为准。集合本身不会移动这个游标，只有"执行"集合的某一项才会移动。所以循环体第一行写$!xxx[$!i]（或$!x）的作用就是把集合第!i项变成当前元素。漏掉这一行，整个循环读的都是同一个元素。
Q3：VAR … COLL ALL … FOR CE与… WITH MATCHW(name of …, '…')分别在筛选什么？COLL ALL BRAN FOR CE筛的是"归属范围 + 类型"：在!!CE之下、类型为BRAN的元素。WITH MATCHW(name of suppo,'*copy-of-*')筛的是"属性值模式"：名称属性符合通配模式的元素，*表示任意字符。前者是结构筛选，后者是命名筛选，两者可以叠加，叠加后的集合就是"我要处理的精确靶子"。
Q4：RENAME ALL之后为什么必须紧跟INCLUDE？不跟会发生什么？
因为名称是定位元素的手段之一，改名后旧的查询串就失效了，元素也不再处于"当前选择集合"里。社区真实宏的做法是rename all之后立刻include <新名>，把改名后的元素重新纳入，后续命令（如归属调整、移动）才能继续对它生效。不跟INCLUDE的后果通常是静默失败：PML 在很多情况下不报错，只是什么都不做，你以为改成功了，实际后续步骤全部落空。
Q5：批量改名最容易踩的坑是"命名冲突"，它从哪来、怎么提前挡住？
冲突有两个来源：一是新名与同层级已有元素重名（唯一性约束导致改名被拒）；二是过滤规则过宽，把已改过名的元素又选进来，导致同一元素被改成"叠了两层后缀"的名字。挡住它的唯一办法是"先只读、后写入"：在只读巡检阶段就把"拟改名"整列算出来，在外部做一次重复值检测；确认无重复后再执行写入。不要在写库脚本里用异常处理去补救冲突，因为 PML 的错误不会立刻抛出，补救往往来不及。
Q6：PML 的错误处理机制为什么不支持"立刻抛异常"的写法？
因为官方定义的 PML 错误处理是"延迟判定"：宏或函数中的错误不会立即报错，报不报取决于下一行的输入。如果紧跟一条匹配的handle命令，错误就不输出，转而执行匹配的 handle 块；elsehandle用于没有 handle 块匹配的情形。这意味着你不能像多数语言那样靠 try/catch 把风险语句包起来就地判定成功/失败——失败信息要等到下一行才可能被"接住"，所以工程上更应该把风险前移到只读预检，而不是依赖运行期捕获。
