Caché Buttons Readme
File
Last Updated:
10/21/2005
Caché Buttons makes it easier for users to collect technical information that may be attached to problems sent to InterSystems Technical Support.
The utility has two options: the "little button" (the Basic option) provides most of the information required for InterSystems Technical Support to analyze a medium complexity problem. The data this option generates should be present on every problem logged into InterSystems' support system. The "big button" (the Advanced option) is sometimes required on complex problems where Support needs more in-depth information about a system's behavior. It includes all the information contained in the Basic option and adds a lot more. All the information is stored in a single HTML-formatted file.
On 32-bit Windows systems (NT, 2000, XP and 2003 Server), Caché Buttons makes use of a couple of third-party utilities developed by SysInternals Software. The first utility (named PsInfo.Exe) is used for displaying extended system information and the second one (named PsList.Exe) for showing process information at the OS level.
The entire process should not take too long to complete (average time is 5 minutes, but depending on the system it make take more). The Buttons tool is written in the Caché ObjectScript language and is available for all Windows platforms and all brands of UNIX supported by the specific Caché version and also OpenVMS. It runs on all Caché versions starting from 3.2.1 on the corresponding supported Operating System platforms. It does not run on Caché 2.x.
For the rare instances where Caché is completely down and unresponsive, making it impossible for the Caché ObjectScript-based Buttons to run, there are Operating System-level scripts that can be run to collect all the system information available outside of Caché. These scripts are an integral part of the Buttons tool and are available for 32-bit Windows systems (NT, 2000, XP and 2003 Server), several UNIX platforms and OpenVMS. The names of the scripts by platform are:
Ø CacheHung.Cmd for Windows systems.
Ø CacheHung.sh for UNIX platforms.
Ø CACHEHUNG.COM on OpenVMS (DCL script).
Once the report has been run you may compress (zip) the output up into a single file and then submit the report, along with a problem description using the WRC application. Just login using your customer account and then "Open New Problem". Once the problem description has been saved you will see a link called "Add File" in the problem detail view. Clicking on this link will bring up a screen that allows you to upload a file over HTTP. This will "tie" your report file to the problem. This can also be done to an existing issue. This process can take a long time and for very large files (such as files greater than 5 MB) it may be more efficient to FTP them to the ftp.intersystems.com machine and just provide the name of the file in the problem description. If you are under maintenance and don't have an account to use the WRC application feel free to e-mail support@intersystems.com and we will gladly assist you.
The distribution files of the Caché Buttons package are compressed into a single ZIP file named CacheButtons.zip. To install the product, execute the following steps:
%SYS> Do ^%RIMF
And enter the full filename (including the path) of the corresponding routine object code file extracted from the ZIP file into the Bin directory (for Caché 3.2.1 to 4.1.x the filename is ButtonsV3x4x.obj and for Caché 5.x and later the filename is ButtonsV5.obj). This will install the %Buttons object code into the %SYS Namespace.
Note: Caché 5.0 introduces an incompatibility with routine object code compiled with previous versions of Caché. Please be sure to load the appropriate version of the routine object code file for your version of Caché.
The CacheHung OS scripts are installed into the Caché Bin directory on step # 1 above.
If you are installing the Caché Buttons on a UNIX system, make sure that the file CacheHung.sh has the proper attributes set (Read and Execute). Go to the Caché Bin directory where the file was installed (e.g. /usr/cachesys/bin) and execute from a UNIX prompt:
/usr/cachesys/bin> chmod 555 CacheHung.sh
On most UNIX systems, in order to run the CacheHung.sh script, you will need root privilege in order to complete the process.
Installation of the SysInternals utilities (Windows
32-bit platforms only)
On 32-bit Windows systems (NT, 2000, XP and 2003 Server), Caché Buttons takes advantage of two third party utilities: one is used to display extended system information and the second for showing processes at the Operating System level. They were developed by SysInternals Software and may be used for free. The names of these utilities are PsInfo.Exe and PsList.Exe, you can download them from the links below. Do not install them on systems running Windows 9x or ME, as they were designed for 32-bit systems only.
http://www.sysinternals.com/files/PsInfo.zip
http://www.sysinternals.com/files/PsList.zip
The utilities PsInfo.Exe and PsList.Exe must be copied to the Caché Bin directory on Windows systems for the extended system information and Process info to work. This must be done for every Caché instance that will need to run %Buttons.
Your Microsoft Windows installation should already have a DLL named Pdh.dll on directory %SystemRoot%\System32 (e.g. C:\WinNT\System32). If it doesn't, a copy of this DLL is included in the PsInfo.zip file referenced above. Copy Pdh.dll to the Caché Bin directory along with the PsInfo.exe and PsList.exe utilities.
The activation of the Caché ObjectScript routine %Buttons is extremely simple. In any Namespace, please execute from the Caché Terminal prompt:
%SYS> Do ^%Buttons
The routine will request the desired diagnostic level (Basic or Advanced) and will generate an HTML document containing the system information.
When the routine finishes, a message will be displayed informing the name and size of the HTML file generated as well as its location on the disk. All files, temporary or not, will be created in the Caché Manager's Directory (e.g. C:\CacheSys\Mgr on Windows or /usr/cachesys/mgr on UNIX).
Contents of the HTML log file generated by the Caché
ObjectScript Routine %Buttons
The Basic option includes:
The Advanced option includes all the information contained in the Basic report plus:
Execution of the Operating System script
CacheHung
If Caché is completely down and unresponsive, you may use the CacheHung OS scripts instead. To run the script, go to the Caché Bin directory (e.g. C:\CacheSys\Bin on Windows or /usr/cachesys/bin on UNIX), open a Command Prompt window and execute from the OS prompt:
C:\CacheSys\Bin> .\CacheHung
/usr/cachesys/bin> ./CacheHung.sh
The script will request the full name of the base directory where Caché was installed (e.g. C:\CacheSys on Windows or /usr/cachesys on UNIX), collect all information available from the Operating System and shared memory used by Caché and store it in a single HTML-formatted file named CacheHungButton.html. This file will be located at the Caché Manager’s Directory (e.g. C:\CacheSys\Mgr on Windows or /usr/cachesys/mgr on UNIX).
On Windows systems, login with an account that has Administrator privileges. On UNIX systems you need to login with a username which has at least enough privileges to start / stop Caché. Preferably, login as “root” to avoid permission related problems.
Note about Windows NT 4.0 systems:
The CacheHung Windows script was written using Shell Command Extensions, available on Windows NT, 2000, XP and 2003 Server. However, InterSystems has received notice that some of the extended syntax commands don’t behave as expected on Windows NT 4.0 systems, even when the command extensions are enabled. The main symptom of this problem is that the script does not ask the user for the Caché installation directory, therefore preventing the script from executing properly. Alternatively, in this case, please execute the script passing the full Caché installation directory as a parameter. If the directory name contains white spaces, please surround it with double quotes. Examples:
Ø C:\CacheSys\Bin> .\CacheHung C:\CacheSys
Ø C:\CacheSys Version 5\Bin> .\CacheHung “C:\CacheSys Version 5”