SIRFACT command

Note: This is a Sirius Mods-only command prior to Version 7.5 of Model 204.

The SIRFACT command invokes the SirFact post hoc debugging facility. SIRFACT has a set of several subcommands that lets you tailor, trap early, and otherwise maximize the error information dumped for Model 204 debugging purposes.

SIRFACT commands can also be issued as operator commands, that is, on the Online virtual console under VM or as the response to the HALT message under z/OS.

SIRFACT command syntax

SIRFACT subcomm operands

Where:

• subcomm is one of the subcommands listed in the table below.
• operands is one or more operands specific to the SIRFACT subcommand that is being invoked.

The SIRFACT subcommands are summarized below and described in detail in the sections that follow.

You invoke a subcommand with the SIRFACT prefix (for example, SIRFACT CANCEL, SIRFACT MAXDUMP).

SIRFACT subcommand summary

CANCEL	Indicates which return codes from $functions should result in request cancellation. Can be abbreviated CAN.
DISPLAY	Shows the currently active SIRFACT subcommands. Can be abbreviated DISP.
DUMP	Indicates which request cancellations should cause a SirFact dump to be taken and where the dump is to go.
IGNORE	Indicates which request cancellation error messages are not to produce SirFact dumps. Can be abbreviated IGN.
MAXDUMP	Places limits on the number of SirFact dumps that will be taken. Thedefault system limit is 0 so a SIRFACT MAXDUMP must be issued to get any SirFact dumps. Can be abbreviated MAXD.
NOCANCEL	Indicates that certain return codes from $functions should not result in request cancellation. Cancels out the effect of a SIRFACT CANCEL command. Can be abbreviated NOCAN.
NODUMP	Indicates that certain request cancellations should not result in SirFact dumps being produced. Cancels out the effect of a SIRFACT DUMP command.
NOIGNORE	Indicates that certain request cancellation error messages are to produce SirFact dumps. Cancels out the effect of a SIRFACT IGNORE command. Can be abbreviated NOIGN.
QUIESCE	Facilitates updates of APSY subsystem procedures while the subsystem is up and in use.
RECNDUMP	Establishes the number of record numbers from each found set or $list to be dumped. Can be abbreviated RECND.
RESUME	Stops the effect of a SIRFACT QUIESCE command and returns the subsystem to normal operation.
SNAP	Requests that a SirFact dump be taken for another thread.

Some SIRFACT subcommands make use of the wildcard characters asterisk (*), question mark (?), and double quotation mark ("):

?	Represents any single character.
*	Represents any string of characters.
"	The escape flag that allows special characters to bypass wildcard translation.

The following examples illustrate the use of the wildcard characters:

• This command requests a display of all the SIRFACT CANCEL subcommands in effect for $functions that begin with the letters "$LIST":

  SIRFACT DISPLAY CAN $LIST*

• This command indicates that a SirFact dump should be created for any request cancellation errors that occur in a subsystem with a name that is seven characters long and ends in the letters "CUST":

  SIRFACT DUMP DUMPROC DUMP.+T SUBSYS ???CUST

• This command indicates that a SirFact dump should be created for any request cancellation errors that occur for user ?WEIRD. The double-quote (") is required to prevent the question mark (?) from being interpreted as a wildcard character:

  SIRFACT DUMP DUMPROC DUMP.+T USER "?WEIRD

SIRFACT CANCEL

The SIRFACT CANCEL subcommand requires a parameter that indicates the $function to which it applies, followed by return codes that should be intercepted and cause request cancellation when returned by the function.

Syntax

SIRFACT CANCEL function returncodes

function	The name of the function to which the command applies. This name cannot contain wildcard characters.
returncodes	A blank delimited set of return codes that will be intercepted and cause request cancellation.

The subcommand CANCEL can be abbreviated to CAN.

Examples

This command causes cancellation of any request that gets a return code of 1 from $Setg:

SIRFACT CANCEL $SETG 1

This command causes cancellation of any request that gets a return code of -3, -5, -6, or -7 from $ListAdd:

SIRFACT CAN $LISTADD -3 -5 -6 -7

See also Sample settings per $function, below.

Usage

• The rationale for SIRFACT CANCEL is that certain return codes from certain $functions indicate programming errors or severe environmental problems (return code 1 from $Setg, for example), so these codes should result in immediate request cancellation, even in ad hoc or development procedures. For example, a return code of -6 from $Listloc, indicating an invalid $list identifier, suggests a severe problem in a program. Even in an ad hoc procedure, there is little reason to go on after such an error.

  There is a distinction, however, between cancelling the request and creating a SirFact dump for the error. A dump would generally not be desirable for errors in ad hoc or development procedure errors. Because of this, the creation of dumps is controlled by a different SIRFACT subcommand, the SIRFACT DUMP subcommand (SIRFACT DUMP). This subcommand limits the creation of dumps to specific subsystems, procedures, or users.

• It is strongly recommended that the collection of SIRFACT CANCEL commands in the development and test regions match the collection in production. Otherwise, things that work in development might not work in test or production and vice versa. It can't be overemphasized that SIRFACT CANCEL should be used for return codes that indicate programming errors or severe environmental problems that are as invalid in development as in production. In the rare cases where such a return code might be considered "normal" or at least acceptable in a chunk of code, the SirFact statement can be used to temporarily disable SirFact $function error trapping for a specific user.
• A SIRFACT CAN can be disabled with a SIRFACT NOCAN command for the same function.
• If multiple SIRFACT CANCELs (or NOCANCELs) are issued for the same $function, only the last one is used. So the following would only trap return codes of -6 from $Listloc:

  SIRFACT CAN $LISTLOC -5 SIRFACT CAN $LISTLOC -6

  To trap return codes of -5 and -6 from $Listloc, you must issue:

  SIRFACT CAN $LISTLOC -5 -6

• The implementation of SIRFACT CANCEL is very efficient and should cause no measurable performance degradation in the execution of functions for which return codes are being trapped. Performance of the SirFact error trapping is certainly significantly more efficient than testing for the same errors using SOUL.
• Whether or not a SirFact dump is produced for an error trapped by the SIRFACT CANCEL command, these trapped errors are always accompanied by a message indicating the procedure and line number in which the error occurred, as well as the name of the function causing the error and the function arguments.

  SirFact will use any one of several mechanisms to collect the procedure and line number information, each of them having some cost in either QTBL, STBL, VTBL, or CCATEMP space. For a discussion of the costs and tradeoffs of the various approaches, see The SIRFACT parameter.

• It is strongly recommended that you set SIRFACT CANCEL as aggressively as possible. If a SIRFACT CANCEL should cause a problem with "dirty" use of $functions, the preferred solution is to clean up the use of the $functions.

  The next best solution is to wrap the "dirty" function calls in a SIRFACT OFF/SIRFACT ON bracket.

  Eliminating the SIRFACT CANCEL for a value is the least preferable solution, because:

  • It reduces the benefit of SIRFACT CANCEL to encourage good programming practices.
  • It eliminates the ability of SIRFACT CANCEL to catch unintentional misuses of $functions.

Sample settings per $function

The following is a list of "reasonable" SIRFACT CANCEL commands for most Onlines:

SIRFACT CAN $BLDPROC 1 SIRFACT CAN $DATECHG * SIRFACT CAN $DATECNV * SIRFACT CAN $DATEDIF 99999999 SIRFACT CAN $EDIT '' '#' SIRFACT CAN $INCRG 1 2 SIRFACT CAN $LSTPROC 4 SIRFACT CAN $RDPROC 2 SIRFACT CAN $SETG 1 SIRFACT CAN $UNBIN '' SIRFACT CAN $UNFLOAT '' SIRFACT CAN $UNPACK '' SIRFACT CAN $LISTADD -3 -5 -6 -7 SIRFACT CAN $LISTADDI -3 -5 -6 -8 SIRFACT CAN $LISTCNT -5 -6 SIRFACT CAN $LISTCPY -3 -5 -6 SIRFACT CAN $LISTDEL -5 SIRFACT CAN $LISTFIND -5 -6 -7 -8 SIRFACT CAN $LISTILN -5 -6 -7 SIRFACT CAN $LISTIMG -5 -6 -8 SIRFACT CAN $LISTINF -5 -6 -7 -9 SIRFACT CAN $LISTINFI -5 -6 -7 -8 SIRFACT CAN $LISTINS -3 -5 -6 -7 -9 SIRFACT CAN $LISTINSI -3 -5 -6 -8 -9 SIRFACT CAN $LISTLOC -3 -5 -6 -7 -9 SIRFACT CAN $LISTLUP -3 -5 -6 -7 -9 SIRFACT CAN $LISTMOVE -5 -6 SIRFACT CAN $LISTOVL -5 -6 -7 -9 SIRFACT CAN $LISTREM -5 -6 -7 SIRFACT CAN $LISTRST -13 SIRFACT CAN $LISTSAV -3 -5 -13 SIRFACT CAN $LISTSAVE -3 -5 -13 SIRFACT CAN $LISTSAVL -3 -5 -6 SIRFACT CAN $LISTSRT -3 -5 -6 -10 -12 SIRFACT CAN $LISTSORT -3 -5 -6 -10 -12 SIRFACT CAN $LISTSUB -3 -5 -6 -7 -9 SIRFACT CAN $LIST_GLOBAL -3 -14 -15 SIRFACT CAN $LIST_CONV_ITEM -5 -6 -7 SIRFACT CAN $LIST_COPY_ITEMS -3 -5 -6 -7 -8 SIRFACT CAN $LIST_DIFF_ITEM -3 -5 -6 -7

Special-case settings

As might be apparent from the examples above, there are a few $functions for which the return values are special-cased. These are:

$Datechg	On errors, this function will return a number of asterisks (*) equal to the length of the second parameter (the output format). SirFact interprets a SIRFACT CANCEL $DATECHG '*' to require request cancellation for any $Datechg call that returns one or more asterisks.
$Datecnv	On errors, this function will return a number of asterisks (*) equal to the length of the first parameter (the input format). SirFact interprets a SIRFACT CANCEL $DATECNV '*' to require request cancellation for any $Datecnv call that returns one or more asterisks.
$Edit	On errors, this function will return a number of hashes (#) equal to the length of the second parameter (the edit mask). SirFact interprets a SIRFACT CANCEL $EDIT '#' to require request cancellation for any $Edit call that returns one or more hashes.
$Listinf	$Listinf always returns a string value. To indicate an error, $Listinf returns a 2-digit string containing -5, -6, -7, or -9. Yet, in theory at least, these values could also be reasonable values of $list items. SIRFACT CANCEL provides a work-around for this design flaw in $Listinf, because SIRFACT CANCEL will not cause request cancellation when a cancellation value is actually a value in a $list item. SIRFACT CANCEL will only cause cancellation when the return value is truly the result of an error.

SIRFACT DISPLAY

The SIRFACT DISPLAY subcommand displays many of the SIRFACT subcommands currently in effect.

Syntax

SIRFACT DISPLAY [subcom [subset]]

DISPLAY can be abbreviated to DISP.

subcom

The name of the class of subcommands to which the display is to apply. SIRFACT DISPLAY with no subcom value displays all SIRFACT commands from the subcommand classes listed below that are currently in effect. Valid values for subcom are: CANCEL Displays active SIRFACT CANCEL commands. Can be abbreviated CAN. CANCEL can be followed by a subset value that can contain wildcards indicating the $functions for which SIRFACT CANCEL settings are to be displayed. SIRFACT NOCANCEL commands are not displayed because these simply eliminate the SIRFACT CANCELs for the specified $functions. DUMP Displays active SIRFACT DUMP and NODUMP commands. IGNORE Displays active SIRFACT IGNORE commands. Can be abbreviated IGN. IGNORE can be followed by a subset that can contain wildcards indicating the messages for which SIRFACT IGNORE settings are to be displayed. SIRFACT NOIGNORE commands are not displayed because these simply eliminate the SIRFACT IGNOREsfor the specified messages. MAXDUMP Displays active SIRFACT MAXDUMP commands. Can be abbreviated MAXD. MAXDUMP can be followed by a subset indicating the type of limitto be displayed. This can be TOTAL or USER. A SIRFACT DISPLAY MAXDUMP output line is followed by a comment line that reports the number of SirFact dumps taken since the Model 204 Online initialization. For example: SIRFACT DISPLAY MAXDUMP SIRFACT MAXDUMP TOTAL 20 * 11 Number of dumps taken RECNDUMP Displays active SIRFACT RECNDUMP command. Can be abbreviated RECND.

subset

A string indicating which values of the indicated subcommand should be displayed. For SIRFACT DISPLAY CANCEL and SIRFACT DISPLAY IGNORE, subset can contain wildcard characters. For SIRFACT DISPLAY MAXDUMP, it must be a specific limit type. subset is ignored for SIRFACT DISPLAY DUMP and SIRFACT DISPLAY RECNDUMP.

Usage

The display format for the SIRFACT DISPLAY command repeats the format of the SIRFACT commands that are used to set SIRFACT controls. As such, they can be captured (for example with a USE statement) for subsequent reuse.

If no SIRFACT controls are in effect at all or for the specific subcommand and subset requested, SIRFACT DISPLAY simply returns without issuing any messages.

Examples of valid SIRFACT DISPLAY commands follow:

SIRFACT DISPLAY SIRFACT DISPLAY CANCEL SIRFACT DISPLAY CAN $LIST* SIRFACT DISPLAY CANCEL $EDIT SIRFACT DISPLAY DUMP SIRFACT DISPLAY IGNORE SIRFACT DISPLAY IGN MSIR.* SIRFACT DISPLAY MAXDUMP SIRFACT DISPLAY MAXD USER

SIRFACT DUMP

The SIRFACT DUMP subcommand indicates where SirFact dumps are to be taken and for which environments dumps are to be taken. All SirFact dumps are taken to procedures.

Information contained in a SirFact dump is easily viewed using the FACT subsystem, described in SirFact FACT subsystem. You can also use a set of $functions, as described in SirFact $functions.

Syntax

SIRFACT DUMP procfile procname [criteria]

procfile	The name of the procedure file to which dumps are to be taken. If the procedure file is not open at the time a SirFact dump is to be taken, the procedure file is opened with the privileges required to create the dump (X'1239') and then closed after the dump. If the procedure file is already open it must be open with the privileges required to take the dump, or the dump will not be taken.
procname	The name of the procedure to be created in procfile for the SirFact dump. procname can be a simple literal string or it can contain special substitution strings consisting of a plus sign (+) followed by a single character indicating what should be substituted into the dump procedure name. Because SirFact will never overwrite a procedure with the required procedure name, the use of substitution strings in procname is strongly encouraged. Procedure name substitution strings are described in greater detail in Procedure name substitutions.
criteria	A list of blank-delimited selection criteria that indicate to which "environments" the SIRFACT DUMP command is to apply. All these environments can also be specified on a SIRFACT NODUMP command and have the same meaning for that command. If criteria is not specified, the SIRFACT DUMP (or SIRFACT NODUMP) command applies to any request that receives a request cancellation message that is not being "ignored" by SirFact (SIRFACT IGNORE). Valid selection criteria are: FILE The procedure file to which the DUMP rule applies. The file name can contain wildcard characters. FILE refers to the file in which the outer procedure being evaluated resides, whether or not the INCLUDE was done in gr- oup context. IODEV The IODEV number to which the DUMP rule applies. msg number The Model 204 message number to which the DUMP rule applies. This message number must start with either a M204. for standard Model 204 error messages, MSIR. for SirMods error messages or USER. for site-specific error messages. The message number could also be SNAP, which means that the rule applies to SirFact dumps taken as a result of SIRFACT SNAP commands. For example, this sends all dumps for subscript range errors to file SUBSERR: SIRFACT DUMP SUBSERR OUCH.+P.+T M204.0553 And this sends all dumps resulting from SIRFACT SNAP commands to file FACTSNAP: SIRFACT DUMP FACTSNAP OOCH.+P.+T SNAP PROC The procedure name to which the DUMP rule applies. The procedure name can contain wildcard characters. PROC refers to the outer procedure being evaluated, not the Included procedure in which the error occurred. SUBSYS The APSY subsystem to which the DUMP rule applies. The subsystem can contain wildcard characters. USER The userid to which the DUMP rule applies. The userid can contain wildcard characters. For a DUMP rule to apply to an error being handled by SirFact, the error time environment must match all criteria specified in the SIRFACT DUMP command.

Usage

• SirFact dumps are taken for any request cancellation message that is not being "ignored" (SIRFACT IGNORE) if the following criteria are met:
  • SIRFACT MAXDUMP has been set.
  • None of the SIRFACT MAXDUMP limits has been exceeded.
  • There is a SIRFACT DUMP command for which the current thread matches all criteria.
  • The dump procedure file as determined by the appropriate SIRFACT DUMP command is already open with the correct privileges (any superset of X'1239') or can be opened with the correct privileges.
  • The output procedure as determined by the appropriate SIRFACT DUMP command does not already exist.
• Dumps are taken for request cancellations resulting from M204.1332: LONG REQUEST messages, even though technically this message is not a request cancellation message. Note that the dump will only be taken if the user is not given a chance to continue with a DO YOU REALLY WANT TO CONTINUE? message, that is, if the PROMPT X'10' bit is set, if the request is running in an application subsystem, or the request is running on a batch thread.
• SirFact dumps can be terminated if there is insufficient space in the dump procedure file to hold the dump. In this case, the partial dump will be deleted because it is essentially useless.

Procedure name substitutions

The dump procedure name specified in the SIRFACT DUMP command can contain the special character plus (+) followed by a single character indicating a substitution string. The following characters cause the following substitutions to take place:

+	A literal plus.
1-9	A single digit sequence number as in +2 or +6. SirFact tries sequence numbers from 0 through the indicated number until it finds one that creates a procedure name that doesn't already exist in the target proc file.
D	The date that the error happened in YYYYMMDD format.
F	The file (not group) that contains the evaluating outer proc.
J	The jobname of the job in which the error occurred.
M	The number of the message that caused the request cancellation, or the word SNAP if the dump was caused by a SIRFACT SNAP command. The substituted message number does not include the period. So for example, if the request cancellation was caused by a MSIR.0491, a +M would be replaced by a MSIR0491.
P	The name of the evaluating outer procedure.
S	The name of the current subsystem.
T	The date and time that the error happened in YYYYMMDDHHMISS format.
U	The userid that encountered the error.

Any other characters following a plus are simply dropped.

For example, if this is the SIRFACT DUMP command:

SIRFACT DUMP FACTDUMP DUMP.+P.+T

And a SirFact trapped error happens in procedure PRE.BADLY.CODED at 14:22:31 on May 12, 2001, the dump procedure name is DUMP.PRE.BADLY.CODED.20010512142231. If the SIRFACT DUMP command is:

SIRFACT DUMP FACTDUMP DUMP.+J.+2

And a SirFact trapped error happens in job DEVONLN, SirFact tries to take the dump to procedure DUMP.DEVONLN.00. If that procedure already exists, it tries to take the dump to DUMP.DEVONLN.01, and so on. If SirFact gets all the way to DUMP.DEVONLN.99 without finding a procedure that doesn't already exist, the dump is not taken.

Because most of the substitution characters in a dump are likely to occur in multiple dumps, it is recommended that most SIRFACT DUMP rules have a procedure name that contains a +1, +2, +3, or a +T.

Managing SirFact dumps

• Multiple SIRFACT DUMP commands might apply to a particular situation. For example, say the following two commands are in effect:

  SIRFACT DUMP DUMPCUST DUMP-+P-+2 SUBSYS CUSTOMER SIRFACT DUMP JUNKDUMP DUMP-+S-+P PROC *JUNK

  If a request cancellation occurs in procedure PCUST-MISCJUNK in subsystem CUSTOMER, both SIRFACT DUMP commands seem applicable. In such cases, SirFact will always use the last applicable SIRFACT DUMP rule. In this example, the SirFact dump is taken to procedure DUMP-CUSTOMER-PCUST-MISCJUNK in file JUNKDUMP.

  Because SirFact uses the last applicable SIRFACT DUMP rule, these rules should be specified in most general first, most specific last order. For example, this requests that most dumps would go to file SIRFACTD but dumps for subsystem INVENTORY would go to file INVDUMP, except for those in procedures the end in WIDGET, which would go to file WIDGETD:

  SIRFACT DUMP SIRFACTD DMP.+P-+T SIRFACT DUMP INVDUMP DMP.+P-+T SUBSYS INVENTORY SIRFACT DUMP WIDGETD DMP.+P-+T SUBSYS INVENTORY PROC *WIDGET

  If a SIRFACT DUMP command has criteria that are a superset of previous SIRFACT DUMP commands, those previous criteria are discarded. For example, in this sequence, the last SIRFACT DUMP command would always supersede the previous two. When SirFact encounters that last command, it discards the previous two, so a SIRFACT DISPLAY DUMP will only show the last SIRFACT DUMP command.

  SIRFACT DUMP JUNKDUMP +P.+1.DUMP SUBSYS INVENTORY SIRFACT DUMP DUMPDATA +P.+1.DUMP SUBSYS INVENTORY SIRFACT DUMP IDUMP +P.+1.DUMP SUBSYS I*

  An unqualified SIRFACT DUMP command, that is, one with just the procedure file and name, supersedes all previous SIRFACT DUMP commands.

• SirFact dumps are synchronous on a thread level but asynchronous on a system level. This means that the user or thread for which a SirFact dump is being taken will not be able to do anything while the dump is being taken, but other users or threads will continue to run. This is different from CCASNAPs (and SYSMDUMPs), which stop the entire Online while they are being taken. In any case, even very large SirFact dumps should only take a few seconds to complete so should not have a severe negative impact on performance for either the affected user or any other user.
• SirFact dumps do not log roll-forward information for the dump procedures, even if the procedure file to which the dump is going is configured to log roll-forward information (the FRCVOPT X'04' bit is not set). This will not interfere with the roll-forward logging for any other data going to the dump procedure file, and it will not cause any recovery problems. It simply means that if the system crashes after a SirFact dump, and the procedure file is rolled back to a checkpoint before the SirFact dump in recovery, the dump will be lost.
• Checkpoint logging is performed on the dump procedure file as indicated by FRCVOPT. If no checkpoint logging is being performed on the dump procedure file (FRCVOPT X'20' bit set), then there is no danger of losing a SirFact dump because of a roll-back during recovery. But there is a very real chance of the file being left physically broken after an inopportune system crash. This might still be an acceptable risk: without checkpoint logging SirFact dumps will be extremely fast and have very little impact on system performance, and the procedure dictionary and Table D allocations are fairly tolerant of physical inconsistencies.

  This latter point means that should the system crash and a SirFact dump procedure file be left physically inconsistent, most of the information in that file could be recovered after resetting FISTAT — though after doing so, the file should be reorganized or reinitialized after moving the dump procedures elsewhere. It is considerably more questionable to depend on being able to do this if procedure deletions are being mixed with SirFact dump creation. Because of this, it is recommended that SirFact dump procedure file cleanup happen when SirFact dumps are unlikely (perhaps as part of a batch cycle) if the dump procedure file is being run with recovery turned off.

• While SirFact dumps are very useful, it is probably not critical if a few are lost because of a system crash (in fact the system crash itself would probably cause greater damage), so it might make sense to run with recovery completely turned off for the SirFact dump procedure file with no formal strategy for recovering from a system crash.

  Note: Because of the unusual nature of SirFact dumps, it is strongly recommended that no other data be stored in files that are to receive SirFact dumps.

SIRFACT IGNORE

The SIRFACT IGNORE subcommand indicates which request cancellation error messages are not to produce SirFact dumps.

Syntax

SIRFACT IGNORE msg

Where:

msg	The message number of the request cancellation message for which dumps are to be suppressed. The message number must include the message prefix (M204 for standard Model 204 messages, MSIR for Sirius messages, and USER for user messages).

Usage

• Usually a request cancellation error message is indicative of a programming error or a severe environmental problem. In the case of a programming error, it is very useful to get a SirFact dump to determine the cause of the error.

  In case of a severe environmental problem, it might be helpful to get a SirFact dump to determine the cause of the environmental problem (for example, a SIRFACT CANCEL intercepted $Setg error). But more often than not, a dump would not be particularly helpful, especially for problems that affect structures that are shared among many users.

• There are even a few request cancellation messages that are actually a normal part of operation! A successful VTAM TRANSFER, for example, results in the cancellation of the request that initiated the TRANSFER.
• The SIRFACT IGNORE command makes it possible to suppress SirFact dumps for messages for which the dumps would either be undesirable or useless. Examples of such error messages are:

  M204.0441 CCATEMP FULL M204.0443 TABLE D FULL M204.1229 TABLE B FULL -- INSERTS M204.1230 TABLE B FULL -- APPENDS M204.1231 TABLE B FULL -- SPILLS M204.1270 TABLE C FULL - PROPERTY ENTRY M204.1272 TABLE C FULL - PAGE ENTRY M204.1273 TABLE C FULL - REDEFINE M204.1808 ERROR IN EXECUTING TRANSFER STATEMENT M204.1899 TRANSFER STATEMENT COMPLETE, ... MSIR.0517 Cancelling request because of $SIRPARM LISTFC setting (CCATEMP full)

  Certainly, if CCATEMP or a file table fills up and SirFact dumps were not being suppressed for the associated message, a flood of SirFact dumps could occur as user after user trips over the same problem. To prevent getting SirFact dumps for these messages, simply issue the following commands during Online initialization:

  SIRFACT IGNORE M204.0441 SIRFACT IGNORE M204.0443 SIRFACT IGNORE M204.1229 SIRFACT IGNORE M204.1230 SIRFACT IGNORE M204.1231 SIRFACT IGNORE M204.1270 SIRFACT IGNORE M204.1272 SIRFACT IGNORE M204.1273 SIRFACT IGNORE M204.1808 SIRFACT IGNORE M204.1899 SIRFACT IGNORE MSIR.0517

  There might be other request cancellation errors for which a site might want to suppress SirFact dumps. Among these might be:

  M204.0452 TTBL FULL M204.0562 REQUEST TOO LONG - table M204.0574 REQUEST TOO LONG - VTBL M204.0577 QTBL FULL -- DIRECT SEARCH M204.2126 USER'S PUSHDOWN LIST OVERFLOWED

• SoftSpy can issue some request cancellation errors which occur on the SoftSpy server thread; to ignore these errors, use the following command:

  SIRFACT IGNORE M204.0000

SIRFACT MAXDUMP

The SIRFACT MAXDUMP command establishes limits on the number of SirFact dumps to be taken. The default for the maximum dumps for the entire system is 0, so at least one SIRFACT MAXDUMP command must be issued to get any SirFact dumps.

Syntax

SIRFACT MAXDUMP [type] limit

Where:

type

The type of limit being established. It can be one of the following values: USER Maximum SirFact dumps to be taken in a single user logon. The default is no limit. TOTAL Maximum SirFact dumps to be taken in the entire Online. The default is 0, so a SIRFACT MAXUMP TOTAL must be issued to get any SirFact dumps. If type is not specified, it is assumed to be TOTAL, so SIRFACT MAXDUMP 20is the same as SIRFACT MAXDUP TOTAL 20.

limit

The maximum number of dumps to be taken for the indicated type.

Usage

• A SIRFACT MAXDUMP should be issued at the start of any Online run for which you want SirFact dumps. If for some reason an application or environmental error is causing a "flood" of SirFact dumps, further dumps can be prevented with a SIRFACT MAXDUMP 0. This should not be a concern if a reasonable limit is set by a SIRFACT MAXDUMP at the start of the run.
• You can view the number of SirFact dumps taken since the Model 204 Online initialization by issuing a SIRFACT DISPLAY|SIRFACT DISPLAY MAXDUMP command.

SIRFACT QUIESCE

SIRFACT QUIESCE facilitates updates of application subsystem procedures while the subsystem is up and in use. This subcommand gets all subsystem users into a "quiescent" state where they are not likely to block procedure update operations or compile inconsistent copies of inner and outer subsystem procedures. Users are quiescent if they are evaluating a pre-compiled request (as determined by the request's prefix not its true pre-compilability) or between procedures in the subsystem driver loop.

When SIRFACT QUIESCE is issued:

• Any user that is going to switch to the next procedure in the subsystem driver is stopped until the subsystem is resumed.
• Any user that exits a pre-compiled procedure is stopped at end of request.
• Other users continue to run until they encounter one of the preceding two points.
• A user that is evaluating a pre-compiled request or that is between procedures is already considered quiesced.

Syntax

SIRFACT QUIESCE subsys [WAIT sec] [BUMP]

Where:

subsys	The name of the subsystem to be quiesced.
sec	The number of seconds to wait for the subsystem to be quiesced. If the subsystem quiesces before this time, SIRFACT QUIESCE returns at that point. If the subsystem is not quiesced after sec seconds, SIRFACT QUIESCE returns with a message stating that the subsystem is not yet quiesced, unless BUMP was specified. The wait time cannot be set to 0. The default wait time is 3 seconds.
BUMP	A Model 204 BUMP, issued for any users still not quiescedaftersec seconds. After bumping these users, SIRFACT QUIESCE waits another second for these users to notice the bump. Bumped users do not actually disappear from the system: The BUMP sets the user's next procedure to the application subsystem error procedure, but the error procedure does not run because in a quiescing subsystem, users do not go to the next procedure.

Usage

• If a SIRFACT QUIESCE does not completely quiesce a subsystem, it is quite likely that it will still allow for safe update and replacement of subsystem procedures — any user that hasn't quiesced within a reasonably long time will probably not cause or encounter any problems during an update operation. This is especially true if the X'40' bit of SIRFACT is set (see The SIRFACT parameter). The BUMP option of SIRFACT QUIESCE offers further assurance that no subsystem users will impede or threaten procedure updates.
• SIRFACT QUIESCE can be issued multiple times by one or multiple users for the same subsystem. In either case, only a single invocation of the SIRFACT QUIESCE inverse operation, SIRFACT RESUME, is necessary to stop the quiescing and resume normal operation of the subsystem. If a user is waiting for the return from SIRFACT QUIESCE, another user can cancel the quiesce and cause the first user to return immediately (with a warning message) by issuing a SIRFACT RESUME for the same subsystem.
• SIRFACT QUIESCE is valuable for doing application subsystem maintenance. Such maintenance probably requires appropriate settings of the SIRAPSYF parameter and of the SIRFACT parameter.

SIRFACT RESUME

SIRFACT RESUME counters the effect of SIRFACT QUIESCE: SIRFACT QUIESCE renders a currently operating subsystem safe for updates by waiting for and stopping users until no users are inside a non-pre-compiled procedure or compiling precompiled procedures. SIRFACT RESUME stops this quiescing and returns the subsystem to normal operation.

Syntax

SIRFACT RESUME subsys

Usage

• If a user is waiting for the return from SIRFACT QUIESCE, another user can cancel the quiesce and cause the first user to return immediately (with a warning message) by issuing a SIRFACT RESUME for the same subsystem.
• SIRFACT QUIESCE can be issued multiple times by one or multiple users for the same subsystem. In either case, only a single invocation of the SIRFACT QUIESCE inverse operation, SIRFACT RESUME, is necessary to stop the quiescing and resume normal operation of the subsystem.

SIRFACT RECNDUMP

The SIRFACT RECNDUMP establishes the number of record numbers from each found set or $list (from LIST option of Display command) to be dumped. By default, SirFact dumps two record numbers from each found set or $list, the first and the last. Note that SirFact does not actually dump the records in any found set or $list unless a record in a found set or $list is the current record in an active FOR EACH RECORD loop, in which case that single record is dumped.

Syntax

SIRFACT RECNDUMP num

The maximum num value for SIRFACT RECNDUMP is 256, and the minimum is 1.

Usage

• The count of records in a found set or $list is always dumped.

  If a found set or $list contains fewer or the same number of records as the SIRFACT RECNDUMP value, the entire found set or list is dumped. If a found set or $list contains more records than the SIRFACT RECNDUMP value, the first (num+1)/2 and last num/2 record numbers in the found set or $list are dumped.

  For example, if SIRFACT RECNDUMP is 1, only the first record number in a found set or $list will be dumped. If the value is 32, the first 16 and last 16 will be dumped. And if the value is 127, the first 64 and last 63 will be dumped.

• The cost of a large SIRFACT RECNDUMP value is a somewhat larger dump if a request has many large found sets or $lists, though the cost is only about 6 bytes per record dumped per found set or $list.

  For example, if there are 20 large found sets and $lists in a request that is dumped, a RECNDUMP value of 100 would make the dump 98*20*6 or 11,760 bytes bigger than a dump with the default RECNDUMP value of 2.

  The cost to keeping RECNDUMP small is that potentially useful information is lost about the records in a found set or a $list.

SIRFACT SNAP

The SIRFACT SNAP command requests that a SirFact dump is to be taken for another thread. This can be useful if a thread is looping or hung.

Syntax

SIRFACT SNAP usernum | userid [FORCE]

The SIRFACT SNAP command must be followed by either a user number or a userid. If a userid is specified, the userid must only be logged in on a single thread or SirFact will not take the dump for the thread. If a userid is logged in on multiple threads, the dump must be requested by user number.

The optional FORCE parameter indicates that the SirFact dump is to be taken for the thread, even if the thread holds one or more critical file resource locks. By default, SirFact will not take a dump for another thread on a SIRFACT SNAP command while the thread holds any critical file resource locks, though it will try to wait a little bit (less than 3 seconds) for a window in which the thread being snapped does not hold any critical file resource locks.

Usage

• There are certain cases where a SIRFACT SNAP command might fail for a looping thread:
  • The most likely is when SirFact is unable to find a time when the thread being snapped does not hold a critical file resource lock. This behavior can be overridden by the specification of the FORCE parameter on the SIRFACT SNAP command.
  • SirFact will also not take a dump for a thread if that thread is waiting on journal or checkpoint I/O. As with critical file resources locks, SirFact will try several times over the course of a few seconds to break in on the thread to be snapped when it is not waiting on checkpoint or journal I/O, but if it fails, it gives up.

  In most such failure cases, the SIRFACT SNAP command can be retried until it succeeds. If a few consecutive SIRFACT SNAP commands fail, the chances of success might be improved by setting the target thread's priority to LOW.

• The SIRFACT SNAP command can be useful in diagnosing looping thread problems or problems where a user is presented with incorrect output. In both cases, Help desk personnel or a system manager can get a SirFact dump for the thread with the problem, then do whatever is necessary to get the thread back on track.
• SIRFACT snaps can be taken for non-evaluating threads, even the one issuing the SIRFACT SNAP command, though the dump in such cases will have little besides GTBL.

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