Copilot instructions

1---
2applyTo: "**/*.cbl, **/*.jcl, **/*.asm, **/vsam/**, **/ims/**"
3description: "Extended mainframe standards covering JES2/JES3 job classes, VSAM access patterns, IMS DB/DC, IBM MQ, z/OS batch tuning, DFSORT, RACF security, and CICS resource definitions."
4---
5 
6# Mainframe Extended — Copilot Instructions
7 
8> Applied automatically for COBOL, JCL, Assembler, VSAM, and IMS source files. Extends mainframe.instructions.md with advanced z/OS subsystem patterns.
9 
10---
11 
12## JES2/JES3 — Job Classes and Priorities
13 
14### Job Card Standards
15 
16```jcl
17//PAYROLL1 JOB (FIN-001),'PAYROLL WEEKLY RUN',
18//             CLASS=B,
19//             MSGCLASS=X,
20//             MSGLEVEL=(1,1),
21//             NOTIFY=&SYSUID,
22//             PRTY=8,
23//             REGION=0M,
24//             TIME=(30,0)
25```
26 
27| Parameter | Usage |
28|-----------|-------|
29| `CLASS=A` | Short interactive/test jobs (< 5 min elapsed) |
30| `CLASS=B` | Medium batch jobs (5–30 min), non-priority |
31| `CLASS=C` | Long-running production batch (> 30 min) |
32| `CLASS=S` | STC (started task) — do not use in JOB cards |
33| `PRTY=1–15` | JES2 input priority; production jobs ≥ 8; test jobs ≤ 4 |
34| `TIME=(mm,ss)` | CPU time limit — always set to prevent runaway jobs |
35| `REGION=0M` | Uses installation-defined maximum region; preferred over a hardcoded value |
36 
37### JES3 Job Classes
38 
39In JES3 environments, job class maps to a device group: `CLASS=D` for tape jobs, `CLASS=T` for test. Confirm with your JES3 JCLOPTs member for the local definition.
40 
41---
42 
43## VSAM — Access Patterns and IDCAMS
44 
45### VSAM Dataset Types
46 
47| Type | Key Structure | Access Pattern | Java Equivalent |
48|------|-------------|---------------|----------------|
49| KSDS (Key-Sequenced) | Variable-length key | Random + sequential by key | HashMap + sorted map |
50| ESDS (Entry-Sequenced) | RBA (byte offset) | Sequential append; random by RBA | Append-only log / sequential file |
51| RRDS (Relative Record) | Relative record number | Direct by slot number | Array or DB table with surrogate key |
52 
53### IDCAMS Commands
54 
55```jcl
56//DEFVSAM  EXEC PGM=IDCAMS
57//SYSPRINT DD   SYSOUT=*
58//SYSIN    DD   *
59  DEFINE CLUSTER ( -
60    NAME(PROD.CUSTOMER.KSDS) -
61    INDEXED -
62    KEYS(10 0) -
63    RECORDSIZE(200 500) -
64    FREESPACE(20 10) -
65    SHAREOPTIONS(2 3) -
66    CYLINDERS(100 20) -
67    VOLUMES(PROD01) ) -
68  DATA ( NAME(PROD.CUSTOMER.KSDS.DATA) ) -
69  INDEX ( NAME(PROD.CUSTOMER.KSDS.INDEX) )
70/*
71```
72 
73### COBOL VSAM REWRITE Rules
74 
75```cobol
76* READ for UPDATE before REWRITE — mandatory
77       READ CUSTFILE INTO WS-CUSTOMER-RECORD
78           KEY IS WS-CUST-ID
79           INVALID KEY MOVE 4 TO WS-RETURN-CODE
80           NOT INVALID KEY
81               PERFORM 3000-UPDATE-RECORD
82       END-READ.
83 
84       3000-UPDATE-RECORD.
85      * Must REWRITE immediately after READ with UPDATE — no intervening I/O on same file
86           MOVE WS-NEW-BALANCE TO WS-CUST-BALANCE
87           REWRITE CUSTREC FROM WS-CUSTOMER-RECORD
88               INVALID KEY MOVE 8 TO WS-RETURN-CODE
89           END-REWRITE.
90```
91 
92Never issue `READ ... UPDATE` without a subsequent `REWRITE` or `UNLOCK`. An un-unlocked VSAM record holds a lock for the duration of the task — this causes ENQ conflicts on shared files.
93 
94---
95 
96## IMS DB — Hierarchical Data Model
97 
98### PCB/PSB/DBD Concepts
99 
100| Component | Purpose | Analogy |
101|-----------|---------|---------|
102| DBD (Database Definition) | Defines physical segment types and hierarchical relationships | Schema/DDL |
103| PCB (Program Communication Block) | One PCB per database accessed; defines segment access intent (PROCOPT) | JDBC Connection with permissions |
104| PSB (Program Specification Block) | Collection of PCBs for one application program | Spring Bean with multiple DataSource references |
105 
106### PROCOPT Values
107 
108| PROCOPT | Access | Use |
109|---------|--------|-----|
110| `G` | Get only (read) | Read-only programs |
111| `GU` | Get Unique | Random read by key |
112| `GN` | Get Next | Sequential read |
113| `I` | Insert | Insert only |
114| `D` | Delete | Delete only |
115| `R` | Replace (update) | Update only |
116| `A` | All | Full CRUD — use only when necessary |
117 
118### IMS DL/I Call Pattern (COBOL)
119 
120```cobol
121       WORKING-STORAGE SECTION.
122           EXEC DLI SCHD PSB(CUSTPSB) END-EXEC.
123 
124       01 CUST-SSA.
125          05 SSA-SEGNAME    PIC X(8)  VALUE 'CUSTSEG '.
126          05 SSA-BEGIN-PAREN PIC X    VALUE '('.
127          05 SSA-FIELD      PIC X(8)  VALUE 'CUSTID  '.
128          05 SSA-OPERATOR   PIC X(2)  VALUE '= '.
129          05 SSA-VALUE      PIC X(10) VALUE SPACES.
130          05 SSA-END-PAREN  PIC X    VALUE ')'.
131 
132       2000-GET-CUSTOMER.
133           MOVE WS-CUST-ID TO SSA-VALUE
134           EXEC DLI GU SEGMENT(CUSTSEG) INTO(WS-CUST-RECORD)
135               WHERE CUSTID = :SSA-VALUE
136           END-EXEC
137           IF DIBSTAT = 'GE'
138               MOVE 4 TO WS-RETURN-CODE
139           END-IF.
140```
141 
142---
143 
144## IMS DC — Message Processing
145 
146| Program Type | Trigger | Use Case |
147|-------------|---------|---------|
148| MPP (Message Processing Program) | IMS transaction code | Interactive online transaction |
149| BMP (Batch Message Processing) | Scheduled; can access IMS DB | Batch update with IMS DB access |
150| IFP (IMS Fast Path) | High-speed DEDB transactions | Ultra-high volume (> 10K TPS) |
151 
152### MPP Transaction Flow
153 
1541. Terminal input → IMS TM → Input queue → MPP scheduled in IMS region
1552. MPP issues `GU IOPCB` to get message from queue
1563. MPP processes; issues `ISRT IOPCB` to send response back
1574. IMS TM routes response to terminal
158 
159```cobol
160       2000-GET-INPUT.
161           EXEC DLI GU USING PCB(IOPCB)
162               SEGMENT(INMSEG) INTO(WS-INPUT-MSG)
163           END-EXEC.
164           IF IOAREAL(1:2) = 'QC'
165               EXEC DLI CHKP USING PCB(IOPCB) END-EXEC
166               STOP RUN
167           END-IF.
168```
169 
170---
171 
172## IBM MQ Series
173 
174### Key Concepts
175 
176| Concept | Description |
177|---------|------------|
178| Queue Manager | MQ server instance; name convention: `QM.{ENV}.{LOCATION}` (e.g., `QM.PROD.LONDON`) |
179| Local Queue | Queue owned by this queue manager; prefix `QL.` |
180| Remote Queue Definition | Pointer to queue on another QM; prefix `QR.` |
181| Transmission Queue | Holds messages in transit; prefix `QT.` |
182| Dead Letter Queue | Undeliverable messages; every QM must have one named `DLQ.{QMGR}` |
183| Channel | Communication path between queue managers; `TO.{TARGET-QMGR}` |
184 
185### Message Persistence
186 
187```
188MQMD.Persistence = MQPER_PERSISTENT (1)    -- Survives queue manager restart; use for financial messages
189MQMD.Persistence = MQPER_NOT_PERSISTENT (0) -- Lost on restart; use for audit/log-only messages
190```
191 
192Always use `MQPER_PERSISTENT` for messages that represent financial transactions, order state changes, or audit events.
193 
194### MQ + CICS Bridge Pattern (COBOL)
195 
196```cobol
197      * Put message to MQ from CICS
198           EXEC CICS PUT CONTAINER('MQMSG')
199               FROM(WS-MQ-PAYLOAD)
200               FLENGTH(WS-PAYLOAD-LEN)
201               CHANNEL('MQCHANNEL')
202           END-EXEC.
203 
204           EXEC CICS LINK PROGRAM('CKTI')
205               CHANNEL('MQCHANNEL')
206               RESP(WS-CICS-RESP)
207           END-EXEC.
208```
209 
210For new development, prefer the MQ CICS bridge (`CKTI`) over direct `MQPUT` within CICS to maintain unit-of-work consistency.
211 
212---
213 
214## z/OS Batch Tuning
215 
216### SMF Records for Batch Analysis
217 
218| SMF Record Type | Content | Use |
219|----------------|---------|-----|
220| Type 30 | Job/step accounting (CPU, I/O, elapsed time) | Identify slow steps |
221| Type 42 | VSAM statistics | VSAM buffer tuning |
222| Type 14/15 | Dataset open/close | Identify excessive dataset allocations |
223 
224```jcl
225//SMFPRINT EXEC PGM=IFASMFDP
226//SMFIN    DD   DSN=SYS1.MAN1,DISP=SHR
227//SMFOUT   DD   DSN=&&SMFWORK,DISP=(NEW,PASS),SPACE=(CYL,(10,5))
228//SYSIN    DD   *
229  INDD(SMFIN,OPTIONS(DUMP))
230  OUTDD(SMFOUT,TYPE(30))
231  DATE(2024001,2024365)
232/*
233```
234 
235### Checkpoint/Restart with SYSCHK DD
236 
237```jcl
238//BATCHJOB JOB (ACCT),'LONG RUNNING',CLASS=C
239//STEP1    EXEC PGM=LONGPROG,PARM='RESTART'
240//SYSCHK   DD   DSN=PROD.CHECKPOINT.DATA,
241//             DISP=(MOD,CATLG,KEEP),
242//             SPACE=(CYL,(1,1)),
243//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
244//CHECKPT  DD   SYSOUT=*
245```
246 
247In COBOL: use `RERUN ON SYSCHK EVERY 1000 RECORDS OF filename` in `ENVIRONMENT DIVISION` for checkpoint insertion.
248 
249### JES Spool Management
250 
251```jcl
252/* Limit SYSOUT — critical for high-volume batch */
253//SYSPRINT DD   SYSOUT=*,FREE=CLOSE
254//SYSOUT   DD   SYSOUT=(X,,9999)  /* Limit to 9999 lines */
255 
256/* Route SYSOUT to specific class for archival */
257//AUDITOUT DD   SYSOUT=A,DEST=ARCHIVER
258```
259 
260---
261 
262## SORT Utility — DFSORT / SYNCSORT
263 
264```jcl
265//SORTSTEP EXEC PGM=SORT
266//SYSOUT   DD   SYSOUT=*
267//SORTIN   DD   DSN=INPUT.DATASET,DISP=SHR
268//SORTOUT  DD   DSN=OUTPUT.SORTED,DISP=(NEW,CATLG,DELETE),
269//             SPACE=(CYL,(10,5),RLSE),
270//             DCB=(RECFM=FB,LRECL=100,BLKSIZE=0)
271//SYSIN    DD   *
272  SORT FIELDS=(1,10,CH,A,21,8,ZD,D)
273  INCLUDE COND=(51,2,CH,EQ,C'GB')
274  OUTREC FIELDS=(1,10,21,8,51,2,C'PROCESSED')
275  SUM FIELDS=(31,10,ZD)
276/*
277```
278 
279| Parameter | Meaning |
280|-----------|---------|
281| `FIELDS=(pos,len,fmt,dir)` | Sort key: position, length, format (`CH`=char, `ZD`=zoned decimal, `PD`=packed), direction (`A`/`D`) |
282| `INCLUDE COND=` | Filter records before sort |
283| `OUTREC FIELDS=` | Reformat output records |
284| `SUM FIELDS=` | Aggregate numeric fields with matching keys |
285| `OPTION EQUALS` | Preserve original order for equal keys |
286 
287---
288 
289## RACF Security
290 
291### Dataset Security
292 
293```
294/* Protect a new production dataset */
295ADDSD 'PROD.CUSTOMER.DATA.**' UACC(NONE) OWNER(PRODOWNR)
296PERMIT 'PROD.CUSTOMER.DATA.**' ID(PRODGRP) ACCESS(UPDATE)
297PERMIT 'PROD.CUSTOMER.DATA.**' ID(AUDITGRP) ACCESS(READ)
298PERMIT 'PROD.CUSTOMER.DATA.**' ID(BATCH01) ACCESS(ALTER)
299 
300/* RACF audit — log all access attempts */
301ALTDSD 'PROD.CUSTOMER.DATA.**' AUDIT(ALL(READ))
302```
303 
304### CICS Transaction Security
305 
306```
307/* Define CICS transaction in RACF */
308RDEFINE TCICSTRN CUSTINQ UACC(NONE)
309PERMIT CUSTINQ CLASS(TCICSTRN) ID(CICSTELR) ACCESS(READ)
310SETROPTS RACLIST(TCICSTRN) REFRESH
311```
312 
313All production CICS transactions must be defined in RACF class `TCICSTRN` with `UACC(NONE)`. Access only via named RACF groups — never via individual user IDs for transaction authorization.
314 
315---
316 
317## CICS Transaction Naming and Resource Definition
318 
319### Transaction Naming Convention
320 
321| Prefix | Usage |
322|--------|-------|
323| `C` + 3 chars | Customer-facing transactions (e.g., `CINQ`, `CUPD`) |
324| `B` + 3 chars | Batch-triggered CICS transactions |
325| `A` + 3 chars | Administration/operational transactions |
326| `Z` + 3 chars | Technical/infrastructure transactions (exclude from user menus) |
327 
328### CSD Resource Definition (DFHCSDUP)
329 
330```
331DEFINE TRANSACTION(CINQ)
332       PROGRAM(CUSTINQ)
333       TWASIZE(256)
334       TASKDATALOC(ANY)
335       TASKDATAKEY(USER)
336       STORAGECLEAR(NO)
337       RUNAWAY(5000)
338       SHUTDOWN(DISABLED)
339       STATUS(ENABLED)
340       DTIMEOUT(30)
341       GROUP(CUSTGRP)
342 
343DEFINE PROGRAM(CUSTINQ)
344       LANGUAGE(COBOL)
345       DATALOCATION(ANY)
346       EXECKEY(USER)
347       STATUS(ENABLED)
348       GROUP(CUSTGRP)
349```
350 
351- `RUNAWAY`: CPU time limit in milliseconds — always set; prevents runaway transactions consuming CPU
352- `DTIMEOUT`: Deadlock timeout in seconds — always set for transactions accessing shared resources
353- `TASKDATAKEY(USER)`: Prevents task data from being in CICS key storage — required for all application transactions
354