Jobs are expressed using an Extensible Markup Language XML dialect called XML xJCL 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 Compute Grid 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 the job should be run.
The following table summarizes the xJCL elements:
Element | Compute- intensive | Batch | Sub-element | Attributes | Description |
---|---|---|---|---|---|
job | Y | Y | not-applicable | not-applicable | Scopes the description of a batch job. |
not-applicable | Y | Y | not-applicable | name | Name of the job. This name must match the name of the Compute Grid application. |
not-applicable | Y | Y | jndi-name | not-applicable | JNDI name that is given to the job controller stateless session bean when the Compute Grid application is deployed on WebSphere Application Server. |
not-applicable | Y | Y | step-scheduling-criteria | See step-scheduling-criteria element | not-applicable |
not-applicable | N | Y | checkpoint-algorithm | See checkpoint-algorithm element | not-applicable |
not-applicable | Y | Y | job-step | See job-step element | not-applicable |
job-step | not-applicable | not-applicable | not-applicable | not-applicable | not-applicable |
not-applicable | Y++ | Y | not-applicable | name | Name of the step. This information is returned on operational commands. |
not-applicable | N | Y | step-scheduling | See step-scheduling element | Allows for conditional logic based on return codes of steps that determine if the batch step should be invoked or not |
not-applicable | N | Y | checkpoint-algorithm-ref | See checkpoint-algorithm-ref element | Specifies the checkpoint algorithm to use for the batch job step. |
not-applicable | Y | N | classname | not-applicable | Fully-qualified name of class that implements the compute intensive job. |
not-applicable | N | Y | JNDI-name | not-applicable | Logical JNDI name of the home for the entity bean batch step bean that the batch runtime environment uses to load the batch job step with. |
not-applicable | not-applicable | not-applicable | props | See props element | Name-value properties to pass to the step |
not-applicable | N | Y | 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. |
prop | Y | Y | not-applicable | not-applicable | Single instance of a name value pair, that serves as a property. |
not-applicable | not-applicable | not-applicable | not-applicable | name | Name of the property. |
not-applicable | not-applicable | not-applicable | not-applicable | value | Value of the property. |
props | Y | Y | not-applicable | not-applicable | Series of prop elements that are used to pass name value pair properties to steps, bds, checkpoint algorithms and results algorithms. |
not-applicable | not-applicable | not-applicable | prop | See prop element | not-applicable |
bds | N | Y | not-applicable | not-applicable | Single instance of a batch data stream implementation that is made available to the batch job to use. |
not-applicable | not-applicable | not-applicable | logical-name | not-applicable | A string that is embedded in batch step that the batch step uses to ask the batch runtime environment for a specific batch data stream instance. |
not-applicable | not-applicable | not-applicable | impl-class | not-applicable | Fully qualified class name of the batch data stream implementation class. |
not-applicable | not-applicable | not-applicable | props | See Props elements | List of properties that are passed to the batch data stream implementation class. |
batch-data-streams | N | Y | not-applicable | not-applicable | Series of bds elements |
not-applicable | not-applicable | not-applicable | bds | see bds element | not-applicable |
step-scheduling | N | Y | not-applicable | not-applicable | Can be applied to job steps to create return code-based conditional flows for a batch job. Can compare 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 return code-expression element. |
not-applicable | not-applicable | not-applicable | returncode- expression | see returncode-expression | Returncode- expression for evaluation. |
not-applicable | not-applicable | not-applicable | not-applicable | condition | If there is more than one returncode-expression element in the step-scheduling element, then conditional operators can be applied to them. Conditional operators supported are: AND, OR. |
returncode-expression | N | Y | not-applicable | not-applicable | Used for step scheduling tags to decide if a batch job step is run based on return codes of other job steps. |
not-applicable | not-applicable | not-applicable | not-applicable | step | Name of step whose return code is to be compared in this expression. |
not-applicable | not-applicable | not-applicable | not-applicable | operator | Operator to use for the return code expression; the supported operators are: eq equals, lt less than, gt greater than, le less than or equal to, ge greater than or equal to. |
not-applicable | not-applicable | not-applicable | not-applicable | value | The value with which to compare the return code. |
step-scheduling-criteria | N | Y | not-applicable | not-applicable | Describes the sequence in which the job steps are processed. Currently sequential scheduling is supported, and steps get invoked in the order in which they are displayed in xJCL. |
not-applicable | not-applicable | not-applicable | scheduling-mode | not-applicable | Sequence in which to invoke steps: only possible value is sequential |
checkpoint-algorithm | N | Y | not-applicable | not-applicable | Declares a checkpoint algorithm that can be used for a batch job step. |
not-applicable | not-applicable | not-applicable | not-applicable | name | Name of algorithm. |
not-applicable | not-applicable | not-applicable | classname | not-applicable | Class that implements this algorithm. |
not-applicable | not-applicable | not-applicable | props | see props element | Sequence of props elements for the checkpoint algorithm. |
checkpoint-algorithm-ref | N | Y | not-applicable | not-applicable | Reference to a checkpoint algorithm element. |
not-applicable | not-applicable | not-applicable | not-applicable | name | Name of checkpoint algorithm to which you are referring. |
not-applicable | not-applicable | not-applicable | props | see props element | Sequence of prop elements for the checkpoint algorithm. |
+ Only single-step compute intensive jobs are supported.
The following table summarizes the xJCL elements:
Element | J2EE Compute- intensive | J2EE Batch | Native utility | Sub-element | Attributes | Description |
---|---|---|---|---|---|---|
job | Y | Y | N | Scopes the description of a batch job. | ||
Y | Y | Y | name | Name of the job. This name has to match the name of the Compute Grid application | ||
Y | Y | Y | accounting | Optional accounting information attribute. | ||
Y | Y | Y | class | Optional job class attribute, which identifies the job class under which the job will run. | ||
Y | Y | Y | default-application-name | The application name to be used when no job step application-name attribute is found. | ||
Y | Y | N | jndi-name | JNDI name that is given to the job controller stateless session bean when the Compute Grid application is deployed into WebSphere Application Server. | ||
Y | Y | Y | 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. | |
Y | Y | N | step-scheduling criteria |
see step-scheduling-criteria element | ||
N | Y | N | checkpoint algorithm | see checkpoint-algorithm element | ||
N | Y | Y | results-algorithm | see results-algorithms element | ||
Y | Y | Y | 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 | ||||||
Y* | Y | N | name | Optional name of the step. This information is returned on operational commands. | ||
Y* | Y | N | application-name | Optional name of the application executed by the step. The attribute name is used if application-name is omitted and the job level attribute default-application-name is omitted. | ||
N | Y | N | step-scheduling | See step-scheduling element | Allows for conditional logic based on return codes of steps that determines if the batch step should be invoked or not. | |
N | Y | N | JNDI-name | Logical JNDI name of the home for the entity bean batch step bean that the batch execution environment will use to load the batch job step with. | ||
Y | Y | N | classname | Fully-qualified name of class that implements the compute intensive job. | ||
Y | N | N | checkpoint-algorithm-ref | Specifies the checkpoint algorithm to use for the batch job step. | ||
N | Y | N | results-ref | See results-ref element | Specifies the results algorithm to use for the conditional batch job step execution. | |
N | Y | N | 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. | |
Y | Y | N | props | See props element | Name-value properties to pass to the step. | |
N | N | Y | exec | See exec element | Identifies the executable associated with the job step. | |
N | N | Y | env-entries | See env-entries element | Identifies the environmental properties associated with the job step. | |
prop | Y | Y | N | Single instance of a name value pair, that serves as a property. | ||
name | Name of the property. | |||||
value | Value of the property. | |||||
props | Y | Y | N | prop | See prop element | |
env-entries | N | N | Y | Series of prop elements that is used to pass name-value pair properties to steps, bds, checkpoint algorithms and results algorithms. | ||
env-var | See env-var element | |||||
exec | N | N | Y | Series of prop elements that is used to pass name-value pair properties to steps, bds, checkpoint algorithms and results algorithms. | ||
executable | The name of the executable associated with the job step. | |||||
arg | See line element | |||||
line | N | N | Y | Command line arguments passed to the job step executable. | ||
bds | N | Y | N | Single instance of a batch data stream implementation made available to the batch job. | ||
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. | |||||
impl-class | Fully- qualified class name of the batch data stream implementation class. | |||||
props | See props elements | List of properties that are passed to the batch data stream implementation class. | ||||
batch-data-streams | N | Y | N | Series of bds elements | ||
bds | see bds element | |||||
step-scheduling | N | Y | 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. | |||
returncode- expression | see returncode-expression | Returncode- expression to evaluate. | ||||
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 | N | Y | Used under step-scheduling tags to decide if a batch job step should be run based on return codes of other job steps. | |||
step | Name of step whose return code is to be compared in this expression. | |||||
operator | Operator to use for the return code expression; the supported operators are: eq equals, lt less than, gt greater than, le less than or equal to, ge greater than or equal to. | |||||
value | The value with which to compare the return code. | |||||
step-scheduling-criteria | N | Y | Describes the sequence in which the job steps will be processed. Currently sequential scheduling is supported; i.e. steps get invoked in the order in which they appear in xJCL. | |||
scheduling-mode | Sequence in which to invoke steps, only possible value is sequential right now. | |||||
checkpoint-algorithm | N | Y | Declares a checkpoint algorithm that can be used for a batch job step. | |||
name | Name of algorithm. | |||||
classname | Class that implements this algorithm. | |||||
props | see props element | Sequence of prop elements for the checkpoint algorithm. | ||||
checkpoint-algorithm-ref | N | Y | Reference to a checkpoint algorithm element. | |||
name | Name of checkpoint algorithm to which you are referring. | |||||
props | see props element | Sequence of prop elements for the checkpoint algorithm. |
++ The xJCL element substitution-props is discussed below.
<checkpoint-algorithm-ref name="${checkpoint}" />
<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 timebased 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.