Proper CL Error-Handling

May 5, 2004 Hey, Ted:

When a CL program produces an unexpected error, we find the problem, fix it, and take option “I” (ignore) or “R” (retry) in response to the error message. However, when a user runs a program and encounters an unexpected error, we run into problems. The user might call us. The user might not call us. The user may pick the wrong option and really mess things up. What can we do?

–Sandra

You can prevent the user from seeing an inquiry message when something goes wrong. The first thing you need is a global monitor message (MONMSG) command that branches to an error routine. The other thing you need is an error routine that sends an escape message.

Here is a CL program template I like to use:

pgm                                                               
                                                                  
   dcl   &Abending      *lgl                                      
   dcl   &MsgID         *char      7                              
   dcl   &MsgDta        *char    256                              
   dcl   &MsgF          *char     10                              
   dcl   &MsgFLib       *char     10                              
   dcl   &MsgKey        *char      4                              
   dcl   &MsgType       *char     10                              
   dcl   &RtnType       *char      2                              
   dcl   &PgmName       *char     10                              
   dcl   &Sender        *char     80                              
                                                                  
   monmsg cpf0000 exec(goto abend)                                
                                                                  
   /* retrieve the program name */                                
   sndpgmmsg msg(' ') topgmq(*same) msgtype(*info) keyvar(&msgkey)
   rcvmsg    pgmq(*same) msgtype(*info) sender(&sender) rmv(*yes) 
   chgvar    &PgmName   %sst(&Sender 56 10)                       
                                                                  
   /* begin regular routine */
                                                                         
   /* normal end of job */                                               
      sndpgmmsg  msgid(cpf9898) msgf(qcpfmsg) msgtype(*comp) +           
                   msgdta('Program' *bcat &PgmName *bcat +               
                          'completed normally')                          
      return                                                             
                                                                         
   /* Routine to handle unexpected errors */                             
Abend:                                                                   
      if &Abending then(return)                                          
      chgvar   &Abending '1'        
                                     
      rcvmsg     msgtype(*last) msgdta(&msgdta) msgid(&msgid) +          
                    rtntype(&RtnType) +                                  
                    msgf(&msgf) sndmsgflib(&msgflib)                     
      if ((&RtnType *eq '15') *or (&RtnType *eq '17')) do  /* *escape */ 
         sndpgmmsg  msgid(&msgid)  msgf(&msgf)   msgtype(*diag) +        
                   msgdta(&msgdta)                                       
      enddo                                                              
Escape:                                                                  
   sndpgmmsg  msgid(cpf9898) msgf(qcpfmsg) msgtype(*escape) +            
                msgdta('Program' *bcat &PgmName *bcat +                  
                       'ended abnormally')
endpgm                                    

To use this template, you will have to declare any variables or files you use after the PGM command and before the global MONMSG. Then put the commands that you want to run after the comment that indicates the beginning of the regular routine. The rest of the program remains as is.

If an unmonitored error occurs in the regular routine, control branches to the ABEND label. The first two calculations make sure that the program doesn’t go into a loop if something goes wrong in the ABEND routine. The next lines, up to but not including the ESCAPE label, read the escape message that was unmonitored and send the message back to the caller, as a diagnostic message. The SNDPGMMSG (Send Program Message) command cancels the program by sending an escape message.

In many shops, the typical CL program contains nothing but overrides and a CALL. I encourage you to make it a standard in your shop that CL programs must include commands to handle unexpected errors.

–Ted