---
title: "Reference and troubleshooting"
---

# Reference and troubleshooting

Mainframe module settings and keys, what asks before it changes z/OS, the z/OS action log and run records, accessibility, how policy applies, the z/OS verification kit, and fixes for common problems.

## Keys

| Key | Action |
|---|---|
| Ctrl+Alt+Shift+Z | Connect to z/OS (adds a connection when there is none) |
| Ctrl+Alt+Shift+B | Compile on z/OS |
| Ctrl+Alt+Shift+J | Submit JCL to z/OS |
| Ctrl+Alt+Shift+S | Show z/OS Jobs |
| Ctrl+Shift+B | Compile on z/OS while z/OS leads, else Compile All with GnuCOBOL |
| Ctrl+Alt+J | Run JCL with GnuCOBOL |
| Ctrl+Alt+D (Ctrl+Option+D on macOS) | Debug JCL Step with GnuCOBOL |
| F5 | Debug the open COBOL program with GnuCOBOL and GDB |
| Shift+Alt+H | Show Perform Hierarchy |
| F2, Delete | Rename and delete in the z/OS Data Sets view |
| Ctrl+Enter, Shift+Alt+Down, Ctrl+Shift+Alt+Down, Delete | Insert, duplicate, repeat and delete records in the Record Viewer |
| Alt+F1 | Accessibility Help in the Record Viewer, job editor and z/OS Data Sets view |

The ISPF and IDz key presets are on [The ISPF editor and key presets](https://neuralinverse.com/docs/modules/mainframe/ispf-editor/#key-presets); column editing keys on [Fixed-format editing](https://neuralinverse.com/docs/modules/mainframe/editing/#keys-by-column).

## Settings

All keys are under `neuralInverse.mainframe.`. Machine settings cannot be changed by a workspace.

### Environment and connections

| Setting | Default | Meaning |
|---|---|---|
| `enabled` | `true` | Run the environment in a trusted workspace |
| `certificateAuthorities` | `[]` | PEM files of in-house CAs (machine setting) |
| `security.allowInsecureConnections` | `false` | Allow plain HTTP or unverified TLS |
| `security.rememberPasswords` | `true` | Allow passwords in the Editor's secret storage |
| `hostCopybookLibraries` | `{}` | The site's SYSLIB by connection name (machine setting) |
| `hostProjects` | `{}` | Host projects for a window without a folder |
| `zappVariables` | `{}` | Values of ZAPP `${NAME}` variables |

### Safety

| Setting | Default | Meaning |
|---|---|---|
| `readOnlyDatasets` | `[]` | Data set patterns opened read-only, every change refused before any request (machine setting) |
| `largeDownloadMegabytes` | 50 | Confirm opening larger data sets; spool preview above it |
| `alwaysConfirmJobSubmit` | `false` | Ask before every submission, ignoring "Don't ask again" (machine setting) |
| `sdsf.readOnly` | `false` | SDSF panels without actions or overtypes (machine setting) |
| `consoleCommandPrefixes` | `D`, `$D` | Console commands allowed, by their start |
| `consoleName` | | EMCS console for console commands |
| `agentTools.tsoReadOnlyCommands` | `LISTCAT`, `LISTC`, `LISTDS`, `LISTD`, `LISTALC`, `LISTA`, `LISTBC`, `LISTB`, `STATUS`, `ST`, `TIME`, `HELP`, `H` | TSO/E commands an agent may run without your confirmation (restricted) |
| `menuActions` | `[]` | The shop's own actions (restricted) |

### Jobs, SDSF, VSAM and printing

`idcams.jobCard`, `idcams.workQualifier`, `sdsf.execLibrary`, `sdsf.jobCard`, `sdsf.maxRows` (1000), `sdsf.refreshSeconds` (30), `sdsf.logLines`, `sdsf.logMinutes`, `print.sysoutClass` (`A`), `print.destination`, `search.maxMembers` (1000), `search.maxConcurrentRequests` (4), `compare.ignoreSequenceColumns` (`false`).

### Editing

`cobol.liveCheck` (`true`), `cobol.unreachableCode` (`true`), `cobol.tabStops`, `cobol.sequenceNumberFields`, `sequenceNumbers.start` (100), `sequenceNumbers.step` (100), `cobol.format.pictureColumn` (0), `cobol.format.levelIndent` (4), `cobol.format.statementIndent` (4), `ispf.prefixArea` (`false`), `ispf.scrollAmount` (`PAGE`), `ispf.profiles`, `keymap` (`default`, `ispf`, `idz`).

### Limits and tools

`index.maxMembers` (50,000), `rename.maxPrograms` (10,000), `detection.maxFolders` (20,000); `paths.cobc`, `paths.gdb`, `paths.cobolCheck`, `paths.java`.

## Confirmations and safety rules

An engineer confirms every change to z/OS that is not the plain result of the command they ran, and agents never change z/OS on their own.

- **Asks first, naming the system:** submitting a job, Debug on z/OS jobs included (unless you chose "Don't ask again" for that connection and `alwaysConfirmJobSubmit` is off), purging job output, SDSF actions and overtypes, console commands, shop actions, copying over existing members, deleting data sets, members and z/OS UNIX files, data set utilities, VSAM changes (with a backup before a write), writing spool output to a data set, ISPF MOVE and REPLACE, DBB user builds, Endevor changes, CICS actions, debug profile changes, and writing the SDSF exec to a library.
- **Runs when you start it, without a further question:** saving a member or z/OS UNIX file you edited (refused if it changed on z/OS since you opened it), creating a member, allocating and renaming a data set, and Compile on z/OS and Check on z/OS, which submit the generated compile job (Compile on z/OS link-edits into the project's load library).
- **Agents:** every agent tool that changes z/OS asks you in a dialog every time, whatever "Don't ask again" you chose for your own submissions. See [Agents](https://neuralinverse.com/docs/modules/mainframe/agents/).

Data sets matching `readOnlyDatasets` are refused before any request is sent, for your commands and for agents. Unsaved host data never goes to the hot-exit backups.

## The z/OS action log

Every request the Editor sends through a connection (z/OSMF, CICS CMCI, Endevor, the Debug Profile Service) is recorded in words (List data sets, Write member, Submit job, Purge job output, Issue console command), with the connection and system, the time, the duration and how it ended; actions that change z/OS are marked and also written to the Mainframe log channel as they happen (**Show Mainframe Log** opens it). Run records are added to the action log as they are written. **Show z/OS Action Log** opens it read-only; **Save z/OS Action Log** writes it to `zos-action-log-<date>-<time>.log`. It holds no credentials and keeps the latest 20,000 entries of the window's session. Tested against the z/OSMF-shaped test server.

## Run records

Every run writes one JSON record (format version 1) beside what it produced, so a result can be reproduced months later:

| Run | Record |
|---|---|
| Compile with GnuCOBOL | `<buildDirectory>/bin/<PROGRAM>.build.json`, `<buildDirectory>/modules/<PROGRAM>.build.json` |
| Run JCL with GnuCOBOL | `job.json` in `<buildDirectory>/jobs/<JOB>.<n>/` |
| COBOL Check | `<buildDirectory>/cobol-check/<PROGRAM>/run.json` |
| Debug build | `<PROGRAM>.debug.json` under `<buildDirectory>/debug/` |
| Compile on z/OS, Check on z/OS | `<buildDirectory>/host/<PROGRAM>.run.json`, `<PROGRAM>.check.run.json` |
| Submit JCL to z/OS (a JCL file in a project) | `<buildDirectory>/host/jobs/<JOB>.<JOBID>.run.json`, written at submit and when the job ends |
| Debug on z/OS | `<buildDirectory>/host/debug/<JOB>.<STEP>.debug.json` |

Each record holds `kind`, `started`, `durationMs`, `outcome`, `os`, the z/OSMF `connection` and `system` (from `GET /zosmf/info`) for z/OS runs, `tools` with paths and versions, `commands` with arguments and the environment the module set, `options`, and `inputs` and `outputs` with size, time and SHA-256. A record never holds a secret: fields that name a password, passphrase, token, secret, key, credential, cookie or authorization are left out. Spool content stays on the spool. A JCL outside a project has no build folder and no record.

Run records on the workstation are verified on Linux with the real tools; those of z/OS runs are tested against fixtures and the z/OSMF-shaped server. These records are evidence toward your change and release records; they are not a certification.

## Agents

Agents use 61 typed tools (49 for z/OS, 11 for the project, 1 for both) under the same rules as you: every change to z/OS confirmed naming the system, `readOnlyDatasets` applied inside the tool. See [Agents](https://neuralinverse.com/docs/modules/mainframe/agents/).

## Accessibility

Accessibility Help (Alt+F1) in the Record Viewer, the job editor and the z/OS Data Sets view names their keys. The reason of an invalid record value is the cell's accessible description. When a job ends, the Task Completed or Task Failed signal plays and is announced. `accessibility.verbosity.neuralInverseMainframe` (on by default) says, when the Record Viewer or the job editor gets focus, that Accessibility Help describes its keys. Rendering tests only; not yet checked with a screen reader.

## Your organisation's policy

With Neural Inverse Govern, tasks and launch configurations (such as the GnuCOBOL compile tasks and debug sessions) and changes to Neural Inverse settings are decided by the in-app policy check, which can allow, deny or require approval. The module's own z/OS confirmations and `readOnlyDatasets` apply in addition, and RACF still decides what the host allows. See [Govern](https://neuralinverse.com/docs/govern/).

## The z/OS verification kit

The kit sends, with curl, the exact requests the module sends for each capability, records every answer, and packs them into one archive. You run it without the Editor.

**What it creates.** Only data sets under `<HLQ>.NIVERIFY`, owned by the user in `kit.conf`, plus jobs of that user. It first lists `<HLQ>.NIVERIFY.**` and stops before creating anything if a data set exists there. At the end it deletes only what the run created; `--keep` leaves them, `--cleanup` deletes them later. Optional sections (TSO/E, z/OS UNIX, SDSF, z/OS Debugger, the Debug Profile Service, CMCI, Endevor, Db2 BIND, PL/I, HLASM) run only when `kit.conf` sets them. With `DB2_BIND=yes` the kit leaves the package `<collection>.NIVDB2` in Db2.

**Permissions.** ALTER on `<HLQ>.NIVERIFY.**`; READ on the compile procedure libraries and the libraries they use; access to z/OSMF's jobs, data set and file services; JES authority to submit, hold, release and purge your own jobs; and for each optional section the access its README lists.

**Run it.**

1. Copy the kit's `zos` folder to a machine with curl that reaches z/OSMF.
2. Fill in `kit.conf`: host, port, user ID, your in-house CA unless the trust store trusts z/OSMF, the proxy, the HLQ, the job statement values, and the compile procedure with its step names.
3. Run it and type the z/OSMF password when asked:

```sh
cd zos
sh run.sh
```

```powershell
cd zos
powershell -NoProfile -ExecutionPolicy Bypass -File run.ps1
```

No administrator rights, nothing to install. The password is read without echo, kept in memory, and never written to disk, the command line or the results. If z/OSMF rejects it, the kit stops at once so the user ID is not revoked.

**What it writes.** `results/` and `niverify-results-<time>.tar.gz` (Linux, macOS) or `.zip` (Windows): `summary.txt` with the z/OS and z/OSMF versions and each step's PASS, FAIL or SKIP; `kit.txt` with the site values used; one folder per step with the request (without credentials) and the response. Review the folder before you send it to your Neural Inverse contact. Windows PowerShell 5.1 on Windows has not been verified; `run.ps1` ran under PowerShell 7.5.5 on Linux.

## Troubleshooting

| Problem | What to do |
|---|---|
| Nothing mainframe appears in an empty window | Add a connection with **Connect to z/OS**; the z/OS side runs only while a connection exists. Check the window is trusted. |
| The project side does not start | The folder needs `mainframe.json`, a ZAPP file, zAppBuild's `application-conf`, or COBOL, copybook, JCL or procedure members within twelve folders. A notification says when detection stopped at `detection.maxFolders`. |
| The status bar says a certificate is not trusted | Add your in-house CA's PEM file to `neuralInverse.mainframe.certificateAuthorities`. Do not turn on `allowInsecureConnections` to work around it. |
| The proxy refuses (407) | Set `http.proxy` and, if your proxy needs it, a Proxy-Authorization. Kerberos, NTLM and SOCKS proxies are not supported. |
| The password is not asked again after a rejection | By design, to avoid revoking your user ID. Run **Forget z/OS Credentials** and try again once you know the password. |
| A save is refused with a conflict | The member changed on z/OS since you opened it; choose Compare or Overwrite. |
| A save is refused before any request | The data set matches `readOnlyDatasets`; the editor names the pattern. |
| A copybook is marked missing on a member opened from z/OS | Members from z/OS use host libraries only. Set `host.copybookLibraries` or the site's `hostCopybookLibraries`. |
| Compile on z/OS is not offered | The project needs `host.compile` and a connection. |
| An abend is not mapped to a line | The step says why: no listing from Compile on z/OS, no offset table (compile with LIST or OFFSET), or the program changed since. |
| Local results differ from z/OS | They are GnuCOBOL's. Use Check on z/OS for Enterprise COBOL's verdict. |
| Anything on z/OS behaves unexpectedly | No z/OS run has been verified yet. Run the verification kit and send the archive with the Mainframe log. |

![A connection to an example host that cannot be reached, named in the z/OS Data Sets view and the status bar.](https://neuralinverse.com/docs-images/modules/mainframe/zos-unreachable.webp)

![A configured GDB path that does not exist, raised as a tool needing attention in the status bar.](https://neuralinverse.com/docs-images/modules/mainframe/tools-need-attention.webp)