SirScan scan specification

From m204wiki
Revision as of 23:26, 11 February 2016 by JAL (talk | contribs) (→‎Commands and function keys: change tag)
Jump to navigation Jump to search

Installation of SirScan is described in RKTools installation. SirScan 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 SIRSCAN (or the name of the subsystem you have installed) on the Model 204 command line. A scan specification screen is presented:

Journal scan criteria screen

This screen allows the user to specify the journal data to be retrieved and the format in which it should be displayed. Input fields are:

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 Formatted HH:MM:SS or -MMMMMM. 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 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 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.
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.
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.

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. The maximum value allowed for this field is determined by the user's subsystem SCLASS. 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.
Max records The maximum number of journal records to be formatted by SirScan. The maximum value allowed for this field is determined by the user's subsystem SCLASS. 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.
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.

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 scan specification screen:

Commands

[sir]shortcode [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 invokes the Set Display Colors screen with which you can specify the colors for the various journal entry types in the SirScan output.

Set Display Colors

You can set display colors by entry type for both the 3278/3279 display and for the web version of SirScan. 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.

See also

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