There is no doubt about the necessity of providing documentation after code has been placed into production. But I believe that being proactive demands the induction method, so I thought I should revisit a tip I submitted four years ago: Create an RPG technical document using existing iSeries utilities.
Program documentation should be up front. A business/systems analyst role calls for crafting documentation that will lead the coder in the right direction. It should make the programmer's work easy and efficient.
This work is a matter of strategy. Here is how it can be done:
1. Using the CRTSRCPF command, create a source physical file in your library (YourLib/QDOCSRC) where you will put your program documentation files.
2. Type the command WRKMBRPDM FILE(YourLib/QDOCSRC) to go to the Work with Members Using PDM screen.
Click image for larger version
3. Press F6 to open a screen similar to the one below:
Click image for larger version
In the above screen prompt, PROGRAMA was specified for the source member, TXT for the source type and Technical Specifications for the text description.
4. Press Enter to bring up a screen similar to this:
Click image for larger version
The analyst's program documentation work begins in the above screen. It is also here where most of the programmer's work will take place. Note: It is important that an asterisk (*) should be placed at position seven of every line when writing the documentation. By doing so, the programmer can just copy the source member into any desired source physical file. From there, he can opt to edit (using option 2) the copied file to another source type ( RPG, RPGLE, CLLE, etc.) of his choice.
5. To produce a report, execute the command WRKQRY to query the contents of YourLib/QDOCSRC. Specify the name of the member you worked on.
Using the 'Define result fields' option, define a field to use for searching commented lines.
Define result fields: Type definitions using field names or constants and operators. Press Enter.
Operators: +, -, *, /, SUBSTR, ||, DATE...
Field Expression Column Heading
Len Dec
COMMENT SUBSTR(SRCDTA,7,1)
6. Using the select and sequence fields, select SRCDTA column.
7. Using the 'Select records' option, define a filter to include only commented lines.
Select Records: Type comparisons, press Enter. Specify OR to start each new group.
Tests: EQ, NE, LE, GE, LT, GT, RANGE, LIST, LIKE, IS, ISNOT...
AND/OR Field Test Value (Field, Number, 'Characters', or ...)
COMMENT EQ '*'
8. Use the "Select output type and output form" option if you want to print your documentation.
For those of you who would like to move a step further, bear in mind that an iSeries source member is contained in a physical file. Any RPG programmer can actually write a full-featured integrated tool (a maintenance program with friendly interfaces), which will facilitate the above tasks -- maybe one that can be used by both the analyst and the coder.
ABOUT THE AUTHOR: Carlito 'Itto' Cruz is Lead Programmer Analyst at Kforce Global Solutions, Inc.
