SirFact $functions

Background

When a SirFact dump occurs, information from the time of the error is stored in a dump procedure as specified by the applicable SIRFACT DUMP command. This information is binary data that includes the contents of the user's QTBL, STBL, VTBL, GTBL, NTBL, $lists, and several other user-specific structures.

To simplify the movement of data to other regions, the data is base64-encoded. Base64-encoding is a means of storing binary data by using only 64 displayable characters.

Note: Base64-encoding does use lowercase characters, however, so to load a SirFact dump into an Online using the PROCEDURE command, *LOWER must be set.

SirFact dumps contain binary data for data structures that are interrelated in fairly complex ways. Modification of the data in these dumps, no matter how slight, could cause severe problems in analyzing the dump. Yet, the dumps are in Model 204 procedures, which can be easily modified either intentionally or accidentally.

To detect any modification of the data in a SirFact dump, all dumps contain a 16-byte checksum (really an MD5 digest) of the contents of the dump. Any modification of the data in a dump will be detected because of a mismatch between the checksum in the dump and that calculated from the data. If such a mismatch is detected when the dump is read, SirFact will not return data from the dump, because all data structures in the dump will be suspect.

Using SirFact $functions

SirFact provides a set of $functions that can be used to analyze a dump. These $functions are used by the FACT subsystem to provide a user interface for reading dumps. It is not necessary to explicitly use these $functions to analyze SirFact dumps, yet documentation for these $functions is provided in case you want to write a different user interface to SirFact dumps, perhaps one that takes advantage of site-specific facilities or standards.

To use the SirFact $functions to look at a dump, you must first issue $Fact_Init. $Fact_Init starts an sdaemon, which then tries to read the dump procedure. If the dump procedure looks alright (it has the correct format and the checksum is correct), this sdaemon loads the data at the time of error into its own tables (and into CCATEMP where appropriate). Once the dump is loaded, this sdaemon remains logged on until one of the following events:

• A $Fact_Done is issued.
• Another $Fact_Init is issued by the same user. Only one SirFact dump can be opened by a single user at any time.
• The user that issued the $Fact_Init logs off.
• The sdaemon is bumped.

A SirFact sdaemon runs under the same user ID and account ID as the invoking user.

After a successful $Fact_Init, the user that invoked the $Fact_Init communicates with the SirFact sdaemon using these $functions:

$Fact_Cmd	Issues a command that runs on the SirFact sdaemon.
$Fact_Context	Sets subroutine context for variable names.
$Fact_Data	Requests error time data from the sdaemon.
$Fact_Done	Tells sdaemon to go away.
$Fact_Option	Sets or gets SirFact display options.
$Fact_Vname_Width	Indicates how many characters to reserve for the variable names in the sdaemon output for $Fact_Data.
$Trace2List	Copies data from the SirFact wrap-around trace table in CCATEMP to a $list, facilitating use of the wrap-around trace table for interactive debugging.

$Fact_Cmd and $Fact_Data return data into $lists. The functions to create and manipulate $lists begin with List and are shown on the List of $functions page. SirFact customers are automatically authorized to use all the base $list functions (and many more). In fact, SirFact customers can use these functions in applications that have nothing to do with SirFact or any other Rocket Model 204 product.

CALLing $functions

You can invoke many $functions using a SOUL Call statement instead of assigning the function result to a %variable. For example:

%L = $LISTNEW $LISTADD(%L, 'Once upon a midnight dreary') $LISTADD(%L, 'As I pondered weak and weary') CALL $LIST_PRINT(%L)

You can Call such $functions and still test for their return code, if necessary. For example:

CALL $LIST_PRINT(%L) IF $LIST_PRINT(%L) THEN

This "callability" is an optional approach; it does not replace %variable assignment.

The callable $functions are indicated as such in their individual function descriptions in this document. Typically they are $functions that do more than simply return a value, and the value they return is primarily an indicator of whether the function completed successfully. $ListCnt, for example, is a (non-callable) $function that just returns a value.

$Fact_Cmd: Run a command on the SirFact sdaemon

The $Fact_Cmd function is used to run a command on the SirFact sdaemon and capture the results. This $function is mainly used for the purpose of debugging SirFact. $Fact_Cmd returns the command output to a $list.

$Fact_Cmd accepts two arguments and returns a numeric code. It is also callable.

Syntax

%result = $Fact_Cmd(listid, command)

• listid is the list identifier for the output $list. Data is appended to the end of this $list. The $list can be created with the $ListNew function. This is a required argument.
• command is a Model 204 command. The only commands currently allowed are *LOOK, *ZAP, and VIEW. The results of the VIEW command are the current settings on the SirFact sdaemon, not the settings at the time of the error for the dump being examined.
• %result is set to indicate the success of the function. These are the possible return codes:

  0 - All is well, data returned 1 - No active SirFact request 2 - SirFact SDAEMON no longer around 3 - Out of CCATEMP 4 - $list limit exceeded 5 - Required parameter not specified 6 - Invalid list-identifier 7 - Invalid command 255 - Other severe error in SirFact SDAEMON

Example

The following statement requests the size of QTBL for the SirFact sdaemon:

%rc = $Fact_Cmd(%olist, 'V LQTBL')

$Fact_Context: Set subroutine context for $Fact_Data

The $Fact_Context function is used to set the subroutine context for value class requests for subsequent $Fact_Data requests.

$Fact_Context accepts one argument and returns a numeric code. It is also callable.

Syntax

%result = $Fact_Context(context)

• context is the name of the complex subroutine to use as the context for subsequent value class $Fact_Data requests. A period (.) indicates the error time context, and an asterisk (*) indicates non-subroutines or main program context.
• %result is set to indicate the success of the function. These are the possible return codes:

  0 - All is well 1 - No active SirFact request 2 - SirFact SDAEMON no longer around 5 - Required parameter not specified 6 - Context is invalid 255 - Other severe error in SirFact SDAEMON

Example

The following statement sets the context for subsequent value class requests for $Fact_Data to subroutine NASTY.ALGORITHM:

%rc = $Fact_Context('NASTY.ALGORITHM')

Following are the valid input values to $Fact_Context:

* (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.

$Fact_Data: Retrieve data from a SirFact dump

The $Fact_Data function is used to retrieve data about the environment of the error that caused the currently open SirFact dump to be taken. There must be a current active dump set up via $Fact_Init.

$Fact_Data returns the value(s) of the requested data to a $list.

$Fact_Data accepts two arguments and returns a numeric code. It is also callable.

Syntax

%result = $Fact_Data(listid, datalist)

• listid is the list identifier for the output $list. Data is appended to the end of this $list. The $list can be created with the $ListNew function. This is a required argument.
• datalist is a blank-delimited list of data items whose values are to be returned to the $list. The format of each data item is:

  [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.

  The classes and their formats are described in Display command.
• %result is set to indicate the success of the function. The possible return codes are:

  0 - All is well, data returned 1 - No active SirFact request 2 - SirFact SDAEMON no longer around 3 - Out of CCATEMP 4 - $list limit exceeded 5 - Required parameter not specified 6 - Invalid list-identifier 255 - Other severe error in SirFact SDAEMON

Example

The following statement requests values for all globals that begin with the five characters USER. and requests the value of screen item %SCR:CMD:

%rc = $Fact_Data(%olist, 'G.USER.* %SCR:CMD')

$Fact_Done: Terminate a SirFact dump

The $Fact_Done function is used to terminate the SirFact sdaemon being used to access a dump procedure.

$Fact_Done accepts no arguments and returns a numeric code. It is also callable.

Syntax

%result = $Fact_Done

%result indicates whether the sdaemon had been active.

The possible return codes are:

0 - SirFact sdaemon was not active for user 1 - SirFact sdaemon now terminated

Example

The following statement terminates processing of the active SirFact dump:

%rc = $Fact_Done

$Fact_Init: Open a SirFact dump

The $Fact_Init function is used to initiate a SirFact sdaemon and have it read and load the data from a dump procedure into its own tables.

$Fact_Init accepts three arguments and returns a numeric code.

Syntax

%result = $Fact_Init(fgname, procname, owidth)

• fgname is the name of the file or group that contains the SirFact dump to be opened. Any of the words FILE, GROUP, TEMP GROUP, or PERM GROUP may precede the name to make the context explicit. The file or group specified must be open with procedure display privileges (CURPRIV X'0200' bit set). If the first argument is not specified, the compile time context is used.
• procname is the name of the procedure that contains the dump. This is a required argument.
• owidth is the output line width for data being returned to a $list by $Fact_Data and $Fact_Cmd. This must be a value between 32 and 4095 inclusive, and it defaults to 255 if not specified.
• %result is set to indicate the success of the function. The possible return codes are:

  0 - All is well, SirFact sdaemon set up 1 - Dump file is not open 2 - Insufficient privilege to open proc 3 - Dump proc name missing or proc not found 4 - Proc is enqueued exclusive 5 - Invalid line width (arg 3) 6 - Insufficient virtual storage 7 - No sdaemons available 8 - Not a valid dump proc 9 - Backward compatibility problem 10 - Forward compatibility problem 11 - Model 204 release compatibility problem 12 - Can't get table sizes 255 - Severe error in SirFact sdaemon

Example

This statement opens a procedure called DUMP.JUNK.01 in file DUMPPROC:

%rc = $Fact_Init('FILE DUMPROC', 'DUMP.JUNK.01')

$Fact_Option: Set or get SirFact display options

The $Fact_Option function is used to set or get the values of options that affect the retrieval and display of $Fact_Data output.

$Fact_Option accepts two arguments and returns a numeric code or a string. It is also callable.

Syntax

%result = $Fact_Option(option, value)

• %result is set to indicate the success of the function or the former value.
• option, which is required, is the name of the option that is being updated or retrieved. Current options are:

  CASE

  Controls whether $Fact_Data internally uppercases all non-quoted characters in its arguments before processing. Such auto-uppercasing provides case-insensitivity and mimics the way mixed-case SOUL is supported. Valid CASE values are LEAVE (do not uppercase) and TOUPPER; TOUPPER is the default. LEAVE is useful for accommodating dumps created from code compiled with case-sensitive SOUL if case-sensitivity is necessary. Case-sensitive SOUL is enabled by starting a SOUL program with an all-uppercase BEGIN statement or by specifying the Sirius compiler directive Case Leave. Note: Formerly, the FACT subsystem uppercased all data passed to $Fact_Data (which processes FACT system DISPLAY commands). However, this meant that mixed-case method arguments were also uppercased before $Fact_Data processing (for example, d %myXmlDoc:print('/outer/inner'), became D %MYXMLDOC:PRINT('/OUTER/INNER').). This FACT subsystem uppercasing was replaced by the $Fact_Data uppercasing (which correctly processes the example command as D %MYXMLDOC:PRINT('/outer/inner')). The option to change the default case handling is not available to FACT subsystem users.

  IMPLIM

  Sets the limit for the number of lines that $Fact_Data can output for the implied Print of an object variable's content. An implied Print is an automatic invocation of the Print method for the display of the content of an object variable, for those object classes for which such printing is enabled. For more information about implied printing, see the "Objects" discussion in Additional syntax for VALUE and LIST. Valid IMPLIM values are numbers between 1 and 99999999. The default is 500.

• value is an optional new value for the option you specify as the first argument. If you specify a value for this parameter that changes the current setting of the first parameter, the $Fact_Option return depends on whether you are changing CASE or IMPLIM:
  • If CASE is changed successfully, the return code is 0.
  • If IMPLIM is changed, the return is the previous value of IMPLIM.

Examples

Examples of valid $Fact_Option statements follow:

$Fact_Option('CASE', 'LEAVE') print $Fact_Option('CASE') %oldLimit = $Fact_Option('IMPLIM', %newLimit) $Fact_Option('IMPLIM', 2)

$Fact_Vname_Width: Sets variable name width for $Fact_Data

The $Fact_Vname_Width function is used to set the space allocated for variable names in $Fact_Data output.

$Fact_Vname_Width accepts one argument and returns a numeric code. It is also callable.

Syntax

%result = $Fact_Vname_Width(vwidth)

• vwidth is a required parameter that is the width of the output space for variable names for subsequent $Fact_Data requests.

  The value specified must be between these values:

  • 8
  • The output line width implied or specified on $Fact_Init, minus 11.
• %result is set to indicate the success of the function. The possible return codes are:

  0 - All is well 1 - No active SirFact request 2 - SirFact SDAEMON no longer around 6 - Width is invalid

Example

The following statement sets the space for variable names for subsequent $Fact_Data requests to 33 characters:

%RC = $Fact_Vname_Width(33)

$Trace2List: Copy wrap-around trace table to $list

The $Trace2List function is used to copy data from the SirFact wrap-around trace table in CCATEMP to a $list. This $function can facilitate use of the wrap-around trace table for interactive debugging.

$Trace2List accepts two arguments and returns a numeric code. It is also callable.

Syntax

%result = $Trace2List(listid, parms)

• %result is set to indicate the number of items added to the $list. All errors result in request cancellation.
• listid is the list identifier for the output $list. Data is appended to the end of this $list. The $list can be created with the $ListNew function. This is a required argument.
• parms is a blank-delimited set of options. Valid options are:

  CLEAR	Causes $Trace2List to delete all the data in the wrap-around trace table after extracting it. By default, $Trace2List leaves the wrap-around trace table intact.
  CONT	Indicates that when $Trace2List has to split a line onto multiple $list items (because the width indicated by the WIDTH parameter is exceeded), it will end each continued line with a hyphen (-) character. By default, $Trace2List does not place a hyphen at the end of continued lines.
  DATE	Include date of trace entries in the output $list. By default, only the time of the entries is included.
  MAXREC	This must be followed by an integer value. It indicates the maximum number of trace entries to return. By default, all trace entries in the trace table are returned.
  NOTIME	Do not include the trace entry time stamps in the output $list. By default, the time stamps are included.
  WIDTH	This must be followed by an integer value. It indicates the width of the output data in the output $list. By default, the output width is the maximum length of a $list item, that is, the value returned by $List_MaxIL. This parameter is useful to force $Trace2List to format the trace entries to fit on the debugging user's screen.
  WORD	Indicates that when $Trace2List has to split a line onto multiple $list items (because the width indicated by the WIDTH parameter is exceeded), it will attempt to split lines so as not to split a word onto multiple lines. That is, WORD means to split lines at blanks. Extremely long words can still result in mid-word line continuation even if WORD is specified. By default, $Trace2List splits a line at the maximum output line width, whether the split is in mid-word or not.

It is permissible to not specify an output $list ID, if and only if the CLEAR parameter is specified. Specifying the CLEAR parameter with no output $list ID is the most efficient way to clear the wrap-around trace table if the current contents are not required. Setting the output $list ID to zero is the same as not specifying that argument.

It is not permissible to specify both the DATE and NOTIME parameters.

Example

The following statement retrieves the last 100 entries in the wrap-around trace table to the $list identified by %olist, and then it clears the wrap-around trace table.

%rc = $Trace2List(%olist, 'MAXREC 100 CLEAR')

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