Data Structures Make Good Status Parameters

Published: October 31, 2012

by Ted Holt

When a good program goes bad, someone must fix it. Sometimes that someone is me. As for the "when," it's never a good time. It's important to me that the failing program give me as much information as possible to help me pinpoint the cause of the error as quickly as possible.

There are two ways a program can inform its caller that it could not complete normally. One way is by sending a message. (I have written about this topic before; see the Related Stories at the end of this article.) The other way is to use a status parameter, also known as a "return code."

It is common for a program to place a zero into a status parameter if all went well, and a non-zero value if something went wrong. A good example of this convention is the SQL state.

I wrote earlier this year about an extension of the SQL state that identifies the statement that ended in error.

You can take this idea even further, making the program in error pass back as much data as you wish. I illustrate with an RPG data structure, but the technique works with any language.

First, create a message, like this:

crtmsgf *curlib/mymsgf
addmsgd msgid(MYM1101) msgf(*curlib/mymsgf) +
          msg('&2 errors were found in program &1.') +
          seclvl('Correct the errors and rerun.') +
          fmt((*char 10) (*bin 4))

The message has two positional parameters, which occupy 14 bytes of storage.

Now, define a compatible data structure in the program(s) that will trap for this error. Here's the structure in RPG.

D Status          ds           256    inz
D   MsgID                        7a
D   PgmName                     10a
D   ErrorCount                  10i 0

The first seven bytes are set aside for the message ID. The remaining subfields of the data structure match the definitions of the substitution values in the message description.

I've kept the structure simple. It tells me the name of the rogue program and the number of errors it found. The more information you put into the structure, the better, because a user can read a message to you over the telephone, but having someone read a program dump to you is impractical.

Loading the structure is easy.

     if ErrorCounter > *zero;
        MsgID = 'MYM1101';
        PgmName = ProcName;          // from the PSDS
        ErrorCount = ErrorCounter; 
        ouStatus = Status;
     endif;

The last line gives the data back to the caller, because ouStatus is the first parameter.

D OnePgm          pi
D  ouStatus                    256a
D  inWhs                         3a   const
D  inItem                       12a   const

The driver CL looks like this (without appropriate code to handle unexpected errors).

pgm parm(&inOption &inItem &inWhs)

   dcl  &inOption    *char    1
   dcl  &inItem      *char   12
   dcl  &inWhs       *char    3

   dcl  &Status      *char  256

   call OnePgm  (&Status &inWhs &inItem)

   if cond(%sst(&Status 1 7) *eq ' ') then( +
         call TwoPgm  (&Status &inOption))

   if cond(%sst(&Status 1 7) *eq ' ') then(+
         call RedPgm  (&Status))

   if cond(%sst(&Status 1 7) *eq ' ') then(+
         call BluePgm  (&Status &inWhs))

   if cond(%sst(&Status 1 7) *ne ' ') then( +
         sndpgmmsg   msgid(%sst(&Status 1 7)) msgf(MyMsgF) +
                        msgdta(%sst(&Status 8 249)) +
                        msgtype(*escape))

endpgm

If a program finds an error, the system ignores the subsequent program calls. If any program ends in error, the last IF makes the CL program shut down by sending an escape message similar to this one:

50 errors were found in program OnePgm.

I used this technique in a project I worked on recently, and was very pleased with the results. Data structures make tremendous status parameters.

RELATED STORIES

Sending Escape Messages from RPG

RPG Subprocedure Error-Handling with APIs

Error Checking and Embedded SQL

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot