Skip to main content

​
Mainframe terms

​
Unit

A directory in a mainframe codebase’s own shape, plus a run.json that says what to run: compile programs, submit jobs, run a chain of jobs or start a transaction. run_unit and open_terminal take a unit. See Unit format.

​
Codebase

A directory with a harwell.toml at its root: a real estate’s programs, copybooks, procedures and region, run in place. submit, start and open_terminal take a codebase by repository or as a tree you send. See Run a codebase.

​
Volume

The state a run starts from and leaves: the catalog and its data sets, the Db2 tables and the region’s queues. By default each call gets a fresh volume, discarded when the call ends. Set return_work to keep it: the result names it by work_id, and a later call starts from it. The sql, list_datasets and read_dataset tools read a kept volume.

​
System

A named volume that persists across calls. Name it as system on run_unit, submit, start or open_terminal: the call starts from the state the system’s last call left, and its own state becomes the system’s next. Batch jobs, transactions and a person at a terminal all work on the same data. See Keep state.

​
Result

run_unit, submit and start return one shape:
  • Text. The verdict on the first line, then compile errors at file:line, the job log, each screen sent as 24 rows of 80 characters, and what programs displayed.
  • structuredContent. The same as JSON: status (ok, failed or error), verdict, diagnostics, jobs with each step’s return code, work_id when the volume was kept, and system when the call ran on one.
  • Resource links. report.json, every listing, every step’s output and every spool file, each at a harwell://runs/<run>/<name> URI. Read one with resources/read. Only your organization reads them.
A result whose status is not ok is a tool error.

​
Terminal

A browser page where a person drives a transaction by hand at a 24 by 80 screen. open_terminal returns its link. The person presses keys, marks each turn right or wrong, and closes it. read_terminal returns the screens they pressed, an oracle from the turns they marked right, and their notes. See Drive a CICS transaction.