Help for Real-Time File Monitor

Version

V2.0    Date: 2001/09/03


Installation

The File Monitor can be installed in any library by restoring the save file supplied.

Inventory


XUADDMSG *PGM   Utility to log messages
XUCMNDTA *PGM   Access XUCMNPAR data-area
XUCMNSET *PGM   Setup common parameters
XUFILMON *PGM   File Monitor main program
XUHELPER *PGM   Help processor
XUINVITE *PGM   Invited display reader
XUODPWLK *PGM   Walk ODP chain
XUPARSER *PGM   Script parser and interpreter
XUSCRNAS *PGM   5250 Data-stream generator
XUSCRNFM *PGM   Screen formatter
XUSCRNIO *PGM   Top-level screen handler
XUWRKSET *PGM   Work with Settings
XUSFILES *FILE  Source file with scripts
XUTIMOUT *FILE  Display file for timed reads
XUADDMSG *CMD   Command for XUADDMSG
XUFILMON *CMD   Command for XUFILMON

Trial Period
The product has a 14-day free trial period beginning when the File Monitor is run for the first time. After the trial period has expired, a product license code is needed for continued operation.

Installation
Attached to this Email is a self-extracting "zipped" file (SAVXUF.EXE). Open the attachment. It will ask you where to store the contents. Select any convenient folder (e.g. C:\TEMP) or just use the default.

On your iSeries, sign on with a User Profile that has enough authority to restore programs and to create libraries if you elect to do so. You can use one of your existing libraries or create one called anything you like, e.g. XULIB. Create a save file in that library called SAVXUF.

Now back to the PC, FTP to your iSeries and sign on with a User Profile that has the needed authority. Change your library to XULIB or whichever library you have chosen to instal the File Monitor into. Go to Binary mode. Put the PC file (C:\TEMP\SAVXUF) onto the iSeries into SAVXUF.

Now back to the iSeries. Sign on with a User Profile that has enough authority to restore objects. Restore the objects in SAVXUF1 into XULIB or the library you have chosen.

Add to your library list XULIB or the library you restored the objects into. Execute the XUFILMON command. When the File Monitor starts, it scans all jobs in the system. This may take a little while as many jobs may not have been active for quite some time. This delay you will only have when starting.

You have now successfully loaded the software for use.
Listed below are the detailed steps for the above instructions:

PC

iSeries

FTP to your iSeries

iSeries


Note: You do not need to add the library where File Monitor is stored to the library list in order to run the File Monitor. You can run File Monitor from anywhere, but must then qualify the command with the library, e.g. ===> XULIB/XUFILMON.


The File Monitor (XUFILMON)

The File Monitor keeps track of all files, that are open at any moment. The Work Control Block tables are scanned for active jobs. For every active job, the ODPs, i.e. the Open Data Paths are checked to locate all files that are currently open. Only such files can actually grow. Only physical files and their members are kept track off. Logical files are skipped.

Features

Function keys

F1=Help
Pressing F1 will return the user help for general help or a particular item depending on where the user has positioned the cursor prior to invoking help. Help is available on every screen and for many fields.

F3=Exit
Press F3 to exit the File Monitor. The current Settings are saved in data area XUCMNPAR.

F5=Refresh
Press F5 to refresh the file information. I.e. to re-scan all the ODPs of all active jobs. If a script is enabled, the script will be executed once for every file that survives the filtering process.

F6=Set filters
Press F6 to get the 'Settings' screen where you set filtering and scripting options.

F9=Command line
Press F9 to get a standard Command Line.

F10=New Script
Press F10 to force reading of the script. The script is ordinarily only read when you start the File Monitor. If you have changed the script since, you can use F10 to force the File Monitor to read the new script. After reading the script, file information is automatically refreshed and the script is enabled and executed.

F11=Sort
Press F11 to sort the files into the desired order. If the cursor is in any column, the files are sorted on that column. Some columns sort in ascending order, others in descending order, in a sensible way. Pressing F11 repeatedly will cause the File Monitor to sort on the next column over. A small dot over the column header shows which column is currently sorted on.

F12=Cancel
Press F12 to exit the File Monitor or to stop auto-refreshing.

Page down/up
Press the paging keys to scroll to following or previous pages of information. This also works in auto-refresh mode without stopping the automatic refresh. The file information is not refreshed when you are just navigating the information displayed.
The function keys F7/F8 also work as Page Up/Down (on this and all other screens).

F17=Top
Press F17 to go to the top (i.e. the first record) of the file information.

F18=Bottom
Press F18 to go to the bottom (i.e. the last record) of the file information.

F19=Start/Stop auto refresh
Press F19 to start (or when started, to stop) automatic refresh of file information. The refresh interval can be set by pressing F6, then Page Forward to the next page to locate the refresh interval field. The Enter key and F3/F12 will also stop the refresh.

F20=Size/Count
Press F20 to toggle between showing the size of the file or the I/O count. The size will be shown in Kilobytes (units of 1024 bytes). The size is only shown for ordinary database files, not for display files or spool files. If you do not have authority to see information about the file, the I/O count will be shown instead.

CLICK-Support
Click on a function key prompt to press that function key. Click on the 'More...' prompt to Page Forwards. Click to the left of the 'More...' to Page Backwards. Click on a column to sort on that column. Click on the message line to get help.

Clicking means moving the cursor to a position and pressing the Enter key or, if your emulator allows it, double-clicking with the mouse on a field. Clicking outside of a pop-up window has the same effect as the Cancel key.

Item Options
Enter an option number in the left-most field on each line and press Enter to execute that option. You can choose several (and even different) options on the same screen. If you page forwards or backwards, you abandon the options you have entered. You must have authority to the actions initiated by entering options.

1=Display file description
Displays the complete file description for the selected file. This is just the standard DSPFD command.

2=Display user profile
Displays the user profile under which the job is running. This is just the DSPUSRPRF command.

3=Work with job
Displays all information about the job. You can work with all job aspects by selecting the appropriate options or function keys on the screens presented. In particular, you can control the job, e.g. end it, by pressing 'F16=Job menu' on the first screen.

Days Left of Demo Period

Following a fourteen-day trial period, the File Monitor requires a License Code to run. As long as the demo or evaluation period has not yet expired, this field tells you how much time you have left.

Active Jobs

This field shows the number of jobs currently active. The first (actually the last in the Work Control Table) 100 or so jobs are usually system jobs started following an IPL.


Work with Settings (XUWRKSET)

A set of variables called the 'Settings' controls various aspects of the File Monitor. The Settings are stored in the data area XUCMNPAR, and are maintained from the 'Work with Settings' screen. Pressing Enter will accept the new settings and (after optional confirmation) cause a refresh of the file information.

Features

Function keys

Enter/Accept
Press Enter to check and accept the values entered.

F4=Prompt
Press F4 to get help on each field. You can also press F1=Help.

F5=Refresh
Press F5 to refresh the information from the previously saved values.

F12=Cancel
Press F12 to cancel any changes to the settings and to return to showing the file information previously retrieved.

Filtering Parameters

Filtering can be turned *ON and *OFF by specifying this as the first filtering parameter. In this way, the remaining parameters can be left intact for later use. The rule is that if a filtering parameter is blank it is not active.

Filtering is cumulative in the sense that each non-blank parameter further restricts the number of files that pass the filter.

To get help on the effect of a parameter, place the cursor on it and press F1. You can also press F4 to prompt for each value.

Refresh Frequency

When the File Monitor is in automatic refresh mode, the file information is automatically refreshed and displayed at a certain frequency that you can set as needed. The parameter setting specifies the number of seconds between each refresh.

Scripting Options

For every file shown on the display (i.e. that has 'survived' the filtering process) a script may be executed. The script is given all information about the file and can then, based on its own logic, determine what to do about the file. The script can contain conditional commands that may be executed as wanted. These commands are ordinary AS/400 (iSeries400) commands that for instance send messages to the operator or the security officer or log the event.

Filtering *ON/*OFF

Entering *ON turns filtering ON with the parameter settings as given in the fields below. Entering *OFF turns filtering OFF temporarily without altering any of the filtering parameters.

Job/Device

For interactive jobs, the job name is the same as the name of the workstation you signed on to. For batch (and other types of) jobs you can specify your own job name. You can specify a generic name using an '*'. Thus 'QPDA*' selects all job names that begin with 'QPDA'.

If you leave this field blank, it is not used for filtering.

User Profile

For interactive jobs, the user name is the name you entered in the user field on the signon screen. for batch jobs, you can specify the user profile under which the job is to run. You can specify a generic name using an '*'. Thus 'Q*' selects all jobs whose user name begins with 'Q'.

If you leave this field blank, it is not used for filtering.

Job Number Range

The job number is a unique number assigned by the system to identify jobs. There are two fields that can be used for filtering: a from field, that specifies that all job numbers greater or equal to this field are selected, and a to field, that specifies that among all job selected so far, only those with job numbers smaller or equal to this field are further selected.

If you leave the 'from' field blank there is no lower limit. If you leave the 'to' field blank there is no upper limit.

You can use generic job numbers if you like or just use zeroes, i.e. '024*  ' is the same as '024000'.

Job Type

  • A Autostart job
  • B Batch job
  • I Interactive job
  • M Subsystem monitor
  • R Spooling reader
  • S System job
  • W Spooling writer
  • X Start CPF job
If you specify a value, only jobs of that type are selected.

Filename/Member

Select a file to monitor, or a group of files using a generic filename like 'FIL*'. If the member field is set to *YES, show the member name instead of the filename.

Note that logical files are not shown. Spool files, display files, and other physical files can be monitored. This version of the File Monitor only monitors the 'classical' QSYS filesystem.

Library

Only files in the library specified will be monitored. You can use a generic name to specify a group of libraries all beginning with the same characters. QTEMP, *CURLIB, and *LIBL cannot be used as it is not clear what job they should refer to.

I/O Count & Condition

The I/O Count is the total number of all I/O operations performed on a file since the file was last opened. You can place a condition on the count such as to see only files for which the count is greater than the value given. The possible conditions are:
  • or *GT Greater than
  • >= or *GE Greater than or equal
  • or *LT Less than
  • <= or *LE Less than or equal
  • == or *EQ Equal
  • != or *NE Not equal

Note that '=' is accepted for '==' and '<>' is accepted for '!='.

Last Operation

You can select files based on the last operation performed on the file, e.g. 'W*' will select WRITE and WRT/READ. Possible values are:
  • READ     Read
  • RD/DIR   Read Direct
  • RD/KEYED Read Keyed
  • WRITE    Write
  • WRT/READ Write then Read
  • UPDATE   Update
  • DELETE   Delete
  • OTHER    Other operations
  • OPEN     Open

Note that the operation refers to the last operation on the file. The I/O count refers to the total of all operations.

See Display Files

If you want to see Display Files in addition to physical files, set the field to *YES.

Jobs Started Hours Ago

Several jobs are started when the system is IPLed. These jobs may continue to run indefinitely. You can elect to see only jobs started later. These recent jobs may be the most interesting. Specify the maximum age (in hours) of a job in this field to only see jobs no older that this. Specify *ALL to see all jobs regardless of age.

No files found

No files matched the filtering criteria. Try to relax some of the filter items. If you have 'See Display Files' set to *NO, try setting it to *YES.

Refresh Rate

Enter the number of seconds (at least 2 is recommended) in this field to set the interval between successive automatic refresh of the file information. When the information is refreshed the script is executed if enabled.

Confirmation?

Set this field to *YES if you want a confirmation screen to appear when you exit the 'Work with Settings' screen. This setting is recommended, especially if a script is active as you may decide whether or not to execute the script immediately upon return.

Script Enable

Set this field to *YES to enable execution of a script every time the file information is refreshed. The name of the script is given in the following field.

If the 'Test script' field further down the screen is set to *YES, the setting of the 'Script enable' field is irrelevant, as the script is always executed in test mode, which means that script statements are executed, but that commands are not carried out.

If the field is set to *NEW, it is changed to *YES and the script is read anew.

For more information click on
SCRIPT-TEST: Testing the Script

Script Member

All scripts are stored as members in the source file XUSFILES. If the script is not found (or the member name is blank, but a script is enanbled), an error is indicated and the previous script (if any) is still in effect.

Script Library

If this field is blank, the script files are searched for in the library where the File Monitor is installed, otherwise the library given is used. You can use either a specific name or *CURLIB or *LIBL.

Script Test

If this field is set to *YES, the 'Script enable' field is ignored and the script is executed in test mode, where internal test information is output to the source member given by the 'Test member' field. The member is in the same file and library as the script member.

When in test mode, script statements are executed as usual except that commands are not executed.

Script Test Member

Test output goes to this member which should be in the same file and library as the script.

Executing a script has three phases:

  • 1.Reading the script and building a table of the tokens found in the script. A token is like a number, a variable name, an operator (like +), a keyword (like IF), a parenthesis, and so on.
    The token-table is output to the test output member on one line to a token and terminated by a line of "-----"s.
  • 2.Parsing the token-table into "postfix" form, where all parentheses are removed and operators are reordered so they have the proper order for execution. Consider the statement A = D*(B + C);
    The postfix form looks like this A D B C + * = ;
    Operators (like +) work on their operands (like B and C) to their left in the postfix form.
    The postfix-table is output to the test output member on one line per item and terminated by a line of "====="s.
  • 3.Executing the postfix form once for each file that survives the filtering process.
    The result of the evaluation is output to the test output member on one line per item and terminated by a line of "*****"s for each file.
The first two phases are only executed when the File Monitor starts or when a new script is explicitly called for.

Script Test Clearing

If this field is *YES, the testoutput member is cleared (if test is active) when the script is read anew.

Script Errors

If an error is encountered during execution of a script, the script is disabled until you correct the error. The error type and line number in the script where the error was detected is shown on the message line. These are the error types:
  • Type
    An operand is used in a way incompatible with its type. Like comparing a string to a numeric type, or using an assignment within an IF-condition, e.g. IF ($file = "MYFILE") which should have been: IF ($file == "MYFILE")
  • Syntax
    A statement has grossly incorrect syntax
  • Assign
    Assigning an incomplete expression or having an expression on the left-hand side, like a+b=c. The error may sometimes be on the following line
  • Structure
    The structure of a statement is wrong. This is often caused by missing or extra parentheses
  • Undefined
    Undefined variable or operator is used
  • Command
    Invalid command or error occurred executing a command
  • Not Found
    The script was not found

Demo Expired

Following a fourteen-day trial period, the File Monitor requires a License Code to run. The License code is tied to the machine's serial number. Having procured a license code for your system, enter the code into the License code field on the third page of the 'Settings' screen, and the File Monitor works again.

When you enter a license code, the trial period is considered to be expired. If you entered an invalid license code by mistake, you can clear the license code field and continue the trial.

License Code

Following a fourteen-day trial period, the File Monitor requires a License Code to run. The License code is tied to the machine's serial number. Having procured a license code for your system, enter the code into this field, and the File Monitor works again.

If you need to install File Monitor temporarily on a different system, you automatically get a new two-week trial period on that system, even if you don't have a license code for the system.

Confirming Settings

You have three choices:
  • 1. Accept the settings, return to showing the file information and immediately refresh the information. This entails executing the script if it is enabled.
  • 2. Cancel all changes to the settings.
  • 3. Accept the settings and return to showing the file information, but without refreshing the file information and thus without executing the script.
The settings are stored in a data-area XUCMNPAR in the library where the File Monitor is installed. You cannot edit the data-area. The only way to change it is with the 'Work with Settings' screen.


Work with Scripts (XUPARSER)

All scripts are stored as members in the source file XUSFILES. Script files are by default searched for in the library where the File Monitor is installed. In the 'Settings' you can specify a library name or *CURLIB or *LIBL.

Executing a script has three phases:

  • 1.Reading the script and building a table of the tokens found in the script. A token is like a number, a variable name, an operator (like +), a keyword (like IF), a parenthesis, and so on.
  • 2.Parsing the token-table into "postfix" form, where all parentheses are removed and operators are reordered so they have the proper order for execution. Consider the statement A = D*(B + C);
    The postfix form looks like this A D B C + * = ;
    Operators (like +) work on their operands (like B and C) to their left in the postfix form.
  • 3.Executing the postfix form once for each file that survives the filtering process.
The first two phases are only executed when the File Monitor starts or when a new script is explicitly called for.

Errors
If an error is encountered during execution of a script, the script is disabled until you correct the error.

Data Types

The script parser recognizes the following data types:
  • Commands:  {SNDMSG MSG('message') TOUSR(QSECOFR)}
  • Numbers:   123.456  153   -313
  • Strings:   'Hello'   " T e x t "
  • Variables: $file  my_var  Ab123
  • Truth values: a == b  x > 1.234
Variables are declared simply by assigning something to them. They get (and keep) the type of the quantity assigned to them. E.g. Ab123 = "a string" declares variable Ab123 of type 'string' and value "a string". Variable names are not case sensitive, so that Ab123, ab123, aB123, and AB123 denote the same variable.

Commands have a maximum length of 120 characters. This is not a 'hard' limit and can be expanded at the cost of slower execution. 'White spaces' (that is, multiple spaces and end-of-record) when occurring within commands (but not in strings) are replaced with a single space.

Strings are as long as their last non-blank character, up to a maximum length of 120 characters (not counting the enclosing quotes). Numeric variables are internally kept as ZND(15,5). The numbers you see have been converted to an external representation where trailing and leading zeroes are suppressed. This is the so-called "calculator" style. By example, the result of 123000 divided by 10000 shows as 12.3 while 0.0012 times 10000 shows as 12 so you can see that decimal points and decimals only show when needed. The result of the ** operator is calculated internally in floating point and rounded to 5 decimal places.

Truth values are the results of comparisons and cannot be directly produced, i.e. there are no TRUE or FALSE literals. You can store the result of a comparison as a truth-valued variable:
A = $file == 'MYFILE1' or $file == 'MYFILE2'.

Commands can contain replaceable parameters. A construction of the form <xxxx> where xxxx is the name of a variable, will be replaced by the value of that variable (if defined, otherwise just by the name of the variable):

IF ($user == "BADGUY") {SNDMSG MSG('<$user> is using        <$file>') TOUSER (DBGUY)};

Operators

The script parser recognizes the following operators (in decreasing precedence order, that is, with operations to be performed first at the top of the list. The number next to the operator is its precedence value - operators with higher values are performed before operators with lower values):
  • ** 10 Exponentiation: x**2
  • 09 Multiplication: x*y
  • 09 Division: x/y
  • 09 Remainder: x%y
  • 08 Addition: x+y
  • 08 Subtraction: x-y
  • == 07 Compare equality: x==y
  • != 07 Compare not-equal: x!=y
  • 07 Compare greater: x>y
  • >= 07 Compare greater-equal: x>=y
  • 07 Compare less: x<y
  • <= 07 Compare less-equal: x<=y
  • =? 07 Compare contains: x=?y
  • 06 Relational AND: x&y
  • 05 Relational OR: x!y
  • 03 Substring: x:y
  • 01 End of statement: ;

The order of operations can be controlled in the usual manner with suitable parentheses: A = B + C*D, means: first multiply C and D, then add B, finally assign the result to A, while A = (B + C)*D means: first add B and C, multipy the result by D, finally assign the result to A.

Note that '<>' may be used instead of '!=', 'and' may be used instead of '&', and 'or' may be used instead of '!'. This is partly motivated by the fact that '!' sometimes is translated incorrectly from ASCII to EBCDIC.

Note also that 'and' has a higher precedence than 'or'. This means that 'A and B or C' is executed as '(A and B) or C'.

The Contains Operator
The '=?' operator works on strings and is true if the right-hand operand is contained anywhere within the left-hand operand. I.e. "MYLIB" =? "YL" is true while "MYLIB" =? "XL" is false.

The Substring Operator
The ':' operator works on a position and a length operand applied to a string operand to their left. Example: sss = "abcdefgh" (3:2); sets sss = "cd", the position being 3 and the length being 2.

The Addition Operator
The '+' operator can also be used on strings and then denotes concatenation: A = "my"; B = A + " string"; places "My string" in the variable B.

Predefined Variables

Predefined variables ordinarily have names beginning with a '$' sign. This is just a convenience and you can also use such names of your own. The predefined variables are updated each time the script is executed, so that, for example, $file contains the name of the particular file for which the script is evaluated right now.

These are the predefined variables:

  • $system Name of the AS/400 system
  • $now    Now as YYYY/MM/DD HH:MM:SS
  • $device Job name (device for interactive jobs)
  • $name   Same as $device
  • $user   User name
  • $job    Job number (type is string)
  • $type   Job type
  • $file   File name
  • $member Member name
  • $library Library name
  • $operation Last operation
  • $count  Total I/O count (numeric type)
  • $records Number of records when opened (numeric)
  • $size   Size of member in Kbytes (numeric)
  • $kind   Kind of file: DS, DB, or SP
  • $calls  Calls of the script (numeric)

The '$size' variable is only set for database files ($kind="DB") and will be set to zero for all other kind of file. The size reported is only approximate and is determined when the file was opened. It is calculated as 'Number of records' times 'Maximum record length'. The reason for this is that this information is available from the ODP and is thus very fast to retrieve. The size reported when you press F20 is retrieved by the much slower QUSRMBRD API.

The '$calls' variable is set to zero when the script is read and is incremented by one each time the file information is refreshed while a script is enabled.

Comments

Comments are delimited by '/*' and '*/' and may span several lines. Comments are simply ignored. Note that strings, commands, and comments should not overlap. The parser guards against 'run-away' comments, commands, and strings by inserting end-symbols for each of these at the end of the file.

Statements

Each statement must be terminated by a semicolon (";"). These are the types of statements:
  • Assignments   A = 2.34; B = "ABC";
  • IF-Statements IF (truth-value) command;

Statements are 'free form' and can span several lines with blank space where convenient;

IF-Statements must have an expression in parenthesis that determines a truth-value. If the value is TRUE, the command is excuted. Remember that commands are enclosed in curly brackets: {...}. E.g.
  IF ($file =? "ADM" and $user == "BRADLEY")
      {SNDMSG MSG('bad') TOUSR(QSECOFR)};

Commands can only be executed as part of an IF-Statement. IF-Statements cannot execute assignments. (Maybe we'll relax these two restrictions in later versions).


Help for Help (XUHELPER)

There is help for every screen and for many fields. To get help on a field place the cursor in the field and press F1. To get general help for the screen place the cursor outside of a field, e.g. on the Screen Title and press F1.

The Help text (member FILMON in source file XUSFILES) is written in HTML and can (after downloading to a PC) be viewed with a browser or imported into a Word document for easy printing.

The XU-Help Processor (XUHELPER) reads the Help text and formats it to fit this Help window.

Function keys

F1=Help
Pressing F1 shows this screen. The F1=Help function key prompt does usually not appear on the screens. To see display a help topic place the cursor on it and press Enter.

F3=Exit help
Press F3 to exit the Help.

F5=Refresh - not shown on screen
Press F5 to refresh the help text.

F11=Index
Press F11 to see an Index of Help topics. When on the Index-page, press F3 to exit Help.

F12=Cancel
Return to the previous screen.

F17=Move to top
Returns you the first help page on the current topic.

Error Message
If an error message is shown on the message line, press F1 to get specific help for that message.


Index of Help Topics

Click on a topic:

VERSION: Version Information
INSTALLATION: Installation Information
XUFILMON: Work with File Information
FILTER ON OFF: Turning Filtering On/Off
JOB/DEVICE: Filter on Job Name or Device
USER PROFILE: Filter on User Profile
JOB NUMBERS: Filter on Job Numbers
JOB TYPE: Filter on Job Type
FILE NAME/MEMBER: Filter on File/Member
FILE LIBRARY: Filter on Library
IO COUNT CONDITION: Filter on I/O Count
LAST OPERATION: Filter on Last Operation
SEE DISPLAY FILES: See Display Files too
JOBS STARTED HOURS: Filter on Job Start Time
NO FILES: Help on 'No files..." error msg
REFRESH RATE: Help on 'Refresh rate'
CONFIRMATION: Confirmation flag
SCRIPT-ENABLE: Help on Enabling Scripts
SCRIPT-MEMBER: Name of Script Member
SCRIPT-LIBRARY: Name of Script Library
SCRIPT-TEST: Testing Scripts
SCRIPT-TEST MEMBER: Where testoutput goes
SCRIPT-TEST CLEAR: Clearing test member
SCRIPT-ERRORS: Errors in Script
LICENSE CODE: License Code
DEMO EXPIRED: Demo Expired
DAYS LEFT: Days Left of Demo Period
ACTIVE JOBS: Jobs Currently Active
SET CONFIRM: Confirmation screen
XUPARSER: Work with Scripts
DATA TYPES: Script Data Types
OPERATORS: Script Operators
PREDEFINED: Script Predefined Variables
COMMENTS: Script Comments
STATEMENTS: Script Statements
XUHELPER: Help on Help
HELP NOT FOUND: When no Help is available


Help Not Found

No help page defined yet for this screen or field