Beefing Up The Job Log

Next to Barbara Morris, the job log is the IBM i professional’s best friend. However, even though job logs give useful information, they don’t always tell us everything we need to know to diagnose job failure. A recent email from perspicacious reader Daniel Long reminded me that sometimes we have to help ourselves.

A job log can tell us when a job started and ended, the list of libraries at its disposal, the CL commands and programs it ran, the messages those programs sent, etc. The one thing the job log does not show us, and how I wish it would, is the list of parameters passed to a CALL command. No, the job log shows us this lame message:

CALL PGM(MYPGM)          /* The CALL command contains parameters */

I have written about this before. And also before that. As far as I was concerned, this topic had received adequate coverage in this august publication, and I had no plans to revisit it.

Then came Daniel’s email. Daniel, a really sharp guy, mentioned using the Qp0zLprintf API to write to the job log from RPG programs. I realized that I had not finished the job.

Here’s the procedure prototype Daniel uses:

dcl-pr UTIL_writeJobLog int(10) extproc('Qp0zLprintf');
   out_String pointer value options(*string);
   out_Substitute01 pointer value options(*string:*nopass);
   out_Substitute02 pointer value options(*string:*nopass);
   out_Substitute03 pointer value options(*string:*nopass);
   out_Substitute04 pointer value options(*string:*nopass);
   out_Substitute05 pointer value options(*string:*nopass);
   out_Substitute06 pointer value options(*string:*nopass);
   out_Substitute07 pointer value options(*string:*nopass);
   out_Substitute08 pointer value options(*string:*nopass);
   out_Substitute09 pointer value options(*string:*nopass);
   out_Substitute10 pointer value options(*string:*nopass);
end-pr;

Here are some sample calls:

if sqlstate > EOF;
   UTIL_WriteJobLog( '- - - - - - - - - - - - - -' + X'25' );
   UTIL_WriteJobLog( '- %s ended with 10-%s' + X'25' :
                     %trim(prognm) :
                     sqlstate );
   UTIL_WriteJobLog( '- - - - - - - - - - - - - -' + X'25' );
   return;
endif;

This API works like C’s printf function. The first parameter is a string that may contain substitution variables. The remaining parameters are optional, and refer to the values that are to replace the substitution variables.

As I have worked with this API, I have come to prefer passing only one parameter to Qp0zLprintf. The only substitution variable I have found that works well from RPG is %s, which means that parameters two and following must be character strings. Since all the parameters have to be strings, why not put the string values into the message?

WriteToJobLog ('Counter=' + %char(Counter) + X'25');

Here, then, is an example that puts it all together. First, portions of CL program QAD1C.

pgm

   dcl  &Account   *char    5
   dcl  &ErrorFlag *char    3


   sndpgmmsg ('&Account=' *cat &Account) topgmq(*same) msgtype(*info)
. . . more stuff . . .
   call qad1r (*list &Account &ErrorFlag)
. . . more stuff . . .
   sndpgmmsg ('&ErrorFlag=' *cat &ErrorFlag) topgmq(*same) msgtype(*info)

endpgm

Next, the RPG program.

H dftactgrp(*no) actgrp(*new)

D Qad1R           pr                  extpgm('QAD1R')
D  inAction                     10a   const
D  inAccount                     5a   const
D  ouErrorFlag                   3a

D psds           sds                  qualified
D   ProcName                    10a

D WriteToJobLog   pr            10i 0 extproc('Qp0zLprintf')
D  inMessage                      *   options(*string: *nopass) value

D EOL             c                   const(x'25')

D Counter         s              5p 0

D Qad1R           pi
D  inAction                     10a   const
D  inAccount                     5a   const
D  ouErrorFlag                   3a

 /free
   *inlr = *on;
   Counter += 1;
   WriteToJobLog ('**Enter ' + %trim(psds.ProcName) + EOL);
. . . more stuff . . . 
   WriteToJobLog ('Counter=' + %char(Counter) + EOL);
. . . more stuff . . .
   WriteToJobLog ('**Leave ' + %trim(psds.ProcName) + EOL);
   ouErrorFlag = 'NO';
   return;

We have covered all bases. The job log has messages like these:

&Account=23456
**Enter QAD1R
Counter=5
**Leave QAD1R
&ErrorFlag=NO

I will mention one more thing. Qp0zLprintf returns a four-byte signed integer value that tells how many bytes of data were written, so you can call the API this way if you prefer:

D BytesWritten    s             10i 0

  BytesWritten = WriteToJobLog ('**Enter ' + %trim(psds.ProcName) + EOL);

But I don’t know any need for this.

Now that you have effective ways to write to the job log, load the job log with useful information. Life’s too short to spend time debugging programs.

RELATED STORIES

Remove Misleading Messages from Job Logs

A Better Way to Read Job Log

Let’s See Those Command Parameters

Vincent’s Standards

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