npm GitHub last commit

Much quality. Many standards. The Macro Core library exists to save time and development effort! Herein ye shall find a veritable host of MIT-licenced, production quality SAS macros. These are a mix of tools, utilities, functions and code generators that are useful in the context of Application Development on the SAS platform (eg https://datacontroller.io). Contributions are welcome.

You can download and compile them all in just two lines of SAS code:

filename mc url "https://raw.githubusercontent.com/sasjs/core/main/all.sas";

%inc mc;

Documentation: https://core.sasjs.io

Components

BASE folder (All Platforms)

OS independent
Works on all SAS Platforms
No X command
Prefixes: mf_, mp_

DDL folder (All Platforms)

OS independent
Works on all SAS Platforms
No X command
Prefixes: mddl_(lib)_ -> where lib can be "SAS" (in relation to a SAS component) or "DC" (in relation to a Data Controller component)

This library will not be used for storing data entries (such as formats or datalines). Where this becomes necessary in the future, a new repo will be created, in order to keep the NPM bundle size down (for the benefit of those looking to embed purely macros in their applications).

FCMP folder (All Platforms)

Function and macro names are identical, except for special cases
Prefixes: mcf_

The fcmp macros are used to generate fcmp functions, and can be used with or without the proc fcmp wrapper.

LUA folder

Wait - this is a macro library - what is LUA doing here? Well, it is a little known fact that you CAN run LUA within a SAS Macro. It has to be written to a text file with a .lua extension, from where you can include it. So, without using the proc lua wrapper.

To contribute, simply write your freeform LUA in the LUA folder. Then run the build.py, which will convert all files with a ".lua" extension into a macro wrapper with an ml_ prefix (embedding the necessary data step put statements). You can then use your module in any program by running:

/* compile the lua module */
%ml_yourmodule()
 
/* Execute.  Do not use the restart keyword! */
proc lua;
submit;
  print(yourStuff);
endsubmit;
run;

Prefixes: ml_

META folder (SAS9 only)

Macros used in SAS EBI, which connect to the metadata server.

OS independent
Metadata aware
No X command
Prefixes: mm_

METAX folder (SAS9 only)

OS specific
Metadata aware
X command enabled
Prefixes: mmx_

SERVER folder (@sasjs/server only)

These macros are used for building applications using @sasjs/server - an open source REST API for Desktop SAS.

OS independent
@sasjs/server aware
No X command
Prefixes: ms_

VIYA folder (Viya only)

Macros used for interfacing with SAS Viya.

OS independent
No X command
Prefixes: mv_, mvf_

XPLATFORM folder (Viya, Meta, and Server)

Sometimes it is helpful to use a macro that can be used interchangeably regardless of the server type on which is is running (SASVIYA, SAS9, SASJS).

OS independent
No X command
Prefixes: mx_

Installation

First, download the repo to a location your SAS system can access. Then update your sasautos path to include the components you wish to have available, eg:

%let repoloc=/your/path/core;
options insert=(sasautos="&repoloc/base");
options insert=(sasautos="&repoloc/ddl");
options insert=(sasautos="&repoloc/fcmp");
options insert=(sasautos="&repoloc/lua");
options insert=(sasautos="&repoloc/meta");
options insert=(sasautos="&repoloc/metax");
options insert=(sasautos="&repoloc/server");
options insert=(sasautos="&repoloc/viya");
options insert=(sasautos="&repoloc/xplatform");

The above can be done directly in your sas program, via an autoexec, or an initialisation program.

Alternatively - for quick access - simply run the following! This file contains all the macros.

filename mc url "https://raw.githubusercontent.com/sasjs/core/main/all.sas";

%inc mc;

Agent Skills

This repo ships with agent skills (in .agents/skills) to help coding assistants write idiomatic SAS and follow the @sasjs/core standards. The canonical versions live in the sasjs/skills repo and cover SAS language, @sasjs/core, @sasjs/adapter, @sasjs/cli, the SASjs framework, and @sasjs/server.

To install or update them in your own project, run:

npx skills add sasjs/skills

Standards

File Properties

filenames much match macro names
filenames must be lowercase, without spaces
macro names must be lowercase
one macro per file
prefixes:
- _mcf__: macro compiled functions (proc fcmp)
- _mddl__: macros containing DDL (Data Definition Language)
- _mf__: macro functions (can be used in open code).
- _mfv__: macro functions that work only in Viya
- _ml__: macros that are used to compile LUA modules
- _mm__: metadata macros (interface with the metadata server).
- _mmx__: macros that use metadata and are XCMD enabled (working on both windows and unix)
- _mp__: macro procedures (which generate sas code)
- _ms__: macro procedures that will only work with @sasjs/server
- _mv__: macro procedures that will only work in Viya
- _mx__: macros that work on Viya, SAS 9 EBI and SASjs Server
follow verb-noun convention
unix style line endings (lf)
individual lines should be no more than 80 characters long
UTF-8

Header Properties

The Macro Core documentation is created using doxygen. A full list of attributes can be found here but the following are most relevant:

file. This needs to be present in order to be recognised by doxygen.
brief. This is a short (one sentence) description of the macro.
details. A longer description, which can contain doxygen markdown.
param. Name of each input param followed by a description.
return. Explanation of what is returned by the macro.
version. The EARLIEST SAS version in which this macro is known to work.
author. Author name, contact details optional

All macros must be commented in the doxygen format, to enable the online documentation.

Dependencies

SAS code can contain one of two types of dependency - SAS Macros, and SAS Includes. When compiling projects using the SASjs CLI the doxygen header is scanned for @li items under the following headers:

<h4> SAS Macros </h4>
@li mf_nobs.sas
@li mm_assignlib.sas
 
<h4> SAS Includes </h4>
@li somefile.ddl SOMEFREF
@li someprogram.sas FREFTWO

The CLI can then extract all the dependencies and insert as precode (SAS Macros) or in a temp engine fileref (SAS Includes) when creating SAS Jobs and Services (and Tests).

When contributing to this library, it is therefore important to ensure that all dependencies are listed in the header in this format.

Coding Standards

Indentation = 2 spaces. No tabs!
no trailing white space
no invisible characters, other than spaces. If invisibles are needed, use hex literals.
Macro variables should not have the trailing dot (&var not &var.) unless necessary to prevent incorrect resolution
The closing mend statement must contain the macro name, eg mend mymacro; (enforced by the hasMacroNameInMend lint rule).
All macros should be defined with brackets, even if no variables are needed - ie macro x(); not macro x;
Mandatory parameters should be positional, all optional parameters should be keyword (var=) style.
All dataset references must be 2 level (eg work.blah, not blah). This is to avoid contention when options DATASTMTCHK=ALLKEYWORDS is in effect, or the USER library is active.
Avoid naming collisions! All macro variables should be local scope. Use system generated work tables where possible - eg data ; set sashelp.class; run; data &output; set &syslast; run;
Where global macro variables are absolutely necessary, they must use the hard-coded _SASJS_ prefix and be declared in mp_init.sas - see mp_init.sas
The use of quit; for proc sql is essential, to avoid WARNING: You cannot disconnect or terminate session XXXX until the procedure completes. when terminating CAS sessions in Viya.
Use sasjs lint!

General Notes

All macros should be compatible with SAS versions from support level B and above (so currently 9.3 and later). If an earlier version is not supported, then the macro should say as such in the header documentation, and exit gracefully.
It's best to avoid special / non-ASCII characters for compatibility with the widest variety of SAS installations.

Breaking Changes

We are currently on major release v6. The following breaking changes were applied as part of the v6 release:

all macros - the session macro variables were renamed to the _SASJS_ prefix, matching the names sasjs/server sets in its pre-programs. SASJSWORK is now _SASJS_WORK, SASJS_INIT_NUM is _SASJS_INIT_NUM, SASJS_INIT_DTTM is _SASJS_INIT_DTTM, SASJSPROCESSMODE is _SASJS_PROCESSMODE and SASJS_FUNCTIONS is _SASJS_FUNCTIONS. Code that built paths, tests or ignore lists from the old names must read the new ones - core no longer creates the old names and no alias variables are declared. The one name that still answers to its old form is the initialisation marker described in the next point, which is honoured rather than created.
mp_init.sas - the prefix= parameter was removed, and the prefix is hard-coded as _SASJS_. Call mp_init() with no arguments. The "do not initialise" marker is renamed with everything else: set _SASJS_INIT (formerly SASJS_PREFIX) in the autoexec, to any value, to suppress initialisation. SASJS_PREFIX still suppresses initialisation if it is already set, so an existing autoexec keeps working unchanged; core no longer sets it.

Cutting a release

Releases are cut by semantic-release from the commit messages on main, so the squashed PR message is what decides the version:

a breaking change needs a BREAKING CHANGE: footer in the commit body. The ! after the type on its own did not bump the major on this pipeline - the v6 rename merged as feat!: and shipped as a patch release.
no commit that reaches main may carry a skip marker ([skip ci] and friends), including one copied in by the squashed commit list. A skip marker suppresses every workflow for that push, the release job included, and nothing is published.

Star Gazing

If you find this library useful, please leave a star and help us grow our star graph!

Other SAS Repositories

The following repositories are also worth checking out:

Contributors ✨

![All Contributors](https://img.shields.io/badge/all_contributors-16-orange.svg?style=flat-square)

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

_{Allan Bowe} 💼 💻 🖋 📖 🚇 🚧 🧑‍🏫 💬 👀 ⚠️	_rafgag 💻	_{Trevor Moody} 💻	_{Krishna Acondy} 💻 🚇 📝 🖋 🤔 📹	_{Muhammad Saad} 💻 🤔	_{Yury Shkoda} 💻 🚇 📹	_{Mihajlo Medjedovic} 🚇
_kkchandok 🤔	_{Vladislav Parhomchik} ⚠️ 👀	_{Vignesh T.} 🐛	_{Bart Jablonski} 💻	_{Ikko Ashimine} 💻	_{Henrik Forsell} 📖	_{Rud Faden} 💻
_andyjessen 📖	_NAKAYA-Ryo 💻 ⚠️