═══ 1. Introduction ═══ IBM System Performance Monitor/2 ServicePak WR06075 IBM PTF WR06075 This ServicePak applies to: IBM System Performance Monitor/2 Verson 2.0 For use with OS/2 2.0 with XR06055, or OS/2 2.1 Note: SYSLEVEL.SPM must be present in the product directory tree. It will be left in Read_Only mode. SPMINST /Uninstall will not remove Read_Only files. ═══ 1.1. Trademarks ═══ The following are trademarks of IBM Corporation: o IBM o OS/2 o Operating System/2 o Presentation Manager o NetView o System Performance Monitor/2 o THESEUS2 o CICS OS/2 o DB2/2 The following are registered trademarks of Novell, Inc.: o NetWare o Novell o NetWare Requester for OS/2 ═══ 2. Installation ═══ Installing the ServicePak is essentially a three phase process: Phase 1 - Quiesce the Target System Render the system serviceable by insuring that there will be no Locked Files during the install phase. Refer to Quiese Section for details. Phase 2 - Install the ServicePak Select one of the following methods to replace system files with those provided on this ServicePak. Interactive Install Basic Install Redirected (CID) Install Phase 3 - Return the Serviced System to Normal Operation Perform a normal system boot. ═══ 2.1. Quiescing System Performance Monitor/2 ═══ Locked Files cannot be replaced by either Installation Aid, SERVICE.EXE or FSERVICE.EXE. Both will inform the user that Locked Files are present before replacing any files. To prepare the System Performance Monitor/2 for service: Type SPMNBL /HALTALL. This will halt data collection. Type SPMNBL /STOPLISTEN. This will stop SPM and its background processes. On Monitoring Systems: o Stop all Monitoring Sessions o Close any use of the On Line References for SPM/2 o Close the SPM/2 Control Panel ═══ 2.2. Interactive Install ═══ SERVICE.EXE is a Presentation Manager application that will apply fixes to selected subsystems, local partitions, and directories. After the user completes the selection panels, it will scan the target system for Locked Files that need to be replaced. If any exist, the Application is in Use panel is presented with two options: Retry Implies that the user will take the necessary actions to quiesce the target system and then select the Retry button Reboot Implies that the user intendes to reboot from diskette or in such a way as to render the system servicable. Choosing Reboot records the drive and directory selections in a response file on the boot drive. After reboot, FSERVICE.EXE can use this response file to complete service. Step by Step 1. Ensure that SPM/2 is quiesced. 2. Insert ServicePak diskette #1 in drive A:. 3. Establish A: as the Current Directory. 4. At the A: prompt type "SERVICE" and press Enter. 5. Make selections from the panel. 6. Reboot the system normally. ═══ 2.3. Basic Install ═══ FSERVICE.EXE is full screen Installation Aid that will apply service to the program product's default directory tree. FSERVICE.EXE can run under a minimal OS/2 system, like OS/2 booted from diskette, and supports redirected installation. If Locked Files are encountered, it stops with a full screen error panel (SCF0161: Locked Files) and a list of offending file names. Step by Step - Diskette Based 1. Ensure that SPM/2 is quiesced. 2. Insert ServicePak diskette #1 in drive A:. 3. Establish A: as the Current Directory. 4. At the A: prompt type "FSERVICE" and press Enter. 5. At the panel titled "Updating Default Directories" press Enter (Option 1) 6. Follow the prompts provided by the Installation Aid. 7. Reboot the system normally. ═══ 2.4. Redirected Installation (CID) Method ═══ This method is useful for those who are using the CID (Configuration, Installation, and Distribution) Services as provided by IBM NTS/2. While setting up a CID server is beyond the scope of this document, we have provided a sample CID Utility REXX Command file (CID_6075.CMD) that may prove useful in setting up a CID server for this ServicePak. The sample .CMD file assumes the following: o CID_6075.CMD resides in the ..\CLIENT subdirectory. o The ServicePak files are placed on the code server using "XCOPY A:\*.* /S" (or equivalent) at 'x:\csd\6075' where 'x:' is the drive seen by the client. o The following directory structure contains the ServicePak contents. csd\6075\ * Root directory of ServicePak csd\6075\FIX * No files csd\6075\FIX\SPM * System Performance Monitor/2 Fixes o A log directory exists at 'x:\log\csd\6075' for the log files ═══ Locked Files ═══ Sometimes it is essential that programs own (become the master of) system resources such as Memory Blocks, Communication Ports, and Files. When a program stakes claim to a file, that file is said to be Locked; no other program is allowed to alter (replace or write to) it until the owning program explicitly removes the lock. Some files can take a while to become unlocked after being closed. For example, SPMSNAPL.EXE can take a while to quiesce. ═══ 3. APAR Fixes for Prerequisite Products ═══ This section describes known APARS in prerequisite products for which you may want to obtain fixes. These APAR fixes are recommended, but not required. If you encounter any of these problems, you should obtain the related fix from your IBM Service Representative. ═══ 3.1. OS/2 APARS ═══ SPM/2 2.0 requires one of the following operating systems: o OS/2 2.0 plus Service Pak 1 o OS/2 2.0 plus Service Pak 2 o OS/2 2.1 For Japan, OS/2 J2.00.1 is a prerequisite to running SPM/2 2.0. For Korea and Taiwan, please contact an IBM representative for the required version of OS/2. ═══ 3.1.1. OS/2 2.0 plus Service Pak 1 APARs ═══ The following APARs apply to OS/2 2.0 plus Service Pak 1. o PJ06434 - Disk Device Driver There is a fix to the performance hooks in the OS/2 Disk Device Driver (OS2DASD.DMD) that is needed for SPM/2 2.0, but did not make it into OS/2 2.0 Service Pak 1. (The fix concerns a problem where timers were getting corrupted.) Hence, a replacement for the Service Pak 1 version of OS2DASD.DMD is being provided with SPM/2 2.0. The SPM/2 installation program (SPMINST.EXE) will automatically ensure that your system has a version of OS2DASD.DMD that contains the fix needed for proper execution of SPM/2 2.0. That is, if the date of your OS2DASD.DMD indicates that it is older than the one being supplied with SPM/2 2.0, an updated OS2DASD.DMD will be copied to your system. If your system contains a version that is newer than being provided with SPM/2 2.0, no copy will occur. o PJ06435 - Possible Trap D when monitoring large number of remote systems There is a fix for the OS2KRNL that is needed for SPM/2 2.0 that did not make it into the OS/2 2.0 Service Pak 1. The fix concerns a Trap D in the SPMILOG component of SPM/2 that may occur if you are collecting thread or file data. To avoid this problem, a selective fix for APAR PJ06435 is required. o PJ06906 - vdh_RegisterPerfCtrs API call doesn't work. The vdh_RegisterPerfCtrs API call is not supported in the retail OS2KRNL that shipped with Service Pak 1, but it is supported in the debug version. However, in the debug version, the order of the parameters is mixed up, causing unpredictable results. The fix for this APAR is required if you are writing or using a DOS virtual device driver which contains SPM/2 user metrics. ═══ 3.1.2. OS/2 2.0 plus Service Pak 2 and OS/2 2.1 APARs ═══ The following APARs apply to either OS/2 2.1 plus Service Pak 2 or OS/2 2.1. o PJ08459 - Occasional negative values for THD.tmFault. THD.tmFault is a metric which measures how much time a thread has spent waiting on a page fault. This metric is part of the THD resource group. On a heavily loaded machine, this timer can go negative briefly. It will right itself quickly. The fix for this APAR is only recommended if you are writing your own application to look at this value. SPM/2 does not use this value in any of its reports. 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 with SPM/2. 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 and hangs in OS2KRNL may occur during SPM/2 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 SPM/2. The data collection process continues, but no data is received. To avoid this symptom, obtain the selective fix for APAR PJ10275 or PJ010476. ═══ 3.2. Lan Server/Requester 3.0 APARs ═══ The following LAN Requester APARs apply to LAN Server 3.0 plus ServicePak IP07001. o IC05298 Logon is unsuccessful after an SPM/2 monitoring session is started, or after other programs which use remote path names are started. More specifically, if a peer server is recording or graphing from a machine which is not logged on to a domain, that machine will not be able to log on to a domain until the SPM/2 session is terminated. With the fix for IC05298, when the remote machine logs on, the SPM/2 session will be temporarily disconnected. It will reconnect within 5 minutes. o IC05966 NET3190 errors when breaking connection. This APAR is related to the above APAR, IC05298. The fixes for both APARs should be applied together. The problem occurs when a peer server uses SPM/2 to remotely monitor a machine which is not logged on to a domain. With the fix for APAR IC05298, the remote machine can log on to a domain while SPM/2 is monitoring, but the SPM/2 session is temporarily disconnected. The problem described by IC05966 is that when the session is disconnected, several NET3190 errors appear in the LAN error log. The fix for this APAR will eliminate those NET3190 errors. ═══ 4. Things that Changed ═══ Following is a list of bug fixes and new function in version WR06075. The list is broken down by functional component. ═══ 4.1. Installation ═══ The following list describes APARs relating to Installation that are fixed in SPM/2 SYSLEVEL Version WR06075. o IC05202 SPMINST should only install its own version of OS2DASD.DMD if the original OS2DASD.DMD date is less than 10/31/92. You will receive this fix if you are installing SPM/2 for the first time using SPM/2 version 2.0.1 (SYSLEVEL WR06075). This fix does not apply if you are applying CSD WR06075 on top of version WR06000. o IC05460 SPM/2 Version 2.0 will not issue the flag to allow 'call checkboot' to reboot the client after CID installing SPM/2. You will receive this fix if you are installing SPM/2 for the first time using SPM/2 version 2.0.1 (SYSLEVEL WR06075). This fix does not apply if you are applying CSD WR06075 on top of the original version of SPM/2 (SYSLEVEL WR06000). ═══ 4.2. Data collection and logging ═══ The following list describes APARs relating to data collection and logging that are fixed by this Service Pak. o IC05206 SPMDCF allocates and doesn't free memory when collecting thread or file data. o IC05645 Summarization does not work if too many records are collected in one snapshot. This problem can occur if your recording frequency is greater than your collection frequency and you collect application/process/thread level data on a very busy machine. In this case, the data may be logged incorrectly, and the data as shown in a report will be much lower than the actual value. o IC05816 SPM/2 2.0 will generate a high amount of broadcast frames while local monitoring. When starting recording or graphing locally or remotely, an unnecessary broadcast message is sent out across the network, generating an unacceptable amount of network traffic. This broadcast message has been removed. o IC05312 SPM/2 can't monitor machines with hyphens ('-') and other special characters in their machine names. SPM/2 now accepts any machine name that LAN Server will allow. o Other fixes: - Performance improvements have been made in SPMDCF.EXE and SPMILOG.EXE - the processes responsible for collecting and recording data. - The timer which measures the CPU busy time for a thread, THD.tmRun, may have a negative value for one of the SPMDCF.EXE threads on a very busy system. This would appear as a negative value for the CPU Utilization of an SPMDCF.EXE thread in a thread summary report. - SPM/2 assumes that NETBIOS is located on adapter 0. Now SPM/2 will use the NETBIOS resources on the first adapter for which it finds NETBIOS installed. - LAN Requester and Server timers sometimes have negative values. LAN Server 3.0 Advanced and LAN Requester 3.0 timer metrics as reported in an SPM/2 Dump Report occasionally have negative values, especially for very busy servers/requesters. The negative values should not be used. When the values are not negative they are correct. All other LAN Server/Requester metrics are correct. The negative timer metric values will be fixed in a future release of the LAN Server/Requester product. o The fix in LAN Server Advanced will change the definition of the metrics slightly to "the average time for ONE OR MORE requests to be satisfied" and will always be positive. o The fix in LAN Requester will be to no longer support its timer metrics; they will always be zero. - Potential Memory Leak Collecting Thread or File Data A memory leak is memory that is allocated and never freed, even though it is never used again. An SPM/2 2.0 monitored system can have a memory leak under certain conditions. The problem occurs when the SPM/2 Data Collection Facility does not properly handle file and thread birth and death messages from OS/2. This memory leak can occur under the following conditions: o File or Application/Process/Thread resources are collected, AND o A long Collection Frequency is used, AND o The monitored system has a high rate of file open/closes or thread create/deletes. The symptoms of this memory leak are: o Constant paging and continued growth of the swapper.dat file. o The SPM/2 log file grows faster than necessary. o An "Overflow" warning message is logged at the monitored system IF the Message Level has been changed from the default of Error to Warning or Informational. o In a Summary report, some threads or files may be reported that are no longer present, and some threads or files may not be reported. To prevent this memory leak, any monitor session that collects the File or Application/Process/Thread resources should use a short Collection Frequency. Depending on the level of activity at the monitored systems, a Collection Frequency of 5 to 15 seconds is recommended. - Trap D in SPMILOG. A trap D will occur if the drive to which you are logging fills up, and that drive is formatted for HPFS386. ═══ 4.2.1. New function ═══ o A new command line function, SPMLOGFX, has been added that will recover corrupted log files. If a log file is too badly corrupted, SPMLOGFX may not be able to recover it. However, it can recover many log files that were corrupted due to rebooting or shutting down without stopping data collection. Enter SPMLOGFX ? at an OS/2 command line for syntax or refer to the SPM/2 2.0 On-line documentation for help. ═══ 4.3. Graphing ═══ The following list describes APARs for the Graphing component that are fixed by this Service Pak. o IC05203 When the RAM window is not open, the monitor may trap when it attempts to show the total RAM on the non-existent RAM window. This can occur if the graph window is closed with the RAM window closed. The next time the graph is started, the trap will occur. o IC05625 TRAP E in SPMMON. The trap occurs after a period of time when monitoring remotely and the monitored machine goes down for any reason (machine turned off, logged off LAN, etc). With the default collection frequency of 10 seconds, the graph would trap 40 minutes after the monitored machine went down due to an internal buffer overflow. o Other fixes: - SPM/2 will now display an error if you try to start a graph using the same log file more than once, instead of trapping. ═══ 4.4. Reporting ═══ The following list describes APARs for the Reporting component that are fixed by this Service Pak. o IC05092 SPM/2 2.0 Workstation Summary reports do not contain memory utilization or accessed file name information as expected. o Other fixes: - Very large tabular reports fail due to memory segment exceeded. Large log files can generate large reports. If the report is too large, the reporting facility may fail due to a memory segment boundary being exceeded. We have enhanced the reporting facility to handle larger log files and reports than before. However, it is still possible to generate more data than the reporting facility can handle. If this is the case, you will see a message stating that the report is too big and you should reduce your report size by increasing the report summarization interval or reducing the number or workstations or resources. - Can't specify '00' in Report Time Periods panel. In the Report Time Periods panel, the value "00" is valid in any of the fields and means "take the whole thing." Although "00" is valid for the Stop date/time (meaning to use all the data to the end of the .LOG file), if you specify this value and press OK, you will receive an error popup that says: "Invalid start/stop date/times or sum interval." If you press Cancel at this point, the "00" value will be accepted. This has been fixed to work as it should. - Process IDs (PIDs) greater than 32767 display as negative numbers in a Process or Thread level Summary report. This has been fixed to work as it should. ═══ 4.4.1. New function ═══ o A new command line function, SPMRDFI, has been added to allow the creation of report description files (.RDF) from the command line. With this addition, all SPM/2 function can now be performed from the command line. Refer to the SPM/2 2.0 On-line documentation for instructions on how to use this command. ═══ 4.5. Panels and Messages ═══ The following list describes APARs for the Panels and Messages that are fixed by this Service Pak. o IC05693 Query function in Monitor Description panel traps on OS/2 2.1. o Other fixes: - When running SPM/2 2.0 on OS/2 J2.0, SPM/2 incorrectly handled any DBCS character in an entry field which has its second byte in the range of hexadecimal '61' to '79'. The character was translated incorrectly. - Message SPM0049 comes from SPMNBL, not SPMISTRT. - Message SPM0151 displays incorrectly. - The error panel which displays when the user tries to set the collection frequency and multiplier to too large a value is formatted incorrectly. - When defining a new application for an SPM/2 report, not all existing directories appear in the Directory listbox. ═══ 4.6. Documentation ═══ The following list describes APARs for the SPM/2 On-line Documentation that are fixed by this Service Pak. o IC05391 The on-line documentation section on "Monitoring a Network" is incorrect with regards to Peer Services and User Level Security. o IC05397 SPM/2 doesn't document that HPFS386 cache information can only be seen in a dump report. Clarification about this was added to the on-line documentation section on "Specifying Monitor Session Resources: Procedure." o Other fixes: - Clarified the On-line helps description of when to use a workstation name of LOCAL in a monitor session description. - Clarified the on-line documentation description of the SPMAPIInit and SPMAPISet API calls. There was confusion about the use and meaning of -1 as a value for the collection frequency multiplier parameter. - The sample metric definition file in the on-line documentation incorrectly showed data and comments on the same line. Comments must be on their own line, and this has been updated in the on-line documentation. - You must stop data collection with either the command line or SPM control panel to stop the data collection processes. Closing the SPM control panel or the SPM/2 graph does not stop data collection. This has been documented more clearly in the on-line documentation. - In both the On-line documentation and the On-line helps, the description of the Verbose option in the Report Resources panel of a Report Description is wrong. Selecting the Verbose option means that you will see data for all processes and threads, whether they had any activity or not. Not selecting the verbose option means that only processes and threads that had activity will be present in a report. The verbose option applies to Application, Process, or Thread level Summary reports. ═══ 4.6.1. New function ═══ o Added a getting started section to the on-line documentation to help first time users of SPM/2 know where to start. This section is called "SPM/2 Process: Overview". ═══ 4.7. Distributed Feature updates ═══ The following list describes APARs for the Distributed Feature that are fixed by this Service Pak. These updates also apply if you installed the full SPM/2 product. o IC05206 SPMDCF allocates and doesn't free memory when collecting thread or file data. o IC05312 SPM/2 can not query or remotely monitor machines with hyphens '-' or other special characters in the name. SPM/2 now supports any name that is a valid LAN Server computername. o Other fixes: - Minor performance enhancements were made to the Data Collection Facility. - The size of SPMDCF.EXE was reduced by changing some link options. - SPM/2 will now support NETBIOS on the first adapter it finds, rather than only Adapter 0. - The Distributed Feature has been enhanced to support calls to the SPM/2 API. This is especially useful to users of IBM LAN NetView LAN Management Utility for OS/2 (LMU/2), because now only the SPM/2 2.0 Distributed Feature is required on a system from which LMU/2 will collect performance data, instead of the full SPM/2 2.0 product. With SPM/2 Version 1.0, the API to the performance data was at a lower level than in SPM/2 2.0 (at the named pipe interface), and this API was automatically installed with the SPM/2 1.0 Distributed Feature. In SPM/2 2.0, the API provided is at a higher level, and can handle receiving data from multiple managed systems (i.e. multiple named pipes). This interface is now installed as part of the Distributed Feature, as well as with the full product. ═══ 4.8. THESEUS2 ═══ Many enhancements have been made to THESEUS2. These updates are installed if you have installed the full SPM/2 2.0 product. Please read the Changes section of the THESEUS2 On-line reference for a complete list of the changes from version 2.0 to 2.0.1. Some highlights include: o Fix for THESEUS2 trap that occurs when loading the main panel if running on OS/2 2.1. o A REXX API and C API have been added to allow user written programs to retrieve Free Memory, Swapper, and Process information and to perform working set analysis. o A Memory Leak Detection function has been added. o Improvements to the printability of the THESEUS2 On-line documentation have been made. The document now prints in half the number of pages it used to, and it is formatted better for readability. o A LIST3820 version of the THESEUS2 On-line documentation is now available. It will be placed on Compuserve in the OS2DF2 forum, Library 9, and on OS2BBS. o There are many enhancements to the content of the documentation and helps. ═══ 4.9. SPM/2 API ═══ The following list describes problems in the SPM/2 API component that are fixed by this Service Pak. If you installed SPM/2 with the /API option, you will receive these updates. o Problems with 32-bit user applications using the 16-bit SPM/2 API. o SPM/2 API does not support /NOI link option. ═══ 4.9.1. New function ═══ o A sample program which demonstrates how to use the SPM/2 API is now provided. If you installed SPM/2 with the /API option, you will find three new files: - SPMSAMPL.C - SPMSAMPL.MAK - SPMSAMPL.DEF This program is written to be compiled with the Microsoft C 6.0 Compiler. It is not a functioning program due to values that have been hardcoded for demonstration purposes. o Some new options have been added to the SPMAPIQuery call to provide the following information about the contents of a log file: - Resources configured in each start/stop session in the log file. - Time periods (collection frequency, recording frequency, working set interval) configured for collection in each start/stop session in the log file. - Workstations configured to be collected in each start/stop session in the log file. Refer to the SPM/2 2.0 On-line documentation for instructions on how to use these options. o The Distributed Feature has been enhanced to support calls to the SPM/2 API. This is especially useful to users of IBM LAN NetView LAN Management Utility for OS/2 (LMU/2), because now only the SPM/2 2.0 Distributed Feature is required on a system from which LMU/2 will collect performance data, instead of the full SPM/2 2.0 product. With SPM/2 Version 1.0, the API to the performance data was at a lower level than in SPM/2 2.0 (at the named pipe interface), and this API was automatically installed with the SPM/2 1.0 Distributed Feature. In SPM/2 2.0, the API provided is at a higher level - in a routine called SPMILOG.EXE, which is able to handle receiving data from multiple managed systems (i.e. multiple named pipes). This interface is now installed as part of the Distributed Feature, as well as with the full product. ═══ 4.10. User Metrics ═══ The following list describes APARs for User Metrics that are fixed by this Service Pak. o IC05205 SPM/2 2.0 has no method of dealing with multiple versions of metric definitions, as described in the following text. In addition to the predefined OS/2 and LAN Server/Requester metrics which ship with SPM/2, there also can be user defined metrics which are specified in a .SPM file. Running the SPM/2 SPMAPPIN command against user defined .SPM files generates two files - SPMAPP.INI and SPMCTRGP.H. SPMAPP.INI is the binary file which SPM/2 uses to interpret the data it receives from the Data Collection Facility (SPMDCF). SPMCTRGP.H is the include file that programs that write to the SPM/2 API use to understand the data collected. SPM/2 expects that the metric definitions in SPMAPP.INI will match the format of the metrics it receives from the SPMDCF. If a metric definition has changed on some machines but not on others, SPM/2 does not know how to interpret the data from both the old and new definitions. If you have defined your own user metrics, and find the need to change a definition in your Metric Definition (.SPM) file, there are rules that must be followed to ensure that SPM/2 will continue to collect accurate data. - Adding new fields - Any new fields must be defined at the end of their respective groups in the .SPM file, so SPMAPPIN will add them to the end of their corresponding SPMCTRGP.H structures. This allows existing SPM/2 API programs to work without re-compilation since any new fields would now be found after any old fields. - Deleting fields - Old fields must never be deleted from the .SPM file since this would change the position of subsequent fields in the SPMCTRGP.H counter group format. If a metric exists in the .SPM file, but its corresponding data item is deleted from the actual data collected, the Data Collection Facility will zero the space for the missing field and issue a warning every time a program does an SPMAPIGetData and receives that group record. The warning shows up in the fCollErrors field of DCFRECHDR as a value of hexadecimal '10'. Programs that use the SPM/2 API will not need to be updated or recompiled, as long as they can handle the warning message. - Updating fields o Changing a metric name - Changing the name of a data item (the fieldnme in the .SPM file and the var field on the SPMDataItem call) is fine, but the SPM name (fieldtag in the .SPM file) should remain the same so as not to affect user written programs. If you must change the fieldtag, then user written programs must also make the corresponding change. o Changing a metric type - if the fieldtyp must change, (e.g., 'timer' to 'queue') then there is no recourse but to update and/or recompile old programs since none of the defined types behave in a (computationally) compatible manner. If you are changing a type so that the number of required bytes changes (e.g. 4 byte timer to 12 byte queue), you should leave the original metric in place in the .SPM file, and add the new metric to the end of the group. You are essentially not using the old metric and adding a new one. An example of this situation occurred with the THD.tmReady field which was removed from OS/2 before SPM/2 shipped, but the definition was not removed from SPMAPP.INI. This results in a warning every time a user does a SPMAPIGetData and receives a THD group record. The warning shows up in the fCollErrors field of DCFRECHDR as a value of hexadecimal '10'. o Other fixes: The following fixes are in SPMUH286.LIB and SPMUH386.LIB. Any users of these libraries must relink their programs to pick up these fixes. - If a user process registers user hooks, then dies without deregistering, SPM/2 will trap in OS2KRNL when it tries to access that process's data block which is no longer there. To fix this, SPM/2 will deregister the hooks as part of the registering process's exitlist, and additionally, an entry is added to the System Error Log for each hook deregistered this way. - Added a System Error Log message in the case that a user application attempts to deregister more than once. - Added an SPMDeregisterAll function to the SPM/2 User Hook functions so that an exitlist routine can deregister all registered data blocks without getting any entries in the System Error Log. - Fixed a trap that occurs when two threads attempt to initialize at the same time. ═══ 4.11. Configuration recommendations ═══ o LAN Adapter Configuration Changes The Network Interface Card (NIC) in an SPM/2 2.0 Managing or Monitored system may require configuration changes. Lab tests show that communication problems are possible when heavy LAN Server/Requester traffic is combined with SPM/2 2.0 remote monitoring. The solution is to increase the default NIC configuration parameters. The configuration changes can be made using LAPS or by modifying the PROTOCOL.INI file directly. For example, the Token Ring 16/4 Adapter should be configured as: MAXTRANSMITS = 12 RECVBUFS = 10 RECBUFSIZE = 512 XMITBUFS = 10 o NTS/2 NETBIOS Configuration Changes Remote monitoring requires additional NETBIOS resources. See the SPM/2 2.0 on-line reference ("Requirements for Monitoring a Network" in the "Monitoring a Network: Overview" section) for details on parameter and resource requirements. ═══ 5. Existing problems ═══ Following are descriptions of some problems that are under investigation but could not be fixed in time for this ServicePak. ═══ 5.1. Installation ═══ The following list describes known problems with installation. o Uninstalling a monitored machine with an active monitoring session does not work. In order for uninstall to work, all SPM/2 processes must be stopped. - On a Monitoring system: o Stop all monitoring sessions. o Close THESEUS2, On-line References, and the SPM/2 Control Panel. - On a Monitored or Monitoring system: o SPMNBL /HALTALL will kill the Data Collection Facility (SPMDCF) if it is actively collecting data. o SPMNBL /STOPLISTEN will stop the NETBIOS listener (SPMNBL). o Uninstall may not clean up all files. The following applies if you installed SPM/2 2.0 Service Pak (SYSLEVEL Version WR06075) over SPM/2 2.0 (SYSLEVEL Version WR06000). If you installed SPM/2 2.0.1 (SYSLEVEL Version WR06075) for the first time, please skip this section. CSD level WR06075 contains 9 additional files that were not included in the original SPM/2 2.0 product. Consequently, if you try to uninstall SPM/2 using the SPMINST.EXE on the original shipped diskette, these 9 files will not be erased and the SPM/2 directory will not be removed. You should erase these files by hand if you wish. In addition, if you installed Service Pak WR06075, the SYSLEVEL.SPM file may be marked as read-only. SPM/2's uninstall program will not erase this file. If you want to erase it, you must first remove the read-only restriction by executing the following command at an OS/2 command line: ATTRIB SYSLEVEL.SPM -R You can then erase SYSLEVEL.SPM. o If you installed the /API option, when uninstalling you must explicitly uninstall the /API option. The syntax would be: SPMINST /T:C:\SPM2V2 /UNINSTALL /API ═══ 5.2. Data collection and logging ═══ The following list describes known problems with data collection and logging. o Recording Startup There will be some delay between the time the SPM/2 control panel says "Recording" and when the first data sample is stored into the .LOG file. This is due to the fact that the "Recording" message is displayed when the .LOG file is first opened and not when the first data sample is stored. After the .LOG file is opened, two factors cause a delay in recording data: - There is some initialization time - The first data sample obtained is discarded It is recommended that you wait at least two collection periods before you stop recording, otherwise there may not be any data in your .LOG file. o SPMNBL and LAN Requester startup If you stop LAN Requester and then re-start it while SPMNBL is running, you will have to stop and re-start SPMNBL in order for SPM/2 to work. - To stop SPMNBL, type: SPMNBL /STOPLISTEN - To start SPMNBL, type: SPMNBL /LISTEN o Support of the OASAS I Disk Array SPM/2 2.0 does not support collection of physical activity from an OASAS I disk array (due to the fact that the required performance hooks are not implemented in the OASAS I device driver). However, "File" information CAN be obtained for files residing on an OASAS I disk array. o Error message - "** NETBIOS$ device does not recognize command." When starting graphing/recording sessions for multiple .LOG files simultaneously (that is, specifying multiple .LOG files at the same time from the "Start Graphing/Recording" panel), you may receive the message: ** NETBIOS$ device does not recognize command. There is a timing problem between SPM/2 and NETBIOS, causing this error message to display. As a workaround, start each .LOG file individually. o APARs IC05407 and IC05445 SPM/2 fails to monitor across a network if Novell NetWare Requester for OS/2 is installed on either the monitoring or monitored station. There are some incompatibilities between SPM/2 and Novell NetWare which are not fully understood at this point. Following are the known symptoms: - A NetWare Server can not be an SPM/2 managed machine. The NetWare Operating System does not contain any of the performance metrics that OS/2 2.X contains. - A NetWare Server can not be an SPM/2 managing machine. SPM/2 remote monitoring uses IBM LAN Server named pipes, which are different from and NetWare named pipes. SPM/2 pre-requires the IBM LAN Server product. - SPM/2 will not start a monitoring session on a monitoring machine which has dual requesters - both LAN Requester and NetWare Requester for OS/2 - installed. The status on the SPM/2 Control panel shows PENDING indefinitely. There is a NetWare statement in CONFIG.SYS which prevents SPM/2 from working. If you remove the following statement from CONFIG.SYS, SPM/2 will then work, but NetWare Requester for OS/2 will not. IFS=C:\NETWARE\NWIFS.IFS A workaround which allows you to collect data from machines which have NetWare Requester for OS/2 installed is to use IBM LAN NetView Management Utilities for OS/2 (LMU/2) to collect performance data on a NetWare requester. LMU/2 Version 2.0 CSD level LM00106 is the earliest version which has this capability. LMU/2 pre-requires the SPM/2 Distributed Feature. The collection of data by LMU/2 on a NetWare requester is a 'LOCAL' collection only. LMU/2 collects SPM/2 data and provides the following function: - Bundles up the SPM/2 data for shipment into an IBM Database Manager or DB2/2 database. - Monitors the data for threshold exceptions and generates alerts - Creates summary analysis reports on a time interval. LMU/2 does not provide the data in PM graph form. o SPM/2 may hang shutdown. Under certain conditions, the SPMSNAPL process may not get terminated correctly and shutdown hangs. SPMSNAPL is the process responsible for logging errors to the error log. When working normally, SPMSNAPL terminates itself one minute after the last SPM/2 process dies. If you attempt to shutdown before SPMSNAPL has died, shutdown may hang. This happens very infrequently and is hard to reproduce. o SPMLOGFX, the log file recovery program, will trap if something other than an SPM/2 log file is given to it as input. ═══ 5.3. Graphing ═══ The following list describes known problems with Graphing. o Graphing Startup Initial startup of the graphing facility requires a couple of collection samples before the first points are plotted. If your collection frequency is set rather high, it may seem to take quite a while to see the beginning of a graph line. o Cross-hair cursor on Graphing window The legends on the axes of the SPM/2 graphing facility have been set to a font size that is available on *all* systems. We are aware, however, that these font sizes may not be optimum on some displays (generally they'll be too big). Additionally, under some non-U.S. code pages, when using the cross-hair cursor to get the exact Time and Percent values for a particular point on the graph, nothing may appear in the "readout boxes" to the upper right of each graph. This is due to the fonts being too large to fit in the boxes. The size of the characters used in both the legends and the cross-hair position readouts can be changed using the Font Palette found in the System Setup folder (inside the OS/2 System folder). Simply select the font desired from the Font Palette, then using button 2 of the mouse, drag the cursor over the desired SPM/2 resource window and release the mouse button. The fonts should change immediately. These new font settings can be saved by closing the Graphing Facility with the system icon (that is, from the icon in the upper left corner of the entire graph window). o When starting the graph, you may get a message that says "Already attempting to graph log file ", when there is no graphing going on. This usually happens after one graphing session has just stopped and another is being started. To recover, stop all SPM/2 processes and retry starting the graph. ═══ 5.4. Reporting ═══ The following list describes known problems with Reporting. o Notation in Summary reports For numerical values over 10,000, instead of writing out the full value, SPM/2 will save space by putting a K, M, or G after the value to indicate thousands, millions, or billions, respectively. For example: Instead of: SPM/2 will report: ----------- ------------------ 133,842 133.8K 234,310,100 234.3M o Printing reports on non-IBM PPDS printers. SPM/2 reports are 132 characters wide, and must print in compressed print mode, or 17.1 pitch in order to be readable. SPM/2 supports the IBM Personal Printer Data Stream (IBM PPDS). SPM/2's reports contain the PPDS control code of decimal '15' or hexadecimal '0F' to print in compressed print mode. If your printer does not understand this control code, your reports will not be readable. If you know your printer's compressed print control code for compressed print, sometimes also called SI (Shift In) or 17.1 pitch, you can modify the SPM/2 report to contain this control code. Edit your SPM/2 report with an editor like the OS/2 system editor. You will see that the first character in the report looks like a snowflake. This is the SI control code. Change this control code to the correct control code for your printer. Another option is to print your SPM/2 reports in landscape mode if your printer supports it. o Rate calculations show zero in a summary report even though there was activity. As shown in a summary report, rates such as Memory Paging Rate and Disk Access Rate are shown as an integer value. If these rates ever have a value less than one, the rate as shown in the report will be zero. o Summary times may be out of sequence in a dump report. If you logged data to a log file multiple times, appending each time, the summary times may be out of order in a dump report. o The SPM/2 Report Print option can not print to a network printer. As a workaround, print reports from the OS/2 command line with the PRINT command. o When creating a report description file (RDF) via the SPMRDFI command, SPMRDFI will trap if the input (RDI) file has an ILOG line longer than 246 characters. o The Start Date/Time, Stop Date/Time, and Sum Interval fields in the SPM/2 report header are not the values used for report calculations. The times shown in the report header are the values that the user entered on the Report Time Periods panel when creating a Report Description File (RDF). When creating an RDF file, you can use the default times or specify your own times. The default times correspond to the time that a monitor session was started and stopped. The value used in report calculations is the time that data was actually collected. This is the time between the beeps that signal data collection has started or stopped. The difference between these two values can be great. Consider the case where the monitoring session begins logging from a remote machine at 8:00, but the remote machine is not turned on until 9:00. The difference between the time shown in the report header and the time used for report calculations is one hour. The report shows the activity for the time that data was actually collected. The report is correct, but the summary times in the header may be misleading. o Re-using Report Description Files (.RDF) If you append to or replace a log file, and then run a report using a previously defined RDF file, the report may not contain the new data. When you create an RDF file, you specify the time periods that should be included in the report. If these time periods no longer match the data in the .LOG file, you will not see the data in a report. A convenient way to update the time periods in the .RDF file is to select the Preferences pulldown, and then the Restore Defaults menuitem. Another workaround is to set the start date/time, stop date/time, and summary interval to all zero's. This will force SPM/2 to always use all the data collected in the report, whatever the time periods are. ═══ 5.5. Panels and Messages ═══ The following list describes known problems in the Panels and Messages. o If the user opens an existing Report Description File, all of the values will be displayed as they were previously saved with the exception of "Preferences", "Workstations." The Selected Workstations will now include all the workstations in the selected log files. o The summary interval for a report is not always displayed correctly. If you specify a summary interval, save the report description file, then redisplay that report description file, the summary interval may be wrong. The right summary interval will be used when building the report. o When an .RDF file is created, the names and paths to all the .LOG files selected for the report are stored in the .RDF file. If you do one of the following to the .LOG file(s) that are referenced by an .RDF file, the .RDF file will no longer be able to find the .LOG file: - rename the .LOG file - move the .LOG file to another directory - in the case of an HPFS file system, change the upper or lower case of the .LOG file name o Alt-F7 to move windows Sometimes when SPM/2 starts, some of its windows may position themselves such that the title bar is beyond the end of the screen, making it impossible to move the window with the mouse. If this happens, click on the desired window, press Alt-F7, and then use the mouse or cursor keys to move the window. o Accessing .LOG files on Network Drives If you access a file (such as a .LOG file) on a redirected network drive via the SPM/2 control panel, the control panel will "remember" that path and use it as the default the next time you try to open the same type of SPM/2 file (in this example, another .LOG file). However, if you drop access to the network drive between opening the remote file, and re-opening a similar type file, an error will result where you're presented with an "SPM/2 Open File" window, but you will not be able to select or change any drives. To correct this situation, close the SPM/2 control panel and restart it. ═══ 5.6. User Metrics ═══ The following list describes known problems with User Metrics. o LAN Requester metrics bcRqTotRds and bcRqTotWrt are not supported. These metrics are supposed to measure the total number of reads and writes processed by the redirector. They are not implemented in the LAN Requester code, and are not supported. The values for these metrics will always be zero in a dump report. ═══ 6. Global Registration of SPM/2 User Metrics ═══ Prior to implementation of user metrics in your application, a request must be made to the IBM SPM/2 product group for assignment of ordinal (ID) numbers. Ordinal numbers will be issued and recorded for each requested resource group. Examples: IBM / OS2 / CPU (Ordinal Number = 3) IBM / OS2 / Memory (Ordinal Number = 5) Once ordinal numbers have been assigned, you may proceed with implementation. Refer to the SPM/2 Reference Document, "User Metrics" section for assistance in creating and installing the metric definition file. A range of ordinal numbers has been reserved for in-house testing purposes only. The ordinal range from 512-543 can be used for internal purposes without having to formally register with IBM. Note, however, that programs must not use this ordinal range once the program becomes generally available to the marketplace. THIS ORDINAL RANGE IS FOR INTERNAL USE ONLY. ═══ 6.1. Registration Process ═══ An SPM/2 User Registration form (SPM2 REGISTER) is available on CompuServe in the SPM/2 Library of the OS2DF2 Forum. Submit a completed copy of the SPM/2 User Registration form to the SPM/2 product group via either INTERNET or FAX. The FAX number is specified on the registration form. INTERNET : SPM2@vnet.ibm.com Registration forms will be processed within 2 working days of receipt. ═══ 6.2. Publication of Registered Participants: ═══ The IBM SPM/2 product group will post a list of registered participants to aid users in determining which applications are SPM/2 enabled. This list will consist of only those participating applications that provide publishing approval (i.e. due to unannounced code, etc.). This registered participants list (SPM2 ENABLED) will be available on CompuServe in the SPM/2 Library of the OS2DF2 Forum. Updates to this list will be made at least once a month. ═══ 6.3. Registered Participants ═══ Following is a list of products which have registered SPM/2 User Metrics. ┌───────────────┬──────────┬──────────────────────────────┐ │PRODUCT │ORDINAL │SPECIAL INSTRUCTIONS │ ├───────────────┼──────────┼──────────────────────────────┤ │IBM OS/2 │0 - 49 │Enabled with installation of │ │ │ │SPM/2. See SPM/2 2.0 On-line │ │ │ │documentation for description │ │ │ │of metrics. │ ├───────────────┼──────────┼──────────────────────────────┤ │RESERVED │50 - 199 │For future enhancements to │ │ │ │OS/2 metrics. │ ├───────────────┼──────────┼──────────────────────────────┤ │IBM LAN Server │200 │Enabled with installation of │ │3.0 │ │SPM/2. See SPM/2 2.0 On-line │ │ │ │documentation for description │ │ │ │of metrics. │ ├───────────────┼──────────┼──────────────────────────────┤ │IBM LAN │201 │Enabled with installation of │ │Requester 3.0 │ │SPM/2. See SPM/2 2.0 On-line │ │ │ │documentation for description │ │ │ │of metrics. │ ├───────────────┼──────────┼──────────────────────────────┤ │RESERVED │202 - 205 │For products currently under │ │ │ │development. │ ├───────────────┼──────────┼──────────────────────────────┤ │IBM CICS OS/2 │206 │See CICS OS/2 documentation │ │2.0 │ │for instructions on how to │ │ │ │enable SPM/2 to collect these │ │ │ │metrics. │ ├───────────────┼──────────┼──────────────────────────────┤ │RESERVED │207 - 511 │For future IBM products. │ ├───────────────┼──────────┼──────────────────────────────┤ │User Testing │512 - 543 │For product development only. │ │ │ │Do NOT ship any product using │ │ │ │these ordinals. See section │ │ │ │in this document on │ │ │ │Registration Process. │ ├───────────────┼──────────┼──────────────────────────────┤ │RESERVED │544 - │For future Non-IBM products. │ │ │64000 │ │ └───────────────┴──────────┴──────────────────────────────┘ ═══ ═══ The item in the title line is a trademark of IBM Corporation. ═══ ═══ The item in the title line is a trademark of Novell, Inc.