Which return code to use and when to consider a job complete when submitted from CA 7 to Unix agent

Document ID : KB000055493
Last Modified Date : 14/02/2018
Show Technical Document Details

By default ENF will wait for all background processes to exit before declaring a job as complete, and will assign the return code of the last process to exit to the JOB RC (TRIGGER=LAST/RC=LAST). To change the default to declaring a job complete on exit of the main job script, as is the case when workload runs without ENF, enter the following commands:

  1. echo "enfcontrol JOB TRIGGER EXITMAIN" >>
    $CAIGLBL0000/enf/scripts/rc.local
  2. chmod +x $CAIGLBL0000/enf/scripts/rc.local 
  3. unicycle all

The "WLM" entry in the "enfcontrol 105" command output should now look similar to the following:

    CAIENF-I-APPL[WLM]  UP, PID=<cau9en2.exe pid>, MsgQ=xxx, 
    RC=LAST, TRIGGER=MAIN, CPU=LAST 

Note that for "TRIGGER=MAIN" the "RC" and "CPU" settings are irrelevant since the exit of the main script will end the job.

The default setting can be overwritten for individual jobs by adding

 "enfcontrol JOB TRIGGER EXITLAST" (or 
EXITMAIN)

statements to the beginning of the main job script.

=========================================================================

Here is a sample scenario to explain the two TRIGGER options EXITLAST and EXITMAIN.

Below is the default processing that occurs when CA 7 submits a shell script for execution and that shell script in turn executes other programs and shell scripts:

Job JOB001 (previously defined to CA 7 ) is ready for execution, and the shell script /jobs/job001/script01 is submitted.

/jobs/job001/script01 is:

date
    # Issue UNIX date command
progxyz
    # Execute program progxyz inline, 
    # which consumes 3 seconds of cpu time, 
    # and 10 seconds of wall clock time 
    # before completing. 
/jobs/job001/script02 & 
    # Execute shell script 
    # /jobs/job001/script02 
    # in the background 
    # (as an asynchronous # process) 
exit 25
    # terminate script 
    # /jobs/job001/script01 
    # with an exit code of 25. Elapsed 
    # wall clock time 11 seconds, elapsed 
    # cpu time less than 4 seconds.

/jobs/job001/script02 (which was executed by /jobs/job001/script01) is:

 progabc
    # Execute program progabc inline, 
    # which consumes 40 minutes of cpu time
    # and 90 minutes of wall clock time 
    # before completing.
exit 35
    # terminate script 
    # /jobs/job001/script02 
    # with an exit code of 35. Elapsed
    # wall clock time 91 minutes, elapsed 
    # cpu time just over 40 minutes.

In this example, CAIENF notifies CA 7 that job JOB001 has completed only after the shell script /jobs/job001/script02 has exited, which is approximately 80 minutes after the originally submitted job shell script, /jobs/job001/script01, exited.

Additionally, the CPU time recorded for JOB001 is the combination of CPU time used by both shell scripts (in this case, 131 minutes) and the last exit code reported back to CA 7 (in this case, 35).

CAIENF collects all the appropriate data automatically and presents this data to CA 7 only after all processes associated with the job submitted are completed. You can see this information on the UNIX machine by dumping the contents of the UNIX checkpoint file and checking the JOBTERMU record written for the job. To dump the checkpoint file use the command $CAIGLBL0000/sche/bin/cau9ckl.exe -j "*".

This information is kept by the day of the year and time. The most recent activity will be at the end of this output.

Now, consider a job that completes as soon as the primary shell script completes.

For the previous example, this means considering the job JOB001 complete when the shell script /jobs/job001/script01 has exited.

    enfcontrol JOB TRIGGER EXITMAIN 

instructs CAIENF to consider a job as completed when the main process (in the sample scenario, shell script /jobs/job001/script01) of the job has completed.

If this option were in effect in our sample scenario, CAIENF would alert CA 7 the completion of job JOB001 when /jobs/job001/script01 exited.

Two other enfcontrol options are provided, which have special meaning only if enfcontrol JOB TRIGGER EXITLAST is in effect:

When enfcontrol JOB TRIGGER EXITMAIN is in effect, both the RC and the accumulated CPUTIME of a job are taken from the exit of the main process comprising the job.

enfcontrol JOB RC

This option indicates whether the exit return code presented by CAIENF to CA 7 is the exit code of the main process (shell script) or of the last process associated with this job. This can only be used if enfcontrol JOB TRIGGER EXITLAST is in effect XITLAST is in effect:

Syntax

    enfcontrol JOB RC [EXITMAIN|EXITLAST] 

For example, if the following option was in effect in our sample scenario, the exit return codes that CAIENF presented to CA 7 component would have been 25: ( only if enfcontrol JOB TRIGGER EXITLAST is in effect )

    enfcontrol JOB RC EXITMAIN

If enfcontrol JOB RC EXITLAST were in effect, the exit return code presented would have been 35.