Contents

COBOL, copybooks and JCL

The reference for what gitta Enterprise reads in mainframe code, and what counts as a change of meaning. For setup, see the Mainframe guide.

What gitta follows

Many programs share the same copybook, so one change can reach far. Git merges two branches line by line and does not know that a field in a copybook is used in other programs. gitta reads the COBOL and keeps track of what each agent changes and what each agent’s new code uses.

Fields and condition names in shared copybooks. A change of length, type or value counts.
Program interfaces. These are the parameters a program receives with CALL, EXEC CICS LINK or XCTL.
JCL steps and the programs they run, and the parameters of catalogued procedures.

When one agent changes something that another agent’s new code uses, the other agent gets a warning at its next step, and gitta status shows it too. The agent adapts its code, and your tests on the combined code decide the merge.

Copybook change impact

A copybook is shared by every program that copies it. When an agent widens a field, changes a PIC or moves a REDEFINES, each of those programs reads the record in a new layout. Git shows the copybook diff. It shows nothing about the programs that use the field.

gitta follows the field from the copybook to the code that uses it. The impact it reports is the new code of other agents that uses the changed field, condition name or interface. For each one, it names the field, the program and the agent.

While the agents work, the agent whose program uses the field gets a warning at its next step.
On a pull request, the gitta check names the other pull request whose new code uses the field.
When you merge, gitta runs your build or tests on the combined code and stops the merge when they fail.

IBM watsonx Code Assistant for Z and other AI tools now write and change COBOL (IBM, watsonx Code Assistant for Z). When several of them work on one code base, the copybooks are where their work meets. For a worked case, see What an agent sees.

What gitta supports

Part	What counts as a change of meaning	Symbol in warnings
Data fields in copybooks and programs, levels 01 to 49, 66 and 77, in WORKING-STORAGE, LOCAL-STORAGE, LINKAGE and FILE SECTION	A change of PIC (length, type, sign, decimals), USAGE (for example COMP-3 to COMP, or INDEX, POINTER), OCCURS, VALUE or REDEFINES. A group item changes when one of its fields changes. `9(5)` and `99999` are the same layout.	`ORDREC.ORD-DATE`
Tables with `OCCURS ... DEPENDING ON`	A change of the bounds, of the object that holds the count, or of that object’s layout. Index names from `INDEXED BY` are fields of their own and change with the table.	`ORDREC.ORD-LINE`, `ORDREC.ORD-IX`
EXTERNAL data	Every program that declares an item EXTERNAL shares its storage. A layout change in one program counts for new code in each other program that declares it, and for a change to its declaration there.	`EXTERNAL.CTL-RUN-DATE`
Condition names, level 88	A changed value. New code that tests the condition relies on the old value.	`CUSTREC.CUSTOMER-ACTIVE`
A whole copybook	Any field change. This covers code that holds the record in its own group, for example `01 WS-CUST. COPY CUSTREC.`	`CUSTREC.CUSTREC`
Paragraphs and sections	A removed or renamed paragraph or section. A paragraph that now uses a changed field also counts for code that PERFORMs it.	`ORDERS.CALC-TOTAL`
Programs	The interface: `PROCEDURE DIVISION USING` and `RETURNING`, and the layout of each LINKAGE SECTION parameter. Applies to `CALL 'PROG'`, `CALL identifier` when the identifier has a VALUE, and `EXEC CICS LINK` or `XCTL PROGRAM(...)`.	`CUSTUPD.CUSTUPD`
ENTRY points	The USING list of the entry and the layout of its parameters. Applies to `CALL 'ENTRY'` and `SET ... TO ENTRY 'ENTRY'`.	`CUSTUPD.CUSTRST`
Several programs in one file	Programs in a row and nested programs (`END PROGRAM`) each have their own names. A nested program’s interface counts for `CALL` from the program around it. Its GLOBAL items count for the programs nested in it. `INITIAL` and `RECURSIVE` are part of the interface.	`RPTCALC.RPTCALC`, `RPTCALC.MAIN-PARA`
Object-oriented COBOL	A method’s interface (`METHOD-ID` in a `CLASS-ID`). `INVOKE` uses it when the target is a class from the REPOSITORY paragraph, an `OBJECT REFERENCE` of that class, `SELF` or `SUPER`, and the method name is a literal. A method that uses the class’s object data changes when that data changes.	`REPORT.ADD-LINE`
JCL	A new or changed step with `EXEC PGM=` uses the program's interface. A PROC's symbolic parameters are its interface. A new parameter with a default does not count. gitta reads `DD DSN=` datasets and `DD PATH=` z/OS UNIX files, and quoted values that continue on the next line.	`CUSTUPD.CUSTUPD`

gitta also reads these parts of the code:

COPY member, COPY member OF library and EXEC SQL INCLUDE member END-EXEC.
Copybooks that start below level 01, which a program copies into its own record, for example 01 DFHCOMMAREA. followed by COPY LGCMAREA. or EXEC SQL INCLUDE LGCMAREA END-EXEC. A field of the copybook keeps the copybook’s name, used alone or qualified with the program’s record.
A new statement in a paragraph or section that already uses a field. It counts as a new use of that field.
COPY ... REPLACING with pseudo-text, words, LEADING and TRAILING. If a program copies ORDER with REPLACING ==:TAG:== BY ==WS==, a use of WS-DATE is a use of ORDER.:TAG:-DATE.
Qualified names. CUST-ID OF CONTACT-REC is a different field from CUST-ID OF ORDER-REC. A name that occurs two times in one file is shown with its record.
Host variables in EXEC SQL, and fields in EXEC CICS and EXEC DLI options, for example INTO, FROM, COMMAREA and CHANNEL. They count as uses of the fields.
EXEC CICS LINK, XCTL, LOAD and RELEASE with PROGRAM('NAME') or PROGRAM(field), and START, RETURN and RUN with TRANSID. A field gives the names in its VALUE and in each MOVE 'NAME' TO field of the program. The same holds for CALL and CANCEL with a field.
GO TO, GO TO ... DEPENDING ON, ALTER, SORT and MERGE with USING, GIVING and input or output procedures. The paragraphs, files and keys they name count as uses.
ADDRESS OF and LENGTH OF a field are uses of that field. Intrinsic functions (FUNCTION TRIM, FUNCTION CURRENT-DATE) are not data names. A user-defined function from the REPOSITORY paragraph is a use of that function.
Compiler directives. CBL and PROCESS lines in front of a program, *CBL, *CONTROL, EJECT, SKIP1 to SKIP3, TITLE and >> directives are not code.
Fixed format (sequence area in columns 1 to 6, indicator in column 7, code in columns 8 to 72, identification area in columns 73 to 80, comments, debug lines, continuation lines, also inside a literal) and free format. gitta finds the format itself, and >>SOURCE FORMAT switches it from that line on. Tabs count as stops every 8 columns.
Names in upper case and lower case. COBOL names are not case sensitive, and gitta shows them in upper case.

gitta reads COBOL with its own reader, not with a full COBOL grammar. The reader does what a COBOL preprocessor does with COPY and REPLACING, and it follows the column rules of fixed format. A change that only adds comments, renumbers the sequence area or changes case is not a change of meaning.

COBOL and JCL files merge line by line, as with Git. When the lines clash, the merge stops with a conflict.

gitta also protects COBOL Check test suites (.cut files). If an agent deletes a suite or removes EXPECT lines, gitta reports it in the merge output and the audit trail. See Merging.

Files gitta reads

Files	Read as
`.cbl`, `.cob`, `.cobol`	A program, or a copybook when the file has no PROGRAM-ID
`.cpy`, `.copy`, `.cbk`	A copybook
`.jcl`, `.prc`	JCL, or a catalogued procedure
Files without an extension in a copybook directory	A copybook. Add the directory to `.gitta-copybooks`.

A copybook is known by its member name, which is the file name without the extension in upper case. COPY CUSTREC finds copybook/CUSTREC.cpy, copy/custrec.cpy or cpy/CUSTREC.cbl. A program is known by its PROGRAM-ID.

Copybooks without an extension need a .gitta-copybooks file, see Copybook directories.