Every IBM i shop has one. A program written in 1989 by someone who has since retired to Benidorm. It works, it's important, and nobody wants to touch it because it's full of MOVEL, KLIST and *IN90. Today we're going to touch it. Carefully. With BOB holding the torch and our AGENTS.MD keeping score.
In this lesson you'll:
- Decide when a conversion is worth doing, and when it isn't
- Find out which BOB feature actually does the conversion (spoiler: it's not
/review_rpg) - Follow a safe workflow: a copy, conversion rules, the conversion, a review, an
*EVENTFcompile and a regression test - Walk through a real before-and-after example, including the
MOVEandMOVELtraps that catch out humans and AI alike - Score the result against the
AGENTS.MDfrom the previous lesson
If you're new here, start with Why does BOB use IBM i Mapepire?, How does BOB talk to your IBM i System? and Teaching BOB your shop's rules. This lesson uses the QBOBSRC/AGENTS.MD, the approval settings and the private temp library we set up last time. Kettle on.
Heads up: As usual, I quote IBM's docs where they say something, and mark my own reasoning as reasoning. Anything marked [CHECK] is worth testing on your own system. The example programs are written to compile, but I haven't compiled them on your system with your files, so treat them as a worked example, not a drop-in.
1. Why convert? And when not to
Let's be honest about the reasons first.
Good reasons to convert to fully free-form:
- People. Developers who learned Java, Python or Node.js at university can read free-form RPG. Column-sensitive C-specs, not so much.
- The language moved on. Fully free-form (
**FREE) has been around since IBM i 7.3 (and 7.2 with PTFs), and the newer features and examples all assume free-form. Mixing fixed and free in one member works, but it's harder to read than either. - Tooling. Modern editors, linters, Git diffs and, yes, AI assistants all work better on free-form code.
- Your standards say so. Our lesson 3
AGENTS.MDsays "New and changed RPG is fully free-form." If you're changing a program anyway, converting it first is the cleanest way to follow that rule.
Reasons to leave it alone (for now):
- It's not changing. A stable program that nobody touches doesn't get any better by being converted. It just gets riskier for a week.
- You can't test it. If you don't have a way to prove the converted program behaves the same, you're not converting, you're gambling. Build the test first (see section 4, step 6).
- It's an RPG cycle program with heavy I/O specs, and nobody on the team understands the cycle. BOB can handle these (see section 2), but you still have to review the result.
- It's month-end week. Obviously.
My rule of thumb: convert a program when you're about to change it, and never in the same step as the change. Convert first, prove it's identical, commit. Then make your change. That one rule runs through this whole lesson.
2. What BOB actually gives you (and the bit that surprised me)
When I planned this lesson, I thought /review_rpg would do the conversion. It doesn't. Checking IBM's docs, the conversion work is split like this:
| BOB feature | What it does | Where it's available |
|---|---|---|
| RPG Modernization workflow | "Convert OPM and fixed-format ILE RPG source to modern free-format RPG." This is the converter. | Local or Library List workspace, when connected |
/review_rpg | Reviews RPG source and reports issues by severity, plus a modernization roadmap. It reviews, it doesn't convert. | IBM i Developer mode, connected |
Skills such as rpg-fixed-to-free, rpg-indicators, rpg-refactor-legacy, rpg-opm-to-ile, rpg-legacy-specs | Built-in RPG know-how that BOB loads when a task needs it | IBM i Developer mode |
convert_rpg_source tool | Runs CVTRPGSRC, IBM's OPM RPG to ILE RPG converter | IBM i modes |
The RPG Modernization workflow
IBM describes workflows as a mix of agentic steps (run by subagents or subtasks, where BOB reasons and uses tools) and non-agentic steps that "perform deterministic operations that reduce token consumption and produce more consistent and predictable results." For conversion, that's exactly what you want: as much predictability as possible.
According to IBM's docs, the RPG Modernization workflow:
- Converts OPM RPG (RPG II, RPG III, RPG/400) to ILE free-format, and ILE fixed-format to ILE free-format
- Detects the RPG variant automatically and picks the right conversion path
- Detects cycle programs (those with primary or secondary files) and loads the
rpg-cycle-explainedskill for every conversion step - Converts in two phases:
- Phase 1 externalizes I-specs (input specifications) and O-specs (output specifications)
- Phase 2 converts the remaining fixed-format H, F, D and C specs to free-format
- Can run an optional pre-conversion compile to check the source compiles before it starts
- Produces a summary report at the end
You can start it in two ways:
- Click the Start Workflow button at the top of the chat, choose the workspace, then click Start on RPG Modernization.
- Just ask. If BOB thinks your request fits a workflow, it suggests one in the chat with a Start workflow button.
Two things to note:
- IBM says "most IBM i workflows are only visible and available to Bob when connected to an IBM i." No connection, no workflow.
- It's available in the Local and Library List workspaces, not the IFS Working Directory workspace.
[CHECK] IBM's docs don't say whether the workflow overwrites the member in place or writes somewhere else. That's exactly why the safe workflow below always starts with a copy.
/review_rpg
In IBM i Developer mode, /review_rpg takes an RPG source (.RPGLE, .SQLRPGLE, .RPG, .RPG36 or .RPG38), detects whether it's fixed, free or mixed format, and reviews syntax and format, coding standards, error handling, security, performance and database operations, and modernization opportunities. The report has sections for Detected Format, Summary, Critical Issues, Major Issues, Minor Issues and a Modernization Roadmap. For example:
We'll use it twice: before conversion (to see what we're dealing with) and after (as a second pair of eyes on the result).
What BOB can and can't do
Things BOB can do, according to the docs: convert the source, use its RPG skills, compile through your Code for IBM i actions, and read the compile errors back (we covered the *EVENTF route in lesson 2).
Things it can't do for you, by my reasoning:
- Know your business. It doesn't know that the caller of ORD100R relies on positions 44-50 of a message field. You do (or your tests do).
- Prove equivalence. A clean compile proves the code is valid RPG. It doesn't prove it does the same thing. Only tests do that.
- Take responsibility. BOB runs as your user profile and changes your source. The approval cards are there so you read the diff before it's written. Read it.
3. Add conversion rules to AGENTS.MD
Our lesson 3 AGENTS.MD is written for new and changed code. A conversion is different: the goal is identical behaviour, not better code. If you don't say so, BOB will very sensibly apply your standards (SQL instead of record-level access, MONITOR blocks and so on) and you'll end up with a rewrite instead of a conversion.
There's also a clash: lesson 3 says "Compile into ORDLIB only." For conversions we want a test library. So add a section to ORDLIB/QBOBSRC/AGENTS.MD:
- A conversion must not change behaviour. Same parameters, same files,
same results, same messages, including odd legacy behaviour.
- Convert only. Do not replace record-level access with SQL, add MONITOR
blocks, rename parameters, or "fix" logic during a conversion.
List suggested improvements in your summary instead. They go in a
separate, tested change.
- Work on the copy in ORDTEST/QRPGLESRC. Compile conversions into ORDTEST
only (the one exception to the Compiling rule). Never change the
original member in ORDLIB during a conversion.
- Translate MOVE and MOVEL exactly. MOVEL without (P) does NOT clear the
rest of the target, and MOVE right-aligns. Comment every place where
legacy behaviour is kept on purpose.
- Replace numbered indicators with %FOUND, %EOF, %ERROR or named
indicators. *INLR is allowed.
- Replace KLIST/KFLD with a LIKEREC(...:*KEY) data structure and %KDS,
or a key list in brackets.
- Add the standard comment header with a Changes line for the conversion.
- Before finishing: compile with OPTION(*EVENTF), run /review_rpg on the
result, and list every behaviour difference you know of.
Every line is short, concrete and testable, just like last time. The MOVE/MOVEL rule is there because that's where conversions go wrong (section 5 shows why).
Start a new task after saving, so the updated rules are picked up.
4. The safe conversion workflow
Here's the whole flow at a glance:
Step 1: Make a copy
For a Library List workspace, use a test library. Run these yourself (or let BOB run them, and approve each one):
CRTSRCPF FILE(ORDTEST/QRPGLESRC) RCDLEN(112)
CPYSRCF FROMFILE(ORDLIB/QRPGLESRC) TOFILE(ORDTEST/QRPGLESRC) FROMMBR(ORD100R)
CPYSRCF copies the member with the same name and keeps the source type. RCDLEN(112) gives you 100 characters of source per line, which matches our lesson 3 rule of a maximum line length of 100. [CHECK] If your existing QRPGLESRC files are 92 or 112 long, match them.
For a Local workspace with Git, it's even easier:
Git gives you the diff and the "undo" for free. I'd use Git for anything that matters.
Step 2: Capture a baseline
Before BOB touches anything, compile the original in the test library and record what it does. You'll need this to prove the conversion later:
I compile the original as ORD100RO (O for original), so both versions can sit side by side. More on that in step 6.
Step 3: Review the original
Read the Detected Format and Modernization Roadmap. It tells you what you're dealing with (indicators, MOVEs, KLISTs) before the conversion starts. Save the report somewhere: it's a nice "before" picture for the change record.
Step 4: Run the RPG Modernization workflow
Click Start Workflow, choose the Library List (or Local) workspace, and start RPG Modernization on ORDTEST/QRPGLESRC/ORD100R. Say yes to the pre-conversion compile. If the original doesn't compile, you want to know now, not after the conversion.
When the approval card for writing the member appears, read the diff. Check the things in section 5's table. This is the most important minute of the whole lesson.
Step 5: Compile with *EVENTF and review again
Or use your normal Code for IBM i compile action, which is what our AGENTS.MD asks BOB to do. With *EVENTF, errors come back into VS Code (and into BOB, as we saw in lesson 2). Then:
Expect the Critical and Major sections to be much quieter than before. If it reports something that's also in the original, that's a "separate change" item, not a conversion bug.
Step 6: Regression test (the bit people skip)
Comparing the source line by line is pointless: of course it's different, that's the point! What you compare is behaviour. Call both programs with the same inputs and compare every output.
Here's a tiny ILE CL harness for ORD100R. Note how I fill the message parameter with Xs before the call. That's deliberate: it exposes any difference in how the two versions treat "leftover" data in the field (you'll see why in section 5).
DCL VAR(&CUSTC) TYPE(*CHAR) LEN(7)
DCL VAR(&CUST) TYPE(*DEC) LEN(7 0)
DCL VAR(&STAT1) TYPE(*CHAR) LEN(1)
DCL VAR(&CNT1) TYPE(*DEC) LEN(5 0)
DCL VAR(&TOT1) TYPE(*DEC) LEN(11 2)
DCL VAR(&MSG1) TYPE(*CHAR) LEN(50)
DCL VAR(&STAT2) TYPE(*CHAR) LEN(1)
DCL VAR(&CNT2) TYPE(*DEC) LEN(5 0)
DCL VAR(&TOT2) TYPE(*DEC) LEN(11 2)
DCL VAR(&MSG2) TYPE(*CHAR) LEN(50)
DCL VAR(&FILL) TYPE(*CHAR) LEN(50) +
VALUE('XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
CHGVAR VAR(&CUST) VALUE(&CUSTC)
CHGVAR VAR(&MSG1) VALUE(&FILL)
CHGVAR VAR(&MSG2) VALUE(&FILL)
CALL PGM(ORDTEST/ORD100RO) PARM(&CUST &STAT1 &CNT1 &TOT1 &MSG1)
CALL PGM(ORDTEST/ORD100R) PARM(&CUST &STAT2 &CNT2 &TOT2 &MSG2)
IF COND(&STAT1 *EQ &STAT2 *AND &CNT1 *EQ &CNT2 *AND +
&TOT1 *EQ &TOT2 *AND &MSG1 *EQ &MSG2) +
THEN(SNDPGMMSG MSG('ORD100R: identical'))
ELSE CMD(SNDPGMMSG MSG('ORD100R: DIFFERENT! Old: ' *CAT +
&MSG1 *CAT ' New: ' *CAT &MSG2))
ENDPGM
Compile it as ORDTEST/CMPORD100 (type CLLE) and call it for a handful of customers:
The customer number goes in as a 7-character string because a numeric literal on a command line CALL is passed as packed (15 5), which wouldn't match the program's (7 0) parameter. The CHGVAR converts it.
Pick your test customers deliberately:
- A customer that doesn't exist (the "Not found" path)
- A customer with no open orders
- A customer with one open order, and one with lots
- A customer with closed orders only (status not
'O') - Your biggest customer (the one where totals are largest)
Yes, the harness hard-codes ORDTEST, which breaks the "No hard-coded library names" CL rule. It's a throwaway test tool, not application code, and the library names are the whole point. Tell BOB that if you ask it to write one. (In the next lesson we'll do this properly with RPGUnit.)
Step 7: Promote, then change
Only when every test says identical does the converted member go back through your normal change process (Git merge, or your change management tool). The real change you wanted to make in the first place is a separate step, with its own tests.
5. The worked example: ORD100R
Here's our victim. It's a small but very typical program: given a customer number, it checks the customer exists, counts their open orders and totals them, and builds a message with the customer name and number.
The files it uses (described in DDS, as you'd expect for 1999):
CUSTMAST, record formatCUSTREC, keyCMCUST(7,0 packed), withCMNAME(30 characters)ORDHDR, record formatORDREC, keysOHCUST(7,0 packed) andOHSTAT(1 character), withOHTOTAL(9,2 packed)
[CHECK] These are my example files. On your system, runDSPFFDon each file to check the field names, types and record format names before you rely on any conversion.LIKERECneeds the record format name, not the file name.
Before: fixed-format RPG IV
* ORD100R - Count and total open orders for a customer
* Written 1999 by someone who has since retired to Benidorm
FCUSTMAST IF E K DISK
FORDHDR IF E K DISK
D OpenTotal S 11P 2
D OrderCount S 5P 0
D CustChr S 7A
D WStat S 1A
C *ENTRY PLIST
C PARM PCUSTNO 7 0
C PARM PSTATUS 1
C PARM PCOUNT 5 0
C PARM PTOTAL 11 2
C PARM PMSG 50
C ORDKEY KLIST
C KFLD PCUSTNO
C KFLD WSTAT
*
C MOVE '0' PSTATUS
C Z-ADD 0 PCOUNT
C Z-ADD 0 PTOTAL
C PCUSTNO CHAIN CUSTMAST 90
C *IN90 IFEQ *ON
C MOVE '1' PSTATUS
C MOVEL(P) 'Not found' PMSG
C ELSE
C MOVE 'O' WSTAT
C Z-ADD 0 OPENTOTAL
C Z-ADD 0 ORDERCOUNT
C ORDKEY SETLL ORDHDR
C ORDKEY READE ORDHDR 91
C *IN91 DOWEQ *OFF
C ADD OHTOTAL OPENTOTAL
C ADD 1 ORDERCOUNT
C ORDKEY READE ORDHDR 91
C ENDDO
C Z-ADD ORDERCOUNT PCOUNT
C Z-ADD OPENTOTAL PTOTAL
C MOVE PCUSTNO CUSTCHR
C MOVEL CMNAME PMSG
C MOVE CUSTCHR PMSG
C ENDIF
*
C SETON LR
C RETURN
The column positions matter in fixed format, so if you type this in, copy it exactly (BOB's not the only one who can get columns wrong).
After: fully free-form
// ---------------------------------------------------------------
// Program : ORD100R
// Purpose : Count and total open orders for a customer
// Author : Unknown (retired to Benidorm) Created : 1999
// Changes : 2026-11-19 Nick CHG-0042 Converted to fully free-form,
// behaviour unchanged
// ---------------------------------------------------------------
ctl-opt dftactgrp(*no) actgrp(*new) option(*srcstmt:*nodebugio);
dcl-f custmast keyed;
dcl-f ordhdr keyed;
dcl-pi *n;
pCustNo packed(7:0);
pStatus char(1);
pCount packed(5:0);
pTotal packed(11:2);
pMsg char(50);
end-pi;
dcl-s openTotal packed(11:2);
dcl-s orderCount packed(5:0);
dcl-s custChr char(7);
dcl-ds ordKey likerec(ordrec : *key);
pStatus = '0';
pCount = 0;
pTotal = 0;
chain (pCustNo) custmast;
if not %found(custmast);
pStatus = '1';
pMsg = 'Not found';
else;
ordKey.ohCust = pCustNo;
ordKey.ohStat = 'O';
openTotal = 0;
orderCount = 0;
setll %kds(ordKey) ordhdr;
reade %kds(ordKey) ordhdr;
dow not %eof(ordhdr);
openTotal += ohTotal;
orderCount += 1;
reade %kds(ordKey) ordhdr;
enddo;
pCount = orderCount;
pTotal = openTotal;
// Was: MOVE PCUSTNO CUSTCHR (same result for zero and positive numbers)
custChr = %editc(pCustNo : 'X');
// Was: MOVEL CMNAME PMSG + MOVE CUSTCHR PMSG. Neither cleared PMSG, so
// positions 31-43 keep whatever the caller passed in. Kept on purpose:
// conversion = identical behaviour. Fix it in a separate, tested change.
%subst(pMsg : 1 : %len(cmName)) = cmName;
%subst(pMsg : %len(pMsg) - %len(custChr) + 1) = custChr;
endif;
*inlr = *on;
return;
What changed, line by line
This is the table I keep next to me when I read a conversion diff, whether a person or BOB wrote it:
| Fixed format | Free format | Same behaviour? |
|---|---|---|
H DFTACTGRP(*NO) ACTGRP(*NEW) ... | ctl-opt dftactgrp(*no) actgrp(*new) ...; | Yes |
F CUSTMAST IF E K DISK | dcl-f custmast keyed; | Yes. Input, externally described and DISK are the defaults for dcl-f. |
*ENTRY PLIST with PARM fields defined in C-specs | dcl-pi *n; ... end-pi; | Yes, if the types match. Numeric fields defined on a C-spec are packed, so PCUSTNO 7 0 becomes packed(7:0), not zoned or int. |
KLIST / KFLD | dcl-ds ordKey likerec(ordrec : *key); with %kds(ordKey) | Yes. The work field WSTAT disappears: the status goes straight into ordKey.ohStat. LIKEREC data structures are automatically qualified, hence ordKey. in front. |
CHAIN ... 90 then *IN90 IFEQ *ON | chain (pCustNo) custmast; then if not %found(custmast); | Yes. The indicator in the HI position (71-72) on CHAIN is set on when the record is not found. I put the key in brackets because IBM's docs say a key list in free-form only has to match the key's type, not its exact length. |
READE ... 91 and DOWEQ *OFF | reade ...; then dow not %eof(ordhdr); | Yes. The indicator in the EQ position (75-76) on READE is set on at end of file. |
MOVEL(P) 'Not found' PMSG | pMsg = 'Not found'; | Yes. (P) pads with blanks, and so does assignment. |
ADD OHTOTAL OPENTOTAL | openTotal += ohTotal; | Not quite. A fixed-form ADD that overflows is truncated by default (TRUNCNBR(*YES)). An expression signals an overflow error. Here openTotal is 11,2 and orderCount is 5,0, so you'd need 99,999+ open orders for one customer to notice. Know it, write it down, move on. |
MOVE PCUSTNO CUSTCHR | custChr = %editc(pCustNo : 'X'); | For zero and positive numbers, yes. MOVE from numeric to character produces the zoned digits, right-aligned. %editc(...:'X') gives the same digits with leading zeros. For a negative number, MOVE puts the sign in the zone of the last digit (so -123 ends in L), and %editc 'X' doesn't. A customer number is never negative here, so I'm happy, but it's exactly the kind of thing to check. |
MOVEL CMNAME PMSG | %subst(pMsg : 1 : %len(cmName)) = cmName; | Yes, and this is the trap. MOVEL without (P) only replaces the leftmost 30 positions of the 50-character PMSG. Positions 31-50 keep whatever was there. |
MOVE CUSTCHR PMSG | %subst(pMsg : 44) = custChr; (written as %len(pMsg) - %len(custChr) + 1) | Yes. MOVE without (P) right-aligns and only replaces the rightmost 7 positions (44-50). |
SETON LR | *inlr = *on; | Yes |
The MOVEL trap in detail
Look at what the old code does to PMSG for a found customer:
MOVEL CMNAME PMSGwrites the name into positions 1-30. Positions 31-50 are untouched.MOVE CUSTCHR PMSGwrites the customer number into positions 44-50.- So positions 31-43 still contain whatever the caller passed in.
If the caller passes a blank field, you get "name ... 0001234" and everyone's happy. If the caller reuses the field from a previous call, you get leftover rubbish in the middle. That's a bug, but it's a 1999 bug that callers may now depend on, and it's not the conversion's job to fix it.
The tempting conversion is:
%subst(pMsg : 44) = custChr;
It's shorter, it's cleaner, and it's different: it blanks positions 31-43. That's exactly the sort of "improvement" that sneaks into a conversion, whether written by a tired human or an eager AI. And it's exactly what our regression harness catches, because it fills &MSG1 and &MSG2 with Xs before calling. The old program returns Xs in positions 31-43 and the "clean" version returns blanks. DIFFERENT!
That's why our conversion rules say "Translate MOVE and MOVEL exactly" and "comment every place where legacy behaviour is kept on purpose."
The separate, tested change
Once the converted version is proven identical and promoted, then you fix the message, as its own change with its own ticket:
...
pMsg = cmName;
%subst(pMsg : %len(pMsg) - %len(custChr) + 1) = custChr;
And you update the harness to expect blanks in 31-43, and tell the callers. That's the difference between a refactor and a surprise.
6. Keeping score against AGENTS.MD
I promised at the end of lesson 3 that we'd keep score. Here's the converted ORD100R against the AGENTS.MD rules:
| AGENTS.MD rule (lesson 3) | Converted ORD100R | Score |
|---|---|---|
First line is **FREE, no H/F/D/C specs | Yes | |
| No GOTO, TAG or CABxx | None in the original either | |
| No numbered indicators | *IN90 and *IN91 gone; %found and %eof used. *INLR is not a numbered indicator. | |
ctl-opt dftactgrp(*no) actgrp(*new) option(*srcstmt:*nodebugio) | Yes, carried over from the H-spec | |
| Naming: ORDnnnR | ORD100R | |
| Comment header with a Changes line | Added, with ticket CHG-0042 | |
Declare everything with dcl-*, qualified DS | Yes. LIKEREC data structures are qualified automatically. | |
| Indent 2 spaces, lower-case keywords, max 100 characters | Yes | |
| Return a status parameter ('0' ok, '1' error) | The original already did this. Nice work, 1999. | |
| Variables in camelCase | Mostly. pCustNo, openTotal. File fields keep their DDS names. | |
| Prefer embedded SQL over record-level access | Still record-level access | |
Wrap file work in MONITOR / ON-ERROR, log with logError() | No MONITOR yet | |
| Use subprocedures, not subroutines | No subroutines at all | |
Compile with *EVENTF | Yes | |
| Never touch production libraries | Everything happened in ORDTEST |
Thirteen ticks and two deliberate pauses. The pauses aren't failures. They're the "separate, tested change" list, and BOB's summary (we asked for it in the conversion rules) should list them as suggestions.
If BOB's version scores worse than this, don't fix it by hand in silence. Improve the AGENTS.MD so the next conversion is better. That's the whole point of keeping score.
7. Other conversion tools worth knowing
BOB isn't the only way to convert, and for big batches you may want a second opinion. These are the ones I could verify:
| Tool | Type | What it converts | Notes |
|---|---|---|---|
| IBM RDi "Convert Selection to Free Form" | IBM, part of RDi | C-specs only | Leaves H, F, D and P specs as fixed. Useful, but only half the job. |
CVTRPGSRC | IBM, on IBM i | OPM RPG to ILE RPG (fixed format) | A first step for RPG III code, not a free-form converter. BOB's convert_rpg_source tool runs it. |
| RPG Toolbox (Fortra, formerly HelpSystems/Linoma) | Commercial | Fixed to free, including fully free (RPGWIZ FMTCALC(*FREE2) or *FREE3) | Long-standing commercial tool with an RDi plugin. |
| ARCAD Transformer RPG | Commercial | Fixed to fully free-form | Part of the ARCAD modernization suite. |
| JCRCMDS by Craig Rutledge | Free (jcrcmds.com) | JCR5FREE (C-specs), JCRHFD (H/F/D to DCL-*), plus JCRFREESS side-by-side viewer | Green-screen commands, much loved. |
| vscode-rpgfree by Brian Garland | Free, open source | "Convert to Free Format" from a selection or the whole source | VS Code extension. [CHECK] availability in the Open VSX registry if your BOB install uses it. Its web version (rpgfreeweb) is archived. |
Whatever you use, the safe workflow in section 4 doesn't change. Copy, convert, compile, review, regression test. A tool can't skip the test for you, no matter who sells it.
8. Hands-on exercise: convert ORD100R
Allow about 45 minutes and two cups of tea.
- Set up the files. In a development library, create
CUSTMASTandORDHDR(DDS or SQL, with the fields and keys from section 5) and add a few rows: one customer with three open orders, one with only closed orders, one with none. - Create the original. Copy the "before" program into a member
ORD100R(typeRPGLE) inORDTEST/QRPGLESRC. Compile it asORD100RO. - Update AGENTS.MD. Add the conversion rules from section 3 and start a new task in IBM i Developer mode.
- Review first. Run
/review_rpgon the member and save the report. - Convert. Start the RPG Modernization workflow on the member, with the pre-conversion compile switched on. Read the diff before you approve it. Did BOB translate
MOVEL CMNAME PMSGexactly, or did it "tidy" it? - Compile and review. Compile with
OPTION(*EVENTF)asORD100R, then run/review_rpgagain. Compare the two reports. - Prove it. Build the
CMPORD100harness and run it for every test customer, plus one that doesn't exist. Every call should say identical. - Break it on purpose. Change the converted code to
pMsg = cmName;, recompile, and run the harness again. Watch it say DIFFERENT! Then put it back. Now you trust your harness. - Keep score. Fill in the section 6 table for BOB's version. Anything below thirteen ticks? Add a rule to
AGENTS.MD.
9. Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| I can't find the RPG Modernization workflow | You're not connected to IBM i, or you're in the IFS Working Directory workspace. Connect and switch to Local or Library List. |
/review_rpg isn't there | It's an IBM i Developer mode command. Switch mode, and check you're connected. |
/review_rpg rejects my member | It only accepts .RPGLE, .SQLRPGLE, .RPG, .RPG36 and .RPG38. Check the member's source type. |
| BOB swaps record-level access for SQL, or adds MONITOR blocks | Your lesson 3 "new code" rules are winning. Add the Conversions section from section 3 and start a new task. |
RNF7030 (name not defined) on ohCust or ohStat | The key DS uses the wrong record format name in LIKEREC, or your key field names differ. Check with DSPFFD. |
Compile error on the dcl-pi | Parameter types don't match how they were defined. C-spec numeric PARM fields are packed. |
| Harness says DIFFERENT only in the message | Almost always MOVEL/MOVE translated as a plain assignment. See "The MOVEL trap". |
Decimal data error (MCH1202) or nonsense results when calling from the command line | A numeric literal on a command-line CALL is passed as packed (15 5), not (7 0). Pass the customer as a character string through the CL harness. |
| Long lines are cut off after conversion | The source file record length is too short for free-form. Use RCDLEN(112) or more, or ask BOB to wrap at 100 characters. |
| Totals differ for huge customers | The ADD vs += overflow difference. Fixed-form ADD truncated quietly; the new code signals an error. Make the field bigger in a separate change. |
Key takeaways
- The RPG Modernization workflow converts;
/review_rpgreviews. Use both: review before, convert, review after. - The workflow handles OPM and ILE fixed-format, detects cycle programs, works in two phases (I/O specs first, then H/F/D/C), can do a pre-conversion compile, and needs a connection and a Local or Library List workspace.
- Conversion means identical behaviour. Put that in
AGENTS.MD, and put every improvement in a separate, tested change. - Work on a copy (test library or Git branch), compile with
*EVENTF, and prove equivalence with a regression test. A clean compile proves nothing about behaviour. MOVEandMOVELare where conversions go wrong. Without(P)they don't clear the rest of the target. Check every one.- Keep score against
AGENTS.MD, and when BOB misses a rule, improve the rules, not just the code.
Quick quiz
Easy huh?
ORD100R is now free-form, proven identical, and scores thirteen out of fifteen against our AGENTS.MD, with two deliberate pauses: embedded SQL and MONITOR error handling. Next time we'll make those changes safely. Instead of a throwaway CL harness, you could build a proper safety net with BOB's RPGUnit Test Plan Creation and RPGUnit Test Suite Implementation workflows, then let BOB swap the record-level access for SQL and add error handling, with the tests telling us exactly what changed.
Breaking your own code on purpose is surprisingly satisfying. Almost as satisfying as a proper brew.

