deploy.

App/wwwroot/HiAPI-docsite/manual/run/when-something-goes-wrong.html

@@ -97,15 +97,19 @@ something in it, so a tab with no number beside its name is a sink nothing has r
 <ul>
 <li><strong>Shell</strong> — the session's own account of itself: what started, what finished, what it built, and
 the verdicts it reaches at the end of a play. A conversion or an optimization reports itself here
-too, stage by stage and file by file, from its opening row to its closing count. These rows carry
-no anchor, because there is nothing
+too, from its opening row to its closing count — an optimization stage by stage and file by
+file; a conversion in those two rows alone, the closing one carrying the count and the names of
+every file written in a single sentence, and a row of its own only for a file it could not write.
+These rows carry no anchor, because there is nothing
 in the program to anchor them to. <strong>This is the list a run that appears to have done nothing is
 diagnosed from</strong>: a play that ends with no step having touched the workpiece is reported here, and
 the message names the usual causes — an incremental header with no <code>G90</code> after it, a work offset
 or program zero that puts the program somewhere else, stock that is not where the program expects
-it.</li>
+it, and the tool geometry.</li>
 <li><strong>NC Diagnostics</strong> — everything the NC pipeline said while playing, which is not only complaints.
-It opens each file with the line count it found, and a row about one sentence carries an anchor
+It closes each file with the line count it read — the <em>contains lines</em> row is written once the
+file's last line has been consumed, so it follows every diagnostic that file raised, and a file
+the play is still reading has no such row yet — and a row about one sentence carries an anchor
 naming it. This is the list to read when the program did not do what its text says.</li>
 <li><strong>Step Diagnostics</strong> — anchored to a machining step rather than to a position in the text. Most of
 it is about motion, but not all: an NC-embedded script that fails to compile is reported here too,
@@ -120,33 +124,44 @@ account of itself is on <strong>Shell</strong>.</li>
 <p>A message about a <code>G</code> word and a message about a move are different problems, and they never share a
 list. Looking in the wrong one reads as silence.</p>
 <h2 id="reading-a-row">Reading a row</h2>
-<p><img src="when-something-goes-wrong-img/nc-diagnostics.en.png" alt="The Execution page with the left and right columns switched off: the canvas above, and below it the Session Messages panel with the NC Diagnostics tab selected. The tab row shows Shell badged 11 and NC Diagnostics badged 7, with Step Diagnostics and NC Manipulation carrying no badge at all. Under a filter toolbar of Severity, Category, a text box, Reset and Export, seven rows are listed: six System rows reading Sys-Init&ndash;FileLines with each file and its line count, and one warning row whose anchor column reads Sn 2105, category Unsupported, id Parsing&ndash;Unconsumed, text Unconsumed Parsing entries: G02"></p>
+<p><img src="when-something-goes-wrong-img/nc-diagnostics.en.png" alt="The Execution page with the left and right columns switched off, so no Control Tree pane and no run header is in view: the 3D Rendering Canvas above, showing a white block on a grey fixture with a gold disc cutter at its top face and green tool paths rising above it, and below it the Session Messages panel with the NC Diagnostics tab selected. The tab row shows Shell badged 11 and NC Diagnostics badged 7, with Step Diagnostics and NC Manipulation carrying no badge at all. Under a filter toolbar of Severity, Category, a Filter text… box, Reset and Export, with a 7 / 7 counter at its right end, seven rows are listed: six System rows reading Sys-Init&ndash;FileLines with each file and its line count — circle.ptp listed twice, Inline finishing pass last — and, sixth in the list, one warning row whose anchor column reads Sn 2105, category Unsupported, id Parsing&ndash;Unconsumed, text Unconsumed Parsing entries: G02"></p>
 <p><em>The four lists at <code>/execution</code>, with NC Diagnostics selected. Two of the four tabs carry no badge,
-which is how an empty sink looks.</em></p>
+which is how an empty sink looks. The warning at <code>Sn 2105</code> sits above the line-count row for
+<code>Inline finishing pass</code> because that row closes its file rather than opening it.</em></p>
 <p>A row carries, left to right, the position it is about, the category, the message's own id, and its
-text. The position is the anchor: <code>Sn</code> and a number for a sentence, <code>S</code> and a number for a step. Not
-every row has one — a complaint about the pipeline rather than about a particular sentence has
-nothing to anchor to, and neither has anything on <strong>Shell</strong>.</p>
+text. The position is the anchor. On the two NC lists it is <code>Sn</code> and a number, naming a sentence. On
+<strong>Step Diagnostics</strong> it opens with <code>S</code> and the step's number, and when that step was reached from a
+sentence the one anchor carries both markers — <code>S12 · Sn 340</code> names the step and then the sentence
+behind it; only a step with no sentence behind it reads <code>S</code> and its number alone. Not every row has
+one — a complaint about the pipeline rather than about a particular sentence has nothing to anchor
+to, and neither has anything on <strong>Shell</strong>.</p>
 <p>The id is worth reading. It is stable across languages and releases, so it is the thing to quote
 when asking someone else about a message, and the thing to filter on when one message is repeating.
 The <strong>Filter text…</strong> box, the <strong>Severity</strong> and <strong>Category</strong> lists and <strong>Export</strong> are described with
 the rest of the panel in <a href="../basics/messages-and-logs.html">Messages and Logs</a>.</p>
 <div class="IMPORTANT">
 <h5>Important</h5>
-<p><strong>On the two NC lists, a row is not an occurrence.</strong> <strong>NC Diagnostics</strong> folds across a play and
-<strong>NC Manipulation</strong> across one conversion or optimization run; <strong>Shell</strong> and <strong>Step Diagnostics</strong>
-fold nothing, and every report they take becomes a row of its own. Where it applies, the pipeline
-keeps one entry per
-distinct message — same id, same wording — and drops every repeat instead of listing it. When the
-program ends, each message that occurred more than once gets one summary row reading <em>repeated N
-times in this run, first at</em> the sentence it was first seen on. So a diagnostic raised on forty
-different sentences leaves two rows for that program: the first occurrence, and the summary.</p>
+<p><strong>On the two NC lists, a row is not an occurrence.</strong> <strong>NC Diagnostics</strong> folds across the play of
+one mission command — one <strong>Program File</strong> or one <strong>NC Code</strong> entry, subprograms included, so a
+file played twice is two windows — and <strong>NC Manipulation</strong> across one conversion or optimization
+run; <strong>Shell</strong> and <strong>Step Diagnostics</strong> do no such folding — a report there gets a row of its own unless it is identical to the row just
+before it, in which case it joins that row under the multiplier badge described below. Where it
+applies, the pipeline keeps one entry per distinct message — same id, same wording — and drops
+every repeat instead of listing it. When the program ends, each message that occurred more than
+once gets one summary row: the first occurrence's text followed by <code>[repeated Nx in this run, first at Sn=…]</code>, with the count in place of <code>N</code> and the sentence it was first seen on after <code>Sn=</code>
+(a message with no sentence to anchor to ends in <code>[repeated Nx in this run]</code> instead). So a
+diagnostic raised on forty different sentences of one file leaves two rows for that file: the
+first occurrence, and the summary — and the same diagnostic raised again in the next file, or on
+the same file's second play, starts over with a first occurrence and a summary of its own. The
+screenshot above shows the window's edge: <code>circle.ptp</code> is played twice, and its line-count row
+is listed twice rather than folded.</p>
 <p>Two consequences are worth holding on to. The count is only in that summary sentence — the
 multiplier badge that marks consecutive identical messages is a different mechanism and does not
 appear on these. And <strong>the summary row's anchor is the last occurrence while its text names the
-first</strong>, so jumping from it lands at the end of the run of repeats, not at the beginning.
-Everything between the two rows has no anchor at all: to find those positions, fix the first one
-and play again.</p>
+first</strong>, so the <code>Sn</code> in its anchor column is the end of the run of repeats and the <code>Sn=</code> in its
+text the beginning. Neither is a link: clicking a row opens its detail when it has one and does
+nothing else, so an anchor is a position to read off, not a place to go. Everything between the
+two rows has no anchor at all: to find those positions, fix the first one and play again.</p>
 </div>
 <h2 id="then-the-runs-own-record">Then the run's own record</h2>
 <p>The <strong>Program</strong> branch holds what the run did to each line — the passes it made and the marks each
@@ -157,12 +172,20 @@ what the pipeline thought of a sentence while it was playing, the <strong>Progra
 sentence produced.</p>
 <h2 id="then-the-service-log">Then the service log</h2>
 <p><strong>Show Log</strong> on the menu bar opens the log the service is writing for the current day, with a
-<strong>Download</strong> for sending it to someone else. It holds things the four lists never carry — the
-exception behind a failure, and the engine's own start-up account of itself — and it is the only
-one of these surfaces that outlives the session. What it does not hold is the four lists: those are
-pushed to the browser and are never written to the file, so a message seen in a list is not
-findable there. The viewer itself is described in
-<a href="../basics/messages-and-logs.html">Messages and Logs</a>.</p>
+<strong>Download</strong> for sending it to someone else. It holds things the four lists do not carry — the
+engine's own start-up account of itself, and the exception behind a failure the engine did not report
+through a message, which the service writes to the log and nowhere else — and it outlives the
+session: a Reset on the transport — the eject button in the run header, not the <strong>Reset</strong> in a
+tab's filter toolbar, which clears that tab's filters and touches no list — empties <strong>Shell</strong>,
+<strong>NC Diagnostics</strong> and <strong>Step Diagnostics</strong>, and the log keeps what it had. An exception the engine <em>did</em> report through a message is a different case: it rides
+the row, which carries a chevron; opening it shows the exception in full, with a <strong>Copy</strong> of its
+own, so a script that would not compile or a step record that could not be read is answered from
+the list, not from the log. What the log does not hold is the four lists: those are pushed to the
+browser and are never written to the file, so a message seen in a list is not findable there — the
+exception on a row included. The one list the transport's Reset leaves
+alone is <strong>NC Manipulation</strong> — the next conversion or optimization is what empties it — so the last
+conversion's findings are still on that tab after the run has been reset away, not in the log. The
+viewer itself is described in <a href="../basics/messages-and-logs.html">Messages and Logs</a>.</p>
 <h2 id="while-an-optimization-is-running">While an optimization is running</h2>
 <p>An optimization reports itself on <strong>Shell</strong>, stage by stage. It opens with <em>Start NC optimization.</em>
 and ends with <em>Total N files optimized.</em> and <em>optimization cache cleared.</em>, and between them every
@@ -174,31 +197,50 @@ NC commands..</em>, with one <em>File optimized:</em> row naming each output fil
 stopped one. While the per-step feeds are being solved, every thousandth step adds another
 <em>Computing Optimized Feed by indivisual step..</em> row carrying the source file and line it has
 reached; while the optimized text is being written, every thousandth line adds a <em>Now optimizing
-to:</em> row carrying the same two numbers. <strong>Shell appends every one of them and folds nothing</strong>, so
-its newest row is where the run has got to: numbers that keep advancing are a run still working, and
-a list that has stopped growing on a stage whose successor has not been announced is a run that is
-not.</p>
+to:</em> row carrying the same two numbers. <strong>Each of them is a row on Shell</strong>, subject to the one
+folding <strong>Shell</strong> does: the file and line on a step row are those of the sentence the step came
+from, so a sentence that expands to more than a thousand steps — a long arc at a fine resolution —
+puts the same two numbers on two consecutive rows, and those join under the multiplier badge. And
+because the per-step feeds are solved in parallel, the numbers on successive step rows need not
+climb in strict order. What holds either way is that the newest row is where the run has got to:
+numbers that keep changing are a run still working, and a list that has stopped growing on a stage
+whose successor has not been announced is a run that is not.</p>
 <p>The counting rows are the instrument, not the stage rows. A stage with fewer than a thousand steps
 to solve, or fewer than a thousand lines to write, announces its start and then says nothing until
 it ends — so a short program crosses the whole ladder in near-silence, and that silence means
 nothing on its own.</p>
-<p><strong>A Stop ends an optimization on a success row.</strong> Stop reaches the optimizer between steps and
-between output files rather than only at the end, and what it leaves on <strong>Shell</strong> is <em>optimization
-canceled.</em> followed immediately by <em>Total N files optimized.</em> in success green — even <em>Total 0 files
-optimized.</em> arrives as a success. The count is of the files the run had opened, so a file the Stop
+<p><strong>A Stop ends an optimization on the same two closing rows as a finished one.</strong> Stop reaches the
+optimizer between steps and between output files rather than only at the end, and what it leaves
+on <strong>Shell</strong> is <em>optimization canceled.</em> followed immediately by <em>Total N files optimized.</em> in
+success green and then <em>optimization cache cleared.</em>, the run's last row — even <em>Total 0 files
+optimized.</em> arrives as a success. A Stop that lands while the per-step feeds are being solved puts
+one more row ahead of those: <em>Optimization Feed Process canceled.</em> stands where <em>Optimization
+Feedrate built.</em> would have. The count is of the files the run had opened, so a file the Stop
 landed part-way through is counted with the rest and is left on disk short. The complete ones are
 those whose own <em>File optimized:</em> row appeared before the cancel.</p>
 <h2 id="three-things-that-look-like-faults-and-are-not">Three things that look like faults and are not</h2>
 <p><strong>An English message in a translated interface is the safe answer, not a bug.</strong> Engine messages
-arrive with an id and their English text, and the interface substitutes its own translation only
-when its copy of that message matches the one the engine sent. An engine built against a different
-message set, or a message the interface has no copy of, leaves the original English in place rather
-than rendering text that might say something else. The English is the accurate text.</p>
+arrive with an id and their English text, and the interface translates by id. For a message that
+carries values — a file name, a count, a line number — it substitutes its own translation only when
+its template for that id matches the one the engine sent; an engine built against a different
+message set, or a message the interface has no entry for, leaves the original English in place
+rather than rendering text that might say something else. A message with no values in it is swapped
+on its id alone, with no comparison of wording, so an engine that has reworded such a message while
+keeping its id shows, in a translated interface, the translation of the wording it had before. In
+both cases the English the engine sent is the accurate text, and switching the interface to English
+shows every message exactly as it arrived.</p>
 <p><strong>An action refused because a run is playing is a guard, not a fault.</strong> Switching the NC runner and
 switching the controller brand are both refused while a program is playing, rather than swapping the
-parser underneath it; the refusal names the reason and asks for the run to be paused or finished
-first. It arrives on the action itself — no row is added to any of the four lists, so there is
-nothing to go looking for afterwards.</p>
+parser underneath it. The refusal is a toast that opens with the name of the action it refused and
+the status the service answered with: <em>Switch controller brand: HTTP 409: Cannot switch the
+controller brand while an NC program is playing; pause and let the current program finish first.</em>
+for a brand switch, and <em>Install NC runner: HTTP 409: Cannot switch the NC runner while an NC
+program is playing; pause and let the current program finish first.</em> for a runner installed
+through the <strong>Controller</strong> branch's <strong>Object Management</strong> menu, by a <strong>Load</strong> or a paste. The
+<em>pause</em> in it is not the part that lifts the guard: a paused run is still a playing one to this
+guard, so the switch is refused again until the program finishes or a Stop ends it. The refusal
+arrives on the action itself — no row is added to any of the four lists, so there is nothing to go
+looking for afterwards.</p>
 <p><strong>An empty Step Diagnostics list is not proof that nothing was wrong.</strong> Collision detection is off
 unless the mission turns it on, and the physics-dependent warnings — the cutter geometry checks
 raised at tool change among them — are not raised at all when physics is off. A quiet list on a run