How to Cancel a Job

Published: March 15, 2006

Hey, Ted:

I have what I hope is a simple question. A CL program that runs in batch mode calls an RPG program, passing parameters to it. If the RPG program finds a certain error, it sets one of those parameters to a certain value, sets on the LR indicator, and ends. At this point, the CL program ends, but the message that it generates gives the caller the impression that the job ran OK. How do I make the program end abnormally?

--Mike

That's a good, basic question, Mike, and I understand why you bring it up. This phenomenon drove me nuts when I first started programming a System/38. In the first issue of Four Hundred Guru this year, I mentioned that I would try to devote more attention to the fundamentals. This is one of those fundamentals that everybody should know, and you'll be glad to know that this is an easy problem to solve.

First, let's recreate the problem for the benefit of all readers. Here's CL program D600C.

PGM                                        
DCL        VAR(&STATUS) TYPE(*CHAR) LEN(1) 
CALL       PGM(D600R) PARM(&STATUS)
IF         COND(&STATUS *NE ' ') THEN(RETURN)
CALL       PGM(D610R)
CALL       PGM(D620R)
ENDPGM

RPG program D600R does some sort of verification on the SOMECODE field. If SOMECODE does not have an appropriate value, D600R sets the STATUS parameter to X and shuts down immediately.

C     *entry        plist                                       
C                   parm                    status            1 
C                                                               
C                   eval      Status = ' '                      
C                                                               
C                   if        Somecode < 'A' or Somecode > 'E'  
C                   eval      status = 'X'                      
C                   eval      *inlr = *on                       
C                   return                                      
C                   endif

And what does the user see? Something like this:

Job 123456/JSMITH/SOMEJOB completed normally on 03/08/06 at 10:26:43.

Poor user. He thinks everything is hunky dory. The solution is to make the CL program tell the operating system that something went wrong. Fortunately, that is an easy thing for CL to do. Here is the revised CL program D600C.

PGM                                               
DCL        VAR(&STATUS) TYPE(*CHAR) LEN(1)        
CALL       PGM(D600R) PARM(&STATUS)             
IF         COND(&STATUS *NE ' ') THEN(SNDPGMMSG + 
             MSGID(CPF9898) MSGF(QCPFMSG) +       
             MSGDTA('Program ended abnormally') + 
             MSGTYPE(*ESCAPE))                    
CALL       PGM(D610R)
CALL       PGM(D620R)
ENDPGM

If the status code does not have a blank value, D600C knows that something went wrong during the execution of D600R. D600C sends an escape message. The user sees the following message.

Job 123456/JSMITH/SOMEJOB ended abnormally.

To learn more about escape messages, see the links to previously published articles below.

--Ted

RELATED STORIES:

Proper CL Error-Handling

Sending Escape Messages from RPG

Programming with Assertions