BPXBATCH utility

This information provides a quick reference for the IBM-supplied BPXBATCH program. BPXBATCH makes it easy for you to run shell scripts and z/OS® XL C/C++ executable files that reside in z/OS UNIX files through the z/OS batch environment. If you do most of your work from TSO/E, use BPXBATCH to avoid going into the shell to run your scripts and applications.

In addition to using BPXBATCH, if you want to perform a local spawn without being concerned about environment set-up (that is, without having to set specific environment variables, which could be overwritten if they are also set in your profile) you can use BPXBATSL. BPXBATSL, which provide you with an alternate entry point into BPXBATCH, and force a program to run using a local spawn instead of fork or exec as BPXBATCH does. This ultimately allows a program to run faster.

BPXBATSL is also useful when you want to perform a local spawn of your program, but also need subsequent child processes to be forked or executed. Formerly, with BPXBATCH, this could not be done since BPXBATCH and the requested program shared the same environment variables. BPXBATSL is provided as an alternative to BPXBATCH. It will force the running of the target program into the same address space as the job itself is initiated in, so that all resources for the job can be used by the target program; for example, DD allocations. In all other respects, it is identical to BPXBATCH.

For information on c89 commands, see c89 — Compiler invocation using host environment variables.

BPXBATCH usage

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

JCL: Use one of the following:

EXEC PGM=BPXBATCH,PARM='SH program-name'
EXEC PGM=BPXBATCH,PARM='PGM program-name'

TSO/E: Use one of the following:

BPXBATCH SH program-name
BPXBATCH PGM program-name

BPXBATCH allows you to allocate the z/OS standard files stdin, stdout, and stderr as z/OS UNIX files for passing input, for shell command processing, and writing output and error messages. If you do allocate standard files, they must be z/OS UNIX files. If you do not allocate them, stdin, stdout, and stderr default to /dev/null. You allocate the standard files by using the options of the data definition keyword PATH.

Note: The BPXBATCH utility also uses the STDENV file to allow you to pass environment variables to the program that is being invoked. This can be useful when not using the shell, such as when using the PGM parameter.

Example: For JCL jobs, specify PATH keyword options on DD statements; for example:

//jobname JOB …
 
//stepname EXEC PGM=BPXBATCH,PARM='PGM program-name parm1 parm2'
 
//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
⋮

You can also allocate the standard files dynamically through use of SVC 99.

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

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 program-name

You must always allocate stdin as read. You must always allocate stdout and stderr as write.

Parameter

BPXBATCH accepts one parameter string as input. At least one blank character must separate the parts of the parameter string. When BPXBATCH is run from a batch job, the total length of the parameter string must not exceed 100 characters. When BPXBATCH is run from TSO, the parameter string can be up to 500 characters. If neither SH nor PGM is specified as part of the parameter string, BPXBATCH assumes that it must start the shell to run the shell script allocated by stdin.

SH | PGM

Specifies whether BPXBATCH is to run a shell script or command or a z/OS XL C/C++ executable file that is located in a z/OS UNIX file.

SH: Instructs BPXBATCH to start the shell, and to run shell commands or scripts that are provided from stdin or the specified program-name.
Note: If you specify SH with no program-name information, BPXBATCH attempts to run anything read in from stdin.
PGM: Instructs BPXBATCH to run the specified program-name as a called program.
If you specify PGM, you must also specify program-name. BPXBATCH creates a process for the program to run in and then calls the program. The HOME and LOGNAME environment variables are set automatically when the program is run, only if they do not exist in the file that is referenced by STDENV. You can use STDENV to set these environment variables, and others.

program-name

Specifies the shell command or the z/OS UNIX path name for the shell script or z/OS XL C/C++ executable file to be run. In addition, program-name can contain option information.

BPXBATCH interprets the program name as case-sensitive.

Note: When PGM and program-name are specified and the specified program name does not begin with a slash character (/), BPXBATCH prefixes your initial working directory information to the program path name.

Usage notes

You should be aware of the following:

BPXBATCH is an alias for the program BPXMBATC, which resides in the SYS1.LINKLIB data set.
BPXBATCH must be invoked from a user address space running with a program status word (PSW) key of 8.
BPXBATCH does not perform any character translation on the supplied parameter information. You should supply parameter information, including z/OS UNIX path names, using only the POSIX portable character set.
A program that is run by BPXBATCH cannot use allocations for any files other than stdin, stdout, or stderr.
BPXBATCH does not close file descriptors except for 0, 1, and 2. Other file descriptors that are open and not defined as "marked to be closed" remain open when you call BPXBATCH. BPXBATCH runs the specified script or executable file.
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 BPXBATCH can display messages to the terminal.

Files

The following list describes the files:

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