Internal Developing Model 204 from WSL

Internal use only. This page is intentionally not linked from the main page or any category. Do not link it from customer-facing pages.

Developing Model 204 from WSL or macOS (internal)

The @rocket/m204-tools package makes it possible to edit, assemble, link, patch, and test Model 204 from WSL or macOS. The main commands are:

Command	Purpose
make204	Incrementally assemble Model 204 and link CMS and z/OS modules
emu204	Run the real linked Model 204 module on the workstation
testM204Qa	Start Model 204 under emu204 and run a QA smoke test
prezap	Create the header for a new maintenance ZAP
scanzap	Find the next available local and PTCH$ patch offsets
bldzap	Compare two object decks and generate VER/REP statements
putmod	Upload a linked CMS module and map for mainframe testing
putmodzos	Upload the z/OS object deck that the z/OS binder uses to create the test load module

This page describes the Model 204 8.0 workflow. Release 8.0 is under ZAP maintenance, so the baseline objects and the ZAP objects must be kept separate.

Workstation setup

The published tools support:

• WSL 2 or another x86-64 Linux environment; and
• macOS on Apple silicon.

The npm package does not currently include an Intel macOS emulator binary.

WSL

Use WSL 2 with a current Ubuntu distribution. Keep the Git repositories in the Linux filesystem, for example under ~/gitm204 and ~/m204-80, rather than under /mnt/c. Linux builds and Git operations are faster there and do not inherit Windows filename and permission behavior.

Install Git and Node.js/npm, and make sure npm has access to Rocket's registry.

macOS

Install Git and Node.js/npm. The command-line developer tools supplied by Xcode are sufficient for Git. Homebrew or nvm can be used for Node.js; use one installation consistently so an old global npm prefix does not remain earlier on PATH.

The CMS and z/OS passwords are stored in the macOS Keychain. No Linux keyring setup is needed.

The upload commands invoke an ftp command-line client. Modern macOS does not supply one, so verify command -v ftp. If it is absent, install a compatible client such as tnftp with Homebrew.

Install the tools

On either platform, install or update the complete tool suite:

npm install -g @rocket/m204-tools@latest
hash -r

The single package supplies make204, hlasm, cmslink, zapobj, emu204, testM204Qa, the ZAP utilities, and the Imagine JavaScript runtime.

Verify the installation:

make204 --help
emu204 --help
testM204Qa --help
type -a make204 emu204 testM204Qa prezap scanzap

All commands should normally come from the same npm installation. If the shell finds a mixture of commands under /usr/local/bin, an nvm directory, a Homebrew prefix, or another npm prefix, remove or update the obsolete installation. A split installation can make make204 use one package version while emu204 uses another.

If emu204 reports that @rocket/em204-linux-x64 is not installed, reinstall @rocket/m204-tools without --no-optional or --ignore-scripts.

Repositories

The two repositories have different purposes:

• ~/gitm204 contains the build tools, assembler, linker, emulator, and their tests.
• ~/m204-80 contains the Model 204 source and is where normal Model 204 coding and ZAP work is done.

The Model 204 directory name matters. It must end in the two-digit release, such as m204-80, because the tools derive the release and CMS disk names from it.

Before beginning a change:

cd ~/m204-80
git status --short --branch
git switch master
git pull

Do not discard uncommitted work. Resolve or preserve it before changing branches.

First build and CMS libraries

From the Model 204 repository root:

cd ~/m204-80
make204 --no-zap

On the first build, make204 downloads the macro and object libraries it needs from CMS. You need a CMS userid with FTP access. The userid defaults from $USER, truncated to eight characters. If the workstation login name is not the CMS userid, set M204_FTPVM_USERID in the shell.

On WSL, the tools can offer to install and configure gnome-keyring and libsecret-tools so the CMS password can be saved. If the keyring is not configured, the tools can still run but may ask for the password again. On macOS, they use the system Keychain.

Library fetches are recorded in .m204libs. If a fetch was interrupted, make204 recognizes the half-fetched library and downloads it again. A large number of unknown assembler operations usually means that the macro library is incomplete.

Normal coding and build cycle

Model 204 assembler source, copy members, macros, and ZAP files are under src/. Build outputs are ignored by Git:

Directory	Contents
obj/	Baseline object decks and linked modules
lst/	Baseline assembly listings
ref/	Baseline dependency information
zapobj/	ZAP-build objects, per-module ZAPs, and linked modules
zaplst/	ZAP-build listings
zapref/	ZAP-build dependency information

A typical edit/build loop is:

cd ~/m204-80

# Edit src/MODULE.ASSEMBLE, a COPY member, or a MACRO.

make204 MODULE       # assemble the named source and link if needed
make204              # assemble everything that changed and link if needed

Useful options:

Option	Meaning
--force	Reassemble everything, ignoring dependency timestamps
--link	Force a link even when no object appears to have changed
--no-link	Assemble without linking
--stdout	Show assembler output
--errLines=N	Show the first N diagnostic lines for each failed module
--errMax=0	Continue after assembly failures instead of stopping at the first one
--clear	Empty the selected build directories before building

make204 MODULE names an input source, not necessarily an output object. For example, one input may produce more than one output module.

Review the corresponding listing after an assembly:

less lst/MODULE.LST80

In the 8.0 repository, a bare make204 defaults to ZAP mode because m204.jsonc contains "zap": true. Use --no-zap explicitly when you intend to build the baseline in obj/.

Running and testing under emu204

emu204 runs the real z/OS Model 204 module locally. It is not a source-level reimplementation of Model 204.

Automated smoke test

The simplest supported baseline smoke test is:

cd ~/m204-80
make204 --no-zap
testM204Qa --tree="$HOME/m204-80"

testM204Qa starts obj/M204ONLN.MODULE under emu204 and runs the UL*, REGEX*, and CMD* QA patterns. It takes roughly half a minute. Results are written under m204qa/out/ beside the Model 204 tree.

Run the make204 --no-zap command above only when intentionally building the baseline, normally on unmodified master. On a ZAP branch it would replace the baseline objects with the changed source and destroy the comparison that generates the ZAP.

Do not judge this run by the emulator return code. Tests deliberately provoke Model 204 errors, so a successful run can have a nonzero Model 204 return code. testM204Qa reads QARUN's output and checks that every pattern finished, ran tests, reported no failures, and produced no SNAP.

Building an emu204 case

For an interactive or specialized run, create a directory containing an emu204.jsonc configuration, CCAIN, and any files used by the run:

mkdir -p ~/em204-cases/mycase/{files,out}
cd ~/em204-cases/mycase
vi emu204.jsonc
vi ccain.txt
emu204

With no --config, emu204 reads emu204.jsonc in the current directory. Relative paths in the configuration are resolved against the directory containing the configuration, not against the shell's current directory. This makes the case directory movable.

The complete reference is:

emu204 --help
emu204 --help=config
emu204 --help=em

A useful starting configuration is:

{
  "module": "/home/user/m204-80/obj/M204ONLN.MODULE",
  "lst": "/home/user/m204-80/lst",
  "cpuid": "FF379B789175",
  "jobName": "EMU204ON",
  "parm": "SYSOPT=X'A0',LIBUFF=3072,LOBUFF=7168,SIRFUNC=X'01',SIRTUNE=0",
  "storage": "2G",

  "dd": {
    "SITEPARM": {"path": "siteparm.txt"},
    "CCAIN": {"path": "ccain.txt"},
    "CCAPRINT": {"path": "out/ccaprint.txt"},
    "CCAAUDIT": {"path": "out/ccaaudit.txt"},
    "CCASNAP": {
      "path": "out/ccasnap.txt",
      "sequence": true,
      "cc": true
    },
    "CCASTAT": {
      "path": "out/ccastat.binary",
      "blocked": true
    }
  },

  "ddDirs": [
    {"path": "files", "suffix": "M204FILE", "m204file": true}
  ]
}

Change the module path to zapobj/M204ONLN.MODULE when the purpose of the case is to test a ZAP-linked module.

Identity and authorization

cpuid is the twelve hexadecimal digits reported by the emulated machine. Model 204 checks it against the authorization in the module, so it must be a CPU ID authorized by the development key.

jobName becomes the name in the TIOT header. A bare LOGIN is trusted as this user, so the name must exist in CCASTAT. If the configured CCASTAT path does not exist, emu204 creates a minimal table containing the configured job name. This is normally simpler than copying a password table from a mainframe.

If a real CCASTAT is used, download it with FTP block-mode framing intact and specify "blocked": true. A plain binary byte stream cannot preserve the record boundaries of its undefined-format records.

EXEC PARM, SYSOPT, and CCAIN

The configuration's parm value is the EXEC PARM presented when Model 204 is entered. It is where user-zero parameters such as SYSOPT, LIBUFF, and LOBUFF are normally supplied:

"parm": "SYSOPT=X'A0',LIBUFF=3072,LOBUFF=7168,SIRFUNC=X'01',SIRTUNE=0"

For the development cases:

• SYSOPT X'80' enables the audit trail.
• SYSOPT X'20' includes RK lines in the audit trail.
• X'A0' enables both.
• Do not add X'02' unless CCAGRP is allocated.
• Do not add X'01' unless CCASYS is already available during initialization.
• A security configuration requiring login must agree with the supplied CCASTAT and CCAIN login commands.

CCAIN is ordinary workstation text. emu204 translates it to EBCDIC and pads it to 80-byte card images. Model 204 reads only through column 72; a continued parameter line ends with a dash.

A small CCAIN might be:

HDRCTL=3,LVTBL=60000,LNTBL=18000,LSTBL=480000,                       -
NFILES=200,NDCBS=200,NDIR=200,PAGESZ=6184,SPCORE=120000,             -
TEMPPAGE=20000,OUTMRL=80,NSERVS=8,SERVSIZE=5000000
LOGIN
OPEN M204PROC
OPEN QAPROC
I QARUN MYTEST*
EOJ

Use TEMPPAGE when an in-memory CCATEMP is sufficient. If the test specifically needs a disk-backed CCATEMP, allocate it as an m204file with new and pages instead.

Allocating existing Model 204 files

An m204file is a flat, untranslated sequence of 6184-byte Model 204 pages. For one file:

"PAYROLL": {
  "path": "files/PAYROLL.M204FILE",
  "m204file": true
}

The DDNAME is the JSON key (PAYROLL). For an existing file, omit pages; the allocated size is inferred from the number of pages in the host file.

To allocate every appropriately named file in a directory:

"ddDirs": [
  {
    "path": "files",
    "suffix": "M204FILE",
    "m204file": true
  }
]

With this form, files/PAYROLL.M204FILE becomes DDNAME PAYROLL. The portion before the suffix must be a valid one-to-eight-character DDNAME. Files with the wrong suffix case or invalid DDNAMEs are reported rather than silently used.

The maximum number of pages available to an existing file is its host-file size divided by 6184. Verify a transferred page image before running:

bytes=$(wc -c < files/PAYROLL.M204FILE)
test $((bytes % 6184)) -eq 0 && echo "$((bytes / 6184)) pages" ||
  echo "not a whole number of Model 204 pages"

Creating a new or scratch Model 204 file

For a persistent file that does not exist yet, provide its extent with pages:

"NEWDATA": {
  "path": "files/NEWDATA.M204FILE",
  "m204file": true,
  "pages": 1000
}

The host file is created when Model 204 opens it. CCAIN must still issue the normal Model 204 CREATE, OPEN, and INITIALIZE commands. Do not specify new for a persistent database file: new empties the host file at the first open of every emulator run.

For deliberately disposable storage:

"CCATEMP": {
  "path": "out/ccatemp.pages",
  "m204file": true,
  "new": true,
  "pages": 5000
}

This is suitable for CCATEMP or a test file that must start empty on every run.

Getting files from CMS or z/OS

emu204 does not log on to CMS or z/OS and fetch database files itself. Put the required files in the case directory before starting it.

For a physical z/OS Model 204 data set, download it in binary mode with no character translation. The resulting workstation file must be only the concatenated 6184-byte pages:

ftp zos-host
binary
get 'HLQ.PAYROLL' files/PAYROLL.M204FILE
quit

FTP command syntax and quoting vary by client. After the transfer, verify that the byte count is a multiple of 6184. Do not mark a page image blocked; blocked is for record-oriented files transferred with FTP block-mode framing, not Model 204 database pages.

CMS Model 204 files may be on direct-access minidisks rather than represented as ordinary CMS files. Such a file cannot simply be fetched by CMS filename. Use the site's normal utility to make either:

• a physical sequential page image that can be downloaded without translation; or
• a Model 204 DUMP data set, which can be restored into a newly allocated local m204file.

The same dump-and-restore method works when direct access to a z/OS data set is unavailable.

If the dump data set was downloaded with FTP MODE B, preserve its record framing:

"PAYDUMP": {
  "path": "files/PAYROLL.DUMP",
  "blocked": true
},
"PAYROLL": {
  "path": "files/PAYROLL.M204FILE",
  "m204file": true,
  "pages": 10000
}

The target extent must be large enough for the restored file. The CCAIN stream can then create and initialize the target and restore the dump DD:

CREATE FILE (NOFORMAT) PAYROLL
END
OPEN FILE PAYROLL
IN FILE PAYROLL INITIALIZE
OPEN PAYROLL
IN FILE PAYROLL RESTORE 192 FROM PAYDUMP

Use the site's established DUMP options and restore page size; 192 above is the value used by current Model 204 QA restore procedures, not a universal replacement for the source environment's dump procedure.

Using procedure directories

Source-controlled procedure directories can be presented as read-only Model 204 procedure files without exporting a binary procedure file:

"M204PROC": {
  "path": "/home/user/m204-80/m204proc",
  "procDir": true
},
"QAPROC": {
  "path": "/home/user/m204-80/qaproc",
  "procDir": true
}

Each host file becomes one procedure, with its filename folded to upper case. Subdirectories are searched and flattened. Duplicate procedure names are reported. The procedure image is rebuilt when Model 204 opens the file, so host edits are seen after every user has closed the procedure file and it is opened again.

Output files and interactive control

Text DDs such as CCAPRINT and CCAAUDIT are written as readable workstation text. Use "sequence": true for CCASNAP so that each open produces ccasnap1.txt, ccasnap2.txt, and so on instead of replacing the preceding dump.

While Model 204 runs, a console line beginning with # is an emulator command. A bare # stops the guest at the EM> prompt; BEGIN resumes it. Use #HELP or emu204 --help=em for display, traceback, trap, trace, and profiling commands.

ZAP-maintenance workflow

1. Refresh the unmodified baseline

Every generated ZAP is a comparison against the baseline objects in obj/. Build those objects from current, unmodified master:

cd ~/m204-80
git switch master
git pull
make204 --no-zap

This step is mandatory. A stale baseline can produce ZAPs for modules that were not changed. Rebuild it after master moves or after a change to the assembler, pinned build date, version settings, or other build configuration.

2. Create the maintenance branch

The branch name must match <release>Z<PDS-number>:

git switch -c 80Z9206
prezap

prezap creates src/80Z9206.ZAP. Edit its header to describe the symptom, fix, prerequisites, and any genuinely necessary special instructions. Leave the 80Zxxx placeholder in the header; the distribution build assigns the sequence.

3. Check whether the target can be generated automatically

SIRE2 and EWDP are excluded from automatic object comparison in the current 8.0 configuration. A source change in either module can assemble and link successfully while being absent from the branch ZAP. Such a fix must be cut by hand on CMS or shipped in a relinked module.

Check the target module before doing the implementation.

4. Find patch space and make the source change

For a change that uses a module's local patch area or PTCH$:

scanzap SCOMP
scanzap SCOMP OTHERMOD

The output reports the next PTCH offset and the next local offset for each named module. Then edit the source under src/.

5. Build the ZAP

Use a clean ZAP directory for the first build:

make204 --clear

Subsequent builds can be incremental:

make204

In ZAP mode, make204:

1. assembles into zapobj/, zaplst/, and zapref/;
2. compares each changed object with the baseline object in obj/;
3. invokes bldzap to create per-module NAME/VER/REP statements;
4. links zapobj/M204ONLN.MODULE and zapobj/M204ONLN.ZOSMOD; and
5. appends the generated statements to src/<branch>.ZAP.

A successful run reports a header and one or more generated ZAPs. Header only (no ZAPs) means that no object difference was found. The usual causes are an unchanged source, a baseline that already contains the fix, or a target excluded by m204.jsonc.

Review all three forms of the result:

less src/80Z9206.ZAP
less zaplst/MODULE.LST80
git diff -- src/80Z9206.ZAP src/MODULE.ASSEMBLE

6. Prove the test and test the patched module

First prove that the test exposes the bug in the unpatched baseline:

putmod --no-zap

Recycle the CMS Online and run the test. It should fail or reproduce the reported BUG/SNAP.

Then upload the ZAP-applied build:

make204 --zap
putmod --zap

For z/OS, upload the ZAP-build object deck:

putmodzos --zap

Run the z/OS bind described below, recycle the Online, and run the same test. To switch back:

putmod --no-zap
putmodzos --no-zap

The standard testM204Qa command reads the normal object directory from hlasm.jsonc and therefore tests obj/M204ONLN.MODULE, not zapobj/M204ONLN.MODULE. Do not cite that smoke test as evidence that the generated ZAP was applied. Test the ZAP build explicitly on CMS/z/OS, or create a separate emu204 configuration whose module names the ZAP-linked module.

7. Final review

Before committing:

• Verify that the branch ZAP names only the modules expected for the fix.
• Verify every VER and REP block and the correct patch offsets.
• Check the prerequisite ZAP line; remove it if there is no prerequisite.
• Remove the template's special-instructions block unless it is required.
• Make sure the instructions name every load module that must be patched.
• Run git status --short and stage source paths explicitly. Do not stage build output or unrelated files.

Testing on CMS

putmod uploads the linked CMS MODULE and map to the build disk derived from the release and userid. In the Online's SETUP NAMES, set :tester. to the builder userid so the Online loads that user's module.

The normal recycle is:

EOJ
IPL CMS

At the CMS Ready prompt, PROFILE EXEC normally starts the Online. Run the reproducing QA procedure after the Online is ready.

Procedure changes are separate from the module upload. Push modified procedure directories with:

gitproc push qaproc
gitproc push m204proc

Testing on z/OS

The workstation linker produces a concatenated, fixed-80-byte z/OS object deck:

• baseline: obj/M204ONLN.ZOSMOD
• ZAP build: zapobj/M204ONLN.ZOSMOD

putmodzos uploads that object deck to the PDSE member named by zos.jsonc. It does not create the executable z/OS load module by itself. The gitzosl job on the Builder runs the z/OS binder and creates the test load module.

Configuration

The Model 204 tree needs zos.jsonc containing the z/OS FTP host, userid, object library, and member:

{
  "host": "...",
  "user": "...",
  "objlib": "...",
  "member": "..."
}

Do not put the password in this file. putmodzos obtains it from the workstation credential store, prompting on first use.

Build and upload

For an unpatched baseline test:

cd ~/m204-80
make204 --no-zap
putmodzos --no-zap

For a ZAP-maintenance test:

make204 --zap
putmodzos --zap

The upload is binary into an FB 80 PDSE member. If putmodzos says the object deck is missing, run make204 first and confirm that the selected obj/ or zapobj/ directory contains M204ONLN.ZOSMOD.

Bind on z/OS

On the Builder, run:

gitzosl

The submitted job deletes the prior test load module, compresses the test load library, binds M204ONLN with IEWL, and applies the required ZAPs. Its output returns to the Builder's virtual reader through RSCS/NJE.

Use rl (RDRLIST), then PF11 to inspect the job output. A successful bind includes:

$HASP395 ONLINE ENDED - RC=0000

Do not start the test Online if the bind failed or if the expected object deck was not used.

Select the z/OS Online

On the Online's CMS console:

EOJ
xedit setup names a

Change:

:opsys.CMS

to:

:opsys.MVS

The XEDIT command is:

c/:opsys.CMS/:opsys.MVS/ *
file

Leave :tester. set to the builder userid. It still selects the test version of M204ONLN.

Start and test

Start with either a full CMS IPL or the configuration nickname:

IPL CMS

PROFILE EXEC builds and submits the startup JCL. The JES messages include receipt of the job and completion of the submission step with MAXCC=0000. Unlike a CMS Online, Model 204 is now running as a z/OS batch job; the CMS console returns to VM read instead of displaying the local ONLINE message.

Connect from the normal user session:

M204F suffix
LOGIN
OPEN QAPROC
I QARUN pattern

Run the same reproducer used for the baseline. For a ZAP fix, keep evidence that the baseline failed and the ZAP build passed.

Return to CMS testing

Shut down the z/OS Online, edit SETUP NAMES, and change:

c/:opsys.MVS/:opsys.CMS/ *
file

Then IPL CMS or start the configuration nickname again.

Working on the tools themselves

Use ~/gitm204 only when changing make204, emu204, the assembler/linker, or another tool:

cd ~/gitm204
npm install
npx make
npm test

Useful narrower checks are:

npm run testci
npm run testmake
npm run testm204
npm run testm204qa

To prove the working-tree tools can build and run Model 204:

npx make
npx testM204Build --tree="$HOME/m204-80"
npx testM204Qa --tree="$HOME/m204-80"

testM204Build empties obj/ and ref/ in the tree it is given. Do not point it at a working tree whose current build output must be preserved.

Troubleshooting

Symptom	Action
make204 is not found	Reinstall @rocket/m204-tools, run hash -r, and inspect type -a make204.
emu204 says its platform package is missing	Reinstall without --no-optional or --ignore-scripts; check for an older command earlier on PATH. Published binaries support x86-64 Linux and Apple-silicon macOS.
Hundreds of unknown assembler operations	The macro libraries are probably absent or half-fetched. Run getmaclib --direct, then rebuild.
Linker reports unresolved LE symbols	Fetch the required object library with getobjlib --direct.
ZAP file has only its header	Confirm the source really differs from the baseline, refresh the baseline from unmodified master, and check whether the module is excluded from automatic ZAP generation.
ZAP unexpectedly contains many modules	The baseline or a pinned build setting is stale. Return to master and rebuild with make204 --no-zap.
QA run has a nonzero return code	Read the testM204Qa verdict. The Model 204 return code is not the pass/fail result.
Need more emulator detail	Use emu204 --help, emu204 --help=config, and emu204 --help=em.

Source references

• gitm204/BUILD.md
• gitm204/em204/README.md
• m204-80/DEVELOPMENT.md
• m204-80/ZAP-WORKFLOW.md
• m204-80/.github/skills/building.md
• m204-80/.github/skills/testing.md
• m204-80/.github/skills/zos-crossbuild.md