sasjs-core

@sasjs/core - SAS マクロライブラリ

@sasjs/core は、SAS アプリケーション開発向けの本番品質の SAS マクロを収録した MIT ライセンスのライブラリです。SAS 9（メタデータ）、Viya、SASjs サーバー間で移植可能です。

コーディング規約（必須）

• 1 ファイルにつきマクロは 1 つとし、ファイル名はマクロ名と一致させます（小文字、スペースなし）。
• マクロ定義では括弧を使用します。%macro x(); とし、%macro x; とはしません。
• マクロの 呼び出し の末尾にはセミコロンを付けません。%my_macro() とし、%my_macro(); とはしません。
• スコープの漏洩を防ぐため、すべてのマクロ変数を %local で宣言します。
• fileref を割り当てる場合は常に mf_getuniquefileref を使用し、libref を割り当てる場合は mf_getuniquelibref を使用します（一意の参照をハードコードしたり、独自に生成したりしないでください）。
• インデントはスペース 2 つとし、タブ、末尾の空白、不可視文字は使用しません。行の最大長は 300 文字（厳格な lint 制限）ですが、可能な限り 80 文字以内にしてください。
• すべてのファイルに Doxygen ヘッダーが必要です。

/**
  @file
  @brief One-line description of the macro

  <h4> SAS Macros </h4>
  @li mf_othermacro.sas

  @param [in] paramname Description
  @param [out] outparam Description

  <h4> Related Macros </h4>
  @li mp_related.sas

  @version 9.4
  @author Your Name
**/

フォルダー／プレフィックスの規約

フォルダー	プレフィックス	プラットフォーム
base/	mf_（関数形式）、mp_（プロシージャ形式）	すべてのプラットフォーム
meta/	mm_	SAS 9 メタデータ
metax/	mmx_	SAS 9 メタデータ（OS コマンドに依存）
viya/	mv_	Viya
server/	ms_	SASjs サーバー
xplatform/	mx_	実行時プラットフォーム検出
fcmp/、lua/、ddl/	-	PROC FCMP 関数、LUA ラッパー、DDL

マクロが式で使用可能な値を返す場合は mf_ マクロを使用し、コードやステートメントを生成するプロシージャ形式のマクロには mp_ を使用します。

スイート間のルール： mp_ マクロから mx_ マクロを参照してはいけません。プラットフォームの振り分け（SAS 9／Viya／SASjs サーバー）は mx_ スイートで行い、プラットフォームごとに ms_／mv_／PROC STP に委譲します。mp_ マクロにプラットフォーム固有の動作が必要と思われる場合、そのマクロは xplatform/ に mx_ マクロとして配置してください。

作成前に再利用する

新しいマクロを書く前に、ライブラリに既存のものがないか確認してください。mp_abort（非推奨の mf_abort は後方互換性のために残されています。新しいコードでは使用しないでください）、mf_existds、mf_existvar、mf_existfileref、mf_getuser、mp_jsonout（SAS データセットから _webout 用の JSON を生成）、mp_ds2ddl、mp_hashdataset など、一般的なユーティリティはすでに用意されています。プラットフォーム固有のバリアントは meta/、viya/、server/ にあり、CLI によってコンパイル時に選択されます。

安全な中断

%if/%else ブロック内から %mp_abort を呼び出してはいけません。プロシージャ形式のマクロであるため、中断が有効になる前に、マクロプロセッサがその後のステートメントを実行し続けることがあります。代わりに iftrue= 条件パラメーターを使用してください。

%mp_abort(iftrue= (&syscc ne 0)
  ,mac=&_program
  ,msg=%str(Something went wrong)
)

ループにも同じことが当てはまります。%do %while または %do %to の本体内にある %mp_abort は、ループを実行し続けさせることがあります。中断によって現在のステップがキャンセルされると、マクロプロセッサは次の反復に進みます。進行を待っているものが決して進まない場合、その待機自体が再び中断されるため、ジョブは失敗せずにループし続けます。フラグを設定し、ループ自身のカウンターを停止してから、%end の後に一度だけ中断してください。

%let stuck=0;
%do %while (&left>0);
  /* ...work that may make no progress... */
  %if &nready=0 %then %do;
    %let stuck=1;
    %let left=0;   /* the loop condition, so it cannot re-enter */
  %end;
%end;

%mp_abort(iftrue= (&stuck=1)
  ,mac=&sysmacroname
  ,msg=%str(No progress could be made)
)

目安として、中断は構文ブロックの内部ではなく末尾に置きます。%mp_abort はステップへの要求であり、マクロからの return ではありません。関連するパターンとして、%if <count> >0 %then %do ... %end の中で iftrue=1 を指定して中断する検証処理があります。その場合は、囲んでいるブロックに中断の動作を依存させず、呼び出し時に iftrue= にカウントを渡してください。

%mp_abort が %include ブロック内から呼び出されると、SAS は（たとえば _webout への）正常な終了ができません。インクルードの後（マクロラッパーの外）で %mp_abort(mode=INCLUDE) を呼び出してください。中断ステータスがあるかどうか、work.mp_abort_errds を確認します。

%mp_abort(mode=INCLUDE)

注：マクロ内の %include は %mp_include() で実行してください。これにより _SYSINCLUDEFILEDEVICE インジケーターが設定され、中断データセット（work.mp_abort_errds）が呼び出し元のプログラムに渡されます。

マクロのテスト（必須の規約）

• テスト対象のマクロは必ず %mp_assertscope で囲み、スコープの漏洩を検出します（マクロ変数は %local のままにする必要があります）。

%mp_assertscope(SNAPSHOT)
%mx_foo(args)
%mp_assertscope(COMPARE,
  desc=Test 1: mx_foo does not leak scope,
  outds=work.test_results
)

• アサーションは %mp_assert(iftrue=(...), desc=..., outds=work.test_results) を使って work.test_results に出力します。

Lint とビルド

• 変更のたびに sasjs lint を実行します。合格するまで作業を完了したと見なさないでください。
• package.json のバージョンは絶対に上げないでください（semantic-release が処理します）。
• 生成ファイルを手作業で編集しないでください。all.sas、mc_*.sas、lua/ ラッパー、sasjsbuild/ の出力は CI ビルドによって生成されます。
• Markdown ファイルでは、行を途中で折り返さないでください。段落ごとに 1 行にします。

制限事項

このスキルは @sasjs/core マクロライブラリの静的リファレンスです。コーディング標準、プレフィックスの規約、テストのガイダンスを提供します。SAS コードの実行、シェルコマンドの実行、ファイルシステムへのアクセス、データベースへの接続、ネットワークリクエストの実行は行いません。コード例はすべて参考用であり、ユーザーが SAS セッションに送信する必要があります。