> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a codebase

> Submit a job or start a transaction of a whole estate in place, from its repository or from a tree you send.

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.

```toml theme={"dark"}
[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](https://docs.metaphi.ai/harwell/unit-format.md)). `[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

```json theme={"dark"}
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

```json theme={"dark"}
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](https://docs.metaphi.ai/harwell/guides/cics-transactions.md#3-the-region-and-the-screens)). `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

```json theme={"dark"}
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](https://docs.metaphi.ai/account/github.md). Every fetch from another host is anonymous: send a private tree from it as `codebase_zip_b64`.

## Next

* [Keep state](https://docs.metaphi.ai/harwell/guides/systems.md): run jobs and transactions on one persistent system.
* [Errors](https://docs.metaphi.ai/harwell/errors.md#codebase-refusals): each refusal and its fix.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.