SirFact SOUL statements - Revision history

ELowell at 16:22, 24 April 2017

2017-04-24T16:22:07Z

JAL: link repair

2016-03-14T15:40:01Z

link repair

← Older revision		Revision as of 15:40, 14 March 2016
Line 77:		Line 77:

	<li>The <code>SirFact Off</code> setting also disables SirFact <var>FRN</var> error trapping		<li>The <code>SirFact Off</code> setting also disables SirFact <var>FRN</var> error trapping
	set by the X'08', X'10', or X'20' bits in the <var>[[~~System~~ parameters#factprm\|SIRFACT]]</var> system parameter.		set by the X'08', X'10', or X'20' bits in the <var>[[SirFact system parameters#factprm\|SIRFACT]]</var> system parameter.
	This means that if <var>SIRFACT</var> <var>FRN</var> error trapping is turned on, but an <var>FRN</var>		This means that if <var>SIRFACT</var> <var>FRN</var> error trapping is turned on, but an <var>FRN</var>
	statement, by design, sometimes refers to a non-existent record, the <var>FRN</var> could be coded as follows:		statement, by design, sometimes refers to a non-existent record, the <var>FRN</var> could be coded as follows:

JAL: link repair

2016-03-14T15:30:05Z

link repair

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

	===The SirFact statement===		===The SirFact statement===
	The <var>[[~~The~~ SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command makes it possible		The <var>[[SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command makes it possible
	to trap return codes from $functions that are indicative of programming		to trap return codes from $functions that are indicative of programming
	errors or severe environmental problems. For simplicity and consistency,		errors or severe environmental problems. For simplicity and consistency,

Admin: 1 revision: not all SirFact pages

2016-03-02T00:35:41Z

1 revision: not all SirFact pages

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

JAL: add link

2016-03-01T20:28:24Z

add link

New page

The [[SOUL]] statements discussed on this page can be of great value to
<var class="product">SirFact</var> users.

===The Assert statement===
The <var>[[Assert statement|Assert]]</var> statement tests an assumption, causes request cancellation
if the assumption is incorrect, and
indicates the procedure and line number containing the failing <var>Assert</var>.
In the presence of appropriate <var>[[SIRFACT command#SIRFACT MAXDUMP|SIRFACT MAXDUMP]]</var> and
<var>[[SIRFACT command#SIRFACT DUMP|SIRFACT DUMP]]</var> settings, it causes the creation of a <var class="product">SirFact</var> dump that
contains a wide variety of information about the program environment at the time of the error.

===The Trace statement===
The <var>[[Trace statement|Trace]]</var> statement returns the same output as
a <var>Print</var> or <var>Audit</var> statement,
but it lets you store that output in a "wrap-around" table in CCATEMP that you can examine with SirFact.

===The SirFact statement===
The <var>[[The SIRFACT command#cancel|SIRFACT CANCEL]]</var> command makes it possible
to trap return codes from $functions that are indicative of programming
errors or severe environmental problems. For simplicity and consistency,
the scope of <var>SIRFACT CANCEL</var> for a $function is global, that is, it
applies to every program running on every thread in the Online.
This should not be a problem, as once again, <var>SIRFACT CANCEL</var> should
only be used to trap severe problems.

However, even the most unlikely return codes might be handled by
<var class="product">SOUL</var> code in certain odd instances.
For these cases, the <var>SirFact</var> SOUL
statement is provided to temporarily disable <var class="product">SirFact</var> error trapping for all $functions or <var>FRN</var> errors.

====Syntax====
SirFact On | Off 
Where:
<table class="thJustBold">
<tr><th nowrap>On | Off</th>
<td><var>Off</var> indicates that <var class="product">SirFact</var> $function error trapping is to be temporarily disabled for the current thread. <var>On</var> indicates that it is to be reenabled.</td></tr>
</table>
If no <var>SirFact</var> statement is present in a <var class="product">SOUL</var> program,
<var class="product">SirFact</var> $function error trapping is always enabled.

The end of a <var class="product">SOUL</var> request automatically re-enables <var class="product">SirFact</var>
$function error trapping.
That is, a <code>Sirfact Off</code> only applies to the program in which it is executed.

====Usage====
<ul>
<li>The <code>SirFact Off</code> and <code>SirFact On</code> statements are evaluated — they are not compiler directives.
This means that in the following chunk of code,
the <code>$SETG</code> will be executed with <var class="product">SirFact</var> error trapping disabled
if <code>%RECOVER</code> is non-zero; otherwise, it will run with <var class="product">SirFact</var> error
trapping enabled.
<nowiki>IF %RECOVER THEN
SIRFACT OFF
END IF
%RC = $SETG('NEXTPROC', 'XP.MAIN-MENU')
IF %RECOVER THEN
SIRFACT ON
END IF
</nowiki></li>

<li>There is no harm in using <code>SIRFACT ON</code> if <var class="product">SirFact</var> error checking is
already enabled, and there is no harm in using <code>SIRFACT OFF</code> if <var class="product">SirFact</var> error checking
is already disabled.
The previous example could just has easily have been coded:
<nowiki>IF %RECOVER THEN
SIRFACT OFF
END IF
%RC = $SETG('NEXTPROC', 'XP.MAIN-MENU')
SIRFACT ON
</nowiki>
Also valid (but pointless) is this:
<nowiki>SIRFACT OFF
SIRFACT OFF
%RC = $SETG('NEXTPROC', 'XP.MAIN-MENU')
SIRFACT ON
</nowiki></li>

<li>The <code>SirFact Off</code> setting also disables SirFact <var>FRN</var> error trapping
set by the X'08', X'10', or X'20' bits in the <var>[[System parameters#factprm|SIRFACT]]</var> system parameter.
This means that if <var>SIRFACT</var> <var>FRN</var> error trapping is turned on, but an <var>FRN</var>
statement, by design, sometimes refers to a non-existent record, the <var>FRN</var> could be coded as follows:
<nowiki>SIRFACT OFF
%HAVEREC = 0
IN FILE ODD FRN %RECNO
%HAVEREC = 1
END FOR
SIRFACT ON
</nowiki></li>

<li>It is good programming practice to minimize the number
of <var class="product">SOUL</var> statements inside a <code>SIRFACT OFF/SIRFACT ON</code>
bracket to prevent accidentally leaving <var class="product">SirFact</var> $function error checking disabled.
It is even better programming practice to avoid the
use of <code>SirFact Off</code> altogether.

For example, suppose that a <var>SIRFACT CANCEL</var> has been set up to cancel requests on
a return code of <code>-6</code> from <var>[[$ListDel]]</var>.
And suppose a procedure has the following chunk of code: 
<nowiki>%LIST = $LISTRST('SAVEDLIST')
%RC = $LISTDEL(%LIST)
</nowiki>

Suppose sometimes this code is run where there is no <var>$ListSav</var>
$list under the name <code>SAVEDLIST</code>.
Before <var class="product">SirFact</var>, the
<var>$ListRst</var> would simply return a <code>-14</code>, indicating that no $list is saved under the indicated name.
When the <code>-14</code> is passed to <var>$ListDel</var>,
<var>$ListDel</var> would return a <code>-6</code>, indicating that <code>-14</code> is an invalid $list identifier (all $list identifiers are positive).

Probably this would not matter: since the ostensible purpose of this code is to
make the name <code>SAVEDLIST</code> available to save another $list,
the <var>$ListDel</var> "failure" is irrelevant.
Unfortunately, with the <code>SIRFACT CAN $LISTDEL -6</code> active, this code would often cause a request cancellation. 

One solution to this problem would be to simply stop trapping
return code <code>-6</code> from <var>$ListDel</var>.
Unfortunately, this would mean that
the benefits of <var class="product">SirFact</var> error trapping would be lost for a mis-coded <var>$ListDel</var>. 

Another option is to change the above code to: 
<nowiki>%LIST = $LISTRST('SAVEDLIST')
SIRFACT OFF
%RC = $LISTDEL(%LIST)
SIRFACT ON
</nowiki>

This gets around the problem, but it is a bit sloppy and does not really
make clear what is going on.
A "cleaner" solution is to change the code to: 
<nowiki>%LIST = $LISTRST('SAVEDLIST')
IF %LIST GT 0
%RC = $LISTDEL(%LIST)
END IF
</nowiki>

This solution actually uses slightly less QTBL space, uses no more CPU, and makes the code clearer. </li>

<li>Ultimately, while the <var>SirFact Off</var> statement can be very useful, it should be used with discretion. </li>
</ul>

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

[[Category: SirFact]]

← Older revision		Revision as of 16:22, 24 April 2017
Line 2:		Line 2:
	<var class="product">SirFact</var> users.		<var class="product">SirFact</var> users.

	===~~The~~ Assert statement===		===Assert statement===
	The <var>[[Assert statement\|Assert]]</var> statement tests an assumption, causes request cancellation		The <var>[[Assert statement\|Assert]]</var> statement tests an assumption, causes request cancellation
	if the assumption is incorrect, and		if the assumption is incorrect, and
Line 10:		Line 10:
	contains a wide variety of information about the program environment at the time of the error.		contains a wide variety of information about the program environment at the time of the error.

	===~~The~~ Trace statement===		===Trace statement===
	The <var>[[Trace statement\|Trace]]</var> statement returns the same output as		The <var>[[Trace statement\|Trace]]</var> statement returns the same output as
	a <var>Print</var> or <var>Audit</var> statement,		a <var>Print</var> or <var>Audit</var> statement,
	but it lets you store that output in a "wrap-around" table in CCATEMP that you can examine with SirFact.		but it lets you store that output in a "wrap-around" table in CCATEMP that you can examine with SirFact.

	===~~The~~ SirFact statement===		===SirFact statement===
			The SirFact statement temporarily disables SirFact $function error trapping for a specific user.

	The <var>[[SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command makes it possible		The <var>[[SIRFACT command#cancel\|SIRFACT CANCEL]]</var> command makes it possible
	to trap return codes from $functions that are indicative of programming		to trap return codes from $functions that are indicative of programming
	errors or severe environmental problems. For simplicity and consistency,		errors or severe environmental problems. For simplicity and consistency,
	the scope of <var>SIRFACT CANCEL</var> for a $function is global~~, that is,~~ it		the scope of <var>SIRFACT CANCEL</var> for a $function is global: it
	applies to every program running on every thread in the Online.		applies to every program running on every thread in the Online.
	This should not be a problem~~, as once again,~~ <var>SIRFACT CANCEL</var> should		This should not be a problem because <var>SIRFACT CANCEL</var> should
	only be used to trap <b>severe</b> problems.		only be used to trap <b>severe</b> problems.