---
title: "Project files: mainframe.json, ZAPP and zAppBuild"
---

# Project files: mainframe.json, ZAPP and zAppBuild

How the Mainframe module opens an application repository as it is, the mainframe.json keys, IBM ZAPP files and zAppBuild's application-conf read and edited round trip in a form, Write to zapp.yaml, and host projects with no local copy.

**Verification state:** the project reader, ZAPP and zAppBuild reading and the round-trip form are the module's own code, **verified on Linux** on AWS CardDemo (44 programs, 62 copybooks, 55 jobs, 6 procedures), IBM's dbb-zappbuild MortgageApplication, IBM's own sample `zapp.yaml` and a generated estate of 37,601 members in 50 projects. Files written here have **not been opened in IBM Z Open Editor, IDz or DBB**. Host projects are tested against the z/OSMF-shaped test server only, **not yet run against z/OS**.

## Open the repository as it is

Open the application's folder. The module reads:

- `mainframe.json` at the top of a project folder, every key optional;
- IBM's ZAPP files (`zapp.yaml`, `zapp.yml`, `zapp.json`): COBOL property groups, `local` libraries as folder globs and `mvs` libraries as data sets, `${NAME}` variables with values from `neuralInverse.mainframe.zappVariables`;
- zAppBuild's `application-conf` (`application.properties` and the `Cobol.properties` and `file.properties` it lists).

Without a project file it finds COBOL, copybook, JCL and procedure members by extension, or by their text for `.txt` and extensionless files (as Zowe downloads and PDS members are named), up to twelve folders deep. Copybooks are found by name, case-insensitively, with the project's extensions; `.prc` and `.proc` files are procedures. Detection stops after `neuralInverse.mainframe.detection.maxFolders` folders (20,000) and says so once. A plain-text document opened on its own is shown as COBOL or JCL by its text.

A folder below a workspace folder that holds its own project file is a project of its own, for monorepos with `apps/<app>/`. Without a project file, copybooks are searched only next to the program.

## mainframe.json

For example, a payroll project:

```json
{
  "$schema": "neuralinverse://schemas/mainframe-project",
  "sources": ["cobol"],
  "format": "fixed",
  "dialect": "ibm-strict",
  "copybooks": ["copybook"],
  "tests": "tests",
  "host": {
    "copybookLibraries": ["PAYROLL.COPYLIB"],
    "compile": {
      "procedure": "IGYWCL",
      "jobCard": [
        "//${PROGRAM}C JOB (ACCT),'COMPILE',CLASS=A,MSGCLASS=X,",
        "//             NOTIFY=&SYSUID"
      ],
      "options": "LIB,LIST,MAP,XREF",
      "loadLibrary": "PAYROLL.LOAD"
    }
  }
}
```

The schema is always available, so the editor completes and checks the keys.

| Key | What it holds |
|---|---|
| `sources`, `copybooks`, `libraries` | Program folders, copybook folders, and folders for `COPY ... OF library` |
| `copybookExtensions`, `extensions` | The project's own extensions for COBOL, copybooks, JCL, procedures, PL/I, HLASM and REXX |
| `procedures` | Cataloged procedures and INCLUDE members; by default folders named PROCLIB, PROC, PROCS or JCL |
| `datasets` | Data set names mapped to local files, for links from `DSN=` and for local runs |
| `tests` | COBOL Check tests (`.cut` files); by default `src/test/cobol` |
| `host.profile` | The connection profile the project uses |
| `host.copybookLibraries`, `host.procedureLibraries` | The host's copybook and procedure libraries, in search order |
| `host.compile` | The job card (with `${PROGRAM}`), the procedure, its step names, PARM and DD overrides per step, symbolic parameters, the load library, the shop's compiler options; `profiles` per program kind (`batch`, `db2`, `cics`, `db2cics`, `pli`, `hlasm`) with BIND; `check` for Check on z/OS. See [Compile and check on z/OS](https://neuralinverse.com/docs/modules/mainframe/compile/) |
| `host.debug` | z/OS Debugger: `compileOptions`, `mode` (`batch` or `fullScreen`), `terminal`, `testOptions`, `debuggerLibrary`, `profileService`. See [Debug on z/OS](https://neuralinverse.com/docs/modules/mainframe/zos-debug/) |
| `host.cics` | The CICS region (`region`, `cicsplex`, `programs`, `afterCompile`). See [CICS regions and New Copy](https://neuralinverse.com/docs/modules/mainframe/cics/) |
| `host.userBuild` | The DBB user build when no ZAPP `dbb` profile gives it |
| `pli`, `hlasm`, `rexx` | Include, COPY and macro libraries for those languages |
| `dialect`, `format`, `cobcOptions`, `buildDirectory` | The workstation path with GnuCOBOL |
| `layout` | The shop's layout standard: `pictureColumn`, `levelIndent`, `statementIndent` |
| `hostProjects`, `menuActions`, `codeReview` | Host projects, the shop's own actions, the code review rule set |

## Edit ZAPP and zAppBuild files in a form

ZAPP files and zAppBuild's property files open in a **Project File Form** beside their source, on the same document, so Undo, Save and the source editor work as for text. **Open Form to the Side** and **Open Source to the Side** switch between them.

- **ZAPP:** property groups with local and MVS libraries, the `dbb`, `rseapi` and `preprocessor` profiles, and variables.
- **zAppBuild:** each property with what it does, file overrides, and the files `application.properties` loads.

Every edit is read back and refused if anything other than the edited value would change: comments, key order, quoting, line endings and unknown keys stay as they were. Problems come from the module's own rules, written from IBM's ZAPP schema 1.12.0 and zAppBuild's documentation; the schema itself is not shipped.

Verified on Linux: MortgageApplication's three files edited, each differing only in the edited line; every one of its 452 properties in 33 files edited alone; CardDemo; IBM's sample `zapp.yaml`. Profile types other than `dbb`, `rseapi` and `preprocessor` are kept but edited only in the source. A YAML `key:` with no value must be fixed in the source first.

### Write to zapp.yaml

**Write to zapp.yaml** adds to `zapp.yaml` the libraries, procedures and compile options from `mainframe.json` that it lacks, after a confirmation that names each change. Verified on CardDemo: the file written and read back.

## The build configuration of a DBB shop

When `mainframe.json` names no sources, zAppBuild's `application-conf` gives them; its copybook search runs after the project's own; and `cobol_compileParms` with the CICS and SQL parameters becomes the options of Compile on z/OS when `host.compile.options` gives none. DBB itself is not run for this: its scanner, which decides CICS and SQL on the build machine, is approximated by the program's EXEC statements. Property files outside `application-conf` are not read. Verified on Linux on MortgageApplication. To run a DBB user build, see [DBB user build](https://neuralinverse.com/docs/modules/mainframe/compile/#dbb-user-build).

## Host projects: no local copy

For applications whose members stay in PDS libraries (IDz's MVS subprojects), define `hostProjects` in `mainframe.json`, or the user setting `neuralInverse.mainframe.hostProjects` for a window without a folder, with data set patterns such as `PROD.PAYROLL.COBOL(PAY*)`.

- Members are read through the host copybook cache and indexed into the [application map](https://neuralinverse.com/docs/modules/mainframe/application-map/) (references, CALL and job links).
- They compile with Compile on z/OS by the project's `host` settings.
- They are listed under **Host Projects** in the z/OS Data Sets view.
- In a window without a folder, build output and the cache go to the window's workspace storage.

State: tested against the z/OSMF-shaped test server; **not yet run against z/OS**.