sas-packages

SAS Packages (SPF)

SAS 软件包是一个单独的 zip 文件，其中包含一组 SAS 程序（宏、函数、数据步骤），以及自动生成的描述、加载、卸载和帮助文件。SAS Packages Framework（SPF，由 Bartosz Jablonski 开发）会从一个 zip 文件目录中安装和加载这些软件包，因此无需修改 SASAUTOS 或宏目录，就能固定软件包版本、进行版本管理并替换软件包。

本技能介绍如何作为使用者使用该框架。它并非 SASjs 专用——SPF 是一个独立项目，它提供的软件包可以来自任何作者。

适用场景

• 在 SAS 会话中安装软件包，例如 sasjscore（@sasjs/core 的 SASPAC 打包版本）
• 调试 %installPackage / %helpPackage / %loadPackage 失败的问题
• 设置软件包目录，或确定 packages fileref 应指向哪个路径
• 为单个作业加载宏，而不将它们添加到共享服务器的 SASAUTOS 中

不适用于：编写或发布软件包（%generatePackage），或遵循 @sasjs/core 自身的宏编码规范——相关内容请参阅 sasjs-core 技能。

启用框架

框架是一个单独的文件。在会话中启用它：

filename packages "%sysfunc(pathname(work))";
filename SPFinit url "https://bit.ly/SPFinit";
%include SPFinit;

原始 URL https://raw.githubusercontent.com/yabwon/SAS_PACKAGES/main/SPF/SPFinit.sas 指向同一个文件，只是不使用短链接；如果不希望发生重定向，这是更好的选择。启用框架需要 SAS 会话能够访问互联网；除非将文件保存在磁盘上，否则每个会话都需要启用一次（参见下文的持久化）。

packages fileref（必需）

• fileref 必须命名为 packages。packages 和 package 是 SPF 中的保留关键字；使用其他名称将无法被识别。
• 它指向一个目录，而不是 zip 文件。
• 目录必须已存在。 SPF 不会创建目录——文档说明 %installPackage 等同于手动将 zip 下载到该文件夹中，而且它不会替你创建文件夹。

根据需求选择路径：

需求	使用
临时 / 可移植，适用于 Windows、Viya 和 SASjs Server	filename packages "%sysfunc(pathname(work))";
会话结束后仍保留（安装一次，重复使用）	一个已存在的实际目录，例如 Windows 上的 C:/SAS_PACKAGES，或 Linux 环境中的任意可写目录

SPF 文档中经常出现 C:/SAS_PACKAGES，但这是 Windows 示例。在 Linux（Viya、SASjs Server）上，它只是一个相对路径，因此除非该目录恰好已存在，否则安装会失败——参见“常见问题”。

安装、加载和卸载

%installPackage(sasjscore)  %* download the zip into the packages folder;
%helpPackage(sasjscore)     %* print the package description and contents;
%loadPackage(sasjscore)     %* compile the macros into the session;
%unloadPackage(sasjscore)   %* remove them again;

• %installPackage() 会通过网络获取 zip 文件。默认来源是 SASPAC 存档 https://github.com/SASPAC/；可通过 sourcePath= 或 mirror= 覆盖。
• 软件包名称以空格分隔，不带 .zip 扩展名：%installPackage(pkg1 pkg2)。在括号中指定固定版本：%installPackage(baseplus(1.17) macroarray(1.0))。添加 replace=0 可避免覆盖已安装的软件包。
• %installPackage(SPFinit) 会将框架本身安装到软件包目录中。
• %loadPackage() 会将内容编译到会话中；%unloadPackage() 会从宏目录中删除这些条目。如果某个作业需要这些宏，但服务器不应在 SASAUTOS 中保留它们，可以在同一个会话中加载、使用并卸载。
• 如果 SAS 会话不支持 zip fileref，请将 <name>.zip 解压到 <name>.disk，并传入 zip=disk：%loadPackage(pkgname,zip=disk,options=)。

持久化：安装一次，然后离线使用

先将框架安装到软件包目录中：

%installPackage(SPFinit)

之后，两个需要联网的语句可合并为一个本地 include，运行时无需访问网络：

filename packages "/permanent/path/to/packages";
%include packages(SPFinit.sas);
%loadPackage(sasjscore)

这要求 fileref 指向一个永久目录——如果使用 %sysfunc(pathname(work))，会话结束时框架也会消失。

陷阱

• rc=20006 表示失败，尽管看起来像成功。 %installPackage 会打印 Done with return code rc=20006 (zero = success)——括号中的内容只是消息模板。20006 表示安装失败；真正的错误是后面那行 ERROR: Physical file does not exist, <dir>/<name>.zip。不要只相信 rc= 这一行。
• 调用 %installPackage 前，packages 文件夹必须已存在。 这是上述失败最常见的原因，在 Linux 上尤其容易遇到，因为文档中的 C:/SAS_PACKAGES 示例会悄悄变成相对路径。使用 %put %sysfunc(fileexist(<dir>)); 验证；如果返回 0，请先创建该文件夹。
• 缺少 zip 文件会引发连锁故障。 安装失败后，%helpPackage 和 %loadPackage 都会因 File "<dir>/<name>.zip" does not exist! 而失败，而且这些宏根本不存在——后续调用会提示 WARNING: Apparent invocation of macro X not resolved。请修复安装问题，而不是追查宏。
• 安装需要 SAS 会话具备网络出站访问能力，而不是你的工作站具备网络访问能力。无法访问互联网的受限计算环境无法连接 SASPAC 或 GitHub。
• %loadPackage 仅对当前会话生效。 在一个会话中加载的宏在另一个会话中不可见；请在每个会话中重新加载（或使用 SASAUTOS / CLI 以实现持久解析）。

验证

加载后，请确认这些宏确实已生效，而不是假定安装成功：

%put NOTE: package version check;
%helpPackage(sasjscore)          %* prints "Help for package SASjsCore, version X.Y.Z, license MIT";
%put NOTE: getuser returns %mf_getuser();

运行正常时会显示 INFO: Package sasjscore installed.、包含明确版本号的帮助信息块，以及已解析的宏调用。随后，可以通过再次调用并返回 Apparent invocation of macro MF_GETUSER not resolved 来确认 %unloadPackage() 已生效。

局限

此技能是 SAS Packages Framework 的静态参考。它不会执行 SAS 代码、运行 shell 命令、访问文件系统或发起网络请求。代码示例仅供参考，用户必须将其提交到 SAS 会话中。该框架由 https://github.com/yabwon/SAS_PACKAGES 维护，归档位于 https://github.com/SASPAC——请查阅这些资源以获取权威的宏参考和当前框架版本。