+

Search Tips   |   Advanced Search

CommandRunner utility job step

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

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

True or false to indicate whether the command line runs in debug mode or not. Debug mode prints debug messages to assist us 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

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

Shell executor command. 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

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

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

Default value for the com.ibm.websphere.batch.shell.executor job step property.

(Windows) The default is cmd.exe /c.

(AIX) (HPUX) (Solaris) (Linux) (ZOS) The default is sh -c.

com.ibm.websphere.batch.command.runner.shell.failure_rc

Default value for the com.ibm.websphere.batch.shell.failure.rc job step property.

(Windows) The default is 1.

(AIX) (HPUX) (Solaris) (Linux) (ZOS) The default is 127.


Property substitution

The CommandRunner utility job step supports property substitution for expansion. We 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.


Related:

  • Compute-intensive programming model
  • Batch programming model
  • xJCL sample for a compute intensive job
  • XML schema for a native execution job
  • Native execution job state table
  • Requirements-based job scheduling
  • Administer the batch environment