SirScan scan specification

From m204wiki
Revision as of 20:49, 9 March 2018 by Dme (talk | contribs) (→‎Screen input fields)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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"