 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.


.
