SirScan scan specification: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision: SirScan doc from m204stage)
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!-- Page name: SirScan scan specification-->
Installation of <var class="product">SirScan</var> is described in [[RKTools installation]].
Installation of <var class="product">SirScan</var> is described in the [[UL/SPF installation guide]].
<var class="product">SirScan</var> should be installed as a [[Application Subsystem development#Security options|private Application Subsystem]] in order to use the I/O limits assigned to each [[SCLASS]].
<var class="product">SirScan</var> should be installed as a private APSY subsystem
in order to use the I/O limits assigned to each SCLASS.
To access the system, enter
<code>SIRSCAN</code> (or the name of the subsystem you have installed)
on the <var class="product">Model 204</var> command line.
A scan specification screen is presented:


<p class="caption">Journal Scan Criteria screen</p>
To access the system, enter <code>SIRSCAN</code> (or the name of the subsystem you have installed) on the <var class="product">Model&nbsp;204</var> command line.
You are presented with a scan specification screen, which lets you specify the journal data to be retrieved and the format in which it should be displayed.


This screen allows the user to specify the journal data to be retrieved
In [[RKWeb]], selecting the <code>Monitor > Journal Scan</code> option displays an equivalent menu.  
and the format in which it should be displayed.
Input fields are:
<table class="thJustBold">
<tr><th>Start Time</th>
<td>Formatted <b>HH:MM:SS</b>.or <b>-MMMMMM</b>. The earliest audit trail entry to be formatted. The second syntax identifies the number of minutes to go back from the current time to begin formatting the journal.
If <b>Start</b> Time is not specified, data is formatted from the start of the run or the oldest ring journal (if using ring journals) if the requesting user is a system manager (or is in one of the ADMIN SCLASSes).
Otherwise data is formatted from the logon time of the requesting user.</td></tr>


<tr><th>Start Date</th>
<p class="caption" style="width:430px">Journal scan criteria screen</p>
<td>Formatted <b>YY/MM/DD</b>. The date of the earliest audit trail entry to be formatted.
<p class="figure">[[File:ScanCriteria.png|430px]]</p>
If this is not specified, it is determined based on the start time. If the start time is less than the current time the current date is used, otherwise yesterday's date is used.</td></tr>


<tr><th>Interval</th>
==Screen input fields==
<td>Valid formats are <b>MM:SS, HH:MM:SS</b> or <b>MMMMMMM</b>, where <code>H</code> is hours, <code>M</code> is minutes, and <code>S</code> is seconds.
<table class="thJustBold">
If an interval is not specified, data is formatted up to the current time (or until I/O limits are hit). In addition, by leaving this time blank, <var class="product">SirScan</var> runs in auto-refresh mode
([[SirScan browsing of the journal#autoref|Auto-refresh mode]]) so that the data being scanned is constantly refreshed to reflect any new audit trail data that was generated after the initial data was collected.</td></tr>


<tr><th>User</th>
<tr><th>Users</th>
<td>Users to be included in the formatted output. This input field indicates which thread's/user's audit entries will be viewed.
<td>Users to be included in the formatted output. This input field indicates which thread's/user's audit entries will be viewed.
The selection criteria can be a set of blank or comma delimited "phrases," each made up of one or more "clauses" separated by the ampersand (<code>&amp.</code>) symbol. Each clause can contain one of the following criteria:
The selection criteria can be a set of blank or comma delimited "phrases," each made up of one or more "clauses" separated by the ampersand (<code>&amp;</code>) symbol. Each clause can contain one of the following criteria:
<table>
<table>
<tr><th><var>IODEV</var><i>n</i></th>
<tr><th><var>IODEV</var><i>n</i></th>
Line 37: Line 22:


<tr><th><var>PST</var></th>
<tr><th><var>PST</var></th>
<td>Entries for all <var class="product">Model 204</var> Psuedo-SubTasks.</td></tr>
<td>Entries for all <var class="product">Model&nbsp;204</var> [[Controlling_system_operations_(CCAIN)#Pseudo_subtasks|Psuedo-SubTasks]].</td></tr>


<tr><th>n1.n2.n3.n4</th>
<tr><th><i>n1</i>.<i>n2</i>.<i>n3</i>.<i>n4</i></th>
<td>An IP address for a Janus thread,
<td>An IP address for a [[Janus TCP/IP Base#The Janus family|Janus]] thread, as in <code>198.242.244.97</code> or <code>150.209.8.51</code>. The IP address can also be followed by a slash (<tt>/</tt>) and a subnet mask, or by a hyphen (<tt>-</tt>) and a number of bits in a subnet mask, as in <code>98.242.244.0/255.255.255.0</code> or <code>198.242.244.0-24</code>.
as in <code>198.242.244.97</code> or <code>150.209.8.51</code>.
The IP address can also be followedby a slash (<tt>/</tt>) and a subnet mask, or by a hyphen (<tt>-</tt>) and a number of bits in a subnet mask, as in 1<code>98.242.244.0/255.255.255.0</code> or <code>198.242.244.0-24</code>.
These two subnetted IP addresses encompass the same set of IP addresses.</td></tr>
These two subnetted IP addresses encompass the same set of IP addresses.</td></tr>


<tr><th><var>JAN</var>:sss</th>
<tr><th><var>JAN</var>:<i>sss</i></th>
<td>The name of a Janus port, possibly containing wildcards, as in <code>JAN:WEBPORT</code>, <code>JAN:WEB*</code>, or <code>JAN:???PORT</code>.</td></tr>
<td>The name of a Janus port, possibly containing wildcards, as in <code>JAN:WEBPORT</code>, <code>JAN:WEB*</code>, or <code>JAN:???PORT</code>.</td></tr>


<tr><th>xxx</th>
<tr><th><i>xxx</i></th>
<td>A specific user number, as in <code>0</code>, <code>233</code>, or <code>1024</code>.</td></tr>
<td>A specific user number, as in <code>0</code>, <code>233</code>, or <code>1024</code>.</td></tr>


<tr><th>xxx-yyy</th>
<tr><th><i>xxx</i>-<i>yyy</i></th>
<td>A range of user numbers, as in <code>0-20</code> or <code>111-1000</code>.</td></tr>
<td>A range of user numbers, as in <code>0-20</code> or <code>111-1000</code>.</td></tr>


<tr><th>ssss</th>
<tr><th><i>ssss</i></th>
<td>A string, possibly containing wildcards, that indicates a specific userid, as in <code>RASPUTIN</code>, <code>RAS*</code>, <code>???PUTIN</code>.
<td>A string, possibly containing wildcards, that indicates a specific userid, as in <code>RASPUTIN</code>, <code>RAS*</code>, <code>???PUTIN</code>.
For users in the ADMIN_xxx SCLASSes, a userid of just an asterisk (<tt>*</tt>) is special-cased to mean not only all logged-on users, but all threads, whether logged on or not.</td></tr>
For users in the ADMIN_xxx SCLASSes, a user ID of just an asterisk (<tt>*</tt>) is special-cased to mean not only all logged-on users, but all threads, whether logged on or not.</td></tr>
</table>
</table>
<p>
<p>
Criteria can be mixed and matched using the <code>&amp.</code> separator, which indicates an "And" operation, or using blanks or commas, which indicate an "Or" operation. For example, the following string
Criteria can be mixed and matched using the <code>&amp;</code> separator, which indicates an "And" operation, or using blanks or commas, which indicate an "Or" operation. For example, the following string
requests information for all <var>IODEV</var> 15 threads logged on as userid <code>LENIN</code>, and requests all the information for user numbers 11 through 20:</p>
requests information for all <var>IODEV</var> 15 threads logged on as userid <code>LENIN</code>, and requests all the information for user numbers 11 through 20:</p>
<p class="code"><nowiki>IODEV15&amp.LENIN 11-20
<p class="code"><nowiki>IODEV15&amp;LENIN 11-20
</nowiki></p>
</nowiki></p>
<p>And this:</p>
<p>
And this:</p>
<p class="code"><nowiki>TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST
<p class="code"><nowiki>TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST
</nowiki></p>
</nowiki></p>
<p>requests information for all of the following:</p>
<p>
requests information for all of the following:</p>
<ul>
<ul>
<li>All connections from IP address 198.242.244.33 that log on a userid that begins with <code>TROT</code></li>
<li>All connections from IP address 198.242.244.33 that log on a userid that begins with <code>TROT</code></li>
Line 73: Line 58:
</ul>
</ul>
<p>
<p>
Portnames and userids can contain special wildcard characters. These characters and their meanings are:</p>
Port names and user IDs can contain special wildcard characters. These characters and their meanings are:</p>
<table class="thJustBold">
<table class="thJustBold">
<tr><th>*</th>
<tr><th>*</th>
Line 79: Line 64:


<tr><th>?</th>
<tr><th>?</th>
<td>Matches a single character. For example, <code>?RUSHCHEV</code> matches <code>TRUSHCHEV</code>,<code>BRUSHCHE</code>V, and <code>KRUSHCHEV</code>.</td></tr>
<td>Matches a single character. For example, <code>?RUSHCHEV</code> matches <code>TRUSHCHEV</code>, <code>BRUSHCHE</code>V, and <code>KRUSHCHEV</code>.</td></tr>


<tr><th>"</th>
<tr><th>"</th>
Line 86: Line 71:
</table>
</table>
<p>
<p>
Users in <var>USER_HI</var>, <var>USER_MED</var> or <var>USER_LO</var> SCLASSes, no matter what selection criteria are specified, are only able to view audit entries associated with their own userid or, if the system <var>SCANPARM</var> 1 bit is set,
Users in <var>USER_HI</var>, <var>USER_MED</var> or <var>USER_LO</var> SCLASSes, no matter what selection criteria are specified, are only able to view audit entries associated with their own user ID or, if the system <var>[[SCANPARM parameter|SCANPARM]]</var> 1 bit is set,
entries for public logins on Janus Web threads.
entries for public logins on [[Janus Web Server]] threads.
So if a user in the <var>USER_MED</var> SCLASS specifies the following for a selection criterion:  </p>
So if a user in the <var>USER_MED</var> SCLASS specifies the following for a selection criterion:  </p>
<p class="code"><nowiki>IODEV15
<p class="code">IODEV15
</nowiki></p>
</p>
<p>
<p>
The user will be able to see only <var>IODEV</var> 15 activity for her own userid or perhaps for public logins to a Janus Web thread (if the <var>SCANPARM</var> 1 bit is set).</p>
You are able to see only <var>IODEV</var> 15 activity for your own user ID or perhaps for public logins to a Janus Web thread (if the <var>SCANPARM</var> 1 bit is set).</p>
<p>
<p>
Because the specified time interval may not include the journal entries that would allow <var class="product">SirScan</var> to associate a thread's activity with a particular userid, IP address, or port number, it
Because the specified time interval may not include the journal entries that would allow <var class="product">SirScan</var> to associate a thread's activity with a particular user ID, IP address, or port number, it is possible that entries associated with a particular user ID, IP address, or port number will not be formatted.
is possible that entries associated with a particular userid, IP address, or port number will not be formatted.
It is also possible that many entries in a time interval for a requested user ID, IP address, or port number will not be formatted, but those after an audit entry that allows determination of all these entities
It is also possible that many entries in a time interval for a requested userid, IP address, or port number will not be formatted, but those after an audit entry that allows determination of all these entities
(a since-last statistic or a <var class="product">SirScan</var> RK line), will be.</p>
(a since-last statistic or a <var class="product">SirScan</var> RK line), will be.</p>
<p><var class="product">SirScan</var> makes every effort to use all available information (current logged on userids and log times, M204.0352 messages, M204.0118 messages, since-last stat entries, etc.)
<p>
<var class="product">SirScan</var> makes every effort to use all available information (current logged on userids and log times, M204.0352 messages, M204.0118 messages, since-last stat entries, etc.)
to ascertain this information about each audit trail entry, but these attempts are necessarily hit and miss: While most of the time, <var class="product">SirScan</var> will pick up the desired information,
to ascertain this information about each audit trail entry, but these attempts are necessarily hit and miss: While most of the time, <var class="product">SirScan</var> will pick up the desired information,
it is possible that information will also seem to be inexplicably missing. Often this information can still be retrieved by varying the date/time interval.</p>
it is possible that information will also seem to be inexplicably missing. Often this information can still be retrieved by varying the date/time interval.</p>
Line 105: Line 90:
<var class="product">SirScan</var>s behavior can be made completely consistent and predictable at a (hopefully slight) cost.</p>
<var class="product">SirScan</var>s behavior can be made completely consistent and predictable at a (hopefully slight) cost.</p>
<p>
<p>
If no criteria are specified for <b>USER</b>, only audit entries for the requesting user are displayed.</p>
If no criteria are specified for <b>Users</b>, only audit entries for the requesting user are displayed.
<p class="note"> <b>Note:</b> that one additional selection criterion is applied to any <b>USER</b> phrase if
</p>
<var class="product">SirScan</var> has not been purchased but instead is automatically authorized by <var class="product">Limited Janus Web Server</var>.
<blockquote class="note">
<var class="product">Limited Janus Web Server</var> is a free, restricted version of <var class="product">Janus Web Server</var>; they are both documented in
<p><b>Note:</b> One additional selection criterion is applied to any <b>Users</b> phrase if <var class="product">SirScan</var> has not been purchased but instead is automatically authorized by <var class="product">Limited Janus Web Server</var>. <var class="product">Limited Janus Web Server</var> is a free, restricted version of <var class="product">Janus Web Server</var>; they are both documented in [[Janus Web Server]]. </p>
[[Janus Web Server]]. To assist in web development,
<p>
sites that don't already have <var class="product">SirScan</var> can use it for free if they are using <var class="product">Limited Janus Web Server</var>.
To assist in web development, sites that don't already have <var class="product">SirScan</var> can use it for free if they are using <var class="product">Limited Janus Web Server</var>. Sites using <var class="product">SirScan</var> for free are automatically limited to viewing the journal activity of Janus Web threads and the TCP/IP subtask; any <b>Users</b> selection will thus be automatically restricted.</p>
Sites using <var class="product">SirScan</var> for free are automatically limited to viewing the journal activity of Janus Web threads and the TCP/IP subtask; any <b>USER</b> selection will thus be automatically restricted.</p>
<p>
You may, of course, upgrade to a full <var class="product">SirScan</var> at any time.</p>
</blockquote></td></tr>
 
<tr><th>Start time</th>
<td>The earliest audit trail entry to be formatted. Formatted <i>HH</i>:<i>MM</i>:<i>SS</i>, <i>HHMMSS</i>, or <i>HH</i>.<i>MM</i>.<i>SS</i> (as of version 7.5), or -<i>MMMMMM</i>. The -<i>MMMMMM</i> syntax identifies the number of minutes to go back from the current time to begin formatting the journal.
<p>
If <b>Start time</b> is not specified, data is formatted from the start of the run or the oldest ring journal (if using ring journals) if the requesting user is a system manager (or is in one of the [[ADMIN SCLASS]]es). Otherwise data is formatted from the logon time of the requesting user.</p></td></tr>
 
<tr><th>Start date</th>
<td>Formatted <i>YY</i>/<i>MM</i>/<i>DD</i>. The date of the earliest audit trail entry to be formatted.
<p>
If <b>Start date</b> is not specified, it is determined based on the start time. If the start time is less than the current time the current date is used; otherwise, yesterday's date is used. </p></td></tr>
 
<tr><th>Interval</th>
<td>Valid formats are <i>MM</i>:<i>SS</i>, <i>HH</i>:<i>MM</i>:<i>SS</i>, or <i>MMMMMMM</i>, where <i>H</i> is hours, <i>M</i> is minutes, and <i>S</i> is seconds.
<p>
If an interval is not specified, data is formatted up to the current time (or until I/O limits are reached). In addition, by leaving this time blank, <var class="product">SirScan</var> runs in [[SirScan browsing of the journal#autoref|auto-refresh mode]], so the data being scanned is constantly refreshed to reflect any new audit trail data that was generated after the initial data was collected.</p></td></tr>
 
<tr id="inputJournal"><th>Input journal</th>
<td>By default, this is the journal currently in use by the Online in which you are working, and it is indicated by a blank value or by the word <code>CURRENT</code>.
<p>
<p>
You may, of course, upgrade to a full <var class="product">SirScan</var> at any time.</p></td></tr>
To scan a historical journal for this Online, or a current or historical journal for another Online, allocate it as a sequential file and enter the DD name in this field. If <b>Start date</b> and <b>Interval</b> cannot be accommodated by the non-default journal, you are warned and a corrected time range is displayed.</p></td></tr>
 
<tr><th>Online init date/time</th>
<td>The time and date that the Online in which you are working was initialized.</td></tr>


<tr><th>Output Line Width</th>
<tr><th>Line Width</th>
<td>The audit trail data can be formatted for any line width from one less than the screen width to 255. The minimum output line width is 131 for <var>[[MODEL parameter|MODEL]]</var> 5 terminals, and it is 79 for all other terminal types.</td></tr>
<td>The audit trail data can be formatted for any line width from one less than the screen width to 255. The minimum output line width is 131 for <var>[[MODEL parameter|MODEL]]</var> 5 terminals, and it is 79 for all other terminal types.
<p>
If you set a value greater than your screen width, left and right scrolling of the journal with the PF10 and PF11 keys is available to view all the audit trail data. </p></td></tr>


<tr><th>Read extra SCANTIME seconds</th>
<tr><th nowrap>Read extra <br>SCANTIME seconds</th>
<td>This field only appears if the <var>SCANTIME</var> system parameter is set to a non-zero value.The value of this field must be either <code>Y</code> or <code>N</code>.
<td>This field only appears if the <var>[[SCANTIME parameter|SCANTIME]]</var> system parameter is set to a non-zero value. The value of this field must be either <code>Y</code> or <code>N</code>.
Setting this field to <code>N</code> allows anomalous and confusing behavior on <var class="product">SirScan</var>'s part so should be avoided unless following are all true:
<blockquote class="note">
<p><b>Note:</b> Setting this field to <code>N</code> allows anomalous and confusing behavior on <var class="product">SirScan</var>'s part so should be avoided unless following are all true: </p>
<ul>
<ul>
<li>The <var>SCANTIME</var> parameter is set, against recommendations, to a very high value.</li>
<li>The <var>SCANTIME</var> parameter is set, against recommendations, to a very high value.</li>
Line 127: Line 138:


<li>You understand the anomalous behavior that is likely to result, and either you feel it doesn't apply to your selection criteria, or you don't care.</li>
<li>You understand the anomalous behavior that is likely to result, and either you feel it doesn't apply to your selection criteria, or you don't care.</li>
</ul></blockquote>
</td></tr>
<tr><th>Max I/O's</th>
<td>The maximum number of full-track journal reads <var class="product">SirScan</var> will perform when scanning the journal.
<p>
In the case of very busy systems, set <b>Max I/O's</b> to a relatively small number, such as 100 or 1000, to avoid accidentally scanning too much of the journal if an inappropriate time interval is specified.</p>
<p>
Though you may specify here a larger number, the maximum value allowed for this field is determined by your subsystem user class ([[SCLASS]]). The value can be viewed and set using the SirAdmin subsystem (within the <b>SirScan SCLASS settings</b> option). As of version 7.5, if the value you enter exceeds the value recorded in SirAdmin, these actions follow: </p>
<ul>
<li>The value is automatically reset to the maximum allowable. </li>
<li>An informational message is displayed on the "message line" near the bottom of this screen. </li>
</ul></td></tr>
</ul></td></tr>


<tr><th>Maximum I/O's</th>
<tr><th>Max records</th>
<td>The maximum number of full-track journal reads <var class="product">SirScan</var> will perform when scanning the journal. The maximum value allowed for this field is determined by the user's subsystem SCLASS.
<td>The maximum number (no more than seven digits) of journal records to be formatted by <var class="product">SirScan</var>. It is recommended that you set <b>Max records</b> to a reasonably small number, such as 10000, to avoid accidentally building an unmanageably large list of formatted records.
This value should generally be kept to a relatively small number such as 100 or 1000 in the case of very busy systems to avoid accidentally scanning too much of the journal when an inappropriate time interval is specified.</td></tr>
<p>
Though you may specify here a larger number, the maximum value allowed for this field is determined by your subsystem user class ([[SCLASS]]). The value can be viewed and set using the SirAdmin subsystem (within the <b>SirScan SCLASS settings</b> option). As of version 7.5, if the value you enter exceeds the value recorded in SirAdmin, these actions follow: </p>
<ul>
<li>The value is automatically reset to the maximum allowable. </li>


<tr><th>Maximum records</th>
<li>An informational message is displayed on the "message line" near the bottom of this screen. </li>
<td>The maximum number of journal records to be formatted by <var class="product">SirScan</var>. The maximum value allowed for this field is determined by the user's subsystem SCLASS.
</ul>
This value should generally be kept to a reasonably small number such as 10000 to avoid accidentally building an unmanageably large list of formatted records.</td></tr>
</td></tr>


<tr><th>Display User Numbers</th>
<tr><th>Display</th>
<td>This indicates whether user numbers are to appear in the fomatted audit trail data.</td></tr>
<td>
<table>
<tr><th>Date</th>
<td>Indicates whether the date of each entry is to appear in the formatted audit trail data. The dates are displayed in YYMMDD format.</td></tr>


<tr><th nowrap>Display Server Numbers</th>
<tr><th nowrap>Server number</th>
<td>This indicates whether server numbers are to appear in the fomatted audit trail data.</td></tr>
<td>Indicates whether server numbers are to appear in the fomatted audit trail data.</td></tr>


<tr><th>Diplay Entry Dates</th>
<tr><th>Entry type</th>
<td>This indicates whether the date of each entry is to appear in the formatted audit trail data. The dates are displayed in <var>YYMMDD</var> format.</td></tr>
<td>Indicates whether the type of each entry is to be included in the formatted audit trail data. The types are described in [[SirScan browsing of the journal#Journal entry types|Journal entry types]]. If entry types are not displayed, colors are automatically turned off. </td></tr>


<tr><th>Display Entry Times</th>
<tr><th>Time</th>
<td>This indicates whether the time of each entry is to appear in the formatted audit trail data. The times are displayed in <var>HHMMSSTH</var> format.</td></tr>
<td>Indicates whether the time of each entry is to appear in the formatted audit trail data. The times are displayed in HHMMSSTH format.</td></tr>


<tr><th>Display Entry Types</th>
<tr><th>User numbers</th>
<td>This indicates each type of entry which is to be included in the formatted audit trail data. The dates are displayed in <var>YYMMDD</var> format.</td></tr>
<td>Indicates whether user numbers are to appear in the fomatted audit trail data.</td></tr>


<tr><th>Use color</th>
<td>Indicates whether the formatted journal output is to be shown using user-specified colors. User colors are displayed only if <b>Entry type</b> is <code>Y</code>. The colors can be changed using the screen ([[#Setting scan display colors|Set Display Colors]]) accessed with the F6 key.
<p>
This color feature is available in version 7.5 or higher. </p></td></tr>
</table></tr>
<tr><th>Format Entry Types</th>
<td>
<table>
<tr><th>ST</th>
<tr><th>ST</th>
<td>Responding <code>Y</code> to this prompt causes ST records (all types of statistics records) to be included in the formatted output. Specifying <code>N</code> excludes these records.</td></tr>
<td>Responding <code>Y</code> to this prompt causes ST records (all types of statistics records) to be included in the formatted output. Specifying <code>N</code> excludes these records.</td></tr>


<tr><th>AA</th>
<tr><th>All Audit Types</th>
<td>Responding <code>Y</code> to this prompt causes all audit type records to be included in the formatted output.
<td>Responding <code>Y</code> to this prompt causes all audit type records to be included in the formatted output.
Specifying <code>N</code> causes <var class="product">SirScan</var> to pay attention to the specific <code>Y/N</code> settings for each record type in the bottom two rows on the screen.
Specifying <code>N</code> causes <var class="product">SirScan</var> to pay attention to the specific <code>Y/N</code> settings for each record type in the bottom two rows on the screen.
The various record types are described in the next section, and also in
The various record types are described in [[SirScan browsing of the journal#Journal entry types|Journal entry types]] and also in
[[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Audit trail format|Audit trail format]].
[[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Audit trail format|Audit trail format]].


<tr><th>SirScan RK</th>
<tr><th nowrap>SirScan RK lines</th>
<td>Responding <code>Y</code> to this prompt causes SirScan heartbeat RK messages for the <var>SCANTIME</var> system parameter to be formatted.
<td>Responding <code>Y</code> to this prompt causes SirScan heartbeat RK messages for the <var>SCANTIME</var> system parameter to be formatted.
These messages largely exist to help <var class="product">SirScan</var> identify threads by userid or other selection criteria and are not particularly interesting so are ordinarily suppressed
These messages largely exist to help <var class="product">SirScan</var> identify threads by userid or other selection criteria and are not particularly interesting so are ordinarily suppressed
regardless of the <var>AA</var> or <var>RK</var> switch settings.
regardless of the <b>All Audit Types</b> or <var>RK</var> switch settings.
If this prompt is set to <code>Y</code> the <var class="product">SirScan</var> heartbeat messages will be displayed.</td></tr>
If this prompt is set to <code>Y</code>, the <var class="product">SirScan</var> heartbeat messages will be displayed.</td></tr>
 
<tr><th>Bookmarks</th>
<td>Creates extra lines in the resulting display listing that mark the time range for each scan. This feature is available with version 7.5 or higher. See [[#Using bookmarks|Using bookmarks]], below.
<p class="note"><b>Note:</b> Bookmarks are only active if the <b>Interval (Minutes)</b> field is left blank.</p>
</td></tr>
 
<tr><th>AD, CI, ... QT</th>
<td>[[SirScan browsing of the journal#Journal entry types|Journal entry types]].</td></tr>
</table></td></tr>
</table>
</table>


==Commands and function keys==
==Commands and function keys==
The following commands and PF keys are valid on the scan specification screen:
The following commands and PF keys are valid on the TN3270 scan specification screen. Typical browser controls provide comparable functionality in RKWeb. 
 
<table class="thJustBold">
<table class="thJustBold">
<caption>Commands</caption>
<caption>Commands</caption>
<tr><th>=<i>x</i>.y<i>y</i>.<i>z</i></th>
<tr><th nowrap><p class="codeInTable">[sir]<i>prodShortName</i> [<i>num</i>]</p></th>
<td>Commands prefixed by <code>=</code> invoke fastpath navigation of the UL/SPF menu system. <code>=M</code> sends the user to the UL/SPF main menu if UL/SPF is active.
<td><p>
<code>=X</code> exits to command level. <code>=M.4.5.2</code> sends the user to the "Active Subsystems" display in <var class="product">[[Sirmon]]</var> (if <var class="product">Sirmon</var> is active).</td></tr>
[[RKTools#Fast-pathing|Fastpath navigation of the RKTools menu system]]. For example, <code>pro 8</code> takes you to the <var class="product">SirPro</var> group definitions screen.</p></td></tr>


<tr><th>X</th>
<tr><th>X</th>
Line 182: Line 231:
<table class="thJustBold">
<table class="thJustBold">
<caption>PF keys</caption>
<caption>PF keys</caption>
<tr><th>PF1</th>
<tr><th>F1</th>
<td>Accesses online help.</td></tr>
<td>Accesses online Help. If the cursor is located on a screen field, the invoked Help is positioned at the Help text for that field. Otherwise, it is positioned at the start of the Help for the screen.</td></tr>


<tr><th>PF3</th>
<tr><th>F3</th>
<td>Quit (return to command level).</td></tr>
<td>Quit (return to command level).</td></tr>
<tr><th>F4</th>
<td>Resets <b>Start time</b> and <b>Start date</b> to the time and date the current journal was initialized (that is, to the value shown in this screen's <b>Online init date/time</b> field). </td></tr>
<tr><th>F6</th>
<td>Set or reset the colors of the journal scan lines using the [[#Setting scan display colors|Set Display Colors screen]] described in the next section.
</td></tr>
</table>
</table>
==Setting scan display colors==
You can change the colors in the display of the journal scan you are defining. Pressing the F6 key in the TN3270 interface invokes the <b>Set Display Colors</b> screen with which you can specify the colors for the various journal entry types in the SirScan output. In RKWeb, clicking the journal entry type opens a color-picking tool.
<p class="caption" style="width:450px">Set Display Colors</p>
<p class="figure">[[File:SScanSetColors.png|450px]]</p>
<p>
The <b>(sample)</b> column lists the valid 3278/3279 colors you can use. The F1 Help text describes the web-version colors you can specify and the three ways you can specify them. </p>
<p>
The F1 Help also contains the definitions of the various entry types.
</p>
==Using bookmarks==
Bookmarks let you save multiple consecutive scans in a virtual array for the duration of your Online session. Bookmarks are numbered, and new bookmarks numerically follow the number of the last one previously created. You can revisit any of these bookmarked scans, in any order you want, navigating by PF key or command line.
Bookmarks are not available in the RKWeb interface.
If you set the <b>Bookmark</b> option (in the <b>Format Entry Types</b> section) to <code>Y</code>, then each time you invoke a scan, a solid horizontal line is displayed near the top of the [[SirScan browsing of the journal|formatted output screen]], marking the beginning of a bookmarked scan and saving that scan with the previous bookmarked scans in the session. Below the bookmark line are the usual content lines of the scan, extending to the current time. 
To the right of the bookmark starting line is a label that identifies the bookmark ID number and time range for that scan period. The time range begins according to the screen's <b>Start time</b> field value and ends at the current time:
<p class="code">___________________________________________________ BookMark 1: 19:59:37.23 - 19:59:58.90
</p>
The current (active) bookmark is shown in green, while older bookmarks are red. The bookmarks are sequentially numbered, and the message line (red, non-solid) at the bottom of the screen shows the latest bookmark ID. For example, if you have bookmarked four scans, the bottom message line is:
<p class="code">------------------------------------------------------------------ -- Latest Bookmark: 4
</p>
<p>
Bookmarks are saved for the session: if you exit SirScan and re-enter
during the same Online session, the previous bookmarks are retained and can be re-displayed. If you change the screen's <b>Display</b> section or <b>Format Entry Types</b> section values, the changes propagate as well through the journal lines in your saved bookmarked scans.  </p>
===Navigating your bookmarks===
<ul>
<li>The function keys F5 (<b>Prev Bkmk</b>) and F6 (<b>Next Bkmk</b>) let you "walk" one at a time through the bookmarked scans. Pressing F6 while within the latest scan invokes a new scan.</li>
<li>The <var>.<i>bookmark</i></var> command-line command takes you directly to the scan whose ID number corresponds to the <var class="term">bookmark</var> number in the command.
<p>
Specifying just a period with no <var class="term">bookmark</var> value (<code>.</code>), takes you to the latest bookmark. </p></li>
<li>When you return to a saved scan (other than the "latest"), your view contains only the lines for that particular scan. The <var>Top</var> and <var>Bot</var> commands, for example, operate with respect to that scan. You cannot use the Up and Down function keys to move to the following or trailing bookmarked scan.
<p>
If you are in the latest bookmark, the view is dynamic: </p>
<ul>
<li>Pressing the Enter key adds a bookmark to the page and whatever new lines are being created in the journal. If the Online is quiet, pressing Enter has no effect. </li>
<li>Pressing F6 clears the screen for any new scan lines (which are displayed whenever you press Enter or F8 or issue a <var>Bot</var> command).
<p>
Pressing F6 here is equivalent to pressing F3, setting <b>Start Time</b> to <code>-0</code>, then pressing Enter. </p></li>
</ul></li>
</ul>


==See also==
==See also==

Latest revision as of 20:49, 9 March 2018

Installation of SirScan is described in RKTools installation. SirScan should be installed as a private Application Subsystem in order to use the I/O limits assigned to each SCLASS.

To access the system, enter SIRSCAN (or the name of the subsystem you have installed) on the Model 204 command line. You are presented with a scan specification screen, which lets you specify the journal data to be retrieved and the format in which it should be displayed.

In RKWeb, selecting the Monitor > Journal Scan option displays an equivalent menu.

Journal scan criteria screen

Screen input fields

Users Users to be included in the formatted output. This input field indicates which thread's/user's audit entries will be viewed.

The selection criteria can be a set of blank or comma delimited "phrases," each made up of one or more "clauses" separated by the ampersand (&) symbol. Each clause can contain one of the following criteria:

IODEVn A number n indicating a specific IODEV type, as in IODEV15, IODEV7, or IODEV11.
PST Entries for all Model 204 Psuedo-SubTasks.
n1.n2.n3.n4 An IP address for a Janus thread, as in 198.242.244.97 or 150.209.8.51. The IP address can also be followed by a slash (/) and a subnet mask, or by a hyphen (-) and a number of bits in a subnet mask, as in 98.242.244.0/255.255.255.0 or 198.242.244.0-24. These two subnetted IP addresses encompass the same set of IP addresses.
JAN:sss The name of a Janus port, possibly containing wildcards, as in JAN:WEBPORT, JAN:WEB*, or JAN:???PORT.
xxx A specific user number, as in 0, 233, or 1024.
xxx-yyy A range of user numbers, as in 0-20 or 111-1000.
ssss A string, possibly containing wildcards, that indicates a specific userid, as in RASPUTIN, RAS*, ???PUTIN. For users in the ADMIN_xxx SCLASSes, a user ID of just an asterisk (*) is special-cased to mean not only all logged-on users, but all threads, whether logged on or not.

Criteria can be mixed and matched using the & separator, which indicates an "And" operation, or using blanks or commas, which indicate an "Or" operation. For example, the following string requests information for all IODEV 15 threads logged on as userid LENIN, and requests all the information for user numbers 11 through 20:

IODEV15&LENIN 11-20

And this:

TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST

requests information for all of the following:

  • All connections from IP address 198.242.244.33 that log on a userid that begins with TROT
  • All connections to Janus port SOCIALIST that log on to userid MARX
  • All PSTs

Port names and user IDs can contain special wildcard characters. These characters and their meanings are:

* Matches any number of characters. For example, BRE* matches BREAD, BREEZY, and BREZHNEV.
? Matches a single character. For example, ?RUSHCHEV matches TRUSHCHEV, BRUSHCHEV, and KRUSHCHEV.
" Means the next character is to be treated literally, even if it is wildcard character. Using the double-quotation character is necessary if a wildcard character appears in the name to be matched.For example, E"*BARTER matches E*BARTER.

Users in USER_HI, USER_MED or USER_LO SCLASSes, no matter what selection criteria are specified, are only able to view audit entries associated with their own user ID or, if the system SCANPARM 1 bit is set, entries for public logins on Janus Web Server threads. So if a user in the USER_MED SCLASS specifies the following for a selection criterion:

IODEV15

You are able to see only IODEV 15 activity for your own user ID or perhaps for public logins to a Janus Web thread (if the SCANPARM 1 bit is set).

Because the specified time interval may not include the journal entries that would allow SirScan to associate a thread's activity with a particular user ID, IP address, or port number, it is possible that entries associated with a particular user ID, IP address, or port number will not be formatted. It is also possible that many entries in a time interval for a requested user ID, IP address, or port number will not be formatted, but those after an audit entry that allows determination of all these entities (a since-last statistic or a SirScan RK line), will be.

SirScan makes every effort to use all available information (current logged on userids and log times, M204.0352 messages, M204.0118 messages, since-last stat entries, etc.) to ascertain this information about each audit trail entry, but these attempts are necessarily hit and miss: While most of the time, SirScan will pick up the desired information, it is possible that information will also seem to be inexplicably missing. Often this information can still be retrieved by varying the date/time interval.

Alternatively, if the SCANTIME system parameter is set, and the "Read extra SCANTIME seconds" switch is set to Y, SirScans behavior can be made completely consistent and predictable at a (hopefully slight) cost.

If no criteria are specified for Users, only audit entries for the requesting user are displayed.

Note: One additional selection criterion is applied to any Users phrase if SirScan has not been purchased but instead is automatically authorized by Limited Janus Web Server. Limited Janus Web Server is a free, restricted version of Janus Web Server; they are both documented in Janus Web Server.

To assist in web development, sites that don't already have SirScan can use it for free if they are using Limited Janus Web Server. Sites using SirScan for free are automatically limited to viewing the journal activity of Janus Web threads and the TCP/IP subtask; any Users selection will thus be automatically restricted.

You may, of course, upgrade to a full SirScan at any time.

Start time The earliest audit trail entry to be formatted. Formatted HH:MM:SS, HHMMSS, or HH.MM.SS (as of version 7.5), or -MMMMMM. The -MMMMMM syntax identifies the number of minutes to go back from the current time to begin formatting the journal.

If Start time is not specified, data is formatted from the start of the run or the oldest ring journal (if using ring journals) if the requesting user is a system manager (or is in one of the ADMIN SCLASSes). Otherwise data is formatted from the logon time of the requesting user.

Start date Formatted YY/MM/DD. The date of the earliest audit trail entry to be formatted.

If Start date is not specified, it is determined based on the start time. If the start time is less than the current time the current date is used; otherwise, yesterday's date is used.

Interval Valid formats are MM:SS, HH:MM:SS, or MMMMMMM, where H is hours, M is minutes, and S is seconds.

If an interval is not specified, data is formatted up to the current time (or until I/O limits are reached). In addition, by leaving this time blank, SirScan runs in auto-refresh mode, so the data being scanned is constantly refreshed to reflect any new audit trail data that was generated after the initial data was collected.

Input journal By default, this is the journal currently in use by the Online in which you are working, and it is indicated by a blank value or by the word CURRENT.

To scan a historical journal for this Online, or a current or historical journal for another Online, allocate it as a sequential file and enter the DD name in this field. If Start date and Interval cannot be accommodated by the non-default journal, you are warned and a corrected time range is displayed.

Online init date/time The time and date that the Online in which you are working was initialized.
Line Width The audit trail data can be formatted for any line width from one less than the screen width to 255. The minimum output line width is 131 for MODEL 5 terminals, and it is 79 for all other terminal types.

If you set a value greater than your screen width, left and right scrolling of the journal with the PF10 and PF11 keys is available to view all the audit trail data.

Read extra
SCANTIME seconds		 This field only appears if the SCANTIME system parameter is set to a non-zero value. The value of this field must be either Y or N.

Note: Setting this field to N allows anomalous and confusing behavior on SirScan's part so should be avoided unless following are all true:

  • The SCANTIME parameter is set, against recommendations, to a very high value.
  • You are very concerned about security.
  • You understand the anomalous behavior that is likely to result, and either you feel it doesn't apply to your selection criteria, or you don't care.
Max I/O's The maximum number of full-track journal reads SirScan will perform when scanning the journal.

In the case of very busy systems, set Max I/O's to a relatively small number, such as 100 or 1000, to avoid accidentally scanning too much of the journal if an inappropriate time interval is specified.

Though you may specify here a larger number, the maximum value allowed for this field is determined by your subsystem user class (SCLASS). The value can be viewed and set using the SirAdmin subsystem (within the SirScan SCLASS settings option). As of version 7.5, if the value you enter exceeds the value recorded in SirAdmin, these actions follow:

  • The value is automatically reset to the maximum allowable.
  • An informational message is displayed on the "message line" near the bottom of this screen.
Max records The maximum number (no more than seven digits) of journal records to be formatted by SirScan. It is recommended that you set Max records to a reasonably small number, such as 10000, to avoid accidentally building an unmanageably large list of formatted records.

Though you may specify here a larger number, the maximum value allowed for this field is determined by your subsystem user class (SCLASS). The value can be viewed and set using the SirAdmin subsystem (within the SirScan SCLASS settings option). As of version 7.5, if the value you enter exceeds the value recorded in SirAdmin, these actions follow:

  • The value is automatically reset to the maximum allowable.
  • An informational message is displayed on the "message line" near the bottom of this screen.
Display
Date Indicates whether the date of each entry is to appear in the formatted audit trail data. The dates are displayed in YYMMDD format.
Server number Indicates whether server numbers are to appear in the fomatted audit trail data.
Entry type Indicates whether the type of each entry is to be included in the formatted audit trail data. The types are described in Journal entry types. If entry types are not displayed, colors are automatically turned off.
Time Indicates whether the time of each entry is to appear in the formatted audit trail data. The times are displayed in HHMMSSTH format.
User numbers Indicates whether user numbers are to appear in the fomatted audit trail data.
Use color Indicates whether the formatted journal output is to be shown using user-specified colors. User colors are displayed only if Entry type is Y. The colors can be changed using the screen (Set Display Colors) accessed with the F6 key.

This color feature is available in version 7.5 or higher.

Format Entry Types
ST Responding Y to this prompt causes ST records (all types of statistics records) to be included in the formatted output. Specifying N excludes these records.
All Audit Types Responding Y to this prompt causes all audit type records to be included in the formatted output.

Specifying N causes SirScan to pay attention to the specific Y/N settings for each record type in the bottom two rows on the screen. The various record types are described in Journal entry types and also in Audit trail format.

SirScan RK lines Responding Y to this prompt causes SirScan heartbeat RK messages for the SCANTIME system parameter to be formatted.

These messages largely exist to help SirScan identify threads by userid or other selection criteria and are not particularly interesting so are ordinarily suppressed regardless of the All Audit Types or RK switch settings.

If this prompt is set to Y, the SirScan heartbeat messages will be displayed.
Bookmarks Creates extra lines in the resulting display listing that mark the time range for each scan. This feature is available with version 7.5 or higher. See Using bookmarks, below.

Note: Bookmarks are only active if the Interval (Minutes) field is left blank.

AD, CI, ... QT Journal entry types.

Commands and function keys

The following commands and PF keys are valid on the TN3270 scan specification screen. Typical browser controls provide comparable functionality in RKWeb.

Commands

[sir]prodShortName [num]

Fastpath navigation of the RKTools menu system. For example, pro 8 takes you to the SirPro group definitions screen.

X Exits to command level.
PF keys
F1 Accesses online Help. If the cursor is located on a screen field, the invoked Help is positioned at the Help text for that field. Otherwise, it is positioned at the start of the Help for the screen.
F3 Quit (return to command level).
F4 Resets Start time and Start date to the time and date the current journal was initialized (that is, to the value shown in this screen's Online init date/time field).
F6 Set or reset the colors of the journal scan lines using the Set Display Colors screen described in the next section.

Setting scan display colors

You can change the colors in the display of the journal scan you are defining. Pressing the F6 key in the TN3270 interface invokes the Set Display Colors screen with which you can specify the colors for the various journal entry types in the SirScan output. In RKWeb, clicking the journal entry type opens a color-picking tool.

Set Display Colors

The (sample) column lists the valid 3278/3279 colors you can use. The F1 Help text describes the web-version colors you can specify and the three ways you can specify them.

The F1 Help also contains the definitions of the various entry types.

Using bookmarks

Bookmarks let you save multiple consecutive scans in a virtual array for the duration of your Online session. Bookmarks are numbered, and new bookmarks numerically follow the number of the last one previously created. You can revisit any of these bookmarked scans, in any order you want, navigating by PF key or command line.

Bookmarks are not available in the RKWeb interface.

If you set the Bookmark option (in the Format Entry Types section) to Y, then each time you invoke a scan, a solid horizontal line is displayed near the top of the formatted output screen, marking the beginning of a bookmarked scan and saving that scan with the previous bookmarked scans in the session. Below the bookmark line are the usual content lines of the scan, extending to the current time.

To the right of the bookmark starting line is a label that identifies the bookmark ID number and time range for that scan period. The time range begins according to the screen's Start time field value and ends at the current time:

___________________________________________________ BookMark 1: 19:59:37.23 - 19:59:58.90

The current (active) bookmark is shown in green, while older bookmarks are red. The bookmarks are sequentially numbered, and the message line (red, non-solid) at the bottom of the screen shows the latest bookmark ID. For example, if you have bookmarked four scans, the bottom message line is:

------------------------------------------------------------------ -- Latest Bookmark: 4

Bookmarks are saved for the session: if you exit SirScan and re-enter during the same Online session, the previous bookmarks are retained and can be re-displayed. If you change the screen's Display section or Format Entry Types section values, the changes propagate as well through the journal lines in your saved bookmarked scans.

Navigating your bookmarks

  • The function keys F5 (Prev Bkmk) and F6 (Next Bkmk) let you "walk" one at a time through the bookmarked scans. Pressing F6 while within the latest scan invokes a new scan.
  • The .bookmark command-line command takes you directly to the scan whose ID number corresponds to the bookmark number in the command.

    Specifying just a period with no bookmark value (.), takes you to the latest bookmark.

  • When you return to a saved scan (other than the "latest"), your view contains only the lines for that particular scan. The Top and Bot commands, for example, operate with respect to that scan. You cannot use the Up and Down function keys to move to the following or trailing bookmarked scan.

    If you are in the latest bookmark, the view is dynamic:

    • Pressing the Enter key adds a bookmark to the page and whatever new lines are being created in the journal. If the Online is quiet, pressing Enter has no effect.
    • Pressing F6 clears the screen for any new scan lines (which are displayed whenever you press Enter or F8 or issue a Bot command).

      Pressing F6 here is equivalent to pressing F3, setting Start Time to -0, then pressing Enter.

See also

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