sas-packages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAS Packages (SPF)

A SAS package is a single zip holding a group of SAS programs (macros, functions, data steps) plus automatically generated description, load, unload and help files. The SAS Packages Framework (SPF, by Bartosz Jablonski) installs and loads them from a folder of zips, so a package can be pinned, versioned and swapped without touching

SASAUTOS

or a macro catalogue.

This skill covers using the framework as a consumer. It is not SASjs-specific - SPF is an independent project, and the packages it serves come from any author.

一个 SAS package 是单个 zip 文件，包含一组 SAS 程序（macros、functions、data steps），以及自动生成的 description、load、unload 和 help 文件。SAS Packages Framework（SPF，由 Bartosz Jablonski 创建）负责从 zip 文件夹中安装和加载这些 package，从而无需改动

SASAUTOS

或 macro catalogue，即可固定 package 版本并切换 package。

本 skill 介绍如何使用该 framework。它并非 SASjs 专用——SPF 是一个独立项目，它所服务的 packages 可以来自任何作者。

When to use

何时使用

Installing a package into a SAS session, e.g.
```
sasjscore
```
(the SASPAC packaging of @sasjs/core)
Debugging
```
%installPackage
```
/
```
%helpPackage
```
/
```
%loadPackage
```
failures
Setting up a packages folder, or working out which path to point the
```
packages
```
fileref at
Loading macros for one job without adding them to a shared server's
```
SASAUTOS
```

Don't use for: authoring or publishing a package (

%generatePackage

), or for @sasjs/core's own macro coding standards - see the

sasjs-core

skill for those.

将 package 安装到 SAS session 中，例如
```
sasjscore
```
（
```
@sasjs/core
```
的 SASPAC packaging）
调试
```
%installPackage
```
/
```
%helpPackage
```
/
```
%loadPackage
```
失败问题
设置 packages 文件夹，或确定
```
packages
```
fileref 应指向的路径
为单个 job 加载 macros，而不将其添加到共享 server 的
```
SASAUTOS
```
中

不适用于：创作或发布 package（

%generatePackage

），也不适用于

@sasjs/core

自身的 macro 编码规范——相关内容请参阅

sasjs-core

skill。

Enabling the framework

启用 framework

The framework is a single file. Enable it in the session:

sas

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

The raw URL

https://raw.githubusercontent.com/yabwon/SAS_PACKAGES/main/SPF/SPFinit.sas

is the same file without the shortener, and is a better choice where a redirect is unwanted. Enabling the framework needs internet access from the SAS session; it is a one-off per session unless the file is kept on disk (see Persistence below).

该 framework 是单个文件。在 session 中启用：

sas

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

指向同一个文件，但不使用短链接；如果不希望发生重定向，应优先使用该 URL。启用 framework 需要 SAS session 具备互联网访问能力；除非将文件保存在磁盘上（见“持久化”部分），否则每个 session 只需执行一次。

The packages fileref (mandatory)

packages fileref（必需）

The fileref must be named
```
packages
```
.
```
packages
```
and
```
package
```
are reserved keywords in SPF; a different name is not picked up.
It points at a directory, not a zip file.
The directory must already exist. SPF does not create it -
```
%installPackage
```
is documented as equivalent to manually downloading the zip into that folder, and it will not make the folder for you.

Pick the path by what you need:

Need	Use
Throwaway / portable, works on Windows, Viya and SASjs Server	`filename packages "%sysfunc(pathname(work))";`
Survives the session (install once, reuse)	A real directory that exists, e.g. `C:/SAS_PACKAGES` on Windows, or any writable directory on a Linux estate

C:/SAS_PACKAGES

appears throughout the SPF documentation, but it is a Windows example. On Linux (Viya, SASjs Server) it is just a relative path, so unless that directory happens to exist the install fails - see Pitfalls.

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

根据实际需求选择路径：

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

C:/SAS_PACKAGES

出现在 SPF 文档的多个位置，但它只是一个 Windows 示例。在 Linux（Viya、SASjs Server）上，它会被视为相对路径，因此除非该目录恰好存在，否则安装会失败——请参阅“常见问题”部分。

Install, load, unload

安装、加载、卸载

sas

%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()
```
fetches the zip over the network. Default source is the SASPAC archive,
```
https://github.com/SASPAC/
```
; override with
```
sourcePath=
```
or
```
mirror=
```
.
Package names are space separated and carry no
```
.zip
```
extension:
```
%installPackage(pkg1 pkg2)
```
. Pin a version in parentheses:
```
%installPackage(baseplus(1.17) macroarray(1.0))
```
. Add
```
replace=0
```
to refuse to overwrite an already-installed package.
```
%installPackage(SPFinit)
```
installs the framework itself into the packages folder.
```
%loadPackage()
```
compiles into the session;
```
%unloadPackage()
```
deletes those entries from the macro catalogue. A job that needs the macros but whose server should not carry them in
```
SASAUTOS
```
can load, use and unload in one session.
Where the SAS session has no zip fileref support, unzip
```
<name>.zip
```
into
```
<name>.disk
```
and pass
```
zip=disk
```
:
```
%loadPackage(pkgname,zip=disk,options=)
```
.

sas

%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 archive
```
https://github.com/SASPAC/
```
；可使用
```
sourcePath=
```
或
```
mirror=
```
覆盖默认来源。
Package 名称以空格分隔，且不要带
```
.zip
```
扩展名：
```
%installPackage(pkg1 pkg2)
```
。可在括号中固定 version：
```
%installPackage(baseplus(1.17) macroarray(1.0))
```
。添加
```
replace=0
```
可拒绝覆盖已安装的 package。
```
%installPackage(SPFinit)
```
会将 framework 自身安装到 packages 文件夹中。
```
%loadPackage()
```
会将 macros 编译到 session 中；
```
%unloadPackage()
```
会从 macro catalogue 中删除相应条目。如果某个 job 需要这些 macros，但不希望其 server 将其持久保存到
```
SASAUTOS
```
中，可以在同一个 session 内完成加载、使用和卸载。
如果 SAS session 不支持 zip fileref，请将
```
<name>.zip
```
解压到
```
<name>.disk
```
，并传入
```
zip=disk
```
：
```
%loadPackage(pkgname,zip=disk,options=)
```
。

Persistence: install once, then go offline

持久化：安装一次，然后离线运行

Install the framework into the packages folder once:

sas

%installPackage(SPFinit)

After that the two network-facing lines collapse to a local include, and no network access is needed at run time:

sas

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

This requires the fileref to point at a permanent directory - with

%sysfunc(pathname(work))

the framework is gone when the session ends.

先将 framework 安装到 packages 文件夹中一次：

sas

%installPackage(SPFinit)

之后，两行面向网络的操作可简化为一次本地 include，运行时不再需要网络访问：

sas

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

这要求 fileref 指向一个永久目录——如果使用

%sysfunc(pathname(work))

，framework 会在 session 结束时消失。

Pitfalls

常见问题

rc=20006
is a failure, despite reading as success.
```
%installPackage
```
prints
```
Done with return code rc=20006 (zero = success)
```
- the parenthetical is just the message template. 20006 means the install failed; the real error is the
```
ERROR: Physical file does not exist, <dir>/<name>.zip
```
line that follows. Do not trust the
```
rc=
```
line alone.
The packages folder must exist before you call
%installPackage
. This is the most common cause of the failure above, and it bites hardest on Linux because the documented
```
C:/SAS_PACKAGES
```
example silently becomes a relative path. Verify with
```
%put %sysfunc(fileexist(<dir>));
```
and create it first if it returns 0.
A missing zip cascades. Once the install fails,
```
%helpPackage
```
and
```
%loadPackage
```
both fail with
```
File "<dir>/<name>.zip" does not exist!
```
, and the macros are simply absent - a later call gives
```
WARNING: Apparent invocation of macro X not resolved
```
. Fix the install rather than chasing the macro.
Installing needs network egress from the SAS session, not from your workstation. A locked-down compute context without internet cannot reach SASPAC or GitHub.
%loadPackage
is per session. Macros loaded in one session are not visible in another; re-load in each session (or use
```
SASAUTOS
```
/ the CLI for durable resolution).

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!
```
而失败，macros 也会直接缺失——后续调用将出现
```
WARNING: Apparent invocation of macro X not resolved
```
。应修复安装问题，而不是继续排查 macro。
安装需要 SAS session 具备网络出口能力，而不是你的 workstation。受严格限制且没有互联网访问的 compute context 无法连接 SASPAC 或 GitHub。
%loadPackage
的作用域限于单个 session。在一个 session 中加载的 macros 在另一个 session 中不可见；需要在每个 session 中重新加载，或者使用
```
SASAUTOS
```
/ CLI 实现持久解析。

Verification

验证

After loading, prove the macros are actually live rather than assuming the install worked:

sas

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

A clean run shows

INFO: Package sasjscore installed.

, the help block with an explicit version, and a resolved macro call.

%unloadPackage()

can then be confirmed by the same call returning

Apparent invocation of macro MF_GETUSER not resolved

加载后，应验证 macros 确实已生效，而不是想当然地认为安装成功：

sas

%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.

、包含明确 version 的 help 块，以及成功解析的 macro 调用。随后可以再次调用

%unloadPackage()

；如果同一个调用返回

Apparent invocation of macro MF_GETUSER not resolved

，即可确认卸载成功。

Limitations

限制

This skill is a static reference for the SAS Packages Framework. It does not execute SAS code, run shell commands, access the filesystem, or make network requests. Code examples are illustrative and must be submitted to a SAS session by the user. The framework is maintained at https://github.com/yabwon/SAS_PACKAGES and the archive at https://github.com/SASPAC - consult those for the authoritative macro reference and the current framework version.

本 skill 是 SAS Packages Framework 的静态参考文档。它不会执行 SAS 代码、运行 shell 命令、访问文件系统或发起网络请求。代码示例仅供说明，必须由用户提交给 SAS session 执行。Framework 维护地址为 https://github.com/yabwon/SAS_PACKAGES，archive 地址为 https://github.com/SASPAC——有关权威的 macro 参考和当前 framework version，请查阅这两个项目。