An auditor sits down with your team and points at one field in the customer master, the credit limit. She wants to know which programs can change it. Your database administrator can show her the field and its type in a few seconds. The list of programs takes a lot longer, because that answer is not in the database at all.
Database documentation on IBM i has to close that gap. The schema tells you what the data looks like. The RPG source tells you who touches it.
What database documentation covers on the schema side
Database documentation starts from the schema. A team lists the tables and their columns, along with keys and the comments someone left in the definitions. Tools read that information from the database catalog and print it as a reference. For a database that only one application uses, that reference may be enough.
Db2 for i, the relational database built into IBM i, keeps that kind of catalog too, and it rebuilds its catalog views on its own. Your team can list files and fields from it today.
Ask your team where its current database documentation lives, and when someone last checked it against the code. If the answer is a spreadsheet or a binder, check the program half first, because each release can change which programs use a file.
On IBM i, many programs can share one file by design. One customer file may serve order entry and billing programs that different people wrote years apart. The schema side of the record cannot show any of that, because the links live in the code that opens the file.
The program side lives in the RPG source
IBM i gives programs two ways into the database. The native interface defines files with Data Description Specifications, known as DDS, and SQL is the second way in. A library that has grown over decades may use both.
When an RPG program uses a DDS file, the compiler builds the file’s record format into the program. Field definitions also echo through display files and printer files. Copy members can spread a layout further, because a copy member pulls shared source into each program that includes it at compile time.
The facts your auditor wants therefore live outside the database, in the programs and screens built on each file. Complete database documentation for IBM i has to bring that program side into the same record as the schema.
What goes into database documentation for IBM i
A useful record covers each file from both sides, and each part has its own source.
| Part of the record | Where it comes from |
|---|---|
| The files and their fields | The DDS definitions and the SQL definitions |
| The programs that read each file | A structured analysis of the RPG source |
| The programs that update each file | The same analysis, with a plain-English description of each program |
| The display files and reports that show each field | The field-level view of the analysis |
| What each field and code value means to the business | The people who run the jobs |
Your team may already keep the file and field list. The program side is what an auditor or a new analyst asks about. The business meaning only a person can write, and it gives the rest of the record its value.
Where each part comes from
You can start the program side with a command your team already has. DSPPGMREF reports which files a program references at the file level, and it captures those references when the program is compiled. It is a good first pass for a single program. It works at the file level, while your auditor asked about one field. A program can open the customer master and never touch the credit limit, and the file list alone cannot tell those programs apart.
AS/Forward fills in the rest from your source. It ingests your RPG programs and the DDS around them through a proprietary ingestion layer. Then it builds a dependency map across the whole codebase before any AI model sees the code. The IBM i Navigator shows how each program connects to the files and procedures it uses. Each program also gets a plain-English description written from its source, so your team can tell a lookup program from one that updates the credit limit. A description can say that a program reads a file for validation, or that it updates the file in batch. Each program page also feeds the model both the raw source and its description, so an answer to your auditor starts from your real code.
Your people supply the business meaning. A program may set a status code, and a description can say so. Only someone in the business knows what each code value means, and that person writes it into the record. When the two halves live in one record, an auditor can follow a field from its definition to the programs that change it and to the reason the business cares.
Our post on one page of documentation per program shows what each program description looks like. If you want to test descriptions against the code that runs, our post on checking documentation against the compiled source covers that check.
Answering a field question before anyone edits a file
The same record answers a change request too. A business analyst asks to widen the credit limit field. Before anyone opens the file definition, your team picks the field in the Migration view. The view lists what else would need to change, down to programs, logical files, display files and reports.
That list turns a vague worry into a plan. “If we touch this, what else moves?” now has a written answer your team can review and test. A person on your team reviews every change that follows, program by program.
The field view also helps the people who never open source code. A business analyst can see whether a wider credit limit reaches a printed statement or an inquiry screen before anyone writes a specification. Your auditor gets an answer that points to named programs.
Who uses the record, and how
The record serves more people than the auditor who asked the first question. Each of them comes to it with a different need.
A new analyst uses it to learn the system. Instead of asking a senior developer which programs touch the customer master, the analyst opens the record and reads the list with a description beside each program. The senior developer then spends time on the questions the record cannot answer.
Your database administrator uses it to plan changes. Before a field grows or a file gains a column, the record shows which programs and screens depend on the current layout. Your developers use it to review each other’s work, because a change to a shared file now comes with its own list of programs to check.
Leadership uses it in a different way. The record shows how many programs depend on each core file, and that count helps a CTO judge how much care each change needs.
What the record cannot show
A record built from source is only as complete as the source behind it. A program name assembled from a parameter at run time does not appear in any static cross-reference, because no tool that reads source can see that value. A file opened under a name built the same way stays hidden too. Your senior developers may know where those cases live, and the record should carry a short list of them. Keep each case beside the file it touches, so the next person who looks up that file finds the warning in the same place as the program list.
AS/Forward also lists the copy members it could not resolve. That list shows where the map stops, and each entry is a copy member your team still needs to find. Programs with gaps carry a review status, while clean programs are marked ready, so you can see which parts of the record need a person’s eyes first.
Keeping database documentation useful after the audit
After the audit, the same record serves the database work and the program work your team plans next. The same record supports a move from DDS to SQL, and our post on moving DDS files to SQL sets out that road. We do that work on IBM i, file by file. We also convert programs to Python or another language your team picks. Some teams want to keep their green screens, and we modernize the programs behind them. Each of those outcomes is valid, and your team makes the call.
A team can put AS/Forward to work before any migration and use the record for audit prep or knowledge transfer. When a developer later adds a program that opens a shared file, your team runs the analysis again and the new program joins the list for that file. The assessment report can go to a CTO and a lead developer in the same meeting, and both of them see the same files and programs.
The analysis runs inside your infrastructure. The preferred deployment is fully local and air-gapped, and with a local model no data travels to an external API. Your team chooses the model, whether Claude, OpenAI, Gemini or one you run locally.
Start with the assessment
The IBM i modernization assessment is the first step. It gives you the program count and the dependency map, along with a plain-English description of each program and the list of unresolved copy members. It builds the program side of your database documentation, and it sizes any work that follows. The decision about what comes next stays with you.
Tell us which file your auditors ask about most and how many source libraries you run. Call 501-232-7188, or reach us through our contact page.