



			Citrix Winview
			Application Note

			American Power Conversion
			PowerChutePLUS for OS/2 and
			Uninterruptible Power Supply family
			(Back-UPS, Smart-UPS).

			

			This application note is for
			informational use only and Citrix
			makes no representations or
			warranties with respect to the
			contents or use of this document
			or of any third-party products
			discussed within.


(January 3, 1995)

Citrix Systems
210 University Drive
Suite 700
Coral Springs, FL 33071
Phone (305) 755-0559
FAX   (305) 341-6880


OVERVIEW

This application note discusses installing American Power Conversion's
PowerChute software (Version 2.2.2) on Citrix application server products.

PowerChute for OS/2 is a software product that takes user-specified measures
in the event of power problems. It warns when power is unstable (brownout)
or nonexistent (blackout), and shuts down the application server if power is
not restored within a specified time or if the UPS battery runs low. Refer
to the APC PowerChute manual for information on making the required serial
connections between the application server and the UPS.


DISCLAIMER

The scenarios described in this document have been tested by Citrix
Systems.  Variations to the scenarios described in this document may work,
but have not specifically been tested by Citrix.  In order to recreate
the configurations, you should use the specified revision levels of all software
products described in this document and stay within the bounds of the features
and functions described in this document.

This application note is a living document and will be modified as new
information and versions of the software described herein become available.
Make sure you have the latest version of this document before you begin. The
latest version is always available in the Citrix Forum on Compuserve.


SYSTEM REQUIREMENTS

1. Citrix application server, Version 2.21 or higher

2. American Power Conversion PowerChute for OS/2, Version 2.2.2

3. American Power Conversion UPS that supports PowerChute
	
4. American Power Conversion Cable (APC Part Number 940020)


INSTALLATION AND CONFIGURATION

Use the following steps to install and configure the APC PowerChute
software on an application server:

1. Transfer the PowerChute files to the application server.
2. Create a PowerChute initialization file.
3. Create PowerChute command files.
4. Modify the CONFIG.SYS and STARTUP.CMD files.
5. Test the PowerChute software.

These steps are described in detail in the following sections.


STEP 1. Transfer the PowerChute Files

Because the PowerChute installation program (INSTALL.EXE) is written for OS/2
Presentation Manager, you must manually copy the files from the installation
diskette to a directory on the application server. The procedure below
assumes that the application server boot drive is drive C. If your
boot drive is another drive letter, replace each instance of C in this note
with your boot drive letter. Login to the application server as an
Administrator, start an OS\2 session, insert the PowerChute installation
diskette into the diskette drive (drive A is assumed in the procedure below),
and type the following commands:

    MD C:\PWRCHUTE
    COPY A:\*.* C:\PWRCHUTE /V
    COPY C:\PWRCHUTE\UPSSA.EXE C:\PWRCHUTE\UPS.EXE
    REGISTER C:\PWRCHUTE /ALIAS:PWRCHUTE /SYSTEM
    CONFIG ACCESS \API\DOSCALL.100 PWRCHUTE X /P
    CONFIG ACCESS \API\DOSCALL.206 PWRCHUTE X /P
	

STEP 2. Create a PowerChute Initialization File

Use the following commands to create a PowerChute initialization file:

    C:
    CD \PWRCHUTE
    E PWRCHUTE.INI

At this point you are in the OS/2 editor program.  Type in the
following lines to create a PWCHUTE.INI file:

    ; This is the POWERCHUTE INI file.
    [ups]
      msgdelay = 5
      recharge = 36
      msgtime = 30
      downtime = 600
      lowbattruntime = 0
      returnscript = c:\pwrchute\return.cmd
      failscript = c:\pwrchute\fail.cmd
      timerexpscript = c:\pwrchute\timerexp.cmd
      shutdownscript = c:\pwrchute\shutdwn.cmd
      lowbatteryscript = c:\pwrchute\lowbatt.cmd
      returnmsg =
      failmsg =
      shutdownmsg =
      lowbatterymsg =
      downtimemsg =
      logpath = c:\pwrchute\pwrchute.log
      logmax = 10000
      cmdfile =
      signals = 111
      voltlevels = 111
      device = COM1
    ; End POWERCHUTE.INI.

Press F4 to save and exit the file.
	

STEP 3. Create PowerChute Command Files

PowerChute runs several different command files, depending on the event
detected; e.g., power failure, UPS battery low, etc. Create these script
files in the C:\PWRCHUTE directory. These scripts use the MSG utility to
notify users of PowerChute events, and the SHUTDOWN utility to shutdown the
application server.

Here are some sample command files. Modify them to fit your requirements.

A. FAIL.CMD (Power Failure)
   This command file runs when a power failure is detected:
   @ECHO off
   REM FAIL.CMD - PowerChute power failure script
   MSG * POWER FAILURE DETECTED - Please save files and log off.
   REM End of FAIL.CMD

B. RETURN.CMD (Power Return)
   This command file runs when power is restored before PowerChute
   times out:
   @ECHO off
   REM RETURN.CMD - PowerChute power return script
   MSG * POWER RESTORED - Resume normal operation.
   REM End of FAIL.CMD

C. TIMEREXP.CMD (Power Timeout)
   This command file runs when PowerChute's power failure timer expires
   before power is restored:
   @ECHO off
   REM TIMEREXP.CMD - PowerChute timer expiration script
   MSG * POWER FAILURE TIMEOUT - SYSTEM WILL BE SHUTDOWN
   REM End of TIMEREXP.CMD

D. SHUTDWN.CMD (System Shutdown)
   This command file shuts down the system. NOTE: Do not use the /NOW or
   /REBOOT parameters, because they cause a reboot.
   @ECHO off
   REM SHUTDWN.CMD - PowerChute shutdown script
   SHUTDOWN /NOKILL /NOMSG /F
   REM End of SHUTDWN.CMD

E. LOWBATT.CMD (Battery Low)
   This command file runs when the UPS battery is low:
   @ECHO off
   REM LOWBATT.CMD - PowerChute low battery script
   MSG ADMIN UPS battery is low.
   REM End of LOWBATT.CMD


STEP 4. Modify the CONFIG.SYS and STARTUP.CMD Files

Make the following changes to CONFIG.SYS:

A. Modify the SET PATH= line to include the C:\PWRCHUTE directory.

B. Add the following line to specify the path to the PWRCHUTE.INI
   file for the UPS.EXE program:
   SET PCPATH=C:\PWRCHUTE\PWRCHUTE.INI

C. The PowerChute daemon, UPS.EXE, runs under the disconnected user
   STARTUP.CITRIX when started from STARTUP.CMD.  Add the following
   line to C:\STARTUP.CMD to start the PowerChute daemon:
   START "APC PowerChute" /N /I C:\PWRCHUTE\UPS.EXE

These changes will not take effect until you reboot the application server.


STEP 5. Test the PowerChute Software

A. Unplug the UPS from the commercial power source.  The application
   server should continue to operate, and the FAIL.CMD command file
   should be executed within a few seconds.

B. Plug the UPS back into the commercial power source.  The command file
   RETURN.CMD will be executed, and the message contained within the
   command file displayed.

C. To test the shutdown feature, you will have to remove commercial power
   for a length of time greater than the limit set in the PWRCHUTE.INI file.
   When this limit is reached, the file TIMEREXP.CMD is executed, followed
   by SHUTDWN.CMD.


NOTES

Make sure that the limit set in the PWRCHUTE.INI file allows
sufficient time to shutdown the application server before the battery
runs out of power. This limit depends on the capacity of the APC UPS
and the power consumption of your attached system.  Refer to the APC
charts and manuals for information on UPS size recommendations.

American Power Conversion supplies a cable (grey cable, Part Number 940020)
for use with PowerChute. This cable supports the following UPS signals:
Return Power, Low Battery, Line Fail & Shutdown. No other cable
configuration is supported.


PROBLEMS

There are no known problems at this time.
