--- title: "COBOL and copybooks" --- # COBOL and copybooks COBOL language features over the program as the compiler sees it, with copybooks expanded with REPLACING, copybooks from local folders and host libraries, references and rename across the application, and the module's snippets. **Verification state:** the language features are the module's own code and need no host and no GnuCOBOL. They are **verified on Linux** on the payroll sample, AWS CardDemo (44 programs, 62 copybooks, 55 jobs) and a generated estate of 37,601 members. Copybooks read from z/OS are tested against the z/OSMF-shaped server, **not yet run against z/OS**. Results are not compared with IDz's on the same programs. ## Copybooks expand as the compiler expands them Nested COPY, REPLACING with pseudo-text, `:TAG:` partial words, LEADING and TRAILING, continued literals and words. Every token keeps its file and line, so every feature below works through copybooks. The expansion was compared word for word with GnuCOBOL 3.1.2's `cobc -E` on the payroll programs and a stress program; it is not compared with Enterprise COBOL's expansion on z/OS. ### Where copybooks are found 1. **Local folders:** the project's `copybooks`, by name, case-insensitively, with the project's extensions; `COPY ... OF library` through `libraries`. 2. **Host libraries**, while a connection exists: the project's `host.copybookLibraries` and ZAPP `mvs` libraries, in SYSLIB order. Members are cached in `/hostCopybooks/` with their ETags, checked again on open and with **Refresh Host Copybooks**, which reads only the members that changed. The cache works without network across sessions. 3. A member **opened from z/OS** resolves its copybooks from host libraries only, as the compiler on z/OS would: the owning project's libraries, else the site's SYSLIB in `neuralInverse.mainframe.hostCopybookLibraries` (a machine setting, by connection name, `*` for every connection), else the source libraries of its high-level qualifier. A COPY whose copybook is not found is marked, one marker per missing copybook, naming the libraries searched. Without a connection, the marker says so and offers **Add z/OS Connection** as a quick fix. ![A CICS program from AWS CardDemo with its outline and Problems: IBM CICS copybooks marked missing because no z/OS connection is configured.](https://neuralinverse.com/docs-images/modules/mainframe/cics-copybook-problems.webp) ## In the program - **Outline:** divisions, sections, FDs, data items nested by level, paragraphs, and a copybook's items under its COPY. - **Go to Definition and Peek** for data names (`IN-EMP-ID` to its `:PFX:-EMP-ID` line in the copybook), qualified names (`CITY OF IN-ADDRESS`), files, sections and paragraphs (PERFORM, GO TO, THRU), COPY names and `CALL 'literal'`. - **Find All References** and highlights. - **Hover** with level, PICTURE, USAGE, qualification and where it is defined; a paragraph's first lines; a copybook's text; and on a CBL or PROCESS statement, what each option does in a local build. - **Completion** of data, file, section and paragraph names in the PROCEDURE DIVISION, and the dialect's statement words. - **COPY links** open the copybook. - **Folding** by divisions, sections, paragraphs, FDs, group items, EXEC blocks and comment blocks. - Programs with EXEC SQL: DCLGEN members expand into the outline, navigation and references, and host variables are references. A program of about 12,000 lines is analysed within the test's 5-second bound. ![Hover on a field from a copybook: level, PICTURE and usage, its record, and where it is defined and copied.](https://neuralinverse.com/docs-images/modules/mainframe/hover-copybook-field.webp) ## Across the application As IDz's search, references and refactoring: - **Find All References** on a copybook item lists it in every program that copies it, under the name each program's REPLACING gives it (`IN-EMP-ID` in one program, `OUT-EMP-ID` in another). On a COPY name it lists every COPY; on a CALL literal or PROGRAM-ID every CALL, EXEC CICS LINK and XCTL, and every JCL `PGM=`. - **Go to Symbol in Workspace** finds programs, copybooks, sections, paragraphs, 01 and 77 items, JCL jobs, procedures and steps. ![Find All References on a copybook item in AWS CardDemo: 23 references in 11 files.](https://neuralinverse.com/docs-images/modules/mainframe/references-copybook-item.webp) ### Rename **Rename** (F2) of a data name, file, section or paragraph changes the program, its copybooks and every program that reads an edited shared copybook, as one workspace edit in the refactor preview, keeping fixed-format columns. A rename is refused, with the reason, when REPLACING produces or mentions the name, the new name is not a COBOL word or is reserved, a program already defines it, a use is ambiguous, a line would pass column 72, or the rename reaches more than `neuralInverse.mainframe.rename.maxPrograms` (10,000) programs. A warning says when the application map is truncated. Reserved words come from your `cobc` (`cobc -std= --list-reserved`); GnuCOBOL's list for `-std=ibm` is not Enterprise COBOL's. Verified on the payroll project and a five-program application, every edit asserted, renamed programs compiled again; rename measured across 500 and 25,000 programs. ![Rename of a working-storage item in a sample program, with Ctrl+Enter to preview the edit across programs.](https://neuralinverse.com/docs-images/modules/mainframe/cobol-rename.webp) ## Snippets The module's own 42 COBOL, copybook and JCL snippets appear in completion and through **Insert Mainframe Snippet**: - program skeletons: batch, CICS pseudo-conversational, Db2 batch, subprogram; - file definitions for QSAM, KSDS and ESDS (the FD at the cursor, its SELECT in FILE-CONTROL and its status item in WORKING-STORAGE); - record layouts: keyed, header/detail/trailer, OCCURS DEPENDING ON, COMMAREA, SQL cursor; - statements: read loop, EVALUATE, PERFORM VARYING, SEARCH, SEARCH ALL, STRING, UNSTRING, CALL; EXEC SQL and EXEC CICS patterns; - JCL: job statement, IEFBR14, IEBGENER, IDCAMS, SORT, compile-link-go, GDG, IKJEFT01 for Db2, BPXBATCH. They are laid out by the project's `layout`, filled with the shop's names (PROGRAM-ID, high-level qualifier, libraries, Db2 subsystem and plan, job card) and offered where they belong. Every COBOL snippet compiles with GnuCOBOL 3.1.2 `-std=ibm-strict` in four layouts; every JCL snippet reads with no problems. They have not been compiled by Enterprise COBOL with the CICS translator and Db2 precompiler. Fixed-format editing is on [Fixed-format editing](https://neuralinverse.com/docs/modules/mainframe/editing/); checks as you type on [Checks and code review](https://neuralinverse.com/docs/modules/mainframe/checks-and-review/).