SirFact system parameters

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

The SIRFACT parameter

The SIRFACT 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 SirFact parameter are:

X'01'	Collect quad offset to procedure line number mapping information to CCATEMP.
X'02'	Collect quad offset to procedure line number mapping information to server tables even if it is also being collected to CCATEMP.
X'04'	Don't do comment-initialized global dummy string substitution.
X'08'	Cancel For Record Number (or FRN) statements where the record number is a null string.
X'10'	Cancel For Record Number or FRN statements where the record number is not a valid number.
X'20'	Cancel For Record Number or FRN statements where the record number is not found.
X'40'	When a procedure is included (whether as part of an application subsystem (APSY) or directly from Model 204 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.
X'80'	Enable the SirFact APSY maintenance enhancements you specify with the SIRAPSYF parameter. Also, regardless of the SIRAPSYF 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.

Subsystem procedure enqueues

Unless the SIRFACT X'80' bit is set, a procedure that ends in an End statement is locked in share mode until procedure evaluation completes and Model 204 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 End 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 $RdProc, $ProcOpn, or something similar against itself and wants to avoid being deleted), either do not set the SIRFACT X'80' bit, or add a blank or comment line to the end of any such procedure. However, if the SIRFACT X'40' bit is on, all procedures are dequeued before they evaluate, so procedures cannot depend on $RdProc or $ProcOpn 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, Model 204 does not collect the information required to produce this information. This is because Model 204 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, Model 204 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.

• The DEBUGUL parameter, when non-zero, causes the SOUL statement-to-quad mapping to be stored in QTBL, VTBL, and STBL.

  The DEBUGUL parameter is a standard Model 204 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 DEBUGUL in a production environment.

• If the SIRFACT 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 SIRFACT 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 SIRFACT X'01' bit has no effect on evaluation time performance, and because all the information is stored in CCATEMP, no effect on server sizes.

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

  This causes the Assert 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 Assert statements always produce a procedure and line number in the error message.

• If DEBUGUL is 0 and the SIRFACT X'01' bit is not set, $functions that are being "monitored" because of the SIRFACT CANCEL 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 SIRFACT CANCEL trapped $function errors always produce a procedure and line number in the error message.

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

In any case, all the mechanisms used to collect mappings of SOUL to quads result in error time messages that indicate the following:

• The procedure (or command level indication)
• The file that contains the procedure
• The line number within the procedure where the error happened

The actual contents of the line of SOUL 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 INCLUDE'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 SirFact dumps, so the location of the error can be retrieved from the dump. The SOUL-to-quad mapping is also used by SirFact 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 SirFact dumps collected for programs compiled with the SIRFACT X'01' bit or with DEBUGUL 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 SirFact dumps. Nevertheless, the location of the error and subroutine callback trace are often crucial pieces of information, so it is suggested that if SirFact dumps are to be collected, either set DEBUGUL to a non-zero value, or set the SIRFACT X'01' bit.

The SIRAPSYF parameter

The SIRAPSYF 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 SIRAPSYF features are enabled unless you also set the X'80' bit on the SIRFACT parameter parameter.

X'01'	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.
X'02'	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.
X'04'	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 STOP SUBSYSTEM 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.

Usage notes:

• These SIRAPSYF features along with the SIRFACT 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 SIRFACT QUIESCE and SIRFACT RESUME subcommands supplement these features by preventing subsystem users from interfering with procedure update operations.

• 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.
• 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:
  • If the bit is off, the procedure might or might not be recompiled.
  • If the bit is on, the procedure is always recompiled.

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

• The SIRAPSYF 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 SIRAPSYF option:

  SIRAPSYF override

  

  As shown for SIRLOCAL above, you must:

  1. In 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 APSFDN field in the SCLS records for the subsystem.
  2. Begin the deferred update DD name with the characters TAPE*, and append the two hexadecimal digits that indicate the subsystem-specific bit settings you want for the SirFact APSY enhancements. TAPE*07 sets the SIRAPSYF X'07' features for the group.

  Setting a deferred index update file name is completely harmless in systems that do not have the SirFact APSY facility or do not have the facility enabled (by specifying the SIRFACT X'80' bit).

See also

• SirFact
• SirFact post hoc debugging
• SIRFACT command
• SirFact SOUL statements
• SirFact system parameters
• SirFact $functions
• SirFact and comment-initialized globals
• SirFact FACT subsystem
• SirFact date processing