Copilot instructions

1---
2applyTo: "**/*.rpgle, **/*.rpg, **/*.clle, **/*.cl, **/*.dspf, **/*.pf, **/*.lf"
3description: "IBM i RPG IV/RPGLE coding conventions, ILE naming, DB2 for i SQL standards, job structure, error handling, and modernization patterns."
4---
5 
6# IBM i — Copilot Instructions
7 
8> Applied automatically when working with RPG IV, RPGLE, CL, DDS display files, physical files, and logical files. Loaded alongside copilot-instructions.md.
9 
10---
11 
12## RPG IV / RPGLE Free-Format Conventions
13 
14Always write new RPG code in **fully free format** (no `/free`/`/end-free` directives required in RPGLE 7.2+). For legacy fixed-format code being modified, use the existing format; for new code within a legacy program, wrap additions in `/free` / `/end-free`.
15 
16### Program Header Specification
17 
18```rpgle
19**FREE
20// ============================================================
21// Program  : CUSTINQ
22// Purpose  : Customer inquiry — retrieve customer by ID
23// Author   : Development Team
24// Date     : 2024-11-01
25// Called by: CSTMNU (interactive menu) / CUSTAPI (REST wrapper)
26// ============================================================
27Ctl-Opt DftActGrp(*No) ActGrp(*Caller) Option(*SrcStmt:*NoDebugIO);
28Ctl-Opt BndDir('ENTBNDDIR');
29Ctl-Opt Main(Main);
30```
31 
32### Mandatory `Ctl-Opt` Settings
33 
34| Option | Required Value | Reason |
35|--------|--------------|--------|
36| `DftActGrp` | `*No` | Prevents legacy activation group; enables ILE error handling |
37| `ActGrp` | `*Caller` or named group | Controls object lifecycle; do not use `*New` for service programs |
38| `Option(*SrcStmt)` | Always set | Enables source-level debugging |
39| `BndDir` | `'ENTBNDDIR'` (project binding directory) | Makes service programs available |
40 
41### Procedure Prototype and Interface Pattern
42 
43```rpgle
44// ---- Prototype (in QRPGLESRC or copybook CUSTPRT) ----
45Dcl-Pr GetCustomer ExtPgm('CUSTINQ');
46  PCustomerId    Char(10) Const;
47  PCustomerName  Char(50);
48  PReturnCode    Int(10);
49End-Pr;
50 
51// ---- Procedure Interface ----
52Dcl-Pi Main;
53  PCustomerId    Char(10) Const;
54  PCustomerName  Char(50);
55  PReturnCode    Int(10);
56End-Pi;
57```
58 
59### Data Structure Naming
60 
61```rpgle
62// Externally described data structure — preferred over hardcoded fields
63Dcl-Ds CustRec ExtName('CUSTPF') Qualified;
64End-Ds;
65 
66// Program status data structure
67Dcl-Ds PSDS PSDS Qualified;
68  PgmName    *Proc;
69  StatusCode *Status;
70  MsgId      Char(7)  Pos(40);
71End-Ds;
72```
73 
74---
75 
76## ILE Naming — Service Programs, Modules, Binding Directories
77 
78| Object Type | Naming Convention | Example |
79|-------------|------------------|---------|
80| Module (`*MODULE`) | Verb+Noun, max 10 chars | `GETCUST`, `UPDORDER` |
81| Program (`*PGM`) | Uppercase, max 10 chars, matches source member | `CUSTINQ`, `ORDPRC` |
82| Service Program (`*SRVPGM`) | Domain prefix + function, max 10 chars | `CUSTSRV`, `PAYMTSRV` |
83| Binding Directory (`*BNDDIR`) | Project + `BNDDIR` suffix | `ENTBNDDIR`, `FINBNDDIR` |
84| Export list (`*.bnd`) | Same name as SRVPGM | `CUSTSRV.bnd` |
85 
86### Creating a Service Program
87 
88```cl
89/* Create module */
90CRTRPGMOD MODULE(ENTLIB/CUSTSRV) SRCFILE(QRPGLESRC) SRCMBR(CUSTSRV)
91           DBGVIEW(*SOURCE) OPTIMIZE(*FULL) OUTPUT(*NONE)
92 
93/* Create service program from module + export list */
94CRTSRVPGM SRVPGM(ENTLIB/CUSTSRV) MODULE(ENTLIB/CUSTSRV)
95          EXPORT(*SRCFILE) SRCFILE(QSRVSRC) SRCMBR(CUSTSRV)
96          BNDDIR(ENTLIB/ENTBNDDIR) ACTGRP(*CALLER)
97 
98/* Add to binding directory */
99ADDBNDDIRE BNDDIR(ENTLIB/ENTBNDDIR) OBJ((ENTLIB/CUSTSRV *SRVPGM))
100```
101 
102---
103 
104## CL Procedure Naming
105 
106| Object | Convention | Example |
107|--------|-----------|---------|
108| CL Program (`*PGM`) | Action + domain + suffix `C` | `CRTCUSTC`, `PURGLOGSCC` |
109| CL Command (`*CMD`) | Verb + Object, max 10 chars | `CRTCUST`, `PRGLOG` |
110| CL Module in ILE | Same as program, used in SRVPGM | `JOBSTRC` |
111 
112```cl
113PGM        PARM(&CUSTID &RETCODE)
114 
115DCL        VAR(&CUSTID)  TYPE(*CHAR) LEN(10)
116DCL        VAR(&RETCODE) TYPE(*INT)  LEN(4)
117DCL        VAR(&MSGID)   TYPE(*CHAR) LEN(7)
118 
119MONMSG     MSGID(CPF0000 MCH0000) EXEC(GOTO CMDLBL(ERRHANDLE))
120 
121/* Main logic */
122CALL       PGM(ENTLIB/CUSTINQ) PARM(&CUSTID *OMIT &RETCODE)
123 
124GOTO       CMDLBL(END)
125 
126ERRHANDLE:
127RCVMSG     MSGTYPE(*EXCP) MSGID(&MSGID)
128CHGVAR     VAR(&RETCODE) VALUE(-1)
129 
130END:
131ENDPGM
132```
133 
134---
135 
136## DDS Field Naming
137 
138### Physical File (PF) Standards
139 
140```dds
141     A          R CUSTREC                   TEXT('Customer Record')
142     A            CUSTID         10A         COLHDG('Customer' 'ID')
143     A            CUSTNM         50A         COLHDG('Customer' 'Name')
144     A            CUSTBAL        15P 2       COLHDG('Balance')
145     A            CRTDT           8S 0       COLHDG('Create' 'Date')
146     A          K CUSTID
147```
148 
149- Record format name: max 10 chars, uppercase, derived from file purpose
150- Field names: max 10 chars, uppercase; no leading/trailing spaces
151- All numeric monetary fields: packed decimal (`P`) with 2 decimal positions; never floating point
152- Date fields: 8-digit numeric (`S 0` or `L` with `DATFMT`)
153 
154### Logical File (LF) Standards
155 
156```dds
157     A          R CUSTNMR                   PFILE(CUSTPF)
158     A            CUSTNM
159     A            CUSTID
160     A            CUSTBAL
161     A          K CUSTNM
162     A          K CUSTID
163```
164 
165Logical files: prefix with `L` or domain abbreviation; always specify `PFILE`.
166 
167### Display File (DSPF) Standards
168 
169- Record format naming: screen purpose + format code (e.g., `CUSTFMT1`, `CUSTMSGS`)
170- Use `OVERLAY` indicator to avoid clearing screen between formats
171- All user input fields must have `CHECK(RZ)` to strip leading zeros from numeric input
172- Error messages through `ERRMSG` or `ERRMSGID` keywords, not hardcoded literals
173 
174---
175 
176## DB2 for i SQL Standards
177 
178### Schema vs Library
179 
180- In SQL context: use `SET SCHEMA` or fully qualify with schema name: `ENTSCHEMA.CUSTOMERS`
181- In native I/O context: library used directly — `ENTLIB/CUSTPF`
182- Do not mix native I/O and SQL on the same file within the same program without commit control alignment
183 
184### Parameterized SQL — Forbidden Pattern
185 
186```rpgle
187// WRONG — EXECUTE IMMEDIATE with string concatenation is FORBIDDEN
188SqlStmt = 'SELECT * FROM CUSTOMERS WHERE CUSTID = ''' + CustId + '''';
189Exec Sql Execute Immediate :SqlStmt;
190 
191// CORRECT — Parameterized with host variables
192Exec Sql
193  Select CustName, CustBal
194  Into   :WsCustName, :WsCustBal
195  From   ENTSCHEMA.CUSTOMERS
196  Where  CustId = :WsCustId;
197```
198 
199### SQL Error Handling
200 
201```rpgle
202Exec Sql
203  Select CustName Into :WsCustName
204  From ENTSCHEMA.CUSTOMERS
205  Where CustId = :WsCustId;
206 
207Select;
208  When SqlCode = 0;
209    // Success
210  When SqlCode = 100;
211    // Not found
212    ReturnCode = 4;
213  When SqlCode < 0;
214    // SQL error
215    ErrMsg = %Char(SqlCode);
216    ReturnCode = 12;
217EndSl;
218```
219 
220### JDBC vs Native I/O
221 
222| Scenario | Recommended Access Method |
223|----------|--------------------------|
224| New REST API exposing IBM i data | JDBC via IBM Toolbox for Java (`jt400.jar`) |
225| Existing RPG accessing PF directly | Native I/O (file declarations with F-specs) |
226| Cross-platform reporting | SQL over JDBC — use `SELECT` with explicit column list |
227| Batch record processing > 100K rows | Native I/O with sequential read for performance |
228 
229---
230 
231## IBM i Job Structure
232 
233Every scheduled batch job must have a corresponding job description:
234 
235```cl
236/* Create Job Description */
237CRTJOBD JOBD(ENTLIB/NIGHTBAT) JOBQ(ENTLIB/BATCHQ) TEXT('Nightly batch jobs')
238        OUTQ(ENTLIB/BATOUTQ) LOG(4 0 *NOLIST) LOGCLPGM(*YES)
239        INQMSGRPY(*SYSRPYL) ACGCDE('BATCHACG')
240 
241/* Submit to batch */
242SBMJOB CMD(CALL PGM(ENTLIB/NIGHTPRC)) JOB(NIGHTPRC) JOBD(ENTLIB/NIGHTBAT)
243        JOBQ(ENTLIB/BATCHQ) MSGQ(*JOBD) HOLD(*NO)
244```
245 
246- Every production batch job must specify `JOBD` explicitly — never rely on defaults
247- `LOG(4 0 *NOLIST)` for production; `LOG(4 0 *SECLVL)` for debugging
248- High-volume jobs: specify subsystem routing entry to dedicated batch subsystem
249 
250---
251 
252## Error Handling — Monitor-On vs Message Handling
253 
254### Preferred: Monitor-On in ILE RPG
255 
256```rpgle
257Monitor;
258  Exec Sql
259    Insert Into ENTSCHEMA.AUDIT_LOG
260    Values (:WsAuditRec);
261  On-Error 802;
262    // Duplicate key — record already exists, acceptable
263    ReturnCode = 0;
264  On-Error;
265    // All other SQL errors
266    ReturnCode = 12;
267    Leave;
268EndMon;
269```
270 
271### CL Message Handling
272 
273```cl
274CALL       PGM(ENTLIB/CUSTUPD) PARM(&CUSTID &RETCODE)
275MONMSG     MSGID(CPF9999) EXEC(DO)
276  RCVMSG   MSGTYPE(*EXCP) MSGID(&ERRMSGI) MSGDTA(&ERRMSGD)
277  SNDPGMMSG MSGID(&ERRMSGI) MSGF(QCPFMSG) MSGDTA(&ERRMSGD) +
278              TOPGMQ(*CALLER) MSGTYPE(*DIAG)
279  CHGVAR   VAR(&RETCODE) VALUE(-1)
280ENDDO
281```
282 
283---
284 
285## Conversion Patterns: RPG to REST API (IWS)
286 
287IBM i Integrated Web Services (IWS) exposes RPG programs as REST endpoints without rewriting them:
288 
2891. Program must use `EXTPGM` prototype with `CONST` input parameters and output parameters
2902. Register in IWS: `WRKWTR` → Web Services → Create Web Service → Program call
2913. XML/JSON payload mapping is auto-generated from parameter data types
2924. For production: deploy via IWS deployment manager; version with `/v1/` prefix in URI
2935. Authentication: IBM i digital certificate + HTTP Basic Auth at minimum; OAuth 2.0 preferred
294 
295### RPG to Java Bridge (JDBC)
296 
297```java
298// IBM Toolbox for Java — jt400.jar
299import com.ibm.as400.access.*;
300 
301AS400 system = new AS400("ibmi-host.internal", "SVCUSER", credentials);
302ProgramCall pgm = new ProgramCall(system);
303pgm.setProgram("/QSYS.LIB/ENTLIB.LIB/CUSTINQ.PGM");
304ProgramParameter[] params = {
305    new ProgramParameter(AS400Text.toBytes("CUST0012345", 10)),  // Input: customer ID
306    new ProgramParameter(50),                                      // Output: customer name
307    new ProgramParameter(4)                                        // Output: return code
308};
309pgm.setParameterList(params);
310if (!pgm.run()) {
311    throw new RuntimeException("CUSTINQ failed: " + pgm.getMessageList()[0].getText());
312}
313String custName = new AS400Text(50, system).toObject(params[1].getOutputData()).toString().trim();
314```
315 
316---
317 
318## Modernization Risk Classification
319 
320### Tight-Coupling Indicators — High Risk to Modernize
321 
322| Indicator | Risk | Action |
323|-----------|------|--------|
324| `CALL` to > 5 external programs in procedure | HIGH | Map call graph before modernizing |
325| Native I/O with no SQL equivalent | HIGH | Create SQL view before modernizing |
326| `DSPATR(PR)` (protected display fields) driven by runtime data | MEDIUM | Map UI logic carefully |
327| `INFDS` used for I/O error trapping | MEDIUM | Replace with structured error handling in Java |
328| `%PARMS` (parameter count checking) for optional params | LOW | Implement method overloading in Java |
329 
330### Data Dependency Analysis
331 
332Before modernizing an RPG program, run:
333 
334```sql
335-- Find all physical files accessed by this program (via IFS catalog)
336SELECT SYSTEM_TABLE_NAME, SYSTEM_TABLE_SCHEMA, TABLE_TYPE
337FROM QSYS2.SYSTABLES
338WHERE SYSTEM_TABLE_NAME IN (
339  SELECT OBJECT_NAME FROM QSYS2.OBJECT_REFERENCES
340  WHERE OBJECT_LIBRARY = 'ENTLIB' AND OBJECT_NAME = 'CUSTINQ' AND OBJECT_TYPE = '*PGM'
341);
342```
343 
344See `.github/agents/modernization-expert.agent.md` for the IBM i modernization agent.
345