








XA
X10 Command Interpreter
Version 2.3 - August 1994


Copyright c 1991-1994 by Bruce Christensen - All Rights Reserved.









======================================================================
1. Shareware
======================================================================

     This floppy contains a set of useful DOS utilities for X10's CP-
     290 Computer Interface.  These programs are being marketed using
     the SHAREWARE concept which allows you a complete evaluation of
     the product before you are required to register.  Shareware
     provides you with low-cost, high-performance software and
     support.  Shareware also provides incentives for programmers to
     continue to develop new products.  If you find XA and its support
     files useful and you continue to use them after a trial period
     not to exceed 45 days, you must make a registration payment of
     $29 to the author.  When you register, you will receive the
     latest, full-featured version of XA along with a printed User's
     Manual.  For more information, read the file REGISTER.TXT,
     complete the form, and register your copy of XA.


======================================================================
2.Introduction
======================================================================

     You are probably familiar with the menu-driven program (X10.EXE)
     supplied with your CP-290.  The software approach used in that
     implementation is great for beginners since it offers a fool-
     proof method of organizing commands and events.  Unfortunately,
     that method also becomes a bottle-neck every time you want to
     activate a single module via your computer.  What's worse is
     trying to maintain a schedule of lighting events that vary due to
     seasonal changes.  XA is a shareware package designed to
     alleviate many of the frustrations you may have experienced with
     the X10-supplied software.  In addition, XA makes schedule
     maintenance a breeze.  Soon, your computer will automatically
     handle the monotony of CP-290 scheduling for you.  Be sure to
     read this manual to take full advantage of XA's power.
   
   What is XA?
  ----------------------------------------------------------------------

     The XA program is an interpreter.  XA translates English-like
     sentences into commands that are understood by the CP-290.  For
     instance, you can quickly tell XA to turn on a set of lights with
     the  following DOS command:

          XA "PORCH ON"

     XA knows that the PORCH lights are addressed at HOUSE A UNIT 9,
     or whatever address you choose (you DEFINE modules and their
     addresses in the file XA.INI, discussed later).  Since
     XA accepts commands from the DOS prompt, you can place statements
     like these in your batch files too.  For instance, I use an X10-
     controlled nightlight near our downstairs phone to warn other
     family members if I'm "on-line" with a remote computer or BBS.
     The light is turned on prior to the session, and turned off when
     I'm finished.  Here's the sample PHONE.BAT with X10 commands:

          XA "WARNING_LAMP ON"
          TELIX (OR PROCOMM) STATEMENTS HERE
          XA "WARNING_LAMP OFF"

     XA will also process X10 commands and events contained in a file.
     This is ideal for maintaining the CP-290's event schedule, or for
     running a Christmas "lightshow".  Simply tell XA which file to
     read, and XA does all the work.  For instance, to run the
     Christmas lighting command file:
          XA F=XMAS.CMD

     To download my event schedule to the CP-290, type:

          XA F=XA.CMD

     XA calculates sunrise and sunset times based on your latitude and
     longitude, and automatically compensates for any Daylight Savings
     changes.  XA can be programmed to handle events for special dates
     that may be weeks, months, or years in the future.  Best of all,
     XA can automatically update the CP-290 on a once-per-week basis
     without any intervention on your part (an Appliance module is
     needed to control your PC).

  Registered vs. Shareware
  ----------------------------------------------------------------------

     The next section highlights the many additions to XA since
     Version 2.0.  Note that some items are reserved only for
     "registered" users.  The "shareware" version of XA provides all
     the features of past versions, plus many newer features.  When
     you register your copy of XA, you will receive a floppy with a
     "registered" status allowing full use of the commands described
     in this manual.


======================================================================
3. New Features Summary for Version 2.x
======================================================================

     XA Version 2.00 has been completely rewritten, allowing such
     features as conditional statements, operators, and user-variables
     to be supported.  Also, XA performs sun-related calculations much
     faster.  The following list highlights the major enhancements of
     Version 2.x.  Additional details may be found in later sections.

  Improved HELP screens
       Type "XA /?" at the DOS prompt to get on-line information
       about XA's syntax and features.

  DEMO program for new users.
       Type DEMO to start a special introduction on the capabilities
       of XA.  Type DEMO_BW if you have a black and white or
       monochrome monitor.

  Power-fail recovery mode
       This feature allows you to restore the programmed state of
       each module in the eventuality of a power failure, or other
       circumstance.  XA determines the latest state of the module by
       examining the CP-290's event schedule.  Selected modules may
       be excluded from recovery, others can be forced to a
       particular state no matter what XA determines. 

  Program events "EVERY 'n' DAYS"
       XA now supports programming for events that need to repeat
       every `n' days.  For instance, you need to water your plants
       every 4 days, but it's impossible to schedule using MON, FRI,
       etc.

       The new "EVERY 'n' DAYS" tokens will automatically calculate
       which days to program events.  XA ensures accurate weekly
       scheduling even when the required days do not fall within the
       same 7-day period.

  Improved DATE handling.
     A new token "EXCEPT" has been added which allows to program 
     events to occur EXCEPT when certain dates arrive:

          DEFINE MEMORIAL_DAY DATE 5/31
          BEDROOM_LIGHTS ON WEEKDAYS 6:30 EXCEPT MEMORIAL_DAY

  Automatic Daylight Savings Time adjustment.
       Use the token DST to have XA determine when changes for
       Daylight Savings or Standard Time should go into effect. This
       means you only have to specify a single timezone token in your
       initialization file (XA.INI).

  IF/ELSE/ENDIF constructs.       (Registered Version Only)
       Finally! Support for conditional statements within your
       command files.  Now you can perform a test to see whether
       SUNRISE  falls within a certain time period, and schedule
       events based on the  result.  IF/ELSE statements may be nested
       up to 100 levels deep. 

  Variable assignments          (Registered Version Only)
       Variables may be used as temporary storage locations.  These
       variables may then be evaluated later using IF/ELSE constructs
       to trigger a DIRECT command or to program an EVENT.
     
  Logical, Arithmetic operators     (Registered Version Only)
       Operations may be performed on variables and later evaluated.

  Appends new events automatically.
       You may now easily append a new event from the command line
       without having to figure out where the next "free" event
       resides in the CP-290.  XA finds the empty event slot for you.

  GOSUB/RETURN
       In addition to GOTO statements, XA now supports calling
       subroutines (GOSUB), and returning to the original calling
       statement (RETURN). 

  INPUT/OUTPUT (I/O) control.     (Registered Version Only)
       Use your Joystick port, LPT port (or any other port) as a
       general purpose Input/Output port. Connect switches and/or
       relays to these ports and program XA to react to real-world
       events.

  INCLUDE files
       Use the INCLUDE token to instruct the XA parser to read
       additional initialization or command files. Different files
       may be included based on the results of conditional IF/ELSE
       statements.

  "ALL_LIGHTS_ON", "ALL_UNITS_OFF".
       These "undocumented" CP-290 commands are fully supported.

  Faster execution.
       XA reduces the number of passes required to process a file.
       Sunrise/set calculations are faster. Also, a new token "FAST"
       can be included in a direct command which informs XA to
       ignore the CP-290 acknowledgement message thus speeding up
       overall execution time.

  Conditional COLOR highlighting.
       XA can optionally display each line of the XA.INI and command
       file as it's parsed. In addition, you can define your own
       color attributes for conditional statements that evaluate TRUE
       or FALSE, as well as define special color attributes for
       EVENTS and DIRECT commands.  See "Screen Color Control".

  Shell to DOS capability.
       XA can invoke a copy of COMMAND.COM allowing you to execute a
       DOS program, batch file, etc. from within a command file.

  Utility to locate CP-290 port connection.
       A new utility called FINDX10.EXE searches all 4 COM ports for
       the CP-290 interface.  If it is found, you are asked whether
       you would like the parameters stored in the XA.INI file for
       you.

  Expanded POWERUP.EXE Utility
       An additional "week" argument has been added allowing you to
       detect certain conditions. For example, on the 2nd Friday of
       the month,  update the CP-290 and backup all hard drives.

  Other Features
  ----------------------------------------------------------------------

       Supports COM1...COM4  (Interrupt-driven or Polling)
       Fully configurable communications. COM1...COM4. Interrupt
       driven or polling.

       SUNRISE-SUNSET calculations
       XA calculates precise sunrise/sunset times for your location
       based on the latitude and longitude of your city.

       Specific DATE handling
       Request any event to occur days, months, even years from now.
       XA expands X10's time base by allowing you to program an event
       for any day in the future, or you can schedule an event to
       occur between two defined dates. You can also program modules
       to NOT activate on certain dates.

       Time synchronization
       XA can keep the internal clocks of your PC and CP-290 accurate
       to within 1 second of each other.  You can set either clock
       based on the time maintained by the other clock.

  Miscellaneous Features
  ----------------------------------------------------------------------

       X10.EXE compatible - creates X10.DAT file with the same
       module names and events that were downloaded by XA.

       Initialization file - XA.INI contains all module definitions,
       communication parameters, location coordinates, and other
       information that will greatly reduce redundant data used in
       command files.

       The tokens "TIMER", and "PAUSE" let you trigger X10 commands
       after a number of seconds have elapsed, useful for
       synchronizing X10-controlled lights with pre-recorded music.

       "NOW" allows you to program an event relative to the current
       time (for instance, turn off a battery charger 14 hours from
       now).

       "RANDOM" provides an even better security mode by offering
       precise control of random event times.

       Better reporting facilities.  XA has 2 report formats to
       document the events you downloaded to the CP-290.

       Monitor events as the CP-290 executes them and optionally
       log them to a file.

       You can easily change the basecode without losing all the
       data already stored in the interface.

       String substitution in the command file allows you to equate
       a device (FAMILY_ROOM_LAMP) with its module address (A3).


======================================================================
4. Utilities supplied with XA
======================================================================


  POWERUP.EXE
  ----------------------------------------------------
     This utility is provided for those of you who control your
     computer with an X10 Appliance module.  Powerup is designed to be
     called from your AUTOEXEC.BAT file.  You pass arguments to
     Powerup that specify a "window" of time based on day, week, and
     time. If your computer begins its boot phase during this window,
     it returns an errorlevel of 1, otherwise it returns a 0. This
     errorlevel can then be evaluated by simple batch file statements
     and a number of special functions can be executed.  For instance,
     you can have X10 turn on your computer at 3:00 AM every Sunday
     morning and automatically update the CP-290 with an entirely new
     schedule of events.  Your computer can then perform disk
     optimizations, disk backups, communications, etc., without any
     operator intervention. When all is done, a command can be called
     to turn the computer off (XA "COMPUTER OFF").  All this can take
     place while you sleep.  This is what automation is all about.

  FINDX10.EXE
  ----------------------------------------------------
     This new utility is provided to help you determine the
     configuration of the serial port your CP-290 is connected to.
     After FINDX10 searches all COM ports in your system, it
     determines the I/O address and IRQ level of the port and attempts
     to communicate with the CP-290. If it successfully locates the CP-
     290, it displays the port setup and prompts you if it is OK to
     save the data in your XA.INI file.


======================================================================
5. Installation
======================================================================

     First, copy the contents of this floppy to the same drive and
     directory in which your X10 software resides.  For example, if
     your X10 files are located on Drive C in the directory "X10", and
     the XA installation floppy disk is inserted in Drive A, you would
     type at the DOS prompt:

          C:
          CD \X10
          COPY A:\*.* C:

     If you've never used XA before, now would be a great time to see
     what XA is all about. Here's how to start XA's demonstration
     program - just type:

          DEMO      (FOR COLOR SYSTEMS)
          DEMO_BW   (FOR LCD OR MONOCHROME SYSTEMS)

     If you haven't already done so, include this drive and directory
     within your PATH statement of the AUTOEXEC.BAT file.  The "PATH"
     statement tells DOS where to locate frequently used executable
     files.

          SET PATH=C:\DOS;C:\X10;...

     You should set the XA environment variable to the drive and
     directory of your command files.  This environment variable,
     which can also be placed in your AUTOEXEC.BAT file, tells XA
     where to find its  initialization and command files.

          SET XA=C:\X10

     If you don't understand the concepts of the PATH or SET command,
     refer to your DOS User's Guide and Reference manual. Also, see
     the  AUTOEXEC.BAT supplied with this package for an example.

     Finally, let XA's utility program "FINDX10" search your
     computer's serial ports for the CP-290. FINDX10 will determine
     the IO port address and IRQ (interrupt vector) for that
     particular port. These parameters are important for the
     successful operation of XA. If the CP-290 is located, you will be
     prompted if it's OK for FINDX10 to write those parameters into
     your XA.INI initialization file. Enter 'Y' for YES if you agree
     with these values.  You can always edit these statements later.
     See the chapters "XA.INI - Initialization file" and "FINDX10.EXE"
     for more details.

     Please read the file READ.ME that was distributed on this floppy
     disk (or compressed archive). This file contains any last minute
     information that was not included in the printed documentation
     (or XA_203.TXT file).

     This document will often discuss examples found in other files.
     You may wish to print these files now so you can study the
     examples as they're being described:  AUTOEXC.BAT, XA.CMD,
     JOYSTICK.CMD, XA.INI, XMAS.CMD, and REGISTER.TXT


======================================================================
6. Getting Started
======================================================================

     XA may be invoked several different ways.  How you configured XA,
     or the types of parameters that you use with it, determine how XA
     behaves.

     Method 1 - The "HELP" screen.
     --------------------------------------------------
       At the DOS prompt, enter:

          XA

       XA will display the first of many different "help" screens.
       These screens include a brief synopsis of XA, and a list of
       available commands that it recognizes.  NOTE: This method will
       not work if the token XACMD is defined in your XA.INI file.
       The default XA.INI file shipped on this floppy will have XACMD
       "commented out" (or undefined).

     Method 2 - The "HELP" screen.
     --------------------------------------------------
       At the DOS prompt, enter:

          XA /?
          XA /H

       Again, XA will display the first of many different "help"
       screens.  Use this method if your XA.INI file utilizes the
       XACMD token and you wish to see the help screens.

     Method 3 - Executing a DIRECT Command from DOS.
     --------------------------------------------------
       At the DOS prompt, enter:

          XA "A1 OFF"

       The above is a direct command which sends an X10 Off command
       to the module with a House-Unit code of A1. Direct commands
       are always executed immediately.

     Method 4 - Storing an EVENT into the CP-290's memory via DOS.
     --------------------------------------------------
       At the DOS prompt, enter:

          XA "A1 ON MONDAY SUNSET"

       XA will determine which event slot is available in the CP-
       290's memory. The event will be downloaded for later
       execution.

     Method 5 - Executing a Command File
     --------------------------------------------------
       At the DOS prompt, enter:

          XA F=XA.CMD

       The file XA.CMD contains a series of EVENT or DIRECT command
       statements.  These statements are either executed immediately
       as they are parsed, or sent to the CP-290 to be activated at
       some future time.


======================================================================
7. Syntax and Command Line Arguments
======================================================================

     XA understands the following command line options:

       XA  ["commands"...] [f=filename] [-e] [+l] [+m] [+p] [-p]
           [+u] [+r1] [+r2] [c=comm port] [i=irq] [o=I/O addr] [/?]

     Options appearing on the command line always override any options
     that have been specified in XA's command and initialization
     files.  This gives you the final "say" when overriding defaults.
     Options and commands are parsed from left to right. Under normal
     circumstances, options may appear in any order without any
     conflict.  Many of these options have equivalent tokens that can
     be embedded within a command file or the XA initialization file
     (XA.INI). Therefore, you won't have to specify these options
     every time you execute XA.

    ["commands"]

       "commands" consist of one or more tokens that describe an
       event or direct command.  When you send a DIRECT command or
       EVENT via the DOS command line, a command consisting of
       several tokens must be enclosed in "quotation marks".   The
       quotation marks inform XA to treat the tokens as a group, not
       individual commands. For example:

          XA "A1 ON"

       In the above example, A1 and ON are tokens. Together they form
       a single command.  Multiple commands may appear in the command
       line as long as they are enclosed in their own quotation
       marks.  The next example shows the use of multiple commands to
       create a flashing effect.

          XA "A1 ON" "A1 OFF" "A1 ON" "A1 OFF"
     
    [f=filename]
       This is the name of the file containing the commands to be
       interpreted by XA.  To use XA in its file mode with a command
       file called MONITOR.CMD, you would type:

          XA F=MONITOR.CMD

       Commands contained in files do not have to be enclosed in
       "quotation marks".

       You can specify a default command file using the "XACMD" token
       in the XA.INI initialization file.

       See also:
          Miscellaneous tokens: XACMD
          XA.INI - Initialization file

    [-e]
       This option is used to prevent any communications to the
       interface.  When you use this option, the parser verifies
       every statement, but does not send any event information or
       direct commands to the CP-290.  Use this option for testing
       new command files.

    [c=comm_port]
       This allows you to select the serial port for communications
       with the interface.  You may select ports 1...4. For example,
       if your CP-290 is connected to COM3:

          XA C=3

       If not specified, the default port will be COM1.    When using
       this option, you are actually specifying both an IO address as
       well as the IRQ vector for this port.
  
       See also:
          Communication tokens: COM1...COM4 
          Command Line options: [o=io_addr] 

    [o=io_addr]
       This option allows you to select a different IO address from
       the default 3F8 hex.  If your serial port is setup for 2E8
       hex, then use:

          XA O=2E8H

       Under most circumstances, you should not need to use this
       option.

       See also:
          Communication tokens: IO x

    [i=irq#]
       XA supports interrupt-driven and polled-mode communications
       with the CP-290. In general, interrupt-driven communications
       work best, especially if you intend to use XA in a multi-
       tasking environment such as Desqview, Windows, or OS/2.
       Running in interrupt mode requires a dedicated IRQ line.  If
       the serial port connected to the CP-290 shares an IRQ with
       another device, then use polled-mode communications.
       
       Interrupt-driven:
          I=(3,4,5...).
          I=4  (DEFAULT FOR COM1).

       For polling-mode, use:
          I=0

       See also:
          Communication tokens: IRQ x

    [+m]
       This option will monitor the comm port for any events reported
       by the CP-290 after other XA operations have taken place.
       Press the <ESC> key to terminate.
  
       If the token XACMD appears in your XA.INI file, or you
       specifed a command file with f=file.cmd, then monitoring
       occurs after the command file has been parsed.  To skip
       parsing of the command file, you can use the "MONITOR" token
       instead:

          XA "MONITOR"

       See also:
          Reporting tokens:   MONITOR 
          "Monitoring and Logging Events" 

    [+l]
       This option will append any monitoring information to the file
       XA.LOG.  The report file will be saved on the same drive and
       directory as was specified by the XA environment variable
       (discussed in "Installation").
  
       See also:
          Reporting tokens: LOG
          "Monitoring and Logging Events"

    [+r1]
       This option will produce a report file (called XA.RPT) of all
       events that were just processed by the interpreter.  The
       format of the report contains a sorted list of events (based
       on time) for each day of the week.
     
       See also:
          Reporting tokens: REPORT1
          "Report Files"

    [+r2]
       This option will produce a report file (called XA.RPT) of all
       events just processed by the interpreter.  The format of the
       report contains a sorted list of events (based on time), for
       each module, for each day of the week.  The report file will
       be saved on the same drive and directory as was specified by
       the XA environment variable (discussed in "Installation").
       Any existing reports called XA.RPT will be overwritten.
       You may specify both report types to be included in the same
       file, as in the following example.

          XA +R1 +R2

       See also:
          Reporting tokens: REPORT2
          "Report Files"

    [+u]
       XA is able to bypass the lengthy event uploads from the CP-290
       by reading a copy of the schedule stored in the X10.DAT file.
       Some shareware programs may not update this file, causing a
       possible conflict when XA appends new events to the CP-290's
       memory, or when a powerfail recovery is attempted.  Use the
       "+u" option to force XA to upload the schedule prior to any
       other processing.  Later, XA will restore X10.DAT to reflect
       the latest schedule.

    [+p]
       Parses command file, then performs powerfail recovery.

    [-p]
       Immediate recovery based on stored events, no parsing of
       command file  takes place.
  
       Powerfail recovery allows you to restore each module to its
       scheduled state. By default, XA uses the last 6 days to
       determine the state.  You can tell XA to use fewer days if
       necessary. Simply append a number between 1and 6 to the
       command. If you want XA to review the event schedule of the
       previous 2 days in order to determine the correct state, then
       append a 2 to the command, for example:

          XA -P2

       Use "-e" in conjunction with either "+p" or "-p" to see how XA
       would restore each module without actually sending any X10
       commands.  You can use "+u" to ensure the latest events are
       uploaded and analyzed prior to recovery.
  
       See also:
          "Powerfail Recovery" 

    [/?][/h][/H]
       Displays a summary of the options described above, along with
       a list of all supported tokens recognized by the interpreter.
  

======================================================================
8. XA Tokens
======================================================================


  What are tokens?
  ----------------------------------------------------------
     A token is to an X10 command as a word is to an English sentence.
     Individual words are constructed to form a complete sentence -
     tokens are constructed to form a complete command.  This section
     will describe each token that is recognized by the interpreter.
     Some tokens may appear anywhere in the command.  For example, the
     command:

          XA "A1 ON"    (MAY ALSO BE CONSTRUCTED AS):
          XA "ON A1"

     In other instances, tokens must be arranged in groups.  Their
     order is important.  For example, the command to set your PC's
     internal clock to the time that is maintained by the CP-290 is:

          XA "SYNCHRONIZE PC"      <---THIS IS LEGAL

     If the tokens SYNCHRONIZE and PC were reordered as in the
     following command:

          XA "PC SYNCHRONIZE"      <---THIS IS ILLEGAL

     The interpreter would respond with a message indicating it did
     not recognize the token. Therefore, throughout this documentation
     any tokens that must be arranged in a certain order will be
     contained in curly braces {..}.  Other tokens may be optional and
     will be contained in parentheses (..) or brackets [..].

     Most or the examples in the next chapter describe how the tokens
     may be used from the DOS command line. Therefore, the tokens that
     make up a complete command will be enclosed in "quotation marks".
     Other examples show how the tokens may be used in a file,
     therefore, quotation marks are not used, or needed.


======================================================================
9. Tokens in Detail
======================================================================


  Action Tokens
  ------------------------------------------------------

    ON
       This token informs the interface to turn the selected modules
       ON.

          XA "A1 ON"

    OFF
       This token informs the interface to turn the selected modules
       OFF.

          XA "A1 OFF"

    {DIM %%}
       These two tokens specify the intensity level of the selected
       lamp or wall switch module.  The modules will turn on,
       brighten to full intensity, then dim to the percentage
       specified in the second token.  There are 16 different
       brightness levels available, the percentage you choose (0 to
       100) is mapped to one of these levels. The percentage level
       you select may not correspond exactly with level reported by
       the X10-supplied program X10.EXE.

          XA "A1 DIM 50"

    {ALL_UNITS_OFF HOUSE x}
       These tokens will issue the X10 "ALL_UNITS_OFF" command for
       the selected housecode. This command affects Appliance-style
       and Lamp Dimmer/Wall Switch modules.
     
          XA "ALL_UNITS_OFF HOUSE A"
     
       Using this command is faster than issuing:
     
          XA "HOUSE A UNIT ALL OFF"

    {ALL_LIGHTS_ON HOUSE x}
       These tokens will issue the X10 "ALL_LIGHTS_ON" command for
       the selected housecode. This command affects only Lamp
       Dimmer/Wall Switch modules.
     
          XA "ALL_LIGHTS_ON HOUSE A"
     
       Only one token in this category should appear in a command. If
       two or more of these tokens appear, only the last one will be
       processed.  For example:

          XA "A1 ON OFF"  -  WILL BE INTERPRETED AS:
          XA "A1 OFF"
     
       If you are trying to flash the lights, the proper way to
       perform this action is:
     
          XA "A1 ON"  "A1 OFF"
     
       You may activate as many modules as you want in a single
       command providing these modules share the same HOUSE code:

          XA "A1 A2 A3 A4 A5 A6 ON"

       To activate modules with different HOUSE codes, use separate
       commands:
     
          XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"

  Module Address Tokens
  -------------------------------------------------------------

    A1...P16
       This is a shortcut method of specifying both HOUSE and UNIT
       tokens.  The house code must appear first, followed by the
       unit code.  Specifying ALL is not permitted.

          XA "A1 ON"  "P16 OFF"

    {HOUSE x}
       These two tokens specify the HOUSE code of the module you want
       to select.  There are 16 HOUSE codes available,  lettered A
       through P.  This method of selecting addresses requires the
       use of the UNIT token.  Only one HOUSE token should appear in
       a command.

    {UNIT y}
    {UNIT ALL}
       These two tokens specify the UNIT code of the module you want
       to select.  There are 16 UNIT codes available, numbered 1
       through 16.  Specifying UNIT ALL operates on all 16 modules
       addressed by the HOUSE token.  This method of module
       addressing requires the use of the HOUSE token:

          XA "HOUSE A UNIT 1 ON"   OR,
          XA "UNIT 1 HOUSE A ON"

       Multiple UNITs may appear in a single command:

          XA "HOUSE A UNIT 1 UNIT 2 UNIT 3 ON"

       Turn off all units on HOUSE P:

          XA "HOUSE P UNIT ALL OFF"
          XA "HOUSE P ALL_UNITS_OFF"    (THIS IS THE FASTER METHOD)
     
       You may activate as many modules as you want in a single
       command providing these modules share the same HOUSE code:
     
          XA "A1 A2 A3 A4 A5 A6 ON"

       To activate modules with different HOUSE codes, use separate
       commands:
     
          XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"
     
       You can give your module's more descriptive names by using the
       DEFINE token. For instance, place the following line
       in your XA.INI file:

          DEFINE COFFEE HOUSE A UNIT 10

       To turn the coffee pot ON from your computer, all you have to
       type is:
     
          XA "COFFEE ON" OR
          XA "A10 ON"

  Coordinate Tokens
  -------------------------------------------------------------
     This group of tokens enable the precise calculation of sunrise
     and sunset times for your location.  This information can be
     found in almanacs, or extrapolated from maps.  Coordinates for
     major U.S. cities may be found in the file US_LATIT.TXT supplied
     with XA. Your local library or city hall may also have your
     city's precise coordinates.  These tokens should be placed in
     your XA.INI file so that all command files will be able to
     calculate sun-related events.

    {LATITUDE dms}
    {LATITUDE  ' "}
       Your latitude in degrees (0...+/-90), minutes (0...59) and,
       optionally, seconds (0...59).

          LATITUDE 4135'20"  # MENTOR, OH.  USA
          LATITUDE -33D53M # SYDNEY, AUSTRALIA

    {LONGITUDE dms}
    {LONGITUDE  ' "}
       Your longitude in degrees (0...+-180), minutes (0...59) and,
       optionally, seconds. Longitudes West of the prime meridian are
       positive, those East of the prime meridian are negative.  In
       the US, all longitudes are positive.

          LONGITUDE 8120'45" # MENTOR, OH.  USA
          LONGITUDE -151D10M  # SYDNEY, AUSTRALIA

    {TIMEZONE x}
       Exact calculations depend on the local time.  Use the
       following table to determine your time zone. Use the DST token
       to automatically adjust time changes.
  
                       ZONE       TIMEZONE
                     Eastern         5
                     Central         6
                     Mountain        7
                     Pacific         8
                  Alaska/Hawaii      10
                     Aleutian        11

                  Table 1 - U.S. Timezones
  
  
       Longitudes that are east of the Prime Meridian should use
       negative timezone values.
     
          TIMEZONE 5    # MENTOR, OH.  USA
          TIMEZONE -10# SYDNEY, AUSTRALIA

    DST
       Use the token DST to have XA determine when changes for
       Daylight Savings or Standard Time should go into effect. This
       means you only have to specify a single timezone token in your
       initialization file  (XA.INI).

          TIMEZONE 5  DST

  Clock Tokens
  -------------------------------------------------------------

    {SYNCHRONIZE PC (EXACT)}
       These tokens instruct XA to set your computer's clock based on
       the current time retrieved from the CP-290.  It will not
       affect the  computer's date.
     
          XA "SYNCHRONIZE PC"

       Use the optional "EXACT" token to wait for the X10 time to
       rollover to the next minute.  This provides a synchronization
       within 1 second, but forces you to wait for up to one minute
       for this rollover to happen.
     
          XA "SYNCHRONIZE PC EXACT"

    {SYNCHRONIZE X10 (EXACT)}
       These tokens instruct XA to set the time and day of the CP-290
       internal clock based on the current time retrieved from your
       computer.

          XA "SYNCHRONIZE X10"

       Using "EXACT" will force XA to wait until the PC's clock to
       rollover to the next minute.  This provides a synchronization
       within 1 second, but forces you to wait for up to one minute
       for this rollover to happen.

          XA "SYNCHRONIZE X10 EXACT"

       You might want to include the command XA "SYNCHRONIZE PC" in
       your AUTOEXEC.BAT file to set your PC's internal clock if your
       system lacks an on-board battery backed-up clock.  Note that
       this command will not set up the date since the CP-290 does
       not contain a real-time calendar.
  
       Use XA "SYNCHRONIZE PC" or XA "SYNCHRONIZE X10" in your
       AUTOEXEC.BAT file if either your PC or CP-290 does not keep
       accurate time.

  Day Tokens
  -------------------------------------------------------------
    Use of these tokens indicates a timed event, i.e., the complete
    command will be downloaded to the interface and stored there for
    later activation.

    SUNDAY, SUN
    MONDAY, MON
    TUESDAY, TUE
    WEDNESDAY, WED
    THURSDAY, THU
    FRIDAY, FRI
    SATURDAY, SAT
       These tokens describe the specific day of the event. Multiple
       day tokens may appear within a command.

          XA "MONDAY FRIDAY A1 ON TIME 7:30 AM"

    WEEKENDS, WEEKEND
       Event occurs on SATURDAY and SUNDAY.

    WEEKDAYS, WEEKDAY
       Event occurs MON, TUE, WED, THU, FRI.

    EVERYDAY
       Event occurs MON TUE WED THU FRI SAT SUN.
     
    TODAY
       Event will occur today only at the specified time.  It is then
       deleted from the interface after midnight.  If "OFFSET hh:mm"
       is also programmed causing the event to trigger after
       midnight, the event  will be modified for TOMORROW status.
  
     
    TOMORROW
       Event will occur tomorrow only at the specified time.  It is
       then deleted from the interface after midnight.  If "OFFSET
       hh:mm" is also programmed causing the event to trigger
       before midnight, the event  will be modified for TODAY status.
     
    EVERY 'n' DAYS (FROM (DATE) mm/dd/yyyy)
    EVERY 'n' WEEKS (FROM (DATE) mm/dd/yyyy)
       These tokens allow you to specify an event to repeat itself
       every 'N' days. Suppose you have a garden irrigation system
       that must be activated every 5th day.  It's impractical to use
       the DAY tokens (MON, SAT, etc) because each week would require
       a different set of days to be programmed. Using "Every 'n'
       Days" solves this problem by correctly specifying the required
       days on a weekly basis.

          GARDEN ON SUNRISE EVERY 5 DAYS

       Assuming you schedule XA to update the CP-290 every Sunday
       (using POWERUP), the module addressed as GARDEN would be
       programmed as follows:

          Week 1:
            SUN - JULY 24, 1994
            FRI - JULY 29, 1994
          Week 2:
            WED - AUGUST 3, 1994
          Week 3:
            MON - AUGUST 8, 1994
            SAT - AUGUST 13, 1994

       Use the optional "FROM DATE mm/dd/yyyy" tokens if you need to
       change the "period" of the event and you want to specify the
       new date which the event should be based on.  For instance,
       after Week 2 you want to activate GARDEN every 6 days instead
       of 5.  By changing the statement to:

          GARDEN ON SUNRISE EVERY 6 DAYS

       The result would be:

          Week 3:
            SUN - AUGUST 7, 1994
            SAT - AUGUST 13, 1994

       This is not what you wanted, since the difference between Aug
       3 and Aug 7 is only 4 days. To offset this effect, include a
       reference date so XA can calibrate subsequent events.

          GARDEN ON SUNRISE EVERY 6 DAYS FROM DATE 8/9/1994

       The results are:

          Week 3:
            TUE - AUGUST 9, 1994

       Activate the garden irrigation control between during the
       Spring and Summer:

          DATE 4/15 THRU 8/31 GARDEN ON SUNRISE EVERY 6 DAYS FROM 4/15

       You can also program an event cycle based on the number of
       WEEKS instead of days. Use the optional FROM DATE mm/dd/yyyy
       tokens to specify the reference date to calibrate XA.
       
     NOTES:
          If you leave off a DAY token when downloading an event to
          the CP-290, XA will assign the command as a TODAY-only
          event. Therefore, at midnight the event will be cleared from
          the CP-290's memory. The following command will take place
          at 11:00 tonight and be deleted at midnight since it was
          given "TODAY" status (no other DAY was specified):

              XA "FAN ON TIME 11:00 PM"

          Registered Users - Using the "CDAY" token in conjunction
          with "SAT,SUN MON, TUE, WED, THU, FRI, WEEKEND, WEEKDAY"
          tokens allows you to program special functions based on the
          current day. For example, the statements below will the
          initialize the default command file (using XACMD) based on
          the current day.

              IF ((CDAY == SAT) OR (CDAY == SUN))
                 XACMD WEEKEND.CMD
              ELSE
                 XACMD WEEKDAY.CMD  ENDIF

  Specific Date Tokens
  -------------------------------------------------------------
    Since the CP-290 does not contain an on-board calendar, there is
    no direct method of storing an event that occurs more than 1 week
    away.  However, XA has the ability to evaluate dates and as long
    as XA is run at least once a week it can determine the
    appropriate time to download the event.  This feature allows you
    specify an event weeks, months, or years in advance.

    Date features:
         You can specify an event to occur on specific days of each
          month (such as every 10th day of the month), or annually
          (every 4th of July).
  
        Events may be scheduled to trigger on selected days between
          specific dates (such as Christmas and New Year's).  You can
          also program an event to NOT happen on an individual date,
          or between certain dates.
  
         XA makes use of screen color control (see VIDEO ) to
          show you if a scheduled event meets date criterion.
       
     To guarantee that specific dates will be evaluated and events
     will be triggered at the proper time in the future, plug your
     computer into an Appliance module and have the CP-290 turn your
     computer on automatically on a once-per-week basis.  By using
     XA.EXE in conjunction with POWERUP.EXE (supplied with this
     package) you can have a new set of events automatically
     downloaded to the CP-290.  Now you'll never forget to update your
     CP-290, your computer does it for you automatically.  This is
     what "automation" is all about.  See section "Powerup" for more 
     details.

     When using the following "DATE" tokens, you should include the
     "ERASE" token at the beginning of your command file.  ERASE will
     clear the entire contents of the CP-290, removing all event
     information. The reason you want to erase its memory is because
     once XA downloads an event to the CP-290, it will remain there
     until it is deleted or overwritten.  The next time XA is run
     (next week) the event may still remain and trigger itself again
     and again until it is either manually deleted, or eventually
     overwritten by a new event. ERASE ensures that the data is
     cleared and that the interface will contain fresh information.
     Also, since all your information is stored in a command file, the
     relevant information will always be placed in the CP-290.



    {DATE mm/dd/yyyy}
       Event occurs on specified date.  You must specify the date in
       the  following format:

          Month  - none, 1, or 2 digits (1 = Jan ...  12 = Dec)
          Day    - none, 1, or 2 digits
          Year   - none, 2, or 4 digits

       To specify module A5 ON July 4, 1994 at 5:00 pm:
          A5 ON DATE 7/4/1994 TIME 5:00 PM

       You may omit fields which is the equivalent of specifying any
       month, day, or year.  Each field must be delineated by a
       separator, either a '/' or '-' character.  For example, to
       specify module A5 to turn OFF on the 4th of every month at
       6:00 AM:

          DATE /4/ A5 OFF TIME 6:00 AM

       To specify module A5 to turn ON every 4th of July at sunset,
       leave off the "yyyy" field:

          DATE 7/4/ A5 ON SUNSET
     
       An exception to the separator requirement arises when the
       "yyyy" is not being programmed -simply omit the '/' or '-'
       character between the "dd" and "yyyy" fields. The above
       statement could be written as:

          DATE 7/4 A5 ON SUNSET

       You may specify multiple dates in the same command:

          DATE 7/4 DATE 7/6 DATE 7/8 A5 ON SUNSET

    {DATE mm/dd/yyyy THRU (DATE) mm/dd/yyyy (DAY)}
       The event will occur EVERYDAY between the two dates unless you
       place specific DAY tokens within the command.  Use the same date
       format conventions as described above.

       If you will be going on vacation between July 1, 1995 and August
       1, 1995, and you want the bedroom lights (A3) turned ON and OFF
       every weekday in a random fashion during the evenings:

          DATE 7/1/1995 THRU 8/1/1995  ON A3 TIME 9:00 PM SECURITY WEEKDAYS
          DATE 7/1/1995 THRU 8/1/1995 OFF A3 TIME 11:30 PM WEEKDAYS

       To turn ON your Christmas lights everyday between Thanksgiving
       and New Year's Eve, turn them OFF at 10:00PM on weekdays, and
       turn them off at 11:30 during the weekends:

          DEFINE THANKSGIVING DATE 11/24/95
          DEFINE NEW_YEARS_EVE DATE 12/31/95
          THANKSGIVING THRU NEW_YEARS_EVE  XMAS ON SUNSET
          THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 10:00 PM WEEKDAYS
          THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 11:30 PM WEEKENDS

    EXCEPT
       Once XA parses this token, any DATE (or DATE...THRU)
       statements become "exceptions", that is, events will not be
       scheduled to activate during that date (or period). For
       example, to turn a lamp (A7) on every weeknight except
       Memorial Day:

          A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31

       You may specify multiple exception dates in the same command:
     
          A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1

     NOTES:
         Events that are not downloaded because they do not meet the
          range criteria will be displayed using the VIDEO2 screen
          attributes (to signify a FALSE condition).
     
         Use the format:
          {EXCEPT DATE MM/DD/YYYY THRU (DATE) MM/DD/YYYY (DAY)}
          to  prevent an event from occurring between two dates.
          EVERYDAY will be assumed unless you place specific DAY
          tokens within the command.  For example, to prevent the
          porch lights from coming on while your Christmas lights are
          on:

          PORCH ON SUNSET EXCEPT DATE 12/1/1994 THRU 1/1/1995

     Special Note:
     When dates "rollover" into the next year, you must specify the
     "year" within the date statement (as in the above example).

         Use the format:
          {DATE MM/DD/YY THRU (DATE)  MM/DD/YY EXCEPT DATE MM/DD/YY
               THRU (DATE) MM/DD/YY}

          to specify a range of dates that a module should not
          activate, within a range of dates that it should be
          activated.  For instance, turn on deck lights only during
          the summer, except while you are on vacation:

               DECK ON SUNSET DATE 6/21 THRU 9/22 EXCEPT DATE 7/1 THRU 7/14

  Time Tokens
  -------------------------------------------------------------
    Use of these tokens indicate a timed event, i.e., the complete
    command will be downloaded to the interface and stored there for
    later activation.
     
    {TIME hh:mm (AM/PM)}
       Schedule event at a certain time.

          XA "D1 ON SUNDAY TIME 12:30 AM"

       AM is the default. You may specify military-style time as
       follows:

          XA "D1 ON SUNDAY TIME 23:34 "

    SUNRISE
    SUNSET
       These tokens will calculate the sunrise or sunset for the day
       token in the command.  The use of these tokens also requires
       the LATITUDE, LONGITUDE, and TIMEZONE (and optional DST)
       tokens to be included in  the XA.INI file.

          D1 ON MONDAY SUNSET

       If multiple day tokens appear in the command line, the sunrise
       or sunset time will be the average sunrise or sunset time for
       the next seven days.

          MONDAY TUESDAY WEDNESDAY ON SUNSET D1
     
       If more accuracy is needed, then break each daily event into
       its own command.
     
          MONDAY ON SUNSET D1
          TUESDAY ON SUNSET D1
          WEDNESDAY ON SUNSET D1

    {OFFSET +/-hh:mm}
    {OFFSET +/-mins}
       Push or postpone the scheduled event by up to 24 hours (1440
       minutes).  This token is useful if you want to activate lights
       at dusk rather than sunset, or to deactivate lights at dawn
       rather than sunrise.  The '+' sign is the default condition,
       you must specify the  '-' if needed.  To turn ON lights 30
       minutes after sunset:
     
          MONDAY ON SUNSET D1 OFFSET 30
     
       Turn lights OFF 1 hour before sunrise:
     
          MONDAY OFF SUNRISE D1 OFFSET -1:00
     
       Use DEFINEs  for another way of  specifying DUSK or
       DAWN using the DEFINE token.  For example:
     
          DEFINE DUSK SUNSET OFFSET 30
          DEFINE DAWN SUNRISE OFFSET -1:00
               :
          MONDAY ON DUSK D1  MONDAY OFF DAWN D1


    {NOW +mm}
    {NOW +hh:mm}
       Creates a one-shot event based on the current DOS day and time
       and the hh:mm offset specified in the token. The event will
       initially be given a "TODAY" status.  If the added offset
       causes the event to be scheduled past midnight, the event will
       be converted to "TOMORROW" status.  In either case, the event
       will be deleted from the CP-290 at midnight following its
       activation.
  
       The following command file example shows how to activate a
       battery charger and then turn it off 14 hours later. The
       example file is called CHARGER.CMD.
     
          DEFINE CHARGER H1
          CHARGER ON      # TURN THE CHARGER ON...
          CHARGER OFF NOW 14:00 # HAVE THE CP-290 TURN IT OFF 14 HRS LATER
     
       Earlier versions of XA required the use of the EVENT token in
       order to prevent overwriting existing events in the CP-290's
       memory.  Now XA automatically appends the command to current
       schedule, eliminating the need to figure this out manually.
  

    {RANDOM +/-hh:mm}
    {RANDOM +/-mins}
       These tokens surpass the CP-290's built-in security feature by
       providing greater control over the random event sequence.
       "HH:MM" is the number of hours and minutes that a random
       offset should be added/subtracted from the programmed time.
       This offset should be in the range of 1 minute to 24 hours
       (1440 mins).
       
       If "hh:mm" is programmed with a "+" sign, then the calculated
       random value will be added to the programmed time. The
       following example will add between 0 and 9 minutes to the
       requested time, that is, anywhere between 5:00 PM and 5:09 PM.
     
          A5 ON TIME 5:00 PM RANDOM +9
     
       If "mm" is programmed with a "-" sign, then the calculated
       random value will be subtracted from the programmed time. The
       following example will subtract between 0 and 15 minutes from
       the calculated SUNRISE time. If SUNRISE occurs at 6:00 AM,
       then the resulting time could be anywhere in the range of 5:45
       through 6:00.
     
          SUNRISE RANDOM -:15
     
       If "mm" is programmed without any sign, then the calculated
       random value will either be added or subtracted to/from the
       programmed time.  For example, to allow 90 minutes on either
       side of SUNSET:
     
                                # SUNSET @ 9:00 PM
          SUNSET RANDOM 1:30    # TIME RANGES BETWEEN 7:30 PM...10:30 PM

       RANDOM, as well as OFFSET, will automatically change the day
       if the adjustment causes a rollover into the previous or next
       day.
     

    NORMAL
       This token activates the event at the specified time.  It is
       the default mode, therefore it does not need to be specified.

    SECURITY
       This token allows the CP-290 to psuedo-randomly select the
       activation time of the event.  This activation occurs within
       the hour of the programmed time.  Therefore, if the downloaded
       time was for 7:30 PM, actual activation time could range from
       7:00 PM through 7:59 PM. This mode provides a security feature
       giving your lighting a more lived-in look.

          XA "A1 ON TIME 7:30 PM SECURITY EVERYDAY"



  Direct Command Control Tokens
  -------------------------------------------------------------
     The following tokens may be used within an XA command file so you
     can use the CP-290 to perform a series of lighting effects.
     Certain commands may be repeated a limited number of times or
     forever.  Commands may also be synchronized with a key press,
     allowing special effects with a high degree of accuracy.  The
     "registered" version of XA can also read data from an I/O port,
     allowing X10 commands to be synchonized with an external event.
     
     PAUSE
       When this token is executed, it displays a message and halts
       further execution of the command file.:

          "PRESS ANY KEY TO CONTINUE..."

       When a key press is detected, an internal timer maintained by
       XA is reset to ZERO, and any remaining commands are executed.
       The internal timer is used in conjunction with the TIMER
       token.  This command is useful for synchronizing a series of
       commands to an external event.  See TIMER below, for an
       example.

    [module command] TIMER hh:mm:ss.s
       This token informs XA to issue a command when the internal
       timer reaches "hh:mm:ss.s".  The built-in timer is initialized
       to 0 when XA is invoked, or whenever a key press follows a
       PAUSE command, or when the token "RESET" is parsed. All
       subsequent TIMER commands are evaluated from the point at
       which the internal timer was initialized.

       One very useful application of the PAUSE and TIMER commands is
       to synchronize X10-controlled lighting sequences with pre-
       recorded  music.  For instance, you could assign each song its
       own command  file.  Each file would start off with a PAUSE
       (Registered version may use INPORT) token to intialize the
       timer, as well as provide a means to start the music and
       command chain from a common point.  TIMER statements would
       specify the exact times that the CP-290 would trigger an X10
       command at an appropriate moment in the song.
     
          PAUSE                    # WAIT FOR ANY KEY PRESS, RESET TIMER
          A1 ON TIMER 0:0:10.0     # AT 10 SECONDS, TURN ON A1
          A1 DIM 0 TIMER 0:0:20.5  # AT 20.5 SECONDS, FADE LIGHT OUT.
     
       In this example, the PAUSE waits for a cue to start the
       sequence. 10 seconds later, A1 is activated. 20.5 seconds
       after the cue, A1 is DIMMED to a level 0.
  
       XA will automatically anticipate and adjust for any delays
       that may be caused by the CP-290.  For instance,  the amount
       of time it takes to turn on a lamp may take as much as 1.4
       seconds. Even worse, the CP-290 forces a lamp module to go to
       the fully BRIGHT state before allowing the module to be dimmed
       - delaying the actual effect by 6 seconds.  In order to have
       XA compensate for these delays, you should place an X10
       command on the same line just prior to the timer command.  For
       example, the following line turns the lamp on after 7 seconds.
       However, XA actually issues the command at 5.6 seconds:
     
          A1 ON TIMER 0:0:7.0
     
       Likewise, to completely dim a module to 0% after 10 seconds,
       XA will begin issuing the command after approximately 4
       seconds have elapsed.
     
          A1 DIM 0 TIMER 0:0:10.0
     
       If no commands are programmed on the same line as the TIMER
       statement, then a default adjustment of 1.4 seconds will be
       used for  commands that appear later.  It is very important
       that you program the 'hour' and 'minute' fields, even if they
       are zero. Otherwise, XA will convert the 'seconds' field to
       minutes, and you'll be waiting a long time. For example, do
       this:
     
          TIMER 0:0:15.5 <--- DO THIS
          TIMER 15.5     <--- NOT THIS

    RESET
       When the RESET token is parsed, the internal timer maintained
       by XA is preset to 0.  The PAUSE token also presets this
       internal timer to 0, but only after a key has been pressed.
       This token may be useful when used in conjunction with the
       "INPORT port" statement. (INPORT can monitor a  bit of a
       selected port and force a RESET when the bit goes TRUE. INPORT
       is only available in the "registered" version).

    {DELAY hh:mm:ss}
       These tokens allow you wait for the specified number of hours,
       minutes and seconds to pass before executing the next command.
       These delays are relative to the present time and do not work
       in conjunction with the TIMER or PAUSE tokens.  Make sure you
       program the HH, MM, SS fields. To wait 5 seconds between
       commands, use:
     
          A1 OFF
          DELAY 0:0:5
          A2 ON


    STOP
       Normally, XA stops execution when it reaches the end of a
       command file.  The STOP token forces XA to immediately stop
       execution. It may be placed anywhere in the command file. See
       the GOSUB example later in this document for an example.

    :LABEL
       This token identifies a location in your command file that you
       may GOTO or GOSUB later.  Each label must start with a colon
       ":" character.  Normally, labels will occupy a line by
       themselves, however they may appear in a line containing other
       tokens.

    :EXIT
       This special label has been reserved for providing controlled
       shutdown commands.  This label must begin with the colon ":"
       character.  Whenever the <ESC> key is pressed, the interpreter
       will jump to the location where the :EXIT label is located and
       execute any commands placed after the label. Therefore, the
       :EXIT label should appear towards the end of the command file.
       Note that the :EXIT label is not mandatory.  If <ESC> is
       pressed and the :EXIT label does not appear in the file, then
       the interpreter simply aborts the remaining commands.  Examine
       the use of :EXIT in the example below.

    {GOTO :label}
       These statements instruct XA to jump to a sequence of commands
       identified by the ":label" and begin executing them.  XA
       continues executing all remaining statements from that point.
       If XA has encountered ":label" previously, it will immediately
       jump to that location. Otherwise, XA will begin searching for
       ":label" in the remaining portion of the current file, or
       within other files that may have been "INCLUDED".

       Earlier versions of XA used the following syntax:

          GOTO :LABEL TIMES

       where "times" acted as a counter.  This method is no longer
       supported. Use the conditional statements (IF/ELSE -
       "registered" versions only) instead to control looping.

       The following code flashes (turns ON and OFF) a module
       addressed as A1 three times. It uses a variable (see
       "Variables") named "COUNTER" that is incremented and
       tested every time the loop is executed. When COUNTER reaches
       3, the IF portion of the test is no longer true, so XA
       continues with the rest of the program:

          COUNTER = 0               # DECLARE AND INITIALIZE COUNTER TO 0
          
          :LOOP
          A1 ON
          A1 OFF
          COUNTER = COUNTER + 1
          IF (COUNTER < 3)
                  GOTO  :LOOP
          ENDIF
          
          :EXIT
          A1 OFF

       Note the special use of the ":EXIT" label in the above
       example. If the user pressed the <ESC> during execution inside
       the loop, XA would abort the loop and search for the ":EXIT"
       label. If found, XA would execute the "A1 OFF" statement
       ensuring that the module was in a known state. Without
       ":EXIT", XA would abort and possibly leave A1 in the ON state.
       
       By using the LABEL and GOTO constructs, you can produce some
       pretty sophisticated lighting displays.  One application where
       this could be put to use is for Christmas lighting.  Consider
       placing solid color Christmas tree light strands on individual
       lamp dimmers.  Vary the brightness levels of each strand for
       an everchanging lighting effect. See the sample file XMAS.CMD
       for an example.

    {GOSUB :label}
    (statements go here...)
    RETURN
        These statements instruct XA to jump to a sequence of commands
       identified by ":label" and begin executing them. XA continues
       executing all remaining statements until it reaches the
       "RETURN"  token. XA then returns control of the program to the
       point from which  it came.
     
       If XA has encountered ":label" previously, it will immediately
       jump to that location. Otherwise, XA will begin searching for
       ":label" in the remaining portion of the current file, or
       within other files that may have been "INCLUDED".
       
       Placing a subroutine in a program allows you to repeat a
       sequence of statements in several places without writing the
       same statements several times.
       
       It is good practice to place subroutines in the beginning of
       the command file so that searching will be minimized. See the
       sample "XMAS.CMD" command file for an example.
       
       XA may call subroutines that are present in the current file,
       or any previously "included" file. You may nest up to 20
       subroutine levels.
       The previous "flash" example (using GOTO's) could be rewritten
       to use GOSUBS as follows:

          GOSUB :FLASH  # ONCE...
          GOSUB :FLASH  # ...TWICE
          GOSUB :FLASH  #    ...THREE TIMES
          STOP          # TELL XA TO STOP (PREVENTS RUNNING INTO SUBROUTINE)
     
          :FLASH        # START OF SUBROUTINE
          A1 ON  
          A1 OFF  
          RETURN        # RETURN TO ORIGINAL CALLER
     
          :EXIT         # SPECIAL SHUTDOWN SEQUENCE...
          A1 OFF        # ...ENSURE A1 IS OFF

    FAST
       By default, XA always waits for an acknowledgement message
       from the CP-290 after sending a direct command. You can avoid
       this wait and speed up the overall execution of XA by
       including the token "FAST" in your command:

          XA "PHONE_IN_USE  ON  FAST"

       FAST is best used in single command statements. If you attempt
       to send multiple direct commands using the FAST token, XA will
       be forced to wait for the acknowledgement message before
       issuing the remaining commands.
  
       Some computers may experience problems when XA executes a
       single statement in a batch file using the FAST token. Avoid
       using the FAST token when the TSR program "XT.EXE" is
       installed.  In some instances, XA may restore the old
       communication interrupt vectors while the acknowledgement
       message is in transit from the CP-290. This may result in XT
       reading an incomplete message.  It may take several messages
       for XT to correct itself.  You should experiment with your
       computer to see if this affects your setup.
  
       FAST only works with DIRECT commands.  FAST has no effect on
       EVENTS since these commands are managed by the CP-290
       firmware.

     

=====================================================================
Communications Tokens
=====================================================================

     This group of tokens allow you configure XA for your particular
     computers communications setup. The following table lists the
     "standard" I/O port addresses as well as typical IRQ assignments
     for the first (4) serial ports. Note the potential IRQ conflict
     that might arise with devices COM1/COM3 and COM2/COM4 because of
     the shared IRQ's.  If you have more than 2 devices attached to
     your computers serial ports, beware of this conflict and resolve
     it by assigning a different IRQ to the offending port.


              Comm Port   I/O Address    IRQ Level
                COM1       3F8H (Hex)        4
                COM2          2F8H           3
                COM3          3E8H           4
                COM4          2E8H           3

                 Table 2 - COM Port Parameters

     XA was designed to work using interrupt-driven communications
     allowing features such as "monitoring" to operate effectively.
     Since some users are unable to dedicate a unique IRQ for the CP-
     290 serial port, XA can be configured to communicate in a
     "polled" fashion. Simply use the "i=0" command line option or
     "IRQ 0" statement in your XA.INI file.

    COMx
       This token allows you to specify which comm port the interface
       is attached to.  This token was intended to be placed in the
       XA initialization and/or command files.

          COM3

       If your port IO address does not match those in the above
       table, then use the command line parameter [o=xxx] , or the
       file mode token "IO" (see below) to customize the
       communication characteristics.

     
    {IO x}
       This option allows you to select a different IO address from
       the default 3F8H (hex).  If your serial port is setup for
       2E8H, then use the following line in your command file:

          IO 2E8H

       Notes:
           When specifying a HEXADECIMAL number, you must include the
            trailing "H" character.
           These tokens were intended to be placed in the initialization
            or command files.



    {IRQ x}
       This option allows you to select a different IRQ level from
       the default interrupt 4.  To use COM3 (an IO address of 3E8)
       with an IRQ level 5, use the following commands in the XA
       initialization file:
     
          IO 3E8H
          IRQ 5

       Use IRQ 0  for "polling mode" communications if you can't
       configure your system with a free IRQ for the CP-290 port.
       Note that operations such as Monitoring and Logging may not
       operate correctly in polled mode.

     
=====================================================================
I/O Port Control     ( ** Registered Version Only ** )
=====================================================================

    XA can read and write to most of the I/O ports. Of particular
    interest is the Joystick or Game port. This port (location 201
    Hex) provides up to four digital inputs. XA can read the state of
    these ports and react accordingly.
     
    {(variable =) INPORT io_port}
       Read the status of the selected port, and optionally store it
       into a variable for later processing.  Example: Read the
       status of the Joystick port (201H) and save it into a variable
       called "joy_port".
     
          JOY_PORT = INPORT 201H

    {OUTPORT io_port value}
       Output a byte value to the selected io_port. Example, turn
       data bit 1 of LPT1 on:

          OUTPORT   378H   1
                                
                                
                                
                           IMPORTANT NOTE:
                                  
     When dealing with IO ports, make sure you know what you are
     doing. Connecting devices that should not be connected to a port
     may cause damage to your computer, its peripherals, even you. Be
     careful that you are writing to the proper ports, otherwise you
     may crash your system.  If you are not sure what you are doing,
     then you better not do it. I will in no way be responsible for
     your use, misuse, or abuse you might possibly inflict on you or
     your computer.
                                

=====================================================================
Miscellaneous Tokens
=====================================================================

    {DEFINE x z}
       This token is designed to be used in initialization or command
       files.  It allows you to substitute several tokens into a
       single token of your choice. It will help to make command
       files more readable.  For example, you can assign the token:

          "XMAS_ON"
       to an equivalent group of tokens, such as:
     
          "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY"
     
       as follows:

          DEFINE   XMAS_ON   HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
                   <- X ->   <------------------ Z ---------------->

       Notice that the "x" portion uses underscore characters "_" to
       separate the words but to keep the string contiguous.  This is
       important because the XA interpreter looks for the first SPACE
       character to separate the "x" and "z" components.  All
       subsequent SPACE characters are ignored.
       Later in the command file, you can use the following command
       to activate your Christmas lights:
     
          XMAS_ON
     
       Internally, XA will convert this string to its equivalent:
          HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
     
       More Examples:
            :
          DEFINE PLANT_GROW_LIGHTS A8
          DEFINE OUTSIDE_LIGHTS A1
          DEFINE ALL_ON ALL_LIGHTS_ON HOUSE A ON
            :
          PLANT_GROW_LIGHTS ON TIME 6:00 AM EVERYDAY
          PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY
            :
          OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
            :
          ALL_ON SUNDAY TIME 7:30 PM
     
       Using DEFINEs helps make the monitoring and logging screens
       more readable.  Refer to section "Monitoring and Logging
       events" for additional information.

    {EVENT xxx}
       The CP-290 can store up to 128 events in its memory.  Each
       event occupies fixed locations in memory.  Prior to XA Version
       2.0 you were required to assign a unique event number if you
       did not want to overwrite an existing event.  Since XA now
       automatically determines the next available slot for you,
       there is little need for these tokens.  However, these tokens
       remain as part of XA should you need to overwrite a particular
       event.
  
       When you produce a report file, the event number assigned to
       each event is printed in the right-most column of the listing.
       An * (asterisk) will be placed next to the event number if the
       event is scheduled to occur on multiple days.
     
    {CLEAR EVENT xxx}
       These tokens delete the specified event from the computer
       interface.  See description for EVENT xxx above. Only 1 event
       may be cleared per command.
     
          XA "CLEAR EVENT 100" "CLEAR EVENT 101"
     
       When an event is cleared from the interface, the actual memory
       locations it occupied are cleared to zero.  All subsequent
       events remain in their assigned memory locations.  Use the
       report listing to display each events number (or location) in
       the CP-290. This number is printed in the right-most column of
       the report.  Any event numbers that are followed by an
       asterisk "*" indicate that the event will be triggered on
       multiple days.
     
    ERASE
       This token erases all events from the CP-290 memory. If you
       use XA to maintain your CP-290 schedules, then this token
       should appear at the beginning of the command file. This is
       important because XA tries to append new events to the
       existing events in the CP-290.  If you do not erase the CP-290
       memory, you will exceed its 128 event capacity.

       Always use this token when specific dates (declared by the
       DATE/THRU tokens) are present in your command file.  This way,
       once the date has come and gone, it will be deleted from the
       CP-290 memory automatically.

    {BASECODE x}
    {HOUSECODE x}
       These tokens change the base housecode of the interface
       WITHOUT losing the data stored in the interface. Prior to
       changing the housecode, a complete upload of all events stored
       in the interface is performed.  The housecode is changed, then
       all events are downloaded back into the interface.  Valid
       housecodes are A...P.
     
          XA "BASECODE  D" -OR-
          XA "HOUSECODE  D"
     
       XA displays a bar graph during the upload and download phases
       providing a visual indication of progress, as well as the
       amount of available event storage.

    DIAGNOSE
       This token triggers the CP-290's built-in diagnostic routine.
       You will be informed of the results after a few seconds.
       Since the diagnostics overwrite any existing events, XA first
       uploads the contents of the CP-290 memory prior to the
       diagnostic.  If the diagnostics report an OK status, then the
       events are downloaded back to the CP-290.

    {XACMD filename}
       This token is intended to be placed inside the XA
       initialization file.  It defines the default
       command file that XA should parse and execute if no other
       commands files or direct commands are present.  If your XA.INI
       file contains the following line:

          XACMD EVENTS.CMD

       Then each time XA is invoked without any arguments, the file
       "EVENTS.CMD" will be parsed and executed.  The following
       examples show how you can specify unique command files based
       on the day of the week (see later section for IF/ELSE
       programming):
     
          IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
            XACMD M_W_F.CMD
          ELSE
            XACMD XA.CMD

    {INCLUDE filename}
       These tokens allow XA to parse additional files.  When XA
       reads the "INCLUDE filename" statement, it begins to parse the
       requested file.  Upon reaching the end of the new file, XA
       will begin parsing the original file at the statement
       following the INCLUDE.  This concept  is similar to calling
       and returning from a subroutine.
       
       The include file may be called from your XA.INI as well as
       XA.CMD (or any other file). Include files may be nested up to
       20 levels deep.  The following example shows you how XA.CMD
       could include VACATION.CMD if the current date (CDATE) falls
       between AUG 21 and AUG 28.
     
          IF ((CDATE >= DATE 8/21) AND (CDATE <= DATE 8/28))
            INCLUDE VACATION.CMD
          ENDIF

    {DOS command_string}
       The DOS token allows you to execute any DOS command from
       within XA.  The following line (taken from JOYSTICK.CMD) tells
       the SoundBlaster to play the GREETING.VOC file:
     
          DOS C:\SBLASTER\VPLAY C:\SBLASTER\GREETING.VOC
     
       Display a directory:
     
          DOS DIR
     
       Use XA to kickoff a communications program at a precise time
       (see PHONE.CMD):
     
          # AT 11:15, CALL BBS...
          DISPLAY OFF
          :WAIT
          IF (CTIME < TIME 11:15 PM)
            GOTO :WAIT
          ENDIF
          DOS PROCOMM OPTIONS...      # INVOKE PROCOMM WITH 
                                      # COMMAND LINE PARAMETERS...

    BEEP
       The BEEP token will issue a short tone through your PC's
       speaker.

    {DISPLAY ON}
    {DISPLAY OFF}
       XA will display just about every statement as its parsed.
       There may be instances where you don't want the display
       active, for instance, parsing the XA.INI file, comments, or
       when critical loops are being  processed. XA allows you to
       control the display with the commands:
     
          DISPLAY ON
          DISPLAY OFF
     
       In some instances, it will be necessary to issue the command
       display off because of time considerations. If you are in a
       tight loop monitoring an IO port for a bit to change, you may
       miss the toggle while XA is printing the current statement to
       the CRT. By turning the display off, you allow XA to execute
       much faster, virtually eliminating any bottlenecks that may
       cause XA to miss an event from the port.
       
       The sample XA.INI file shipped with this version has the
       display turned off at the start of the file, and restores the
       display at the end of the file.
     
  Reporting Tokens
  ----------------------------------------------------------------
    See section "Monitoring and Logging events" for
    additional information about how these tokens may be used.

    MONITOR
       This token informs XA to continuously monitor the
       communications port for any messages sent by the CP-290 when
       it executes a stored event or when one of the panel buttons is
       pressed.
  
       "Monitor" and its command line counterpart "+m" may operate
       differently based on your XA configuration.  See section -
       "Monitoring and Logging Events" for more information.

    LOG
       This token appends the monitored information in the file
       XA.LOG.

    REPORT1
       This token will produce a report file with events sorted by
       day and time.

    REPORT2
       This token will produce a report file with events sorted by
       day, module, and time.


=====================================================================
10. Powerfail Recovery
=====================================================================

     Powerfail recovery allows you to restore each module to its
     scheduled state.  XA determines this state by reading the event
     information stored in the CP-290.  By default, XA uses the last 6
     days to determine the state.  You can tell XA to use fewer days
     if necessary.  Also, you can tell XA to FORCE a module to a
     particular state overriding the calculated state, or have XA
     IGNORE the calculated state and not send any command to the
     module.

     Powerfail recovery may be invoked from the command line using the
     following parameters:

          +P- PARSES COMMAND FILE, THEN PERFORMS RECOVERY.
          -P- IMMEDIATE RECOVERY, NO PARSING OF COMMAND FILE.

     If you want XA to review the event schedule of the previous 4
     days in order to determine the correct state, then append a 4 to
     the command, for example -P4 or +P4.  The maximum number of days
     that XA can scan is 6.  XA uses the information stored in the
     file X10.DAT for the schedule calculations because it's faster
     than uploading all the data from the CP-290.  Also, if you change
     your schedule with X10's original software package (X10.EXE),
     those changes will be reflected properly.  If XA can not find the
     X10.DAT, then XA will upload the data from the CP-290.  You can
     also tell XA to upload the latest schedule by using the "+u"
     command line option.

           XA +U -P

     Use the command line option "-e" in conjunction with powerfail
     recovery to see how XA would have restored each module without
     sending any X10 commands:
     
          XA -E -P
     
     The FORCE and IGNORE token statements can override powerfail's
     determined module state. These overrides may be used for certain
     modules that do not have any programmed events stored in the CP-
     290.


    {FORCE module state}
       Forces a module to a desired state, no matter what powerfail
       recovery  thinks it should be in. "Module"  can be a module
       address (A1) or pre-defined name (STAIRS). "State" can be any
       of the following X10 commands:

           ON, OFF, DIM %%

       Example (from XA.INI):

          FORCE P_C ON

       You can "force" a module from the command line too, thus
       overriding the calculated state:

          XA "FORCE DEN OFF" -P



    {IGNORE module}
       Ignores sending any command to module during a powerfail
       recovery.  "Module" can be a module address or pre-defined
       name  Example:

          IGNORE HORULY_CHIME

       You can tell XA to ignore sending any recovery actions to a
       module from the command line too:

          XA "IGNORE BEDROOM_LAMP" -P


=====================================================================
11.  Screen Color Control
=====================================================================

    Screen color control lets you program how commands should be
    displayed.  You will be able to tell at a glance how certain
    conditional statements IF/ELSE, DATE/THRU/EXCEPT were evaluated
    by XA just by looking at the display.

    {VIDEO1 Foreground Background}
       IF or ELSE expression is TRUE (registered version).

    {VIDEO2 Foreground Background}
       IF or ELSE expression is FALSE (registered version), or
       DATE/THRU/EXCEPT evaluates to FALSE.
     
    {VIDEO3 Foreground Background}
       Statements resulting in DIRECT commands being sent to CP-290
     
    {VIDEO4 Foreground Background}
       Statements resulting in EVENTS being sent to CP-290.

    {VIDEO5 Foreground Background}
       Important messages reported by XA.

    {VIDEO6 Foreground Background}
       All other non event or command statements processed by XA.
  
    FOREGROUND may be any of the following:
          BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
          DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
          LIGHTMAGENTA, YELLOW, WHITE

    BACKGROUND may be any of the following:
          BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY

    To display a "TRUE" IF/ELSE statement in GREEN foreground
    characters on a BLACK background, and a "FALSE" IF/ELSE (or
    DATE/THRU/EXCEPT) statement in RED foreground characters on a
    BLACK background:

          VIDEO1 GREEN BLACK
          VIDEO2 RED BLACK

    To display a DIRECT command (XA "P1 ON") in YELLOW on BLACK:
          VIDEO3 YELLOW BLACK


=====================================================================
12. Programming Additions          ( * Registered Version Only * )
=====================================================================


  Variables
  -------------------------------------------------------------------
     Variables are user-defined objects which may be assigned values,
     or examined. You can assign numbers, dates, times, port data,
     true/false data into a variable.

     Variables are dynamically created at the first instance when XA
     parses a token that is not part of the normal XA language. For
     instance, the following statement declares a variable called
     VACATION, because VACATION is not part of XA's syntax.

           VACATION = WEEKEND

     Internally, variables are treated as 32 bit integer values. When
     variables are created they are initialized to 0 as soon as they
     are parsed. However, they may be assigned a different value in
     the declaring statement. In the above example, "VACATION" was
     assigned the value WEEKEND (the internal value is set to 96, or
     60 Hex - but you  don't really need to know that).

     The next example declares a variable called "ATHOME", assigning
     it a value of 1.

          DEFINE TRUE   1
          DEFINE FALSE  0
          ATHOME = TRUE

     First, we define constants TRUE and FALSE to be 1 and 0
     respectively.  Next, we declare a variable called ATHOME.
     Internally, the variable is created and initialized to 0. The
     statement is parsed further, the assignment operator "=" sets
     ATHOME equal to TRUE (or 1).
     
     When declaring variable, the first character in its name should
     begin with an ALPHA character, that is, A...Z. You can then use
     numbers as part of the name, but they must not start the name.
     All characters are  converted to UPPERCASE.  The list of legal
     characters are:
     
          ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_
     
     Examples:
          BIRTHDAY     <--- THIS IS OK!
          1_BIRTHDAY   <--- CAN'T START WITH A NUMERIC VALUE
          BIRTH,DAY    <--- COMMA NOT A VALID CHARACTER



  Hexadecimal Notation
  -------------------------------------------------------------------
     Hexadecimal notation specifies an integer value in base 16 or
     "hex" (hexadecimal).  When writing computer programs, it is
     sometimes easier  to work in this base than the normal base 10. A
     hex value has 3 parts:

        0  NNNNNNN  H

     where:
         0 - A leading zero is required if the first digit of the hex
              number is an alphabetic character (A...F) so that XA can
              distinguish it as a number and not a variable name. A leading
              zero may also be used in front of a numeric character in the hex
              number just as in a normal integer constant (0987H = 987H).

         NNNNNNN - The eight Ns represent the 8 hexadecimal digits in
              the range of 0...F.

         The trailing H indicates the number is hex and is always
              required.

     Example:
          IO 3E8H

     Previous versions of XA assumed hex numbers for certain tokens
     (such as IO). This is no longer the case!
  
   

  Pre-Defined Variables:
  -------------------------------------------------------------------
     XA maintains several built-in variables that are accessible by
     your programs. These variables are:


     CDATE
       The current date (month-day-year).
  
       Internally, XA maintains the current date as a 32 bit long
       integer. CDATE is actually the number of days since 1/1/1970.
       You can perform simple math and logical operations to this
       variable to test for special conditions. For instance, to run
       a special command file called XMAS.CMD between Thanksgiving
       and New Years Eve:

          IF ((CDATE >= DATE 11/25) AND (CDATE <= DATE 12/31))
            INCLUDE XMAS.CMD
          ENDIF

       When comparing dates with CDATE, make sure you specify the
       DATE token:
     
          IF (CDATE == 12/25)      <--- THIS IS WRONG!
          IF (CDATE == DATE 12/25) <--- THIS IS CORRECT!


     CDAY
       The current day of the week (MON, TUE, WED...)
  
       Internally, XA maintains the current day as an X10 bit-
       pattern, that is MON = 1, TUE = 2, WED = 4, ...SUN = 40Hex.
       The Day Tokens (MON, TUE... SUN) are also mapped to these
       values, so you can use them in conjunction with logical
       operations when determining special days. The file XMAS.CMD
       performs a test on CDAY to see if its FRI or SAT, thus
       allowing the Christmas lights to stay on longer:
       
          IF ((CDAY == FRI) OR (CDAY == SAT))
              IF (CTIME >= TIME 11:30 PM)
                  GOTO EXIT
              ENDIF
          ELSE
              IF (CTIME >= TIME 10:30 PM)
                  GOTO EXIT
              ENDIF
          ENDIF
          GOTO LOOP   # IT'S NOT TIME YET, REPEAT THE LOOP.


     CTIME
       The current time (in 24-hour format)
       
       Internally, XA maintains the current time as the number of
       seconds since midnight.  You can perform arithmetic and
       logical operations on this variable by using the TIME token.
       See the previous example for a way of leaving Christmas lights
       on until 11:30 pm on FRI and SAT nights, all other nights they
       are shutdown at 10:30 pm.

  Operators
  -------------------------------------------------------------------
     Operators allow some kind of operation to be performed to
     variables and constants. Operators are evaluated as they are
     parsed from left to right.  When an expression is contained in
     parentheses, that expression will be evaluated first. When nested
     parentheses are present, the inner most expression is evaluated,
     then the one immediately outside of it, and so on.

     Arithmetic Operators

              Operator  Function      Example
              ========  ==========   ==========
                 *      Multiply     A = B * C
                 /       Divide      B = A / C
                 +      Addition     C = A + B
                 -     Subtraction   A = C - B
                 -     Unary Minus   A = - B
                 %       Modulus     A = B % C

                 Table 3 - Arithmetic Operators

     Relational Operators

              Operator  Function
              ========  =============================
                  =     Assigns a value to a variable
                  <     Less than
                  >     Greater than
                  <=    Less than or equal to
                  >=    Greater than or equal to
                  <>    Not equal to
                  ==    Equal to (not assignment)

                 Table 4 - Relational Operators


     Logical Operators
     These Logical Operators produce either a FALSE (0) or TRUE (1) result.

              Operator  Function
              ========  =========================
                 AND    Logical AND
                  &&    Logical AND (same as AND)
                  OR    Logical OR
                  ||    Logical OR (same as OR)
                  !     NOT

                   Table 5 - Logical Operators

     Truth Table
              A  B  A AND B   A OR B  !A
              =  =  =======   ======  ==
              0  0     0         0     1
              0  1     0         1     1
              1  0     0         1     0
              1  1     1         1     0

             Table 6 - Logical Operator Truth Table

     Bitwise Logical Operators
     These operators are used to mask off some set of bits (AND), or
     to turn on some bits (OR). You will need these when using XA in
     conjunction with IO ports.

              Operator  Function
                  |     Bitwise OR
                  &     Bitwise AND

               Table 7 - Bitwise Logical Operators



=====================================================================
13.  IF/ELSE/ENDIF Statements          (* Registered Version Only *)
=====================================================================

    The IF/ELSE/ENDIF statement provides a transfer of control based
    on the result of a relational or comparison expression. The
    IF/ELSE/ENDIF statement has the following format:

         IF (EXPRESSION)
              STATEMENTS
         [ ELSE
              STATEMENTS ]
         ENDIF

    The expression within parentheses is evaluated. If the expression
    evaluates to TRUE, then the series of statements starting on the
    next line are executed. If the expression evaluates to FALSE, and
    there is an ELSE clause, then the series of statements on the
    lines following the ELSE will be executed.  The ELSE clause is
    optional. If there is no ELSE clause, then execution continues
    immediately following the ENDIF statement.

    Conditional IF/ELSE/ENDIF statements may be nested up to 100
    levels deep.
         IF (1 < 2)
            IF (2 < 3)
                IF (3 < 4)
                    A = 5
                 ENDIF
             ENDIF
         ENDIF

    Each conditional expression must finish with an ENDIF clause so
    the parser can evaluate further statements.
    Indentation is used throughout these examples and you are urged
    to indent your programs too. Proper indentation makes your
    program much easier to read.
    
    Complex conditional statements may be evaluated. The above
    example could be rewritten as:

        IF ((1 < 2) AND (2 < 3) AND (3 < 4))
            A = 5
        ENDIF

    Use parentheses () to group individual expressions. Grouping
    ensures that expressions are evaluated correctly, as well as
    makes your program more readable.

    The following example (found in XA.CMD) uses an IF statement to
    determine whether additional indoor/outdoor lighting is needed
    based on seasonal changes.  Let's say you leave for work around
    5:30 am.  During the winter, it's probably still dark, yet in the
    summer, dawn is already breaking.  This example determines if
    lights are needed by comparing the average weekly sunrise with a
    pre-determined time. If sunrise occurs after 6:00 am, then it's
    still dark at 5:30 am so we'll program the lights to turn on,
    then turn off at sunrise. Otherwise, there's enough daylight
    present and the additional lights are not needed.

         IF (SUNRISE > TIME 6:00)
              OUTSIDE_PORCH_LIGHTS ON TIME 5:30 WEEKDAYS RANDOM 10
              OUTSIDE_PORCH_LIGHTS OFF SUNRISE WEEKDAYS
              LIVING_ROOM_LAMP ON TIME 5:35 WEEKDAYS RANDOM 10
              LIVING_ROOM_LAMP OFF SUNRISE WEEKDAYS OFFSET 10
         ENDIF


=====================================================================
14.  XA.INI - Initialization file
=====================================================================

    XA supports the use of an initialization file called XA.INI.
    This file is intended to hold tokens and communication parameters
    that you use regularly.  For instance, the following tokens are
    ideal candidates for inclusion in the initialization file:
    
         COMx           - Communication port
         IO x           - Special IO port address
         IRQ x          - Special IRQ level
         DEFINE x y     - Place as many DEFINE statements as you want
         LATITUDE dms   - The latitude of your city
         LONGITUDE dms  - The longitude of your city
         TIMEZONE x     - Your timezone
         DST            - If Daylight Savings is observed
         XACMD file     - The command file to use as a default

    This file, always called XA.INI, is the very first file that the
    XA parser looks for.  If it is found in the current directory (or
    the directory specified by the XA environment variable ( see:
    Installation) then the file is scanned for all tokens
    described above.

    These tokens are then used to define modules or override default
    communication parameters.  The following example is taken from
    the file XA.INI distributed with this software:

         DEFINE P_C C1
         DEFINE DEN A5
         DEFINE GARAGE A1
           :
         LATITUDE 4135'
         LONGITUDE 8120'
         TIMEZONE 5 DST
           :
         COM3
         IRQ 5

    Since XA.INI is always parsed, this allows you to send
    descriptive X10 commands that don't rely on your memory for the
    actual house and unit codes.  For instance:
    
         XA "DEN ON"
    
    turns ON the unit at Housecode A Unit 5.
    
    Do not place events or direct commands in this file because they
    will not be executed.  XA is only looking for tokens that
    describe your particular setup.  Events and direct commands
    should be placed in command files.

    You may place comments in your initialization file.  A comment is
    delineated by the pound sign character "#".  The comment symbol
    may appear in any column. Once XA sees the comment, the rest of
    the line is ignored. Therefore, comments can be placed in front
    of tokens you do not want to be parsed by the interpreter at this
    time.

         # THIS IS AN EXAMPLE COMMENT. PLACE THEM AFTER STATEMENTS TOO:
         LATITUDE  4135'          # LATITUDE OF MENTOR, OH.

    When creating this file, use an editor or word processor that
    stores its files in pure ascii format.  Otherwise the formatting
    characters that the word processor embeds within the file will
    confuse the XA parser.  Either the DOS "EDIT" or the Windows
    "NOTEPAD" are excellent utilities for modifying these files.
    The token XACMD specifies the default command file
    that should be executed if no direct command was included at the
    DOS prompt. The next section describes what command files are and
    how they are used with XA.


=====================================================================
15. Command Files
=====================================================================

    Since the CP-290 is only capable of storing a single weeks worth
    of events, command files were created to allow easy updates of
    the events that may need to be revised due to ever-changing
    conditions such as sunrise and sunset times.  Specific date
    information may also be contained within this file.  XA has the
    capability to interpret these dates and update the CP-290
    accordingly. See the sample command  file "XA.CMD" (included in
    this package) I use for automating events  in my home.
    Command files work very well for executing a series of direct
    commands too. See the sample file XMAS.CMD for an example of an
    X10 lighting script.
    
    Command files should only be created with an editor or word
    processor  that saves files in pure ASCII format.  Any extraneous
    characters or control codes will cause the XA interpreter to
    ignore your commands. Either the DOS "EDIT" or the Windows
    "NOTEPAD" are excellent utilities for modifying these files.
    XA defaults to reading a command file if there are no commands in
    the command line and as long as the statement "XACMD filename"
    was included in your XA.INI file. You may override
    the default command file by using the "f=filename" option when
    starting XA.  For example, if you wanted to execute the commands
    found in a file called 'MONITOR.CMD', you would start the XA
    utility as:

         XA F=MONITOR.CMD

    You can pass parameters to your *.CMD files. These parameters can
    then be evaluated using IF/ELSE statements.
    
    Prior to Version 2.0, XA would only execute either command files
    or commands passed as arguments to XA on the DOS command line -
    NOT  BOTH.  With version 2.x, you can execute both types at the
    same time, however the file must be specified using the
    "f=filename" syntax.  This is very useful when you want to pass a
    variable to a command file (Registered version only). For
    example, suppose your normal command file (XA.CMD) contains
    special lighting events that you activate when you plan on
    vacationing for the weekend:

         XA.CMD:
           # NORMAL EVENTS...
           GARAGE ON SUNSET WEEKDAYS
             ...
           # SPECIAL VACATION EVENTS...
           IF (VACATION)
             HALLWAY ON TIME 9:30 PM WEEKENDS SECURITY
             HALLWAY OFF TIME 11:30 WEEKENDS RANDOM 10
             STEREO ON TIME 3:30 PM WEEKENDS RANDOM 15
             STEREO OFF TIME 11:15 PM WEEKENDS RANDOM 5
           ENDIF

    See "Appendix B. Passing arguments to your command file." 
    for more information.

    To activate the vacation sequence, you must specify both XA.CMD
    and set the vacation variable to TRUE:

         XA F=XA.CMD "VACATION = 1"


=====================================================================
16. Initialization file, Command files, and Command Line Options
=====================================================================

    This section tries to clear any confusion you may have about the
    initialization file, command files, and command line options.
    Each serves a unique purpose, offering a very easy and flexible
    means of controlling your X10 equipment.  As discussed earlier,
    XA provides the mechanism for controlling the CP-290 via the DOS
    prompt, batch files, or from a text-based file.  XA distinguishes
    which mode of operation it takes by examining the way you invoked
    XA.  If any direct (or immediate) commands are present, then XA
    sends the command directly to the CP-290.  For instance, the
    following is a direct command:
    
         XA "A5 ON"
    
    It's nicer to assign a meaningful name to your modules, so XA
    allows you to place these names in an initialization file called
    "XA.INI".  You define a module using the following token syntax:
    
         DEFINE DEN HOUSE A UNIT 5
    
    Now you can activate the same module using a descriptive (and
    easier to remember) name:
    
         XA "DEN ON"
    
    Other items may also appear in the intialization file.  If your
    computer communicates with the CP-290 via COM3 serial port, then
    you may place the token "COM3" within the XA.INI too.  XA always
    looks at this file before attempting any communication with the
    CP-290.  Other tokens that XA looks for are:
    
         IRQ, IO, LATITUDE, LONGITUDE, TIMEZONE, DST, XACMD, DEFINE, COMX
    
    After parsing the XA.INI file, XA then looks to see if the
    "f=filename" option was specified on the command line. This
    allows you to override the default command file you may have
    specified by using the XACMD token in the XA.INI file.
    Next, the command line options are scanned. Any options defined
    here will override all previous options declared in the
    initialization file.  If a file and a series of commands are
    placed in the XA command line, then XA will execute the command
    and the file.  This allows you to set variables to a specific
    value and be evaluated so special actions can be taken inside
    your command file. See the previous section for more details.


=====================================================================
17. Report Files
=====================================================================

    XA can produce a report of all events that were just parsed by
    the interpreter.  These reports come in 2 styles:

       Events sorted by day and time
       Events sorted by day, module, and time.

    You have the option of selecting any style, or both styles.  The
    report file will be created after the events have been downloaded
    to the CP-290.  The file is named "XA.RPT", and is located in the
    same drive and directory that your "XA" environment variable is
    set to.  Refer to "Installation" for setting XA environment
    variables.
    
    Each report file will contain a header containing the XA
    copyright notice, revision number, and the date and time the file
    was created.   Next, the event list will be generated starting
    with today's events.  Each day will have its own heading, and if
    the LATITUDE, LONGITUDE, and TIMEZONE tokens were included in
    either of the initialization or command files, then the sunrise
    and sunset times for this day will be added to the report.
    The format of the report is self-explanatory, but a few items are
    worth noting. The "Description" column retrieves the module
    definition via the "DEFINE" statement. The DEFINE must include
    both the HOUSE and UNIT tokens when describing a module.  You
    should not use the short cut method, such as:
    
         DEFINE PORCH_LIGHTS A 1            <=== WILL NOT WORK.
         DEFINE PORCH_LIGHTS HOUSE A UNIT 1 <=== WILL WORK.
    
    The "Event" column displays the actual location of the event in
    the CP-290's memory.  Event locations range anywhere from 0 to
    127.  Use this information if you want to CLEAR an event from the
    CP-290 interface (see EVENT, and CLEAR EVENT).
    
    An asterisk (*) following the event number is a flag to warn you
    that the event is triggered on multiple days.  Therefore, if you
    do CLEAR this event, the event will be deleted for the other days
    as well.


    Report Style 1 - Sort by Day and Time
    ------------------------------------------------------

    Use the REPORT1 token in the command file (or use +r1 on the
    command line) to produce a report file which sorts every event by
    the day it  takes place and the time it occurs.  The following is
    a condensed sample of this style:
    

      XA - X10 Command Interpreter - Version 2.3
      Copyright 1991-1994 by Bruce Christensen. All Rights Reserved.
      Registered to: Your name here - Your town here.

      Event report prepared: 08/03/94 2:53 PM

      Saturday - August 3, 1994  Sunrise:  7:15:27   Sunset: 7:18:53

      Time      Cmd  Mode   Module Address/Description      Event
      ========= ==== ====== ==============================  ======
      1:30 am   OFF         (A3) BEDROOM_LIGHT              ( 75)
      5:00 am   ON          (B2) DEHUMIDIFIER               ( 77)*
      6:45 am   OFF         (A6) STAIRS                     ( 84)*
      6:45 am   OFF         (H1) HALLWAY                    ( 81)*
      9:00 am   OFF         (B2) DEHUMIDIFIER               ( 78)*
      12:30 pm  OFF         (A8) LIVING_ROOM_LAMP           ( 56)
      12:30 pm  OFF         (A4) FAMILY_ROOM_LAMP           ( 61)
      5:00 pm   ON          (B2) DEHUMIDIFIER               ( 79)*
      6:18 pm   ON          (A4) FAMILY_ROOM_LAMP           ( 72)
      7:18 pm   DIM         (A9) OUTSIDE_PORCH_LIGHT        ( 66)
      7:23 pm   ON          (A1) DECK_LIGHTS_1              ( 69)
      7:48 pm   DIM         (A6) STAIRS                     ( 82)*
      7:48 pm   DIM         (A1) DECK_LIGHTS_1              ( 70)
      7:48 pm   ON          (A8) LIVING_ROOM_LAMP           ( 67)
      8:48 pm   OFF         (A1) DECK_LIGHTS_1              ( 71)
      9:00 pm   OFF         (B2) DEHUMIDIFIER               ( 80)*
      9:45 pm   DIM         (H1) HALLWAY                    ( 86)*
      10:34 pm  ON          (A3) BEDROOM_LIGHT              ( 74)
      10:43 pm  OFF         (A9) OUTSIDE_PORCH_LIGHT        ( 76)
      11:00 pm  DIM         (A6) STAIRS                     ( 83)*





    Report Style 2 - Sort by Day, Module, and Time
    ------------------------------------------------------

    Use the REPORT2 token in the command file (or use +r2 on the
    command line) to produce a report file which sorts every event by
    the day it takes place, the module, and the time it occurs. The
    following is a condensed sample of this style.


      XA - X10 Command Interpreter - Version 2.3
      Copyright 1991-1994 by Bruce Christensen. All Rights Reserved.
      Registered to: Your name here - Your town here.

      Event report prepared: 08/03/94 2:53 PM)

      Saturday - August 3, 1994  Sunrise:  7:15:27   Sunset: 7:18:53

      Module      Time      Function    Mode      Event
      =========== ========  =========== ========  =====
      (A1) DECK_LIGHTS_1
                  7:23 pm       ON                ( 69)
                  7:48 pm       DIM               ( 70)
                  8:48 pm       OFF               ( 71)

      (A3) BEDROOM_LIGHT
                  1:30 am       OFF               ( 75)
                  10:30 pm      ON                ( 74)

      (A4) FAMILY_ROOM_LAMP
                  12:30 pm      OFF               ( 61)
                  6:18 pm       ON                ( 72)

      (A6) STAIRS
                  6:48 am       OFF               ( 84)*
                  7:43 pm       DIM               ( 82)*
                  11:00 pm      DIM               ( 83)*

      (A8) LIVING_ROOM_LAMP
                  12:30 pm      OFF               ( 56)
                  7:48 pm       ON                ( 67)

      (A9) OUTSIDE_PORCH_LIGHTS
                  7:18 pm       DIM               ( 66)
                  10:31 pm      OFF               ( 76)

      (B2) DEHUMIDIFIER
                  5:00 am       ON                ( 77)*
                  9:00 am       OFF               ( 78)*
                  5:00 pm       ON                ( 79)*
                  9:00 pm       OFF               ( 80)*

      (H1) HALLWAY
                  6:48 am       OFF               ( 81)*
                  9:45 pm       DIM               ( 86)*


=====================================================================
18. Monitoring and Logging events
=====================================================================

    The CP-290 sends a message to your computer after it processes a
    direct command (via XA.EXE or X10.EXE), or after one of its eight
    keys has been pressed, or when it executes an event stored in its
    memory.  Most software packages (including X10.EXE shipped with
    the CP-290) will ignore these messages.  XA allows you to monitor
    and log these transmissions if desired. XA will enter its monitor
    mode after all other commands have been processed.

    You can activate the monitor feature in two ways: as a  command,
    or as a command line parameter.
    Command example:
    
         XA "MONITOR"
    
    Command line parameter example:
    
         XA +M
    
    In the first example, "MONITOR" is the only command that XA
    processes. XA ignores the default command file if it has been
    specified with XACMD.  In the second example, XA would process
    the default command file (if specified) and then initiate the
    monitor sequence.
    
    When XA begins to monitor, it displays the following message:
    
         MONITOR EVENTS.  PRESS <ESC> WHEN FINISHED...
    
    XA then waits for messages from the CP-290.  You may exit this
    function by pressing the <ESC> key.  When the CP-290 executes an
    event, it sends a message to the PC with the following
    information; the HOUSE code, UNIT code, and the event FUNCTION
    (ON, OFF, DIM).  XA takes this information and adds the time and
    date information from your PC's clock and prints the following
    message to the monitor:
    
         SUN MAR 24 07:00:13 1991 HOUSE A UNIT 5 ON
    
    This message is semi-useful; it describes what just occurred but
    if you forgot what was addressed as HOUSE A UNIT 5 then the
    message is meaningless.  You can give this module a more
    descriptive name by using a command file that includes DEFINE
    statements for all your modules.  Below is sample command file
    (MONITOR.CMD - supplied with  this package) that describes what
    we're talking about:
    
         DEFINE PORCH/GARAGE_LIGHTS HOUSE A UNIT 1
         DEFINE PLANT_GROW_LIGHTS HOUSE A UNIT 5
         DEFINE FAMILY_ROOM_TV HOUSE A UNIT 6
         DEFINE BASEMENT_COMPUTER HOUSE A UNIT 7
    
    Now when a message is sent by the CP-290, a scan of all the
    definitions will be made to see if the HOUSE and UNIT codes
    match.  If found, then that description will be used instead of
    the codes.  Therefore, you would get the following message on
    your screen:
    
         SUN MAR 24 07:00:13 1991 (A6) PLANT_GROW_LIGHTS ON
         SUN MAR 24 08:43:13 1991 (A1) PORCH/GARAGE_LIGHTS ON
    
    In the above messages, a combined House and Unit code (A6) is
    automatically provided, you don't have to include it as part of
    the DEFINE token.  Also, the DEFINE must include both the HOUSE
    and UNIT tokens when describing an object.  You can not use the
    short cut method, such as:
    
         DEFINE PORCH_LIGHTS A 1            <=== WILL NOT WORK.
         DEFINE PORCH_LIGHTS HOUSE A UNIT 1 <=== WILL WORK.
    
    You can also log these events to a file called XA.LOG by
    specifying either the LOG token in a command file or the [+l]
    option on the command line.  Each event reported by the CP-290
    will be displayed on the screen, and also be appended to the file
    XA.LOG.  By appending the information, all previous events will
    be saved.  XA.LOG is located in the same drive and directory that
    your "XA" environment variable is set to.  See Installation 
    for more information about the XA environment variable.
    

=====================================================================
19. POWERUP Utility
=====================================================================

    The POWERUP utility is provided in this package to help you
    perform unattended, automatic, event downloads to the CP-290 if
    your computer is controlled by an Appliance module.  POWERUP
    should be placed in your AUTOEXEC.BAT file so it will always be
    executed after your computer boots.  This way, it can decide
    whether or not it's time to perform any updates to your
    interface, and it prevents you from needlessly sending commands
    when you don't need to.
    
    The POWERUP command has the following form:
    
        POWERUP d=day [[d=day]...] [w=1,2,3,4,5] s=hh:mm e=hh:mm
    
    The command line parameters may appear in any order, and they
    must all be present (except for "w=" which is optional):
    
    d=day
      This is the text string for the day you want to check for.
      Legal strings are:
         MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY,
         SUNDAY, WEEKDAYS, WEEKDAY, WEEKENDS, WEEKEND, EVERYDAY.
    
    [w=week]
      This optional argument allows you to optionally specify the
      week of the month you want POWERUP to check for. For instance,
      to have POWERUP check for the 3rd SUNDAY of the month,
      specify:
    
           POWERUP D=SUNDAY W=3 S=2:55 E=3:05
    
      You may not specify multiple weeks, however the default
      condition (not specifying the w= command) will still check
      every week.
    
    s=hh:mm
      This is the "window" start time.  Hours must be entered in 24
      hour format only.  e=hh:mm  This is the "window" end time.  (24
      hr format). For example:
    
          POWERUP D=SUNDAY S=2:55 E=3:05
    
    If the "day" specified matches the day reported by DOS, and the
    time reported by DOS falls within the specified "window", then
    POWERUP will return an ERRORLEVEL of 1, otherwise a 0 is
    returned. Therefore, by placing the proper batch file commands in
    AUTOEXEC.BAT, you can now execute a variety of functions at
    certain times.
    
    You may enter multiple 'd=day' parameters.  For instance, to have
    Powerup check for a window beginning at NOON and lasting until
    1:00 pm every MONDAY, WEDNESDAY, and FRIDAY, you would enter:
    
         POWERUP D=MONDAY D=WEDNESDAY D=FRIDAY S=12:00 E=13:00
         IF NOT ERRORLEVEL 1 GOTO :NOT_DAY
    
    If your computer is controlled by an Appliance module, you can
    now automatically download revised event times.  The following
    example also appears in the sample AUTOEXC.BAT file supplied with
    XA:

         POWERUP D=SUN S=2:55 E=3:05
         IF NOT ERRORLEVEL 1 GOTO SKIP
         XA F=XA.CMD +R1
         REM - DEFRAGMENT UTILS, BACKUPS ALSO APPEAR HERE.
         XA "P_C OFF"
         :SKIP


=====================================================================
20.  FINDX10.EXE
=====================================================================

    A new utility has been added to help determine the configuration
    of the serial port the CP-290 is connected to. After searching
    all ports in your system, FINDX10 determines the IRQ of the port
    and attempts to communicate with the CP-290. If it finds the CP-
    290, it displays the port setup and prompts you if it is OK to
    save the data in your XA.INI file.  If you select 'Y', the IO
    address and the IRQ level tokens are placed at the end of your
    XA.INI file.
    
    FindX10 may not work properly if run from a Windows DOS shell.
    You must exit Windows and return to DOS.  Also, because of the
    wide variety of hardware in use, FINDX10 may not be able to
    locate the CP-290.
    
    
=====================================================================
21.  Other Programs and X10 Information
=====================================================================


  XT - Memory Resident Software for the CP-290
  --------------------------------------------------------

    XA is just one of a series of programs that have been developed
    for the X10 CP-290.  If you received XA on a floppy disk, then
    you should have also received a program called XT, a terminate-
    stay-resident program (or TSR) that sits silently in the
    background waiting for you to activate it with the proper
    keystroke.  This means you can instantly call it from any text-
    based application.  When activated, it displays a list of all
    modules that you can control with the CP-290.  Each line on the
    list contains a description of the module, its address, and its
    current status.  You select the module you want to control, and
    then choose the action (ON, OFF, DIM).

    Since XT is resident, it continuously monitors the serial port
    for any communication transmitted by the CP-290 (such as when an
    event is issued or when one of the buttons on the unit is
    pressed).  The status of each module will always be properly
    reflected in the pop-up menu.
    
    XT (version 2.0) now comes with utility package called XTS.EXE.
    XTS has direct access to XT's database of 256 module states.
    Every command issued by the CP-290 is captured and stored by XT.
    XTS can return these module states (via errorlevel statements),
    allowing you to write batch files that react to a module's X10
    status.
    
    XA (2.x) communicates with XT too.  Whenever XA executes a direct
    command, (or monitors X10 activity), it sends the information
    along to XT so the new state is reflected in the XT's database.
    
    Another feature of XT is its ability to perform a limited "power-
    fail recovery".
    


  FX - TW-523 Command Interpreter
  --------------------------------------------------------
    FX.EXE is a DOS-based X10 command interpreter for the TW-523.
    Valid X10 commands are ON, OFF, DIM and BRIGHT.  These commands
    can be input from the DOS command line, or they may be read from
    a "script" file.
    
    A special feature of FX is its ability to send SIMULTANEOUS
    Bright and Dim commands to multiple X10 modules.  This allows you
    to create some very interesting lighting effects.  My primary use
    for this program is for Halloween and Christmas lighting.
    
    FX communicates with the TW-523 via your computer's parallel port
    (LPT1...LPT3).  Complete instructions for building the necessary
    connectors are included in the documentation.
    
    FX can be found on many BBS's, including those listed in Future
    Updates.  Look for X10FX100.ZIP (the version number - 1.00) 
    is the last 3 digits of the ZIP filename.



  Other Information
  --------------------------------------------------------
    If you would like further information about the X10 system, then
    contact Steve Mueller of the Silicon Valley Video Group.  Steve
    has put together a paper (currently over 80 pages) which covers
    such  topics as:

         X10 transmission theory, undocumented functions of the CP-
         290, debugging spurious failures, modifying X10 devices
         (local dimming), descriptions of the PL-513 and TW-523
         modules,  CP-290 Users and Programming Guides, and
         manufacturers/retailers of X10 compatible equipment.

    There is a charge for Steves paper. You may contact Steve via:
         Steve Mueller
         Silicon Valley Video Group
         335 Bodega Way
         San Jose, CA. 95119-1603
         Prodigy - SJCR28A
         Internet - shm@vnet.ibm.com


=====================================================================
22.  Acknowledgements
=====================================================================

    I would like to thank the many people for their help in making XA
    a better program. First of all, thanks go to my wife and children
    for letting me spend the time to pursue this hobby. Next, my
    thanks go out to all the beta testers, and proofreaders for their
    valuable input.  Finally, my thanks go out to all the folks who
    have taken the time to register this program and offer
    suggestions.


=====================================================================
23. Warranty, Copyright, and Registration Policy
=====================================================================


  Limited Warranty
  --------------------------------------------------------
    THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
    THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM
    IS ASSUMED BY YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND
    NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY
    SERVICING, REPAIR OR CORRECTION.  FURTHER, THE AUTHOR DOES NOT
    WARRANT, GUARANTEE, OR MAKE REPRESENTATIONS REGARDING THE USE OF,
    OR THE RESULTS OF THE USE OF THIS PROGRAM IN TERMS OF
    CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS, OR OTHERWISE;
    AND YOU RELY ON THE PROGRAM AND IT'S RESULTS SOLELY AT YOUR OWN
    RISK.  THE AUTHOR CANNOT ACCEPT RESPONSIBILITY FOR SYSTEM DAMAGE,
    LOSS OF PROFIT, OR ANY OTHER SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGE RESULTING FROM THE USE OR INABILITY TO USE
    THIS PRODUCT.

    The author DOES warrant to the original licensee of a REGISTERED
    product that the program disk(s) on which the program is recorded
    be free from defects in materials and workmanship under normal
    use and service for a period of ninety (90) days from the date of
    delivery. The author's entire liability and your exclusive remedy
    shall be replacement of the disk not meeting this Limited
    Warranty.


  Copyright
  --------------------------------------------------------
    The XA software package, including its utilities and this
    document, is Copyright c 1991-1994 by Bruce Christensen. All
    rights reserved.

    Any specific hardware/software names used in this document are
    trademarks of specific manufacturers.

    Regardless of the method of marketing, XA is not in the public
    domain. It is copyrighted by Bruce Christensen. All rights are
    reserved. Copying, duplicating, selling or otherwise distributing
    the registered version of this product is a violation of the Law.
    However, we grant you the right, in fact encourage you to make
    and distribute as many copies of the SHAREWARE version of XA as
    you wish, using any acceptable medium of exchange, with the
    following provisions:

       Please feel free to distribute this SHAREWARE version as often
         as you like, to any interested parties.
       Please do not distribute this program without all of its
         original related files, addendum files, documentation and this
         notice.
       Please do not alter the program or documentation in any
         manner.
       DISTRIBUTION of the REGISTERED USER version of the program is
         in violation of license agreements and copyright Law!


  Registration
  --------------------------------------------------------
    If you are still using XA beyond the initial 45-day trial period,
    you must register this software with the author. Please use the
    included registration form (REGISTER.TXT) and send a $29
    registration fee to the address below.  Your registration will
    entitle you to the latest full-featured registered version of
    this program, and a printed copy of this user manual.
    The registered version of XA and its utilities are licensed for
    individual personal use for an unlimited time.

    This is a "living" program - new features are added from time to
    time.  Your input is the basis for future improvements.  Send any
    comments to the address given below, or you may contact me on
    CompuServe, Prodigy,  America On-line, or Internet.

         BRUCE CHRISTENSEN
         6594 HUDSON AVENUE
         MENTOR, OH.  44060-4545

         COMPUSERVE: 73201,1531
         PRODIGY ID:  MHNC39A
         AMERICA ON-LINE: AUGGIEBEN
         INTERNET: AUGGIEBEN@AOL.COM

  Future Updates
  --------------------------------------------------------
    Future updates of the shareware version XA can be found on
    CompuServe, America On-Line, as well as the following BBS's as
    they become available. The current version of XA will be named
    "X10XA203.ZIP". The last 3 digits of the filename will indicate
    the revision level (in this case, 2.03).

    MicroSellar BBS offers limited, free access to validated callers.
    Their number is: (201)-239-1151 v.32bis, or (201)-239-1331 HST
    16.8/v.32 terbo.

    Dave Mabry, a sysop of the "Going Down BBS" has offered free
    access to his BBS to anyone interested in X10 - Home Automation.
    Users can gain immediate access to the home automation files by
    logging on with a userid and password of "X10". This BBS can be
    reached at:  1-(810)-576-7882.

    Baran-Harper, a Canadian home automation mail order outfit, also
    runs a very popular BBS. There are many programs for the CP-290
    for PC's, Mac's, and other computers. The Baran Harper BBS is a
    free BBS, their number is: 1-(905)-471-6776, or 1-(905)-471-9574.

    Circuit Cellar Inc. publishes "The Computer Applications
    Journal", and runs occasional articles on X10.  Their BBS number
    is 1-(203)-871-1988.

    Home Automation Laboratories (HAL) has the best mail-order
    catalog for home automation equipment. Call 1-(800)-YEL-4HAL to
    request a catalog.  HAL's BBS # is 1-(404)-319-6227.
    


=====================================================================
24. Appendix A. Tokens - Quick Reference
=====================================================================


  Action tokens
  --------------------------------------------------------
      ON - turns ON the specified modules.
      OFF - turns OFF the specified modules.
      {DIM %%} - DIM to a % (percentage) level of brightness.
      {ALL_UNITS_OFF HOUSE x} - turns OFF all modules on selected
         HOUSEcode.
      {ALL_LIGHTS_ON HOUSE x} - turns ON all lamp/wallswitch modules
         on selected HOUSEcode.


  Module address tokens
  --------------------------------------------------------
      A1...P16
      HOUSE A...P
      UNIT 1...16
      UNIT ALL


  Coordinate tokens
  --------------------------------------------------------
      {LATITUDE dms} - your LATITUDE in Degrees and Minutes
      {LONGITUDE dms} - your LONGITUDE in Degrees and Minutes
      {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings)
      DST - Automatic Daylight Savings adjustments
    

  Clock tokens
  --------------------------------------------------------
      {SYNCHRONIZE PC (EXACT)} - set PC time based on X10 time
      {SYNCHRONIZE X10 (EXACT)} - set X10 time based on PC time
    

  Day tokens
  --------------------------------------------------------
      SUNDAY, SUN - Specific day for event to occur
      MONDAY, MON -      "
      TUESDAY, TUE -     "
      WEDNESDAY, WED -   "
      THURSDAY, THU -    "
      FRIDAY, FRI -      "
      SATURDAY, SAT -    "
      EVERYDAY - Event occurs everyday
      TODAY - Event occurs once today only
      TOMORROW - Event occurs once tomorrow only
      WEEKDAY, WEEKDAYS - Event occurs only on weekdays
      WEEKEND, WEEKENDS - Event occurs only on weekends
      EVERY `n' DAYS [FROM[DATE]mm/dd/yy - Repeats event every
         number of days
      EVERY `n' WEEKS [FROM[DATE]mm/dd/yy - Repeats event every
         number of weeks
  
  

  Time tokens
  --------------------------------------------------------
      {TIME hh:mm (AM)(PM)} - Schedule event time
      SUNRISE - Calculate time of sunrise
      SUNSET - Calculate time of sunset
      {OFFSET +/-hh:mm} - Event occurs +/- 23h59m of prog time
      NORMAL - Event occurs at specified time
      SECURITY - Event occurs within the hour
      {RANDOM +/-hh:mm} - Event occurs within a random offset +/-
         23h59m.
      {NOW hh:mm} - Event occurs with respect to current time.
    

  Specific Date tokens
  --------------------------------------------------------
      {DATE mm/dd/yyyy} - Event occurs on specified date
      {DATE mm/dd/yyyy THRU [DATE] mm/dd/yyyy (SUNDAY...SATURDAY)} -
         Event occurs between two dates
      {EXCEPT mm/dd/yyyy} - Event does NOT occur on specified date
      {EXCEPT mm/dd/yyyy THRU [DATE] mm/dd/yyyy (SUNDAY...SATURDAY)}
         - Event does NOT occur between two dates
      {DATE mm/dd/yy THRU [DATE] mm/dd/yy EXCEPT mm/dd/yy THRU
         [DATE] mm/dd/yy} - Special exceptions within a given range.
      

  Communication tokens
  --------------------------------------------------------
      {COMx} - send commands via COM1...COM4
      {IRQ x} - customize IRQ level for port.
      {IO x}  - customize port address (in hex).
    

  Miscellaneous tokens
  --------------------------------------------------------
      {BASECODE x} - Change BASECODE to A...P
      {HOUSECODE x} - Change BASECODE to A...P
      {DEFINE x z}      - Substitute string 'x' for 'z'  {XACMD
         file.cmd} - Specify default command file.
      {INCLUDE filenme} - Specify another file to parse.
      {CLEAR EVENT xxx} - Clear event xxx from CP-290 memory
      ERASE - Erase ALL events from CP-290 memory
      {EVENT xxx} - Place event xxx in a known location of CP-290
         memory
      BEEP - Causes PC speaker to beep.
      {DOS command} - Shell to DOS
      {DISPLAY ON/OFF} - Turn XA output display on or off.
      DIAGNOSE - CP-290 performs internal diagnostics.


  Reporting tokens
  --------------------------------------------------------
      LOG - Append event info to file XA.LOG
      MONITOR - Watch events as the CP-290 executes them.
      REPORT1 - Produce report file based on daily events.
      REPORT2 - Produce report file based on a module by module
         basis.
    

  Direct Command Control Tokens
  --------------------------------------------------------
      :LABEL - Identify an area to "goto/gosub" later.
      {GOTO label } - Jump to location identified by "label".
      {GOSUB label} - Execute subroutine identified by "label". Upon
         returning, continue with the rest of the cmd file.
      RETURN - from subroutine (used with GOSUB).
      STOP - Force XA to stop execution
      :EXIT - Special shutdown location jumped to when <ESC>
         pressed.
      {DELAY hh:mm:ss} - Wait for time to pass before executing the
         next cmd.
      PAUSE - Halt execution of direct commands until key pressed,
         then reset internal timer and resume direct commands.
      {TIMER hh:mm:ss.s} - Wait until "seconds" have elapsed
         (relative to the internal timer).
      RESET - Reset internal timer.
      FAST - ignore ack message from CP-290, speeds up single cmds.
    

  Conditional Expressions
  --------------------------------------------------------
      IF (expression)    When expression evaluates TRUE...
        statements       ...execute the following statements
      [ELSE              Otherwise...
        statements]      ...optionally execute the following statements
      ENDIF              Must always terminate conditional statements.


  Arithmetic Operators
  --------------------------------------------------------
      * Multiply      A = B * C
      / Divide        B = A / C
      + Addition      C = A + B
      - Subtraction   A = C - B
      - Unary minus   A = -B
      % Modulus       A = B % C


  Relational Operators
  --------------------------------------------------------
      = Assign
      < Less than
      > Greater than
     <= Less than or equal to
     <> Not equal to
     >= Greater than or equal to
     == Equals (not to be confused with '=' assignment operator)


  Logical Operators
  --------------------------------------------------------
      AND Logical AND
      &&  Logical AND
      OR  Logical OR
      ||  Logical OR
      !   NOT


  Bitwise Logical Operators
  --------------------------------------------------------
      &   Bit "AND"
      |   Bit "OR"


  Screen Color Control
  --------------------------------------------------------
      {VIDEO1 Foreground Background} - IF/ELSE evaluates to TRUE
      {VIDEO2 Foreground Background} - IF/ELSE, or DATE/THRU/EXCEPT
         evaluates FALSE
      {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-
         290
      {VIDEO4 Foreground Background} - Sending EVENTS to CP-290
      {VIDEO5 Foreground Background} - Important XA messages
      {VIDEO6 Foreground Background} - Statements that are non-event
         or non-commands.

      where FOREGROUND may be any of the following:
         BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
         DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
         LIGHTMAGENTA, YELLOW, WHITE

      and BACKGROUND may be any of the following:
         BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
    
  I/O Port Control
  --------------------------------------------------------
      {(variable =) INPORT io_port} - read status of port
      {OUTPORT io_port value} - output value to port

  Pre-defined Variables
  --------------------------------------------------------
      CDAY - The current day
      CTIME - The current time
      CDATE - The current date
    
  Powerfail Recovery module status overrides
  --------------------------------------------------------
      {IGNORE HOUSE UNIT} - Leave module in its present state
      {FORCE HOUSE-UNIT state} - Force module to ON, OFF, DIM state


=====================================================================
25. Appendix B. Passing arguments to your command file.
=====================================================================

    By default, XA will only accept input from either the DOS command
    line (ie, commands enclosed in "parentheses"), or via a file.
    
         XA "P1 OFF"   <=== DOS COMMAND LINE ARGUMENTS.
         XA F=XA.CMD <=== XA COMMAND FILE.
    
    You may now override this feature and have XA interpret commands
    from the DOS command line as well as a file by using the
    following format:
    
         XA "COMMAND" F=FILE.CMD  -OR-
         XA F=FILE.CMD "COMMAND"  (THE ORDER IS NOT IMPORTANT).
         XA "P1 OFF" F=XA.CMD
    
    This form of operation is very useful if you wish to pass special
    arguments into your command file and allow XA to activate special
    sequences. Your normal command file (XA.CMD) could contain some
    special commands that are only activated when you define a
    variable to be a certain value. The following sample code is
    executed when the variable "Babysitter" is set TRUE:
    
         IF (BABYSITTER)
              FOYER_LIGHTS ON DUSK TODAY
              HALLWAY ON SUNSET TODAY
              DECK_LIGHTS ON SUNSET TODAY
         ENDIF
    
    To have XA execute the above sequence, you must program the
    command file name AND the variable assignment statement:
    
         XA F=SPECIAL.CMD "BABYSITTER = TRUE"
    
    
=====================================================================
26. Appendix C. Running XA in Windows
=====================================================================

    XA may be run in the Windows environment. A major advantage is
    the ability to multi-task your applications while XA monitors the
    CP-290, downloads new event schedules, or performs a special
    lighting sequences.  In order to use XA successfully in Windows,
    you must ensure that Windows understands your COM port
    configuration. Follow these steps (applies to Windows 3.1):
    
      1.Run "Program Manger"
    
      2.In the MAIN group, run "Control Panel"
    
      3.Run "Ports"
    
      4.Select the COM port that the CP-290 is connected to. This
         should match the COM token in you XA.INI file. Press "Settings".
    
      5.Set the Baud Rate to 600, Data Bits to 8, Parity to None, Stop
         Bits to 1, and Flow Control to None.
    
      6.If you use the tokens "IO, IRQ, i=, o=" in your XA.INI file
         (or command line), you should press "Advanced..." button to
         verify these settings.  Make sure the Base I/O Port Address
         matches the address of your COM port. See the table in the XA
         documentation for typical addresses of the COM ports.  Next,
         ensure that the IRQ is set properly. Select "OK".
    
      7.Select OK.  Windows may need to reboot your machine in order
         to activate these parameters.
    
    Several PIF files were included with XA to perform such functions
    as downloading events, monitoring CP-290 activity, and recovering
    from a power failure. You will need to customize these files
    based on your installation.
    
