SirFact FACT subsystem

From m204wiki
Revision as of 21:21, 18 May 2017 by JAL (talk | contribs) (→‎Using a local subsystem or SirPro: make SirPro subsection)
Jump to navigation Jump to search

Overview

The diagnostic dumps produced by SirFact are stored in base64 encoded format in Model 204 procedures inside Model 204 files. Not readable in raw format, the dumps must have diagnostic information extracted from them with the $Fact_* functions described in SirFact $functions.

While users can write their own system using the $Fact_* functions, the FACT subsystem is a ready-to-run, full-screen interface for viewing SirFact dumps.

Accessing the FACT subsystem

Using the command line

The FACT subsystem can be accessed from the Model 204 command line by specifying the file and procedure names in this format:

FACT filename procname

For example:

FACT SAMPLFIL DUMP.PROC86.20040603120114

Using a local subsystem

The FACT subsystem can also be invoked from a subsystem that displays lists of procedures containing SirFact dumps. To transfer control from a local subsystem to FACT, use the standard application subsystem (APSY) transfer facility (the XFER global). Make sure to:

  1. Set the global variable FACT.RETURN to the name of the APSY to which FACT should return control.
  2. Set the global variable COM to the source file and source procedure containing the SirFact dump.

An example follows:

%DUMMY = $SETG('COM',%FILENAME WITH ' ' WITH %DUMP_PROC_NAME) %DUMMY = $SETG('NEXTPROC','XFER') %DUMMY = $SETG('XFER','FACT') %DUMMY = $SETG('FACT.RETURN','MYAPSY') STOP

Using SirPro

The SirPro subsystem is already configured to perform an APSY transfer (as described above) when an F prefix command is entered on the SirPro Procedure List screen:

F command in SirPro

The F prefix command in SirPro only works for sites that own SirFact. If a non-SirFact procedure is selected with an F, an error message is posted to the screen.

Using RKWeb

RKWeb is a web interface available as of version 7.7 of RKTools.

In RKWeb, selecting the Build > Fact Dump Analysis > Select option lets you display a list of SirFact dump procedures (like the one above in F command in SirPro) from which you select the dump to process.

The FACT context information display

Whether the FACT system is accessed from the command line, from SirPro or a local subsystem, or from RKWeb, the main screen displayed is the same: a scrollable display of the basic dump information, extracted from the dump. As further commands are entered on the screen's command line, their output is appended to the display, and you can scroll through the list. If you want a printed version of the output, the F12 key sends the list to a print device.

FACT context information

The initial FACT screen shows default context information for the error condition, including a date/time stamp, source procedure and file, user ID of the user for whom the error occurred, etc. Additional information is extracted from the dump via Display or Context commands. The output of each command is appended to the list of previously extracted data. The list of all this formatted dump information is scrollable and printable from the FACT scan screen.

C[ontext] command: Setting program context for data extraction

Information in a SirFact dump is categorized by context within the program that is executing when the error occurs. The "context" is either a complex subroutine or the main body of the executing program. You can switch contexts within the dump file with the Context command. The Display output (described below in D[isplay] command) is sensitive to the context set by the Context command for the values and attributes of %variables, screen items, and image items.

Valid information contexts are the same as those documented for the $Fact_Context function:

* (asterisk) Switches FACT context to the mainline of the executing program.
. (period) Switches to whichever context the program was in at the time of the SirFact error.
subroutine-name Switches to the context of the named complex subroutine. Simple subroutines are not valid contexts, as they share the same context as the main body of the program.

The Context command adds a dividing line to the output list, and any Display information that follows applies to the current context until the context is switched again.

D[isplay] command: Displaying data from the SirFact dump

The Display command requests for specific kinds of data to be extracted from the current context in the SirFact dump.

The Display command specifies a series of data items. It is formatted as follows:

D[isplay] [X.]c[.s] [X.]c[.s] ...

Where:

X An optional flag specifying that the requested data should be displayed in hexadecimal format
c The class of data requested.
s An optional selection pattern for data of class c.

For example:

  • To display global variables beginning with the string STR: DISPLAY G.STR*
  • To display context information (user, job, program, error, etc.): D I
  • To display the value of %b in hexadecimal: D X.%b

The valid c values are described in the following list. They are the same as for the Fact_Data function. All can be abbreviated to a single letter, except for RIN and ROUT, which require two letters. So V.%JUNK is the same as VALUE.%JUNK, and G.X* is the same as GLOBAL.X*.

You can enter the Display command and c values in any case: all non-quoted values are translated to uppercase before being processed.

ATTRIBUTE Attributes of a %variable, image item, or screen item. For %variables, wildcards are not allowed, and the percent character (%) must be present in the variable name (as in A.%I). ATTRIBUTE returns information like variable type, variable length and DP value, and, for object %variables, the object class name.
FIELD Value of one or more fields in active For Each Record loops. FIELD can befollowed by a For Each Record loops nesting level, where 0 is the innermost nesting level, -1 is the next innermost, and so on.

FIELD, or the nesting level, or both, can then be followed by a field name, which can contain wildcards.

The nesting level is only necessary to distinguish like-named fields in different For Each Record loops, though they will be distinguished on display anyway.

Examples of FIELD specifications follow:

FIELD.FOO(3) Returns the value(s) of the third occurrence of field FOO in every active ForEach Record loops
FIELD.0.BAR(*) Returns all occurrences of field BAR in the innermost (active) For Each Record loops
FIELD.-1.* Returns all fields in the second innermost (active) For Each Record loop
FIELD.* Returns all field values in all active For Each Record loops
GLOBAL Value of one or more global variables. Wildcards are allowed.

The selection pattern can be left off, so GLOBAL or G is the same as GLOBAL.*

INFO The following informational entities are available from the dump, displaying values that were in effect at the time the dump was taken.

Although they are displayed by default at the beginning of the FACT subsystem dump output (see the FACT context information figure), you can dynamically request an entity's display by entering at the command prompt the entity name preceded by INFO. (optionally preceded by X.).

Wildcards are allowed for the entities (D INFO.W* returns informational data for the WHAT and WHERE entities); and the selection pattern can be left off entirely, returning information for all the entities for the current context (INFO or I is the same as INFO.*).

Each entity returns one or more informational strings.

ACCOUNT Value of the Model 204 ACCOUNT parameter for the active user.
CALL If applicable, the program location of the active ON unit or active subroutine, one line showing the location of the return point for each outer context.
ERRMSG Error message that provoked the dump.
FILE Name of the file that contains the executing procedure.
FORLEV Nesting level of the active For Each Record loops (0 is innermost, -1 is next innermost, and so on)
JESID For MVS only, the job number assigned the job by the spooling subsystem.
JOBNM The name on the job card.
IODEV Value of the Model 204 IODEV parameter of the active user.
PROC Procedure active when the error occurred.
STEPNM The identifier of the step within the job being executed.
SUBSYS The name of the subsystem within which the error occurred.
TIME The date and time the error occurred.
TERMID Value of the Model 204 TERMID parameter of the active user.
USERID Login user ID.
USERNUM Thread number assigned the user by Model 204.
VERSIONS The Model 204 version, the SirMods version, and the SirFact internal dump format version in effect when the dump was produced.
WHAT General activity category (Model 204 WHAT flag) of user when error occurred.
WHERE Location within the code at which the error occurred.
LIST Value of one or more $list items. LIST must be followed by a %variable that contains the list identifier.

For specific list items, the list identifier can be followed by a parenthesis and an indication of the range of item numbers and columns required.

Example LIST specifications follow:

LIST.%LIST(5)

Returns list item number 5 in the $list identified by %LIST

LIST.%LIST(3-4,10-29)

Returns columns 10 through 29 in items 3 through 4 in a list identified by %LIST

LIST.%LIST(3.2,10.20)

Returns columns 10 through 29 in items 3 through 4 in a list identified by %LIST

If a list identifier is in an array, the array item number must be specified and cannot be a range. For example, to request list item 10 in the list identified by %LISTA(9), use LIST.%LISTA(9)(10).

An asterisk wildcard is not allowed (D LIST.* is not valid). See Additional syntax for VALUE and LIST for the complete syntax used with $lists.

RIN The number of records and some of the record numbers in a found set label.

The count of records in the found set is always returned, and the number of record numbers returnedis the minimum of the number of records in the found set and the SIRFACT RECNDUMP value at the time the dump was taken.

Wildcards are not allowed.

RON The number of records and some of the record numbers on a LIST.

The count of records in the LIST is always returned, and the number of record numbers returned is the minimum of the number of records in the LIST and the SIRFACT RECNDUMP value at the time the dump was taken.

Wildcards are not allowed.

TRACE All or a specified number of the entries in the SirFact wrap-around trace table in CCATEMP (see Trace statement).

TRACE can be followed by the number of entries to return:

T.* and TRACE return all entries in the trace table; and T.20 returns the last 20 entries.
VALUE Value of a %variable, image item, or screen item. For %variables, wildcards are not allowed, and the percent character (%) must be present in the variable name (as in VALUE.%I).

The term VALUE can be left off, so %I is the same as VALUE.%I.

Note:

  • You must know the variable names you are looking for: SirFact cannot process a V.* command to show all variables that exist in a program or within a complex subroutine, because the variable names are not available to the program at runtime in plain text format.
  • Image and Screen variables are not collected until they have been Prepare'd, Identify'd, or Read. If SirFact replies that the specified image or screen variable does - not exist, then it was not referenced at the time of the SirFact dump.

See Additional syntax for VALUE and LIST for additional syntax that can be used for arrays and objects.

After the D command is executed, a separator line is output to the screen, and the output of the command is appended to any previous output. FACT automatically scrolls the screen to the top of the new information.

The returned values from the D command contain the requested data item followed by the value. The class requested is shown in its minimum abbreviated form, except for the VALUE class, which is omitted.

Additional syntax for VALUE and LIST

In addition to simply specifying a %variable in a VALUE or LIST display, there is syntax that can (or must) be used for arrays, structures, $lists, and objects. This section explains that syntax.

Arrays Array variables must be followed (in parentheses) by as many subscript indicators as the dimension of the array. You specify a single digit or a range for each subscript; you can use the following:
  • A hyphen (-), to indicate a range of array elements
  • A period (.), to separate a starting subscript and number of elements
  • An asterisk (*), to indicate all of, or the rest of, a dimension

For example:

  • VALUE.%DATA(11) returns array item 11 in array %DATA
  • VALUE.%DATA(*) returns all array items in array %DATA
  • VALUE.%DATA(5-*) and VALUE.%DATA(5.*) return array items 5 through the last in array %DATA
  • VALUE.%DATA(7-11) and VALUE.%DATA(7.5) return array items 7 through 11 in array %DATA.

These range qualifiers can be used in multiple dimensions as in VALUE.%MULTI(*,6-12,2.3).

$lists $List items use a similar range and item number specification as that used for %variables. Currently you can only display information about $lists whose identifiers are stored in %variables:

D L.%LIST(1-5) D L.%LIST(20.2)

If %LIST is an array of $list identifiers, you must specify the array item number and then the range of values to extract from the list, like this:

D L.%LIST(5)(1-5) D L.%LIST(2)(20.2)

SirFact currently doesn't support range for the array items in this case.

To see only specific columns of $list items, add a second range as in:

D L.%LIST(1-5, 1.20) D L.%LIST(20.2 100-110)

To see the number of $list items, use a single "subscript" of a number sign:

D L.%LIST(#)

For a single $list item, without a column restriction, you can also use a colon and the item numberas a suffix; to see the number of items, you can use the :# suffix. For example, to see item number 3, and to see the number of items:

D L.%LIST:3 D L.%LIST:#

Structures You display the value of structure variables by specifying the name of the variable after the structure. For example, to display the value of structure variable VAR in structure %STRUCT, you can use the following:

D %STRUCT:VAR

If the structure variable is an array, use the array syntax described earlier. For example, the following displays the value of items 7 through 11 in array variable DATA of structure %STRUCT:

D %STRUCT:DATA(7-11)

Objects The format for displaying the contents of a Janus SOAP system or user class member (variable or method) is as follows:

D %object:member[(parms)]

This format is very nearly the same as the format used in a SOUL program to access the objects. Some examples follow:

D %MG:MILEAGE

Displays the value of a (user class) public or private variable: the content of class variable MILEAGE, when %MG is a user class object.

Note: If MILEAGE were a shared variable in class CAR, it could also be displayed by the following command:

D %(CAR):MILEAGE

This use of the class name in parentheses instead of an object variable is valid for system class as well as user class shared variables.

D %RS:COUNT

Displays the value of a system class member: the return from the Count method, when %RS is a Recordset object variable, for example.

D %SL:ITEM(5)

Displays the value of a system class member: the return from the Item method applied to the fifth item, when %SL is a Stringlist object variable, for example.

D %NAMES('Bush'):FIRSTNAME

Displays the value of a (user class) NamedArraylist collection method: the content of the return from the FIRSTNAME method, when %NAMES('Bush') is a NamedArraylist collection item.

D %NAMES('Bush'):LIST:COUNT

Displays the value of strung-together class members: the content of the return from the Count method, when %NAMES('Bush') is a NamedArraylist collection item of a user class, and LIST is a variable that is a Stringlist object.

D %DOC

Displays the value of an object variable: the content of %DOC, when %DOC is an instance of a system XmlDoc object.

The information displayed always includes whether or not the %variable is Null. If the object is not Null, the output from the Print method applied to the object is automatically included (for some classes, such as the Stringlist class or the XmlDoc class). For an XmlNodelist object variable, for example, which has no Print method inits class,the FACT display simply includes whether or not the variable is Null.

As an example, if %l is a Stringlist object, a d %l command might produce:

%l = Not null %l:Print = 'This is a test 1' = 'This is a test 2' = 'This is a test 3'

This example also demonstrates that the SirFact display:

  • Uppercases non-quoted command input before processing (this is adjustable if you are using the SirFact $functions to look at dumps — see $Fact_Option).
  • Quotes the output values but not informational or error messages
  • Uses the "terminal output" form (adding equal signs and quotation marks) for the Print method result and not its normal format.

    This Print output is truncated at 500 lines,

    a limit that is adjustable if you explicitly specify the Print method

    (see the following "Note"), or if you are using the SirFact $functions to look at dumps (see $Fact_Option).

Note: Some methods that produce terminal output (such as most Print methods or, for example, the Janus SOAP

Serial method) can be invoked explicitly in the Display command. For example,if %xmlPier is an XmlDoc object, the following commands provide the same information:

D %xmlPier D %xmlPier:PRINT

Advantages of invoking a Print method explicitly include:

  • You can specify Print method parameters:

    D %XMLPIER:PRINT('/outer/inner')

  • The output is not subject to the 500-line (default) limit of an "implied" Print.

Although object contents can be accessed from SirFact very much the same as they are accessed in SOUL, the following restrictions apply:

  • The special range, count, and wildcard syntaxes supported for some other display types are not supported for objects. For example, to request the display of the first three items in Stringlist %SL, you cannot use D %SL(1-3). You can get the result you want, however, by using Stringlist Print method parameters, as in:

    D %SL:PRINT(,,1,3)

  • Not all system methods may be invoked in a Display command. In general, methods thatupdate an object or that create a new object instance are not allowed. For example, if %SL is a Stringlist object, D %SL:ADD('A new item') is not allowed.

Navigation and display commands

The command descriptions follow:

PFKEYS ON | OFF Toggles the display of the PF key labels.
SCALE ON | OFF Toggles the display of a scale line.
RIGHT n Shifts the display to the right n columns.
LEFT n Shifts the display to the left n columns.
F xxxx or | F /xxxx Finds the string xxxx in the formattted audit trail data, beginning on the current line.
-F | -/ Same as above, but performs the search backwards from the current line.
M (with PF7,8,10,11) Moves the screen to the top, bottom, first column or last, depending upon PF key pressed.
L xxx Moves the current line to the requested line number xxx.

Program function keys

The key descriptions follow:

F1 Display help information for the current screen.
F2 Toggle on/off the horizontal scale.
F3 Exit the current screen and return to the previous screen or menu.
F4 Toggle on/off the display of pfkeys - when pfkeys are not displayed the extra two lines are used to display data.
F7 Scroll back to the previous page.
F8 Scroll forward to the next page.
F9 Repeat the last valid command entered in the command window.
F10 Scroll left.
F11 Scroll right.
F12 Print the extracted data. This key passes the list of retrieved diagnostic data to an internal print routine and presents a print option screen to the user.

FACT Print screen

FACT Print screen

The Print screen allows the user to specify how to route the formatted dump extract to a print device.

To print, enter the following information in the screen fields:

Print from ... to line The starting and ending lines within the SirFact extract to be printed.
Destination The destination of the procedure. Select 1 to output the procedures to the file named in the Dataset DDNAME field, 2 to print to a the printer named in the Printer ID field, and 3 to invoke a USE $PRINT command, to the specified Class and Printer.
Printer ID A valid predefined printer name. If this field is blank or invalid when a 1 is specified in the Destination field, the print comes to the user's terminal.
Dataset DDNAME A valid preallocated sequential file.
$PRINT Class The job class to use for USE $PRINT requests. This job class should be a valid class at your site. USE $PRINT is an obsolete method of printing, and its use is discouraged. If Printer ID is blank or invalid when a USE $PRINT is invoked, the print is routed to PRINTER=LOCAL by Model 204.
with Enter in these two fields any print routing criteria normally placed in the WITH clause of a Use statement (such as COPIES=xx, TAG or ID statements).
Lines Per Page The number of lines to be printed or displayed per page (UDDLPP parameter). The default is 60 lines per page.
Characters per Line The number of characters to be printed or displayed per line (UDDCCC parameter). The default is 133 characters per line.
Record Format The number of characters to be printed or displayed per line (UDDRFM parameter). The default is 133 characters per line.
Header Control Header control settings let you suppress various levels of automatic print headers (HDRCTL parameter).

Function keys active on the Print screen:

F1 Display Help information for the current screen.
F2 Toggle on/off the horizontal scale.
F3 Exit the current screen and return to the previous screen or menu.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=SirFact_FACT_subsystem&oldid=103013"