Run a codebase

A unit copies what it needs into one directory. A codebase already has its libraries. submit and start run a codebase where its files sit: programs, copybooks and procedures are found through the search order the codebase declares, and nothing is copied. Needs harwell:runs:write.

1. Mark the root

Put a harwell.toml at the root of the codebase. Every key is optional; an unknown key is refused by name.

[run]
clock = "20240501120000"

[site]
search_order = ["Progs", "services", "Stubs"]
copybook_order = ["Copybooks"]
job_card = "'SITE {pgm}',CLASS=A,MSGCLASS=X"
job_name = "SITEJOB"

[run] holds the settings a run executes under, the same keys as run.json (Unit format). [site] describes the codebase:

Key	Description
`search_order`	Libraries searched for a program or CALLed name, earlier first. Default: the program libraries
`system_library`	Libraries installed outside the codebase: `{NAME = "path"}`, relative to `harwell.toml`
`copybook_order`	Libraries searched for a `COPY` or `EXEC SQL INCLUDE` member. Default: `cpy`, `cpyv1`, `copy`, `copybooks`
`procedure_order`	Libraries searched for a PROC, `INCLUDE` member or submitted deck. A job’s `JCLLIB ORDER` comes first
`job_card`, `job_name`	The JOB statement of a deck Harwell writes for you. `{pgm}` is the program
`csd`	CSD source the region is built from: `DEFINE TRANSACTION`, `FILE`, `TDQUEUE`, `TSMODEL`
`region`	The region by hand, for a codebase with no CSD: `transactions`, `fct`, `dct`, `assign`
`catalog`	The site’s data sets: `{DSN = {path, lrecl, recfm, cluster}}`, laid on every fresh volume
`db2_catalog`	The SQL members the site’s Db2 setup ran, in order
`schemas`	Schema qualifiers stripped from SQL: `SITE.TABLE` becomes `TABLE`

What a codebase is lives in harwell.toml alone. A run.json that restates a [site] key is refused.

2. Name the codebase

Either way, path and the tree are the directory that holds harwell.toml.

Parameters	Codebase
`repo`, `ref`, `path`	A repository: GitHub `owner/name` or an https clone URL on any host, a branch, tag or commit, and the directory that holds `harwell.toml` (`""` for the root). Push the ref first
`codebase_zip_b64`	A tree you send: the directory as a base64 zip. Any tree, including members retrieved from Endevor or ChangeMan

The result’s source names what ran: the host, repository, ref, commit and path, or the tree’s digest, file count and bytes.

3. Submit a job

submit {"repo": "acme/billing", "ref": "main", "path": "mainframe", "deck": "BILLJOB"}

deck is a member of the codebase’s procedure libraries, or a path to a deck in the tree.

Parameter	Description
`step`	Run one step, named as `RESTART=` names it
`symbols`	Symbolic parameters the submitter sets: `{"PERIOD": "0602"}`

The result is run_unit’s: the verdict, each failed compile, each mapset that did not assemble, the job log and links to every output.

4. Start a transaction

start {"repo": "acme/billing", "ref": "main", "path": "mainframe", "transid": "CB00",
       "screens": [{"aid": "DFHENTER"},
                   {"aid": "DFHENTER", "map": "CBMAP", "mapset": "CBSET", "fields": {"ACCT": "00000000011"}}]}

The region is the one the codebase installs (csd or region). screens has the shape of cics.screens (Drive a CICS transaction). CEMT, CECI and CEDF are in every region: give the command as the first screen’s text, as in {"text": "CEMT I TRANS"}.

5. Open a terminal on it

open_terminal {"repo": "acme/billing", "ref": "main", "path": "mainframe"}

The person gets every transaction the codebase installs, on an empty screen.

Private repositories

A private GitHub repository is read with the caller’s GitHub access; see GitHub. Every fetch from another host is anonymous: send a private tree from it as codebase_zip_b64.

Keep state: run jobs and transactions on one persistent system.
Errors: each refusal and its fix.

Get started

Guides

Concepts

Reference

1. Mark the root

2. Name the codebase

3. Submit a job

4. Start a transaction

5. Open a terminal on it

Private repositories

Next

​1. Mark the root

​2. Name the codebase

​3. Submit a job

​4. Start a transaction

​5. Open a terminal on it

​Private repositories

​Next

1. Mark the root

2. Name the codebase

3. Submit a job

4. Start a transaction

5. Open a terminal on it

Private repositories

Next