OA47398: BPXBATCH DOCUMENTATION UPDATES

APAR status

• Closed as documentation error.

Error description

• BPXBATCH Return Code Documentation Updates
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of z/OS UNIX System Services       *
  ****************************************************************
  * PROBLEM DESCRIPTION: Documentation for BPXBATCH return codes *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  Clarification for BPXBATCH return codes is needed.
  

Problem conclusion

• Book Title - Unix System Services Command Reference
  Chapter - Appendix D. Running shell scripts or executable
            files under MVS environments
  Section - BPXBATCH Return Codes
  .
  A - General rules of setting the return code
   When running a shell script, your joblog should reflect the
   failure in the script if you code
      'set -o errexit'
   in the script itself.  The command 'set -o errexit' tells
   the non-interactive shell to execute the ERR trap and then
   exit.  As soon as the script encounters an error, processing
   of the shell script ends, and you may see a console message
   like:
     $HASP165 jobname  ENDED AT PLPSC  MAXCC=23
   In the JOBLOG you may find:
     IEF142I jobname  *OMVSEX - STEP WAS EXECUTED - COND CODE 0023
  
   Without 'set -o errexit' coded in your script, the script is
   going to keep executing even if it encounters an error, and
   the last shell command issued in your script is what will be
   reflected in the joblog.  If this last shell command is
   successful, then you get MAXCC=00.
  .
   Return Codes < 128 indicate a failure of the command.  You
   need to look at the application script running to determine
   what the RC means.  The script is either setting the return
   code explicitly or the last command executed in the script
   has an exit status equalling the RC.
  .
   If the Exit Status >= 128 it means that the process was
   terminated by a signal.  Subtract 128 from the RC to get
   the signal number.  A list of signal numbers and their
   function is documented in:
     z/OS UNIX System Services Programming:
          Assembler Callable Services Reference
     Appendix G - The relationship of z/OS UNIX signals to
                  callable services
     Table - z/OS UNIX signals
  .
  For example, if the return code is 157, the signal number is
  157-128  which is Signal 29.  Signal 29 is SIGXCPU -
  CPU time limit exceeded.
  .
  The shell command kill can be used to find the signal
  number.  If nnn is the return code,
  shell command  'kill -l nnn' will return the signal name.
  For example:
   kill -l 157    returns XCPU
  .
  B - Circumstances that cause the internal and real return code
      to be multiplied by 256 before being issued by BPXBATCH.
   - BPXBATCH is run from within a TSO environment.
   - Environment variable _BPX_BATCH_SPAWN=YES is set.
     (This means using spawn instead of Fork/Exec.)
   - STDOUT and/or STDERR are pointing to an MVS data set or to
     SYSOUT.
  .
  C. Examples of interpreting BPXBATCH return codes in
     different environment.
  
   - The OSHELL REXX exec invokes BPXBATCH to run non-
     interactive shell commands from the TSO/E READY prompt.
  
     Issuing 'tso oshell exit 255' results in RC = 65280.  The
     value 65280 is set by multiplying the return code 255 by
     256 (255 * 256 = 65280).
  
   - A job or job step return code can only be a remainder of a
     value divided by 4096.  In the previous example, where the
     return code was 65280, the return code would be converted as
     follows:  65280//4096 = 3840.
  
   - In a situation with a BPXBATCH job (not running under TSO)
     and STDOUT and STDERR pointing to the default /dev/null or
     to a UNIX file, it is the environment variable
     _BPX_BATCH_SPAWN that decides how the return code is set and
     what you can find in the job log.
  
     Using the simple UNIX command 'exit 3' as an example,
     following is what the return codes would be:
  
   > BPXBATCH jobstep information for _BPX_BATCH_SPAWN=YES:
     JOBNAME  STEPNAME PROCSTEP    RC
     jobname  OMVS                 768
   > BPXBATCH jobstep information for _BPX_BATCH_SPAWN=NO:
     JOBNAME  STEPNAME PROCSTEP    RC
     jobname  OMVS                 00
     jobname  *OMVSEX              00
     jobname  *OMVSEX              03
  
   - The following examples are all taken from an
     environment having BPXBATCH using STDOUT and STDERR pointing
     directly to SYSOUT:
    //OMVS     EXEC PGM=BPXBATCH,PARM='SH sleep 300'
    //STDOUT   DD SYSOUT=*,LRECL=137,RECFM=VB
    //STDERR   DD SYSOUT=*,LRECL=137,RECFM=VB
  
   After starting the job, the sleep process can be stopped by
   sending a signal to the job.
   > kill -s signame process
     (signame is the signal name - for example USR1 for SIGUSR1
      process is the process ID )
  
   The following is a table of signals sent to the process via
   the kill command and the return codes in the job output:
  
   Signal  Signal                        Job
   number  name   Calculation            RC   Comments
   ------  ------ --------------------   ---  ------------------
       1   HUP    ((128+01)*256)//4096   256  Same as with RC=1
       3   ABRT   ((128+03)*256)//4096   768
       9   KILL   ((128+09)*256)//4096  2304  (**)
      14   ALRM   ((128+14)*256)//4096  3584
      15   TERM   ((128+15)*256)//4096  3840
      16   USR1   ((128+16)*256)//4096     0  RC=0 but not OK
      17   USR2   ((128+17)*256)//4096   256  Same as signal 1
      24   QUIT   ((128+24)*256)//4096  2048
      25   TSTP   ((128+25)*256)//4096  2304  Same as signal 9
  
   It is hard to decipher the signal sent from the return code
   for several reasons:
    - Signal 16 and 32 result in a RC = 0, which generally
      indicates successful job completion
    - Signal x and signal x+16 both end up having the same
      return code - one signal cannot be distinguished
      from the other.  For example Signal 9 and signal 25 (9+16)
      both have RC = 2304.
  
     However, with STDERR, you will normally see a CEE message
     showing the actual signal causing the proces to stop/end:
       CEE5208S The signal SIGname was received.
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

  OA46726

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels