Verification state: the project tools are verified on Linux with GnuCOBOL 3.1.2 on the payroll project. The z/OS tools are tested against the z/OSMF-shaped server and the modelled CMCI, Endevor Web Services and Debug Profile Service only, not against a host. No agent model was run in these tests: they call the tools as an agent would.
Agents in the Editor (the agent modes and chat) work through the same services as you, under the same rules. Every action is one tool over the service method your own command calls, so the agent gets the same typed result and you see the same outcome: a job in the job list and the job editor, compiler messages in Problems.
The rules every tool keeps
- Registered only while its side runs. z/OS tools exist while a connection exists; project tools while a Mainframe project is open. None when the module is off or the window is not trusted.
- Typed input and output. Parameters are checked before the tool runs. The answer is
{"ok":true,"result":...}, or{"ok":false,"refusal":...,"message":...}with one ofinvalidInput,notAvailable,readOnly,tooLarge,declined,failed. - Declared effect. Each tool says whether it is read-only, changes only the build folder, or changes z/OS.
- Confirmed by you, naming the system. Every tool that changes z/OS asks you in a dialog before anything is sent, whatever the agent's permissions and whatever "Don't ask again" you chose for your own submissions. The question names the data set, member, file, job, region, element or profile, the connection with its host and port, the user, and the service the change goes through when it is not z/OSMF. A declined call sends nothing.
- Production data, inside the tool.
neuralInverse.mainframe.readOnlyDatasetsis applied before the confirmation and before any request. A job whose DD statements would create, extend, use exclusively, delete or uncatalog a protected data set is refused, naming the step and DD (SET symbols substituted). A compile is refused when its load or DBRM library is protected. Allocate, copy, rename, VSAM changes, debug profile changes and debug jobs are checked the same way. The check reads the JCL as written: DDs of cataloged procedures and what a program does inside a data set it reads (such as an IDCAMS DELETE in SYSIN) are not seen, and RACF still decides. - Large data. A data set or z/OS UNIX file above
neuralInverse.mainframe.largeDownloadMegabytesis not read (tooLarge); you can open it in the editor, which asks.
TSO/E commands
mainframe_tsoReadOnlyCommand runs, without a question, only a line whose first word is in the machine setting neuralInverse.mainframe.agentTools.tsoReadOnlyCommands (by default LISTCAT, LISTDS, LISTALC, LISTBC, STATUS, TIME, HELP and their abbreviations) and that holds no ;. Anything else goes through mainframe_tsoCommand, which you confirm every time. Each call starts its own address space and logs it off.
z/OS tools
| Tool | Effect | What it does |
|---|---|---|
mainframe_listDatasets | read-only | Data sets matching a pattern, with the read-only pattern that protects each |
mainframe_listMembers | read-only | Members of a library, with ISPF statistics |
mainframe_readMember | read-only | A member or sequential data set as text, by lines, with its version |
mainframe_writeMember | changes z/OS | Saves over the version read; a newer version on z/OS refuses the save |
mainframe_deleteMember | changes z/OS | Deletes a member or a data set |
mainframe_searchDatasets | read-only | Search of data sets and members; migrated data sets are never recalled |
mainframe_submitJob | changes z/OS | Submits JCL and waits for the end (at most 900 seconds) |
mainframe_jobStatus, mainframe_readSpool | read-only | A job's state, return code, steps and spool files; a spool file's first records |
mainframe_purgeJobOutput | changes z/OS | Purges a job's output, cancelling it first if it runs |
mainframe_holdJob, mainframe_releaseJob, mainframe_cancelJob, mainframe_changeJobClass | changes z/OS | SDSF's job actions, the job read again after |
mainframe_compileOnZos, mainframe_checkOnZos | changes z/OS | Compile on z/OS; Check on z/OS (a job on the spool, nothing link-edited or bound) |
mainframe_allocateDataset, mainframe_copyDataset, mainframe_renameDataset, mainframe_recallDataset | changes z/OS | ISPF 3.2 allocate, 3.3 copy, rename, DFSMShsm recall |
mainframe_listUssFiles, mainframe_readUssFile | read-only | A z/OS UNIX directory; a file as text in its tagged code set |
mainframe_writeUssFile, mainframe_deleteUssFile | changes z/OS | Writes over the version read; deletes a file or directory |
mainframe_tsoReadOnlyCommand | read-only | One allowed TSO/E command |
mainframe_tsoCommand | changes z/OS | Any one TSO/E command, CALL or EXEC |
mainframe_listCicsRegions, mainframe_listCicsResources | read-only | CICS regions and their resources through CMCI |
mainframe_cicsAction | changes z/OS | NEWCOPY, PHASEIN, ENABLE, DISABLE, OPEN, CLOSE |
mainframe_listEndevorMap, mainframe_retrieveEndevorElement | read-only | Endevor's map one level at a time; an element's source without signout |
mainframe_generateEndevorElement, mainframe_moveEndevorElement | changes z/OS | Generate with the project's CCID; move to the next stage |
mainframe_listVsamClusters, mainframe_vsamClusterDetails, mainframe_readVsamRecords | read-only | Clusters, LISTCAT ALL, records with the fingerprint a write needs (LISTCAT and REPRO jobs on the spool) |
mainframe_writeVsamRecords | changes z/OS | Writes a KSDS back after a fingerprint check and a backup copy |
mainframe_defineVsamCluster, mainframe_deleteVsamCluster, mainframe_reproVsamCluster, mainframe_verifyVsamCluster | changes z/OS | IDCAMS DEFINE CLUSTER, DELETE, REPRO, VERIFY |
mainframe_runUserBuild | changes z/OS | A DBB user build with zAppBuild |
mainframe_prepareDebugJob | build folder | Writes the batch z/OS Debugger job of a step; nothing sent |
mainframe_submitDebugJob | changes z/OS | Submits the debug job and reads INSPLOG into the trace |
mainframe_readDebugTrace | build folder | The trace of a debug job submitted earlier |
mainframe_listDebugProfiles | read-only | DTCN and EQAUOPTS debug profiles |
mainframe_createDebugProfile, mainframe_setDebugProfileActive, mainframe_deleteDebugProfile | changes z/OS | Create, activate or deactivate, delete a debug profile |
Project tools
| Tool | Effect | What it does |
|---|---|---|
mainframe_programsUsingCopybook | read-only | Programs that copy a copybook, at any depth |
mainframe_jobsRunningProgram | read-only | Job steps that run a program, directly or through static CALLs |
mainframe_impact | read-only | What a change to a copybook or program affects |
mainframe_compileLocal | build folder | Compile with GnuCOBOL (GnuCOBOL's results) |
mainframe_runLocal | build folder | Run a JCL job with GnuCOBOL |
mainframe_programControlFlow | read-only | Sections, paragraphs, calls, ends and edges; unreachable and undefined procedures |
mainframe_dataElements | read-only | Data items with Enterprise COBOL offset and length, set and read counts |
mainframe_dataFlow | read-only | Statements that set and read a data item |
mainframe_codeReview | read-only | Findings of the project's code review rule set |
mainframe_listRunRecords, mainframe_readRunRecord | read-only | Run records, newest first; one record whole |
Both sides
| Tool | Effect | What it does |
|---|---|---|
mainframe_decodeRecords | read-only | Records of a data file through a copybook's record |
These remain your own commands and are not offered to agents: 3270 sessions (an agent drives TSO/E through mainframe_tsoCommand instead), COBOL Check tests, record edits of local data files, Endevor add, update, signout and signin, and Compile for Debug.