Free RPG manuals aren't what they used to be
IBM stopped maintaining the old-style RPG II and RPG III documentation years ago, but the current manuals are still scattered across various IBM sites and third-party archives. If you're working with IBM i systems — what most people still call AS400 — you need the RPG IV reference, not the vintage stuff. The free versions that circulate online are usually PDF dumps from IBM's own technical library. I use the one from ibm.com/docs/en/i to cover syntax, built-in functions, and the op-code reference. It's not the prettiest reference book, but it's the closest thing to an official answer you're going to get. The most reliable source is IBM's official documentation portal. Go to the IBM Knowledge Center for IBM i, search for "RPG Reference," and download the PDF directly. It changes with each OS version, so make sure you grab the one matching your current release. If you're on V7R4 or later, grab the RPG Reference for IBM i 7.4. Anything older and you'll need to adjust your expectations a bit. The file is usually around 8 to 12 megabytes depending on the release. Third-party mirrors exist but I don't trust them — you could end up with a corrupted PDF or one missing entire chapters. It's not a tutorial. Don't expect hand-holding. The official IBM RPG Reference gives you op-code descriptions, data structure layouts, and the grammar rules. It tells you what a %LOOKUP does, what parameters are required, and what the valid keywords are. That's it. You won't find walkthroughs of real business logic or advice on how to structure a production system. If you need that, you're better off finding community threads or older books that were written before IBM decided documentation should be purely functional.
When I'm stuck on something — a compile error that doesn't make sense, a field that won't read right from a DDS file — I search the manual for the relevant op-code. I look at the example code, compare it to mine, and spot the mismatch. Most of the time it's a data type issue or a mismatched field length. The manual has plenty of those examples. For %SCAN, for instance, it shows you the exact parameter order. I've found that the order matters more than the documentation makes it sound. Swap two parameters and the compiler doesn't always catch it right away. One thing the manual is really good about is its section on free-format versus fixed-format syntax. It clearly lays out the differences and when you need to use % rather than the old * indicators. If you're maintaining legacy code, this section is critical. You'll spot fixed-format quirks that trip up new developers constantly.
Edge cases the manual doesn't cover well
I ran into a problem recently where a subroutine was returning incorrect values when called from a trigger program. The manual had the syntax right, the compile succeeded without errors, but the data was wrong. After about three hours of stepping through the logic, I found it: the trigger was firing before the record lock was released in the calling program, which meant the subroutine was reading stale data from the file. The workaround was to add an explicit COMMIT(0) in the calling program before the trigger fired, or to change the trigger to INSTEAD OF INSERT instead of AFTER INSERT. Neither solution was documented anywhere in the manual. It was pure trial and error combined with reading the system messages more carefully. Another one: when you use the %CHAR built-in function with a packed decimal field that has trailing zeros, the manual shows one result, but on some older releases of IBM i the output included extra decimal places that weren't documented. I had a report that printed $10.50 as 10.5000 on V6R1 and 10.50 on V7R3. Same source code, different behavior. The fix was adding an explicit decimal position parameter to the %CHAR call.
Get the Full Details
What I wish the manual included
Performance guidance. The manual will tell you that using %LOOP with a subscript is valid syntax, but it won't warn you that doing it inside a tight loop over a large database file will tank your response time. It also won't tell you that the free-format keyword %EOF is faster than checking the EOF indicator manually in most modern scenarios. Those are the things you learn from being burnt. Data structure alignment is another gap. The manual describes DS clearly, but real-world problems with multi-language environments — particularly when mixing RPG with COBOL or C programs — create alignment issues that aren't obvious until something breaks in production. I once spent a full day tracking down a record layout problem caused by a COBOL program defining the same physical file with different key ordering. The RPG manual didn't help at all.
Alternatives worth knowing about
For learning purposes, the IBM Redbooks on RPG IV are far more useful than the reference manual. Look for SG24-5512 or the newer ones on midrange.com. They actually teach you how to write programs, not just what the syntax is. For quick lookups, the RPG wiki at rpgwiki.com has community-maintained examples that are sometimes more practical than IBM's official ones. And if you just need to know whether a specific keyword is valid, the online RPG documentation at ibm.com is fine. It's searchable and updated for each release. The manual is a reference, not a teacher. Use it when you need to verify something, not when you're trying to learn RPG from scratch. If you're starting a new project and want to understand the language properly, spend time with the Redbooks first. Then come back to the manual when you need the specifics.
