It is a hard reality in many RPG IT shops that we find many in-house programs running in the production environment without any technical documentation at all. In cases like this, we have to analyze the program code by code and come up with the technical documentation to avoid the same problem again.
The challenge, therefore, is to find a fast and effective way of doing the job when confronted with this scenario. I came up with an idea which I'm not sure every programmer will appreciate. But given the resources at hand, this does the work for me. With the existing iSeries utilities, we can achieve this by going through the following steps:
1. Create a source physical file in your programmer library
(myLib/QDOCSRC) where you will put your program documentation.
2. Copy the program source member for which you want to create a
program documentation into myLib/QDOCSRC.
3. Using SEU, open the source member and write the essential
remarks describing what each part of the program does. Make it as detailed as necessary but concise as possible. (With necessary references to a subroutine, a program call, external procedure, etc.).
Save your work.
4. When all the necessary remarks have been written, execute the
command WRKQRY to query the contents of myLib/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)
5. Using the select and sequence fields, select 'SRCDTA' column.
6. 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 '*'
7. Use the 'Select output type and output form' option if you want to print your documentation.
You may later choose to convert the spooled file output into other PC formats such as PDF or TXT. There are numerous utilities out there to do the work for you. So why should we re-invent the wheel?
==================================
MORE INFORMATION ON THIS TOPIC
==================================
The Best Web Links: tips, tutorials and more.
Ask your programming questions--or help out your peers by answering them--in our live discussion forums.
Ask the Experts yourself: Our application development gurus are waiting to answer your programming questions.
