Receive messages from the job log.

For the last few months, we've been looking at various considerations related to the running of CL commands using the QCMDEXC, QCAPCMD, and system APIs. As part of that discussion, we've explored some of the ways your RPG program can remove error-related messages from the job log. Due to several notes that I have received on the topic of message retrieval and removal, this article (and a following one) will go into more detail concerning some of the points I briefly discussed last month.

In the scenario we'll be using, our application program attempts to clear a member of file SOMEFILE using the Clear Physical File Member (CLRPFM) command, the CLRPFM fails due to CPF3141 (Member not found), the application attempts to add the member using the Add Physical File Member (ADDPFM) command, and the ADDPFM fails with message CPF7306 (Member not added and to see previous messages for the reason of the failure). At this point, the application program needs to determine the cause of the CPF7306 and, depending on the cause, take action to correct the situation.

Below is the initial version of the application program that we will be reviewing today. I have restructured the program from previous articles in order to consolidate the various calls to the Send Program Message API (I was getting tired of the duplication in sending messages) and to allow a discussion of how call level can impact the parameter values you pass to various message-handler APIs (a discussion deferred to next month).

h dftactgrp(*no)                                                  

dRunCmd           pr                  extpgm('QCAPCMD')          

d SourceCmd                  65535    const options(*varsize)    

d LenSrcCmd                     10i 0 const                      

d CtlBlk                     65535    const options(*varsize)    

d LenCtlBlk                     10i 0 const                      

d CtlBlkFmt                      8    const                      

d ChgCmd                         1    options(*varsize)          

d LenAvlChgCmd                  10i 0 const                      

d LenRtnChgCmd                  10i 0                            

d QUSEC                               likeds(QUSEC)              

dSndMsg           pr                  extpgm('QSYS/QMHSNDPM')    

d MsgID                          7    const                      

d QualMsgF                      20    const                       

d MsgDta                     65535    const options(*varsize)   

d LenMsgDta                     10i 0 const                     

d MsgType                       10    const                     

d CSE                        65535    const options(*varsize)   

d CSECtr                        10i 0 const                     

d MsgKey                         4                              

d QUSEC                               likeds(QUSEC)             

d LenCSE                        10i 0 const options(*nopass)    

d CSEQual                       20    const options(*nopass)    

d DSPWaitTime                   10i 0 const options(*nopass)    

d CSEType                       10    const options(*nopass)    

d CCSID                         10i 0 const options(*nopass)    

dRcvMsg           pr                  extpgm('QSYS/QMHRCVPM')   

d MessageInfo                    1    options(*varsize)         

d LenMsgInfo                    10i 0 const                     

d FmtMsgInfo                     8    const                     

d CSE                        65535    const options(*varsize)  

d CSECtr                        10i 0 const                    

d MsgType                       10    const                    

d MsgKey                         4                             

d WaitTime                      10i 0 const                    

d MsgAction                     10    const                    

d QUSEC                               likeds(QUSEC)            

d LenCSE                        10i 0 const options(*nopass)   

d CSEQual                       20    const options(*nopass)   

d CSEType                       10    const options(*nopass)   

d CCSID                         10i 0 const options(*nopass)   

d AlwDftRpyRej                  10    const options(*nopass)   

dSndHardError     pr                                           

dHdlCPF3213       pr                                           

dMaxInt           pr            10i 0                          

d Input1                        10i 0 const                    

d Input2                        10i 0 const                    

 /copy qsysinc/qrpglesrc,qcapcmd                                

 /copy qsysinc/qrpglesrc,qmhrcvpm                              

 /copy qsysinc/qrpglesrc,qusec                                 

dPSDS            sds           429    qualified                 

d JobUsr                254    263                             

dErrCde           ds                  qualified                

d Common                              likeds(QUSEC)             

d ErrMsgDta                    512                             

dMessageInfo      ds                  qualified                

d Common                              likeds(QMHM010001)       

d ErrMsgDta                    512                              

dCmd              s            512                              

dMsgKey           s              4                               

dNotUsedChr       s              1                              

dNotUsedInt       s             10i 0                           

 /free                                                           

  QUSBPRV = 0;                                                  

  ErrCde.Common.QUSBPRV = %size(ErrCde);                        

  QCAP0100 = *loval; // initialize input structure to nulls     

  QCACMDPT = 0;      // Run command                             

  QCABCSDH = '0';    // Ignore DBCS                             

  QCAPA = '0';       // Do not prompt command                   

  QCACMDSS = '0';    // User i5/OS syntax                       

  Cmd = 'CLRPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';             

  RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)            

         :'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);            

  if ErrCde.Common.QUSBAVL > 0;                                      

     select;                                                          

        when ErrCde.Common.QUSEI = 'CPF3141';                        

             Cmd = 'ADDPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')'; 

             RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)  

                    :'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde); 

             if ErrCde.Common.QUSBAVL > 0;                           

                select;                                              

                   when ErrCde.Common.QUSEI = 'CPF7306';             

                        RcvMsg(MessageInfo :%size(MessageInfo)       

                               :'RCVM0100' :'*' :0 :'*DIAG' :MsgKey  

                               :0 :'*OLD' :ErrCde);                  

                        if ErrCde.Common.QUSBAVL > 0;                

                           SndHardError();                            

                        endif;                                        

                        select;                                        

                           when MessageInfo.Common.QMHMI03 = 'CPF3213';

                                HdlCPF3213();                         

                           other;                                     

                                SndHardError();                       

                        endsl;                                        

                   other;                                             

                        SndHardError();                                

                endsl;                                                

             endif;                                                   

        when ErrCde.Common.QUSEI = 'CPF3142';                         

             Cmd = 'CRTPF FILE(SOMEFILE) MBR(' + PSDS.JobUsr +        

                   ') MAXMBRS(*NOMAX) OPTION(*NOSRC *NOLIST)';        

             RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)  

                    :'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde); 

             if ErrCde.Common.QUSBAVL > 0;                           

                SndHardError();                                      

             endif;                                                  

        other;                                                       

             SndHardError();                                          

     endsl;                                                          

  endif;                                                             

  // Do further processing                                            

  *inlr = *on;                                                       

  return;                                                            

 /end-free                                                           

pSndHardError     b                                               

 /free                                                           

  SndMsg(ErrCde.Common.QUSEI :'QCPFMSG   *LIBL'                  

         :ErrCde.ErrMsgDta                                       

         :MaxInt(0 :ErrCde.Common.QUSBAVL - %size(QUSEC))        

         :'*DIAG' :'*PGMBDY' :1 :MsgKey :QUSEC);                 

  SndMsg('ESC0001' :'OURMSGS   *LIBL' :' ' :0                    

         :'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);               

 /end-free                                                        

pSndHardError     e                                              

 *****************************************************           

pHdlCPF3213       b                                               

 /free                                                             

  Cmd = 'CHGPF FILE(SOMEFILE) MAXMBRS(*NOMAX)';                    

  RunCmd(Cmd :%len(%trimr(Cmd)) :QCAP0100 :%size(QCAP0100)         

         :'CPOP0100' :NotUsedChr :0 :NotUsedInt :QUSEC);          

  Cmd = 'ADDPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';          

  RunCmd(Cmd :%len(%trimr(Cmd)) :QCAP0100 :%size(QCAP0100)         

         :'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);          

  if ErrCde.Common.QUSBAVL > 0;                                     

     SndHardError();                                               

  endif;                                                           

 /end-free                                                          

pHdlCPF3213       e                                                

 *****************************************************             

pMaxInt           b                                      

dMaxInt           pi            10i 0                    

d Input1                        10i 0 const              

d Input2                        10i 0 const              

 /free                                                   

  if Input1 > Input2;                                     

     return Input1;                                      

  else;                                                  

     return Input2;                                      

  endif;                                                 

 /end-free                                               

pMaxInt           e                                     

The program should look familiar to you if you have previously read the article "Automating Recovery, Part II." These are the differences:

• Adding a prototype for the Receive Program Message (QMHRCVPM) API
• Adding a prototype for the procedure SndHardError (Send Hard Error)
• Adding a prototype for the procedure HdlCPF3213 (Handle message CPF3213 – Members for file more than maximum allowed)
• Copying the QMHRCVPM QSYSINC header file for the QMHRCVPM API
• Defining the data structure MessageInfo, which is defined the same as the data structure QMHM010001 of the QMHRCVPM QSYSINC member with an additional 512 bytes allocated for message replacement data
• Adding additional error-recovery logic for when the ADDPFM command fails, which we will be reviewing shortly
• Replacing, at several locations within the program, two calls to the QMHSNDPM API with a call to the new SndHardError procedure
• Adding a call to the SndHardError procedure
• Adding the HdlCPF3213 procedure, which we will also be reviewing shortly

In the original program utilizing the QCAPCMD API, if the ADDPFM command failed, the application would send the user escape message ESC0001 (ending the program). The current program, on the other hand, interrogates the QCAPCMD API ErrCde parameter to further analyze why the ADDPFM command failed. If the error is not CPF7306 (the Other operation of the Select group), the program calls the SndHardError procedure to log the failure message.

If the cause of the failure is CPF7306 (Member not added), the program calls the QMHRCVPM API to receive the diagnostic message associated with the CPF7306 escape message. As was mentioned in last month's article, CPF7306 does not tell you why the ADDPFM failed, only that it did. Diagnostic messages, sent to you prior to the escape message, provide the details behind the failure.

The parameters used with the QMHRCVPM API are very similar to some of the parameters used with the Remove Program Message (QMHRMVPM) API first introduced in "Automating Recovery (or Keeping the Help Desk Out of the Loop)" and the Send Program Message (QMHSNDPM) API. The API documentation for QMHRCVPM can be found here. Basically the API receives a message from either a call message queue or an external message queue, and returns information describing the message.

The first three parameters, as is true with most retrieve type APIs, define what data we want returned about the message. Format RCVM0100 returns basic message information such as the message ID, the message severity, the message key (which will be utilized in a later enhancement of the example program), and optionally the message replacement data associated with the message. Quite a bit more information is available with format RCVM0200, but the current application has no need for this additional data.

The other parameters describe how the message is to be accessed. As the message was sent to the current procedure (the procedure running the ADDPFM command), the '*' value is used as the fourth parameter to indicate that the message is to be found relative to the current call-stack entry (that is, the caller of the API). The fifth parameter, call stack counter, identifies the call stack to be used relative to the call-stack entry identified by the fourth parameter. The value 0 indicates to use the base call-stack entry. The message type parameter value is '*DIAG' as we're looking for the diagnostic message associated with the CPF7306 escape message, and the message key parameter is a value of blanks, indicating we want the first available new message. The message action parameter is set to the value '*OLD', indicating that the received message should be marked as old and retained in the job log. The program could have the message removed as a part of receiving the message, but I prefer to remove the message only after I know it's no longer needed or relevant.

Having received the message, the program determines if the message is CPF3213 (Members for file more than maximum allowed). If it is, then procedure HdlCPF3213 is run; otherwise, the SndHardError procedure is run to send the original CPF7306 message, followed by the user escape message ESC0001.

The HdlCPF3213 procedure attempts to run the Change Physical File (CHGPF) command to change the maximum number of members to *NOMAX. When running the CHGPF command, the QCAPCMD API error code parameter is specified as QUSEC. This, due to the QUSEC setting of Bytes provided to 0, indicates that any error found with the CHGPF command should result in an escape message being sent. The program does this as there's no recovery logic associated with an error on the CHGPF command. The application could use the ErrCde parameter, rather than QUSEC, followed by a call to SndHardError if the returned ErrCde Bytes available is non-zero, but you've already seen several examples of using this approach.

If the CHGPF command is successful—that is, control is returned to the application program as opposed to an escape message being sent by the API—then the ADDPFM command is run again. The odds are good that this add will be successful, though the program does once again check the ErrCde Bytes available field just in case.

Calling this level of the program, and running the scenario described above, will result in the successful addition of a new member to file SOMEFILE. In the job log, you will find the three messages:

• CPF3213 – Members for file SOMEFILE more than maximum allowed.
• CPC7303 – File SOMEFILE in library xxxxxx changed.          
• CPC7305 – Member yyyyyy added to file SOMEFILE in xxxxxx.

Depending on personal (or corporate) preference, you may or may not want these messages in the job log. Personally, I tend to look at job logs only when something has gone wrong, and I prefer to only have to look at messages related to the failure. These messages, however, are not describing a failure in the application. Rather, they document the successful handling of an environmental problem (namely, the lack of a necessary member). In particular, the CPF3213 message is the type of message that might cause me to spend a few minutes determining if it's a problem, only to find that it's not. So how might we remove this message?

Next month, we'll look at how various parameters of the QMHRMVPM API can be used to remove the CPF3213 message, the two CPC messages, and other messages that you might find to be a nuisance in your job logs.

Questions?

If you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.  

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,

Bruce Vining

• Email
• Site

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at bvining@brucevining.com. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale