SirFact $functions - Revision history

Dme: /* Syntax */

2018-12-24T19:03:37Z

Syntax

← Older revision		Revision as of 19:03, 24 December 2018
Line 235:		Line 235:
	</table>		</table>

	The classes and their formats are described in [[SirFact FACT subsystem#~~dispcmd~~\|Display command]]. </li>		The classes and their formats are described in [[SirFact FACT subsystem#dcmd\|Display command]]. </li>

	<li><var class="term">%result</var> is set to indicate the success of the function. The possible return codes are:		<li><var class="term">%result</var> is set to indicate the success of the function. The possible return codes are:

ELowell at 21:21, 24 April 2017

2017-04-24T21:21:27Z

← Older revision		Revision as of 21:21, 24 April 2017
Line 422:		Line 422:

	==<b id="tr2list"></b>$Trace2List: Copy wrap-around trace table to $list==		==<b id="tr2list"></b>$Trace2List: Copy wrap-around trace table to $list==
	The <var>$Trace2List</var> function is used to copy data from the <var class="product">SirFact</var> [[SirFact SOUL statements#~~The~~ Trace statement\|wrap-around trace table]] in CCATEMP to a $list.		The <var>$Trace2List</var> function is used to copy data from the <var class="product">SirFact</var> [[SirFact SOUL statements#Trace statement\|wrap-around trace table]] in CCATEMP to a $list.
	This $function can facilitate use of the wrap-around trace table for interactive debugging.		This $function can facilitate use of the wrap-around trace table for interactive debugging.

JAL: link repair

2016-11-18T22:11:45Z

link repair

← Older revision		Revision as of 22:11, 18 November 2016
Line 62:		Line 62:
	<td>Issues a command that runs on the <var class="product">SirFact</var> sdaemon.</td></tr>		<td>Issues a command that runs on the <var class="product">SirFact</var> sdaemon.</td></tr>

	<tr><th>[[#~~fcntxt~~\|$Fact_Context]]</th>		<tr><th>[[#fcontxt\|$Fact_Context]]</th>
	<td>Sets subroutine context for variable names.</td></tr>		<td>Sets subroutine context for variable names.</td></tr>

	<tr><th>[[#~~factdata~~\|$Fact_Data]]</th>		<tr><th>[[#factdat\|$Fact_Data]]</th>
	<td>Requests error time data from the sdaemon.</td></tr>		<td>Requests error time data from the sdaemon.</td></tr>

JAL: link repair

2016-03-14T15:36:25Z

link repair

← Older revision		Revision as of 15:36, 14 March 2016
Line 360:		Line 360:
	<td>Sets the limit for the number of lines that <var>$Fact_Data</var> can output for the implied Print of an object variable's content. An implied Print is an automatic invocation of the <var>Print</var> method		<td>Sets the limit for the number of lines that <var>$Fact_Data</var> can output for the implied Print of an object variable's content. An implied Print is an automatic invocation of the <var>Print</var> method
	for the display of the content of an object variable, for those object classes for which such printing is enabled.		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 [[~~The~~ FACT subsystem#val\|Additional syntax for VALUE and LIST]].		For more information about implied printing, see the "Objects" discussion in [[SirFact FACT subsystem#val\|Additional syntax for VALUE and LIST]].
	<p>		<p>
	Valid <var>IMPLIM</var> values are numbers between 1 and 99999999. The default is 500.</p></td></tr>		Valid <var>IMPLIM</var> values are numbers between 1 and 99999999. The default is 500.</p></td></tr>

JAL: link repair

2016-03-14T15:31:32Z

link repair

← Older revision		Revision as of 15:31, 14 March 2016
Line 3:		Line 3:
	When a <var class="product">SirFact</var> dump occurs, information from the time of the error		When a <var class="product">SirFact</var> dump occurs, information from the time of the error
	is stored in a dump procedure as specified by the applicable		is stored in a dump procedure as specified by the applicable
	<var>[[~~The~~ SIRFACT command#dump\|SIRFACT DUMP]]</var> command.		<var>[[SIRFACT command#dump\|SIRFACT DUMP]]</var> command.
	This information is		This information is
	binary data that includes the contents of the user's QTBL, STBL,		binary data that includes the contents of the user's QTBL, STBL,

JAL: reduce toc levels

2016-03-02T00:48:59Z

reduce toc levels

← Older revision		Revision as of 00:48, 2 March 2016
Line 1:		Line 1:
			<div class="toclimit-2">
	==Background==		==Background==
	When a <var class="product">SirFact</var> dump occurs, information from the time of the error		When a <var class="product">SirFact</var> dump occurs, information from the time of the error
Line 486:		Line 487:
	==See also==		==See also==
	{{Template: SirFact topic list}}		{{Template: SirFact topic list}}

			</div> <!-- end of div "toclimit-2" -->

	[[Category: SirFact]]		[[Category: SirFact]]

Admin: 1 revision: not all SirFact pages

2016-03-02T00:35:42Z

1 revision: not all SirFact pages

← Older revision	Revision as of 00:35, 2 March 2016
(No difference)

JAL: misc formatting

2016-03-01T22:00:03Z

misc formatting

New page

==Background==
When a <var class="product">SirFact</var> dump occurs, information from the time of the error
is stored in a dump procedure as specified by the applicable
<var>[[The SIRFACT command#dump|SIRFACT DUMP]]</var> 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 <var class="product">SirFact</var> dump into an Online using the <var>[[PROCEDURE command|PROCEDURE]]</var>
command, <var>[[*LOWER command|*LOWER]]</var> must be set. 

<var class="product">SirFact</var> 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 <var class="product">Model 204</var> procedures, which can be easily modified either intentionally
or accidentally.

To detect any modification of the data in a
<var class="product">SirFact</var> 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, <var class="product">SirFact</var> will not return data from the dump, because
all data structures in the dump will be suspect.

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

To use the <var class="product">SirFact</var> $functions to look at a dump,
you must first issue <var>[[#factinit|$Fact_Init]]</var>.
<var>$Fact_Init</var> starts an [[Sdaemons|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:
<ul>
<li>A <var>[[#factdone|$Fact_Done]]</var> is issued.</li>

<li>Another <var>$Fact_Init</var> is issued by the same user.
Only one <var class="product">SirFact</var>
dump can be opened by a single user at any time.</li>

<li>The user that issued the <var>$Fact_Init</var> logs off.</li>

<li>The sdaemon is bumped.</li>
</ul>
A <var class="product">SirFact</var> sdaemon runs under the same user ID and account ID as the invoking user.

After a successful <var>$Fact_Init</var>, the user that invoked the <var>$Fact_Init</var>
communicates with the <var class="product">SirFact</var> sdaemon using these $functions:
<table class="thJustBold">
<tr><th>[[#factcmd|$Fact_Cmd]]</th>
<td>Issues a command that runs on the <var class="product">SirFact</var> sdaemon.</td></tr>

<tr><th>[[#fcntxt|$Fact_Context]]</th>
<td>Sets subroutine context for variable names.</td></tr>

<tr><th>[[#factdata|$Fact_Data]]</th>
<td>Requests error time data from the sdaemon.</td></tr>

<tr><th>[[#factdone|$Fact_Done]]</th>
<td>Tells sdaemon to go away.</td></tr>

<tr><th>[[#factopt|$Fact_Option]]</th>
<td>Sets or gets <var class="product">SirFact</var> display options.</td></tr>

<tr><th>[[#factvname|$Fact_Vname_Width]]</th>
<td>Indicates how many characters to reserve for the variable names in the sdaemon output for <var>$Fact_Data</var>.</td></tr>

<tr><th>[[#tr2list|$Trace2List]]</th>
<td>Copies data from the <var class="product">SirFact</var> wrap-around trace table in CCATEMP to a $list, facilitating use of the wrap-around trace table for interactive debugging.</td></tr>
</table>

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

==CALLing $functions==
You can invoke many $functions using a SOUL <var>Call</var> statement instead of assigning the function
result to a %variable.
For example:
<nowiki>%L = $LISTNEW
$LISTADD(%L, 'Once upon a midnight dreary')
$LISTADD(%L, 'As I pondered weak and weary')
CALL $LIST_PRINT(%L)
</nowiki>

You can <var>Call</var> such $functions and still test for their return code, if necessary.
For example:
<nowiki>CALL $LIST_PRINT(%L)
IF $LIST_PRINT(%L) THEN
</nowiki>

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.
<var>[[$ListCnt]]</var>, for example, is a (non-callable) $function that just returns a value.

==$Fact_Cmd: Run a command on the SirFact sdaemon==
The <var>$Fact_Cmd</var> function is used to run a command on the <var class="product">SirFact</var> sdaemon
and capture the results.
This $function is mainly used for the purpose
of debugging <var class="product">SirFact</var>.
<var>$Fact_Cmd</var> returns the command output to a $list.

<var>$Fact_Cmd</var> accepts two arguments and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Cmd(listid, command)

<ul>
<li><var class="term">listid</var> is the list identifier for the output $list.
Data is appended to the end of this $list.
The $list can be created with the <var>[[$ListNew]]</var> function.
This is a required argument. </li>

<li><var class="term">command</var> is a <var class="product">Model 204</var> command.
The only commands currently allowed are <var>*LOOK</var>, <var>*ZAP</var>, and <var>VIEW</var>. The results
of the <var>VIEW</var> command are the current settings on the <var class="product">SirFact</var>
sdaemon, not the settings at the time of the error for the dump being examined. </li>

<li><var class="term">%result</var> is set to indicate the success of the function. These are the possible return codes:

 0 - All is well, data returned
1 - No active <var class="product">SirFact</var> request
2 - <var class="product">SirFact</var> 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 <var class="product">SirFact</var> SDAEMON
</li>
</ul>

===Example===
The following statement requests the size of QTBL for the <var class="product">SirFact</var> sdaemon:
<nowiki>%rc = $Fact_Cmd(%olist, 'V LQTBL')
</nowiki>

==$Fact_Context: Set subroutine context for $Fact_Data==
The <var>$Fact_Context</var> function is used to set the subroutine context for
value class requests for subsequent <var>$Fact_Data</var> requests.

<var>$Fact_Context</var> accepts one argument and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Context(context)

<ul>
<li><var class="term">context</var> is the name of the complex subroutine to use as the context for subsequent value class <var>$Fact_Data</var> requests.
A period (<tt>.</tt>) indicates the error time context, and an asterisk (<tt>*</tt>) indicates non-subroutines or main program context. </li>

<li><var class="term">%result</var> is set to indicate the success of the function.
These are the possible return codes:
 0 - All is well
1 - No active <var class="product">SirFact</var> request
2 - <var class="product">SirFact</var> SDAEMON no longer around
5 - Required parameter not specified
6 - Context is invalid
255 - Other severe error in <var class="product">SirFact</var> SDAEMON
</li>
</ul>

===Example===
The following statement sets the context for subsequent value class requests for <var>$Fact_Data</var>
to subroutine <code>NASTY.ALGORITHM</code>:
<nowiki>%rc = $Fact_Context('NASTY.ALGORITHM')
</nowiki>

Following are the valid input values to <var>$Fact_Context</var>:
<table class="thJustBold">
<tr><th>* (asterisk)</th>
<td>Switches <code>FACT</code> context to the mainline of the executing program.</td></tr>

<tr><th>. (period)</th>
<td>Switches to whichever context the program was in at the time of the <var class="product">SirFact</var> error.</td></tr>

<tr><th nowrap>subroutine-name</th>
<td>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.</td></tr>
</table>

==$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 <var class="product">SirFact</var> dump to be taken.
There must be a current active dump set up via <var>$Fact_Init</var>.

<var>$Fact_Data</var> returns the value(s) of the requested data to a $list.

<var>$Fact_Data</var> accepts two arguments and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Data(listid, datalist)


<ul>
<li><var class="term">listid</var> is the list identifier for the output $list.
Data is appended to the end of this $list.
The $list can be created with the <var>[[$ListNew]]</var> function.
This is a required argument. </li>

<li><var class="term">datalist</var> 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:
<table class="thJustBold">
<tr><th>X</th>
<td>An optional flag specifying that the requested data should be displayed in hexadecimal format.</td></tr>

<tr><th>c</th>
<td>The class of data requested.</td></tr>

<tr><th>s</th>
<td>An optional selection pattern for data of class <var class="term">c</var>.</td></tr>
</table>

The classes and their formats are described in [[SirFact FACT subsystem#dispcmd|Display command]]. </li>

<li><var class="term">%result</var> is set to indicate the success of the function. The possible return codes are:
 0 - All is well, data returned
1 - No active <var class="product">SirFact</var> request
2 - <var class="product">SirFact</var> 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 <var class="product">SirFact</var> SDAEMON
</li>
</ul>

===Example===
The following statement requests values for all globals that begin with the five characters
<code>USER.</code> and requests the value of screen item <code>%SCR:CMD</code>:
%rc = $Fact_Data(%olist, 'G.USER.* %SCR:CMD')


==$Fact_Done: Terminate a SirFact dump==
The <var>$Fact_Done</var> function is used to terminate the <var class="product">SirFact</var> [[Sdaemons|sdaemon]] being
used to access a dump procedure.

<var>$Fact_Done</var> accepts no arguments and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Done


<var class="term">%result</var> indicates whether the sdaemon had been active.
The possible return codes are:
0 - <var class="product">SirFact</var> sdaemon was not active for user
1 - <var class="product">SirFact</var> sdaemon now terminated


===Example===
The following statement terminates processing of the active <var class="product">SirFact</var> dump:
%rc = $Fact_Done


==$Fact_Init: Open a SirFact dump==
The <var>$Fact_Init</var> function is used to initiate a <var class="product">SirFact</var> [[sdaemons|sdaemon]] and have
it read and load the data from a dump procedure into its own tables.

<var>$Fact_Init</var> accepts three arguments and returns a numeric code.

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


<ul>
<li><var class="term">fgname</var> is the name of the file or group that contains the <var class="product">SirFact</var> dump to be opened.
Any of the words <code>FILE</code>, <code>GROUP</code>,
<code>TEMP GROUP</code>, or <code>PERM GROUP</code> may precede the name to make the context explicit.
The file or group specified must be open with procedure display privileges (<var>CURPRIV</var> X'0200' bit set).
If the first argument is not specified, the compile time context is used.</li>

<li><var class="term">procname</var> is the name of the procedure that contains the dump.
This is a required argument.</li>

<li><var class="term">owidth</var> is the output line width for data being returned
to a $list by <var>$Fact_Data</var> and <var>$Fact_Cmd</var>.
This must be a value between 32 and 4095 inclusive, and it defaults to 255 if not specified.</li>

<li><var class="term">%result</var> is set to indicate the success of the function. The possible return codes are:
 0 - All is well, <var class="product">SirFact</var> 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
</li>
</ul>

===Example===
This statement opens a procedure called <code>DUMP.JUNK.01</code> in file <code>DUMPPROC</code>:
%rc = $Fact_Init('FILE DUMPROC', 'DUMP.JUNK.01')


==$Fact_Option: Set or get SirFact display options==
The <var>$Fact_Option</var> function is used to set or get the values of options
that affect the retrieval and display of <var>$Fact_Data</var> output.

<var>$Fact_Option</var> accepts two arguments and returns a numeric code or a string.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Option(option, value)

<ul>
<li><var class="term">%result</var> is set to indicate the success of the function or the
former value. </li>

<li><var class="term">option</var>, which is required, is the name of the option
that is being updated or retrieved.
Current options are:
<table class="thJustBold">
<tr><th>CASE</th>
<td>Controls whether <var>$Fact_Data</var> internally uppercases all non-quoted characters in its arguments before processing.
Such auto-uppercasing provides case-insensitivity and mimics the way mixed-case <var class="product">SOUL</var> is supported.

Valid <var>CASE</var> values are <var>LEAVE</var> (do not uppercase) and <var>TOUPPER</var>; TOUPPER is the default.
<var>LEAVE</var> is useful for accommodating dumps created from code compiled with
case-sensitive <var class="product">SOUL</var> if case-sensitivity is necessary. Case-sensitive <var class="product">SOUL</var> is enabled by starting a <var class="product">SOUL</var>
program with an all-uppercase <var>BEGIN</var> statement or by specifying the Sirius compiler directive <var>Case Leave</var>.
Note: Formerly, the <code>FACT</code> subsystem uppercased all data passed to <var>$Fact_Data</var> (which processes <code>FACT</code> system <var>DISPLAY</var> commands).
However, this meant that mixed-case method arguments were also uppercased before <var>$Fact_Data</var> processing (for example, <code>d %myXmlDoc:print('/outer/inner')</code>,
became <code>D %MYXMLDOC:PRINT('/OUTER/INNER')</code>.). This <code>FACT</code> subsystem uppercasing was replaced by the <var>$Fact_Data</var> uppercasing
(which correctly processes the example command as <code>D %MYXMLDOC:PRINT('/outer/inner')</code>). 

The option to change the default case handling is not available to <code>FACT</code> subsystem users.</td></tr>

<tr><th>IMPLIM</th>
<td>Sets the limit for the number of lines that <var>$Fact_Data</var> can output for the implied Print of an object variable's content. An implied Print is an automatic invocation of the <var>Print</var> 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 [[The FACT subsystem#val|Additional syntax for VALUE and LIST]].

Valid <var>IMPLIM</var> values are numbers between 1 and 99999999. The default is 500.</td></tr>
</table> </li>

<li><var class="term">value</var> 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
<var>$Fact_Option</var> return depends on whether you are changing <var>CASE</var> or <var>IMPLIM</var>:
<ul>
<li>If <var>CASE</var> is changed successfully, the return code is 0. </li>
<li>If <var>IMPLIM</var> is changed, the return is the previous value of <var>IMPLIM</var>. </li>
</ul> </li>
</ul>

===Examples===
Examples of valid <var>$Fact_Option</var> 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 <var>$Fact_Vname_Width</var> function is used to set the space allocated
for variable names in <var>$Fact_Data</var> output.

<var>$Fact_Vname_Width</var> accepts one argument and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Fact_Vname_Width(vwidth)


<ul>
<li><var class="term">vwidth</var> is a required parameter that is the width of the output space for variable names
for subsequent <var>$Fact_Data</var> requests.

The value specified must be between these values: 
<ul>
<li>8</li>
<li>The output line width implied or specified on <var>$Fact_Init</var>, minus 11.</li>
</ul></li>

<li><var class="term">%result</var> is set to indicate the success of the function.
The possible return codes are:
 0 - All is well
1 - No active <var class="product">SirFact</var> request
2 - <var class="product">SirFact</var> SDAEMON no longer around
6 - Width is invalid
</li>
</ul>

===Example===
The following statement sets the space for variable names for
subsequent $Fact_Data requests to 33 characters:
<nowiki>%RC = $Fact_Vname_Width(33)
</nowiki>

==$Trace2List: Copy wrap-around trace table to $list==
The <var>$Trace2List</var> function is used to copy data from the <var class="product">SirFact</var> [[SirFact SOUL statements#The Trace statement|wrap-around trace table]] in CCATEMP to a $list.
This $function can facilitate use of the wrap-around trace table for interactive debugging.

<var>$Trace2List</var> accepts two arguments and returns a numeric code.
It is also [[#callfun|callable]].

===Syntax===
%result = $Trace2List(listid, parms)

<ul>
<li><var class="term">%result</var> is set to indicate the number of items added to the $list.
All errors result in request cancellation.</li>

<li><var class="term">listid</var> is the list identifier for the output $list.
Data is appended to the end of this $list.
The $list can be created with the <var>[[$ListNew]]</var> function.
This is a required argument.</li>

<li><var class="term">parms</var> is a blank-delimited set of options.
Valid options are:
<table class="thJustBold">
<tr><th>CLEAR</th>
<td>Causes <var>$Trace2List</var> to delete all the data in the wrap-around trace table after extracting it. By default, <var>$Trace2List</var> leaves the wrap-around trace table intact.</td></tr>

<tr><th>CONT</th>
<td>Indicates that when <var>$Trace2List</var> has to split a line onto multiple $list items (because the width indicated by the <var>WIDTH</var> parameter is exceeded),
it will end each continued line with a hyphen (<tt>-</tt>) character. By default, <var>$Trace2List</var> does not place a hyphen at the end of continued lines.</td></tr>

<tr><th>DATE</th>
<td>Include date of trace entries in the output $list. By default, only the time of the entries is included.</td></tr>

<tr><th>MAXREC</th>
<td>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.</td></tr>

<tr><th>NOTIME</th>
<td>Do not include the trace entry time stamps in the output $list. By default, the time stamps are included.</td></tr>

<tr><th>WIDTH</th>
<td>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 <var>[[$List_MaxIL]]</var>.

This parameter is useful to force <var>$Trace2List</var> to format the trace entries to fit on the debugging user's screen.</td></tr>

<tr><th>WORD</th>
<td>Indicates that when <var>$Trace2List</var> has to split a line onto multiple $list items (because the width indicated by the <var>WIDTH</var> parameter is exceeded), it will attempt to split lines so as not to split a word onto multiple lines.
That is, <var>WORD</var> means to split lines at blanks.

Extremely long words can still result in mid-word line continuation even if <var>WORD</var> is specified. By default, <var>$Trace2List</var> splits a line at the maximum output line width, whether the split is in mid-word or not.</td></tr>
</table></li>
</ul>

It is permissible to not specify an output $list ID, if and only if the <var>CLEAR</var> parameter is specified.
Specifying the <var>CLEAR</var> 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 <var>DATE</var> and <var>NOTIME</var> parameters.

===Example===
The following statement retrieves the last 100 entries in the wrap-around trace table to the
$list identified by <code>%olist</code>, and then it clears the wrap-around trace table.
%rc = $Trace2List(%olist, 'MAXREC 100 CLEAR')


==See also==
{{Template: SirFact topic list}}

[[Category: SirFact]]