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
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
. //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
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 fromstdin
. - 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
, orstderr
. - BPXBATCH does not close file descriptors except for
0
,1
, and2
. Other file descriptors that are open and not defined asmarked 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 ofstdout
. If all defaults are accepted,stderr
is/dev/null
.