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).
- EXEC PGM=BPXBATCH,PARM='SH program-name'
- EXEC PGM=BPXBATCH,PARM='PGM program-name'
- BPXBATCH SH program-name
- BPXBATCH PGM program-name
//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.
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
- 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.