A call that names a
system also needs a systems scope.
Parameters ending in _zip_b64 take a directory as a base64 zip (cd dir && zip -qr - . | base64). Hum packs a directory path for you.
Scopes
Each tool needs one scope. Your organization holds Harwell’s scopes, and your client lists only the tools they reach.
A write scope includes the read scope of the same resource.
A call outside your scopes is a tool error:
checkpoint needs harwell:systems:write; this credential holds harwell:runs:read harwell:systems:read. A credential with no Harwell scope lists no tools, and every call ends this credential holds no Harwell scope. To get a scope, request access.
The run result
run_unit, submit and start return one result. A result whose status is not ok is a tool error.
Text. The verdict on the first line, then each compile error at file:line with the listing, the job log, each screen sent as 24 rows of 80 characters, what programs displayed, and, with an ORACLE/, oracle: passed or what missed.
structuredContent:
Resource links.
report.json, every listing, every step’s output and every spool file, at harwell://runs/<run>/<name>. Read one with resources/read. Only your organization reads them.
run_unit, submit, start and open_terminal can run as MCP tasks for clients that support the Tasks extension. The task’s result is the same result.
run_unit
Compile and run a unit: compile programs, submit jobs, run a chain, or start a transaction.
Give at most one of
work_id, work_zip_b64 and system. With none, the run starts on a fresh volume holding the unit’s CATALOG/ and DB/seed.sql, discarded when the call ends.
Returns the run result.
submit
Submit a job of a codebase in place.
With no volume, the job starts on a fresh volume holding the site data sets and tables
harwell.toml declares.
Returns the run result.
start
Start a transaction in a codebase’s region.
Returns the run result.
open_terminal
Open a browser page where a person drives a transaction by hand at a 24 by 80 screen.
Returns
read_terminal
Read what the person did at a terminal: the keys they pressed, the turns they marked right, and their notes.
Returns
Only your organization reads a terminal it opened.
sql
Run one read-only SQL statement against the Db2 database of a kept volume or a system.
Returns
{statement, columns, rows, more, sqlcode}. sqlcode is 0 with rows and 100 with none. A failed statement returns error, sqlcode and sqlstate, such as -204 for an unknown table.
list_datasets
List the data sets a kept volume or system catalogs, and its Db2 tables.
Returns
{pattern, datasets, tables}. Each data set has its name, organization, RECFM, LRECL, bytes and record count.
read_dataset
Read a data set’s records, as text and hex or decoded through a copybook.
Returns
{framing, record_count, start, more, records}. Each record is {n, text, hex}, or {n, fields} with a copybook, plus the layout’s fields. A KSDS or RRDS is refused: REPRO it to a sequential data set in a job.
systems
List your organization’s systems, or describe one.
Returns For a list,
{systems}, each with system, head, updated, volume_bytes, checkpoints, terminal and busy. For one system, the same plus created, lineage (the last calls that moved it) and each checkpoint’s run.
checkpoint
Label a system’s current state sorestore can bring it back. A label used before moves to the current state.
Returns The system, as
systems describes it, and checkpoint.
restore
Move a system back to a checkpoint. The state it leaves stays in its lineage. Refused while a call runs on it or a terminal holds it.
Returns The system, as
systems describes it, and restored.
delete_system
Forget a system and its checkpoints. Refused while a call runs on it or a terminal holds it.
Returns
{status, deleted}.