BPXBATCH - Run shell commands, shell scripts, or executable files
Format
BPXBATCH SH [program_name] | PGM program_name
where program_name is an optional parameter that is passed to SH or a required parameter when PGM is used. Optional suffix [RC] can be included on either SH or PGM, where the requirements for each are the same, respectively.
Description
BPXBATCH makes it easy for you to run, from your TSO/E session, shell scripts or z/OS® XL C/C++ executable files that reside in z/OS UNIX files. To use it when running shell scripts and executable files that reside in files through job control language (JCL), see BPXBATCH.
With BPXBATCH, you can allocate stdin only as a z/OS UNIX file for passing input. You can allocate 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.
BPXBATCH SH
PXBATCH SH [program_name]
PXBATCH PGM program_name
In addition to using BPXBATCH, 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. It provides users with an alternate entry point into BPXBATCH, and forces a program to run 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 program_name'
/* 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
BPXBATSL is also useful when the user wants to perform a local spawn of their program, but also needs subsequent child processes to be fork/exec'ed. Formerly, with BPXBATCH, this could not be done because BPXBATCH and the requested program shared the same environment variables.
BPXBATSL is an alias of BPXBATCH.
- The PGM keyword is the only invocation type that is supported. The SH keyword is not supported.
- The interfaces can only be used from started task address spaces.
- The z/OS UNIX program that is the target of the BPXBATA2 and BPXBATA8 job must be marked as an APF-authorized executable file.
Parameters
- SH|PGM
- Specifies whether BPXBATCH is to run a shell script or command, or a z/OS C/C++ executable file located in a z/OS
UNIX file. If neither SH nor PGM is specified, BPXBATCH assumes that the shell is to be started in order to run the shell script allocated by stdin.
- SH
- Instructs BPXBATCH to start the shell and to run shell commands or scripts provided from stdin
or the specified program_name. BPXBATCH passes all of the argument data,
blanks included as is, to the shell as one parameter.
BPXBATCH PARM='SH command string'
If you specify SH with no program_name information, BPXBATCH attempts to run anything read in from stdin.
SH is the default.
- PGM
- Instructs BPXBATCH to run the specified program_name as a called
program. This is done either via a spawn or a fork and exec. BPXBATCH creates a process for the
program to run in and then calls the program. BPXBATCH breaks each argument up that is separated by
one or more blanks into multiple parameters passed to the target program, taking out the blanks.
BPXBATCH PARM='PGM arg1 ... argn'
If you specify PGM, you must also specify program_name.
All environment variables read from stdenv are set when the program is run, if stdenv was allocated. If the HOME and LOGNAME environment variables are not specified in the stdenv file, or stdenv was not allocated, then HOME and LOGNAME, if possible, are set when the program is run.
When using PGM, the program_name parameter cannot contain any shell-specific functions because they will not be resolved. If shell specific functions must be specified, then SH should be used to avoid possible errors or unpredictable results.
- program_name
- Specifies the shell command name or path name for the shell script
or z/OS XL C/C++ executable
file that you want to run. program_name can
also contain option information. program_name must
be in uppercase and lowercase letters.
When PGM and program_name are specified and the specified program name does not begin with a slash character (/), BPXBATCH prefixes the user's initial working directory information to the program path name.
Arguments that may be passed to the program specified by program_name are determined by the program being passed to PGM as a parameter. For more information about arguments that may be passed to the program, refer to the documentation of the program.
Examples
- You want to run the shell script that you specify with stdin.
ALLOCATE FILE(STDIN) PATH('/stdin_file_pathname') PATHOPTS(ORDONLY) BPXBATCH SH
- You want to run the program /usr/bin/payroll.
BPXBATCH PGM /usr/bin/payroll
- You want to run the script shellscriptA and put its output into the file
a.out in a temporary directory.
BPXBATCH SH /u/usr/joe/shellscriptA > /tmp/a.out