Documenting nested program structures on the AS/400

Documenting nested program structures on AS/400 is a complex task and is sometimes overlooked or not updated. The XPGMSTR command automates documentation in a structured and reliable way, eliminating the human-error (or lazyness) involved in the usual nested program structure documentation mishaps.

Often, it's a big task to keep track of and document nested program structures on the AS/400 -- (DOW/ENDDO, DOU/ENDDO,

IF/ELSE/ENDIF, CASE/ENDCS, SELEC/ENDSL, BEGSR/ENDSR). If we don't do it, it's really hard to follow the sequence within a program, and on the other hand when we do it, it's difficult to update and usually this documentation ends up being obsolete and unreliable. So, in order to solve this problem we created the XPGMSTR command to document these structures in a standard and automatic way, so no matter what you do or how you edit your source code you can always keep it up to date just by calling the command as many times as it takes.

The command can be invoked in any way you wish (e.g., directly from the command line, through PDM or in my personal favorite way via the exit point of the STRSEU command so that when you edit an RPG source code you will have its structures documented).

Here, we'll cover the first two ways, leaving the third option as an extra homework task for those who were interested in it.

Example: The command looks like the one shown in the following screenshot and you need to write the information regarding the source you want to document (library/file/member)


Click on image for larger version

If you want to use it from PDM you can add the command to the PDM's user-defined options as in the following screenshot


Click on image for larger version

Now, let's see an example using PDM. In the "Work with Members Using PDM" screen we choose an RPG member, e.g., P0305OLD, and then type 5


Click on image for larger version

We see in the source code that there are no comments or references regarding the RPG structures in the program.


Click on image for larger version

Then we go back to the "Work with Members Using PDM" panel and type "XP" next to the source member that we want to document.


Click on image for larger version

After we run the command when we go back to the source code we see at the right of the panel (in the comments are) the nested RPG structures (in this example the BEGSR and IFEQ RPG commands).

>
Click on image for larger version

And we also are able to see every nested structure (IF, ELSE, ENDIF) at the comments column all of them with a four digits number telling us its nested level (from 0010 the outermost to 9990 the innermost).

>
Click on image for larger version

All RPG structures are well documented here and clear to follow.

Source code
A PDF of the RPG program code is provided.

A PDF of the CLP program code is provided.

Command

0001.00              CMD        PROMPT('Documenting RPG structure')            

0001.01 PARM KWD(BIBLIO) TYPE(*CHAR) LEN(10) MIN(1) +
0001.02 PROMPT('Library name')
0001.03 PARM KWD(ARCHIVO) TYPE(*CHAR) LEN(10) MIN(1) +
0001.04 PROMPT('Source file')
0002.00 PARM KWD(MEMBER) TYPE(*CHAR) LEN(10) MIN(1) +
0003.00 PROMPT('RPG member name')

Compiling the programs and command

  1. Create a dummy file:
    CRTSRCPF FILE(QTEMP/FSOURCE) TEXT('Dummy file')
  2. Compile RPG program:
    CRTRPGPGM PGM("your_library"/P55ARA02) SRCFILE("your_source_file")
  3. Compile CLP program:
    CRTCLPGM PGM("your_library"/J55ARA02) SRCFILE("your_souce_file")
  4. Create Command: (make sure that "your_library" is in your current library list
    CRTCMD CMD("your_library"/XRPGSTR) PGM(J545ARA02)

ABOUT THE AUTHOR: Benito Abraham is an analyst programmer at Pride International. He has over 15 years experience on AS/400, including iSeries security and RPG.

This was first published in November 2008

Dig deeper on RPG iSeries programming

2 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

SearchEnterpriseLinux

SearchDataCenter

Close