Bug 5533 - stop/end/fail exit-status should affect job exit status, not step (as claimed in spec).
stop/end/fail exit-status should affect job exit status, not step (as claimed...
Status: RESOLVED FIXED
Product: jbatch
Classification: Unclassified
Component: SPEC
1
All All
: P5 normal
: ---
Assigned To: ScottKurz
1.0_mr_pending
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2013-11-07 05:05 UTC by ScottKurz
Modified: 2015-09-03 21:24 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description ScottKurz 2013-11-07 05:05:32 UTC
For each of stop/end/fail, the spec says that the 'exit-status' attribute specifices the step exit status rather than the job exit status.

That's contrary to 4).   The TCK as I recall, (and looking quick it looks like BatchletRestartStateMachineTests would be an example) assumes this affects
the job exit status which fits with rule 4).

So I think we should treat this as a spec bug... and update the spec to clarify this is the job 'exit-status'.  

That interpretation would also makes the last part of 8.7.1 meaningless. 

Step termination may be optionally configured in the Job XML using the terminating transition elements, fail, end, or stop. These elements can also set the exit status. Note that setting the exit status programmatically through the StepContext object overrides setting the exit status through any of these element types.
Comment 1 ScottKurz 2013-11-09 21:12:02 UTC
Let's also use this to fix the spec typo on p. 45:

saying that for 'stop' element's restart attribute "This is a required attribute."

As the XSD shows, it's actually optional.
Comment 2 ScottKurz 2014-01-09 21:44:55 UTC
The first 6 changes are the same two copied three times (for each of fail, end, stop).  Then there are a few additonal related ones.  

Since we had some discussion on the public ML, it seemed worthy of the example I included below.

------------------------------------------------------------------------------

1) Changed Section 8.6.2 (Fail Element) initial paragraph to:

The fail element is used to terminate the job at the conclusion of the current step or flow. The job batch status is set to FAILED.   This does not, however, directly affect the batch status of the parent (containing) step of the fail element.   Multiple fail elements may be specified in the current containment scope.   The fail element is supported as a child of the step, flow, and decision elements.  

2) Also in 8.6.2, change 'exit-status' attribute description to:

Specifies the new exit status for the job. It must be a valid XML string value.  This is an optional attribute.  If not specified, the job-level exit status is unchanged.  This attribute does not directly change any step exit status (particularly the step which is the parent of this fail element).

---

3) Changed Section 8.6.3 (End Element) initial paragraph to:

The end element is used to terminate the job at the current step.  The job batch status is set to COMPLETED.  This does not, however, directly affect the batch status of the parent (containing) step of the end element.  Multiple end elements may be specified in the current containment scope. The end element is supported as a child of the step, flow, and decision elements.

4) Also in 8.6.3, change 'exit-status' attribute description to:

Specifies the new exit status for the job. It must be a valid XML string value.  This is an optional attribute.  If not specified, the job-level exit status is unchanged.  This attribute does not directly change any step exit status (particularly the step which is the parent of this end element).

---

5) Changed Section 8.6.4 (Stop Element) initial paragraph to:

The stop element is used to terminate the job after the current step or flow.  If the stop element matches the exit status, the job-level batch status is then set to STOPPED.   This does not, however, directly affect the batch status of the parent (containing) step of the stop element.   Multiple stop elements may be specified in the current containment scope.  The stop element is supported as a child of step, flow, and decision elements.

6) Also in 8.6.4, change 'exit-status' attribute description to:

Specifies the exit status for the job. It must be a valid XML string value.  This is an optional attribute.  If not specified, the job-level exit status is unchanged.  This attribute does not directly change any step exit status (particularly the step which is the parent of this stop element).

---

7) In 8.6.4 (Stop Element), change the last sentence of the 'restart' attribute description to:

This is an optional attribute.

---

8) Bigger change, with example to clarify..

Replace entire paragraph (i.e. delete old paragraph) starting with:
 "Step termination may be optionally configured...."

with replacement paragraphs (with example):


  An important point to note is that transition elements do not affect the batch and exit status of their containing step (for a step with one or more child transition elements), but only potentially affect the batch and exit status of the job.

Example:
  <step id=”FS1”>
        <batchlet … >
	<next on="RC0” />
	<fail on="RC4” exit-status=”BAD”/>
	<fail on="RC8” /> 
 </step>

Suppose for the above example JSL snippet, FS1’s batchlet executes normally with an exit status of “RC4”.     Then step FS1’s batch status will end up as COMPLETED, and FS1’s exit status will end up as “RC4”.   The job’s batch status will end up as FAILED and the job’s exit status will end up as “BAD”.    Likewise, if the batchlet completes with an exit status of “RC8” the step’s batch and exit status will be COMPLETED and “RC8”, respectively, while the job’s batch and exit status will be FAILED and “FAILED” (assuming the job exit status hasn’t been set and defaults in this case).

Note the implications for restart processing.   For example, a completed step won’t re-run just because the step includes a transition element failing the job on the original step execution’s exit status. See section 10.8 for more on restart processing.

9) Sec. 8.7.2 Exit Status for Partitioned Steps
It's hard to separate out the change for this particular bug from changes for others.

The key point to note here is that we no longer say the step exit status is affected by "1. transition elements stop, end, fail", which had appeared in the numbered list.  (The list is gone now).
Comment 3 mminella 2014-01-14 19:04:50 UTC
Section 8.6.2
In a number of areas, the new verbiage refers to a "parent (containing) step".  Can we drop the word parent and just use containing?  Since inheritance was originally a feature that was in the spec (and I'm hoping will be resurrected in a future version), I'd rather just leave any verbiage that implies inheritance out of the current version.
Comment 4 ScottKurz 2014-01-14 20:28:06 UTC
Hadn't thought of that context as a source of confusion.

I was hedging I think in case anyone thought that "containing" was less precise than parent...  But I think "containing" would be clear enough and avoid inheritance confusion.

Going to add "1.0_mr_planned" to the whiteboard tag to queue up this change as a TODO.
Comment 5 ScottKurz 2014-02-13 13:09:31 UTC
Replaced "parent" with "containing".  Refer to the in-document change history (via comments) in the new draft to see exactly where.
Comment 6 ScottKurz 2015-09-03 21:24:32 UTC
As mentioned before I think the BatchletRestartStateMachineTests tests already enforce this.