xJCL elements

xJCL elements

Jobs are expressed using an Extensible Markup Language XML dialect called xJCL (XML Job Control Language). This dialect has constructs for expressing all of the information needed for both compute-intensive and batch jobs, although some elements of xJCL are only applicable to compute-intensive or batch jobs. See the xJCL provided with the Sample applications, the xJCL table, and xJCL XSD schema document for more information about xJCL. The xJCL definition of a job is not part of the batch application, but is constructed separately and submitted to the job scheduler for to run. The job scheduler uses information in the xJCL to determine where and when to run the job.

xJCL elements

The following table summarizes the xJCL elements.

Element Java EE compute-intensive Java EE Batch Subelement Attributes Description
job yes yes

Scopes the description of a batch job.
job yes yes
name Name of the job. This name must match the name of the batch application unless default-application-name is specified.
job yes yes
accounting Optional accounting information attribute.
job yes yes
class Optional job class attribute, which identifies the job class under which the job runs.
job yes yes
default-application-name The application name to be used when no job step application-name attribute is found. The application name to be used. For OSGi batch applications, format the name as osgi:<eba name>:<version>.

job yes yes jndi-name
JNDI name givenn to the job controller stateless session bean when the batch application is deployed into the product.
job yes yes job-scheduling criteria required-capability The required-capability of the job, which must be defined on an endpoint for the job to be dispatched to that endpoint.
job yes yes step-scheduling criteria See step-scheduling-criteria element

job no yes checkpoint algorithm See checkpoint-algorithm element

job no yes results-algorithm See results-algorithms element

job yes yes substitution-props++ See prop element The required-capability of the job, which must be defined on an endpoint for the job to be dispatched to that endpoint
job-step yes* yes
name Optional name of the step. This information is returned on operational commands.
job-step yes* yes
application-name Optional name of the application run by the step. The attribute name is used if application-name is omitted and the job level attribute default-application-name is omitted.
job-step no yes step-scheduling See step-scheduling element Allows for conditional logic based on return codes of steps that determines whether the batch step is invoked.
job-step yes yes classname
Fully-qualified name of class that implements the compute intensive job.
job-step yes no checkpoint-algorithm-ref
Checkpoint algorithm to use for the batch job step.
job-step no yes results-ref See results-ref element Results algorithm to use for the conditional batch job step execution.
job-step no yes batch-data-streams See batch-data-streams element A sequence of bds elements. Each bds is the configuration information necessary to create a batch data stream.
job-step yes yes props See props element Name-value properties to pass to the step.
job-step no no exec See exec element Identifies the executable associated with the job step.
job-step no no env-entries See env-entries element Identifies the environmental properties associated with the job step.
prop yes yes

Single instance of a name value pair, that serves as a property.
prop yes yes
name Name of the property.
prop yes yes
value Value of the property.
props yes yes prop See prop element

env-entries no no

Series of prop elements used to pass name-value pair properties to steps, bds, checkpoint algorithms, and results algorithms.
env-entries no no env-var See env-var element

exec no no

Series of prop elements used to pass name-value pair properties to steps, bds, checkpoint algorithms, and results algorithms.
exec no no
executable The name of the executable associated with the job step.
exec no no arg See line element

line no no

Command-line arguments passed to the job step executable.
bds no yes

Single instance of a batch data stream implementation made available to the batch job.
bds no yes logical-name
A string that is embedded in batch step, which uses it to query the batch runtime environment for a specific batch data stream instance.
bds no yes impl-class
Fully- qualified class name of the batch data stream implementation class.
bds no yes props See props elements List of properties passed to the batch data stream implementation class.
batch-data-streams no yes

Series of bds elements
batch-data-streams no yes bds See bds element

step-scheduling no yes

Applies to job-steps to create return code-based conditional flows for a batch job. Compares values of return codes defined for this batch job to decide whether a step is invoked or not while processing a batch job. The values of return codes are compared using the returncode-expression element.
step-scheduling no yes returncode- expression see returncode-expression Returncode- expression to evaluate.
step-scheduling no yes
condition If there is more than one returncode-expression element in the step-scheduling element, conditional operators are applied to them. Conditional operators supported are: AND, OR.
returncode-expression no yes

Used under step-scheduling tags to decide whether a batch job step runs based on return codes of other job steps.
returncode-expression no yes
step Name of step whose return code is to be compared in this expression.
returncode-expression no yes
operator Operator to use for the return code expression. The supported operators are eq for equals, lt for less than, gt for greater than, le for less than or equal to, and ge for greater than or equal to.
returncode-expression no yes
value The value with which to compare the return code.
step-scheduling-criteria no yes

Describes the sequence in which the job steps are processed. Currently sequential scheduling is supported; for example, steps get invoked in the order in which they exist in xJCL.
step-scheduling-criteria no yes scheduling-mode
Sequence in which to invoke steps, only possible value is sequential right now.
checkpoint-algorithm no yes

Declares a checkpoint algorithm that can be used for a batch job step.
checkpoint-algorithm no yes
name Name of algorithm.
checkpoint-algorithm no yes classname
Class that implements this algorithm.
checkpoint-algorithm no yes props See props element Sequence of prop elements for the checkpoint algorithm.
checkpoint-algorithm-ref no yes

Reference to a checkpoint algorithm element.
checkpoint-algorithm-ref no yes
name Name of checkpoint algorithm to which we are referring.
checkpoint-algorithm-ref no yes props See props element. Sequence of prop elements for the checkpoint algorithm.

++ The xJCL element substitution-props is discussed in the following section.

xJCL substitution-props

The job xJCL can contain symbolic variables. A symbolic variable is an expression of the form ${variable-name}, which is found outside a comment in an otherwise well-formed document. For example:
<checkpoint-algorithm-ref name="${checkpoint}" />
The xJCL element, substitution-props, defines a default name and value pairs for symbolic variables. Following is an example of the substitution-props element, taken from the postingSampleXJCL.xml document:
<substitution-props>
<prop name="wsbatch.count" value="5" /> 
<prop name="checkpoint" value="timebased" />
<prop name="checkpointInterval" value="15" />
<prop name="postingsDataStream" value="${was.install.root}${file.separator}temp${file.separator}postings" />
</substitution-props>
Substitution for symbolic variables occurs at run time. At run time, the string ${variable-name} is replaced with the value of the property when the xJCL is submitted for execution. Using the properties in the previous example, the string ${checkpoint} is replaced with the string time-based before the job is submitted.

Symbolic variables can be indirect. For example: name=FILENAME value=${${filename}} used with the name/value pair filename=postingsDataStream yields the same result as specifying name=FILENAME value=${postingsDataStream}.

Symbolic variables can also be compound. For example, name=postingsDataStream value=${was.install.root}${file.separator}temp${file.separator}postings.

The name/value pairs do not have to be defined in the job document substitution-props element. The props name and value pairs defined in the substitution-props element are default values for the named variables. If not defined in the substitution-props element, name/value pairs must be either passed in via the job scheduler APIs when the job is submitted or defined in the system properties for the JVM. Every symbolic variable defined in the body of a job document must be resolved for the xJCL to be considered valid. Every name/value pair defined in the job document must resolve to a symbolic variable which is found in the body of the xJCL for the xJCL to be considered valid.

If name/value pairs are both defined in the xJCL document and passed to the job scheduler APIs at job submission time, the name/value pairs passed via the Job Scheduler APIs override the default values defined in the xJCL document. If name/value pairs are neither passed in via the job scheduler APIs nor defined as defaults in the xJCL document, name/value pairs for the symbolic variables must be defined in the system JVM properties for the xJCL to be considered valid.

Symbolic variables are resolved by the job scheduler before job submission, except for the following special variables, which are resolved at the grid endpoint. The following special variables all must be defined as JVM system properties. They are:

${was.install.root}
${user.install.root}
${agent.home}

Subtopics

Batch job state table
As the job scheduler and grid endpoint process a batch job, the job state updates in the job scheduler database. The diagram shows the relationship between states, and the following table lists the possible batch job states and the events that trigger transitions between states. We can view the current state of a batch job from the job management console, or retrieve it using the command line or EJB interface. If a failure occurs before a batch step initializes, then the batch job goes into execution failed state. Otherwise, it goes into restartable state.
Native execution job state table
As the job scheduler and grid endpoint process a native execution job, the job state updates in the job scheduler database.

Related:

XML schema for a batch job
xJCL sample for a batch job
Endpoint WebSphere variables

Element	Java EE compute-intensive	Java EE Batch	Subelement	Attributes	Description
job	yes	yes			Scopes the description of a batch job.
job	yes	yes		name	Name of the job. This name must match the name of the batch application unless default-application-name is specified.
job	yes	yes		accounting	Optional accounting information attribute.
job	yes	yes		class	Optional job class attribute, which identifies the job class under which the job runs.
job	yes	yes		default-application-name	The application name to be used when no job step application-name attribute is found. The application name to be used. For OSGi batch applications, format the name as osgi:<eba name>:<version>.
job	yes	yes	jndi-name		JNDI name givenn to the job controller stateless session bean when the batch application is deployed into the product.
job	yes	yes	job-scheduling criteria	required-capability	The required-capability of the job, which must be defined on an endpoint for the job to be dispatched to that endpoint.
job	yes	yes	step-scheduling criteria	See step-scheduling-criteria element
job	no	yes	checkpoint algorithm	See checkpoint-algorithm element
job	no	yes	results-algorithm	See results-algorithms element
job	yes	yes	substitution-props++	See prop element	The required-capability of the job, which must be defined on an endpoint for the job to be dispatched to that endpoint
job-step	yes*	yes		name	Optional name of the step. This information is returned on operational commands.
job-step	yes*	yes		application-name	Optional name of the application run by the step. The attribute name is used if application-name is omitted and the job level attribute default-application-name is omitted.
job-step	no	yes	step-scheduling	See step-scheduling element	Allows for conditional logic based on return codes of steps that determines whether the batch step is invoked.
job-step	yes	yes	classname		Fully-qualified name of class that implements the compute intensive job.
job-step	yes	no	checkpoint-algorithm-ref		Checkpoint algorithm to use for the batch job step.
job-step	no	yes	results-ref	See results-ref element	Results algorithm to use for the conditional batch job step execution.
job-step	no	yes	batch-data-streams	See batch-data-streams element	A sequence of bds elements. Each bds is the configuration information necessary to create a batch data stream.
job-step	yes	yes	props	See props element	Name-value properties to pass to the step.
job-step	no	no	exec	See exec element	Identifies the executable associated with the job step.
job-step	no	no	env-entries	See env-entries element	Identifies the environmental properties associated with the job step.
prop	yes	yes			Single instance of a name value pair, that serves as a property.
prop	yes	yes		name	Name of the property.
prop	yes	yes		value	Value of the property.
props	yes	yes	prop	See prop element
env-entries	no	no			Series of prop elements used to pass name-value pair properties to steps, bds, checkpoint algorithms, and results algorithms.
env-entries	no	no	env-var	See env-var element
exec	no	no			Series of prop elements used to pass name-value pair properties to steps, bds, checkpoint algorithms, and results algorithms.
exec	no	no		executable	The name of the executable associated with the job step.
exec	no	no	arg	See line element
line	no	no			Command-line arguments passed to the job step executable.
bds	no	yes			Single instance of a batch data stream implementation made available to the batch job.
bds	no	yes	logical-name		A string that is embedded in batch step, which uses it to query the batch runtime environment for a specific batch data stream instance.
bds	no	yes	impl-class		Fully- qualified class name of the batch data stream implementation class.
bds	no	yes	props	See props elements	List of properties passed to the batch data stream implementation class.
batch-data-streams	no	yes			Series of bds elements
batch-data-streams	no	yes	bds	See bds element
step-scheduling	no	yes			Applies to job-steps to create return code-based conditional flows for a batch job. Compares values of return codes defined for this batch job to decide whether a step is invoked or not while processing a batch job. The values of return codes are compared using the returncode-expression element.
step-scheduling	no	yes	returncode- expression	see returncode-expression	Returncode- expression to evaluate.
step-scheduling	no	yes		condition	If there is more than one returncode-expression element in the step-scheduling element, conditional operators are applied to them. Conditional operators supported are: AND, OR.
returncode-expression	no	yes			Used under step-scheduling tags to decide whether a batch job step runs based on return codes of other job steps.
returncode-expression	no	yes		step	Name of step whose return code is to be compared in this expression.
returncode-expression	no	yes		operator	Operator to use for the return code expression. The supported operators are eq for equals, lt for less than, gt for greater than, le for less than or equal to, and ge for greater than or equal to.
returncode-expression	no	yes		value	The value with which to compare the return code.
step-scheduling-criteria	no	yes			Describes the sequence in which the job steps are processed. Currently sequential scheduling is supported; for example, steps get invoked in the order in which they exist in xJCL.
step-scheduling-criteria	no	yes	scheduling-mode		Sequence in which to invoke steps, only possible value is sequential right now.
checkpoint-algorithm	no	yes			Declares a checkpoint algorithm that can be used for a batch job step.
checkpoint-algorithm	no	yes		name	Name of algorithm.
checkpoint-algorithm	no	yes	classname		Class that implements this algorithm.
checkpoint-algorithm	no	yes	props	See props element	Sequence of prop elements for the checkpoint algorithm.
checkpoint-algorithm-ref	no	yes			Reference to a checkpoint algorithm element.
checkpoint-algorithm-ref	no	yes		name	Name of checkpoint algorithm to which we are referring.
checkpoint-algorithm-ref	no	yes	props	See props element.	Sequence of prop elements for the checkpoint algorithm.