The sample COBOL program file STOCKCON.CBL and structured programming techniques
--------------------------------------------------------------------------------

Lately, not more than two or three weeks ago, Amanda, posted a message in the
newsgroup COMP.LANG.COBOL, crying desperately for help to solve her current
problems with her program. I responded to her posting by email and I got an
email message from her containing fragments of COBOL code with lots of
errors and fragments of program specifications which did not make much sense.

So, I have decided to write a sample program, starting from incomplete
code fragments and program specification to create STOCKCON.CBL. Of course,
I had to improvise a little bit to conceptualize a problem that was not
fully explained to me. This was to give her an idea as to how one can
create a parallell between the program specification and the program
implementation by using the structured programming techniques in COBOL
language. Since the COBOL language implementation for screen handling is
highly platform-dependent, I have used the most primitive ISO/ANSI standard
screen handling statements in order to avoid compilation problems on her
specific platform. I have avoided to use the function keys of the keyboard
also. So, there is nothing pretty about data entry, data display or
menu presentations in this sample program. However, I have done my best
to illustrate the structured programming techniques that I have been using
for a long time. One can talk a lot about these techniques, but the best
thing to do is to give an example so that one can see how these techniques
are employed in real life. Thanks to the structured programming techniques
employed, it was possible, for me, to write, compile, link and test this
sample program in half a day's time. Here are the highligts of these
techniques:

1) Never use GO TO.

2) Go as deep in procedure calls as it is necessary. I have never hit the
   compiler stack limits so far. So, you will probably not hit it either.

4) Use meaningful paragraph names. Keep paragraph names as short as
   necessary but not shorter than necessary. So, if necessary, use up
   the maximum lenght of 30 characters when you need to do so.

5) Use meaningful constant/data names as long as necessary, applying the
   same criteria as those applied to paragraph names.

4) Make the COBOL source file as close to simple English language
   as possible so that, only by reading the COBOL source file, you
   can feel like you are reading the program specification in detail.

5) Use COBOL constants (78 level items) with joy when needed. This
   will render the COBOL code more understandable and it will make
   modification of your code almost free of errors. It is
   much easier to change the value of the numeric constant
   from 30 to 45 in the following example of constant declaration
   than hunting for every occurrence of the constant value 30
   in a large source file and change each one to 45.

   78 MaximumNumerOfLinesPerPage  Value 30.

6) If your editor and/or platform of development allows it, use a
   Capital letter to form Constant/Data/Paragraph names instead of
   dashes, thus gaining precious name space and still insuring
   legibility as in the example below:

   A113-DoMainProcess but not A113-DO-MAIN-PROCESS.

7) Use four digit alphanumeric paragraph prefixes. This will allow
   you to use the same paragraph name several times, when you need
   to do so in your source program, thus rendering the paragraph
   name unique. Examples:

   A251-AddDataToFile.
    A252-DisplayScreenMask.

   A452-UpdateDataFile.
    A453-DisplayScreenMask.

   Since, A252-DisplayScreenMask is called by A251-AddDataToFile,
   why bother trying to say DisplayAddDataToFileScreenMask, running out of
   name space and than force yourself to find a cryptic paragraph name.
   Since hierachical call order makes it evident that A252-DisplayScreenMask
   called by A251-AddDataToFile, it suffices to say DisplayScreenMask
   prefixed by A252. And in its context, it is also evident that, even
   if you use the same paragraph name in A453-DisplayScreenMask, it is
   the screen mask of the procedure of A452-UpdateDataFile. There are
   abondant other examples of similar situations when you code your
   program. So, quickly chose a paragraph prefix and continue with ease
   to code your program in a meaningful way in its context.

8) Use a rectangular, for comments, in front of each division, section
   and paragraph to aerate your code. Blank lines increase the legibility
   of the code when used as in the example program. You can extend the meaning
   of the paragraph name within the preceding rectangle of comments
   line or just repeat it in open seperated form as an English language
   phrase. This much extra work is tolerable and it improves the
   reading of the code if you want to have an exlusive reading session
   without glancing at the formed paragraph names.

9) Pay a lot of attention to error conditions for file input/output,
   for external routine calls, calculation statements, etc. and
   handle them gracefully when possible and let the program exit
   when an abnormal error condition occurs. When you are not sure
   if an error can be handled, exit the program with an abnormal
   end condition rather than doing nothing to handle the error
   condition.

10)Use a separate paragraph name for each fatal error and indicate
   at least its paragraph prefix when you exit the program with
   abnormal end condition. Thus, you can pinpoint exactly where
   the error has occured. If necessary, you may also add extra
   information such as file-status code, etc.
