The DIARY User's Manual
Welcome to The DIARY
====================
The DIARY is a program that allows you to select one or more JOBs on your
system and record every move made by each JOB. You may monitor up to 30 JOBs
on your system at once with The DIARY. For each JOB you choose to monitor,
you may completely dictate exactly how The DIARY should record the actions of
the JOB. For example, you can watch seven JOBs "like a hawk" and "casually
scan" five others. And it's quick - The DIARY will seem transparent to all
of your normal daily operations.
When a JOB runs The DIARY, the program will create statistics files in the
PPN where the JOB is currently logged. These files are in a compact format.
You cannot type these files out directly. However, there is a quick
conversion program that will take a statistics file created by The DIARY and
convert this information into a legible ASCII file that you may then TYPE,
VUE, or PRINT.
Loading Your New Software
=========================
The DIARY is very flexible. One of the neat features of The DIARY is that
the JOB running DIARY.LIT may be logged into any PPN on your system. One of
the better locations for this JOB would be off of DSK0: since this disk is
overloaded on most systems (remember: the program creates files in the PPN
where the JOBS is logged). As for disk space requirements, you will find
there is a lot of information that The DIARY may store in a relatively small
space. However, if you are going to push The DIARY to its limits, you might
want to locate the JOB on a disk that has some ample free space.
Suppose you choose DSK2:[300,0] as the location where the JOB running The
DIARY will be logged ( we will assume this location for the remainder of the
documentation ). Perform the following:
1) .LOG DSK2:[300,0]
2) .VCRRES = ALL:[]
1) DIARY.LIT - The actual monitoring program.
2) DIARY.INI - A sample initialization file for DIARY.LIT.
3) STSLST.LIT - The statistics ---> ASCII conversion program.
4) STSLST.CTL - A sample control file for the Task Manager.
Running The DIARY
=================
1) Understanding and Modifying the DIARY.INI File
In order for The DIARY to know exactly how each chose JOB on your system
should be monitored, the program reads in a file called DIARY.INI. This file
contains two basic parts. The first part of the file (the first three lines)
must never be removed from the file . The second part of the file consists
of one or more "paragraphs" - one paragraph for each JOB chosen to be
monitored.
Below is a sample DIARY.INI file - the same sample you have received on
the VHS cassette. You will need to modify this file to suit the needs of
your own system. This sample file is set up to inform The DIARY to watch two
JOBs on the system: JOB2 and PHONE. All text presented in BOLD indicates
"do not modify". All text in ITALICS indicates variables that may be
modified to meet the needs of your system.
Two notes: 1) Do NOT have any spaces following any of the "=" signs.
2) You may have up to 30 "paragraphs" (only 2 are shown in this
example).
NUMBER OF JOBS=2
NUMBER OF SCANS PER WRITE=3
NUMBER OF 1/2 SECOND SLEEP INTERVALS=2
JOB=JOB2
START HOUR=8
STOP HOUR=17
CPU SENSITIVITY=5
REALTIME=N
LOCATION=Y
PROGRAM=Y
READS=N
WRITES=N
CPU TIME=Y
JOB=PHONE
START HOUR=6
STOP HOUR=24
CPU SENSITIVITY=1
REALTIME=Y
LOCATION=Y
PROGRAM=Y
READS=Y
WRITES=Y
CPU TIME=Y
Let's look at each line of the DIARY.INI file in depth. The numbers
listed on the far right indicate allowed ranges of each line.
Listed Once at the Top of the File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NUMBER OF JOBS= (1...30)
This line informs The DIARY of the total number of JOBs that will be
monitored at any one time. Each time you add a new JOB to the DIARY.INI
file, you must change this running count of the number of JOBs. This
number should match the number of "paragraphs" (one per JOB) in the
DIARY.INI file.
NUMBER OF SCANS PER WRITE= (1...255)
This number indicates how many times The DIARY will cycle through your
system scanning the appropriate JOBs and store the desired statistics in
memory before the program writes this information permanently to the
statistics files.
NUMBER OF 1/2 SECOND SLEEP INTERVALS= (1...255)
This value indicates how long the JOB running The DIARY will sleep before
awaking to check the system statistics. If "hawk-like" monitoring is
desired, this value should be small. In a more casual monitoring
environment, this value may be higher. Not that the lower the value, the
more CPU time The DIARY will consume.
Listed For Each JOB Defined to The DIARY
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
JOB= (valid JOB name)
For each JOB you've chosen to monitor, you must supply The DIARY with the
corresponding JOB name. JOB order does not matter, and SYSTAT will
produce all valid JOB names if you are not sure what each JOB on your
system is named.
START HOUR= (1...24)
This line indicates to The DIARY the hour in which you would like to begin
recording the actions of the particular JOB. "24" represents 12:00 am,
"14" represents 2:00 pm, etc. You may only indicate integer values on
this and the following line.
STOP HOUR= (1...24)
As with the START HOUR above, this line informs The DIARY when monitoring
should cease. Not that in order to monitor a JOB from 11:59pm through
12:01am, your START HOUR would actually be greater than your STOP HOUR.
CPU SENSITIVITY= (1...255)
This line determines how closely The DIARY will monitor the JOB by
examining the CPU time that the JOB has used. Each value of "1" indicates
a sensitivity value of approximately 8 "jiffies" - a very small unit of
time. If the CPU time used by the JOB has changed by at least the amount
of "jiffies" indicated, The DIARY will record the current statistics of
the JOB. In simpler terms, to "watch like a hawk" enter a "1", to briefly
scan, enter a larger number - the larger the number, the less times The
DIARY will record the current status of the JOB.
REALTIME= (Y/N)
If you desire to have The DIARY record the real time of day each time is
scans the JOB, then this line should contain a "Y". Placing an "N" on
this line will tell The DIARY to disregard the real time of day.
LOCATION= (Y/N)
If this line contains a "Y", then each time The DIARY scans the JOB it
will record the DSK:[P,PN] where the JOB is currently logged. An "N" on
this line will disregard the logged disk location when scanning.
PROGRAM= (Y/N)
This line determines whether or not The DIARY should take note of the
program begin run by the JOB at the time of the scan. Placing a "Y" on
this line will record the program being run, an "N" will bypass program
recording. A nice feature of The DIARY is that if the JOB is "still
running" the same program as the last time The DIARY looked at this JOB,
The DIARY will not repeat the information to avoid redundancy. When the
JOB begins a new program, The DIARY will pick up from there. This makes
it easy for you to examine how long a user was running a particular
program!
READS= (Y/N)
This line determines whether or not The DIARY will record the current
number of disk reads that the JOB has performed. A "Y" will have The
DIARY record the disk reads, an "N" will info9rm The DIARY to bypass
recording disk reads.
WRITES= (Y/N)
This is very similar to READS above. If you desire The DIARY to record
the number of disk writes a JOB has made, enter a "Y" on this line. If
recording disk writes are not desired, then enter an "N".
CPU TIME= (Y/N)
If recording the current total CPU time is desired, then a "Y" on this
line will inform The DIARY to record the running total. If the current
total of CPU time is not desired, then place an "N" on this line.
2) Modifying Your AMOSL.INI File
The DIARY can run on any one JOB on your system. However, The DIARY can
run just as well from a "mini" JOB setup on your system that does not occupy
a terminal or a port. In order to create such a JOB, you must make some
modifications to your system initialization file. To do so, perform the
following steps:
1) .LOG SYS: |RETURN|
2) .COPY DTEST.INI=AMOSL.INI |RETURN|
3) .VUE DTEST.INI |RETURN|
and add the following lines in the correct places:
a) Increase the line JOBS by one
b) Add a JOBALC {jobname} line
c) Add a TRMDEF {trmname} line
d) Where you attach terminals to JOBs, add:
ATTACH trmname * , jobname *
KILL jobname *
FORCE jobname *
MEMORY 15K
LOG DSK2:[300,0] *
|RETURN|
WAIT jobname *
(The * indicates a value defined by the User)
4) > F inish from VUE and enter
.LOG OPR:
5) Test the new initialization file by typing
.MONTST AMOSL,DTEST.INI
If there is an error in DIARY.INI, the JOB running The DIARY will
create a file titled DIARY.ERR and return to monitor level ("the
dot"). Type out the file DIARY.ERR to examine the error within the
DIARY.INI file.
6) If MONTST works and there are no errors, then enter
.RENAME AMOSL.OLD=AMOSL.INI
.RENAME AMOSL.INI=DTEST.INI
3) Initiating The DIARY
To start The DIARY at any time, simply type from any location on your
system
.FORCE jobname DIARY
where "jobname" is the JOB assigned to The DIARY.
4) Stopping The DIARY
To stop The DIARY at any time, simply type from any location on your
system
.KILL jobname
where "jobname" is the JOB running The DIARY.
5) Examining a JOB's Statistics File
The DIARY will create a unique statistics file for the JOB being
monitored when it first starts to record the actions of the particular
JOB. The filename of each statistics file is in the format of
JOBNAME.STS. If a statistics file for a JOB already exists, The DIARY
will append any new information to this file.
Statistics files are in a compact format. In order to examine the
information from within a statistics file, you need to run a program
called STSLST. This program will convert a "JOBNAME.STS" file into a
"JONAME.LST" file quickly and accurately. To perform the conversion,
simply enter
.STSLST jobname
where "jobname" is the name of the ".STS" file you would like converted.
Once this conversion is complete, you may erase the "old" statistics
file since all of the information in this file is now in a legible ASCII
format. Daily erasing of all *.STS files after conversion to *.LST
files will increase the accuracy of each report and decrease the amount of
CPU time The DIARY will consume.
If you would like to generate "daily reports" via the Task Manager,
there is an easy way to do this. Simply modify the supplied STSLST.CTL
file to match the names of the JOBs listed in your DIARY.INI file. Then
submit this file to the Task Manager. For example, to have the Task
Manager convert all of your statistics files to list files every night at
10:00pm, enter
.SUBMIT STSLST/PR1:1/AFTER:0-0-0,10:00 PM/NEXT:0-1-0/PERMANENT/RESTART
NOTES:
1) You may only have one paragraph per JOB you choose to monitor.
2) It is best to run STSLST only when The DIARY does not have a chance to
modify or update the corresponding statistics file.
3) You may start The DIARY at any time. No restrictions apply here.
4) If security is a problem, place The DIARY in an account that contains a
unique Project number (the first P in [P,PN]), and then place a password
on this account via SYSACT. See the AMOS System Commands Reference
Manual for details.
5) Avoid big statistics files. Update statistic files on a regular basis
with STSLST. Erase the old statistics files after conversions to
minimize disk occupancy and speed up the performance and accuracy of The
DIARY.
6) Although no more than 30 JOBs are allowed, if you have the NUMBER OF
SCANS PER WRITE fairly low in value, you may actually monitor more than
30 JOBs on the system. The value 30 is stated to ensure proper function
of The DIARY no matter what value is contained in the NUMBER OF SCANS PER
WRITE.
7) When an update is available, BolderBITS will inform you of the new
version release. There is no cost to you for an update. Simply mail
BolderBITS a VHS cassette, and the update will be shipped back to you.
8) If there is an error in DIARY.INI, the JOB running The DIARY will create
a file titled DIARY.ERR and return to monitor level ("the dot"). Type
out the file DIARY.ERR to examine the error within the DIARY.INI file.
9) AMUS appreciates any bug reports, hints, or suggestions to make The
DIARY clear to the end user or to "squash" any known bugs. Please feel
free to call AMUS with any positive criticism or comments.