SirFact SOUL statements
The SOUL statements discussed on this page can be of great value to SirFact users.
The Assert statement
The Assert statement tests an assumption, causes request cancellation if the assumption is incorrect, and indicates the procedure and line number containing the failing Assert. In the presence of appropriate SIRFACT MAXDUMP and SIRFACT DUMP settings, it causes the creation of a SirFact dump that contains a wide variety of information about the program environment at the time of the error.
The Trace statement
The Trace statement returns the same output as a Print or Audit 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 SIRFACT CANCEL 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 SIRFACT CANCEL 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, SIRFACT CANCEL should only be used to trap severe problems.
However, even the most unlikely return codes might be handled by SOUL code in certain odd instances. For these cases, the SirFact SOUL statement is provided to temporarily disable SirFact error trapping for all $functions or FRN errors.
Syntax
SirFact On | Off
Where:
| On | Off | Off indicates that SirFact $function error trapping is to be temporarily disabled for the current thread. On indicates that it is to be reenabled. |
|---|
If no SirFact statement is present in a SOUL program, SirFact $function error trapping is always enabled.
The end of a SOUL request automatically re-enables SirFact
$function error trapping.
That is, a Sirfact Off only applies to the program in which it is executed.
Usage
- The
SirFact OffandSirFact Onstatements are evaluated — they are not compiler directives. This means that in the following chunk of code, the$SETGwill be executed with SirFact error trapping disabled if%RECOVERis non-zero; otherwise, it will run with SirFact error trapping enabled.IF %RECOVER THEN SIRFACT OFF END IF %RC = $SETG('NEXTPROC', 'XP.MAIN-MENU') IF %RECOVER THEN SIRFACT ON END IF
- There is no harm in using
SIRFACT ONif SirFact error checking is already enabled, and there is no harm in usingSIRFACT OFFif SirFact error checking is already disabled. The previous example could just has easily have been coded:IF %RECOVER THEN SIRFACT OFF END IF %RC = $SETG('NEXTPROC', 'XP.MAIN-MENU') SIRFACT ON
Also valid (but pointless) is this:
SIRFACT OFF SIRFACT OFF %RC = $SETG('NEXTPROC', 'XP.MAIN-MENU') SIRFACT ON
- The
SirFact Offsetting also disables SirFact FRN error trapping set by the X'08', X'10', or X'20' bits in the SIRFACT system parameter. This means that if SIRFACT FRN error trapping is turned on, but an FRN statement, by design, sometimes refers to a non-existent record, the FRN could be coded as follows:SIRFACT OFF %HAVEREC = 0 IN FILE ODD FRN %RECNO %HAVEREC = 1 END FOR SIRFACT ON
- It is good programming practice to minimize the number
of SOUL statements inside a
SIRFACT OFF/SIRFACT ONbracket to prevent accidentally leaving SirFact $function error checking disabled. It is even better programming practice to avoid the use ofSirFact Offaltogether.For example, suppose that a SIRFACT CANCEL has been set up to cancel requests on a return code of
-6from $ListDel. And suppose a procedure has the following chunk of code:%LIST = $LISTRST('SAVEDLIST') %RC = $LISTDEL(%LIST)
Suppose sometimes this code is run where there is no $ListSav $list under the name
SAVEDLIST. Before SirFact, the $ListRst would simply return a-14, indicating that no $list is saved under the indicated name. When the-14is passed to $ListDel, $ListDel would return a-6, indicating that-14is 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
SAVEDLISTavailable to save another $list, the $ListDel "failure" is irrelevant. Unfortunately, with theSIRFACT CAN $LISTDEL -6active, this code would often cause a request cancellation.One solution to this problem would be to simply stop trapping return code
-6from $ListDel. Unfortunately, this would mean that the benefits of SirFact error trapping would be lost for a mis-coded $ListDel.Another option is to change the above code to:
%LIST = $LISTRST('SAVEDLIST') SIRFACT OFF %RC = $LISTDEL(%LIST) SIRFACT ON
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:
%LIST = $LISTRST('SAVEDLIST') IF %LIST GT 0 %RC = $LISTDEL(%LIST) END IF
This solution actually uses slightly less QTBL space, uses no more CPU, and makes the code clearer.
- Ultimately, while the SirFact Off statement can be very useful, it should be used with discretion.