1. 代码开发工具选型:为什么用 UFUN 清理工作部件而不是手工点菜单
代码开发工具选型这件事,在 NX 二次开发里往往不是比谁功能多,而是比谁能把一次性的手工清理变成可重复执行的命令。工作部件交付前要清掉冗余对象,手工点菜单容易漏,用 UFUN 写 cleanup 小程序更稳:入口短、日志可追踪,批量时还能从命令行灌入 PRT 列表。
它适合需要反复出图、出件的工程师,也适合要把清理动作固化到交付流程里的团队;不适合只想学界面按钮的人。下面从最小工程骨架开始,把 UF_CALL、ufusr 和外部模式批处理串起来。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. NX 二次开发代码开发工具链:UF_CALL、ufusr 与 do_it 三件套
最小工程不需要花哨界面。一个能跑的 cleanup 命令通常只有三层:错误上报、入口生命周期、实际清理。三层拆开后,交互模式和外部模式可以共用 do_it,不会把打开、保存、关闭混在清理逻辑里。先写 UF_CALL,是因为后面每一行 UFUN 调用都要能定位到文件和行号,否则批量跑完只看到一句失败,排查成本很高。
2.1 错误上报骨架:UF_CALL 把返回值变成可追踪日志
cpp复制#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <uf.h>
#include <uf_ui.h>
#include <uf_cfi.h>
#include <uf_part.h>
// 统一错误上报:文件、行号、调用文本一起记录
#define UF_CALL(X) (report_error(__FILE__, __LINE__, #X, (X)))
static int report_error(char *file, int line, char *call, int irc)
{
if (irc)
{
char err[133], msg[133];
sprintf(msg, "*** ERROR code %d at line %d in %s:\n+++ ",
irc, line, file);
UF_get_fail_message(irc, err);
// 系统日志:外部模式没有界面时,这条线仍然能留下线索
UF_print_syslog(msg, FALSE);
UF_print_syslog(err, FALSE);
UF_print_syslog("\n", FALSE);
UF_print_syslog(call, FALSE);
UF_print_syslog(";\n", FALSE);
// 交互模式尽量同步到列表窗口
if (!UF_UI_open_listing_window())
{
UF_UI_write_listing_window(msg);
UF_UI_write_listing_window(err);
UF_UI_write_listing_window("\n");
UF_UI_write_listing_window(call);
UF_UI_write_listing_window(";\n");
}
}
return irc;
}
这段代码的重点不是“打印错误”,而是把一次 UFUN 调用变成可回溯记录。UF_CALL(X) 里的 X 是实际调用,宏展开时把 __FILE__、__LINE__ 和 #X 一起传给 report_error,所以日志里能同时看到哪个文件、哪一行、调用了什么。irc 是 UFUN 返回码,非零才进入错误分支;UF_get_fail_message 把返回码翻译成可读文本,避免只看到一串数字。
UF_print_syslog 负责系统日志,UF_UI_open_listing_window 和 UF_UI_write_listing_window 负责把同样的内容写到 NX 的列表窗口。注意 UF_UI_open_listing_window() 返回 0 才表示打开成功,因此代码里用 ! 判断。外部模式下没有可用的 UI 上下文时,列表窗口这一段可能走不到,日志就要靠系统日志和后面的 printf 接住。老环境编译前要确认 UF_print_syslog 是否存在,别把错误骨架写成编译错误。
固定缓冲区 err[133]、msg[133] 够不够用,取决于文件路径和错误文本长度。路径特别长时,不要把整条路径硬塞进 msg,否则 sprintf 可能截断或越界。这个骨架的目标是让错误可见,不是替代完整的日志系统。
2.2 清理动作 do_it:位掩码参数怎么读
cpp复制static void do_it(void)
{
// 在 all 的基础上排除 parts_all 与 parts_components 两类清理项
UF_CALL(UF_PART_cleanup(
UF_PART_cleanup_all &
~UF_PART_cleanup_parts_all &
~UF_PART_cleanup_parts_components));
}
do_it 只做一件事:调用 UF_PART_cleanup。参数不是单个枚举,而是一个位掩码表达式:先取 UF_PART_cleanup_all 作为全集,再用按位与取反的方式把 UF_PART_cleanup_parts_all 和 UF_PART_cleanup_parts_components 两个位排除掉。按这段代码的意图,清理时不要连带触发“整件”和“组件”相关的清理项,避免把不该动的结构一起处理。
这里的“排除”必须和业务预期对齐。有人看到 all 就以为所有清理项都会执行,实际表达式已经减掉了两类;反过来,如果确实要全部清理,就不能照抄这个掩码。不同版本的枚举定义可能变化,编译前看头文件里的位定义,比背表达式可靠。清理动作本身不保存文件,交互入口只负责把当前工作部件清干净,保存要由调用方或外部批处理决定。
UF_CALL 包住 UF_PART_cleanup 后,返回码会进入统一错误上报。如果掩码写错导致 API 返回非零,日志里能看到具体调用文本;如果返回 0 但结果不对,那就不是错误上报能解决的事,要回头检查位掩码和当前版本枚举。
2.3 入口与卸载:ufusr 和 ufusr_ask_unload 的生命周期
cpp复制void ufusr(char *param, int *retcode, int paramLen)
{
if (UF_CALL(UF_initialize())) return;
do_it();
UF_terminate();
}
int ufusr_ask_unload(void)
{
return (UF_UNLOAD_IMMEDIATELY);
}
ufusr 是交互入口。进入后第一件事是 UF_initialize(),没有初始化就不要调用后续 UFUN。初始化失败时直接返回,避免在未就绪环境里继续执行。do_it() 放在初始化和终止之间,保证清理动作处在有效的 UFUN 会话里。最后 UF_terminate() 释放会话资源,不能因为函数短就省掉。
param、paramLen 在这个最小示例里没有使用,retcode 也没有被赋值。这意味着交互入口即使清理失败,宿主侧也未必能通过返回码知道;失败信息主要靠 UF_CALL 的日志。如果调用方需要明确成功或失败,就要在返回前给 *retcode 设置约定值,别让“没有报错”和“执行成功”混为一谈。
ufusr_ask_unload 返回 UF_UNLOAD_IMMEDIATELY,表示卸载策略是立即卸载。这个返回值要和入口的生命周期一起看:如果后续还要在同一个会话里保留状态,就不能随意改成延迟卸载;如果只是一次性清理命令,立即卸载更干净。交互入口不调用 UF_PART_save,所以它适合“先看结果再决定是否保存”的场景。真正跑批时,保存逻辑放在外部 main 的成功分支里。
3. 外部模式跑批:用代码开发工具批量打开 PRT 并执行 cleanup
批量跑的时候,交互入口不够用:每次点菜单不现实。外部模式把程序当成独立 exe 运行,靠命令行传入 PRT 列表。这套骨架里的 main 不是简单循环,它先用 uc4624 解析参数,再用 uc4621 逐个取部件名,失败时用 check_load_status 打印并释放状态。
3.1 命令行参数如何变成 PRT 列表:uc4624 与 uc4621
cpp复制int main(int argc, char *argv[])
{
int cnt = 0;
tag_t part;
char part_name[MAX_FSPEC_SIZE + 1];
UF_PART_load_status_t status;
if (!UF_CALL(UF_initialize()))
{
// 把 argc/argv 交给 UFUN 的命令行参数解析
UF_CALL(uc4624(0, argc, argv));
// uc4621 返回 1 表示取到一个部件名
while (uc4621(part_name) == 1)
{
printf("%d. %s\n", ++cnt, part_name);
if (UF_CALL(UF_PART_open(part_name, &part, &status))
|| status.n_parts > 0)
{
check_load_status(&status);
}
else
{
do_it();
UF_CALL(UF_PART_save());
UF_PART_close_all();
}
}
printf("\nProcessed %d parts.\n", cnt);
UF_CALL(UF_terminate());
}
return 0;
}
main 的第一段是初始化,第二段是参数解析。uc4624(0, argc, argv) 的第一个参数在示例里传 0,按原代码保留;argc 和 argv 直接来自进程启动参数。uc4621(part_name) 每次取一个部件名,返回 1 表示还有下一项,返回其他值就结束循环。part_name 用 MAX_FSPEC_SIZE + 1 分配,给结尾留一个字符位置。
UF_PART_open(part_name, &part, &status) 打开部件,part 接收 tag,status 接收加载状态。判断条件里有两个分支:UF_PART_open 返回非零,或者 status.n_parts > 0,都走 check_load_status。前者是打开调用失败,后者是打开过程中有需要报告的子状态。只有两者都干净时,才执行 do_it()、UF_PART_save() 和 UF_PART_close_all()。
printf("%d. %s\n", ++cnt, part_name) 在打开之前执行,所以 cnt 统计的是“尝试处理的部件数”,不是“成功清理的部件数”。最后那句 Processed %d parts 看起来很顺眼,但不能当成成功数。批量脚本里要把这个区别记住,否则失败文件被算进 processed,复盘时会对不上。
3.2 打开失败的收尾:check_load_status 为什么要释放两块内存
cpp复制static void check_load_status(UF_PART_load_status_p_t status)
{
char msg[133];
int ii;
for (ii = 0; ii < status->n_parts; ii++)
{
UF_get_fail_message(status->statuses[ii], msg);
printf(" %s - %s\n", status->file_names[ii], msg);
}
UF_free(status->statuses);
UF_free_string_array(status->n_parts, status->file_names);
}
check_load_status 处理的是 UF_PART_load_status_t。status->n_parts 是状态条目数,status->statuses[ii] 是每个条目的返回码,status->file_names[ii] 是对应文件名。UF_get_fail_message 把返回码转成文本,printf 把“文件名 - 错误文本”打到标准输出,外部模式运行时能在控制台看到。
两块内存必须释放:status->statuses 用 UF_free,status->file_names 用 UF_free_string_array,后者还要带上 status->n_parts。批量处理几十上百个文件时,漏掉释放会累积泄漏;更麻烦的是,下一次 UF_PART_open 还可能复用结构,状态没清干净会干扰判断。把释放放在打印之后,保证错误信息先落地,再回收内存。
这个函数要放在 main 前面,或者在 main 之前先声明。示例里 main 直接调用它,如果没有声明,编译会报找不到函数。打开失败时不要继续执行 do_it 和 UF_PART_save,否则可能对半加载的部件做清理和保存,风险比直接跳过更大。
3.3 批量保存的边界:先小批量验证再放开
外部模式的命令行写法在示例注释里给了两类:
bash复制program.exe /path/to/part1.prt /path/to/part2.prt
program.exe -pim=yes @DB/partno1/rev @DB/partno2/rev
第一行是外部原生模式,后面直接跟 PRT 文件路径。路径里有空格时要加引号,否则 argc/argv 会被拆成多个参数,uc4621 取到的部件名就不完整。第二行带 -pim=yes,走受管数据模式的参数写法,@DB/... 是数据引用,不是普通文件路径。两种模式不要混着传,先把单件跑通,再扩到两件、三件。
批量保存是这个工具最需要克制的地方。成功分支里 do_it() 之后直接 UF_PART_save(),然后 UF_PART_close_all(),没有询问、没有另存、没有备份。也就是说,只要打开成功、状态干净,源 PRT 就会被就地保存。第一次跑必须用副本,确认清理掩码和保存结果都符合预期,再考虑在生产目录执行。
我一般会先用一个测试文件跑交互入口,看 UF_CALL 有没有错误、do_it 后的结果对不对;再用外部模式跑单件,确认 Processed 1 parts 和 UF_PART_open 的状态;最后才跑两件小批量,其中故意混一个错误路径,观察 check_load_status 能不能打印文件名和错误文本。这个顺序能把“打开失败”“清理失败”“保存覆盖”三类问题分开。
4. 常见问题排查:NX 二次开发 cleanup 最容易翻车的四处
cleanup 命令短,但翻车点不少。下面四条都是从入口生命周期、位掩码、命令行参数和保存分支里长出来的,按“现象 → 原因 → 解决”拆开看。
4.1 列表窗口没有错误信息:外部模式没有可写的 UI 上下文
现象:外部 exe 跑完只看到 Processed N parts,打开失败的文件没有在列表窗口里留下任何错误;有时连列表窗口都没有弹出来。
原因:report_error 里先写 UF_print_syslog,再尝试 UF_UI_open_listing_window()。外部模式没有交互式 UI 上下文时,打开列表窗口可能失败,后面的 UF_UI_write_listing_window 就不会执行。错误并没有消失,只是写到了系统日志,或者根本没进入 UI 分支。
解决:外部批处理不要依赖列表窗口,先看系统日志;同时在 check_load_status 里保留 printf,把文件名和 UF_get_fail_message 的文本打到控制台。需要看 UI 的时候,回到交互模式触发 ufusr,再对照系统日志。两种入口的日志通道不一样,别用同一种预期去判断。
4.2 cleanup 返回 0 但该清的对象还在:位掩码排除了 parts_all 与 parts_components
现象:UF_PART_cleanup 没有报错,日志干净,但打开部件检查时发现预期要清理的整件或组件相关对象仍然存在。
原因:do_it 用的是 UF_PART_cleanup_all & ~UF_PART_cleanup_parts_all & ~UF_PART_cleanup_parts_components。这不是“全部清理”,而是在 all 的基础上排除了两个位。如果业务预期是全部清理,这个掩码本身就把目标排掉了;如果版本枚举定义不同,排除的也可能是另一类清理项。
解决:先查当前版本头文件里的枚举位定义,确认 parts_all 和 parts_components 到底代表什么;再在测试副本上把掩码拆开,一次只保留一个清理项,观察结果变化。不要在没有备份的部件上反复试掩码。返回 0 只说明调用成功,不说明清理范围符合业务预期。
4.3 Processed 0 parts:命令行参数没有进到 uc4621
现象:外部 exe 启动后直接打印 Processed 0 parts,一个部件都没打开;或者只处理了第一个,后面的路径没有进入循环。
原因:uc4624(0, argc, argv) 依赖进程启动参数,uc4621(part_name) 再逐个取出部件名。启动时没有传参、路径被空格拆开、引号没加对、工作目录和相对路径不匹配,都会让 uc4621 取不到完整名字。取不到时循环条件不成立,计数自然停在 0。
解决:先用一个全路径的测试文件跑单件,命令里只放一个参数,确认 Processed 1 parts;再跑两个路径,检查 printf 打出来的名字是不是完整路径。路径带空格时加引号,相对路径改成绝对路径。受管模式的 -pim=yes 和 @DB/... 写法要单独验证,不要和普通文件路径混在一起。
4.4 跑完后源文件被改:成功分支无条件执行 UF_PART_save
现象:批量跑完,源 PRT 的修改时间变了,内容也被清理过;如果清理掩码不符合预期,原文件已经没有后悔药。
原因:main 的成功分支是 do_it()、UF_PART_save()、UF_PART_close_all() 顺序执行。只要 UF_PART_open 成功且 status.n_parts 为 0,就会进入这个分支,没有二次确认,也没有另存。UF_PART_close_all() 还会把当前进程里打开的部件统一关掉。
解决:第一次运行必须用副本目录,不要直接指向生产文件;确认掩码、日志和清理结果后,再让保存分支进入正式目录。需要更保守时,做一个不调用 UF_PART_save 的测试构建,只看 do_it 后的结果,确认无误后再恢复保存。批量前把文件纳入版本管理,至少留一条回退路径。
5. 验收与进阶:把 cleanup 命令收进代码开发工具的日常流程
我现在验收这类 cleanup 命令,不会只看 Processed N parts。先拿一份测试 PRT 走交互入口,确认 UF_initialize 成功、do_it 没有错误码、listing window 或系统日志干净;再跑外部单件,命令只给一个全路径文件,观察 UF_PART_open 是否成功、status.n_parts 是否为 0;最后才跑两件小批量,故意混一个不存在的路径,看 check_load_status 能不能打印文件名和 UF_get_fail_message 的文本。三关都过了,才把保存逻辑放到生产副本上。
| 验收
