SirFact SOUL statements: Difference between revisions

Revision as of 00:35, 2 March 2016

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 Off and SirFact On statements are evaluated — they are not compiler directives. This means that in the following chunk of code, the $SETG will be executed with SirFact error trapping disabled if %RECOVER is 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 ON if SirFact error checking is already enabled, and there is no harm in using SIRFACT OFF if 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 Off setting 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 ON bracket to prevent accidentally leaving SirFact $function error checking disabled. It is even better programming practice to avoid the use of SirFact Off altogether.
For example, suppose that a SIRFACT CANCEL has been set up to cancel requests on a return code of -6 from $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 -14 is passed to $ListDel, $ListDel would return a -6, indicating that -14 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 SAVEDLIST available to save another $list, the $ListDel "failure" is irrelevant. Unfortunately, with the SIRFACT CAN $LISTDEL -6 active, this code would often cause a request cancellation.

One solution to this problem would be to simply stop trapping return code -6 from $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.