═══ 1. Description ═══ UPS Monitor for OS/2 ver. 1.0 - Utility program to monitor the status of the APC Uninterruptible Power Sources (UPS). Provides shutdown services to the operating system. Includes two programs optimized for most APC-brand UPS models. Designed for single workstation environment. UPS Monitor for OS/2 is shareware and registration is available through BMT Micro at www.bmtmicro.com or through the author directly. See the section How To Register UPS Monitor for details. CAUTION if you are using the Back-UPS model (non-Pro version). Please read the section Caution - Warning before you use UPS Monitor B (UPSMONB.EXE). Which executable do I use? There are currently two versions of the UPS Monitor program available. UPSMONS.EXE supports the smart signalling of the Smart-UPS, Smart-UPS v/s and the Back-UPS Pro. Matrix-UPS may also be supported, but is untested. This program provides support for the features common to all these models. Exceptions are restart capabilities and UPS Turn Off Delay which are only available on the Back-UPS Pro and Smart-UPS models. These two features are available in UPSMONS.EXE. This program requires the cable number 940-0024B or 940-0024C to be connect to the UPS. UPSMONS.EXE will not work with the Back-UPS models. UPSMONB.EXE, also referred to as UPS Monitor B, is designed for the Back-UPS model only (non-Pro version) and uses simple signalling. This program requires the cable number 940-0020B to be connect to all the UPS model. UPSMONB.EXE will not work with other models. If enough interest and support exists for these kinds of programs, I will write and include a third program that will fully support the additional features of Back-UPS Pro and Smart-UPS models. I may also add a pipe to these programs which would make UPS Monitor accessible over a network. ═══ 2. General Program Operation ═══ Installation and Configuration. You must first configure UPS Monitor to recognize the UPS model and the comm port it is connected to. Select Options - Settings and select the comm port from the controls. Save the settings and select Options - Connect. This will connect to the UPS and a message will tell you if it was successful. You are all set. If it did not recognize the UPS, see the section on Troubleshooting for information. If you want UPS Monitor to start automatically when your OS/2 system powers up, then place a shadow of the executable into the Startup folder (it's located under the OS/2 System folder, simply drag and drop the UPSMONB object into the Startup folder). You must also provide the command line parameters to UPSMONS.EXE or UPSMONB.EXE for automatic operation. The commands are /Con to automatically connect to the UPS and /Min to minimize on start-up. You must provide these commands on the Parameters line in the Properties page of Warp 4.0 or Settings page of Warp 3.0. To get to that page, right-click on the UPSMON object and click Properties or Settings. Program Operation. To minimize the program load, UPS Monitor will check the UPS every 4 seconds for status. All time settings therefore have a resolution of 4 seconds as well. For example, a UPS on Battery alarm in the worst case, may not be detected until 4 seconds after the actual power failure. The UPS Monitor background color changes according to events and settings. If UPS Monitor is not connected to the UPS, the background color is light yellow. During normal operation when the UPS is on-line the background is light green. If a power failure is detected and the UPS is on battery, the background changes to light red. If UPS Monitor detects a power failure and after the Message Delay expired, the program will give itself focus and it will be restored to screen if it had been minimized. This will alert you of a possible shutdown. The UPS Monitor window can be sized and positioned anywhere on the desktop. Size and position are saved. To bring up Help, simply press F1. Help is context sensitive, so if you have the Settings window open, help for the settings will pop up. When UPS Monitor shuts down your system, it will not save any data of the applications that are running. It is the applications responsibility to save any data. Set your application to auto or timed save if this option is available. The Back-UPS model does not offer built-in turn off delay as other models do and thus poses a problem shutting OS/2 down and turning the UPS off. If the UPS is on battery and the fixed duration time expired, UPSMONB.EXE will secure the file system by issuing a DOSShutdown API call. This does not shutdown the Presentation Manager or any other sessions currently running, but all buffers get flushed and the system will restart cleanly after power has been restored. The UPS will be turned off immediately after the file system has been secured. It is possible that the line power may be restored as the file system is being secured. In this case, the UPS will not be turned off. The operating system appears locked-up and will not respond to inputs. In this case, you must reboot the system using ALT-CTRL-DEL or the RESET button on your computer. Not to worry, the file system is secured and the system will restart cleanly the next time. ═══ 3. Caution - Warning ═══ The APC Back-UPS model does not use conventional serial communications, rather it uses the serial control lines to report line failure and command the UPS to turn off. Always use the cable with the part number 940-0020B. Other cables will cause UPSMONB.EXE to report line failure. Please read the following section carefully. I have discovered the behavior listed below on my APC model Back-UPS 400 and assume that all Back-UPS models reflect the same behavior. Remember, this only happens when the line power is off and the UPS is running on battery. The Back-UPS (no-Pro) model uses the DTR line (pin 4 on the 9 pin serial connector end) of the serial port to receive a signal to turn itself off. If DTR is ON and the UPS is running on batteries, it will turn off right away without any delay. Under what circumstances can the UPS turn off unexpectedly? ■ The UPS can turn off if you connect the UPS with any cable to a serial port at the same time a power failure occurs. ■ If the UPS is attached to a serial port with any cable, no Back-UPS specific software is controlling it and the power goes out. ■ When UPS Monitor B is started while UPS is running on battery and DTR was left turned on from a previous program that controlled the serial port. To prevent this unexpected turn off, you can do the following: ■ Start UPS Monitor B only when line power is active. ■ Connect 940-0020B serial cable to UPS only when line power is active and then run UPS Monitor B right away. UPS Monitor B will turn DTR off whenever it is started. If you don't use the serial port for any other purposes, and UPS Monitor B is used exclusively to monitor the UPS, DTR will remain off and the above problem will never happen. The Back-UPS model is not an ideal power backup solution for your OS/2 operating system, but if you follow these guidelines, UPS Monitor B will provide the best protection and let's you safely use this UPS model if you have already purchased one. Avoid the Back-UPS model if you are looking at purchasing a new UPS. UPS that provide turn off delays and are using a full serial protocol are better choices. ═══ 4. Menu Description ═══ Describes all menu items available for this program. ═══ 4.1. FILE - Open Log ═══ Opens a UPS Monitor log file for viewing. This log file is a regular text file and can also be opened with any text editor or word processor. After a log file has been selected, it will show the log in a separate window. From this window, you can print or open another log file. You can reposition or resize the View Log window. Size and position will be remembered the next time you open this window. Printing is done with the font 6.Helvetica. Note: The main UPS Monitor window displays the last 10 to 20 events only. If more than 20 events are displayed, the oldest 10 events are cut. You can use Open Log to view all previous log events. ═══ 4.2. FILE - Exit ═══ Exit the program. If the program is still connected to the UPS, the connection is terminated. This event is logged. ═══ 4.3. OPTIONS - Settings ═══ Opens the UPS Monitor settings window. Set the Com Port (COM1 - COM8) where the UPS is connected to, Enable Logging to a file, set the maximum Log File Size and set the location and name of the log file. The log file will be kept approximately within the file size specified. If the log file exceeds the selected size, then it is renamed for backup to the same name with the extension .000 and a new log is started. If the backup file with the extension .000 already exists, then it is replaced. This way it keeps at least one log full of data. The Beep check box enables or disables the audible alarm during program operation. The audible alarm will activate whenever a power failure is detected and at every subsequent shutdown message interval. The alarm is a short, low to high tone beep. ═══ 4.4. OPTIONS - Shutdown Parameters ═══ Opens the shutdown parameter window. Set the UPS on Battery message delay (0-99 secs.) and message interval (0-999 secs.). It is the delay and interval at which the UPS Monitor is brought to the foreground to indicate that the UPS is running on battery. Select a range that matches your UPS capacity in order to get notified on time when the UPS shuts down. Default values are 10 second delay and 30 second intervals. The Back-UPS model does not report low battery through the serial port. Shutdown time can only be set to a fixed time. Set Fixed Duration shutdown time. In a power fail situation, the UPS Monitor will then shutdown the system after the set time has expired. Default value is 60 seconds. Depending on your model number, you can set this to a longer value. The Ext. Shutdown Script check box allows to execute an external script (the file UPSMONB.CMD) for shutting the system down. You can customize this file to your own liking to shut down OS/2. The external shutdown will not secure the file system or turn the UPS off after the fixed time has expired. The UPS will simply continue to run until the battery is low and can not regulate the power anymore. You will have to shutdown OS/2 with your own script within the run-time provided by the battery. Please read General Program Operation for more information on how UPS Monitor B shuts down the UPS. ═══ 4.5. OPTIONS - Connect ═══ Opens the selected comm port and connects to the UPS. This event is logged. ═══ 4.6. OPTIONS - Disconnect ═══ Disconnects from the UPS and closes the comm port. This event is logged. ═══ 4.7. HELP - Help Index ═══ Displays this help file (UPSMONB.HLP). ═══ 4.8. HELP - About ═══ Product information. ═══ 5. Simple Signalling Cable Pinout ═══ Below is a connection diagram to connect the APC UPS to a 25 or 9 pin serial port. This cable requires a UPS supporting simple signalling and the UPSMONB.EXE program. Note: Simple signalling UPS models do not exchange serial data through the regular pins 2 and 3, rather the status of the UPS is sensed through the CTS and DTR control lines. ═══ 6. Troubleshooting ═══ If you are having problems connecting to the UPS, then follow these steps below. ■ UPS Monitor is only designed and tested for the APC (American Power Conversion) models Back-UPS, Smart-UPS, Smart-UPS v/s and Back-UPS Pro. ■ The UPSMONS.EXE executable is only designed to work with models supporting smart signalling like the Smart-UPS, Smart-UPS v/s and Back-UPS Pro. You must use cable number 940-0024B or 940-0024C included with these UPS for proper operation. It is possible that this program will work with other APC models, like the Matrix-UPS, using smart signalling. UPS Monitor has not been tested with the Matrix-UPS model. UPSMONS.EXE will not work with the model Back-UPS (400, 450 and 600) which use simple signalling. Refer to the Help file of UPSMONS.EXE for more information. ■ The UPSMONB.EXE executable is only designed to work with models supporting simple signalling, like the Back-UPS (non-Pro models). You must use cable number 940-0020B included with this UPS for proper operation. ■ Next paragraph for UPSMONB.EXE only Because of the simple signalling the Back-UPS model uses, you must manually test if communication is working properly. Make sure the Fixed Duration time is set to 60 seconds before doing this test. Connect UPSMONB.EXE (using Options - Connect) to the UPS and if the proper cable is connected to the UPS, you should get the message Connected to UPS Now remove the power from the UPS for 10 seconds and you should get the message Power Failure detected. UPS on battery. This completes the test. If you do not get these messages, the connection to the UPS is not working or you have the wrong cable connected. ■ When UPSMONB.EXE is started during a power failure and the UPS is running on battery, the UPS may turn off right away. See Caution - Warning before you use UPS Monitor B (UPSMONB.EXE). ■ UPS Monitor will not work with brands other than APC. ■ Make sure the Com Port in the Settings window matches the com port you use for the UPS. ■ Make sure you have all the included files present in your directory. ■ If you have Ray Gwinn's SIO comm drivers, use the included PMLM (Poor Man's Line Monitor) to monitor the CTS control line status. IF CTS is lower case, then power is on. If CTS is upper case, then the line power is off and the UPS is running on batteries. PMLM will also display the baudrate the port is set to. If it is not 2400 then SIO may be locking the port to another baudrate. See below. ■ If you are using Ray Gwinn's SIO com drivers, check if the baud rate is locked for the particular com port you are using with the interface. Unlock it so UPS Monitor can change the baud rate to 2400. From the SIO reference, it states: Locked Baud Rate Placing a colon and a baud rate following the communications port, eg (COM1:38400,3F8,IRQ4), causes the port to be locked at that baud rate. No program, OS2 or DOS, is allowed to change the baud rate. ■ Try the standard COM1 or COM2 ports if you have problems with any other com ports like COM3 - COM8. Also, remove any serial cable extensions or adapters and connect the UPS directly to the computer. See the section Simple Signalling Cable Pinout for connector pin-outs. ■ Try using a different computer or different com port to access the UPS. ═══ 7. Installation ═══ Note: REXX or Object REXX must be installed on your system for this program to work. REXX is installed by default, but if you did not install it then run Warp installation again and selectively install REXX support. Unzip all files into a separate directory, I suggest the name UPSMON. Open an OS/2 Window and change to the directory you just created. Type INSTALL and the script will create a UPSMonitor folder on the desktop and fill it with all executable programs present in the directory. To start the program, double-click on the UPSMONB or UPSMONS object inside the folder. You must first configure UPS Monitor to recognize the UPS model and the comm port it is connected to. Select Options - Settings and select the comm port and UPS model from the controls. Save the settings and select Options - Connect. This will connect to the UPS and a message will tell you if it was successful. You are all set. If it did not recognize the UPS, see the section on Troubleshooting for information. Next paragraph for UPSMONB.EXE only Because of the simple signalling the Back-UPS model uses, you must manually test if communication is working properly. Make sure the Fixed Duration time is set to 60 seconds before doing this test. Connect UPSMONB.EXE (using Options - Connect) to the UPS and if the proper cable is connected to the UPS, you should get the message Connected to UPS. Now remove the power from the UPS for 10 seconds and you should get the message Power Failure detected. UPS on battery. This completes the test. If you do not get these messages, the connection to the UPS is not working or you have the wrong cable connected. If you want UPS Monitor to start automatically when your OS/2 system powers up, then place a shadow of the executable into the Startup folder (it's located under the OS/2 System folder, simply drag and drop the UPSMON object into the Startup folder). You must also provide the command line parameters to UPSMONS.EXE or UPSMONB.EXE for automatic operation. The commands are /Con to automatically connect to the UPS and /Min to minimize on start-up. You must provide these commands on the Parameters line in the Properties page of Warp 4.0 or Settings page of Warp 3.0. To get to that page, right-click on the UPSMON object and click Properties or Settings. Installing this program on your system does not change any of the INI or CONFIG.SYS files. UPS Monitor is only designed and tested for the APC models Back-UPS, Smart-UPS, Smart-UPS v/s and Back-UPS Pro. It includes two executable programs and to determine which program to use, please read the Description for information. The following files belong to this program: UPSMONB.EXE The executable program using simple signalling. UPSMONS.EXE The executable program using smart signalling. UPSMONB.HLP The help file for UPSMONB.EXE. UPSMONS.HLP The help for UPSMONS.EXE. UPSMONB.INI Settings file for UPSMONB.EXE. UPSMONS.INI Settings file for UPSMONS.EXE. UPSMONB.LOG Default log file created by UPSMONB.EXE. UPSMONS.LOG Default log file created by UPSMONS.EXE. VPUTIL.DLL Dynamic Link Library required by executables. Packed for smaller size with LXWARP. UPSPMSD.DLL Dynamic Link Library required by executables. RXSI2.DLL Dynamic Link Library required by executables. RXASYNC.DLL Dynamic Link Library required for serial communications to the UPS. This library of serial communications routines is included by permission of Crucial Applications (Author: Ian Timms, e-mail: itimms@ariel.ucs.unimelb.edu.au). The entire serial communications package, including the source code for RXASYNC, is available at my home page or other major OS/2 sites by the filename RXASYN20.ZIP. This file has been packed for smaller size using LXWARP. INSTALL.CMD General installation script for UPS Monitor. README.TXT Program description and installation instructions. BMTORDER.TXT Order form to register UPS Monitor through BMT Micro. To remove this program from your system, close the program, delete all your UPS Monitor object or shadow from your desktop or folders and delete all the files listed above. ═══ 8. The Legal Stuff ═══ UPS Monitor for OS/2 is shareware and not free. You may use it and try it out for 30 days. There are no limitations to the shareware version of UPS Monitor other than it will cease to function after 30 days. If you like this program and would like to continue using it, you must register to obtain a license. See How To Register section on ways to register. The shareware version of this program may be distributed electronically as long as all files are kept together. The shareware version is recognized by the title UPS Monitor for OS/2 - Unregistered in the title bar of the main program. A single registration entitles the owner to use the two executables as individual registered programs. Only one copy of each of the executables may be run at one time on a computer, in other words, if you have a laptop and a desktop, you may copy this program onto both computers but only one instance of one of the UPS Monitor programs may be run at one time. If there is a possibility that two of the same executable programs may be run at the same time, then you must get a second license. You may however use UPSMONS.EXE and UPSMONB.EXE together on two separate systems by only having one registration. The registered version of UPS Monitor may not be distributed in any way. Quantity discounts start with two licenses, contact the author for more information. Registration gives you many benefits. Besides removing of all restrictions, I will provide prompt technical support, implement suggestions to program improvements, enhancements and customization (if technically possible). RXASYNC.DLL, required for serial communications to the UPS, is a library of serial communications routines and is included by permission of Crucial Applications (Author: Ian Timms, e-mail: itimms@ariel.ucs.unimelb.edu.au). The entire serial communications package, including the source code for RXASYNC, is available at my home page or other major OS/2 sites by the filename RXASYN20.ZIP. This DLL has been packed using LXWARP for smaller size. UPS Monitor is protected using SecureIt. To get more information on this shareware protection program, see http://www.bmtmico.com/catalog/secureit/ DISCLAIMER Although this software has been tested and run successfully, the author of UPS Monitor for OS/2 is in no way responsible for any damage this program may cause to computer equipment. Any trademarks mentioned in this document belong to their respective owners and the author of this program is not connected in any way to these products nor does he endorse any of the products mentioned. TRADEMARKS APC stands for American Power Conversion. APC, Back-UPS, Smart-UPS, Smart-UPS v/s, Back-UPS Pro and Matrix-UPS are registered trademarks of American Power Conversion. ═══ 9. How to Register UPS Monitor ═══ There are two ways you can register UPS Monitor: Send e-mail to ASchw@worldnet.att.net to request my mailing address. You can then send me a check or money order and I will return the registration code. The cost is $10.00 using this option. Register through BMT Micro at www.bmtmicro.com. BMT Micro offers a variety of purchasing methods, see the file BMTORDER.TXT for details. You will receive the registration code usually within one day. The cost is $15.00 for this option. Quantity discounts are available. Please e-mail me for details. A single registration entitles you to use both programs, UPSMONB.EXE and UPSMONS.EXE and any new versions of UPS Monitor will always be free to registered users. ═══ 10. Support ═══ For support for this program, you can contact me directly via e-mail. My e-mail address: ASchw@worldnet.att.net Visit my home page, "The Warped Code Cellar" at http://home.att.net/~ASchw for other information and applications for OS/2 like HOUSE/2 a home automation program using X10 devices, Memory Game and Leave One, two speech navigation enabled games. Monitor my home page regularly for new and upgraded OS/2 programs. This will be the place where all programs will be available first. This program is also available at the following sites: Internet: http://home.att.net/~ASchw http://www.bmtmicro.com http://hobbes.nmsu.edu