SIRFACT command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (needed a space)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="toclimit-2">
<p class="note"><b>Note:</b> This is a <var class="product">[[Sirius Mods]]</var>-only command prior to Version 7.5 of <var class="product">[[Model 204]]</var>.</p>
<p class="note"><b>Note:</b> This is a <var class="product">[[Sirius Mods]]</var>-only command prior to Version 7.5 of <var class="product">[[Model 204]]</var>.</p>


The SIRFACT command invokes the [[SirFact]] post hoc debugging facility.
The <var>SIRFACT</var> command invokes the <var class="product">[[SirFact]]</var> post hoc debugging facility.
SIRFACT has a set of several subcommands that lets you tailor, trap early,
<var>SIRFACT</var> has a set of several subcommands that lets you tailor, trap early,
and otherwise maximize the error information dumped for <var class="product">Model 204</var>
and otherwise maximize the error information dumped for <var class="product">Model 204</var> debugging purposes.
debugging purposes.


SIRFACT commands can also be issued
<var>SIRFACT</var> commands can also be issued
as operator commands, that is, on the Online virtual console under VM or
as operator commands, that is, on the Online virtual console under VM or
as the response to the HALT message under OS/390.
as the response to the <var>HALT</var> message under z/OS.


The SIRFACT command is described in detail in the [http://sirius-software.com/maint/download/factr.pdf SirFact Reference Manual].
===SIRFACT command syntax===
<p class="syntax">SIRFACT <span class="term">subcomm operands</span> </p>
Where:
<ul>
<li><var class="term">subcomm</var> is one of the subcommands listed in the table below.
 
<li><var class="term">operands</var>
is one or more operands specific to the <var>SIRFACT</var> subcommand that is being invoked.
</ul>
 
The <var>SIRFACT</var> subcommands are summarized below and described in detail
in the sections that follow.
 
You invoke a subcommand with the <code>SIRFACT</code> prefix (for example, <var>SIRFACT CANCEL</var>, <var>SIRFACT MAXDUMP</var>).
 
<table class="thJustBold">
<caption>SIRFACT subcommand summary</caption>
<tr><th>CANCEL</th>
<td>Indicates which return codes from $functions should result in request cancellation. Can be abbreviated <var>CAN</var>.</td></tr>
 
<tr><th>DISPLAY</th>
<td>Shows the currently active <var>SIRFACT</var> subcommands. Can be abbreviated <var>DISP</var>.</td></tr>
 
<tr><th>DUMP</th>
<td>Indicates which request cancellations should cause a <var class="product">SirFact</var> dump to be taken and where the dump is to go.</td></tr>
 
<tr><th>IGNORE</th>
<td>Indicates which request cancellation error messages are not to produce <var class="product">SirFact</var> dumps. Can be abbreviated <var>IGN</var>.</td></tr>
 
<tr><th>MAXDUMP</th>
<td>Places limits on the number of <var class="product">SirFact</var> dumps that will be taken. Thedefault system limit is 0 so a <var>SIRFACT MAXDUMP</var>
<b>must</b> be issued to get <b>any</b> SirFact dumps. Can be abbreviated <var>MAXD</var>.</td></tr>
 
<tr><th>NOCANCEL</th>
<td>Indicates that certain return codes from $functions should not result in request cancellation. Cancels out the effect of a <var>SIRFACT CANCEL</var> command. Can be abbreviated <var>NOCAN</var>.</td></tr>
 
<tr><th>NODUMP</th>
<td>Indicates that certain request cancellations should not result in <var class="product">SirFact</var> dumps being produced. Cancels out the effect of a <var>SIRFACT DUMP</var> command.</td></tr>
 
<tr><th>NOIGNORE</th>
<td>Indicates that certain request cancellation error messages are to produce <var class="product">SirFact</var> dumps. Cancels out the effect of a <var>SIRFACT IGNORE</var> command. Can be abbreviated <var>NOIGN</var>.</td></tr>
 
<tr><th>QUIESCE</th>
<td>Facilitates updates of APSY subsystem procedures while the subsystem is up and in use.</td></tr>
 
<tr><th>RECNDUMP</th>
<td>Establishes the number of record numbers from each found set or [[$lists|$list]] to be dumped. Can be abbreviated <var>RECND</var>.</td></tr>
 
<tr><th>RESUME</th>
<td>Stops the effect of a <var>SIRFACT QUIESCE</var> command and returns the subsystem to normal operation.</td></tr>
 
<tr><th>SNAP</th>
<td>Requests that a <var class="product">SirFact</var> dump be taken for another thread.</td></tr>
</table>
 
Some <var>SIRFACT</var> subcommands make use of the wildcard characters
asterisk (<code>*</code>), question mark (<code>?</code>), and
double quotation mark (<code>"</code>):
<table class="thJustBold">
<tr><th>?</th>
<td>Represents any single character.</td></tr>
 
<tr><th>*</th>
<td>Represents any string of characters.</td></tr>
 
<tr><th>"</th>
<td>The escape flag that allows special characters to bypass wildcard translation.</td></tr>
</table>
 
The following examples illustrate the use of the wildcard characters:
<ul>
<li>This command requests a display of all the <var>SIRFACT CANCEL</var> subcommands in
effect for $functions that begin with the letters "$LIST":
<p class="code"><nowiki>SIRFACT DISPLAY CAN $LIST*
</nowiki></p> </li>
 
<li>This command indicates that a <var class="product">SirFact</var> dump should be created for any request
cancellation errors that occur in a subsystem with a name that is seven
characters long and ends in the letters "CUST":
<p class="code"><nowiki>SIRFACT DUMP DUMPROC DUMP.+T SUBSYS ???CUST
</nowiki></p> </li>
 
<li>This command indicates that a <var class="product">SirFact</var> dump should be created for any request
cancellation errors that occur for user <code>?WEIRD</code>.
The double-quote (<code>"</code>) is required to prevent the question
mark (<code>?</code>) from being interpreted as a wildcard character:
<p class="code"><nowiki>SIRFACT DUMP DUMPROC DUMP.+T USER "?WEIRD
</nowiki></p> </li>
</ul>
 
==<b id="cancel"></b>SIRFACT CANCEL==
The <var>SIRFACT CANCEL</var> subcommand requires a parameter that indicates
the $function to which it applies, followed by return codes that should
be intercepted and cause request cancellation when returned by the function.
 
===Syntax===
<p class="syntax">SIRFACT CANCEL <span class="term">function returncodes</span></p>
 
<table>
<tr><th>function</th>
<td>The name of the function to which the command applies. This name cannot contain wildcard characters.</td></tr>
 
<tr><th>returncodes</th>
<td>A blank delimited set of return codes that will be intercepted and cause request cancellation.</td></tr>
</table>
 
The subcommand <var>CANCEL</var> can be abbreviated to <var>CAN</var>.
 
===Examples===
This command causes cancellation of any request that gets a return code of 1 from <var>$Setg</var>:
<p class="code">SIRFACT CANCEL $SETG 1
</p>
 
This command causes cancellation of any request that gets a return code
of -3, -5, -6, or -7 from <var>$ListAdd</var>:
<p class="code">SIRFACT CAN $LISTADD -3 -5 -6 -7
</p>
<p>
See also [[#Sample settings per $function|Sample settings per $function]], below. </p>
 
===Usage===
<ul>
<li>The rationale for <var>SIRFACT CANCEL</var> is that certain return codes from certain
$functions indicate programming errors or severe environmental
problems (return code 1 from <var>$Setg</var>, for example), so these codes should result in
immediate request cancellation, even in ad hoc or development procedures.
For example, a return code of -6 from <var>$Listloc</var>, indicating an invalid $list identifier, suggests a severe problem in a program.
Even in an ad hoc procedure, there is little reason to go on after such an error.
<p>
There is a distinction, however, between cancelling the request and creating
a <var class="product">SirFact</var> dump for the error.
A dump would generally not be desirable
for errors in ad hoc or development procedure errors.
Because of this, the creation of dumps is controlled by a different <var>SIRFACT</var> subcommand,
the <var>SIRFACT DUMP</var> subcommand ([[#dump|SIRFACT DUMP]]).
This subcommand limits the creation of dumps to specific subsystems, procedures, or users. </p></li>
 
<li>It is <i>strongly</i> recommended that the collection of <var>SIRFACT CANCEL</var> commands in the development and test regions match
the collection in production.
Otherwise, things that work in development might not work in test or production and vice versa.
It can't be overemphasized that <var>SIRFACT CANCEL</var> should be used for return codes
that indicate <i>programming errors</i> or <i>severe environmental</i>
problems that are as invalid in development as in production.
In the rare cases where such a return code might be considered "normal"
or at least acceptable in a chunk of code, the <var>[[SirFact SOUL statements#SirFact statement|SirFact]]</var> <i>statement</i> can be used to temporarily disable <var class="product">SirFact</var>
$function error trapping for a specific user. </li>
 
<li>A <var>SIRFACT CAN</var> can be disabled with a <var>SIRFACT NOCAN</var> command for the same function. </li>
 
<li>If multiple <var>SIRFACT CANCEL</var>s (or <var>NOCANCEL</var>s) are issued
for the same $function, only the last one is used.
So the following would only trap return codes of -6 from <var>$Listloc</var>:
<p class="code">SIRFACT CAN $LISTLOC -5
SIRFACT CAN $LISTLOC -6
</p>
<p>
To trap return codes of -5 and -6 from <var>$Listloc</var>, you must issue: </p>
<p class="code">SIRFACT CAN $LISTLOC -5 -6
</p></li>
 
<li>The implementation of <var>SIRFACT CANCEL</var> is very efficient and should
cause <b>no</b> measurable performance degradation in the execution
of functions for which return codes are being trapped.
Performance of the <var class="product">SirFact</var> error trapping is certainly significantly more efficient
than testing for the same errors using <var class="product">SOUL</var>. </li>
 
<li>Whether or not a <var class="product">SirFact</var> dump is produced for an error trapped
by the <var>SIRFACT CANCEL</var> command, these trapped errors are <i>always</i>
accompanied by a message indicating the procedure and line number
in which the error occurred, as well as the name of the function causing
the error and the function arguments.
<p>
<var class="product">SirFact</var> will use any one of
several mechanisms to collect the procedure and line number information,
each of them having some cost in either QTBL, STBL, VTBL, or CCATEMP space.
For a discussion of the costs and tradeoffs of the various
approaches, see the [[SirFact system parameters#factprm|SIRFACT parameter]]. </p></li>
 
<li><b><i>It is strongly recommended that you set SIRFACT CANCEL as aggressively as possible.</i></b>
If a <var>SIRFACT CANCEL</var> should cause a problem with "dirty" use of $functions, the preferred solution
is to clean up the use of the $functions.
<p>
The next best solution is to
wrap the "dirty" function calls in a <var>SIRFACT OFF</var>/<var>SIRFACT ON</var> bracket. </p>
<p>
Eliminating the <var>SIRFACT CANCEL</var> for a value is the least preferable solution, because:</p>
<ul>
<li>It reduces the benefit of <var>SIRFACT CANCEL</var> to encourage good programming practices.</li>
 
<li>It eliminates the ability of <var>SIRFACT CANCEL</var> to catch unintentional misuses of $functions.</li>
</ul></li>
</ul>
 
===Sample settings per $function===
The following is a list of "reasonable" <var>SIRFACT CANCEL</var> commands for most Onlines:
<p class="code"><nowiki>SIRFACT CAN $BLDPROC          1
SIRFACT CAN $DATECHG          *
SIRFACT CAN $DATECNV          *
SIRFACT CAN $DATEDIF          99999999
SIRFACT CAN $EDIT              &apos;&apos; '#'
SIRFACT CAN $INCRG            1 2
SIRFACT CAN $LSTPROC          4
SIRFACT CAN $RDPROC            2
SIRFACT CAN $SETG              1
SIRFACT CAN $UNBIN            &apos;&apos;
SIRFACT CAN $UNFLOAT          &apos;&apos;
SIRFACT CAN $UNPACK            &apos;&apos;
SIRFACT CAN $LISTADD          -3 -5 -6 -7
SIRFACT CAN $LISTADDI          -3 -5 -6 -8
SIRFACT CAN $LISTCNT          -5 -6
SIRFACT CAN $LISTCPY          -3 -5 -6
SIRFACT CAN $LISTDEL          -5
SIRFACT CAN $LISTFIND          -5 -6 -7 -8
SIRFACT CAN $LISTILN          -5 -6 -7
SIRFACT CAN $LISTIMG          -5 -6 -8
SIRFACT CAN $LISTINF          -5 -6 -7 -9
SIRFACT CAN $LISTINFI          -5 -6 -7 -8
SIRFACT CAN $LISTINS          -3 -5 -6 -7 -9
SIRFACT CAN $LISTINSI          -3 -5 -6 -8 -9
SIRFACT CAN $LISTLOC          -3 -5 -6 -7 -9
SIRFACT CAN $LISTLUP          -3 -5 -6 -7 -9
SIRFACT CAN $LISTMOVE          -5 -6
SIRFACT CAN $LISTOVL          -5 -6 -7 -9
SIRFACT CAN $LISTREM          -5 -6 -7
SIRFACT CAN $LISTRST          -13
SIRFACT CAN $LISTSAV          -3 -5 -13
SIRFACT CAN $LISTSAVE          -3 -5 -13
SIRFACT CAN $LISTSAVL          -3 -5 -6
SIRFACT CAN $LISTSRT          -3 -5 -6 -10 -12
SIRFACT CAN $LISTSORT          -3 -5 -6 -10 -12
SIRFACT CAN $LISTSUB          -3 -5 -6 -7 -9
SIRFACT CAN $LIST_GLOBAL      -3 -14 -15
SIRFACT CAN $LIST_CONV_ITEM    -5 -6 -7
SIRFACT CAN $LIST_COPY_ITEMS  -3 -5 -6 -7 -8
SIRFACT CAN $LIST_DIFF_ITEM    -3 -5 -6 -7
</nowiki></p>
 
===Special-case settings===
As might be apparent from the examples above, there are a few $functions
for which the return values are special-cased.
These are:
<table>
<tr><th><var>$Datechg</var></th>
<td>On errors, this function will return a number of asterisks (*) equal to the length of the second parameter (the output format). <var class="product">SirFact</var>
interprets a <code>SIRFACT CANCEL $DATECHG '*'</code> to require request cancellation for any <var>$Datechg</var> call that returns one or more asterisks.</td></tr>
 
<tr><th><var>$Datecnv</var></th>
<td>On errors, this function will return a number of asterisks (<tt>*</tt>) equal to the length of the first parameter (the input format). <var class="product">SirFact</var>
interprets a <code>SIRFACT CANCEL $DATECNV '*'</code> to require request cancellation for any <var>$Datecnv</var> call that returns one or more asterisks.</td></tr>
 
<tr><th><var>$Edit</var></th>
<td>On errors, this function will return a number of hashes (<tt>#</tt>) equal to the length of the second parameter (the edit mask). <var class="product">SirFact</var>
interprets a <code>SIRFACT CANCEL $EDIT '#'</code> to require request cancellation for any <var>$Edit</var> call that returns one or more hashes.</td></tr>
 
<tr><th><var>$Listinf</var></th>
<td><var>$Listinf</var> always returns a string value. To indicate an error, <var>$Listinf</var> returns a 2-digit string containing -5, -6, -7, or -9.
Yet, in theory at least, these values could also be reasonable values of $list items. <var>SIRFACT CANCEL</var> provides a work-around for this design flaw in <var>$Listinf</var>, because <var>SIRFACT CANCEL</var> will
<b>not</b> cause request cancellation when a cancellation value is actually a value in a $list item. <var>SIRFACT CANCEL</var> will only cause cancellation when the return value is truly the result of an error.</td></tr>
</table>
 
==<b id="sfdisp"></b>SIRFACT DISPLAY==
The <var>SIRFACT DISPLAY</var> subcommand displays many of the <var>SIRFACT</var> subcommands currently in effect.
 
===Syntax===
<p class="syntax">SIRFACT DISPLAY [<span class="term">subcom</span> [<span class="term">subset</span>]]
</p>
 
<var>DISPLAY</var> can be abbreviated to <var>DISP</var>.
 
<table>
<tr><th>subcom</th>
<td>The name of the class of subcommands to which the display is to apply.
<p>
<var>SIRFACT DISPLAY</var> with no <var class="term">subcom</var> value displays all <var>SIRFACT</var> commands from the subcommand classes listed below that are currently in effect. </p>
<p>
Valid values for <var class="term">subcom</var> are: </p>
<table>
<tr><th><var>CANCEL</var></th>
<td>Displays active <var>SIRFACT CANCEL</var> commands. Can be abbreviated <var>CAN</var>.
<p>
<var>CANCEL</var> can be followed by a <var class="term">subset</var> value that can contain wildcards indicating the $functions for which <var>SIRFACT CANCEL</var> settings are to be displayed.
<var>SIRFACT NOCANCEL</var> commands are not displayed because these simply eliminate the <var>SIRFACT CANCEL</var>s for the specified $functions.</p></td></tr>
 
<tr><th><var>DUMP</var></th>
<td>Displays active <var>SIRFACT DUMP</var> and <var>NODUMP</var> commands.</td></tr>
 
<tr><th><var>IGNORE</var></th>
<td>Displays active <var>SIRFACT IGNORE</var> commands. Can be abbreviated <var>IGN</var>.
<p>
<var>IGNORE</var> can be followed by a <var class="term">subset</var> that can contain wildcards indicating the messages for which <var>SIRFACT IGNORE</var> settings are to be displayed.
<var>SIRFACT NOIGNORE</var> commands are not displayed because these simply eliminate the <var>SIRFACT IGNORE</var>sfor the specified messages.</p></td></tr>
 
<tr><th><var>MAXDUMP</var></th>
<td>Displays active <var>SIRFACT MAXDUMP</var> commands. Can be abbreviated <var>MAXD</var>.
<p>
<var>MAXDUMP</var> can be followed by a <var class="term">subset</var> indicating the type of limitto be displayed. This can be <var>TOTAL</var> or <var>USER</var>. </p>
<p>
A <code>SIRFACT DISPLAY MAXDUMP</code> output line is followed by a comment line that reports the number of <var class="product">SirFact</var> dumps taken since the <var class="product">Model&nbsp;204</var> Online initialization. For example:  </p>
<p class="code"><b>SIRFACT DISPLAY MAXDUMP</b>
SIRFACT MAXDUMP TOTAL 20
<nowiki>*</nowiki> 11 Number of dumps taken
</p></td></tr>
 
<tr><th><var>RECNDUMP</var></th>
<td>Displays active <var>SIRFACT RECNDUMP</var> command. Can be abbreviated <var>RECND</var>.</td></tr>
</table></td></tr>
 
<tr><th>subset</th>
<td>A string indicating which values of the indicated subcommand should be displayed.
For <code>SIRFACT DISPLAY CANCEL</code> and <code>SIRFACT DISPLAY IGNORE</code>, <var class="term">subset</var> can contain wildcard characters. For <code>SIRFACT DISPLAY MAXDUMP</code>, it must be a specific limit type.
<p>
<var class="term">subset</var> is ignored for <code>SIRFACT DISPLAY DUMP</code> and <code>SIRFACT DISPLAY RECNDUMP</code>.</p></td></tr>
</table>
 
===Usage===
The display format for the <var>SIRFACT DISPLAY</var> command repeats the format
of the <var>SIRFACT</var> commands that are used to set <var>SIRFACT</var> controls.
As such, they can be captured (for example with a <var>USE</var> statement) for subsequent reuse.


===SIRFACT command syntax===
If no <var>SIRFACT</var> controls are in effect at all or for the
<p class="syntax">SIRFACT subcomm operands </p>
specific subcommand and subset requested, <var>SIRFACT DISPLAY</var> simply
where
returns without issuing any messages.
<dl>
 
<dt>subcomm
Examples of valid <var>SIRFACT DISPLAY</var> commands follow:
<dd>One of the subcommands listed below.
<p class="code">SIRFACT DISPLAY
<dt>operands
SIRFACT DISPLAY CANCEL
<dd>One or more operands specific to the SIRFACT subcommand invoked.
SIRFACT DISPLAY CAN $LIST*
These are described in detail in the ''SirFact Reference Manual''.
SIRFACT DISPLAY CANCEL $EDIT
</dl>
SIRFACT DISPLAY DUMP
SIRFACT DISPLAY IGNORE
SIRFACT DISPLAY IGN MSIR.*
SIRFACT DISPLAY MAXDUMP
SIRFACT DISPLAY MAXD USER
</p>
 
==<b id="dump"></b>SIRFACT DUMP==
The <var>SIRFACT DUMP</var> subcommand indicates where <var class="product">SirFact</var> dumps are to
be taken and for which environments dumps are to be taken.
All <var class="product">SirFact</var> dumps are taken to procedures.
 
Information contained in a <var class="product">SirFact</var> dump is easily viewed using the
<code>FACT</code> subsystem, described in [[SirFact FACT subsystem]].
You can also use a set of $functions, as described in [[SirFact $functions]].
 
===Syntax===
<p class="syntax">SIRFACT DUMP <span class="term">procfile</span> <span class="term">procname</span> [<span class="term">criteria</span>]
</p>
 
<table>
<tr><th>procfile</th>
<td>The name of the procedure file to which dumps are to be taken. If the procedure file is not open at the time a <var class="product">SirFact</var> dump is to be taken, the procedure file
is opened with the privileges required to create the dump (X'1239') and then closed after the dump.
If the procedure file is already open it <i>must</i> be open with the privileges required to take the dump, or the dump will not be taken.</td></tr>
 
<tr><th>procname</th>
<td>The name of the procedure to be created in <var class="term">procfile</var> for the <var class="product">SirFact</var> dump. <var class="term">procname</var> can be a simple literal string or it can contain special
substitution strings consisting of a plus sign (<tt>+</tt>) followed by a single character indicating what should be substituted into the dump procedure name.
<p>
Because <var class="product">SirFact</var> will never overwrite a procedure with the required procedure name, the use of substitution strings in <var class="term">procname</var> is strongly encouraged.
Procedure name substitution strings are described in greater detail in [[#procins|Procedure name substitutions]].</p></td></tr>
 
<tr><th>criteria</th>
<td>A list of blank-delimited selection criteria that indicate to which "environments" the <var>SIRFACT DUMP</var> command is to apply.
All these environments can also be specified on a <var>SIRFACT NODUMP</var> command and have the same meaning for that command. If <var class="term">criteria</var> is not specified, the <var>SIRFACT DUMP</var> (or <var>SIRFACT NODUMP</var>) command
applies to any request that receives a request cancellation message that is not being "ignored" by <var class="product">SirFact</var> ([[#ignore|SIRFACT IGNORE]]). Valid selection criteria are:
<table>
<tr><th><var>FILE</var></th>
<td>The procedure file to which the <var>DUMP</var> rule applies. The file name can contain wildcard characters. <var>FILE</var> refers to the file in which the outer procedure being evaluated resides, whether or not the I<var>NCLUDE</var> was done in gr-
oup context.</td></tr>
 
<tr><th><var>IODEV</var></th>
<td>The <var>IODEV</var> number to which the <var>DUMP</var> rule applies.</td></tr>
 
<tr><th nowrap>msg number</th>
<td>The <var class="product">Model&nbsp;204</var> message number to which the <var>DUMP</var> rule applies. This message number must start with either a <code>M204.</code> for standard <var class="product">Model&nbsp;204</var>
error messages, <code>MSIR.</code> for <var class="product">SirMods</var> error messages or <code>USER.</code> for site-specific error messages. The message number could also be <code>SNAP</code>,
which means that the rule applies to <var class="product">SirFact</var> dumps taken as a result of <var>SIRFACT SNAP</var> commands. For example,
this sends all dumps for subscript range errors to file <code>SUBSERR</code>:
<p class="code">SIRFACT DUMP SUBSERR OUCH.+P.+T M204.0553
</p>
And this sends all dumps resulting from <var>SIRFACT SNAP</var> commands to file <code>FACTSNAP</code>:
<p class="code">SIRFACT DUMP FACTSNAP OOCH.+P.+T SNAP
</p></td></tr>
 
<tr><th><var>PROC</var></th>
<td>The procedure name to which the <var>DUMP</var> rule applies. The procedure name can contain wildcard characters.
<var>PROC</var> refers to the outer procedure being evaluated, not the Included procedure in which the error occurred.</td></tr>
 
<tr><th><var>SUBSYS</var></th>
<td>The APSY subsystem to which the <var>DUMP</var> rule applies. The subsystem can contain wildcard characters.</td></tr>
 
<tr><th><var>USER</var></th>
<td>The userid to which the <var>DUMP</var> rule applies. The userid can contain wildcard characters.</td></tr>
</table>
<p>
For a <var>DUMP</var> rule to apply to an error being handled by <var class="product">SirFact</var>, the error time environment must match <b>all</b> criteria specified in the <var>SIRFACT DUMP</var> command.</p></td></tr>
</table>
 
===Usage===
<ul>
<li><var class="product">SirFact</var> dumps are taken for any request cancellation message that is not being "ignored" ([[#ignore|SIRFACT IGNORE]]) if the following criteria are met:
<ul>
<li><var>SIRFACT MAXDUMP</var> has been set. </li>
 
<li>None of the <var>SIRFACT MAXDUMP</var> limits has been exceeded. </li>
 
<li>There is a <var>SIRFACT DUMP</var> command for which the current thread matches all criteria. </li>
 
<li>The dump procedure file as determined by the appropriate <var>SIRFACT DUMP</var>
command is already open with the correct privileges (any superset
of X'1239') or can be opened with the correct privileges. </li>
 
<li>The output procedure as determined by the appropriate <var>SIRFACT DUMP</var> command does not already exist. </li>
</ul></li>
 
<li>Dumps are taken for request cancellations resulting from <code>M204.1332: LONG REQUEST</code> messages,
even though technically this message is not a request cancellation message.
Note that the dump will only be taken if the user is not given a chance
to continue with a <code>DO YOU REALLY WANT TO CONTINUE?</code> message,
that is, if the <var>[[PROMPT parameter|PROMPT]]</var> X'10' bit is set, if the request is running in
an application subsystem, or the request is running on a batch thread. </li>
 
<li><var class="product">SirFact</var> dumps can be terminated if there is insufficient space in the dump procedure file to hold the dump.
In this case, the partial dump will be deleted because it is essentially useless. </li>
</ul>
 
===<b id="procins"></b>Procedure name substitutions===
The dump procedure name specified in the <var>SIRFACT DUMP</var> command can
contain the special character plus (<tt>+</tt>) followed by a single character indicating a substitution string.
The following characters cause the following substitutions to take place:
<table class="thJustBold">
<tr><th>+</th>
<td>A literal plus.</td></tr>
 
<tr><th>1-9</th>
<td>A single digit sequence number as in <code>+2</code> or <code>+6</code>. <var class="product">SirFact</var> tries sequence numbers from 0 through the indicated number
until it finds one that creates a procedure name that doesn't already exist in the target proc file.</td></tr>
 
<tr><th>D</th>
<td>The date that the error happened in YYYYMMDD format.</td></tr>
 
<tr><th>F</th>
<td>The file (not group) that contains the evaluating outer proc.</td></tr>
 
<tr><th>J</th>
<td>The jobname of the job in which the error occurred.</td></tr>
 
<tr><th>M</th>
<td>The number of the message that caused the request cancellation, or the word <code>SNAP</code> if the dump was caused by a <var>SIRFACT SNAP</var> command.
The substituted message number does not include the period. So for example, if the request cancellation was caused by a <code>MSIR.0491</code>, a <code>+M</code> would be replaced by a <code>MSIR0491</code>.</td></tr>
 
<tr><th>P</th>
<td>The name of the evaluating outer procedure.</td></tr>
 
<tr><th>S</th>
<td>The name of the current subsystem.</td></tr>
 
<tr><th>T</th>
<td>The date and time that the error happened in YYYYMMDDHHMISS format.</td></tr>
 
<tr><th>U</th>
<td>The userid that encountered the error.</td></tr>
</table>
Any other characters following a plus are simply dropped.
 
For example, if this is the <var>SIRFACT DUMP</var> command:
<p class="code">SIRFACT DUMP FACTDUMP DUMP.+P.+T
</p>
And a <var class="product">SirFact</var> trapped error happens in procedure <code>PRE.BADLY.CODED</code> at
14:22:31 on May 12, 2001, the dump procedure name is <code>DUMP.PRE.BADLY.CODED.20010512142231</code>.
If the <var>SIRFACT DUMP</var> command is:
<p class="code">SIRFACT DUMP FACTDUMP DUMP.+J.+2
</p>
And a <var class="product">SirFact</var> trapped error happens in job <code>DEVONLN</code>,
<var class="product">SirFact</var> tries to take the dump to procedure <code>DUMP.DEVONLN.00</code>.
If that procedure already exists, it tries to take the dump to
<code>DUMP.DEVONLN.01</code>, and so on.
If <var class="product">SirFact</var> gets all the way to <code>DUMP.DEVONLN.99</code> without finding a procedure that doesn't already
exist, the dump is not taken.
 
Because most of the substitution characters in a dump are likely to occur in multiple dumps, it is recommended that most
<var>SIRFACT DUMP</var> rules have a procedure name that contains a <code>+1</code>,
<code>+2</code>, <code>+3</code>, or a <code>+T</code>.
 
===Managing SirFact dumps===
<ul>
<li>Multiple <code>SIRFACT DUMP</code> commands might apply to a particular situation.
For example, say the following two commands are in effect:
<p class="code"><nowiki>SIRFACT DUMP DUMPCUST DUMP-+P-+2 SUBSYS CUSTOMER
SIRFACT DUMP JUNKDUMP DUMP-+S-+P PROC *JUNK
</nowiki></p>
If a request cancellation occurs in procedure <code>PCUST-MISCJUNK</code> in
subsystem <code>CUSTOMER</code>, both
<var>SIRFACT DUMP</var> commands seem applicable.
In such cases, <var class="product">SirFact</var>
will always use the last applicable <var>SIRFACT DUMP</var> rule. In
this example, the <var class="product">SirFact</var> dump is taken to procedure
<code>DUMP-CUSTOMER-PCUST-MISCJUNK</code> in file <code>JUNKDUMP</code>.
<p>
Because <var class="product">SirFact</var>
uses the last applicable <var>SIRFACT DUMP</var> rule, these rules should be
specified in most general first, most specific last order.
For example, this
requests that most dumps would go to file <code>SIRFACTD</code> but dumps for
subsystem <code>INVENTORY</code> would go to file <code>INVDUMP</code>, except for those in
procedures the end in <code>WIDGET</code>, which would go to file <code>WIDGETD</code>: </p>
<p class="code">SIRFACT DUMP SIRFACTD DMP.+P-+T
SIRFACT DUMP INVDUMP DMP.+P-+T SUBSYS INVENTORY
SIRFACT DUMP WIDGETD DMP.+P-+T SUBSYS INVENTORY PROC *WIDGET
</p>
<p>
If a <var>SIRFACT DUMP</var> command has criteria that are a superset of previous
<var>SIRFACT DUMP</var> commands, those previous criteria are discarded.
For example, in this sequence,
the last <var>SIRFACT DUMP</var> command would always supersede the previous
two. When <var class="product">SirFact</var> encounters that last command, it discards the
previous two, so a <code>SIRFACT DISPLAY DUMP</code> will only show the
last <var>SIRFACT DUMP</var> command. </p>
<p class="code"><nowiki>SIRFACT DUMP JUNKDUMP +P.+1.DUMP SUBSYS INVENTORY
SIRFACT DUMP DUMPDATA +P.+1.DUMP SUBSYS INVENTORY
SIRFACT DUMP IDUMP +P.+1.DUMP SUBSYS I*
</nowiki></p>
<p>
An unqualified <var>SIRFACT DUMP</var> command,
that is, one with just the procedure file and name, supersedes
<b>all</b> previous <var>SIRFACT DUMP</var> commands. </p></li>
 
<li><var class="product">SirFact</var> dumps are synchronous on a thread level but asynchronous on a system level.
This means that the user or thread for which a <var class="product">SirFact</var>
dump is being taken will not be able to do anything while the dump is
being taken, but other users or threads will continue to run.
This is different from CCASNAPs (and SYSMDUMPs), which stop the entire Online
while they are being taken.
In any case, even very large <var class="product">SirFact</var> dumps
should only take a few seconds to complete so should not have a severe
negative impact on performance for either the affected user or any other user. </li>
 
<li><var class="product">SirFact</var> dumps do <b>not</b> log roll-forward information for
the dump procedures, even if the procedure file to which the dump
is going is configured to log roll-forward information (the <var>[[FRCVOPT parameter|FRCVOPT]]</var> X'04' bit is not set).
This will not interfere with the roll-forward
logging for any other data going to the dump procedure file, and it will
not cause any recovery problems. It simply means that if the system
crashes after a <var class="product">SirFact</var> dump, and the procedure file is rolled back
to a checkpoint before the <var class="product">SirFact</var> dump in recovery, the dump will be lost. </li>
 
<li>Checkpoint logging is performed on the dump procedure file as indicated by <var>FRCVOPT</var>.
If no checkpoint logging is being performed on the dump
procedure file (<var>FRCVOPT</var> X'20' bit set), then there is no danger
of losing a <var class="product">SirFact</var> dump because of a roll-back during recovery. But
there <i>is</i> a very real chance of the file being left physically
broken after an inopportune system crash.
This might still be an acceptable
risk: without checkpoint logging <var class="product">SirFact</var> dumps will be extremely
fast and have very little impact on system performance, and
the procedure dictionary and Table D allocations are fairly tolerant of physical inconsistencies.
<p>
This latter point means that should the
system crash and a <var class="product">SirFact</var> dump procedure file be left physically
inconsistent, most of the information in that file could be recovered
after resetting <var>FISTAT</var> &mdash; though after doing so, the file should be reorganized
or reinitialized after moving the dump procedures elsewhere.
It is considerably more questionable to depend on being able to do this if procedure deletions
are being mixed with <var class="product">SirFact</var> dump creation.
Because of this, it is
recommended that <var class="product">SirFact</var> dump procedure file cleanup happen when
<var class="product">SirFact</var> dumps are unlikely (perhaps as part of a batch cycle) if the dump procedure file is being run with recovery turned off. </p></li>
 
<li>While <var class="product">SirFact</var> dumps are very useful, it is probably not
critical if a few are lost because of a system crash (in fact the
system crash itself would probably cause greater damage), so it might
make sense to run with recovery completely turned off for the <var class="product">SirFact</var>
dump procedure file with <b>no</b> formal strategy for recovering from a system crash.
 
<p class="note"><b>Note:</b> Because of the unusual nature of <var class="product">SirFact</var> dumps, it is
strongly recommended that no other data be stored in files that are to
receive <var class="product">SirFact</var> dumps. </p></li>
</ul>
 
==<b id="ignore"></b>SIRFACT IGNORE==
The <var>SIRFACT IGNORE</var> subcommand indicates which request cancellation
error messages are not to produce <var class="product">SirFact</var> dumps.
 
===Syntax===
<p class="syntax">SIRFACT IGNORE <span class="term">msg</span>
</p>
 
Where:
<table>
<tr><th>msg</th>
<td>The message number of the request cancellation message for which dumps are to be suppressed. The message number must include the message prefix
(<code>M204</code> for standard <var class="product">Model&nbsp;204</var> messages, <code>MSIR</code> for Sirius messages, and <code>USER</code> for user messages).</td></tr>
</table>
 
===Usage===
<ul>
<li>Usually a request cancellation error message is indicative of
a programming error or a severe environmental problem.
In the case of a programming error, it is very useful to get a <var class="product">SirFact</var>
dump to determine the cause of the error.
<p>
In case of a severe environmental problem, it
might be helpful to get a <var class="product">SirFact</var> dump to determine the cause of
the environmental problem (for example, a <var>SIRFACT CANCEL</var> intercepted <var>$Setg</var>
error). But more often than not, a dump would not be particularly
helpful, especially for problems that affect structures that are shared among many users. </p></li>
 
<li>There are even a few request cancellation messages that are actually a normal part of operation!
A successful <var>VTAM TRANSFER</var>, for example, results in the cancellation
of the request that initiated the <var>TRANSFER</var>. </li>
 
<li>The <var>SIRFACT IGNORE</var> command makes it possible to suppress
<var class="product">SirFact</var> dumps for messages for which the dumps would either be undesirable or useless.
Examples of such error messages are:
<p class="code">M204.0441 CCATEMP FULL
M204.0443 TABLE D FULL
M204.1229 TABLE B FULL -- INSERTS
M204.1230 TABLE B FULL -- APPENDS
M204.1231 TABLE B FULL -- SPILLS
M204.1270 TABLE C FULL - PROPERTY ENTRY
M204.1272 TABLE C FULL - PAGE ENTRY
M204.1273 TABLE C FULL - REDEFINE
M204.1808 ERROR IN EXECUTING TRANSFER STATEMENT
M204.1899 TRANSFER STATEMENT COMPLETE, ...
MSIR.0517 Cancelling request because of $SIRPARM LISTFC setting (CCATEMP full)
</p>
<p>
Certainly, if CCATEMP or a file table fills up and <var class="product">SirFact</var> dumps
were not being suppressed for the associated message, a flood of
<var class="product">SirFact</var> dumps could occur as user after user trips over the same problem.
To prevent getting <var class="product">SirFact</var> dumps for these messages, simply issue
the following commands during Online initialization: </p>
<p class="code">SIRFACT IGNORE M204.0441
SIRFACT IGNORE M204.0443
SIRFACT IGNORE M204.1229
SIRFACT IGNORE M204.1230
SIRFACT IGNORE M204.1231
SIRFACT IGNORE M204.1270
SIRFACT IGNORE M204.1272
SIRFACT IGNORE M204.1273
SIRFACT IGNORE M204.1808
SIRFACT IGNORE M204.1899
SIRFACT IGNORE MSIR.0517
</p>
<p>
There might be other request cancellation errors for which
a site might want to suppress <var class="product">SirFact</var> dumps.
Among these might be: </p>
<p class="code">M204.0452 TTBL FULL
M204.0562 REQUEST TOO LONG - table
M204.0574 REQUEST TOO LONG - VTBL
M204.0577 QTBL FULL -- DIRECT SEARCH
M204.2126 USER'S PUSHDOWN LIST OVERFLOWED
</p></li>
 
<li><var class="product">[[Introduction to SoftSpy|SoftSpy]]</var> can issue some request cancellation errors which occur on the
SoftSpy server thread; to ignore these errors, use the following command:
<p class="code"><nowiki>SIRFACT IGNORE M204.0000
</nowiki></p></li>
</ul>
 
==<b id="maxdump"></b>SIRFACT MAXDUMP==
The <var>SIRFACT MAXDUMP</var> command establishes limits on the number
of <var class="product">SirFact</var> dumps to be taken.
The default for the maximum dumps for
the entire system is 0, so at least one <var>SIRFACT MAXDUMP</var> command
must be issued to get <b>any</b> <var class="product">SirFact</var> dumps.
 
===Syntax===
<p class="syntax">SIRFACT MAXDUMP [<span class="syntax">type</span>] <span class="syntax">limit</span>
</p>
 
Where:
 
<table>
<tr><th>type</th>
<td>The type of limit being established. It can be one of the following values:
<table>
<tr><th><var>USER</var></th>
<td>Maximum <var class="product">SirFact</var> dumps to be taken in a single user logon. The default is no limit.</td></tr>
 
<tr><th><var>TOTAL</var></th>
<td>Maximum <var class="product">SirFact</var> dumps to be taken in the entire Online. The default is 0, so a <code>SIRFACT MAXUMP TOTAL</code> must be issued to get any <var class="product">SirFact</var> dumps.</td></tr>
</table>
<p>
If <var class="term">type</var> is not specified, it is assumed to be <var>TOTAL</var>, so <code>SIRFACT MAXDUMP 20 </code>is the same as <code>SIRFACT MAXDUP TOTAL 20</code>.
</p></td></tr>
 
<tr><th>limit</th>
<td>The maximum number of dumps to be taken for the indicated type.</td></tr>
</table>
 
===Usage===
<ul>
<li>A <var>SIRFACT MAXDUMP</var> should be issued at the start of any Online run for which you want <var class="product">SirFact</var> dumps.
If for some reason an application
or environmental error is causing a "flood" of <var class="product">SirFact</var> dumps,
further dumps can be prevented with a <code>SIRFACT MAXDUMP 0</code>.
This should not be a concern if a reasonable limit
is set by a <var>SIRFACT MAXDUMP</var> at the start of the run. </li>
 
<li>You can view the number of <var class="product">SirFact</var> dumps taken
since the <var class="product">Model&nbsp;204</var> Online initialization by issuing
a <code>[[#sfdisp|SIRFACT DISPLAY|SIRFACT DISPLAY MAXDUMP]]</code> command. </li>
</ul>
 
==<b id="quiesce"></b>SIRFACT QUIESCE==
<var>SIRFACT QUIESCE</var> facilitates updates of application subsystem procedures while the subsystem is up and in use.
This subcommand gets all subsystem users into a "quiescent" state
where they are not likely to block procedure update operations
or compile inconsistent copies of inner and outer subsystem procedures.
Users are quiescent if they are
evaluating a pre-compiled request (as determined by the request's
prefix not its true pre-compilability) or between procedures in the subsystem driver loop.
 
When <var>SIRFACT QUIESCE</var> is issued:
<ul>
<li>Any user that is going to switch to the
next procedure in the subsystem driver is stopped until the subsystem is resumed. </li>
 
<li>Any user that exits a pre-compiled procedure is stopped at end of request. </li>
 
<li>Other users continue to run until they encounter one of the preceding two points. </li>
 
<li>A user that is evaluating a pre-compiled request or that is between procedures
is already considered quiesced. </li>
</ul>
 
===Syntax===
<p class="syntax">SIRFACT QUIESCE <span class="term">subsys</span> [WAIT <span class="term">sec</span>] [BUMP]
</p>
 
Where:
<table>
<tr><th>subsys</th>
<td>The name of the subsystem to be quiesced.</td></tr>
 
<tr><th>sec</th>
<td>The number of seconds to wait for the subsystem to be quiesced.
If the subsystem quiesces before this time, <var>SIRFACT QUIESCE</var>
returns at that point. If the subsystem is not quiesced after <var class="term">sec</var> seconds, SIRFACT QUIESCE returns with a message stating that the subsystem is not yet quiesced, unless <code>BUMP</code> was specified.
<p>
The wait time cannot be set to 0. The default wait time is 3 seconds.</p></td></tr>
 
<tr><th><var>BUMP</var></th>
<td>A <var class="product">Model&nbsp;204</var> <var>BUMP</var>, issued for any users still not quiescedafter<var class="term">sec</var> seconds. After bumping these users, <var>SIRFACT QUIESCE</var> waits another second for these users to notice the bump.
<p>
Bumped users do not actually disappear from the system: The <var>BUMP</var> sets the user's next procedure to the application subsystem error procedure, but the error procedure does not run because in a quiescing subsystem,
users do not go to the next procedure.</p></td></tr>
</table>
 
===Usage===
<ul>
<li>If a <var>SIRFACT QUIESCE</var> does not completely quiesce
a subsystem, it is quite likely that it will still allow for safe update and
replacement of subsystem procedures &mdash; any user that hasn't
quiesced within a reasonably long time will probably not cause or encounter any problems during an update operation.
This is especially true if the
X'40' bit of <var>SIRFACT</var> is set (see [[SirFact system parameters#factprm|The SIRFACT parameter]]).
The <var>BUMP</var> option of <var>SIRFACT QUIESCE</var> offers further assurance that no subsystem users
will impede or threaten procedure updates. </li>
 
<li><var>SIRFACT QUIESCE</var> can be issued multiple times by one or multiple users for the same subsystem.
In either case, only a single invocation of the <var>SIRFACT QUIESCE</var> inverse operation, <var>SIRFACT RESUME</var>, is necessary to
stop the quiescing and resume normal operation of the subsystem.
If a user is waiting for the return from <var>SIRFACT QUIESCE</var>, another user
can cancel the quiesce and cause the first user to return immediately
(with a warning message) by issuing a <var>SIRFACT RESUME</var> for the same subsystem. </li>
 
<li><var>SIRFACT QUIESCE</var> is valuable for doing application subsystem maintenance.
Such maintenance probably requires appropriate settings of
the <var>[[SirFact system parameters#sirapsy|SIRAPSYF]]</var> parameter and of the <var>[[SIRFACT parameter|SIRFACT]]</var> parameter. </li>
</ul>
 
==<b id="resume"></b>SIRFACT RESUME==
<var>SIRFACT RESUME</var> counters the effect of <var>[[#quiesce|SIRFACT QUIESCE]]</var>:
<var>SIRFACT QUIESCE</var> renders a currently operating subsystem safe for updates by waiting for and stopping users until
no users are inside a non-pre-compiled procedure or compiling precompiled procedures.
<var>SIRFACT RESUME</var> stops this quiescing and returns the subsystem to normal operation.
 
===Syntax===
<p class="syntax">SIRFACT RESUME <span class="term">subsys</span>
</p>
 
===Usage===
<ul>
<li>If a user is waiting for the return from <var>SIRFACT QUIESCE</var>, another user
can cancel the quiesce and cause the first user to return immediately
(with a warning message) by issuing a <var>SIRFACT RESUME</var> for the same subsystem. </li>
 
<li><var>SIRFACT QUIESCE</var> can be issued multiple times by one or multiple users for the same subsystem.
In either case, only a single invocation of the <var>SIRFACT QUIESCE</var> inverse operation, <var>SIRFACT RESUME</var>, is necessary to
stop the quiescing and resume normal operation of the subsystem. </li>
</ul>
 
==<b id="recndmp"></b>SIRFACT RECNDUMP==
The <var>SIRFACT RECNDUMP</var> establishes the number of record numbers from each found set or $list (from <var>LIST</var> option of <var>[[SirFact_FACT_subsystem#dcmd|Display]]</var> command)  to be dumped.
By default, <var class="product">SirFact</var> dumps two record numbers from each found set or $list, the first and the last.
Note that <var class="product">SirFact</var> does not actually dump the records in any found set or
$list unless a record in a found set or $list is the current record in an
active <var>FOR EACH RECORD</var> loop, in which case that single record is dumped.
 
===Syntax===
<p class="syntax">SIRFACT RECNDUMP <span class="term">num</span>
</p>
 
The maximum <var class="term">num</var> value for <var>SIRFACT RECNDUMP</var> is 256, and the minimum is 1.
 
===Usage===
<ul>
<li>The count of records in a found set or $list is always dumped.
<p>
If a found set or $list contains fewer or the same number of records as
the <var>SIRFACT RECNDUMP</var> value, the entire found set or list is dumped.
If a found set or $list contains more records than the <var>SIRFACT RECNDUMP</var>
value, the first <code>(num+1)/2</code> and last <code>num/2</code> record numbers in the found set or $list are dumped. </p>
<p>
For example, if <var>SIRFACT RECNDUMP</var> is 1, only the first record number
in a found set or $list will be dumped. If the value is 32, the first
16 and last 16 will be dumped. And if the value is 127, the first 64 and
last 63 will be dumped. </p></li>
 
<li>The cost of a large <var>SIRFACT RECNDUMP</var> value is a somewhat
larger dump if a request has many large found sets or $lists, though
the cost is only about 6 bytes per record dumped per found set or $list.
<p>
For example, if there are 20 large found sets and $lists in a request
that is dumped, a <var>RECNDUMP</var> value of 100 would make the dump <code>98*20*6</code>
or 11,760 bytes bigger than a dump with the default <var>RECNDUMP</var> value of 2. </p>
<p>
The cost to keeping <var>RECNDUMP</var> small is that potentially useful information is lost about the records in a found set or a $list. </p></li>
</ul>
 
==<b id="snap"></b>SIRFACT SNAP==
The <var>SIRFACT SNAP</var> command requests that a <var class="product">SirFact</var> dump is to be taken
for another thread.
This can be useful if a thread is looping or hung.
 
===Syntax===
<p class="syntax">SIRFACT SNAP <span class="term">usernum</span> | <span class="term">userid</span> [FORCE]
</p>
 
The <var>SIRFACT SNAP</var> command must be followed by either a user number or a userid.
If a userid is specified, the userid must only be logged in on a single
thread or <var class="product">SirFact</var> will not take the dump for the thread.
If a userid is logged in on multiple threads, the dump must be requested
by user number.
 
The optional <var>FORCE</var> parameter indicates that the <var class="product">SirFact</var> dump is
to be taken for the thread, even if the thread holds one or more critical file resource locks.
By default, <var class="product">SirFact</var> will not take a dump for another thread
on a <var>SIRFACT SNAP</var> command while the thread holds any critical
file resource locks, though it will try to wait a little bit
(less than 3 seconds) for a window in which the thread being
snapped does not hold any critical file resource locks.
 
===Usage===
<ul>
<li>There are certain cases where a <var>SIRFACT SNAP</var> command might fail
for a looping thread:
<ul>
<li>The most likely is when <var class="product">SirFact</var> is
unable to find a time when the thread being snapped does not
hold a critical file resource lock.
This behavior can be overridden by the specification of the <var>FORCE</var>
parameter on the <var>SIRFACT SNAP</var> command. </li>
 
<li><var class="product">SirFact</var> will also not take a dump for a thread if that thread
is waiting on journal or checkpoint I/O.
As with critical file resources locks, <var class="product">SirFact</var> will try several
times over the course of a few seconds to break in on the thread
to be snapped when it is not waiting on checkpoint or journal I/O,
but if it fails, it gives up. </li>
</ul>
<p>
In most such failure cases, the <var>SIRFACT SNAP</var> command can be retried
until it succeeds.
If a few consecutive <var>SIRFACT SNAP</var> commands fail, the chances of
success might be improved by setting the target thread's priority to <code>LOW</code>. </p></li>
 
<li>The <var>SIRFACT SNAP</var> command can be useful in diagnosing looping
thread problems or problems where a user is presented with
incorrect output.
In both cases, Help desk personnel or a system manager can
get a <var class="product">SirFact</var> dump for the thread with the problem, then do whatever is necessary to get the thread back on track. </li>
 
<li><var>SIRFACT</var> snaps can be taken for non-evaluating threads, even the
one issuing the <var>SIRFACT SNAP</var> command, though the dump in such
cases will have little besides GTBL. </li>
</ul>
 
</div> <!-- div for toc heading levels -->


The SIRFACT subcommands are summarized below and described in detail
==See also==
in the ''SirFact Reference Manual''.
{{Template: SirFact topic list}}
You invoke a subcommand with the
&ldquo;SIRFACT&rdquo; prefix (for example, SIRFACT CANCEL, SIRFACT MAXDUMP).
<dl>
<dt>CANCEL
<dd>Indicates which return codes from $functions should result in request
cancellation.
Can be abbreviated &ldquo;CAN&rdquo;.
<dt>DISPLAY
<dd>Shows the currently active SIRFACT subcommands.
Can be abbreviated
&ldquo;DISP.&rdquo;.
<dt>DUMP
<dd>Indicates which request cancellations should cause a [[SirFact]] dump to
be taken and where the dump is to go.
<dt>IGNORE
<dd>Indicates which request cancellation
error messages are not to produce ''SirFact'' dumps.
Can be abbreviated
&ldquo;IGN.&rdquo;.
<dt>MAXDUMP
<dd>Places limits on the number of ''SirFact'' dumps that will be taken.
The
default system limit is 0 so a SIRFACT MAXDUMP '''must''' be issued
to get '''any''' SIRFACT dumps.
Can be abbreviated &ldquo;MAXD&rdquo;.
<dt>NOCANCEL
<dd>Indicates that certain return codes from $functions should not result in
request cancellation.
Cancels out the effect of a SIRFACT CANCEL command.
Can be abbreviated &ldquo;NOCAN&rdquo;.
<dt>NODUMP
<dd>Indicates that certain request cancellations should not result in
''SirFact'' dumps being produced.
Cancels out the effect of a SIRFACT DUMP command.
<dt>NOIGNORE
<dd>Indicates that certain request cancellation
error messages are to produce ''SirFact'' dumps.
Cancels out the effect of a SIRFACT IGNORE command.
Can be abbreviated &ldquo;NOIGN&rdquo;.
<dt>QUIESCE
<dd>Facilitates updates of APSY subsystem procedures
while the subsystem is up and in use.
<dt>RECNDUMP
<dd>Establishes the number of record numbers from each
found set or LIST to be dumped.
Can be abbreviated
&ldquo;RECND.&rdquo;.
<dt>RESUME
<dd>Stops the effect of a SIRFACT QUIESCE command
and returns the subsystem to normal operation.
<dt>SNAP
<dd>Requests that a ''SirFact'' dump be taken for another thread.
</dl>


[[Category:System administrator commands]]
[[Category:System administrator commands]]
[[Category:Operator commands]]
[[Category:Commands]]
[[Category:Commands]]
[[Category:SirFact]]

Latest revision as of 23:54, 22 November 2022

Note: This is a Sirius Mods-only command prior to Version 7.5 of Model 204.

The SIRFACT command invokes the SirFact post hoc debugging facility. SIRFACT has a set of several subcommands that lets you tailor, trap early, and otherwise maximize the error information dumped for Model 204 debugging purposes.

SIRFACT commands can also be issued as operator commands, that is, on the Online virtual console under VM or as the response to the HALT message under z/OS.

SIRFACT command syntax

SIRFACT subcomm operands

Where:

  • subcomm is one of the subcommands listed in the table below.
  • operands is one or more operands specific to the SIRFACT subcommand that is being invoked.

The SIRFACT subcommands are summarized below and described in detail in the sections that follow.

You invoke a subcommand with the SIRFACT prefix (for example, SIRFACT CANCEL, SIRFACT MAXDUMP).

SIRFACT subcommand summary
CANCEL Indicates which return codes from $functions should result in request cancellation. Can be abbreviated CAN.
DISPLAY Shows the currently active SIRFACT subcommands. Can be abbreviated DISP.
DUMP Indicates which request cancellations should cause a SirFact dump to be taken and where the dump is to go.
IGNORE Indicates which request cancellation error messages are not to produce SirFact dumps. Can be abbreviated IGN.
MAXDUMP Places limits on the number of SirFact dumps that will be taken. Thedefault system limit is 0 so a SIRFACT MAXDUMP must be issued to get any SirFact dumps. Can be abbreviated MAXD.
NOCANCEL Indicates that certain return codes from $functions should not result in request cancellation. Cancels out the effect of a SIRFACT CANCEL command. Can be abbreviated NOCAN.
NODUMP Indicates that certain request cancellations should not result in SirFact dumps being produced. Cancels out the effect of a SIRFACT DUMP command.
NOIGNORE Indicates that certain request cancellation error messages are to produce SirFact dumps. Cancels out the effect of a SIRFACT IGNORE command. Can be abbreviated NOIGN.
QUIESCE Facilitates updates of APSY subsystem procedures while the subsystem is up and in use.
RECNDUMP Establishes the number of record numbers from each found set or $list to be dumped. Can be abbreviated RECND.
RESUME Stops the effect of a SIRFACT QUIESCE command and returns the subsystem to normal operation.
SNAP Requests that a SirFact dump be taken for another thread.

Some SIRFACT subcommands make use of the wildcard characters asterisk (*), question mark (?), and double quotation mark ("):

? Represents any single character.
* Represents any string of characters.
" The escape flag that allows special characters to bypass wildcard translation.

The following examples illustrate the use of the wildcard characters:

  • This command requests a display of all the SIRFACT CANCEL subcommands in effect for $functions that begin with the letters "$LIST":

    SIRFACT DISPLAY CAN $LIST*

  • This command indicates that a SirFact dump should be created for any request cancellation errors that occur in a subsystem with a name that is seven characters long and ends in the letters "CUST":

    SIRFACT DUMP DUMPROC DUMP.+T SUBSYS ???CUST

  • This command indicates that a SirFact dump should be created for any request cancellation errors that occur for user ?WEIRD. The double-quote (") is required to prevent the question mark (?) from being interpreted as a wildcard character:

    SIRFACT DUMP DUMPROC DUMP.+T USER "?WEIRD

SIRFACT CANCEL

The SIRFACT CANCEL subcommand requires a parameter that indicates the $function to which it applies, followed by return codes that should be intercepted and cause request cancellation when returned by the function.

Syntax

SIRFACT CANCEL function returncodes

function The name of the function to which the command applies. This name cannot contain wildcard characters.
returncodes A blank delimited set of return codes that will be intercepted and cause request cancellation.

The subcommand CANCEL can be abbreviated to CAN.

Examples

This command causes cancellation of any request that gets a return code of 1 from $Setg:

SIRFACT CANCEL $SETG 1

This command causes cancellation of any request that gets a return code of -3, -5, -6, or -7 from $ListAdd:

SIRFACT CAN $LISTADD -3 -5 -6 -7

See also Sample settings per $function, below.

Usage

  • The rationale for SIRFACT CANCEL is that certain return codes from certain $functions indicate programming errors or severe environmental problems (return code 1 from $Setg, for example), so these codes should result in immediate request cancellation, even in ad hoc or development procedures. For example, a return code of -6 from $Listloc, indicating an invalid $list identifier, suggests a severe problem in a program. Even in an ad hoc procedure, there is little reason to go on after such an error.

    There is a distinction, however, between cancelling the request and creating a SirFact dump for the error. A dump would generally not be desirable for errors in ad hoc or development procedure errors. Because of this, the creation of dumps is controlled by a different SIRFACT subcommand, the SIRFACT DUMP subcommand (SIRFACT DUMP). This subcommand limits the creation of dumps to specific subsystems, procedures, or users.

  • It is strongly recommended that the collection of SIRFACT CANCEL commands in the development and test regions match the collection in production. Otherwise, things that work in development might not work in test or production and vice versa. It can't be overemphasized that SIRFACT CANCEL should be used for return codes that indicate programming errors or severe environmental problems that are as invalid in development as in production. In the rare cases where such a return code might be considered "normal" or at least acceptable in a chunk of code, the SirFact statement can be used to temporarily disable SirFact $function error trapping for a specific user.
  • A SIRFACT CAN can be disabled with a SIRFACT NOCAN command for the same function.
  • If multiple SIRFACT CANCELs (or NOCANCELs) are issued for the same $function, only the last one is used. So the following would only trap return codes of -6 from $Listloc:

    SIRFACT CAN $LISTLOC -5 SIRFACT CAN $LISTLOC -6

    To trap return codes of -5 and -6 from $Listloc, you must issue:

    SIRFACT CAN $LISTLOC -5 -6

  • The implementation of SIRFACT CANCEL is very efficient and should cause no measurable performance degradation in the execution of functions for which return codes are being trapped. Performance of the SirFact error trapping is certainly significantly more efficient than testing for the same errors using SOUL.
  • Whether or not a SirFact dump is produced for an error trapped by the SIRFACT CANCEL command, these trapped errors are always accompanied by a message indicating the procedure and line number in which the error occurred, as well as the name of the function causing the error and the function arguments.

    SirFact will use any one of several mechanisms to collect the procedure and line number information, each of them having some cost in either QTBL, STBL, VTBL, or CCATEMP space. For a discussion of the costs and tradeoffs of the various approaches, see the SIRFACT parameter.

  • It is strongly recommended that you set SIRFACT CANCEL as aggressively as possible. If a SIRFACT CANCEL should cause a problem with "dirty" use of $functions, the preferred solution is to clean up the use of the $functions.

    The next best solution is to wrap the "dirty" function calls in a SIRFACT OFF/SIRFACT ON bracket.

    Eliminating the SIRFACT CANCEL for a value is the least preferable solution, because:

    • It reduces the benefit of SIRFACT CANCEL to encourage good programming practices.
    • It eliminates the ability of SIRFACT CANCEL to catch unintentional misuses of $functions.

Sample settings per $function

The following is a list of "reasonable" SIRFACT CANCEL commands for most Onlines:

SIRFACT CAN $BLDPROC 1 SIRFACT CAN $DATECHG * SIRFACT CAN $DATECNV * SIRFACT CAN $DATEDIF 99999999 SIRFACT CAN $EDIT '' '#' SIRFACT CAN $INCRG 1 2 SIRFACT CAN $LSTPROC 4 SIRFACT CAN $RDPROC 2 SIRFACT CAN $SETG 1 SIRFACT CAN $UNBIN '' SIRFACT CAN $UNFLOAT '' SIRFACT CAN $UNPACK '' SIRFACT CAN $LISTADD -3 -5 -6 -7 SIRFACT CAN $LISTADDI -3 -5 -6 -8 SIRFACT CAN $LISTCNT -5 -6 SIRFACT CAN $LISTCPY -3 -5 -6 SIRFACT CAN $LISTDEL -5 SIRFACT CAN $LISTFIND -5 -6 -7 -8 SIRFACT CAN $LISTILN -5 -6 -7 SIRFACT CAN $LISTIMG -5 -6 -8 SIRFACT CAN $LISTINF -5 -6 -7 -9 SIRFACT CAN $LISTINFI -5 -6 -7 -8 SIRFACT CAN $LISTINS -3 -5 -6 -7 -9 SIRFACT CAN $LISTINSI -3 -5 -6 -8 -9 SIRFACT CAN $LISTLOC -3 -5 -6 -7 -9 SIRFACT CAN $LISTLUP -3 -5 -6 -7 -9 SIRFACT CAN $LISTMOVE -5 -6 SIRFACT CAN $LISTOVL -5 -6 -7 -9 SIRFACT CAN $LISTREM -5 -6 -7 SIRFACT CAN $LISTRST -13 SIRFACT CAN $LISTSAV -3 -5 -13 SIRFACT CAN $LISTSAVE -3 -5 -13 SIRFACT CAN $LISTSAVL -3 -5 -6 SIRFACT CAN $LISTSRT -3 -5 -6 -10 -12 SIRFACT CAN $LISTSORT -3 -5 -6 -10 -12 SIRFACT CAN $LISTSUB -3 -5 -6 -7 -9 SIRFACT CAN $LIST_GLOBAL -3 -14 -15 SIRFACT CAN $LIST_CONV_ITEM -5 -6 -7 SIRFACT CAN $LIST_COPY_ITEMS -3 -5 -6 -7 -8 SIRFACT CAN $LIST_DIFF_ITEM -3 -5 -6 -7

Special-case settings

As might be apparent from the examples above, there are a few $functions for which the return values are special-cased. These are:

$Datechg On errors, this function will return a number of asterisks (*) equal to the length of the second parameter (the output format). SirFact interprets a SIRFACT CANCEL $DATECHG '*' to require request cancellation for any $Datechg call that returns one or more asterisks.
$Datecnv On errors, this function will return a number of asterisks (*) equal to the length of the first parameter (the input format). SirFact interprets a SIRFACT CANCEL $DATECNV '*' to require request cancellation for any $Datecnv call that returns one or more asterisks.
$Edit On errors, this function will return a number of hashes (#) equal to the length of the second parameter (the edit mask). SirFact interprets a SIRFACT CANCEL $EDIT '#' to require request cancellation for any $Edit call that returns one or more hashes.
$Listinf $Listinf always returns a string value. To indicate an error, $Listinf returns a 2-digit string containing -5, -6, -7, or -9.

Yet, in theory at least, these values could also be reasonable values of $list items. SIRFACT CANCEL provides a work-around for this design flaw in $Listinf, because SIRFACT CANCEL will

not cause request cancellation when a cancellation value is actually a value in a $list item. SIRFACT CANCEL will only cause cancellation when the return value is truly the result of an error.

SIRFACT DISPLAY

The SIRFACT DISPLAY subcommand displays many of the SIRFACT subcommands currently in effect.

Syntax

SIRFACT DISPLAY [subcom [subset]]

DISPLAY can be abbreviated to DISP.

subcom The name of the class of subcommands to which the display is to apply.

SIRFACT DISPLAY with no subcom value displays all SIRFACT commands from the subcommand classes listed below that are currently in effect.

Valid values for subcom are:

CANCEL Displays active SIRFACT CANCEL commands. Can be abbreviated CAN.

CANCEL can be followed by a subset value that can contain wildcards indicating the $functions for which SIRFACT CANCEL settings are to be displayed. SIRFACT NOCANCEL commands are not displayed because these simply eliminate the SIRFACT CANCELs for the specified $functions.

DUMP Displays active SIRFACT DUMP and NODUMP commands.
IGNORE Displays active SIRFACT IGNORE commands. Can be abbreviated IGN.

IGNORE can be followed by a subset that can contain wildcards indicating the messages for which SIRFACT IGNORE settings are to be displayed. SIRFACT NOIGNORE commands are not displayed because these simply eliminate the SIRFACT IGNOREsfor the specified messages.

MAXDUMP Displays active SIRFACT MAXDUMP commands. Can be abbreviated MAXD.

MAXDUMP can be followed by a subset indicating the type of limitto be displayed. This can be TOTAL or USER.

A SIRFACT DISPLAY MAXDUMP output line is followed by a comment line that reports the number of SirFact dumps taken since the Model 204 Online initialization. For example:

SIRFACT DISPLAY MAXDUMP SIRFACT MAXDUMP TOTAL 20 * 11 Number of dumps taken

RECNDUMP Displays active SIRFACT RECNDUMP command. Can be abbreviated RECND.
subset A string indicating which values of the indicated subcommand should be displayed.

For SIRFACT DISPLAY CANCEL and SIRFACT DISPLAY IGNORE, subset can contain wildcard characters. For SIRFACT DISPLAY MAXDUMP, it must be a specific limit type.

subset is ignored for SIRFACT DISPLAY DUMP and SIRFACT DISPLAY RECNDUMP.

Usage

The display format for the SIRFACT DISPLAY command repeats the format of the SIRFACT commands that are used to set SIRFACT controls. As such, they can be captured (for example with a USE statement) for subsequent reuse.

If no SIRFACT controls are in effect at all or for the specific subcommand and subset requested, SIRFACT DISPLAY simply returns without issuing any messages.

Examples of valid SIRFACT DISPLAY commands follow:

SIRFACT DISPLAY SIRFACT DISPLAY CANCEL SIRFACT DISPLAY CAN $LIST* SIRFACT DISPLAY CANCEL $EDIT SIRFACT DISPLAY DUMP SIRFACT DISPLAY IGNORE SIRFACT DISPLAY IGN MSIR.* SIRFACT DISPLAY MAXDUMP SIRFACT DISPLAY MAXD USER

SIRFACT DUMP

The SIRFACT DUMP subcommand indicates where SirFact dumps are to be taken and for which environments dumps are to be taken. All SirFact dumps are taken to procedures.

Information contained in a SirFact dump is easily viewed using the FACT subsystem, described in SirFact FACT subsystem. You can also use a set of $functions, as described in SirFact $functions.

Syntax

SIRFACT DUMP procfile procname [criteria]

procfile The name of the procedure file to which dumps are to be taken. If the procedure file is not open at the time a SirFact dump is to be taken, the procedure file

is opened with the privileges required to create the dump (X'1239') and then closed after the dump.

If the procedure file is already open it must be open with the privileges required to take the dump, or the dump will not be taken.
procname The name of the procedure to be created in procfile for the SirFact dump. procname can be a simple literal string or it can contain special

substitution strings consisting of a plus sign (+) followed by a single character indicating what should be substituted into the dump procedure name.

Because SirFact will never overwrite a procedure with the required procedure name, the use of substitution strings in procname is strongly encouraged. Procedure name substitution strings are described in greater detail in Procedure name substitutions.

criteria A list of blank-delimited selection criteria that indicate to which "environments" the SIRFACT DUMP command is to apply.

All these environments can also be specified on a SIRFACT NODUMP command and have the same meaning for that command. If criteria is not specified, the SIRFACT DUMP (or SIRFACT NODUMP) command applies to any request that receives a request cancellation message that is not being "ignored" by SirFact (SIRFACT IGNORE). Valid selection criteria are:

FILE The procedure file to which the DUMP rule applies. The file name can contain wildcard characters. FILE refers to the file in which the outer procedure being evaluated resides, whether or not the INCLUDE was done in gr- oup context.
IODEV The IODEV number to which the DUMP rule applies.
msg number The Model 204 message number to which the DUMP rule applies. This message number must start with either a M204. for standard Model 204

error messages, MSIR. for SirMods error messages or USER. for site-specific error messages. The message number could also be SNAP, which means that the rule applies to SirFact dumps taken as a result of SIRFACT SNAP commands. For example, this sends all dumps for subscript range errors to file SUBSERR:

SIRFACT DUMP SUBSERR OUCH.+P.+T M204.0553

And this sends all dumps resulting from SIRFACT SNAP commands to file FACTSNAP:

SIRFACT DUMP FACTSNAP OOCH.+P.+T SNAP

PROC The procedure name to which the DUMP rule applies. The procedure name can contain wildcard characters. PROC refers to the outer procedure being evaluated, not the Included procedure in which the error occurred.
SUBSYS The APSY subsystem to which the DUMP rule applies. The subsystem can contain wildcard characters.
USER The userid to which the DUMP rule applies. The userid can contain wildcard characters.

For a DUMP rule to apply to an error being handled by SirFact, the error time environment must match all criteria specified in the SIRFACT DUMP command.

Usage

  • SirFact dumps are taken for any request cancellation message that is not being "ignored" (SIRFACT IGNORE) if the following criteria are met:
    • SIRFACT MAXDUMP has been set.
    • None of the SIRFACT MAXDUMP limits has been exceeded.
    • There is a SIRFACT DUMP command for which the current thread matches all criteria.
    • The dump procedure file as determined by the appropriate SIRFACT DUMP command is already open with the correct privileges (any superset of X'1239') or can be opened with the correct privileges.
    • The output procedure as determined by the appropriate SIRFACT DUMP command does not already exist.
  • Dumps are taken for request cancellations resulting from M204.1332: LONG REQUEST messages, even though technically this message is not a request cancellation message. Note that the dump will only be taken if the user is not given a chance to continue with a DO YOU REALLY WANT TO CONTINUE? message, that is, if the PROMPT X'10' bit is set, if the request is running in an application subsystem, or the request is running on a batch thread.
  • SirFact dumps can be terminated if there is insufficient space in the dump procedure file to hold the dump. In this case, the partial dump will be deleted because it is essentially useless.

Procedure name substitutions

The dump procedure name specified in the SIRFACT DUMP command can contain the special character plus (+) followed by a single character indicating a substitution string. The following characters cause the following substitutions to take place:

+ A literal plus.
1-9 A single digit sequence number as in +2 or +6. SirFact tries sequence numbers from 0 through the indicated number until it finds one that creates a procedure name that doesn't already exist in the target proc file.
D The date that the error happened in YYYYMMDD format.
F The file (not group) that contains the evaluating outer proc.
J The jobname of the job in which the error occurred.
M The number of the message that caused the request cancellation, or the word SNAP if the dump was caused by a SIRFACT SNAP command. The substituted message number does not include the period. So for example, if the request cancellation was caused by a MSIR.0491, a +M would be replaced by a MSIR0491.
P The name of the evaluating outer procedure.
S The name of the current subsystem.
T The date and time that the error happened in YYYYMMDDHHMISS format.
U The userid that encountered the error.

Any other characters following a plus are simply dropped.

For example, if this is the SIRFACT DUMP command:

SIRFACT DUMP FACTDUMP DUMP.+P.+T

And a SirFact trapped error happens in procedure PRE.BADLY.CODED at 14:22:31 on May 12, 2001, the dump procedure name is DUMP.PRE.BADLY.CODED.20010512142231. If the SIRFACT DUMP command is:

SIRFACT DUMP FACTDUMP DUMP.+J.+2

And a SirFact trapped error happens in job DEVONLN, SirFact tries to take the dump to procedure DUMP.DEVONLN.00. If that procedure already exists, it tries to take the dump to DUMP.DEVONLN.01, and so on. If SirFact gets all the way to DUMP.DEVONLN.99 without finding a procedure that doesn't already exist, the dump is not taken.

Because most of the substitution characters in a dump are likely to occur in multiple dumps, it is recommended that most SIRFACT DUMP rules have a procedure name that contains a +1, +2, +3, or a +T.

Managing SirFact dumps

  • Multiple SIRFACT DUMP commands might apply to a particular situation. For example, say the following two commands are in effect:

    SIRFACT DUMP DUMPCUST DUMP-+P-+2 SUBSYS CUSTOMER SIRFACT DUMP JUNKDUMP DUMP-+S-+P PROC *JUNK

    If a request cancellation occurs in procedure PCUST-MISCJUNK in subsystem CUSTOMER, both SIRFACT DUMP commands seem applicable. In such cases, SirFact will always use the last applicable SIRFACT DUMP rule. In this example, the SirFact dump is taken to procedure DUMP-CUSTOMER-PCUST-MISCJUNK in file JUNKDUMP.

    Because SirFact uses the last applicable SIRFACT DUMP rule, these rules should be specified in most general first, most specific last order. For example, this requests that most dumps would go to file SIRFACTD but dumps for subsystem INVENTORY would go to file INVDUMP, except for those in procedures the end in WIDGET, which would go to file WIDGETD:

    SIRFACT DUMP SIRFACTD DMP.+P-+T SIRFACT DUMP INVDUMP DMP.+P-+T SUBSYS INVENTORY SIRFACT DUMP WIDGETD DMP.+P-+T SUBSYS INVENTORY PROC *WIDGET

    If a SIRFACT DUMP command has criteria that are a superset of previous SIRFACT DUMP commands, those previous criteria are discarded. For example, in this sequence, the last SIRFACT DUMP command would always supersede the previous two. When SirFact encounters that last command, it discards the previous two, so a SIRFACT DISPLAY DUMP will only show the last SIRFACT DUMP command.

    SIRFACT DUMP JUNKDUMP +P.+1.DUMP SUBSYS INVENTORY SIRFACT DUMP DUMPDATA +P.+1.DUMP SUBSYS INVENTORY SIRFACT DUMP IDUMP +P.+1.DUMP SUBSYS I*

    An unqualified SIRFACT DUMP command, that is, one with just the procedure file and name, supersedes all previous SIRFACT DUMP commands.

  • SirFact dumps are synchronous on a thread level but asynchronous on a system level. This means that the user or thread for which a SirFact dump is being taken will not be able to do anything while the dump is being taken, but other users or threads will continue to run. This is different from CCASNAPs (and SYSMDUMPs), which stop the entire Online while they are being taken. In any case, even very large SirFact dumps should only take a few seconds to complete so should not have a severe negative impact on performance for either the affected user or any other user.
  • SirFact dumps do not log roll-forward information for the dump procedures, even if the procedure file to which the dump is going is configured to log roll-forward information (the FRCVOPT X'04' bit is not set). This will not interfere with the roll-forward logging for any other data going to the dump procedure file, and it will not cause any recovery problems. It simply means that if the system crashes after a SirFact dump, and the procedure file is rolled back to a checkpoint before the SirFact dump in recovery, the dump will be lost.
  • Checkpoint logging is performed on the dump procedure file as indicated by FRCVOPT. If no checkpoint logging is being performed on the dump procedure file (FRCVOPT X'20' bit set), then there is no danger of losing a SirFact dump because of a roll-back during recovery. But there is a very real chance of the file being left physically broken after an inopportune system crash. This might still be an acceptable risk: without checkpoint logging SirFact dumps will be extremely fast and have very little impact on system performance, and the procedure dictionary and Table D allocations are fairly tolerant of physical inconsistencies.

    This latter point means that should the system crash and a SirFact dump procedure file be left physically inconsistent, most of the information in that file could be recovered after resetting FISTAT — though after doing so, the file should be reorganized or reinitialized after moving the dump procedures elsewhere. It is considerably more questionable to depend on being able to do this if procedure deletions are being mixed with SirFact dump creation. Because of this, it is recommended that SirFact dump procedure file cleanup happen when SirFact dumps are unlikely (perhaps as part of a batch cycle) if the dump procedure file is being run with recovery turned off.

  • While SirFact dumps are very useful, it is probably not critical if a few are lost because of a system crash (in fact the system crash itself would probably cause greater damage), so it might make sense to run with recovery completely turned off for the SirFact dump procedure file with no formal strategy for recovering from a system crash.

    Note: Because of the unusual nature of SirFact dumps, it is strongly recommended that no other data be stored in files that are to receive SirFact dumps.

SIRFACT IGNORE

The SIRFACT IGNORE subcommand indicates which request cancellation error messages are not to produce SirFact dumps.

Syntax

SIRFACT IGNORE msg

Where:

msg The message number of the request cancellation message for which dumps are to be suppressed. The message number must include the message prefix (M204 for standard Model 204 messages, MSIR for Sirius messages, and USER for user messages).

Usage

  • Usually a request cancellation error message is indicative of a programming error or a severe environmental problem. In the case of a programming error, it is very useful to get a SirFact dump to determine the cause of the error.

    In case of a severe environmental problem, it might be helpful to get a SirFact dump to determine the cause of the environmental problem (for example, a SIRFACT CANCEL intercepted $Setg error). But more often than not, a dump would not be particularly helpful, especially for problems that affect structures that are shared among many users.

  • There are even a few request cancellation messages that are actually a normal part of operation! A successful VTAM TRANSFER, for example, results in the cancellation of the request that initiated the TRANSFER.
  • The SIRFACT IGNORE command makes it possible to suppress SirFact dumps for messages for which the dumps would either be undesirable or useless. Examples of such error messages are:

    M204.0441 CCATEMP FULL M204.0443 TABLE D FULL M204.1229 TABLE B FULL -- INSERTS M204.1230 TABLE B FULL -- APPENDS M204.1231 TABLE B FULL -- SPILLS M204.1270 TABLE C FULL - PROPERTY ENTRY M204.1272 TABLE C FULL - PAGE ENTRY M204.1273 TABLE C FULL - REDEFINE M204.1808 ERROR IN EXECUTING TRANSFER STATEMENT M204.1899 TRANSFER STATEMENT COMPLETE, ... MSIR.0517 Cancelling request because of $SIRPARM LISTFC setting (CCATEMP full)

    Certainly, if CCATEMP or a file table fills up and SirFact dumps were not being suppressed for the associated message, a flood of SirFact dumps could occur as user after user trips over the same problem. To prevent getting SirFact dumps for these messages, simply issue the following commands during Online initialization:

    SIRFACT IGNORE M204.0441 SIRFACT IGNORE M204.0443 SIRFACT IGNORE M204.1229 SIRFACT IGNORE M204.1230 SIRFACT IGNORE M204.1231 SIRFACT IGNORE M204.1270 SIRFACT IGNORE M204.1272 SIRFACT IGNORE M204.1273 SIRFACT IGNORE M204.1808 SIRFACT IGNORE M204.1899 SIRFACT IGNORE MSIR.0517

    There might be other request cancellation errors for which a site might want to suppress SirFact dumps. Among these might be:

    M204.0452 TTBL FULL M204.0562 REQUEST TOO LONG - table M204.0574 REQUEST TOO LONG - VTBL M204.0577 QTBL FULL -- DIRECT SEARCH M204.2126 USER'S PUSHDOWN LIST OVERFLOWED

  • SoftSpy can issue some request cancellation errors which occur on the SoftSpy server thread; to ignore these errors, use the following command:

    SIRFACT IGNORE M204.0000

SIRFACT MAXDUMP

The SIRFACT MAXDUMP command establishes limits on the number of SirFact dumps to be taken. The default for the maximum dumps for the entire system is 0, so at least one SIRFACT MAXDUMP command must be issued to get any SirFact dumps.

Syntax

SIRFACT MAXDUMP [type] limit

Where:

type The type of limit being established. It can be one of the following values:
USER Maximum SirFact dumps to be taken in a single user logon. The default is no limit.
TOTAL Maximum SirFact dumps to be taken in the entire Online. The default is 0, so a SIRFACT MAXUMP TOTAL must be issued to get any SirFact dumps.

If type is not specified, it is assumed to be TOTAL, so SIRFACT MAXDUMP 20 is the same as SIRFACT MAXDUP TOTAL 20.

limit The maximum number of dumps to be taken for the indicated type.

Usage

  • A SIRFACT MAXDUMP should be issued at the start of any Online run for which you want SirFact dumps. If for some reason an application or environmental error is causing a "flood" of SirFact dumps, further dumps can be prevented with a SIRFACT MAXDUMP 0. This should not be a concern if a reasonable limit is set by a SIRFACT MAXDUMP at the start of the run.
  • You can view the number of SirFact dumps taken since the Model 204 Online initialization by issuing a SIRFACT DISPLAY|SIRFACT DISPLAY MAXDUMP command.

SIRFACT QUIESCE

SIRFACT QUIESCE facilitates updates of application subsystem procedures while the subsystem is up and in use. This subcommand gets all subsystem users into a "quiescent" state where they are not likely to block procedure update operations or compile inconsistent copies of inner and outer subsystem procedures. Users are quiescent if they are evaluating a pre-compiled request (as determined by the request's prefix not its true pre-compilability) or between procedures in the subsystem driver loop.

When SIRFACT QUIESCE is issued:

  • Any user that is going to switch to the next procedure in the subsystem driver is stopped until the subsystem is resumed.
  • Any user that exits a pre-compiled procedure is stopped at end of request.
  • Other users continue to run until they encounter one of the preceding two points.
  • A user that is evaluating a pre-compiled request or that is between procedures is already considered quiesced.

Syntax

SIRFACT QUIESCE subsys [WAIT sec] [BUMP]

Where:

subsys The name of the subsystem to be quiesced.
sec The number of seconds to wait for the subsystem to be quiesced.

If the subsystem quiesces before this time, SIRFACT QUIESCE returns at that point. If the subsystem is not quiesced after sec seconds, SIRFACT QUIESCE returns with a message stating that the subsystem is not yet quiesced, unless BUMP was specified.

The wait time cannot be set to 0. The default wait time is 3 seconds.

BUMP A Model 204 BUMP, issued for any users still not quiescedaftersec seconds. After bumping these users, SIRFACT QUIESCE waits another second for these users to notice the bump.

Bumped users do not actually disappear from the system: The BUMP sets the user's next procedure to the application subsystem error procedure, but the error procedure does not run because in a quiescing subsystem, users do not go to the next procedure.

Usage

  • If a SIRFACT QUIESCE does not completely quiesce a subsystem, it is quite likely that it will still allow for safe update and replacement of subsystem procedures — any user that hasn't quiesced within a reasonably long time will probably not cause or encounter any problems during an update operation. This is especially true if the X'40' bit of SIRFACT is set (see The SIRFACT parameter). The BUMP option of SIRFACT QUIESCE offers further assurance that no subsystem users will impede or threaten procedure updates.
  • SIRFACT QUIESCE can be issued multiple times by one or multiple users for the same subsystem. In either case, only a single invocation of the SIRFACT QUIESCE inverse operation, SIRFACT RESUME, is necessary to stop the quiescing and resume normal operation of the subsystem. If a user is waiting for the return from SIRFACT QUIESCE, another user can cancel the quiesce and cause the first user to return immediately (with a warning message) by issuing a SIRFACT RESUME for the same subsystem.
  • SIRFACT QUIESCE is valuable for doing application subsystem maintenance. Such maintenance probably requires appropriate settings of the SIRAPSYF parameter and of the SIRFACT parameter.

SIRFACT RESUME

SIRFACT RESUME counters the effect of SIRFACT QUIESCE: SIRFACT QUIESCE renders a currently operating subsystem safe for updates by waiting for and stopping users until no users are inside a non-pre-compiled procedure or compiling precompiled procedures. SIRFACT RESUME stops this quiescing and returns the subsystem to normal operation.

Syntax

SIRFACT RESUME subsys

Usage

  • If a user is waiting for the return from SIRFACT QUIESCE, another user can cancel the quiesce and cause the first user to return immediately (with a warning message) by issuing a SIRFACT RESUME for the same subsystem.
  • SIRFACT QUIESCE can be issued multiple times by one or multiple users for the same subsystem. In either case, only a single invocation of the SIRFACT QUIESCE inverse operation, SIRFACT RESUME, is necessary to stop the quiescing and resume normal operation of the subsystem.

SIRFACT RECNDUMP

The SIRFACT RECNDUMP establishes the number of record numbers from each found set or $list (from LIST option of Display command) to be dumped. By default, SirFact dumps two record numbers from each found set or $list, the first and the last. Note that SirFact does not actually dump the records in any found set or $list unless a record in a found set or $list is the current record in an active FOR EACH RECORD loop, in which case that single record is dumped.

Syntax

SIRFACT RECNDUMP num

The maximum num value for SIRFACT RECNDUMP is 256, and the minimum is 1.

Usage

  • The count of records in a found set or $list is always dumped.

    If a found set or $list contains fewer or the same number of records as the SIRFACT RECNDUMP value, the entire found set or list is dumped. If a found set or $list contains more records than the SIRFACT RECNDUMP value, the first (num+1)/2 and last num/2 record numbers in the found set or $list are dumped.

    For example, if SIRFACT RECNDUMP is 1, only the first record number in a found set or $list will be dumped. If the value is 32, the first 16 and last 16 will be dumped. And if the value is 127, the first 64 and last 63 will be dumped.

  • The cost of a large SIRFACT RECNDUMP value is a somewhat larger dump if a request has many large found sets or $lists, though the cost is only about 6 bytes per record dumped per found set or $list.

    For example, if there are 20 large found sets and $lists in a request that is dumped, a RECNDUMP value of 100 would make the dump 98*20*6 or 11,760 bytes bigger than a dump with the default RECNDUMP value of 2.

    The cost to keeping RECNDUMP small is that potentially useful information is lost about the records in a found set or a $list.

SIRFACT SNAP

The SIRFACT SNAP command requests that a SirFact dump is to be taken for another thread. This can be useful if a thread is looping or hung.

Syntax

SIRFACT SNAP usernum | userid [FORCE]

The SIRFACT SNAP command must be followed by either a user number or a userid. If a userid is specified, the userid must only be logged in on a single thread or SirFact will not take the dump for the thread. If a userid is logged in on multiple threads, the dump must be requested by user number.

The optional FORCE parameter indicates that the SirFact dump is to be taken for the thread, even if the thread holds one or more critical file resource locks. By default, SirFact will not take a dump for another thread on a SIRFACT SNAP command while the thread holds any critical file resource locks, though it will try to wait a little bit (less than 3 seconds) for a window in which the thread being snapped does not hold any critical file resource locks.

Usage

  • There are certain cases where a SIRFACT SNAP command might fail for a looping thread:
    • The most likely is when SirFact is unable to find a time when the thread being snapped does not hold a critical file resource lock. This behavior can be overridden by the specification of the FORCE parameter on the SIRFACT SNAP command.
    • SirFact will also not take a dump for a thread if that thread is waiting on journal or checkpoint I/O. As with critical file resources locks, SirFact will try several times over the course of a few seconds to break in on the thread to be snapped when it is not waiting on checkpoint or journal I/O, but if it fails, it gives up.

    In most such failure cases, the SIRFACT SNAP command can be retried until it succeeds. If a few consecutive SIRFACT SNAP commands fail, the chances of success might be improved by setting the target thread's priority to LOW.

  • The SIRFACT SNAP command can be useful in diagnosing looping thread problems or problems where a user is presented with incorrect output. In both cases, Help desk personnel or a system manager can get a SirFact dump for the thread with the problem, then do whatever is necessary to get the thread back on track.
  • SIRFACT snaps can be taken for non-evaluating threads, even the one issuing the SIRFACT SNAP command, though the dump in such cases will have little besides GTBL.

See also