Copilot instructions

1---
2applyTo: "**/*.cbl, **/*.cob, **/*.asm, **/*.hlasm, **/*.jcl, **/*.cpy, **/*.pco"
3---
4 
5## Context
6 
7This instruction file applies to mainframe source files: IBM COBOL programs, High Level Assembler (HLASM) source, Job Control Language (JCL), and COBOL copybooks. These programs run on IBM z/OS and interact with CICS (transaction processing), DB2 z/OS (relational database), VSAM (indexed file system), and QSAM (sequential datasets). This context is used both for understanding existing programs and for generating migration artifacts. When explaining COBOL, always note the Java equivalent to assist modernization engineers.
8 
9---
10 
11## COBOL Coding Standards
12 
13- **IBM Enterprise COBOL 6.x** syntax — dialect-specific features are acceptable
14- Respect the four division structure: `IDENTIFICATION`, `ENVIRONMENT`, `DATA`, `PROCEDURE`
15- Every program must have a `PROGRAM-ID` in `IDENTIFICATION DIVISION`
16- `WORKING-STORAGE SECTION` holds persistent data for the life of the program
17- `LOCAL-STORAGE SECTION` holds thread-local data (re-initialized on each CICS task)
18- `LINKAGE SECTION` defines parameters passed via `COMMAREA` or `CALL` interface
19- Column layout (fixed-format): columns 1–6 sequence, column 7 indicator (`*` = comment, `-` = continuation), columns 8–11 Area A, columns 12–72 Area B, columns 73–80 identification
20- **Copybooks:** Use `COPY` statements for shared record layouts — never inline what belongs in a copybook. Copybooks live in the `COPYLIB` or equivalent library
21- **Host variable naming:** DB2 host variables are prefixed `HV-` (e.g., `HV-CUSTOMER-ID`)
22- **Return code:** Return code stored in `RETURN-CODE` special register or passed via `WS-RETURN-CODE`
23 
24---
25 
26## COBOL Patterns
27 
28### Basic Program Structure
29 
30```cobol
31       IDENTIFICATION DIVISION.
32       PROGRAM-ID. CUSTINQ.
33       AUTHOR.     ENTERPRISE TEAM.
34      *----------------------------------------------------------------*
35      * DESCRIPTION: Customer inquiry program                          *
36      * CALLED BY:   CICS transaction CINQ                             *
37      *----------------------------------------------------------------*
38       ENVIRONMENT DIVISION.
39       CONFIGURATION SECTION.
40       SOURCE-COMPUTER. IBM-ZOS.
41       OBJECT-COMPUTER. IBM-ZOS.
42 
43       DATA DIVISION.
44       WORKING-STORAGE SECTION.
45       01 WS-RETURN-CODE         PIC S9(4)  COMP VALUE ZEROS.
46       01 WS-CUSTOMER-RECORD.
47          05 WS-CUST-ID          PIC 9(10)        VALUE ZEROS.
48          05 WS-CUST-NAME        PIC X(50)        VALUE SPACES.
49          05 WS-CUST-BALANCE     PIC S9(13)V99 COMP-3 VALUE ZEROS.
50 
51       LINKAGE SECTION.
52       01 DFHCOMMAREA.
53          05 CA-REQUEST-TYPE     PIC X(1).
54          05 CA-CUSTOMER-ID      PIC 9(10).
55          05 CA-RESPONSE-CODE    PIC S9(4)  COMP.
56 
57       PROCEDURE DIVISION.
58           PERFORM 1000-INITIALIZE
59           PERFORM 2000-PROCESS
60           PERFORM 9000-RETURN
61           STOP RUN.
62 
63       1000-INITIALIZE.
64           MOVE ZEROS TO WS-RETURN-CODE.
65 
66       2000-PROCESS.
67           EVALUATE CA-REQUEST-TYPE
68               WHEN 'I'
69                   PERFORM 2100-INQUIRE-CUSTOMER
70               WHEN OTHER
71                   MOVE 8 TO CA-RESPONSE-CODE
72           END-EVALUATE.
73 
74       2100-INQUIRE-CUSTOMER.
75           MOVE CA-CUSTOMER-ID TO HV-CUST-ID
76           EXEC SQL
77               SELECT CUST_NAME, CUST_BALANCE
78               INTO   :HV-CUST-NAME, :HV-CUST-BALANCE
79               FROM   SCHEMA.CUSTOMERS
80               WHERE  CUST_ID = :HV-CUST-ID
81           END-EXEC
82           EVALUATE SQLCODE
83               WHEN 0
84                   MOVE HV-CUST-NAME    TO WS-CUST-NAME
85                   MOVE HV-CUST-BALANCE TO WS-CUST-BALANCE
86               WHEN 100
87                   MOVE 4 TO CA-RESPONSE-CODE
88               WHEN OTHER
89                   MOVE 12 TO CA-RESPONSE-CODE
90           END-EVALUATE.
91 
92       9000-RETURN.
93           EXEC CICS RETURN END-EXEC.
94```
95 
96### DB2 Embedded SQL Host Variables
97 
98```cobol
99       WORKING-STORAGE SECTION.
100      * DB2 SQLCA - always include for SQLCODE checking
101           EXEC SQL INCLUDE SQLCA END-EXEC.
102      * Host variables - prefix HV-
103       01 HV-CUST-ID              PIC 9(10)         VALUE ZEROS.
104       01 HV-CUST-NAME            PIC X(50)         VALUE SPACES.
105       01 HV-CUST-BALANCE         PIC S9(13)V99 COMP-3 VALUE ZEROS.
106       01 HV-NULL-IND             PIC S9(4) COMP     VALUE ZEROS.
107```
108 
109### CICS Command Patterns
110 
111```cobol
112      * Read from CICS COMMAREA
113           EXEC CICS
114               ADDRESS COMMAREA(WS-COMMAREA-PTR)
115               LENGTH(WS-COMMAREA-LEN)
116           END-EXEC.
117 
118      * Read a VSAM file via CICS
119           EXEC CICS READ
120               FILE('CUSTFILE')
121               INTO(WS-CUSTOMER-RECORD)
122               RIDFLD(WS-CUST-ID)
123               RESP(WS-CICS-RESP)
124               RESP2(WS-CICS-RESP2)
125           END-EXEC.
126           EVALUATE WS-CICS-RESP
127               WHEN DFHRESP(NORMAL)   CONTINUE
128               WHEN DFHRESP(NOTFND)   MOVE 4 TO WS-RETURN-CODE
129               WHEN OTHER             MOVE 12 TO WS-RETURN-CODE
130           END-EVALUATE.
131```
132 
133### COBOL → Java Mapping Reference
134 
135| COBOL Construct | Java Equivalent |
136|----------------|----------------|
137| `PIC 9(10)V99` | `BigDecimal` with scale 2 |
138| `PIC X(50)` | `String` (max 50 chars) |
139| `PIC S9(4) COMP` | `short` or `int` |
140| `PIC S9(9) COMP` | `int` or `long` |
141| `COMP-3` (packed decimal) | `BigDecimal` |
142| `WORKING-STORAGE` fields | Instance fields or method-local variables |
143| `LOCAL-STORAGE` fields | Method-local variables (re-initialized per call) |
144| `LINKAGE SECTION` | Method parameters |
145| `PERFORM UNTIL` | `while` loop |
146| `PERFORM n TIMES` | `for (int i = 0; i < n; i++)` loop |
147| `EVALUATE` | `switch` expression |
148| `COPY` copybook | Java interface, abstract class, or shared record |
149| `EXEC SQL ... END-EXEC` | Spring Data JPA `@Query` or `JdbcTemplate` |
150| `EXEC CICS ... END-EXEC` | REST endpoint call or message queue |
151| `MOVE SPACES TO field` | `field = "";` or `field = null;` |
152| `MOVE ZEROS TO field` | `field = 0;` or `BigDecimal.ZERO` |
153| `INSPECT ... TALLYING` | String processing with regex or streams |
154| `STRING ... INTO` | `String.format()` or `StringBuilder` |
155 
156---
157 
158## Anti-Patterns — Flag and Explain
159 
160| Pattern | Action |
161|---------|--------|
162| `ALTER verb` | **Do not generate.** Flag as deprecated and unmaintainable — restructure using `EVALUATE` |
163| `GO TO label` | Flag — suggest `PERFORM` with structured paragraphs instead |
164| `PERFORM THRU` with fall-through | Flag — risk of unintended paragraph execution; restructure as explicit `PERFORM` calls |
165| Dynamic SQL from input fields | Flag as SQL injection risk — explain parameterized host variables |
166| `STOP RUN` inside nested `PERFORM` | Flag — causes program termination from a subroutine, not just the paragraph |
167| Missing `EVALUATE SQLCODE` after `EXEC SQL` | Flag — all DB2 operations must check `SQLCODE` |
168| Missing `RESP` on `EXEC CICS` | Flag — CICS errors must be handled via `RESP`/`RESP2`, not `ABEND` assumption |
169 
170---
171 
172## JCL Standards
173 
174```jcl
175//JOBNAME  JOB (ACCT),'DESCRIPTION',CLASS=A,MSGCLASS=X,
176//             NOTIFY=&SYSUID,MSGLEVEL=(1,1)
177//*--------------------------------------------------------------------*
178//* Step 1: Run the customer inquiry program                           *
179//*--------------------------------------------------------------------*
180//STEP1    EXEC PGM=CUSTINQ,REGION=0M
181//STEPLIB  DD   DSN=LOAD.LIBRARY,DISP=SHR
182//SYSOUT   DD   SYSOUT=*
183//SYSPRINT DD   SYSOUT=*
184//INPUT    DD   DSN=INPUT.DATASET,DISP=SHR
185//OUTPUT   DD   DSN=OUTPUT.DATASET,
186//             DISP=(NEW,CATLG,DELETE),
187//             SPACE=(CYL,(10,5),RLSE),
188//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
189```
190 
191---
192 
193## Assembler (HLASM) Standards
194 
195- Register conventions: R0–R1 = parameters/return, R13 = save area, R14 = return address, R15 = return code / entry point
196- Always save registers at entry with `STM R14,R12,12(R13)` and restore with `LM R14,R12,12(R13)`
197- Use standard save area linkage: `SAVE (14,12)` / `RETURN (14,12)`
198- Macro invocations should be documented with a preceding comment explaining the purpose
199- DSECT definitions for mapped storage areas must be named descriptively
200 
201---
202 
203## Modernization Context
204 
205When analyzing COBOL for modernization:
206 
2071. **Identify bounded contexts** — map program groups to Java microservice candidates
2082. **Extract business rules** — separate computation logic from I/O and infrastructure
2093. **Flag semantic risks** — where COBOL numeric precision (`COMP-3`) differs from Java floating point, use `BigDecimal`
2104. **CICS = synchronous transaction** — maps to a synchronous REST endpoint or a queued command
2115. **Batch JCL job** — maps to a Spring Batch job with `ItemReader` / `ItemProcessor` / `ItemWriter`
2126. **VSAM KSDS** — maps to a relational table or key-value store depending on access pattern
2137. Always produce a **semantic risk matrix**: what was preserved, what changed, what requires human validation
214 
215---
216 
217## Test Conventions
218 
219When generating test artifacts for COBOL modernization:
220- Write Java tests that validate the extracted business rules against known input/output pairs derived from the COBOL logic
221- Use `@ParameterizedTest` with real data samples extracted from COBOL `WORKING-STORAGE` test values
222- Flag any numeric precision differences between COBOL packed decimal and Java `BigDecimal` in test assertions
223