JAL: minor formatting

2017-05-18T17:32:39Z

minor formatting

← Older revision		Revision as of 17:32, 18 May 2017
Line 155:		Line 155:
	or with <var>DEBUGUL</var> set to a non-zero value.		or with <var>DEBUGUL</var> set to a non-zero value.

	Note ~~that even~~ if the SOUL-to-quad mappings were not collected, all other information such		<p class="note"><b>Note:</b> Even if the SOUL-to-quad mappings were not collected, all other information such
	as %variable values, global variable values, and so on are still		as %variable values, global variable values, and so on are still
	available in <var class="product">SirFact</var> dumps.		available in <var class="product">SirFact</var> dumps.
	Nevertheless, the location of the error and subroutine callback trace are often crucial pieces		Nevertheless, the location of the error and subroutine callback trace are often crucial pieces of information, so it is suggested that if <var class="product">SirFact</var> dumps are to
	of information, so it is suggested that if <var class="product">SirFact</var> dumps are to		be collected, set <var>DEBUGUL</var> to a non-zero value, or set the <var>SIRFACT</var> X'01' bit. </p>
	be collected, ~~either~~ set <var>DEBUGUL</var> to a non-zero value, or set the <var>SIRFACT</var> X'01' bit.

	==<b id="sirapsy"></b>SIRAPSYF parameter==		==<b id="sirapsy"></b>SIRAPSYF parameter==

ELowell at 21:37, 24 April 2017

2017-04-24T21:37:57Z

← Older revision		Revision as of 21:37, 24 April 2017
Line 5:		Line 5:
	(or the <var class="product">Model 204</var> call under CMS) or as a User 0 parameter in the CCAIN stream.		(or the <var class="product">Model 204</var> call under CMS) or as a User 0 parameter in the CCAIN stream.

	==<b id="factprm"></b>~~The~~ SIRFACT parameter==		==<b id="factprm"></b>SIRFACT parameter==
	The <var>SIRFACT</var> system parameter consists of several bits that can control		The <var>SIRFACT</var> system parameter consists of several bits that can control
	the collection of compilation data and the trapping of certain SOUL coding errors.		the collection of compilation data and the trapping of certain SOUL coding errors.
Line 162:		Line 162:
	be collected, either set <var>DEBUGUL</var> to a non-zero value, or set the <var>SIRFACT</var> X'01' bit.		be collected, either set <var>DEBUGUL</var> to a non-zero value, or set the <var>SIRFACT</var> X'01' bit.

	==<b id="sirapsy"></b>~~The~~ SIRAPSYF parameter==		==<b id="sirapsy"></b>SIRAPSYF parameter==
	The <var>SIRAPSYF</var> system parameter controls a number of APSY subsystem maintenance features.		The <var>SIRAPSYF</var> system parameter controls a number of APSY subsystem maintenance features.
	The bit options defined for the features are described below.		The bit options defined for the features are described below.

JAL: link repair

2016-03-14T15:30:45Z

link repair

← Older revision		Revision as of 15:30, 14 March 2016
Line 112:		Line 112:

	<li>If <var>DEBUGUL</var> is 0 and the <var>SIRFACT</var> X'01' bit is not set, $functions		<li>If <var>DEBUGUL</var> is 0 and the <var>SIRFACT</var> X'01' bit is not set, $functions
	that are being "monitored" because of the <var>[[~~The~~ SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command stores extra information in QTBL and STBL to		that are being "monitored" because of the <var>[[SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command stores extra information in QTBL and STBL to
	identify the location of a $function error.		identify the location of a $function error.
	<p>		<p>

Admin: 1 revision: not all SirFact pages

2016-03-02T00:35:42Z

1 revision: not all SirFact pages

← Older revision	Revision as of 00:35, 2 March 2016
(No difference)

JAL: misc cleanup

2016-03-01T20:57:36Z

misc cleanup

New page

<var class="product">SirFact</var> makes use of two system parameters: <var>SIRFACT</var>
and <var>SIRAPSYF</var>.
These parameters are honored only if the Online is running with the <var class="product">SirFact</var> product authorized.
The parameters can only be set as a parameter on the EXEC card
(or the <var class="product">Model 204</var> call under CMS) or as a User 0 parameter in the CCAIN stream.

==The SIRFACT parameter==
The <var>SIRFACT</var> system parameter consists of several bits that can control
the collection of compilation data and the trapping of certain SOUL coding errors.
The bits defined for the <var class="product">SirFact</var> parameter are:
<table class="thJustBold">
<tr><th>X'01'</th>
<td>Collect quad offset to procedure line number mapping information to CCATEMP.</td></tr>

<tr><th>X'02'</th>
<td>Collect quad offset to procedure line number mapping information to server tables even if it is also being collected to CCATEMP.</td></tr>

<tr><th>X'04'</th>
<td>Don't do [[SirFact and comment-initialized globals#lucglob|comment-initialized global]] dummy string substitution.</td></tr>

<tr><th>X'08'</th>
<td>Cancel [[Record loops#FOR_RECORD_NUMBER_processing|For Record Number (or FRN)]] statements where the record number is a null string.</td></tr>

<tr><th>X'10'</th>
<td>Cancel <var>For Record Number</var> or <var>FRN</var> statements where the record number is not a valid number.</td></tr>

<tr><th>X'20'</th>
<td>Cancel <var>For Record Number</var> or <var>FRN</var> statements where the record number is not found.</td></tr>

<tr><th>X'40'</th>
<td>When a procedure is included (whether as part of an application subsystem (APSY) or directly from <var class="product">Model 204</var> command mode), copy it to CCATEMP.
After the copy, release the share enqueue on the procedure. As a result, a user who includes a procedure does not prevent others from updating the procedure.

The copy of the procedure to CCATEMP incurs some extra (barely measurable) overhead.</td></tr>

<tr><th>X'80'</th>
<td>Enable the <var class="product">SirFact</var> APSY maintenance enhancements you specify with the <var>[[#sirapsy|SIRAPSYF]]</var> parameter.

Also, regardless of the <var>SIRAPSYF</var> settings, release the share enqueue on a procedure when the last line of the procedure is read, not when the line after the last line is attempted to be read.</td></tr>
</table>

===Subsystem procedure enqueues===
Unless the <var>SIRFACT</var> X'80' bit is set, a procedure that ends in an <var>End</var> statement is locked in
share mode until procedure evaluation completes and <var class="product">Model 204</var> attempts
to get the next line from the procedure.
If the evaluation takes a long time because the procedure does terminal
I/O or contains a long-running program or because of some other
reason, the procedure is ordinarily not available for update until evaluation completes.
Note: Cosmetic elements like blank lines or comments after an <var>End</var> nullify the benefit of this enhancement, because the lock remains until the last line is read.


Should a procedure depend on the enqueue being held (because it does a <var>[[$RdProc]]</var>, <var>[[$ProcOpn]]</var>, or
something similar against itself and wants to avoid being deleted),
either do not set the <var>SIRFACT</var> X'80' bit, or
add a blank or comment line to the end of any such procedure.
However, if the <var>SIRFACT</var> X'40' bit is on, all procedures are dequeued
before they evaluate, so procedures cannot depend on
<var>$RdProc</var> or <var>$ProcOpn</var> calls against themselves working, unless they can depend
on this because of local policies or rules.

===SIRFACT compilation data collection===
One of the most important pieces of information in determining the cause
of an error is the code location of the error.
Knowing the specific line of code in which an error occurred can be critical in determining
the cause of the error.
Yet typically, <var class="product">Model 204</var> does not collect the
information required to produce this information.
This is because <var class="product">Model 204</var> actually runs quads, not SOUL statements, at evaluation time.

These evaluation time quads are built from the original SOUL at compile
time, but once built, there is generally no way to determine the line
of SOUL that created a particular quad.
So when an error occurred, <var class="product">Model 204</var> would generally be able to report only the QTBL
offset of the executing quad, which would be a fairly useless piece of
information for most purposes.

The solution to this problem is to collect information about the
mapping of quads to SOUL statements at compile time.
There are several ways this is done, each with its own cost.
<ul>
<li>The <var>[[DEBUGUL parameter|DEBUGUL]]</var> parameter, when non-zero, causes the SOUL
statement-to-quad mapping to be stored in QTBL, VTBL, and STBL.

The <var>DEBUGUL</var> parameter is a standard <var class="product">Model 204</var> user parameter.
While using this parameter has little compile time overhead and
no performance overhead, it does add 8 bytes to the length of
each quad, which will tend to increase QTBL requirements by 30-50%.
There would be more minor increases in VTBL and STBL, but it is the
QTBL utilization expense that makes it difficult to use <var>DEBUGUL</var> in a production environment. </li>

<li>If the <var>SIRFACT</var> parameter X'01' bit is set,
SOUL statement-to-quad mapping is stored in CCATEMP.

Because accessing CCATEMP requires logical disk I/O, setting the
<var>SIRFACT</var> X'01' bit has a slight compilation time cost.
It also increases CCATEMP utilization, though probably by less than 10%.
CCATEMP writes also increase slightly, but since these are
asynchronous, they have minimal or no impact on system performance.

Finally, since the mapping pages are not accessed at evaluation time,
setting the <var>SIRFACT</var> X'01' bit has no effect on
evaluation time performance, and because all the information is
stored in CCATEMP, no effect on server sizes.</li>

<li>If <var>DEBUGUL</var> is 0 and the <var>SIRFACT</var> X'01' bit is not set, the <var>Assert</var>
statement stores extra information in QTBL and STBL to identify the location of an <var>Assert</var> statement error.

This causes the <var>Assert</var> statement to use 12 more bytes of QTBL and some additional STBL (to hold
procedure names) in these cases.
In any case, errors that happen as the result of <var>Assert</var> statements always produce a procedure
and line number in the error message.</li>

<li>If <var>DEBUGUL</var> is 0 and the <var>SIRFACT</var> X'01' bit is not set, $functions
that are being "monitored" because of the <var>[[The SIRFACT command#cancel|SIRFACT CANCEL]]</var> command stores extra information in QTBL and STBL to
identify the location of a $function error.

This causes each monitored
$function to use 12 more bytes of QTBL and some additional STBL (to hold
procedure names).
In any case, errors that happen as the result of
<var>SIRFACT CANCEL</var> trapped $function errors always produce a
procedure and line number in the error message.</li>
</ul>

<var>DEBUGUL</var> and the <var>SIRFACT</var> X'01' bit cause the collection of the same
information; the difference is where the information is stored,
and the fact that <var>DEBUGUL</var> is a user parameter (so can be controlled
on a user or application level, while the <var>SIRFACT</var> X'01' bit is a system
parameter).

In any case, all the mechanisms used to collect mappings of <var class="product">SOUL</var> to
quads result in error time messages that indicate the following:
<ul>
<li>The procedure (or command level indication)</li>
<li>The file that contains the procedure</li>
<li>The line number within the procedure where the error happened</li>
</ul>

The actual contents of the line of <var class="product">SOUL</var> are not saved in
any case, and so they are not displayed.
It is possible in many cases for
the procedure to change after it's been compiled (especially for
<var>INCLUDE</var>'d procedures), in which case the indicated line numbers might
not match exactly what is in the updated procedure.

No matter what the collection mechanism, the SOUL-to-quad mapping is saved in
<var class="product">SirFact</var> dumps, so the location of the error can be retrieved
from the dump.
The SOUL-to-quad mapping is also used by
<var class="product">SirFact</var> dump analysis to provide a subroutine callback trace,
as in "subroutine at line whatever in proc whatever called from
line whatever in proc whatever".
This is only available in <var class="product">SirFact</var>
dumps collected for programs compiled with the <var>SIRFACT</var> X'01' bit
or with <var>DEBUGUL</var> set to a non-zero value.

Note that even if the SOUL-to-quad mappings were not collected, all other information such
as %variable values, global variable values, and so on are still
available in <var class="product">SirFact</var> dumps.
Nevertheless, the location of the error and subroutine callback trace are often crucial pieces
of information, so it is suggested that if <var class="product">SirFact</var> dumps are to
be collected, either set <var>DEBUGUL</var> to a non-zero value, or set the <var>SIRFACT</var> X'01' bit.

==The SIRAPSYF parameter==
The <var>SIRAPSYF</var> system parameter controls a number of APSY subsystem maintenance features.
The bit options defined for the features are described below.
X'00' (no options enabled) is the parameter's default value.
Note: No <var>SIRAPSYF</var> features are enabled unless you also set the X'80' bit
on the <var>[[#factprm|SIRFACT parameter]]</var> parameter.

<table class="thJustBold">
<tr><th>X'01'</th>
<td>Allows procedure compilations to be saved (precompiled) for unlocked procedure group members. If an outer or an inner procedure in an unlocked file in a procedure group is changed, or if an outer procedure is added to an unlocked file in a procedure group, the procedure is recompiled and that compilation is saved.

Also allows the pre-compiling of a procedure with a pre-compile prefix that was not present in the procedure group when the subsystem was started. 

If this bit is not set, using unlocked files to facilitate the updating of procedures in a running subsystem has an efficiency cost because procedure compilations are not saved. 

This setting has no effect on procedures in subsystems that use a procedure file instead of a procedure group, and it has no effect on subsystems that use a procedure group but not unlocked files.</td></tr>

<tr><th>X'02'</th>
<td>Detects changes to included procedures that reside in a precompiled procedure in a subsystem procedure group. If such an included procedure is changed, the pre-compiled procedure is recompiled.

This setting has no effect on procedures in subsystems that use a procedure file instead of a procedure group, and it has no effect on subsystems that use a procedure group but not unlocked files.</td></tr>

<tr><th>X'04'</th>
<td>Tracks in a bitmap the CCATEMP pages allocated to pre-compiled procedures in a subsystem. When the subsystem is stopped,
this bitmap is used to free the pages rather than chaining through them, which requires considerable CCATEMP I/O. Although the bitmap method has more (but probably not measurable)
overhead while saving compilations, it can make the <var>[[STOP command: Stopping an application subsystem|STOP SUBSYSTEM]]</var> process significantly faster.

The bitmap is subsystem-wide and not procedure-specific. It does not reduce the time required for discarding the CCATEMP pages that are associated with a compilation that is being replaced.</td></tr>
</table>

Usage notes:
<ul>
<li>These <var>SIRAPSYF</var> features along with the <var>SIRFACT</var> X'40' and X'80' bits
are designed to simplify the updating of procedures and the
pre-compiling of these updated procedures while their subsystem is in use.
Note: These settings do not eliminate the lock on outer procedures
in locked procedure files.
They are designed to suit a procedure group and the placement of
updated procedures in unlocked file(s).


The <var>[[SIRFACT command#quiesce|SIRFACT QUIESCE]]</var> and <var>[[SIRFACT command#resume|SIRFACT RESUME]]</var> subcommands supplement these features
by preventing subsystem users from interfering with procedure update operations.
</li>

<li>For both the X'01' and X'02' bits, an inner or
outer procedure is considered changed if the actual procedure is modified
or if a new version of the procedure is added to an earlier file in the
procedure group.</li>

<li>When using temporary procedure groups, a request compilation is not
saved if any of the outer or inner procedures came from a file not
in the subsystem's permanent group.
Furthermore, if the outer procedure is found in a file not in the subsystem's
permanent group, it will always be recompiled.
If an inner procedure (but not the outer) is found in a file not in the subsystem's
permanent group, whether the procedure is recompiled depends on the
X'02' bit setting:
<ul>
<li>If the bit is off, the procedure might or might not be recompiled.</li>
<li>If the bit is on, the procedure is always recompiled.</li>
</ul>

Hence, it is recommended that where temporary procedure groups are to be used,
the X'02' bit is to be set.</li>

<li>The <var>SIRAPSYF</var> features you specify apply on a system-wide basis.
To specify an override for an individual subsystem,
you can specify in CCASYS a special deferred update DD name for a procedure
group that defines its particular <var>SIRAPSYF</var> option:
SIRAPSYF override
[[File:SFactSubsys.png|450px]]

As shown for <code>SIRLOCAL</code> above, you must: 
<ol>
<li>In [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|SUBSYSMGMT]], specify the special deferred update
DD name under Deferred Name on the Subsystem File Use screen.
Or, if you use an ad hoc procedure, specify this special name
for the <code>APSFDN</code> field in the SCLS records for the subsystem.</li>

<li>Begin the deferred update DD name with the characters
<code>TAPE*</code>, and append the two hexadecimal digits that indicate
the subsystem-specific bit settings you want for the
<var class="product">SirFact</var> APSY enhancements.
<code>TAPE*07</code> sets the <var>SIRAPSYF</var> X'07' features for the group.</li>
</ol>

Setting a deferred index update file name is completely harmless
in systems that do not have the <var class="product">SirFact</var> APSY facility or do not have the
facility enabled (by specifying the <var>SIRFACT</var> X'80' bit).</li>
</ul>

==See also==
{{Template: SirFact topic list}}

[[Category: SirFact]]

SirFact system parameters - Revision history

JAL: minor formatting

ELowell at 21:37, 24 April 2017

JAL: link repair

Admin: 1 revision: not all SirFact pages

JAL: misc cleanup