Project files: mainframe.json, ZAPP and zAppBuild

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:

{
  "$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.

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.

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 (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.