═══ 1. Notices ═══ Pegasus Resource Monitor Pegasus Tools PegRexx 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 stand alone OS/2 station tools (Pegasus Resource Monitor and Pegasus Tools) to heterogeneous 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. 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 Other Notices OS/2, OS/2 REXX, and DB2/2 are copyright by IBM Corporation. ═══ 2. 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, working set analysis, kill process options, 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. These utilities include: o AppMon o FileMon o CacheMon o PEGREXX !!! ═══ 3. PegRexx ═══ PegRexx PegRexx provides a REXX interface for processing the output logs created by the Pegasus Tools utilities. Why PegRexx? 1. Although the Pegasus Tools package contains a generic post processor (PegLog), we have released PegRexx to allow users to developer their own output. 2. Many users have indicated that they would like to feed data from the Pegasus Tools log files directly into IBM DB2/2 and other database management system that support REXX. 3. Some users are interested in creating value added applications for the Pegasus user base. 4. I thought it would be cool. The remainder of this document focuses on how to use PegRexx and create your own REXX processors for Pegasus Tools output logs. You can jump to the following topics from here: o Installation o REXX Housekeeping o Functions o The Stem Variable o Sample Procs ═══ 4. Installation ═══ Installing the PegRexx REXX Extension DLL For access to the PegRexx functions through the OS/2 REXX proc interface, you need to make the PEGREXX.DLL visible. This can be accomplished in one of three ways: 1. Copy the PEGREXX.DLL file to a path already setup in your config.sys LIBPATH statement. 2. Create a new DLL path for the PEGREXX.DLL and add the path to the LIBPATH statement in your config.sys file. This option will require that you reboot your machine. 3. Run all REXX procs that use the PEGREXX.DLL from the same directory where you have placed this file. Your choice. ═══ 5. REXX Housekeeping ═══ Before using any of the PegRexx functions, you must make the DLL entry points known to the OS/2 REXX interface. Before exiting a REXX proc, which has loaded the PegRexx extension, it is good practice to exit in an orderly fashion if possible. The following code fragments can can be used for any REXX proc you create that uses PegRexx. Each line is discussed following the example: Housekeeping Fragments /***************************************/ /* Pegasus Log Rexx Extension */ /* Version 1.0 */ /* (c) 1993,1994 C.O.L. Systems Inc. */ /* All Rights Reserved */ /***************************************/ /************************/ /* Load the extension */ /************************/ 001: if RxFuncQuery('PegLoadFunctions') <> 0 then do 002: rcy = RxFuncAdd('PegLoadFunctions','PEGREXX','PegLoadFunctions'); 003: if rcy = 0 then do 004: rcy = PegLoadFunctions(); 005: if rcy > 0 then signal BadLoad; end; 006: else do signal BadAdd; end; end; /* Your code goes here! */ /************************/ /* Drop the extension */ /************************/ 007: rcx = PegDropFunctions(); 008: call RXFUNCDROP 'PEGLOADFUNCTIONS'; 009: exit; Explanation of Fragment 1. Here we use the OS/2 REXX function RxFuncQuery which tells us if the PegRexx function entry points have already been loaded. If not, the execution falls to line 2, otherwise the PegRexx functions are already resident and we skip past the startup code. 2. Here we use the OS/2 REXX function RxFuncAdd to add the PegRexx function PegLoadFunctions to the REXX interface. This adds ONLY one function entry point. Notice the PEGREXX argument, this directs REXX to the DLL that has the requested function. 3. We check for a successful return code. If good we continue to line 4, otherwise we drop to line 6 which will signal a load error routine not shown. 4. The PegLoadFunctions function loads all other PegRexx function entry points such as PegLoadFile, etc. If the function returns a successful completion code of zero (0), we are now ready to use the PegRexx functions. 5. A nonzero return code invokes an error handler which exits the REXX proc. 6. Code invokes an error handler which exits the REXX proc. We are here if the RxFuncAdd failed. 7. This call invokes another PegRexx entry point whose job it is to release all of the other PegRexx function entry points except the PegLoadFunctions call. 8. We drop the PegLoadFunctions call. 9. Exit the REXX proc. ═══ 6. Functions ═══ This section describes the PegRexx functions available to the REXX developer. We have aimed at simplicity without sacrificing functionality. If there is anything that you think would be a valuables addition to PegRexx let's hear it! Entry point Load and Unload Functions Before using any of the PegRexx functions, you must make the DLL entry points known to the OS/2 REXX interface. Before exiting a REXX proc, which has loaded the PegRexx extension, it is good practice to exit in an orderly fashion if possible. PegLoadFunctions PegDropFunctions Log Handling Functions It doesn't take much to load the log files created by the Pegasus Tools utilities, actually it only takes one call: PegLoadFile Date and Time Stamp Functions If you have looked at the section on how PegRexx populates the stem variable passed to the PegLoadFile function you will have noticed reference to the Time and Date stamp on the data record. Here are two functions that can be used to convert this variable to a number of different time and date string formats: GetDate GetTime Metric Classification Functions Originally put in as a means of self documentation, we found that with a little manipulation we could have this function assist in the construction of data group metric stem variables. PegMetric ═══ 6.1. GetDate ═══ GetDate ( options , TDS ) GetDate returns the date and time information derived from the Time and Date Stamp (TDS) in the format: dayname mon day hh:mm:ss yyyy (for example, Tue Jan 25 23:29:42 1994), For mon and dayname, the first three characters of the English name of the month and day will be used. The following options (of which only the capitalized letter is needed, all others are ignored) can be used to obtain alternative formats: European Returns date in the format: dd/mm/yy. Language Returns date in an implementation and language dependent or local date format. In the OS/2 operating system, the Language format is dd Month yyyy. If no local format is available, the default format is returned. Month Returns full English name of the current month, for example, August. Ordered Returns date in the format: yy/mm/dd (suitable for sorting, and so on.) Sorted Returns date in the format: yyyymmdd (suitable for sorting, and so on.) Usa Returns date in the format: mm/dd/yy Weekday Returns the English name for the day of the week, in mixed case. For example, Tuesday. Here is an example: do count = 1 to Stem.Records say GetDate(,Stem.Records.count.TDS); say GetDate('O',Stem.Records.count.TDS); say GetDate('U',Stem.Records.count.TDS); end; ═══ 6.2. GetTime ═══ GetTime ( 'M' , tds ) GetTime returns the date and time information derived from the Time and Date Stamp (TDS) in the format: dayname mon day hh:mm:ss yyyy (for example, Tue Jan 25 23:29:42 1994), For mon and dayname, the first three characters of the English name of the month and day will be used. The following options (of which only the capitalized letter is needed, all others are ignored) can be used to obtain alternative formats: Civil Returns hh:mmxx, the time in Civil format, in which the hours may take the values 1 through 12, and the minutes the values 00 through 59. The minutes are followed immediately by the letters "am" or "pm" to distinguish times in the morning (midnight 12:00am through 11:59am) from noon and afternoon (noon 12:00pm through 11:59pm). The hour will not have a leading zero. Hours Returns number of hours since midnight in the format: hh (no leading zeros). Minutes Returns number of minutes since midnight in the format: mmmm (no leading zeros). Seconds Returns number of seconds since midnight in the format: sssss (no leading zeros). Normal Returns the time in the default format hh:mm:ss. Here is an example: do count = 1 to Stem.Records say GetTime(,Stem.Records.count.TDS); say GetTime('S',Stem.Records.count.TDS); say GetTime('N',Stem.Records.count.TDS); end; ═══ 6.3. PegDropFunctions ═══ PegDropFunctions ( ) The PegDropFunctions function deregisters all of the PegRexx function entry points from the REXX interface. Once this function is called you will be unable to call any of the PegRexx functions. The function will return '0' if no errors occured, otherwise it is the error code returned from the REXX API call to deregister the function. Here is an example: rcx = PegDropFunctions(); if rcx == 0 then say 'PegRexx functions no longer available'; else say 'Unable to deregister PegRexx functions'; ═══ 6.4. PegLoadFunctions ═══ PegLoadFunctions ( ) The PegLoadFunctions function registers all of the PegRexx function entry points to the REXX interface. Once this function is called you will be able to call any of the PegRexx functions. The function will return '0' if no errors occured, otherwise it is the error code returned from the REXX API call to register the functions. Here is an example: if RxFuncQuery('PegLoadFunctions') <> 0 then do rcy = RxFuncAdd('PegLoadFunctions','PEGREXX','PegLoadFunctions'); if rcy = 0 then do rcy = PegLoadFunctions(); if rcy > 0 then signal BadLoad; end; else do signal BadAdd; end; end; ═══ 6.5. PegLoadFile ═══ PegLoadFile ( 'file' , 'stem.' ) The PegLoadFile function loads the Pegasus Tools utility log file and populates the specified stem. variable. Note: You must include the period '.' on the stem variable as well as enclosing the entire argument in quotes in order for the function to correctly build the resulting stem tree. For a full description of the stem variable refer to Stem Variable. This function returns a zero (0) completion code if no errors where detected. Here is an example which assumes the PegRexx functions have been registered: MyStem. = ""; Parse Arg FileFrmCmdLine rcx = PegLoadFile( FileFrmCmdLine, 'MyStem.' ); if rcx == 0 then do /* Your code goes here */ end; ═══ 6.6. PegMetric ═══ PegMetric( 'group', index , 'D' ) The PegMetric returns various information about the Pegasus data group. If called with just the group name, this function will return the count of data metrics that may be used on the stem to retrieve data. If index is specified then the function will return the metric name for that index. If the 'D' option is also supplied, the a short description will be returned for the metric specified in index. For group names that have no meaning, the error 'UNKNOWN' will be returned. For indexes that accede the number of metrics, the error 'BOUNDS' will be returned. Here is a way to generate a group metric listing: count = PegMetric('CPU'); say; say 'CPU metrics and descriptions. Number of metrics = 'count; say; do items = 1 to count say left(PegMetric('CPU',items),14)' 'PegMetric('CPU',items,'D'); end; Here is a way to have a self generating report: PegLoadFile(MyFile,'Data1.'); metcnt = PegMetric('FIL'); /* Get for later calls */ do count = 1 to Data1.Records do fcount = 1 to Data1.Records.count.FIL do mcount = 1 to metcnt dataRef = 'Data1.Records.'||count||'.FIL.'||fcount||PegMetric('FIL',mcount); say 'File 'PegMetric('FIL',mcount)' = 'value(dataRef); end; end; end; ═══ 7. Stem Variable ═══ This section describes how PegRexx populates the Stem variable passed to the PegLoadFile function. The Stem Graphic shows each of the stem variables and combinations that may contain data once the log file has been read. Both the root stem and leaf identifiers are linked to footnotes describing in detail their meaning. ═══ 7.1. Stem Graphic ═══ Following is the Stem layout graphic. For detailed information, double click on any of the highlighted items. All of the items refer to Stem. which you would substitute for the name of the REXX compound variable you use with the PegLoadFile. Stem. │ ├─── FileName │ ├─── Title │ ├─── Creator │ ├─── Resources │ │ │ └── Resources.N │ └──┬─── Records │ │ ├─── Applications │ | │ └── Applications.N │ │ │ ├─ Name │ │ │ └─ PID │ │ ├─── Files │ | │ └── Files.N │ │ │ ├─ Name │ │ │ ├─ PID │ │ │ └─ UID │ ┌──┘ │ Record.N │ │ ├─── TDS │ │ ├─── MT │ │ ├─── CPU │ │ ├─── MEM │ │ ├─── FC │ │ ├─── HC │ │ ┌────────────────┴────────┬─────────────────────────┐ │ │ │ DSK FIL THD | | | +--+--+ +--+--+ +--+--+ | | | | | | DSK.1 DSK.N FIL.1 FIL.N THD.1 THD.N For details on each data group and their individual metrics, run the DATADICT.CMD file. ═══ 8. Sample Procs ═══ This section describes the sample REXX procs included with the PegRexx OS/2 REXX extension. o DataDict.Cmd - This proc can be used to generate a full listing of all the data group metrics and a short description of each. o CpuSamp.Cmd - This proc can be used with the log file from any of the Pegasus Tools utilities that had the System Cpu track option set. The proc expects the name of the log file as input from the command line. o MemSamp.Cmd - This proc can be used with the log file from the CacheMon utility if the Memory track option was set. The proc expects the name of the log file as input from the command line. o FcSamp.Cmd - This proc can be used with the log file from the CacheMon utility if the FAT Cache track option was set. The proc expects the name of the log file as input from the command line. o IOSamp.Cmd - This proc can be used with the log file from the FileMon utility if the Files track option was set. The proc expects the name of the log file as input from the command line. ═══ ═══ Usage Syntax: Stem. The Stem. variable is the REXX compound variable that you pass to the PegRexx PegLoadFile function. PegRexx uses this to store all the information processed from the Pegasus Tools log input. This also provides a means to load more than one log file at a time using unique stem variable names. ═══ ═══ Usage Syntax: Stem.FileName The Stem.FileName variable contains the filename passed to the PegRexx PegLoadFile function. ═══ ═══ Usage Syntax: Stem.Title The Stem.Title variable contains the title placed in the log by the Pegasus Tools utility that created it. ═══ ═══ Usage Syntax: Stem.Creator The Stem.Creator variable contains the numeric ID of the Pegasus Tools utility that created it. Possible values are: o AppMon = 1 o FileMon = 2 o CacheMon = 3 ═══ ═══ Usage Syntax: Stem.Resources The Stem.Resources variable contains the number (count) of metric group flags found in the information header of input log file. This count can be used to setup a loop control for interrogating which metric resources were selected with the log creating utility. See Stem.Resource.N for additional information. ═══ ═══ Usage Syntax: Stem.Resources.N The Stem.Resources.N, where 1 <= N <= Stem.Resources, contains the text string group name of resources that were flagged as collected in the Pegasus Tools utility that created the log. ═══ ═══ Usage Syntax: Stem.Records Contains the count of the number of data stem records attached to the stem variable. Each record contains the detail data information for the measurements collected by the creating utility. Each individual record is addressed by: Stem.Records.N where 1 <= N <= Stem.Records. ═══ ═══ Usage Syntax: Stem.Applications Contains the count for the number of unique application entries in the Application Table. ═══ ═══ Usage Syntax: Stem.Applications.N.variable The Stem.Applications.N, where 1 <= N <= Stem.Applications, is a stem variable for each application entry in the Application Table. For each application entry, the following variables are present: o Application Name - Name o Application Process ID - PID ═══ ═══ Usage Syntax: Stem.Applications.N.Name This variable contains the application name string for the application entry. ═══ ═══ Usage Syntax: Stem.Applications.N.PID This variable contains the process identifier (PID) for the application entry. ═══ ═══ Usage Syntax: Stem.Files Contains the count for the number of unique file entries in the File Table. ═══ ═══ Usage Syntax: Stem.Files.N.variable The Stem.Files.N, where 1 <= N <= Stem.Files, is a stem variable for each file entry in the File Table. For each file entry, the following variables are present: o File Name - Name o Owner Process ID - PID o Unique ID - UID ═══ ═══ Usage Syntax: Stem.Files.N.Name This variable contains the file name string for the file entry. ═══ ═══ Usage Syntax: Stem.Files.N.PID This variable contains the process identifier (PID) for the application that owns the file in the File Table. This can be used as a cross reference lookup into the Application Table. ═══ ═══ Usage Syntax: Stem.Files.N.UID This variable contains the unique identifier (UID) for the file. This can be used as a lookup argument when processing the file metric groups in each record to resolve file names. ═══ ═══ Usage Syntax: Stem.Records.N.TDS Contains the time and date stamp that this record was created by the creating Pegasus Tools utility. This value can be used with the PegRexx functions GetDate and GetTime. ═══ ═══ Usage Syntax: Stem.Records.N.MT Contains the number of milliseconds for the sample interval between the last record and this. ═══ ═══ Usage Syntax: Stem.Records.N.CPU Contains a Boolean (0 or 1) flag which indicates the presence of the CPU group metrics in this record. Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.MEM Contains a Boolean (0 or 1) flag which indicates the presence of the MEM group metrics in this record. Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.THD Contains the number of thread group metrics attached to this record. Each individual thread group metric is addressed by: Stem.Records.N.THD.X.metric where: 1 <= N <= Stem.Records 1 <= X <= Stem.Records.N.THD Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.FIL Contains the number of file group metrics attached to this record. Each individual file group metric is addressed by: Stem.Records.N.FIL.X.metric where: 1 <= N <= Stem.Records 1 <= X <= Stem.Records.N.FIL Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.DSK Contains the number of physical disk group metrics attached to this record. Each individual disk group metric is addressed by: Stem.Records.N.DSK.X.metric where: 1 <= N <= Stem.Records 1 <= X <= Stem.Records.N.DSK Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.FC Contains a Boolean (0 or 1) flag which indicates the presence of the FAT Cache group metrics in this record. Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group. ═══ ═══ Usage Syntax: Stem.Records.N.HC Contains a Boolean (0 or 1) flag which indicates the presence of the HPFS Cache group metrics in this record. Refer to the PegRexx PegMetric function to determine how many metrics, each of their REXX variable names, and a description of the metric contained in this group.