═══ 1. Notices ═══ Pegasus Tools Version 1.10 (c) 1993,1994 C.O.L. Systems Inc. All Rights Reserved PegRexx (Pegasus Rexx Extension) Version 1.10 (c) 1993,1994 C.O.L. Systems Inc. All Rights Reserved C.O.L. Systems Inc. has been in the business of software development and consulting since 1987. Our software has, and will continue to be, geared towards performance and capacity management needs. From the standalone OS/2 station tools (Pegasus Resource Monitor and Pegasus Tools) to heterogenous performance and capacity management (Osrm2*), we continue to meet the users needs in sophisticated, low price, software. *Osrm2 (c) 1991,1994 C.O.L. Systems Inc. Other Notices OS/2 is copyright by IBM Corporation. Contact and Support We have moved to a new location with new phones as well: Mailing Address: C.O.L. Systems Inc. 10 Watergate Drive Amawalk, NY. 10501 Telephone Numbers for: Voice - (914) 245-0442 FAX - (914) 245-0452 BBS - (914) 245-1561 ═══ 2. License and Warranty ═══ License Agreement and Warranty Disclaimer You should carefully read the following terms and conditions before using this software. Use of this software indicates your acceptance of these terms and conditions. If you do not agree with them, do not use the software. The term Pegasus Tools refers to: o AppMon Application Activity Monitor o FileMon File Activity Monitor o CacheMon Cache Activity Monitor o PegRexx Pegasus Tools Log Post Processor Rexx Extension Shareware Version You are hereby licensed to: use the Shareware Version of the software for a 21 day evaluation period; make as many copies of the Shareware version of this software and documentation as you wish; give exact copies of the original Shareware version to anyone; and distribute the Shareware version of the software and documentation in its unmodified form via electronic means. There is no charge for any of the above. You are specifically prohibited from charging, or requesting donations, for any such copies, however made; and from distributing the software and/or documentation with other products (commercial or otherwise) without prior written permission from C.O.L. Systems Inc. Unregistered use of Pegasus Tools after the 21-day evaluation period is in violation of federal copyright laws. Evaluation and Registration This is not free software. This license allows you to use this software for evaluation purposes without charge for a period of 21 days. If you use this software after the 21 day evaluation period a registration fee is required as described in Registration Forms. Quantity discounts are available, see the apporirate order form for details. One registered copy of Pegasus Tools may be dedicated to a single person who uses the software on one or more computers or to a single workstation used by multiple people. You may access the registered version of Pegasus through a network, provided that you have obtained individual license for the software covering all workstations that will access the software through the network. Governing Law This agreement shall be governed by the laws of the State of New York. Disclaimer of Warranty This software and the accompanying files are sold "as is" and without warranties as to performance of merchantability or any other warranties whether expressed or implied. Because of the various hardware and software environments into which this program may be put, no warranty of fitness for a particular purpose is offered. Good data processing procedure dictates that any program be thoroughly tested with non-critical data before relying on it. The user must assume the entire risk of using the program. Any liability of the seller will be limited exclusively to product replacement or refund of purchase price. ═══ 3. Registration Forms ═══ Registering Pegasus Tools C.O.L. Systems Inc. will accept MasterCard, or Visa Credit Cards. C.O.L. Systems Inc. will accept checks or Money Orders in US funds only. After printing the appropriate form, mail it in with your payment ( or fax it if registering by Credit Card ). o For General Registration, print and fill in the information and fax or mail the REGISTER.DOC file. C.O.L. Systems Inc. maintains a Pegasus message and file area for registered users on it's BBS @(914) 245-1561. o For Os/2 Shareware BBS users, print, fill in the information and fax or mail the OS2SHARE.DOC file. C.O.L. Systems Inc. maintains a Pegasus file area for registered users. Once we receive registration we will notify you via Os/2 Shareware private e-mail with the password to this file area. o For Pyramid/2 BBS users, print, fill in the information and fax or mail the REGISTER.DOC file. C.O.L. Systems Inc. maintains a Pegasus file and message area for registered users. Once we have received registration we will have the Pyrmaid/2 sysop update your security level to proivde access to these areas. ═══ 4. APAR Notices ═══ The following are APARS and associated fixes that may be required to run the Pegasus Resource Monitor or Pegasus Tools. These fixes are available from the IBM Corporation. The following APARs apply to OS/2 2.0 plus Service Pak 1. o PJ06434 - Disk Device Driver The fix concerns a problem where disk timers were getting corrupted. The following APARs apply to either OS/2 2.0 plus Service Pak 2 or OS/2 2.1. o PJ08459 - Occasional negative values for Process Page Fault Time. Page Fault time is a metric which measures how much time a thread has spent waiting on a page fault. This metric is part of the thread resource group. On a heavily loaded machine, this timer can go negative briefly. o PJ09410 - Trap E when collecting thread data on a busy system. On a heavily loaded managed system with excessive thread activity, there is a potential for a TRAP E to occur while collecting application/process/thread level data. To avoid this trap, obtain the selective fix for APAR PJ09410. o PJ09893 - Trap D on dirty HPFS disk. If you have HPFS installed, you may experience a trap D in OS2KRNL while collecting data. The trap occurs if chkdsk was run during config.sys time. If you experience this problem, obtain the selective fix for APAR PJ09893. o PJ10475 - A variety of traps in OS2KRNL During data collection on a heavily loaded machine. APAR PJ10475 fixes these traps. o APAR PJ10476 and PJ10275. If you start and stop data collection more than 140 times without rebooting, OS/2 stops returning data. To avoid this symptom, obtain the selective fix for APAR PJ10275 or PJ010476. ═══ 5. What is the Pegasus System? ═══ The Pegasus System Is set of 32 bit application: The Pegasus Resource Monitor is a kernel level, real-time, Presentation Manager monitoring tool for system and application resource usage under OS/2 2.x. Including a configurable sample rate, thresholds settings, exception notification and logging, as well as graphical indicators, the Pegasus Resource Monitor provides the most comprehensive monitoring tool for OS/2. The Pegasus Tools utilities are a number of system measurement and reporting utilities designed to provide detailed insight of system resource activity through intensive monitoring, log collection and post processing reports (PegRexx). These utilities include: o AppMon o FileMon o CacheMon Additional information can be found in: o General Menu Options o Command Line Options o Demo Restrictions o History Of Changes o Frequently Asked Questions For information on post processing of the Pegasus Tools monitor output files refer to the PEGREXX.INF file. ═══ 6. Common Options ═══ Following are options that are available for all three of the Pegasus Tools utilities. ═══ 6.1. Menu Options ═══ All of the Pegasus Tools utilities have the ability to save session settings so that you can quickly recall them without having to remember how you set up a previous session. This becomes valuable when you want to record multiple data logs that maintain the same sample criteria. For example, if testing Cache effectiveness you would take one sample with CacheMon, possibly change the size of the FAT or HPFS cache, and re-run Cachemon with the same frequency and options as set for the first run. You could then compare the two outputs. The save and load options place no restrictions on the filenames used to store the information. Each of the tools can detect if a selected file for input is in fact a Pegasus Tools configuration file. If you load an existing configuration file you need only click the Start button to begin collection. Refer to Command Line Options for additional information. The save and load options can be invoked from the File menu action on each of the utilities. ═══ 6.2. Command Line Options ═══ All of the Pegasus Tools utilities support the following optional command line options: TOOLNAME -M filename Examples: AppMon -m will start the Application Monitor in a minimized state. FileMon theFiles.CfG will start the File Monitor, load the configuration file THEFILES.CFG and automatically invoke the collection engine. CacheMon -m cachechk.001 will start the Cache Monitor, minimize the CacheMon main window, load the configuration file CACHECHK.001 and automatically invoke the collection engine. ═══ 7. AppMon ═══ There are many utilities which provide general OS/2 application information, as well as a number of code profilers. There was not, until now, an affordable utility which can track detailed application activity at the thread and file level without inside knowledge of the application code. AppMon is designed to provide the user with the following features: o The ability to monitor and capture statistics for: 1. A single instance of an application. 2. Multiple instances of an application. 3. Children processes of the monitored application. 4. Individual Application Thread(s) or Application File(s) activity, or both. 5. System CPU statistics. o Granularity between measurements: 1. From 1 second to 44 minutes 59 seconds. o Duration of measurements: 1. Until the application ends. 2. Manually stopped by user. 3. Timed monitoring from 1 minute to 23 hours 59 minutes. Detailed information can be found in: o Setting Up A Session ═══ 7.1. Setting Up A Session ═══ The following is the AppMon configuration and status panel. Descriptions for each of the controls can be found after the picture. o Setup Options Setup define the characteristics for the monitor session. 1. Application Name This field is used to identify the application you want to monitor. You must supply at least the application name and extension, for example: NMAKE.EXE 2. Use Log File This check box indicates that you want to use the log file selected with the Set Log control. This is optional and if left blank AppMon will track activity without writing statistics to disk. 3. Set Log This button will invoke a file dialog box which allows you to name the output log file. 4. Frequency The frequency option has two controls, minutes and seconds. These control how often measurement snapshots are taken and optionally written to the log file if named. The range for frequency is from 1 second to 44 minutes and 59 seconds. Note: Some data samples may be lost if you set a very high frequency on very active systems. In general, higher frequencies will flatten out detail statistics which may not be desired. Samples of 1 minute or less are suggested for performance reporting. 5. Duration The duration option has two controls, hours and minutes. These control how long measurements are to be taken. If duration is set at 0, data will be recorded until manually stopped or if the application being monitored ends. If you set the duration to any other value, the application will continued to be monitored until any of the following events occur: a. The duration expires. b. The application being monitored ends. c. The session is manually stopped. The range for duration is from 1 minute to 23 hours 49 minutes. Note: The duration must be larger than the frequency or an error message will generated. 6. Single This checkbox controls whether or not AppMon will track the first or all instances of the named application that it finds during the session. By default AppMon is set to track a single instance of the named application. 7. Children This checkbox controls whether or not AppMon will track children processes spawned by the named application. By default AppMon is set to ignore any children processes of the named application. 8. Threads This checkbox controls the collection and logging of active thread information for the named application(s) and any children if the Children option is set. By default AppMon collects thread information. 9. Files This checkbox controls the collection and logging of accessed files information for the named application(s) and any children if the Children option is set. By default AppMon collects file information. 10. System CPU This checkbox controls the collection and logging of system wide CPU information. If set, AppMon will display the average system CPU by sample on the CPU Gauge control at the bottom of the window. By default AppMon collects CPU information. o End Of Run Options End of run options determine the actions that should be taken when the specified application exits the system. Some of these options are goverened by the Single and Children settings. 1. Default If set the default is based on the following rules: a. Single Instance with Children - AppMon will wait until any running children processes have ended as well. It will then close the log. b. Single Instance with No Children - AppMon will close the log. c. Multiple Instance with Children - AppMon will wait until all instances and children have ended before closeing the log. d. Multiple Instance with No Children - AppMon will wait until all instances have ended before closeing the log. 2. Automatically Close The Auto Close is based on the following rules: a. Single Instance with Children - AppMon will close the log when the parent process has ended. b. Single Instance with No Children - AppMon will close the log. c. Multiple Instance with Children - AppMon will wait until all parent instances have ended before closeing the log. d. Multiple Instance with No Children - AppMon will wait until all instances have ended before closeing the log. 3. Prompt For Close The user will be prompted to close the log or continue based on the following rules: a. Single Instance with Children - AppMon will wait the parent ends and then prompt to continue monitoring children if there are children running, otherwise it will close the log. b. Single Instance with No Children - AppMon will close the log. c. Multiple Instance with Children - AppMon will wait until the parent ends and the prompt to continue monitoring multiple instances if there are multiple instances running, otherwise it will close the log. d. Multiple Instance with No Children - AppMon will wait until the parent ends and the prompt to continue monitoring multiple instances if there are multiple instances running, otherwise it will close the log. o Start Once the information in the Setup area is complete, this button will invoke the Pegasus Tools collection engine and begin monitoring. o Stop Once collection has started, this button becomes available to manually stop the session at any time. o Application List When the collection engine detects the occurrence of the named application(s) or children, if the Child option is set, it will display the fully qualified path for that process in this list box. When any process ends, and it's name is in the list, it will be removed from the list. o Files List Any files that are opened for the named application(s) or children, if the Child option is set, will be displayed in this list box. As files are closed they will be removed from the list. o CPU Gauge If the System CPU option is set, the collection engine will update this gauge at each frequency sample. o Samples This field will be updated with the number of samples at each snapshot interval. ═══ 8. FileMon ═══ There are many utilities which provide general OS/2 disk/file information There was not, until now, an affordable utility which can track detailed physical disk and file activity. FileMon is designed to provide the user with the following features: o The ability to monitor and capture statistics for: 1. Physical Disk I/O activity 2. Logical disk File I/O Activity 3. File I/O by Application. 4. System CPU statistics. o Granularity between measurements: 1. From 1 second to 44 minutes 59 seconds. o Duration of measurements: 1. Manually stopped by user. 2. Timed monitoring from 1 minute to 23 hours 59 minutes. Detailed information can be found in: o Setting Up A Session ═══ 8.1. Setting Up A Session ═══ The following is the FileMon configuration and status panel. Descriptions for each of the controls can be found after the picture. o Setup Options 1. Use Log File This check box indicates that you want to use the log file selected with the Set Log control. This is optional and if left blank FileMon will track activity without writing statistics to disk. 2. Set Log This button will invoke a file dialog box which allows you to name the output log file. 3. Frequency The frequency option has two controls, minutes and seconds. These control how often measurement snapshots are taken and optionally written to the log file if named. The range for frequency is from 1 second to 44 minutes and 59 seconds. Note: Some data samples may be lost if you set a very high frequency on very active systems. In general, higher frequencies will flatten out detail statistics which may not be desired. Samples of 1 minute or less are suggested for performance reporting. 4. Duration The duration option has two controls, hours and minutes. These control how long measurements are to be taken. If duration is set at 0, data will be recorded until manually stopped. If you set the duration to any other value, FileMon will continued to monitor until any of the following events occur: a. The duration expires. b. The session is manually stopped. The range for duration is from 1 minute to 23 hours 49 minutes. Note: The duration must be larger than the frequency or an error message will generated. 5. Files This checkbox controls the collection and logging of all accessed file information. By default FileMon collects file information. 6. Physical Disk This checkbox controls the collection and logging of physical disk activity. By default FileMon collects physical disk information. 7. System CPU This checkbox controls the collection and logging of system wide CPU information. If set, FileMon will display the average system CPU by sample on the CPU control at the bottom of the window. By default FileMon collects CPU information. o Start Once the information in the Setup area is complete, this button will invoke the Pegasus Tools collection engine and begin monitoring. o Stop Once collection has started, this button becomes available to manually stop the session at any time. o Disk List As the collection engine detects physical local disks, their id (0-23) will be displayed in this list box. o Files List Any files that are opened on the system will be displayed in this list box. As files are closed they will be removed from the list. o CPU Gauge If the System CPU option is set, the collection engine will update this gauge at each frequency sample. o Samples This field will be updated with the number of samples at each snapshot interval. ═══ 9. CacheMon ═══ There has not been, until now, an affordable utility which can track detailed cache (FAT/HPFS) statistics for OS/2. CacheMon is designed to provide the user with the following features: o The ability to monitor and capture statistics for: 1. FAT Cache Activity. 2. HPFS Cache Activity. 3. System Memory/Paging Activity. 4. System CPU statistics. o Granularity between measurements: 1. From 1 second to 44 minutes 59 seconds. o Duration of measurements: 1. Until the application ends. 2. Manually stopped by user. 3. Timed monitoring from 1 minute to 23 hours 59 minutes. Detailed information can be found in: o Setting Up A Session ═══ 9.1. Setting Up A Session ═══ The following is the CacheMon configuration and status panel. Descriptions for each of the controls can be found after the picture. o Setup Options 1. Use Log File This check box indicates that you want to use the log file selected with the Set Log control. This is optional and if left blank CacheMon will track activity without writing statistics to disk. 2. Set Log This button will invoke a file dialog box which allows you to name the output log file. 3. Frequency The frequency option has two controls, minutes and seconds. These control how often measurement snapshots are taken and optionally written to the log file if named. The range for frequency is from 1 second to 44 minutes and 59 seconds. Note: Some data samples may be lost if you set a very high frequency on very active systems. In general, higher frequencies will flatten out detail statistics which may not be desired. Samples of 1 minute or less are suggested for performance reporting. 4. Duration The duration option has two controls, hours and minutes. These control how long measurements are to be taken. If duration is set at 0, data will be recorded until manually stopped. If you set the duration to any other value, FileMon will continued to monitor until any of the following events occur: a. The duration expires. b. The session is manually stopped. The range for duration is from 1 minute to 23 hours 49 minutes. Note: The duration must be larger than the frequency or an error message will generated. 5. Memory 6. FAT Cache 7. HPFS Cache 8. System CPU This checkbox controls the collection and logging of system wide CPU information. If set, CacheMon will display the average system CPU by sample on the CPU Gauge control at the bottom of the window. By default CacheMon collects CPU information. o Start Once the information in the Setup area is complete, this button will invoke the Pegasus Tools collection engine and begin monitoring. o Stop Once collection has started, this button becomes available to manually stop the session at any time. o CPU Gauge If the System CPU option is set, the collection engine will update this gauge at each frequency sample. o Resident Memory Gauge If the Memory option is set, the collection engine will update this gauge with the percent of total memory that is resident. Resident memory is non-discardable and non-pageable. o Used Memory Gauge If the Memory option is set, the collection engine will update this gauge with the percent of total memory that is in use at the sampe time. o FAT Cache Effectiveness Gauge If the FAT Cache option is set, the collection engine will update this gauge with the percentage of cache accesses ( Hits plus Misses ) where the desired data was found ( Hits ). o HPFS Cache Effectiveness Gauge If the HPFS Cache option is set, the collection engine will update this gauge with the percentage of cache accesses ( Hits plus Misses ) where the desired data was found ( Hits ). o Memory and Paging Indicators If the Memory option is set the collection engine will update these text indicators with: 1. Memory - The total memory (in megabytes) found on the system as reported by OS/2. 2. Page In - The number of Page In events during the past snapshot interval. 3. Page Out - The number of Page Out events during the past snapshot interval. o Samples This field will be updated with the number of samples at each snapshot interval. ═══ 10. Demo Restrictions ═══ If this version of Pegasus Tools is the demo suite, then the following restrictions are imposed: 1. The Save configuration and Load configuration menu options are disabled. 2. Command line parameters and drag drop of configuration files are ignored. 3. The Log File name will be set to PTOOL. If you have set this control differently it will be reset before the collection engine starts. 4. The Frequency setting will not go above 10 seconds or below 5 seconds. If you have set this control differently it will be reset before the collection engine starts. 5. The Duration setting will not go above 2 minutes or below 1 minute. If you have set this control differently it will be reset before the collection engine starts. 6. The Stop button will be disabled ever during the active collection. 7. The following options are effected in the demo suite: o If you are running AppMon: a. Only a Single instance of the specified application is tracked. b. Children processes are not tracked. c. Threads are tracked. d. File and System CPU are not tracked. o If you are running FileMon: a. Files are tracked. b. Physical Disk and System CPU are not tracked. o If you are running CacheMon: a. FAT and HPFS Cache are tracked. b. Memory and System CPU are not tracked. Note: These retstrictions do NOT apply to the registered version of Pegasus Tools. ═══ 11. History Of Changes ═══ The following are a list of changes for the product in general, as well as changes that apply to the registered version and demo suite version. The most recent changes will be inserted at the top of the list. o Version 1.10 1. Converted all tools to integer collector engine. 2. Reworked log file to accept any location. 3. New packaging now includes PegRexx.Dll and PegRexx.Inf. o Version 1.0 1. Complete PEGLOG log post processor, including Level 3 support. 2. Online documentation. (This file). o Registered Version 1. Added command line options. 2. Activated the Save and Load File menu options. o Demo Suite 1. Increased the frequency and duration time limits. ═══ 12. Frequently Asked Question (FAQ) ═══ This section will provide answers to many of the questions asked about the Pegasus Tools. We will organized the questions into relative sections and made reference to supporting areas of the Pegasus Tools when applicable. ═══ ═══ Where TOOLNAME is one of the following: o AppMon o FileMon o CacheMon ═══ ═══ When this option is specified on the command line, the Pegasus Tools utility will start minimized. ═══ ═══ When filename is used, the Pegasus Tools utility will load the filename specified as a configuration file and automatically start the collection session. Note: You can also drag a configuration file onto one of the Pegasus Tools utilities. Just make sure that you add %* to the Parameters field of the setting notebook for each tool you want this functionality to exist for.