Related information
BPXBATCH makes it easy
for you to run shell scripts and executable files that reside in z/OS® UNIX files
through the MVS™ job control language
(JCL). If you do most of your work from TSO/E, using BPXBATCH saves
you the trouble of going into the shell to run your scripts and executable
files. REXX execs
can also use BPXBATCH to run shell scripts and executable files.
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. BPXBATSL
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.
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, this could not be done since BPXBATCH and the requested
program shared the environment variables. Failure to meet the following
conditions will result in a failure when BPXBATSL is invoked. For
more details about these restrictions, see the descriptions of the
spawn() function and BPX1SPN callable service in z/OS UNIX System Services Programming: Assembler Callable Services Reference:
- The invoker must have an UID of 0 to issue a SH request
- The child process is not setuid or setgid to a value different
from the parent
- The spawned file name is not an external link or a sticky bit
file
- The parent has enough resources to allow the child process to
reside in the same address space
BPXBATSL is an alias of BPXBATCH.
BPXBATA2
and BPXBATA8 are provided as APF-authorized alternatives to BPXBATSL.
BPXBATA2 and BPXBATA8 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, job log, and so on. BPXBATA2 is
specifically intended to provide the capability for APF-authorized z/OS UNIX program
to be started in a PSW Key 2 . To insure 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 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.
Format
For JCL:
EXEC PGM=BPXBATCH,PARM='SH|PGM program_name'
For TSO/E:
BPXBATCH SH|PGM program_name
Description
The BPXBATCH program allows
you to submit MVS batch jobs
that run shell commands or scripts, or z/OS XL C/C++ executable
files. You can invoke BPXBATCH from a JCL job or from TSO/E (as a
command, through a CALL command, or from a CLIST or REXX EXEC).
With
BPXBATCH, you can allocate the MVS standard
file stdin only as z/OS UNIX files for passing input. You
can allocate the MVS standard
files 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.
For MVS data sets, use the standard data
definition options for MVS data
sets.
For JCL jobs, specify PATH keyword options on DD statements:
//jobname JOB …
//stepname EXEC PGM=BPXBATCH,PARM='SH|PGM program_name'
//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
⋮
Your application in the executable file can also
allocate stdin, stdout, stderr, and stdenv dynamically
through the use of SVC 99.
For TSO/E, you specify PATH keyword
options on the ALLOCATE command:
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|PGM program_name
stdin and stdenv must
always be allocated as read. stdout and stderr must
always be allocated as write.
As previously stated, 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. BPXBATSL 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
Parameters
BPXBATCH accepts one parameter
string as input, the combination of SH|PGM and program_name. At least
one blank character must separate the parts of the parameter string.
The total length of the parameter string will now support up to 32754
characters.
BPXBATCH was first created for use with JCL,
which had a maximum parameter length of 100. Now, BPXBATCH can also
be called form CLIST, REXX,
and TSO. These additional environments do not have the 100 character
parameter limit. From a TSO command environment the parameter string
itself will now support up to 32754 characters.
Parameters
to BPXBATCH can also be supplied via the STDPARM DD up to a limit
of 65,536 characters. When the STDPARM DD is allocated BPXBATCH will
use the data found in the z/OS UNIX file
or MVS data set associated with
this DD rather than what is found on the parameter string or in the
STDIN DD. An informational message BPXM079I is displayed indicating
that this is occurring, as a warning to the user. The STDPARM DD
will allow either a z/OS UNIX file,
or a MVS SYSIN, PDS or PDSE member
or a sequential data set.
If neither SH nor PGM is specified
as part of the parameter string, BPXBATCH assumes that the shell is
to be started 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 located in a z/OS UNIX file.
- SH
- Specifies that the shell designated in your TSO/E user ID's security
product profile is to be started and is to run shell commands or scripts
provided from stdin or the specified program_name.
If SH
is specified with no program_name information, BPXBATCH attempts to
run anything read in from stdin.
- PGM
- Specifies that the program identified by the program_name parameter
is invoked directly from BPXBATCH. 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. If you specify PGM, you must also
specify program_name.
All environment variables read from the
stdenv file are set when the program is run if stdenv was allocated.
If the HOME and LOGNAME 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.
Refer to Usage notes for more information about environment
variable processing.
Restriction: When using PGM, the
program_name 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 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.
The program_name is interpreted as case-sensitive.
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.
Usage notes
- 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 translate characters on the supplied parameter
information. You should supply parameter information, including z/OS UNIX path
names, using only the POSIX portable character set. For information
about the POSIX portable character set, see z/OS UNIX System Services Programming Tools.
- If your BPXBATCH job returns ABEND 4093 reason code 0000001c,
you need to expand the region size. For example:
//SHELLCMD EXEC PGM=BPXBATCH,REGION=8M,PARM='SH shell_cmd'
- BPXBATCH does not support any ddnames other than stdin, stdout,
stderr, stdenv or stdparm . Attempting to allocate or reference any
other ddnames will result in enqueue failures or unpredictable results.
To use an MVS data set in your
batch UNIX application, use "dynamic allocation",
such as SVC99 or the TSO ALLOC command. Also, you must remove all
"static allocations" (ddnames referring to the MVS data set in question) from all steps in the
batch job.
- If you define an MVS data
set for stdout or stderr, consider the following:
- It must be a sequential data set, a partitioned data set (PDS)
member, a partitioned data set extended (PDSE) member, or SYSOUT.
- The data set must have a nonzero logical record length (LRECL)
and a defined record format (RECFM); otherwise, BPXBATCH will fail
with error message BPXM012I indicating an open failure for the affected
ddname.
- If the LRECL of the target STDOUT or STDERR data set is not large
enough to hold a line of output, the data will be truncated and message
BPXM080I will be put out indicating this has occurred. This can happen
for both fixed and variable blocked data sets. For variable block
data sets, the first four bytes of each record, record segment, or
block make up a descriptor word containing control information. You
must allow for these additional 4 bytes in the specified LRECL if
you intend to avoid truncation of the output to the STDOUT and STDERR
DDs.
- If you use two members of the same partitioned data set for the
STDOUT and STDERR ddnames, then you must use a PDSE (not a PDS). Using
a PDS instead of a PDSE can result in a 213 abend (and, if running
in a batch job, an abnormal end for the job step) or the output not
appearing in the members as expected.
- When you specify an MVS data
set for either the STDOUT or STDERR ddnames, a child process will
be created to run the target z/OS UNIX program.
In some cases, the child process will run in a separate address space
from the BPXBATCH job. In such cases, the job log messages for the
child will not appear in the job log of the BPXBATCH job. To capture
the child's job log messages, set the _BPXK_JOBLOG=STDERR environment
variable. This will cause the child's job log messages to be written
to the STDERR data set specified in the BPXBATCH job.
- In early releases of z/OS,
if a MVS data set were specified
on stdout or stderr, BPXBATCH ignored the data set and defaulted to /dev/null.
To remain compatible with this behavior, the current support does
the same defaulting if the MVS data
set type is not supported (for example, DD Dummy, Terminal, or SYSIN),
or if the MVS data set cannot
be opened by BPXBATCH. Also, message BPXM081I is displayed that indicates
when this default behavior is being taken by BPXBATCH.
- If STDOUT or STDERR are allocated as a PDS or PDSE member and
overwriting of the output is expected from multiple runs of the same
job or command, the data set should not be allocated with a disposition
of NEW but rather as SHR or OLD. If the data set is allocated as NEW,
the member will be created on the 1st run, but subsequent runs will
cause i/o errors when attempting to write to the member.
- If STDOUT or STDERR are allocated as a sequential data set and
appending of the output is expected from multiple runs of the same
job or command, the data set should be allocated with a disposition
of MOD.
- In general, any I/O errors that occur with an MVS data set defined to the STDOUT or STDERR
(or STDPARM or STDENV, described below) ddnames will result in an
abend (x13 or x37, for instance) and, if running in a batch job, an
abnormal end for the job step, except for an abend B37, which will
be ignored. For example: If the user does not have security access
to the data set defined to STDOUT, then when BPXBATCH attempts to
open the data set, a 913 abend will occur and message IEC150I will
provide details about the error.
- To avoid the possibility of a timeout abend when directing STDOUT
and STDERR to an MVS data set
or to SYSOUT, specify TIME=1440 (NOLIMIT) on the EXEC statement.
- BPXBATCH now supports a parameter string up to 32754 characters
when called from a TSO command environment. Also from both a batch
and TSO environment, up to 65,536 characters can now be supplied via
the a new input DD named stdparm. When the stdparm DD
is allocated BPXBATCH will use the data found in the z/OS UNIX file or MVS data set associated with this DD rather that
what is found on the parameter string or in the stdin DD. As a warning
to the user, an informational message BPXM079I will be displayed indicating
that this is occurring.
The stdparm DD will allow either a z/OS UNIX file,
or an MVS SYSIN PDS, PDSE or
sequential data set. The following are characteristics of the parameter
data that can be supplied in the stdparm DD, if a z/OS UNIX file is specified:
- It must be a text file defined with read access only
- Specify one argument per line
- The file cannot have sequence numbers in it.
Tip: If
you use the ISPF editor to create the file, set the sequence numbers
off by typing number off on the command line before
you begin typing data. If sequence numbers already exist, type UNNUM to
remove them and then type number off.
If a MVS data set is specified:
- Specify one argument per line. If the parameter string for an
argument spans more than one line of a data set or file, this string
will be divided into two or more arguments that are passed to the
corresponding shell script or program.
- The maximum length of a single argument supplied to the program
is 32,760, which is the same as the maximum LRECL for an unspanned
non-VSAM data set.
- The record format of the data set can fixed or variable (unspanned).
- The data set cannot have sequence numbers in it. If you use the
ISPF editor to edit the data set, set the sequence numbers off by
typing number off on the command line before you begin typing in the
data. If sequence numbers already exist, type UNNUM to remove them
and set number mode off.
- Trailing blanks are truncated for SYSIN and variable block data
sets, but not for fixed block data sets. For a fixed block data set,
trailing blanks will be included in the parameter text for a given
argument up to the end of the record.
- BPXBATCH does not close file descriptors other than 0–2.
Other file descriptors that are open and not defined as “marked to
be closed” remain open when you call BPXBATCH and 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 messages can be displayed
at the terminal.
- BPXBATCH (with the SH parameter) must not be used to run an executable
file, shell command, or shell script in the background (by specifying
the shell & symbol) unless the shell nohup command
is also used. If the shell ampersand (&) symbol is used without nohup,
the results are unpredictable.
- BPXBATCH, when used with the PGM parameter, sets up environment
variables for the program to be run. If the stdenv file is not allocated,
the HOME and LOGNAME environment variables are set. If stdenv is allocated,
the environment variables read from the file it represents are set,
with HOME or LOGNAME or both environment variables added if they are
not specified in the stdenv file. The following types of files can
be allocated to stdenv:
- z/OS UNIX text
file
- Sequential format MVS data
set (including SYSIN data set)
- Member of a partitioned data set (PDS)
- Member of a partitioned data set extended (PDSE)
Other
forms of MVS data sets, such
as DUMMY, TERMINAL, or SYSOUT are not supported for stdenv.
The
stdenv file consists of one or more records, where
record is
defined as a string terminated with a <newline> character (
X'15')
in a z/OS UNIX file,
or a fixed or variable (nonspanned) format record in an MVS data set. Other MVS record
formats are not supported for stdenv. The following rules apply to
the specification of environment variables in
stdenv files:
- Only one environment variable can be specified per record.
- Each environment variable is specified as variable=value.
- Environment variable names must begin in column 1, unless names
beginning with blanks are used.
- Environment variable records should not be terminated with null
characters (X'00'). BPXBATCH automatically appends a null
character to the end of each environment variable, and the lengths
of environment variables as seen by the program include the null characters.
- Trailing blanks (X'40') are truncated for MVS SYSIN data sets, but are not truncated for
any other type of file.
- Be careful that sequence numbers are not present in MVS data sets, because they will be treated as
part of the environment variables. ISPF edit users should always
set number mode off when creating environment variables, including
JCL data sets with environment variables specified as SYSIN.
Some environment variables are release-dependent. If
BPXBATCH is executed on a system that does not support the environment
variable, you will not get an error message and the variable will
be ignored. Use the uname shell command
to determine the release number of the operating system that BPXBATCH
is running on.
Environment variables (including PATH) are established
at the start of the executable program, not for BPXBATCH itself. Thus,
PATH is not searched to locate the program, but instead is used if
the program invokes other executable programs. In the following example,
someprogram may
be found only in the initial working directory defined by the user's
profile, not by the PATH environment variable:
//jobname JOB …
//stepname EXEC PGM=BPXBATCH,PARM='PGM someprogram parm1 parm2'
//STDOUT DD PATH='/tmp/pgmout',PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDENV DD *
PATH=/bin:/u/usr/joeuser
STEPLIB=SYS1.JOE.STEPLIB
/*
- BPXBATCH uses two more environment variables for execution that
are specified by STDENV:
- _BPX_BATCH_UMASK=0755
- _BPX_BATCH_SPAWN=YES|NO
_BPX_BATCH_UMASK allows the user the flexibility of modifying
the permission bits on newly created files instead of using the default
mask (when PGM is specified).
Note: This variable is overridden by
umask (usually set from within /etc/profile)
if BPXBATCH is invoked with the 'SH' option (SH is the default). SH
causes BPXBATCH to execute a login shell which runs the /etc/profile
script (and runs the user's .profile) and which may set the umask
before execution of the intended program.
_BPX_BATCH_SPAWN
causes BPXBATCH to use SPAWN instead of fork/exec and allows data
definitions to be carried over into the spawned process. When _BPX_BATCH_SPAWN
is set to YES, spawn will be used. If it is set to NO, which is equivalent
to the default behavior, fork/exec will be used to execute the program.
If
_BPX_BATCH_SPAWN is set to YES, then you must consider two other environment
variables that affect spawn (BPX1SPN):
- _BPX_SHAREAS = YES|NO|REUSE|MUST
When YES or REUSE, the child
process created by spawn will run in the same address space. Failure
to meet these conditions will result in a spawn failure when MUST
is used. For more detail about these restrictions see the descriptions
of the spawn() function and BPX1SPN callable service in
z/OS UNIX System Services Programming: Assembler Callable Services Reference:
- The invoker must have an UID of 0 to issue a SH request
- The child process is not setuid or setgid to a value different
from the parent
- The spawned file name is not an external link or a sticky bit
file
- The parent has enough resources to allow the child process to
reside in the same address space
- The NOSHAREAS extended attribute is not set
When no, the child and parent run in separate address
spaces.
- _BPX_SPAWN_SCRIPT=YES
Spawn will recognize a header in the
first line of a z/OS UNIX file
that indicates the file to be executed and its first set of arguments.
This header will only be recognized when a z/OS UNIX file is not found in an executable
format. The format of the header is as follows:
#! Path String
where
#! is
the file magic number. The magic number indicates that the first line
of a file is a special header that contains the name of the program
to be executed and any argument data to be supplied to it.
When
_BPX_SPAWN_SCRIPT=yes, spawn will first recognize the file magic number
and will process the file accordingly. If the file magic number is
not found in the file's first line, spawn will treat the specified
file as a shell script and will invoke the shell to run the shell
script.
For more information
about spawn, see BPX1SPN in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
- When using BPXBATCH with the SH parameter, environment
variables specified in the STDENV DD are overridden by those specified
in /etc/profile and .profile (which overrides
/etc/profile). This is because SH causes BPXBATCH to execute
a login shell which runs the /etc/profile script
and runs the user's .profile.
Files
- SYS1.LINKLIB(BPXMBATC) is the BPXBATCH program location.
- The stdin default is /dev/null.
- The stdout default is /dev/null.
- The stderr default is the value of stdout. If all defaults
are accepted, stderr is /dev/null.
- stdenv default is /dev/null.
Return codes
- 0
- Processing successful.
- 254
- Processing unsuccessful. BPXBATCH requires OMVS to be started.
- 255
- Processing unsuccessful. An error message has been issued.
- 4095
- Processing unsuccessful. An error message has been issued.
- 32000
- BPXBATCH invoked the BPX1FRK (fork) callable service. This is
usually invoked only by a TSO/E user. One of the following conditions
may have resulted:
- BPXBATCH failed to open specified files after the program fork.
Files are normally opened and closed prior to a fork. Try running
BPXBATCH again.
- The program_name or the shell exited with an exit status of 125.
- 32512
- One of the following conditions may have resulted:
- other multiples of 256
- A return code greater than 255, unless explicitly
documented as a return code from BPXBATCH (32000 or 32512),
is actually an exit status being returned from the program that was
invoked by BPXBATCH. The exit status can be determined by dividing
the value of BPXYWAST by 256.
- BPXYWAST
- BPXBATCH invoked the BPX1FRK (fork) callable service. This is
usually invoked only by a TSO/E user. Processing was successful with
wait() status containing a nonzero value. The wait status was mapped
by BPXYWAST and returned by BPX1WAT (wait).
No error messages were
issued by BPXBATCH.