MAINFRAMES COND Parameter

COND Parameter, Job Abend

Q. What is Return-Code(Condition Code)?

When you run COBOL Programs by typing a Job, and submitting it, how do you tell, whether the COBOL Program ran fine, or not? COBOL Programs use Code-Language to tell you about their success/failure. When a COBOL Program runs, it leaves behind a signature(trail) in the form of a 2-Digit Status Code, that indicates whether the COBOL Program completed successfully, or it completed with errors. This 2-digit number trail left behind by a COBOL Program, to indicate its success or failure is called Return-Code(Condition Code). I've written a job SYSADMB that's running the ready-made program IEFBR14 in //STEP01, and IEBGENER free program in //STEP02. As I said, whenever COBOL Programs complete, they set a COND CODE, to indicate if they completed successfully, or completed with errors. The log-report of the job would display the COND CODE set by the COBOL Program. The picture below shows the JESYSMSG Listing in the Spool. //STEP01 that runs IEBR14 COBOL Program has set COND CODE = 00. This means IEFBR14 completed without errors successfully. //STEP02 that runs IEBGENER COBOL Program has set COND CODE = 00. This implies IEBGENER was able to copy the contents from //SYSUT1 file to //SYSUT2 File, without any errors successfully. Thus, Return Code(Condition-code) is set by the COBOL Program to send out signals to the outside-world, a code 0 could be Successful Completion, a code 5 could mean completed with warnings, a code 10 could stand for Bad-Input-Data etc. In other words, Return Code(COND CODE) represents communication from the COBOL Program to the Outside-world.

Q. How do I know, what's a good condition-code and what's a bad one?

The COBOL Program sets the COND CODE. If you have written your own custom COBOL Program, you are the COBOL Programmer, you would set the Return-Codes in the COBOL Program. You know what each Condition-Code would mean. But, what if you haven't written the COBOL Program – say it's your friend's COBOL Program, or think of the ready-made free programs supplied to you by IBM like IEBGENER or SORT. How do you tell what's a good acceptable Condition-code, from IEBGENER and which are bad condition-codes? Well, most Programs come along with a documentation manual, which if you read, you would know, what the Program does, and the possible COND CODE that the Program sets. Generally IBM Software such as the free programs IEBGENER, SORT, IEFBR14, IEBPTPCH, compiler IGYCRCTL, Linkage Editor IEWL and other ready-made utility programs, follow this convention with the COND CODE Values - COND CODE 00 – Program execution was completely successful. COND CODE 04 – Program execution was successful, but with warnings. COND CODE 08 – Program execution was seriously flawed, it failed. COND CODE 12 – Program execution was very seriously flawed, severe errors. COND CODE 16 – Program execution disastrously failed.

Q. What is COND Parameter?

In a multi-step job-stream, that contains several steps, you often wish to turn off a certain step. When you want to turn off(shut off) a step, when you don't want to run a step in a Job(JCL), you code the COND Parameter on the EXEC Statement. Thus, COND Parameter is used to turn-off or skip a step. I've written a simple ten-step Toy Job to illustrate the idea – how you can turn-off or skip steps using COND. When you code COND Parameter on a Step, before running the step, first the COND condition is gonna be checked. If the COND Condition is true, the step is turned-off(shut off) or flushed. Only when the condition is false, then the step runs. In the above example, //STEP03 runs the ready-made free program IEFBR14. Suppose IEFBR14 completes successfully and sets COND CODE = 00. Before running //STEP05, first COND Condition is checked. Ask yourself the question, Is 0 EQ(Equal to) STEP03's COND CODE? As 0 EQ 00, the COND Condition is satisfied, so the //STEP05 will be turned-off or skipped off. Why is this useful? Think about it, say you've written a 3-step Compile-Link-Go job, to compile your own custom COBOL Program, Link-Edit it and then run it. If your program is syntactically correct, the compiler is able to compile successfully and issues a COND CODE 00. You go ahead and Link the Program, and then run it. But, what if your COBOL Program is faulty? The Compiler completes with errors and issues a COND CODE 08. If the compiler issues errors, there is no point in continuing with further Link-editing processing. You would want to go back and correct your COBOL Program first. So, I want to shut-off the //LINK Step, if the compiler issues severe errors, and the //COMPILE Step leaves behind a COND CODE Greater than 4(like an 08, or a 12). Let me put it this way - Turn-off(Do not execute) the //LINK Step, if 4 Less Than(LT) COND CODE of //COMPILE //LINK    EXEC PGM=IEWL,COND=(4,LT,COMPILE) Makes sense doesn't it? Let me go a step further and say, you don't want to run the Program either if the Compiler issues errors, or if the Link-Editor fails. Look at the GO Step below - //GO      EXEC PGM=*.LINK.SYSLMOD, //  COND=((4,LT,COMPILE),(4,LT,LINK)) This COND is saying, "If 4 is less than the COND CODE of the //COMPILE Step, or if 4 is less than the COND CODE of the //LINK Step, in either of the cases, turn-off(shut off) the //GO Step". We wouldn't try and //GO if either the //COMPILE or the //LINK edit failed. This is fairly easy to grasp.

Q. What is the general format of COND?

The general pattern of coding COND Parameter on the EXEC Statement is - COND=(value,operator,step-name) For example, This tests the COND CODE of //STEP03. The mantra you would recite is, Do NOT execute this step, if 4 is Less Than(LT) COND CODE of //STEP03. But what if, you want to turn-off(skip) //STEP05, if any of the prior steps – either //STEP01, or //STEP02, or //STEP03, or //STEP04 fails? You do not want to test for the COND CODE of a fixed particular step, but in general you wanna test for the COND CODE of any prior(previous) step. That's when you don't type an explicit step-name like //STEP03, but instead leave it blank. The COND says, Do Not Execute this step, if 4 is Less Than(LT) the COND CODE set by any of the previous(prior) steps. If you want to make a Compound-test(a test involving two to eight individual tests), you code COND in this way.

Q. What is a Job Abend?

When good and well-designed Programs encounter an exceptional error, they trap it, and set a non-zero return code and terminate grace-fully. Bad return codes are one thing. But, sometimes the Program attempts to execute an instruction at the machine code level, which is logically impossible to perform. The MVS OS has to kill the program. This abnormal termination of the program or crash is called an Abend. Every Abend leaves behind a System Abend-Code Sxxxx-yyy.  There are also other problems like, Out-of-Space Issues(Too less space to create a dataset), I-O Errors while opening a dataset, the dataset not being available that cause a crash - an Abend.  Look at the toy-job, in the picture below. There are ten steps in this toy job, each step runs a program.    Each step STEP010, STEP020, STEP030, STEP040 runs the free ready-made COBOL Program IEFBR14. I have coded STEP050 to manually raise an Abend – it runs S806 program(well there's no such program really by the name S806), so the job abends at STEP050(Load Module not found – abend code S806). When the job abends at STEP050, the job is in a hurry(rush) to go to the Abend Exit Door. The Operating System says, "Nothing doing, you'll be kicked out, flushed!". The job can no longer continue any further processing on the Mainframe Computer, all the remaining steps STEP060, STEP070, STEP080, STEP090 and STEP100 are flushed(skipped), and the job is kicked out to the Output Queue Area. When I hit Submit, on the 10-step toy job, STEP010 runs successfully, STEP020 runs, STEP030 runs fine, STEP040 runs and then kaboom! At STEP050, the job abends, as the Program(Load) that you wanna run is not found – it sets an Abend-Code S806. The job is kicked out to the Output Queue,  and all the remaining steps are flushed out, skipped – no further processing can continue. So, STEP060, STEP070, STEP080, STEP090 and STEP100 everything gets flushed. The log-report of the job, as seen in the Spool is shown in the picture below.  As shown the job abends at STEP050 with abend-code S806, Load Module not found. In the picture below, all the successive steps STEP060, STEP070, STEP080 and so on, have been flushed.

Q. What is COND=EVEN and COND=ONLY?

To understand what EVEN and ONLY do, you need bear in mind, that the MVS OS "sees" every job running either in the Normal Processing Mode, or in the Abnormal Termination Mode. Of course, when you hit SUB on a job, all jobs start out in the Normal Processing Mode. If everything goes well, the job completes successfully. Sometimes, due to a fatal error, which the program is unable to handle(for example Bad Data – S0C4 Error), the program gets killed or terminated.  When a program Abends, and the job goes into Abnormal Termination Mode, it is in a hurry(rush) to go to the Abend-Exit door, and no further processing is allowed to continue, all the remaining steps are flushed out(skipped), and the job is kicked out to the Output Queue. In this rush, if you still want stick your foot out in this process, and say, "Hey wait a minute, I still want to run this step!". Ordinarily, MVS will simply flush out all the remaining successive steps, after a program fails. But, coding an EVEN or ONLY allows you to run some last-minute steps, when a job abends.  When you code a COND=EVEN on a step, its like Force-executing a step. When you code //STEP070 EXEC PGM=IEFBR14,COND=EVEN it reads as, even if the job abends at any of the previous steps, force-run this STEP070. Even if the job is in Abnormal Termination Mode, run this step! Abend or no-abend, doesn't matter, always run this STEP070. No matter, whether the job is Normal-Processing Mode or Abnormal-Termination mode, always run this step, darn it! Thus, coding a COND=EVEN forces the step //STEP070 to run, even if the job is in Abnormal Termination mode, which would have otherwise flushed-out(skipped) all the remaining steps. In the ten-step toy-job below, when I hit SUB on the job, the job blows-up(abends) at STEP050. The Log report of the above job in Spool is shown in the picture below. At STEP050 the job abends with an Abend code S806 – Load Module Not found. STEP060, STEP080, STEP090 and STEP100 are flushed(skipped). COND=EVEN causes STEP070 to run.   When you code a COND=ONLY on a step, it runs the step ONLY when the job abends. ONLY causes a step to run, only if the job is already in Abnormal Termination Mode. For example, when I code - //STEP070 EXEC PGM=IEFBR14,COND=ONLY It implies, run STEP070 only if the job abends at any of the previous steps. If the job is in Normal Processing mode, don't run this step. Neither EVEN nor ONLY do any checking on COND CODE(Return Code) Values.