dc/.agents/skills/dc-sas/SKILL.md

name, description

name

description

dc-sas

Use this skill alongside the sasjs/skills collection (sas, sasjs-core, sasjs-cli) when working on Data Controller SAS code. Covers the repo-specific SAS knowledge that is NOT in those skills — DC test-state conventions (MPE control tables, dctest, %let syscc) and the chunked-deploy strategy for the huge generated build script (sasjsbuild/viya.sas). For general SAS language, @sasjs/core macro, and @sasjs/cli guidance, rely on the sas, sasjs-core and sasjs-cli skills.

SAS Development in Data Controller

The sas, sasjs-core and sasjs-cli skills cover general SAS language and SASjs conventions (macro quoting, %mp_assert* testing style, sasjs lint, sasjs run, sasjsbuild/ being generated output). These notes only cover the parts specific to Data Controller.

Tests must be idempotent

A test file must pass when run repeatedly (including after a run that failed partway).

• Clean up all persistent DC state, not just the obvious one: MPE_TABLES registrations, MPE_LOCKANYTABLE lock records (a run dying between LOCK and UNLOCK leaves a stale LOCKED row), physical tables in dctest (proc datasets ... delete), and global macro variables created via select ... into: (%symdel).

Chunked deploy to Viya

The full DC build script (sasjsbuild/viya.sas) is very large (11+ MB / 300k+ lines). The Viya compute API can hang or fail when submitting a file this size in a single request.

Chunked deploy. Split the build script at %let path=<folder> boundaries — these are clean section breaks between service/test folders (always preceded by blank lines, never inside a data step). Each sub-chunk must be prepended with the shared header (the first ~3827 lines containing macro definitions, appLoc setup, and logging options:

options ps=max nonotes nosgen nomprint nomlogic nosource2 nosource noquotelenmax;

Logging is already suppressed in the header — no extra action needed. Keep each chunk under ~1.5 MB. The tests/macros, tests/services, and streaming-app tail sections are the largest and may need further sub-splitting at %let service= boundaries.

When splitting mid-folder (between services in the same folder), the sub-chunk that starts mid-folder must re-assert %let path=<folder>; before its first %let service= line — otherwise &path is unresolved and the %mv_createwebservice(path=&appLoc/&path, ...) call will abort with a recursive reference error.

Deploy each chunk in order with sasjs run <chunk>.sas -t <target>. After all chunks are deployed, run sasjs request services/admin/makedata -d deploy/makeDataViya.json -t <target> to create the database.

Non-fatal errors. ERROR: Unauthorized on /dataSources/providers/Compute/ lines in the log are expected for non-admin Viya users — they come from the Data Sources API during lineage/catalog refresh and do not affect the deploy.

Repo conventions for .sas files

• Test files are named <thing>.test.sas (or <thing>.test.N.sas) and run via npm run 4gl && sasjs test -t 4gl from sas/ — see .agents/docs/testing.md.
• sas/sasjsbuild/ is generated build output — never hand-edit it; edit sources under sas/sasjs/ only.

Temp and scratch files stay out of the repo

Transient artifacts from manual test runs against sasjs-server — captured _webout JSON responses (e.g. *_out.json), request/response logs (e.g. *.log), and iteration snapshots (vd_out2.json, stage_check2.json, etc.) — must not be left in the working tree. They clutter git status, are never referenced by source or tests, and easily leak local filesystem paths (the sasjs-server session dir, /home/.../sasjs_root/sessions/.../) into committed history.

Write them to a gitignored tmp location instead. The repo already provides two:

• tmp/ (gitignored at repo root) — general scratch space.
• sas/tmp/ (gitignored via the root tmp/ rule) — for SAS-side artifacts.

If a helper script dumps captured output for comparison during a debug session, point it at tmp/ (or sas/tmp/ for SAS-local paths) rather than alongside the tracked mocks in sas/mocks/. The tracked mock fixtures live under sas/mocks/sas9/ and sas/mocks/sasjs/services/; loose *_out.json / *.log files at the sas/mocks/ root are not mocks, they are leftover captures — remove them with git clean -fd sas/mocks/ or write to tmp/ in the first place.