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.

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 z/OS UNIX files 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.

Note: The stream of data in the file associated with the STDIN DD is supplied as input to either the target shell program (for the SH case) or target z/OS UNIX program (PGM case) via File Descriptor 0, which is the traditional UNIX standard input (stdin). This data is then read and handled by the shell or the designated program. BPXBATCH itself does nothing with the data in the file.

To display BPXBATCH syntax using multiple commands, use one of the following:

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.

The following example contains DD statements that are accessible to a program that was given control from BPXBATSL:

//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.

BPXBATA2 and BPXBATA8 are provided as APF-authorized alternatives to BPXBATSL. They provide the capability for a target APF-authorized z/OS UNIX program to run in the same address space as the originating job, allowing it to share the same allocations and job log, and so on. BPXBATA2 is specifically intended to provide the capability for a PSW Key 2 APF-authorized z/OS UNIX program to be started. To ensure that the target program receives control PSW Key 2, a PPT entry for BPXBATA2 must be set up that specifies that BPXBATA2 starts up PSW Key 2. The same restrictions that apply to BPXBATSL also apply to BPXBATA2 and BPXBATA8, in addition to the following:

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.

Any other usage of the BPXBATA8 and BPXBATA2 interfaces than what is described is not supported and will cause the invoking job to fail.

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'

Rule: 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.

Restriction: 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 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
```