BPXBATCH

Format

For JCL:
EXEC PGM=BPXBATCH,PARM='SH[RC]|PGM[RC] command_string'
 
For TSO/E:
BPXBATCH SH[RC] [command_string]
BPXBATCH PGM[RC] command_string

Description

The BPXBATCH program allows you to submit MVS batch jobs that run shell commands or scripts, or z/OS XL C/C++ executable files. You can invoke BPXBATCH from a JCL job or from TSO/E (as a command, through a CALL command, or from a CLIST or REXX EXEC).

With BPXBATCH, you can allocate the MVS standard file stdin only as z/OS UNIX files for passing input. You can allocate the MVS standard files stdout, stderr or stdenv as MVS data sets or z/OS UNIX text files. The stdenv file for containing environment variables or the stderr and stdout files for saving job output can be allocated as SYSOUT, PDSE, PDS, or sequential data sets. If you do not allocate them, stdin, stdout, stderr, and stdenv default to /dev/null. Allocate the standard files using the data definition PATH keyword options, or standard data definition options for MVS data sets, for stdenv, stdout and stderr.

For MVS data sets, use the standard data definition options for MVS data sets.

For JCL jobs, specify PATH keyword options on DD statements:

//jobname JOB ...
//stepname EXEC PGM=BPXBATCH,PARM='SH | PGM | SHRC | PGMRC command_string'
//STDIN DD PATH='/stdin-file-pathname',PATHOPTS=(ORDONLY)
//STDOUT DD PATH='/stdout-file-pathname',PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDERR DD PATH='/stderr-file-pathname',PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU

Your application in the executable file can also allocate stdin, stdout, stderr, and stdenv dynamically by using SVC 99.

For TSO/E, you specify PATH keyword options on the ALLOCATE command:

ALLOCATE FILE(STDIN) PATH('/stdin-file-pathname') PATHOPTS(ORDONLY)
ALLOCATE FILE(STDOUT) PATH('/stdout-file-pathname')
         PATHOPTS(OWRONLY,OCREAT,OTRUNC) PATHMODE(SIRWXU)
ALLOCATE FILE(STDERR) PATH('/stderr-file-pathname')
         PATHOPTS(OWRONLY,OCREAT,OTRUNC) PATHMODE(SIRWXU)
 
BPXBATCH SH|PGM command_string

stdin and stdenv must always be allocated as read. stdout and stderr must always be allocated as write.

As previously stated, a user who wants to perform a local spawn without being concerned about environment setup (that is, without having to set specific environment variables, which could be overwritten if they are also set in the user's profile) can use BPXBATSL. BPXBATSL provides users with an alternate entry point into BPXBATCH, and forces a program to run by using a local spawn instead of fork/exec as BPXBATCH does. This ultimately allows a program to run faster.

//jobname JOB ...

//stepname EXEC PGM=BPXBATSL,PARM='PGM command_string'
/* The following 2 DDs are still available in the program which gets 
/* control from BPXBATSL.
//DD1       DD DSN=MVSDSN.FOR.APPL1,DISP=SHR
//DD2       DD DSN=MVSDSN.FOR.APPL2,DISP=SHR
/* The following DDs are processed by BPXBATSL to create file descriptors 
/* for stdin, stdout, stderr
//STDIN   DD  PATH='/stdin-file-pathname',PATHOPTS=(ORDONLY)
//STDOUT  DD  PATH='/stdout-file-pathname',PATHOPTS=(OWRONLY,OCREAT,OTRUNC
//            PATHMODE=SIRWXU
//STDERR  DD  PATH='/stderr-file-pathname',PATHOPTS=(OWRONLY,OCREAT,OTRUNC
//            PATHMODE=SIRWXU

Parameters

BPXBATCH accepts one parameter string as input, the combination of SH | PGM | SHRC | PGMRC and command_string. At least one blank character must separate the parts of the parameter string. The total length of the parameter string supports up to 32754 characters.

BPXBATCH was first created for use with JCL, which had a maximum parameter length of 100. Now, BPXBATCH can also be called form CLIST, REXX, and TSO. These additional environments do not have the 100 character parameter limit. From a TSO command environment, the parameter string itself will now support up to 32754 characters.

Parameters to BPXBATCH can also be supplied by using the stdparm DD up to a limit of 65,536 characters. When the stdparm DD is allocated BPXBATCH will use the data that is found in the z/OS UNIX file or MVS data set associated with this DD rather than what is found on the parameter string or in the stdin DD. An informational message BPXM079I is displayed indicating that this is occurring, as a warning to the user. The stdparm DD will allow either a z/OS UNIX file, or an MVS SYSIN, PDS, or PDSE member or a sequential data set.

Usage notes for BPXPBATCH

1. BPXBATCH is an alias for the program BPXMBATC, which resides in the SYS1.LINKLIB data set.
2. BPXBATCH must be invoked from a user address space running with a program status word (PSW) key of 8.
3. BPXBATCH does not convert characters on the supplied parameter information. You should supply parameter information, including z/OS UNIX path names, using only the POSIX portable character set.
4. If your BPXBATCH job returns ABEND 4093 reason code 0000001c, you need to expand the region size. For example:

   //SHELLCMD  EXEC PGM=BPXBATCH,REGION=8M,PARM='SH shell_cmd'

5. BPXBATCH does not support any ddnames other than stdin , stdout, stderr, stdenv or stdparm. Attempting to allocate or reference any other ddnames will result in enqueue failures or unpredictable results. To use an MVS data set in your batch UNIX application, use "dynamic allocation", such as SVC99 or the TSO ALLOC command. Also, you must remove all "static allocations" (ddnames referring to the MVS data set in question) from all steps in the batch job.
6. If you define an MVS data set for stdout or stderr, consider the following:
   • It must be a sequential data set, a partitioned data set (PDS) member, a partitioned data set extended (PDSE) member, or SYSOUT.
   • The data set must have a nonzero logical record length (LRECL) and a defined record format (RECFM); otherwise, BPXBATCH will fail with error message BPXM012I indicating an open failure for the affected ddname.
   • If the LRECL of the target stdout or stderr data set is not large enough to hold a line of output, the data will be truncated and message BPXM080I will be put out indicating this has occurred. This can happen for both fixed and variable blocked data sets. For variable block data sets, the first four bytes of each record, record segment, or block make up a descriptor word containing control information. You must allow for these additional 4 bytes in the specified LRECL if you intend to avoid truncation of the output to the stdout and stderr DDs.
   • If you use two members of the same partitioned data set for the stdout and stderr ddnames, then you must use a PDSE (not a PDS). Using a PDS instead of a PDSE can result in a 213 abend (and, if running in a batch job, an abnormal end for the job step) or the output not appearing in the members as expected.
   • When you specify an MVS data set for either the stdout or stderr ddnames, a child process will be created to run the target z/OS UNIX program. In some cases, the child process will run in a separate address space from the BPXBATCH job. In such cases, the job log messages for the child will not appear in the job log of the BPXBATCH job. To capture the child's job log messages, set the _BPXK_JOBLOG=STDERR environment variable. This will cause the child's job log messages to be written to the stderr data set specified in the BPXBATCH job.
   • In early releases of z/OS, if a MVS data set were specified on stdout or stderr, BPXBATCH ignored the data set and defaulted to /dev/null. To remain compatible with this behavior, the current support does the same defaulting if the MVS data set type is not supported (for example, DD Dummy, Terminal, or SYSIN), or if the MVS data set cannot be opened by BPXBATCH. Also, message BPXM081I is displayed that indicates when this default behavior is being taken by BPXBATCH.
   • If stdout or stderr are allocated as a PDS or PDSE member and overwriting of the output is expected from multiple runs of the same job or command, the data set should not be allocated with a disposition of NEW but rather as SHR or OLD. If the data set is allocated as NEW, the member will be created on the 1st run, but subsequent runs will cause i/o errors when attempting to write to the member.
   • If stdout or stderr are allocated as a sequential data set and appending of the output is expected from multiple runs of the same job or command, the data set should be allocated with a disposition of MOD.
   • In general, any I/O errors that occur with an MVS data set defined to the stdout or stderr (or stdparm or stdenv) ddnames will result in an abend (x13 or x37, for instance) and, if running in a batch job, an abnormal end for the job step, except for an abend B37, which will be ignored. For example: If the user does not have security access to the data set defined to stdout, then when BPXBATCH attempts to open the data set, a 913 abend will occur and message IEC150I will provide details about the error.
   • To avoid the possibility of a timeout abend when directing stdout and stderr to an MVS data set or to SYSOUT, specify TIME=1440 (NOLIMIT) on the EXEC statement.
7. BPXBATCH supports a parameter string up to 32754 characters when called from a TSO command environment. Also from both a batch and TSO environment, up to 65,536 characters can now be supplied via the a new input DD named stdparm. When the stdparm DD is allocated BPXBATCH will use the data found in the z/OS UNIX file or MVS data set associated with this DD rather that what is found on the parameter string or in the stdin DD. As a warning to the user, an informational message BPXM079I will be displayed indicating that this is occurring.
   The stdparm DD will allow either a z/OS UNIX file, or an MVS SYSIN PDS, PDSE or sequential data set. The following are characteristics of the parameter data that can be supplied in the stdparm DD, if a z/OS UNIX file is specified:

   • It must be a text file defined with read access only.
   • Specify one argument per line.
   • The file cannot have sequence numbers in it.
     Tip: If you use the ISPF editor to create the file, set the sequence numbers off by typing number off on the command line before you begin typing data. If sequence numbers already exist, type UNNUM to remove them and then type number off.

   If a MVS data set is specified:

   • Specify one argument per line. If the parameter string for an argument spans more than one line of a data set or file, this string will be divided into two or more arguments that are passed to the corresponding shell script or program.
   • The maximum length of a single argument supplied to the program is 32,760, which is the same as the maximum LRECL for an unspanned non-VSAM data set.
   • The record format of the data set can fixed or variable (unspanned).
   • The data set cannot have sequence numbers in it. If you use the ISPF editor to edit the data set, set the sequence numbers off by typing number off on the command line before you begin typing in the data. If sequence numbers already exist, type UNNUM to remove them and set number mode off.
   • Trailing blanks are truncated for SYSIN and variable block data sets, but not for fixed block data sets. For a fixed block data set, trailing blanks will be included in the parameter text for a given argument up to the end of the record.
8. BPXBATCH does not close file descriptors other than -2. Other file descriptors that are open and not defined as marked to be closed remain open when you call BPXBATCH and BPXBATCH runs the specified script or executable file.
9. BPXBATCH uses write-to-operator (WTO) routing code 11 to write error messages to either the JCL job log or your TSO/E terminal. Your TSO/E user profile must specify WTPMSG so that messages can be displayed at the terminal.
10. BPXBATCH (with the SH parameter) must not be used to run an executable file, shell command, or shell script in the background (by specifying the shell & symbol) unless the shell nohup command is also used. If the shell ampersand (&) symbol is used without nohup, the results are unpredictable.
11. BPXBATCH, when used with the PGM parameter, sets up environment variables for the program to be run. If the stdenv file is not allocated, the HOME and LOGNAME environment variables are set. If stdenv is allocated, the environment variables read from the file it represents are set, with HOME or LOGNAME or both environment variables added if they are not specified in the stdenv file. The following types of files can be allocated to stdenv:
    • z/OS UNIX text file
    • Sequential format MVS data set (including SYSIN data set)
    • Member of a partitioned data set (PDS)
    • Member of a partitioned data set extended (PDSE)

    Other forms of MVS data sets, such as DUMMY, TERMINAL, or SYSOUT are not supported for stdenv.

    The stdenv file consists of one or more records, where record is defined as a string terminated with a <newline> character (X'15') in a z/OS UNIX file, or a fixed or variable (nonspanned) format record in an MVS data set. Other MVS record formats are not supported for stdenv. The following rules apply to the specification of environment variables in stdenv files:

    • Only one environment variable can be specified per record.
    • Each environment variable is specified as variable=value.
    • Environment variable names must begin in column 1, unless names beginning with blanks are used.
    • Environment variable records should not be terminated with null characters (X'00'). BPXBATCH automatically appends a null character to the end of each environment variable, and the lengths of environment variables as seen by the program include the null characters.
    • Trailing blanks (X'40') are truncated for MVS SYSIN data sets, but are not truncated for any other type of file.
    • Be careful that sequence numbers are not present in MVS data sets, because they will be treated as part of the environment variables. ISPF edit users should always set number mode off when creating environment variables, including JCL data sets with environment variables specified as SYSIN.

    Some environment variables are release-dependent. If BPXBATCH is executed on a system that does not support the environment variable, you will not get an error message and the variable will be ignored. Use the uname shell command to determine the release number of the operating system that BPXBATCH is running on.

    Environment variables (including PATH) are established at the start of the executable program, not for BPXBATCH itself. Thus, PATH is not searched to locate the program, but instead is used if the program invokes other executable programs. In the following example, someprogram might be found only in the initial working directory defined by the user's profile, not by the PATH environment variable:

    //jobname JOB ...
     
    //stepname EXEC PGM=BPXBATCH,PARM='PGM someprogram parm1 parm2'
     
    //STDOUT  DD  PATH='/tmp/pgmout',PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
    //            PATHMODE=SIRWXU
    //STDENV  DD  *
    PATH=/bin:/u/usr/joeuser
    STEPLIB=SYS1.JOE.STEPLIB
    /*

12. BPXBATCH uses two more environment variables for execution that are specified by stdenv:
    • _BPX_BATCH_UMASK=0755
    • _BPX_BATCH_SPAWN=YES|NO
    The _BPX_BATCH_UMASK environment variable allows the user the flexibility of modifying the permission bits on newly created files instead of using the default mask (when PGM is specified).
    Note: This variable is overridden by umask (usually set from within /etc/profile) if BPXBATCH is invoked with the 'SH' option (SH is the default). SH causes BPXBATCH to execute a login shell which runs the /etc/profile script (and runs the user's .profile) and which may set the umask before execution of the intended program.
    _BPX_BATCH_SPAWN causes BPXBATCH to use SPAWN instead of fork/exec and allows data definitions to be carried over into the spawned process. When _BPX_BATCH_SPAWN is set to YES, spawn will be used. If it is set to NO, which is equivalent to the default behavior, fork/exec will be used to execute the program.
    If _BPX_BATCH_SPAWN is set to YES, then you must consider two other environment variables that affect spawn (BPX1SPN):

    • _BPX_SHAREAS = YES|NO|REUSE|MUST

      When YES or REUSE, the child process created by spawn will run in the same address space. Failure to meet these conditions will result in a spawn failure when MUST is used.

      The invoker must have an UID of 0 to issue a SH request.
      The child process is not setuid or setgid to a value different from the parent.
      The spawned file name is not an external link or a sticky bit file.
      The parent has enough resources to allow the child process to reside in the same address space.
      The NOSHAREAS extended attribute is not set.
      When no, the child and parent run in separate address spaces.
    • _BPX_SPAWN_SCRIPT=YES
      Spawn will recognize a header in the first line of a z/OS UNIX file that indicates the file to be executed and its first set of arguments. This header will only be recognized when a z/OS UNIX file is not found in an executable format. The format of the header is as follows:

      #! Path String

      where #! is the file magic number. The magic number indicates that the first line of a file is a special header that contains the name of the program to be executed and any argument data to be supplied to it.
      When _BPX_SPAWN_SCRIPT=yes, spawn will first recognize the file magic number and will process the file accordingly. If the file magic number is not found in the file's first line, spawn will treat the specified file as a shell script and will invoke the shell to run the shell script.
13. When using BPXBATCH with the SH parameter, environment variables specified in the stdenv DD are overridden by those specified in /etc/profile and .profile (which overrides /etc/profile). This is because SH causes BPXBATCH to execute a login shell which runs the /etc/profile script and runs the user's .profile.

Files

• SYS1.LINKLIB(BPXMBATC) is the BPXBATCH program location.
• The default for stdin is /dev/null.
• The default for stdout is /dev/null.
• The default for stderr is the value of stdout. If all defaults are accepted, stderr is /dev/null.
• The default for stdenv is /dev/null.

BPXBATCH return codes

0

Processing successful.

254

Processing unsuccessful. BPXBATCH requires OMVS to be started.

255

Processing unsuccessful. An error message was issued.

4095

Processing unsuccessful. An error message was issued.

32000

BPXBATCH invoked the BPX1FRK (fork) callable service. This is usually invoked only by a TSO/E user. One of the following conditions might have resulted:

• BPXBATCH failed to open specified files after the program fork. Files are normally opened and closed prior to a fork. Try running BPXBATCH again.
• The program or the shell exited with an exit status of 125.

32512

One of the following conditions might have occurred:

• The PGM keyword was specified for BPXBATCH and no program could be found.

  Message BPXM008I was written to the job log or stderr.

• The SH keyword was specified for BPXBATCH and either /bin/login or the shell did not exist.
• The SH keyword was specified with a command_string value for BPXBATCH and no program_name could be found. The shell exited with an exit status of 127. stdout contains a shell message indicating the program was not found.
• The program or the shell exited with an exit status of 127.

other multiples of 256

A return code greater than 255, unless explicitly documented as a return code from BPXBATCH (32000 or 32512), is actually an exit status being returned from the program that was invoked by BPXBATCH. The exit status can be determined by dividing the value of BPXYWAST by 256.

BPXYWAST

BPXBATCH invoked the BPX1FRK (fork) callable service. This is usually invoked only by a TSO/E user. Processing was successful with wait() status containing a nonzero value. The wait status was mapped by BPXYWAST and returned by BPX1WAT (wait).

No error messages were issued by BPXBATCH.

SHRC | PGMRC specified

If these parameters are specified, when the program is not terminated by a signal, the WastExitCode is right-justified into the return code for BPXMBATC. The return code should be in the range of 0-255 (decimal). If the program was terminated by a signal, the WastSigTerm holds the signal number that terminated the program. In this case, the byte is right justified and the low-order bit of the third byte is turned on. The range would be 256-320 (decimal) as shown in the following description of the WAST mapping.

The WAST mapping:

• ** BIT(16) - reserved space
• WastExitStatus BIT(16) - Exit status value
  • WastExitCode BIT(8) - Exit return code for ending process
  • WastSigTerm BIT(8) - Signal number that terminated the process.

General rules for setting return codes

$HASP165 jobname  ENDED AT PLPSC  MAXCC=23

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 is reflected in the job log. If this last shell command is successful, then you get MAXCC=00.

Return Codes < 128 indicates a failure of the command. You need to look at the application script that is running to determine what the return code means. The script is either setting the return code explicitly or the last command that is executed in the script has an exit status equaling the return code.

If Exit Status >= 128, the process was terminated by a signal. Subtract 128 from the RC to get the signal number.

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 returns the signal name. For example, kill -l 157 returns XCPU

Circumstances that cause the internal and real return code to be multiplied by 256 before being issued by BPXBATCH

Examples of interpreting BPXBATCH return codes in different environments

1. The OSHELL REXX exec invokes BPXBATCH to run noninteractive 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).

2. 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.
3. 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, the return codes would be as follows:

   > 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.
   Table 1 lists signals sent to the process via the kill command and the return codes in the job output:

   Table 1. Signals that are sent to the process via the kill command and the resulting return codes

   Signal number	Signal name	Calculation	Job return code	Comments
   1	HUP	((128+01)*256)//4096	256	Same as with RC=1
   3	ABRT	((128+03)*256)//4096	768	None
   9	KILL	((128+09)*256)//4096	2304	(**)
   14	ALRM	((128+14)*256)//4096	3584	None
   15	TERM	((128+15)*256)//4096	3840	None
   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	None
   25	TSTP	((128+25)*256)//4096	2304	Same as signal 9

   It is difficult 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 typically see a CEE message showing the actual signal causing the process to end:

   CEE5208S The signal SIGname was received