@portll/cobolwork 0.5.0 → 0.7.0

package/lib/hlasm/macro/recovery.mjs

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parsers for the z/OS recovery and dump macros: ESTAE, ESPIE, ABEND, SNAP.
+import { HlasmSyntax } from '../operands.mjs';
+
+// The standard, list and execute forms, authorized keywords included (z/OS 3.1 MVS Programming:
+// Authorized Assembler Services Reference, Volume 2, ESTAE and ESTAEX).
+const ESTAE_KW = new Set(['PARAM', 'XCTL', 'PURGE', 'ASYNCH', 'TERM', 'ASCENV', 'RECORD', 'RELATED', 'MF',
+  'AMODE64', 'BRANCH', 'CANCEL', 'KEY', 'SDWALOC31', 'SPIEOVERRIDE', 'SVEAREA', 'TKNPASS', 'TOKEN']);
+const ESPIE_KW = new Set(['PKM', 'MF']);
+const ABEND_KW = new Set(['REASON', 'DUMPOPT', 'DUMPOPX', 'MF']);
+const SNAP_KW = new Set(['DCB', 'TCB', 'ID', 'SDATA', 'PDATA', 'STORAGE', 'LIST', 'STRHDR', 'SUBPLST', 'DSPSTOR', 'MF']);
+
+function checkKw(kw, allowed, op) {
+  for (const k of kw.keys()) {
+    if (!allowed.has(k)) throw new HlasmSyntax(`${op}: unknown keyword ${k}`);
+  }
+}
+
+function parseEstae(st, ops) {
+  const { positional, keywords } = ops;
+  checkKw(keywords, ESTAE_KW, 'ESTAE');
+  // The list and execute forms (MF=) may leave the exit and the CT or OV to the other form.
+  const remote = keywords.has('MF');
+  if ((positional.length < 1 && !remote) || positional.length > 3) {
+    throw new HlasmSyntax('ESTAE: expected 1 to 3 positional operands');
+  }
+  const exit = positional[0] ?? '';
+  for (let i = 1; i < positional.length; i++) {
+    const p = positional[i].trim().toUpperCase();
+    if (p !== 'CT' && p !== 'OV' && !(remote && p === '')) {
+      throw new HlasmSyntax(`ESTAE: unexpected positional operand ${positional[i]}`);
+    }
+  }
+  return { kind: 'ESTAE', exit, keywords: Object.fromEntries(keywords) };
+}
+
+function parseEspie(st, ops) {
+  const { positional, keywords } = ops;
+  checkKw(keywords, ESPIE_KW, 'ESPIE');
+  if (positional.length < 1) throw new HlasmSyntax('ESPIE: missing action');
+  const action = positional[0].toUpperCase();
+  if (action !== 'SET' && action !== 'RESET' && action !== 'TEST') {
+    throw new HlasmSyntax(`ESPIE: invalid action ${positional[0]}`);
+  }
+  const rest = positional.slice(1);
+  if (action === 'SET') {
+    if (rest.length > 2) throw new HlasmSyntax('ESPIE SET: too many operands');
+  } else if (rest.length > 0) {
+    throw new HlasmSyntax(`ESPIE ${action}: no operands expected`);
+  }
+  return { kind: 'ESPIE', action, operands: rest, keywords: Object.fromEntries(keywords) };
+}
+
+function parseAbend(st, ops) {
+  const { positional, keywords } = ops;
+  checkKw(keywords, ABEND_KW, 'ABEND');
+  if (positional.length < 1 || positional.length > 4) {
+    throw new HlasmSyntax('ABEND: expected 1 to 4 positional operands');
+  }
+  const code = positional[0];
+  let dump = false, step = false;
+  for (let i = 1; i < positional.length; i++) {
+    const p = positional[i].toUpperCase();
+    if (p === '') continue;
+    if (p === 'DUMP') dump = true;
+    else if (p === 'STEP') step = true;
+    else if (p === 'USER' || p === 'SYSTEM') continue;
+    else throw new HlasmSyntax(`ABEND: unexpected positional operand ${positional[i]}`);
+  }
+  return { kind: 'ABEND', code, dump, step, keywords: Object.fromEntries(keywords) };
+}
+
+function parseSnap(st, ops) {
+  const { keywords } = ops;
+  checkKw(keywords, SNAP_KW, 'SNAP');
+  const dcb = keywords.has('DCB') ? keywords.get('DCB') : null;
+  return { kind: 'SNAP', dcb, keywords: Object.fromEntries(keywords) };
+}
+
+export const parsers = {
+  ESTAE: parseEstae,
+  ESPIE: parseEspie,
+  ABEND: parseAbend,
+  SNAP: parseSnap
+};

package/lib/hlasm/macro/storage.mjs

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parser for z/OS virtual storage macros: STORAGE, GETMAIN, and FREEMAIN.
+import { HlasmSyntax, remoteForm } from '../operands.mjs';
+import { MVS38_HIARCHY, MVS38_KEYWORDS, MVS38_STORAGE_MODES, mvs38Form } from '../mvs38.mjs';
+
+const GETMAIN_MODES = new Set(['R', 'RU', 'RC', 'VU', 'VC', 'EU', 'EC', 'LU', 'LC', 'VRC', 'VRU']);
+const FREEMAIN_MODES = new Set(['R', 'RU', 'RC', 'VU', 'VC', 'V', 'EU', 'EC', 'E', 'LU', 'LC', 'L']);
+// The request types that have list and execute forms (MF=L, MF=(E,addr)), and those that take
+// BRANCH=(YES,GLOBAL) (z/OS 3.1 MVS Programming: Assembler Services Reference, Volume 1, and
+// Authorized Assembler Services Reference, Volume 2, GETMAIN and FREEMAIN). The request type is
+// optional in both forms: the execute form takes it from the list it names.
+const GETMAIN_LIST_MODES = new Set(['LC', 'LU', 'VC', 'VU', 'EC', 'EU']);
+const FREEMAIN_LIST_MODES = new Set(['LC', 'LU', 'L', 'VC', 'VU', 'V', 'EC', 'EU', 'E']);
+const GETMAIN_GLOBAL_MODES = new Set(['RC', 'RU', 'VRC', 'VRU']);
+const FREEMAIN_GLOBAL_MODES = new Set(['RC', 'RU']);
+const OWNERS = new Set(['HOME', 'PRIMARY', 'SECONDARY', 'SYSTEM']);
+
+// MF=L or MF=(E,addr), and BRANCH=YES or (YES,GLOBAL), each checked against the request type.
+function remoteAndBranch(macro, mode, keywords, listModes, globalModes) {
+  const out = {};
+  if (keywords.has('MF')) {
+    const { form, list } = remoteForm(keywords.get('MF'), 'MF');
+    if (mode && !listModes.has(mode)) throw new HlasmSyntax(`${macro} ${mode} has no list or execute form`);
+    out.mf = form === 'L' ? 'L' : { form: 'E', list };
+  }
+  if (keywords.has('BRANCH')) {
+    const v = keywords.get('BRANCH').replace(/\s+/g, '').toUpperCase();
+    if (v === '(YES,GLOBAL)') {
+      if (!globalModes.has(mode)) throw new HlasmSyntax(`${macro} takes BRANCH=(YES,GLOBAL) only with ${[...globalModes].join(', ')}`);
+      out.branch = 'GLOBAL';
+    } else if (v === 'YES' || v === '(YES)') {
+      out.branch = 'YES';
+    } else {
+      throw new HlasmSyntax(`${macro} BRANCH= value ${keywords.get('BRANCH')} is not YES or (YES,GLOBAL)`);
+    }
+  }
+  return out;
+}
+
+function getKeyword(keywords, key) {
+  const val = keywords.get(key);
+  return val === undefined ? null : val;
+}
+
+function parseStorage(st, ops) {
+  const { positional, keywords } = ops;
+  if (positional.length < 1) {
+    throw new HlasmSyntax('STORAGE requires a request type (OBTAIN or RELEASE)');
+  }
+  const request = positional[0].trim().toUpperCase();
+  if (request !== 'OBTAIN' && request !== 'RELEASE') {
+    throw new HlasmSyntax(`STORAGE request must be OBTAIN or RELEASE, got ${positional[0]}`);
+  }
+  if (positional.length > 1) {
+    throw new HlasmSyntax(`STORAGE does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LENGTH', 'ADDR', 'INADDR', 'SP', 'BNDRY', 'CONTBDY', 'STARTBDY', 'KEY', 'CALLRKY', 'LOC', 'LINKAGE', 'RTCD', 'COND', 'CHECKZERO', 'BACK', 'FIX', 'EXECUTABLE', 'RELATED']);
+  for (const key of keywords.keys()) {
+    if (!allowed.has(key)) {
+      throw new HlasmSyntax(`STORAGE does not accept keyword ${key}`);
+    }
+  }
+
+  return {
+    kind: 'STORAGE',
+    request,
+    length: getKeyword(keywords, 'LENGTH'),
+    address: getKeyword(keywords, 'ADDR'),
+    subpool: getKeyword(keywords, 'SP'),
+    key: getKeyword(keywords, 'KEY'),
+    cond: getKeyword(keywords, 'COND'),
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+function parseGetmain(st, ops, opts) {
+  const { positional, keywords } = ops;
+  const mode = (positional[0] ?? '').trim().toUpperCase() || null;
+  if (!mode && !keywords.has('MF')) {
+    throw new HlasmSyntax('GETMAIN requires a request type');
+  }
+  const legacy = {};
+  if (mode && MVS38_STORAGE_MODES.has(mode)) {
+    mvs38Form(opts, legacy, 'GETMAIN', mode);
+  } else if (mode && !GETMAIN_MODES.has(mode)) {
+    throw new HlasmSyntax(`GETMAIN request type must be one of ${[...GETMAIN_MODES].join(', ')}, got ${positional[0]}`);
+  }
+  if (positional.slice(1).some((p) => p.trim() !== '')) {
+    throw new HlasmSyntax(`GETMAIN does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LA', 'LV', 'A', 'SP', 'BNDRY', 'CONTBDY', 'STARTBDY', 'KEY', 'LOC', 'INADDR', 'CHECKZERO', 'RELATED', 'MF', 'BRANCH', 'OWNER']);
+  for (const key of keywords.keys()) {
+    if (MVS38_KEYWORDS.GETMAIN.has(key)) {
+      mvs38Form(opts, legacy, 'GETMAIN', `${key}=${keywords.get(key).trim()}`);
+      if (!MVS38_HIARCHY.test(keywords.get(key).trim())) throw new HlasmSyntax('GETMAIN HIARCHY must be 0 or 1');
+    } else if (!allowed.has(key)) {
+      throw new HlasmSyntax(`GETMAIN does not accept keyword ${key}`);
+    }
+  }
+  if (keywords.has('OWNER') && !OWNERS.has(keywords.get('OWNER').trim().toUpperCase())) {
+    throw new HlasmSyntax(`GETMAIN OWNER must be one of ${[...OWNERS].join(', ')}`);
+  }
+  const extra = remoteAndBranch('GETMAIN', mode, keywords, GETMAIN_LIST_MODES, GETMAIN_GLOBAL_MODES);
+
+  const length = getKeyword(keywords, 'LV') ?? getKeyword(keywords, 'LA');
+  const address = getKeyword(keywords, 'A');
+  const subpool = getKeyword(keywords, 'SP');
+
+  return {
+    kind: 'GETMAIN',
+    ...legacy,
+    mode,
+    length,
+    address,
+    subpool,
+    ...extra,
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+function parseFreemain(st, ops, opts) {
+  const { positional, keywords } = ops;
+  const mode = (positional[0] ?? '').trim().toUpperCase() || null;
+  if (!mode && !keywords.has('MF')) {
+    throw new HlasmSyntax('FREEMAIN requires a request type');
+  }
+  const legacy = {};
+  if (mode && MVS38_STORAGE_MODES.has(mode)) {
+    mvs38Form(opts, legacy, 'FREEMAIN', mode);
+  } else if (mode && !FREEMAIN_MODES.has(mode)) {
+    throw new HlasmSyntax(`FREEMAIN request type must be one of ${[...FREEMAIN_MODES].join(', ')}, got ${positional[0]}`);
+  }
+  if (positional.slice(1).some((p) => p.trim() !== '')) {
+    throw new HlasmSyntax(`FREEMAIN does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LA', 'LV', 'A', 'SP', 'KEY', 'RELATED', 'MF', 'BRANCH']);
+  for (const key of keywords.keys()) {
+    if (!allowed.has(key)) {
+      throw new HlasmSyntax(`FREEMAIN does not accept keyword ${key}`);
+    }
+  }
+  const extra = remoteAndBranch('FREEMAIN', mode, keywords, FREEMAIN_LIST_MODES, FREEMAIN_GLOBAL_MODES);
+
+  const length = getKeyword(keywords, 'LV') ?? getKeyword(keywords, 'LA');
+  const address = getKeyword(keywords, 'A');
+  const subpool = getKeyword(keywords, 'SP');
+
+  return {
+    kind: 'FREEMAIN',
+    ...legacy,
+    mode,
+    length,
+    address,
+    subpool,
+    ...extra,
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+export const parsers = {
+  STORAGE: parseStorage,
+  GETMAIN: parseGetmain,
+  FREEMAIN: parseFreemain
+};

package/lib/hlasm/macro/structured.mjs

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parsers for the HLASM Toolkit structured programming macros (IF, DO, SELECT, etc.).
+import { HlasmSyntax, NAME, splitOperands } from '../operands.mjs';
+
+const CC_MNEMONICS = new Set(['H', 'L', 'E', 'Z', 'O', 'M', 'P', 'NH', 'NL', 'NE', 'NZ', 'NO', 'NM', 'NP', 'EQ', 'GT', 'LT', 'GE', 'LE',
+  'HE', 'LE', 'NHE', 'NLE']);
+const CONNECTORS = new Set(['AND', 'OR', 'ANDIF', 'ORIF']);
+
+// (Z) or (8): a condition-code mnemonic or a mask; (CLI,0(R1),EQ,C'A') or (LTR,R15,R15,NZ): an
+// instruction and its operands with the condition among them.
+function parseCondition(text) {
+  const t = text.trim();
+  if (!t.startsWith('(') || !t.endsWith(')')) {
+    if (CC_MNEMONICS.has(t.toUpperCase())) return t;
+    throw new HlasmSyntax(`unrecognised condition: ${t}`);
+  }
+  const parts = splitOperands(t.slice(1, -1)).map((x) => x.trim());
+  if (parts.length === 1) {
+    if (CC_MNEMONICS.has(parts[0].toUpperCase()) || /^(?:CC=)?(?:[1-9]|1[0-4])$/i.test(parts[0])) return t;
+    throw new HlasmSyntax(`unrecognised condition: ${t}`);
+  }
+  if (!NAME.test(parts[0])) throw new HlasmSyntax(`condition ${t} does not start with an instruction`);
+  if (!parts.slice(1).some((x) => CC_MNEMONICS.has(x.toUpperCase()))) throw new HlasmSyntax(`unrecognised condition: ${t} names no condition mnemonic`);
+  return t;
+}
+
+// Conditions joined by AND, OR, ANDIF and ORIF, each operand of the macro one condition or joiner.
+function parsePredicate(positional) {
+  const items = positional.map((x) => x.trim()).filter(Boolean);
+  if (!items.length) throw new HlasmSyntax('requires a predicate');
+  const conditions = [];
+  const joins = [];
+  items.forEach((x, i) => {
+    if (i % 2) {
+      if (!CONNECTORS.has(x.toUpperCase())) throw new HlasmSyntax(`expected AND, OR, ANDIF or ORIF, not ${x}`);
+      joins.push(x.toUpperCase());
+    } else conditions.push(parseCondition(x));
+  });
+  if (joins.length === conditions.length) throw new HlasmSyntax('a predicate cannot end with a joiner');
+  return { conditions, joins };
+}
+
+function parseIF(st, ops) {
+  const { conditions, joins } = parsePredicate(ops.positional);
+  return { kind: 'IF', conditions, joins, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseELSEIF(st, ops) {
+  const { conditions, joins } = parsePredicate(ops.positional);
+  return { kind: 'ELSEIF', conditions, joins, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseDO(st, ops) {
+  const pos = ops.positional[0] || '';
+  const kw = ops.keywords;
+  let form = 'SIMPLE';
+  if (pos) {
+    const upper = pos.toUpperCase();
+    if (upper === 'ONCE') form = 'ONCE';
+    else if (upper === 'INF') form = 'INF';
+    else if (upper === 'BXH' || upper === 'BXLE' || upper === 'BCT' || upper === 'BCTR') form = 'COUNT';
+    else if (pos.startsWith('(')) form = 'COUNT';
+    else if (upper === 'WHILE' || upper === 'UNTIL') {
+      if (kw.has(upper)) form = upper;
+      else throw new HlasmSyntax(`unknown DO positional operand: ${pos}`);
+    }
+    else throw new HlasmSyntax(`unknown DO positional operand: ${pos}`);
+  }
+  if (kw.has('FROM')) form = 'FROM';
+  else if (kw.has('WHILE')) form = 'WHILE';
+  else if (kw.has('UNTIL')) form = 'UNTIL';
+  return { kind: 'DO', form, keywords: Object.fromEntries(kw) };
+}
+
+function parseDOEXIT(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos) {
+    parseCondition(pos);
+  }
+  return { kind: 'DOEXIT', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseITERATE(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos) {
+    if (!NAME.test(pos)) throw new HlasmSyntax(`ITERATE operand must be a label: ${pos}`);
+  }
+  return { kind: 'ITERATE', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseASMLEAVE(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos && !NAME.test(pos)) throw new HlasmSyntax(`ASMLEAVE operand must be a label: ${pos}`);
+  return { kind: 'ASMLEAVE', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+// SELECT alone, or SELECT instruction,operand,condition: CLI,0(R6),EQ compares each WHEN's values.
+function parseSELECT(st, ops) {
+  const parts = ops.positional.map((x) => x.trim()).filter(Boolean);
+  if (parts.length && (parts.length < 3 || !CC_MNEMONICS.has(parts[2].toUpperCase()))) throw new HlasmSyntax(`SELECT ${parts.join(',')} is not instruction,operand,condition`);
+  return { kind: 'SELECT', operands: [parts.join(',')].filter(Boolean), keywords: Object.fromEntries(ops.keywords) };
+}
+
+// WHEN takes a condition, or after a comparing SELECT a parenthesised list of values: (X'20'), (1,5,13).
+function parseWHEN(st, ops) {
+  const parts = ops.positional.map((x) => x.trim()).filter(Boolean);
+  if (!parts.length) throw new HlasmSyntax('WHEN needs a condition or values');
+  for (const p of parts) if (!(p.startsWith('(') && p.endsWith(')')) && !CONNECTORS.has(p.toUpperCase())) throw new HlasmSyntax(`WHEN operand ${p} is not in parentheses`);
+  return { kind: 'WHEN', operands: parts, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseNoOperand(st, ops) {
+  if (ops.positional.some((p) => p.trim() !== '')) throw new HlasmSyntax(`${st.operation} does not accept positional operands`);
+  return { kind: st.operation, keywords: Object.fromEntries(ops.keywords) };
+}
+
+export const parsers = {
+  IF: parseIF,
+  ELSEIF: parseELSEIF,
+  ELSE: parseNoOperand,
+  ENDIF: parseNoOperand,
+  DO: parseDO,
+  ENDDO: parseNoOperand,
+  DOEXIT: parseDOEXIT,
+  ITERATE: parseITERATE,
+  ASMLEAVE: parseASMLEAVE,
+  SELECT: parseSELECT,
+  WHEN: parseWHEN,
+  OTHRWISE: parseNoOperand,
+  ENDSEL: parseNoOperand
+};

package/lib/hlasm/model.mjs

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Macro prototypes, model statements and open-code statements that hold variable symbols. A model
+// statement is read as the statement it is: each variable symbol in its operands stands in for an
+// ordinary symbol, or for the letter X inside a quoted string, and the result goes to the parser for
+// its operation. An operation that is itself a variable symbol is decided at expansion and refused.
+import { HlasmSyntax, NAME, splitOperands } from './operands.mjs';
+import { parseHlasmStatement } from './read.mjs';
+
+const VARIABLE = /^&[A-Z$#@_][A-Z0-9$#@_]*$/i;
+// System variable symbols whose value has a fixed length, which is all a constant's length needs.
+// https://www.ibm.com/docs/en/hla-and-tf/1.6.0?topic=symbols-sysdate-system-variable-symbol
+const FIXED_LENGTH = { '&SYSDATE': 8, '&SYSDATC': 8, '&SYSTIME': 5 };
+
+// &NAME, with an optional subscript (&A(1), &A(&I+1)) and an optional period that joins it to what
+// follows. && is one ampersand, not a variable symbol. Inside a quoted string a variable becomes as
+// many X as its value has characters when that is fixed, and one X otherwise, counted as unsized.
+// Outside one it becomes what `standIn` gives for the nth such variable.
+function substitute(text, standIn = (n) => `VAR${n}`) {
+  let out = '';
+  let quoted = false;
+  let n = 0;
+  let unsized = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "'") { quoted = !quoted; out += c; continue; }
+    if (c !== '&') { out += c; continue; }
+    if (text[i + 1] === '&') { out += '&&'; i++; continue; }
+    const m = /^&[A-Z$#@_][A-Z0-9$#@_]*/i.exec(text.slice(i));
+    if (!m) { out += c; continue; }
+    i += m[0].length;
+    if (text[i] === '(') {
+      let depth = 0;
+      for (; i < text.length; i++) { if (text[i] === '(') depth++; else if (text[i] === ')' && --depth === 0) { i++; break; } }
+    }
+    if (text[i] === '.') i++;
+    i--;
+    const fixed = FIXED_LENGTH[m[0].toUpperCase()];
+    if (quoted && !fixed) unsized++;
+    out += quoted ? 'X'.repeat(fixed || 1) : standIn(++n);
+  }
+  return { text: out, unsized, variables: n };
+}
+
+// A variable outside quotes stands in for a symbol. When no statement reads that way, one variable
+// at a time stands in for a quoted string (DC C&MSG, LA &R,=C&LIST), a number (DC &T.F'0') or an
+// option (PRINT &GEN, AMODE &MODE), as a caller's value may be, and then all of them do; past
+// eight variables only the uniform readings are tried.
+const SYMBOL = (n) => `VAR${n}`;
+const VALUES = ["'X'", '1', 'ON', 'ANY'];
+function* standIns(variables) {
+  yield SYMBOL;
+  if (variables <= 8) {
+    for (let j = 1; j <= variables; j++) for (const value of VALUES) yield (n) => (n === j ? value : SYMBOL(n));
+  }
+  for (const value of VALUES) yield () => value;
+}
+
+function read(kind, st) {
+  if (/&[A-Z$#@_]/i.test(st.operation)) throw new HlasmSyntax(`the operation ${st.operation} is decided when the macro is expanded`);
+  // A name built from variable symbols (&NAME, KFBR&SYSNDX) stands in as an ordinary symbol, as the
+  // operands do; one still holding an ampersand would send the statement back here.
+  const named = st.name && !st.name.startsWith('.') ? substitute(st.name).text : null;
+  const name = named && !named.includes('&') ? named : null;
+  const { variables } = substitute(st.field || '');
+  let first = null;
+  for (const standIn of standIns(variables)) {
+    const { text, unsized } = substitute(st.field || '', standIn);
+    const res = parseHlasmStatement({ ...st, name, field: text, inMacro: false, prototype: false });
+    // exact: the symbol reading, with no quoted string holding a variable of unknown length, so the
+    // node's lengths are the source's.
+    if (res.status === 'parsed') return { kind, as: res.kind, node: res.node, exact: standIn === SYMBOL && unsized === 0 };
+    first ||= res;
+    if (!variables) break;
+  }
+  if (first.status === 'unbuilt') throw new HlasmSyntax(`no parser yet for ${first.kind}`);
+  throw new HlasmSyntax(first.reason || `${first.kind} ${first.status}`);
+}
+
+function prototype(st) {
+  if (st.name && !VARIABLE.test(st.name)) throw new HlasmSyntax(`a prototype's name field is a variable symbol or empty, not ${st.name}`);
+  if (!NAME.test(st.operation)) throw new HlasmSyntax(`${st.operation} is not a macro name`);
+  const positional = [];
+  const keywords = {};
+  for (const part of splitOperands(st.field || '')) {
+    const m = /^(&[A-Z$#@_][A-Z0-9$#@_]*)=([\s\S]*)$/i.exec(part);
+    if (m) keywords[m[1].toUpperCase()] = m[2];
+    else if (VARIABLE.test(part)) positional.push(part.toUpperCase());
+    else if (part !== '') throw new HlasmSyntax(`prototype operand ${part} is not a variable symbol`);
+  }
+  return { kind: 'PROTOTYPE', macro: st.operation, label: st.name || null, positional, keywords };
+}
+
+export const parsers = {
+  PROTOTYPE: prototype,
+  MODEL: (st) => read('MODEL', st),
+  SUBSTITUTED: (st) => read('SUBSTITUTED', st),
+};

package/lib/hlasm/mvs38.mjs

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Operands the MVS 3.8 system macros take that z/OS 3.1's documentation does not list, with the
+// meaning those macros give them (MVS 3.8j SYS1.MACLIB, public domain: MODESET, GETMAIN, FREEMAIN,
+// ATTACH, DCB). Read by default; parseHlasmStatement(st, { mvs38: false }) refuses them.
+import { HlasmSyntax } from './operands.mjs';
+
+// MODESET EXTKEY= names and the PSW key each sets.
+export const MVS38_EXTKEYS = new Map([
+  ['SUPR', 0], ['RSM', 0], ['VSM', 0], ['SRM', 0],
+  ['SCHED', 1], ['JES', 1], ['HASP', 1],
+  ['DATAMGT', 5],
+  ['TCAM', 6], ['VTAM', 6],
+]);
+
+// GETMAIN and FREEMAIN P: a request for a subpool, register 0 holding its number in the high byte.
+export const MVS38_STORAGE_MODES = new Set(['P']);
+
+// HIARCHY= chose a storage hierarchy (0 or 1); MVS/XA removed hierarchies.
+export const MVS38_HIARCHY = /^[01]$/;
+
+export const MVS38_KEYWORDS = {
+  GETMAIN: new Set(['HIARCHY']),
+  ATTACH: new Set(['HIARCHY', 'JSCB']),
+  DCB: new Set(['PGFX', 'AERR']),
+};
+
+export const mvs38Enabled = (opts) => opts?.mvs38 !== false;
+
+export const systemKeyExtkeys = (opts) => (mvs38Enabled(opts) ? [...MVS38_EXTKEYS].filter(([, key]) => key > 0) : []);
+
+export const keyZeroExtkeys = (opts) => (mvs38Enabled(opts) ? [...MVS38_EXTKEYS].filter(([, key]) => key === 0).map(([name]) => name) : []);
+
+// Marks an MVS 3.8 form on the node it is read into, or refuses it when the option is off.
+export function mvs38Form(opts, node, macro, form) {
+  if (!mvs38Enabled(opts)) throw new HlasmSyntax(`${macro}: ${form} is an MVS 3.8 form`);
+  (node.mvs38 ||= []).push(form);
+}
+
+// BTAM's READ and WRITE types (IHBRDWRT); BTAM is not in z/OS. READ T alone is its execute form.
+export const MVS38_BTAM_TYPES = {
+  READ: new Set(['T', 'TB', 'TI', 'TT', 'TV', 'TP', 'TS', 'TQ', 'TC', 'TE', 'TM', 'TIR', 'TTR', 'TVR', 'TPR', 'TTA', 'TTL', 'TPL', 'TIQ', 'TRV', 'TCW', 'TBR', 'TMP', 'TBP', 'TQM']),
+  WRITE: new Set(['TB', 'TI', 'TT', 'TV', 'TA', 'TS', 'TN', 'TR', 'TL', 'TD', 'TQ', 'TW', 'TC', 'TIR', 'TTR', 'TVR', 'TLR', 'TIO', 'TIV', 'TCO', 'TTV', 'TUS', 'TIX', 'TVO', 'TTX', 'TSR', 'TIE', 'TTE', 'TRM', 'TSA', 'TSF', 'TIVX', 'TTVX', 'TIXR', 'TTXR']),
+};
+
+// VTAM's basic-mode READ and WRITE, given RPL=, and the RPL fields they may set; z/OS
+// Communications Server keeps SEND and RECEIVE and has no READ or WRITE.
+export const MVS38_VTAM_RPL_KEYWORDS = new Set(['RPL', 'ACB', 'AREA', 'AREALEN', 'RECLEN', 'AAREA', 'AAREALN', 'ARECLEN', 'ECB', 'EXIT', 'OPTCD', 'ARG', 'BRANCH']);

package/lib/hlasm/operands.mjs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// What every HLASM statement parser shares: the refusal it throws, and the split of an operand field
+// into operands at the commas outside parentheses and quotes.
+
+export class HlasmSyntax extends Error {
+  constructor(message) { super(message); this.name = 'HlasmSyntax'; }
+}
+
+export const NAME = /^[A-Z$#@_][A-Z0-9$#@_]{0,62}$/i;
+export const ATTRIBUTES = 'LTSIKNDO';
+
+// A quote after an attribute letter that stands alone, before a name, a variable symbol, * or a
+// literal, is an attribute reference (L'FIELD), not the start of a string. The card reader
+// (lib/bms.mjs) folds continuations by the same rule.
+export const isAttributeQuote = (text, i) => i > 0 && ATTRIBUTES.includes(text[i - 1].toUpperCase())
+  && !/[A-Z0-9$#@_&]/i.test(text[i - 2] || '') && /[A-Z$#@_&*=]/i.test(text[i + 1] || '');
+
+export function splitOperands(field) {
+  const out = [];
+  let depth = 0, quoted = false, start = 0;
+  for (let i = 0; i < field.length; i++) {
+    const c = field[i];
+    if (quoted) {
+      if (c === "'") { if (field[i + 1] === "'") i++; else quoted = false; }
+      continue;
+    }
+    if (c === "'") { if (!isAttributeQuote(field, i)) quoted = true; }
+    else if (c === '(') depth++;
+    else if (c === ')') { if (--depth < 0) throw new HlasmSyntax(`a closing parenthesis has no opening one at column ${i + 1} of the operands`); }
+    else if (c === ',' && depth === 0) { out.push(field.slice(start, i)); start = i + 1; }
+  }
+  if (quoted) throw new HlasmSyntax('a quoted string in the operands is not closed');
+  if (depth) throw new HlasmSyntax('a parenthesis in the operands is not closed');
+  out.push(field.slice(start));
+  return field === '' ? [] : out;
+}
+
+// Positional operands until the first KEY=VALUE, as a macro call is written. A literal (=F'1') is a
+// positional operand, not a keyword with an empty name.
+export function macroOperands(field) {
+  const positional = [];
+  const keywords = new Map();
+  for (const part of splitOperands(field)) {
+    const m = /^([A-Z$#@_][A-Z0-9$#@_]*)=([\s\S]*)$/i.exec(part);
+    if (m) keywords.set(m[1].toUpperCase(), m[2]);
+    else positional.push(part);
+  }
+  return { positional, keywords };
+}
+
+// A macro's list form (MF=L, SF=L) builds only its parameter list; its execute form ((E,addr))
+// runs the service on a list built elsewhere, at addr.
+export function remoteForm(value, keyword) {
+  const t = String(value).trim();
+  if (/^L$/i.test(t)) return { form: 'L', list: null };
+  const m = /^\(\s*E\s*,\s*(\S.*?)\s*\)$/i.exec(t);
+  if (m) return { form: 'E', list: m[1] };
+  throw new HlasmSyntax(`${keyword}= value ${t} is not L or (E,addr)`);
+}

package/lib/hlasm/optable.mjs

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// HLASM's OPTABLE option: which operation code table the assembler reads machine instructions from.
+// A mnemonic outside the chosen table is no instruction, so a macro of that name is called instead.
+import { readFileSync, existsSync } from 'node:fs';
+
+const TABLE = new URL('../../rules/hlasm-optables.json', import.meta.url);
+const T = existsSync(TABLE) ? JSON.parse(readFileSync(TABLE, 'utf8')) : { levels: [], synonyms: {}, machines: {}, mnemonics: {} };
+const RANK = new Map(T.levels.map((level, i) => [level, i]));
+
+// An OPTABLE or MACHINE suboption as written, to the table's level; null when it names none.
+export function optableLevel(name, { machine = false } = {}) {
+  const n = String(name || '').trim().toUpperCase();
+  if (machine) return T.machines[n] ?? null;
+  if (n === 'UNI') return 'UNI';
+  return RANK.has(n) ? n : T.synonyms[n] ?? null;
+}
+
+// "UNI,DOS-370": UNI, a level, a level and later (X-), or a range (X-Y).
+function covers(ranges, level) {
+  return ranges.split(',').some((part) => {
+    if (part === level) return true;
+    if (level === 'UNI') return false;
+    const m = /^([^-]+)-([^-]*)$/.exec(part);
+    if (!m || !RANK.has(m[1])) return false;
+    const at = RANK.get(level);
+    return at >= RANK.get(m[1]) && (m[2] === '' || at <= RANK.get(m[2]));
+  });
+}
+
+// Whether the table at this level (UNI when none is given) holds the mnemonic; one the table does not
+// list is taken as held.
+const excluded = new Map();
+export function inOptable(mnemonic, level) {
+  const at = level ?? 'UNI';
+  if (!excluded.has(at)) excluded.set(at, new Set(Object.entries(T.mnemonics).filter(([, ranges]) => !ranges.some((r) => covers(r, at))).map(([m]) => m)));
+  return !excluded.get(at).has(mnemonic);
+}
+
+// OPTABLE or MACHINE in an option string (PARM, *PROCESS), to a level; OVERRIDE(...) says it is forced.
+export function optableIn(options) {
+  const text = String(options || '').toUpperCase();
+  const override = /OVERRIDE\(([^)]*(?:\([^)]*\)[^)]*)*)\)/.exec(text)?.[1] ?? '';
+  const read = (s) => {
+    const o = /\bOPTABLE\(\s*([A-Z0-9]+)/.exec(s);
+    if (o) return optableLevel(o[1]);
+    const m = /\bMACHINE\(\s*([A-Z0-9-]+)/.exec(s);
+    return m ? optableLevel(m[1], { machine: true }) : null;
+  };
+  const forced = read(override);
+  return forced ? { level: forced, override: true } : read(text) ? { level: read(text), override: false } : null;
+}
+
+// The *PROCESS statements that open a source file name its options.
+export function processOptions(text) {
+  const out = [];
+  for (const line of String(text).replace(/\r\n?/g, '\n').split('\n')) {
+    if (!/^\*PROCESS\s/i.test(line)) break;
+    out.push(line.slice(8, 71).trim());
+  }
+  return out.join(',');
+}