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.
- 1 SIRFACT command syntax
- 2 SIRFACT CANCEL
- 3 SIRFACT DISPLAY
- 4 SIRFACT DUMP
- 5 SIRFACT IGNORE
- 6 SIRFACT MAXDUMP
- 7 SIRFACT QUIESCE
- 8 SIRFACT RESUME
- 9 SIRFACT RECNDUMP
- 10 SIRFACT SNAP
- 11 See also
SIRFACT command syntax
SIRFACT subcomm operands
- 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).
|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
*), question mark (
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
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.
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.
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.
- 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
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 |
|$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 |
|$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 |
|$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 willnot 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.
The SIRFACT DISPLAY subcommand displays many of the SIRFACT subcommands currently in effect.
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:
|subset||A string indicating which values of the indicated subcommand should be displayed.
subset is ignored for
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
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.
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:
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.
- 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 REQUESTmessages, 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 |
|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 |
|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
14:22:31 on May 12, 2001, the dump procedure name is
If the SIRFACT DUMP command is:
SIRFACT DUMP FACTDUMP DUMP.+J.+2
And a SirFact trapped error happens in job
SirFact tries to take the dump to procedure
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
+3, or a
Managing SirFact dumps
SIRFACT DUMPcommands 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
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
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
SIRFACTDbut dumps for subsystem
INVENTORYwould go to file
INVDUMP, except for those in procedures the end in
WIDGET, which would go to file
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 DUMPwill 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.
The SIRFACT IGNORE subcommand indicates which request cancellation error messages are not to produce SirFact dumps.
SIRFACT IGNORE msg
|msg||The message number of the request cancellation message for which dumps are to be suppressed. The message number must include the message prefix
- 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
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.
SIRFACT MAXDUMP [type] limit
|type||The type of limit being established. It can be one of the following values:
If type is not specified, it is assumed to be TOTAL, so
|limit||The maximum number of dumps to be taken for the indicated type.|
- 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
SIRFACT DISPLAY|SIRFACT DISPLAY MAXDUMPcommand.
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.
SIRFACT QUIESCE subsys [WAIT sec] [BUMP]
|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
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.
- 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 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.
SIRFACT RESUME subsys
- 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.
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.
SIRFACT RECNDUMP num
The maximum num value for SIRFACT RECNDUMP is 256, and the minimum is 1.
- 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/2record 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*6or 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.
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.
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.
- 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
- 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.