Use the CommandRunner utility job step to run shell command
lines as job steps. The shell command lines can include shell commands,
shell scripts, and compiled programs.
The CommandRunner utility runs the specified shell command
line in an operating system process. Standard output and standard
error streams are captured and written to the job log. The command-line
return code is captured and set as the step return code. If the job
step is canceled, the return code is -8.
Command syntax
Use the following syntax
for the CommandRunner utility:
<job-step name={step_name}>
<classname>com.ibm.websphere.batch.utility.CommandRunner</classname>
{job_step_properties}
</job-step>
For example, the following job step
code runs a command-line Java program:
<job-step name="RunJava">
<classname>com.ibm.websphere.batch.utility.CommandRunner</classname>
<props>
<prop name="com.ibm.websphere.batch.cmdLine"
value="java.exe com.ibm.websphere.batch.samples.TestCase" />
<prop name="CLASSPATH" value="${user.dir}\testcases;${user.dir}\bin" />
<prop name="Path" value="${java.home}\bin;${env:Path}" />
</props>
</job-step>
Required job step property
The following
property is required for the CommandRunner utility job step.
- com.ibm.websphere.batch.cmdLine
- Specifies the command-line invocation, including arguments.
For
example, run the
java.exe file as the command
line:
<prop name="com.ibm.websphere.batch.cmdLine"
value="java.exe com.ibm.websphere.batch.samples.TestCase" />
Optional job step properties
The following
properties are optional for the CommandRunner utility job step.
- com.ibm.websphere.batch.workingDir
- Specifies working directory in which the specified command-line
runs.
For example, enable
/tmp as the working
directory on Linux:
<prop name="com.ibm.websphere.batch.workingDir" value="/tmp" />
The
default is undefined.
- com.ibm.websphere.batch.debug
- Specifies true or false to indicate
whether the command line runs in debug mode or not. Debug mode prints
debug messages to assist you in resolving problems with variable substitution
and other issues that prevent command lines from running correctly.
For
example, enable the debug mode:
<prop name="com.ibm.websphere.batch.debug" value="true" />
The
default is false.
- com.ibm.websphere.batch.expansion
- Specifies true or false to enable
or disable job step property expansion, also known as property substitution.
Disable this feature to improve step performance for steps with large
property maps that do not depend on property expansion.
For example,
disable property expansion:
<prop name="com.ibm.websphere.batch.expansion" value="false" />
The
default is true.
- com.ibm.websphere.batch.shell.executor
- Specifies the shell executor command. Use this property to specify
a custom shell as your command-line executor.
For example, specify
a custom shell as
fastshell:
<prop name="com.ibm.websphere.batch.shell.executor" value="fasthell" />
The
default is the value of the com.ibm.websphere.batch.command.runner.shell.executor
system property.
- com.ibm.websphere.batch.shell.failure.rc
- Specifies the shell execution failure return code. This return
code is returned by the shell executor to indicate the specified command
line can not be run. When the shell executor return code matches
the shell failure return code value, the CommandRunner utility job
sets the job step return code to the value of com.ibm.websphere.batch.step.failure.rc
property.
For example, the shell returns
-1 when
the specified command line fails to run:
<prop name="com.ibm.websphere.batch.shell.failure.rc" value="-1" />
The
default is the value of the com.ibm.websphere.batch.command.runner.shell.failure_rc
system property.
- com.ibm.websphere.batch.step.failure.rc
- Specifies the job step return code when the command line fails
to execute. This job step return code is returned when the shell
executor return code matches the value of com.ibm.websphere.batch.shell.failure.rc.
For
example, the job step returns
-1 when the shell fails
to run:
<prop name="com.ibm.websphere.batch.step.failure.rc" value="-1" />
System properties
All the CommandRunner utility
system properties are optional.
- com.ibm.websphere.batch.command.runner.shell.executor
- Specifies the default value for the com.ibm.websphere.batch.shell.executor
job step property.
- com.ibm.websphere.batch.command.runner.shell.failure_rc
- Specifies the default value for the com.ibm.websphere.batch.shell.failure.rc
job step property.
Property substitution
The CommandRunner utility
job step supports property substitution for expansion. You can do
expansion using xJCL substitution properties, Java system properties, and process variables
as demonstrated in the following examples.
- xJCL substitution property
- The following example substitutes the testcase.dir xJCL substitution
property as a working directory.
<prop name="com.ibm.websphere.batch.workingDir" value="${testcase.dir}" />
- Java system property
- The following example substitutes the user.dir Java system property
in CLASSPATH process variable:
<prop name="CLASSPATH" value="${user.dir}/classes" />
- Process variable
- The following example substitutes the PATH process variable in
the new value of the PATH process variable:
<prop name="PATH" value="/tmp:${env:PATH}" />
Important: Substitution properties are treated as Java system
properties, if they are displayed in the Java system properties list.
Otherwise, they are treated as xJCL substitution properties. Process
variable substitution is denoted by the special ${env:<variable
name>} syntax.
Process variables
The CommandRunner utility
adds all job step properties, after substitution, to the process variable
pool for the process in which the specified command-line runs.