

XA
X10 Command Interpreter
Version 3.0 - January 1995

Copyright 1991-1995 by Bruce Christensen - All Rights Reserved.


Important Note:
   This file references page numbers found in the printed User's
   Guide.  Please ignore these references.



==========================================================================
1. Shareware
==========================================================================
                                                       
This  floppy contains a set of useful DOS  utilities   Get the latest,
for X10's CP-290 Computer Interface.  These programs   REGISTERED 
are being marketed using the SHAREWARE concept which   version of XA. 
allows  you  a  complete evaluation of  the  product   Fill out 
before  you  are  required to  register.   Shareware   REGISTER.TXT 
provides   you   with   low-cost,   high-performance   and mail it in.
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  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.       

You  can order a registered version of XA with  your   You can order XA
credit   card.   Full  details  may  be   found   in   with your credit
REGISTER.TXT for registration by either PsL  (Public   card too.       
software  Library), or through CompuServe's  on-line
services.


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

You  are  probably  familiar  with  the  menu-driven   "...XA is without 
program  (X10.EXE) supplied with your  CP-290.   The   a doubt, the 
software  approach  used in that  implementation  is   most powerful, 
great  for  beginners since it offers  a  fool-proof   most flexible, 
method    of   organizing   commands   and   events.   most complete 
Unfortunately,  that method also becomes  a  bottle-   package we've 
neck every time you want to activate a single module   reviewed to
via  your  computer.   What's  worse  is  trying  to   date."
maintain a schedule of lighting events that vary due   Electronic House
to  seasonal  changes.  XA is  a  shareware  package   Magazine - 7/94
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  on  pg.  51).   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
--------------------------------------------------------------------------

Beginning  with  Version 3.0, all of  XA's  features
have  been  enabled in the shareware version.   This
includes   IF/ELSE  conditional  statements,   user-
defined     variables,    boolean-logical-arithmetic
operations,  and  I/O  programming.   The  shareware
version  will  occasionally remind you  to  register
this  software.   To bypass these  reminders  simply
order  a  registered  version of  XA.   PsL  (Public
software    Library)   accepts    Discover,    Visa,
MasterCard,  and  American  Express.    Members   of
CompuServe   may   also  order   XA   from   through
CompuServe's online shareware registration  service.
When  you register your copy of XA, you will receive
a   printed  User's  Manual  and  a  floppy  with  a
"registered" version of XA allowing full use of  the
commands   described  in  this  manual.   Refer   to
REGISTER.TXT for complete details.


==========================================================================
3. New Features Summary for Version 3.0
==========================================================================

This  section  summarizes  the  enhancements  to  XA
Version  3.0.  Full details are described  in  later
sections.

* Simplified programming

     1.The use of tokens DATE and TIME are now optional.
       XA will now recognize that 7/1/96 is a date,
       therefore, specifying DATE 7/1/96 is redundant.
       Likewise, XA assumes that 12:34 AM is a time,  so
       writing TIME 12:34 AM is unnecessary.
       
     2.When using the DEFINE token to create an `alias'
       for a select modules, the HOUSE and UNIT tokens are
       no longer needed in the definition:
          OLD WAY:  DEFINE PORCH HOUSE A UNIT 9
          NEW WAY:  DEFINE PORCH A9
     3.You can now override the default drive and
       directory path as specified by the XA environment
       variable.  XA will use whatever path you specify on
       the command line.

* New Bargraph shows CP-290 event utilization

     Whenever XA completes a command sequence, a
     bargraph is displayed showing the amount of
     free and used space in the CP-290.  The %
     utilization is also calculated.
     
     Events:  74 of 128 used ( 57% utilization)
     


* New token: EXPAND
     This token expands a single event command into
     multiple event commands.  For example, if you
     had a statement such as:

          PORCH ON SUNSET EVERYDAY

     XA would program a single event in the CP-290.
     This is fine for events that occur at fixed
     times.  However, for events that are programmed
     based on dynamic data (such as SUNRISE/SUNSET),
     you would get the average sun-time for the next
     7 days.  Now, when EXPAND is programmed, XA
     will automatically create individual events
     using the proper sun-time for each scheduled
     day.

          PORCH ON SUNSET EVERYDAY EXPAND

     This command is also useful when programmed in
     conjunction with the RANDOM token.
     
* Declaring Variables
     In the past, XA would automatically create a
     variable when the parser did not recognize a
     legal XA token (possibly caused by a misspelled
     token).  All variables are now created with a
     "DECLARE variable" statement 
     
     Arithmetic operations can be performed on
     variables.  Variables can be substituted for
     DATES, TIMES, and DAYS.  For example, to
     program a device to activate for 80 days
     following the first day of Spring:

          DECLARE DATE SPRING = 6/21/95
          DECLARE DATE SPRING_80 = SPRING + 80
          
          A1 ON SUNRISE SPRING THRU SPRING_80 EXPAND

Improved Error Reporting.
--------------------------------------------------------------------------
     Because all variables must now be declared, XA
     now provides better error reporting while
     parsing your commands.


* New tokens: INKEY, F1KEY...F12KEY,
              SHIFT-F1...SHIFT-F12,
              CTRL-F1...CTRL-F12,
              ALT-F1...ALT-F12.

     These tokens allow a full screen menu to be
     displayed.  XA reads F1...F12 function keys (or
     combinations of ALT, CTRL, and SHIFT) to invoke
     user-defined actions, such as downloading an
     event file, monitoring CP-290 activity,
     controlling individual lights, creating special
     lighting sequences, or executing DOS commands.
     See pg. 51 for more information.  Also, the
     files KEY.CMD and ALL_KEY.CMD contain many
     programming examples.


* New token: SPAWN
     Spawns a DOS executable file (along with any
     command line arguments) and returns the
     "errorlevel" code from the program to XA.  For
     more information about this token, see pg. 37.

* New token: STATUS
     This command returns the expected state of a
     module as determined by the CP-290's event
     schedule.  You can then use this information to
     program certain actions.
     
     Refer to the command file LO.CMD which
     illustrates a sequence of commands for "logging
     off" your computer.  This file determines if
     it's very late at night and whether certain
     lights need to be activated.  It also shows how
     optional tape backups can be performed (based
     on CDAY) prior to turning the computer off.
     

* New tokens: VIDEO7 (for Bargraph attributes)
              VIDEO8 (for Comment attributes)

     Attributes have been created for XA's newest
     features.  In addition, you can now prevent
     certain statements from being displayed.
     Simply set the VIDEO foreground and background
     attributes of the selected style to the same
     color.  For example, to stop the display of all
     comment statements:

          VIDEO8  BLACK  BLACK

     If a statement begins with the `#' character
     (comment symbol), then the `#' character will
     not be displayed.
     


==========================================================================
4. Feature Summary for XA
==========================================================================

The following list highlights the major features  of
XA.   All  these features are described  in  greater
detail in later sections of this document.

 - 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.
     See page 41 for complete details.

 - 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 "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. See page 21.

 - Improved DATE handling.
     The token "EXCEPT" (see pg. 24) allows you to
     program events EXCEPT when certain dates
     arrive:
          DEFINE MEMORIAL_DAY 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.
     Finally! Support for conditional statements
     within your command files.  Now you can perform
     a test the status of a selected module, or see
     whether SUNRISE falls within a certain time
     period and schedule special events based on the
     result.  IF/ELSE statements can be used to test
     many other conditions.  Feature description
     begins on pg. 50.

 - Variable assignments
     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.

 - Arithmetic / Relational / Logical operators
     Operations may be performed on variables using
     Arithmetic (+, - , \, *), Relational (<, <=, ==
     , >=, >, !=), and Logical (AND, OR, &&, ||)
     operators.

 - 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).  See
     pg. 31

 - INPUT/OUTPUT (I/O) control.
     Use your Joystick port or LPT 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.  See pg. 33

 - 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.
     See pg. 36.

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

 - 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 acknowledgment 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.  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.  You
     can also prevent certain command styles from
     being displayed on the screen. See pg. 42.

 - 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.  See pg. 36.
     
     XA can also "SPAWN" DOS programs that return
     "errorlevel" status which can then be evaluated
     using IF/ELSE logic.

 - Utility to locate CP-290 port connection.
     A 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.

 - 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).
  


==========================================================================
5. Utilities supplied with XA
==========================================================================


POWERUP.EXE
--------------------------------------------------------------------------
 
This  utility  is  provided for  those  of  you  who   POWERUP determines
control  your computer with an X10 Appliance module.   when to update 
Powerup   is  designed  to  be  called   from   your   your CP-290. 
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.

FINDX10  should  be  run in a DOS-only  environment.
When run in a WINDOWS "DOS shell",  FINDX10 may  not
be able to detect the proper IRQ parameters.


==========================================================================
6. 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 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.

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

Finally,  let XA's utility program "FINDX10"  search   FINDX10 will  
your computer's serial ports for the CP-290. FINDX10   determine your 
will   determine  the  IO  port  address   and   IRQ   CP-290 COM port
(interrupt  vector) for that particular port.  These   settings if you
parameters   are   important  for   the   successful   don't know what
operation of XA. If the CP-290 is located, you  will   they are.
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
chapter "FINDX10  Utility" for more details.


IMPORTANT
--------------------------------------------------------------------------

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_300.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,     XA.INI,
JOYSTICK.CMD,  XMAS.CMD,  LO.CMD,  HALOWEEN.CMD  and
REGISTER.TXT


==========================================================================
7. 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:                         DIRECT commands 
                                                       occur immediately.
          XA "A1 OFF"                                  They are not
                                                       stored in the 
     The above is a direct command which sends an      CP-290's memory.
     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     EVENTS contain DAY 
     memory via DOS.                                   and TIME information.
                                                       XA stores events in 
     At the DOS prompt, enter:                         the CP-290's memory 
                                                       for later execution.
          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.


==========================================================================
8. 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  initialization  (XA.INI) and  command  (*.CMD)
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     TOKENS are just
     describe an event or direct command.  When you    special words 
     send a DIRECT command or EVENT via the DOS        that are under-
     command line, a command consisting of several     stood by XA. 
     tokens must be enclosed in "quotation marks".     See "What are 
     The quotation marks inform XA to treat the        tokens?".
     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.
     
     XA uses the path specified in the XA
     environment variable to locate command files.
     You can override this path by including the
     drive:\directory along with the filename:

          XA F=D:\CMD_FILES\MONITOR.CMD

     See also:
          Miscellaneous tokens: XACMD (pg. 36)
          XA.INI - Initialization file  (pg. 51)
          Installation  (pg. 9)
  
  [-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.
     Note that a report file will still be generated
     (if specified).  The file X10.DAT will not be
     created.
  
  [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 (pg. 32)
          Command Line options: [o=io_addr] (pg. 12)
          FINDX10  Utility: (pg. 61)
  
  [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  (pg. 12)
          FINDX10  Utility: (pg. 61)
  
  
  
  [i=irq#]
     XA supports interrupt-driven and polled-mode      FINDX10 will attempt 
     communications with the CP-290.  In general,      to determine the best
     interrupt-driven communications work best,        communication mode.
     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 (pg. .12)
          FINDX10  Utility: (pg. 61)
  
  [+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 specified 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 (pg. 40)
          "Monitoring and Logging Events" (pg. 59)
  
  [+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" on pg. 9).
     
     See also:
          Reporting tokens: LOG (pg. 40)
          "Monitoring and Logging Events" (pg. 59)
  
  [+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 (pg. 40)
          "Report Files" (pg. 57)
  
  [+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" pg. 9).  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 (pg. 40)
          "Report Files" (pg. 58)
  
  [+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
     properly, 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     Use "FORCE" and 
     module to its scheduled state. By default, XA     "IGNORE" tokens 
     uses the last 6 days to determine the state.      to override the
     You can tell XA to use fewer days if necessary.   calculated Power-
     Simply append a number between 1 and 6 to the     fail state.
     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" (pg. 41)
  
  [/?][/h][/H]
     Displays a summary of the options described
     above, along with a list of all supported
     tokens recognized by the interpreter.
     


==========================================================================
9. 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 square  brackets
[..].

Most  of  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.


==========================================================================
10.  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.  Refer to "Table 4 - Dimming Ranges" on
     page 38 for brightness level mappings.

          XA "A1 DIM 50"

     The percentage level you select may not
     correspond exactly with level reported by the
     X10-supplied program X10.EXE.


{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: (as
     described on pg. 17).

          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"    (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 (pg. 34). For
     instance, place the following line in your
     XA.INI file:

          DEFINE COFFEE A10

     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   Set PC time from
     clock based on the current time retrieved from    CP-290 clock.
     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 instructs you to
     press any key to forego the wait period.

          XA "SYNCHRONIZE PC EXACT"


{SYNCHRONIZE X10 [EXACT] }
     These tokens instruct XA to set the time and      Set CP-290 time
     day of the CP-290 internal clock based on the     from PC clock
     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
     instructs you to press any key to forego the
     wait period.

          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" (pg. 26) 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" (pg. 26) is
     also programmed causing the event to trigger
     before midnight, the event  will be modified
     for TODAY status.
     
     You can "define" special days using the DEFINE
     token described on pg. 34.  For example, to
     turn on a hallway light only on school nights:

          DEFINE SCHOOL_NIGHTS SUN MON TUE WED THU
          DEFINE HALLWAY H1
          DEFINE BEDTIME 8:30 PM
          HALLWAY ON BEDTIME SCHOOL_NIGHTS

EXPAND
     This token will automatically expand a single     This is new 
     event command into multiple event commands.       to Version 3.0

          A1 ON SUNSET EVERYDAY EXPAND

     will expand to:

          A1 ON SUNSET SUNDAY
          A1 ON SUNSET MONDAY
          A1 ON SUNSET TUESDAY
              :
          A1 ON SUNSET SUNDAY

     or any other DAY sequence you programmed.
     
     Use this token for dynamic events such as those
     that are based on sunrise/set times.  This
     allows exact sun times to be used for each day
     rather than using the average sun time for the
     upcoming week.
     
     When used in conjunction with RANDOM, unique
     random values will be used for each day rather
     than using the same value for all days.

          A1 OFF 11:30 RANDOM 10 EVERYDAY EXPAND

     The advantage of using this token is that it
     reduces the overall size of your command file
     because fewer statements are required.
     However, keep in mind that command expansion
     consumes additional event storage in the CP-
     290.  It's possible that your schedule may
     exceed the capacity of the interface's memory.
     The bargraph that appears after an XA session
     should help you determine the event utilization
     of your CP-290.
     

     Only use EXPAND for dynamic (sun-related, or      
     random) events only.  Events that occur at a
     fixed time each day do not need to be expanded.


{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     POWERUP performs 
     every Sunday (using POWERUP), the module          automatic, unattended,
     addressed as GARDEN would be programmed as        schedule updates. 
     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 8/10/1994

     The results are:

          Week 3:
            TUE - AUGUST 9, 1994

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

          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 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 11:00 PM"

  -  See section Variables (DECLARE DAY -pg. 45) for an
     example of programming events to occur on random
     days.
  
  -  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
     - pg. 42) 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" on
pg. 60 for more details.

When  using the following "DATE" tokens, you  should   XA always appends 
include  the "ERASE" token at the beginning of  your   events to your 
command  file.  ERASE will clear the entire contents   schedule; you
of  the CP-290, removing all event information.  The   should ERASE the 
reason you want to erase its memory is because  once   CP-290 memory weekly.
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, 1995 at 5:00
     pm:
          A5 ON DATE 7/4/1995 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


     XA now allows you to omit the DATE token.  XA     New to Version 3.0
     recognizes the `/' character as part of an
     actual date.  The preceding example could be
     rewritten as:

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


{ [DATE] mm/dd/yyyy THRU [DATE] mm/dd/yyyy [MON TUE] }
     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:

          7/1/1995 THRU 8/1/1995  ON A3 TIME 9:00 PM SECURITY WEEKDAYS
          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 11/24/95
          DEFINE NEW_YEARS_EVE 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  5/31

     You may specify multiple exception dates in the
     same command:

          A7 ON WEEKDAYS SUNSET EXCEPT  5/31  7/1

  NOTES:
   - Events that are not downloaded because they do
     not meet the date 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 12/1/1994 THRU 1/1/1995
          
   - When dates "rollover" into the next year, you must
     specify the "year" within the date statement (as in
     the above example).
     Use the format:
          { MM/DD/YY THRU MM/DD/YY EXCEPT MM/DD/YY THRU 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  6/21 THRU 9/22 EXCEPT  7/1 THRU 7/14
   - You  can  perform  date  arithmetic  using  XA's
     enhanced operation with variables.  See the topic
     "Variables" (DECLARE DATE on page 44) for  more
     information.



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 "

     The TIME token is now optional.  XA recognizes    This is new 
     the `:' within a numeric string as a time         to Version 3.0
     value.  You could therefore rewrite the above
     the example as:

          XA "D1 ON SUNDAY 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

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

          MONDAY TUESDAY WEDNESDAY ON SUNSET D1

     Use the EXPAND token (see pg. 21) to generate
     additional events for more accurate sun times
     when multiple DAYS are programmed in a single
     statement.

          MONDAY TUESDAY WEDNESDAY ON SUNSET D1 EXPAND

{ [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:

          D1 ON MONDAY SUNSET OFFSET 30



     The OFFSET token is now optional.  XA             This is new 
     recognizes the `:' within a numeric string as a   to Version 3.0
     time offset value.  To turn lights OFF 30
     minutes before sunrise:

          D1 OFF MONDAY SUNRISE  - 30

     Use DEFINEs (see pg. 34) for another way of
     specifying DUSK or DAWN using the DEFINE token.
     For example:

          DEFINE DUSK SUNSET  30
          DEFINE DAWN SUNRISE  - 30
            :
          D1 ON MONDAY DUSK
          D1 OFF  MONDAY DAWN

{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  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 RANDOM 1:30

     RANDOM, as well as OFFSET, will automatically
     change the day if the adjustment causes a
     rollover into the previous or next day.
     
     Use the EXPAND token when multiple days are       This is new 
     programmed in a single command.  This will        to Version 3.0
     ensure that a unique random time will be
     generated for each day:

          A5 ON EVERYDAY SUNSET RANDOM 1:30 EXPAND



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 pseudo-randomly   See the RANDOM token
     select the activation time of the event.  This    for greater control 
     activation occurs within the hour of the          of security events.
     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.   XA can also read data from an I/O  port,
allowing  X10  commands to be synchronized  with  an
external event.

XA  maintains an internal timer which allows you  to
synchronize  lighting  commands  to  specific   time
points.   The timer is initialized to 0 when  XA  is
started,  and  increments itself every 1/10  second.
The timer is reset to 0 whenever the RESET token  is
issued,  or following any keypress after  the  PAUSE
token.

PAUSE
     When this token is executed, it halts further
     execution of the command file and displays the
     message:

          "PRESS ANY KEY TO CONTINUE. . . ."

     When a key press is detected, XA's internal
     timer 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 token to initialize the timer, or
     you could detect a contact closure using the
     INPORT token.  This provides 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
                    # AT 10 SECONDS, TURN ON A1
          A1 ON TIMER 0:0:10.0
                    # AT 20.5 SECONDS, FADE LIGHT OUT.
          A1 DIM 0 TIMER 0:0:20.5

     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 reset to 0.  The
     PAUSE token also resets 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.

{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 below 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.  Labels must contain alpha or
     alphanumeric characters - numbers alone will be
     incorrectly parsed as "time" tokens. 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 next
     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".

  -  IMPORTANT
     The following code flashes (turns ON and OFF) a
     module addressed as A1 three times.  It uses a
     variable (see "Variables" DECLARE VAR pg. 45)
     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:

          # DECLARE AND INITIALIZE COUNTER TO 0
          DECLARE VAR COUNTER = 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 ever-
     changing 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
     acknowledgment 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"

     The sample command file HALOWEEN.CMD contains
     several examples of the FAST token.  Read the
     description in that file how various effects
     were achieved with XA-controlled sound and
     light.  These effects could only be attained by
     including the FAST token on certain X10
     commands.
     
     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 acknowledgment 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 acknowledgment 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
--------------------------------------------------------------------------
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. See the sample command  file
"JOYSTICK.CMD" for an example of turning a light  on
or  off  based  on the state of the joystick  switch
settings.   Another  command  file,  "HALOWEEN.CMD",
reads   the  status  of  a  doorbell  and  a  door's
open/closed state via the joystick port.

{(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.

                   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
that you might 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 8:00 PM EVERYDAY"

     as follows:

          DEFINE XMAS_ON HOUSE A UNIT 4 ON 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 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 6:00 AM EVERYDAY
          PLANT_GROW_LIGHTS OFF  12:00 AM EVERYDAY
            :
          OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
            :
          ALL_ON SUNDAY  7:30 PM

     The use of DEFINES is helpful if you want to
     monitor the CP-290 for events as they occur.


{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.


{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.  When XA
     displays the bargraph upon finishing, a "hole"
     will be shown where the former event was
     located.
     
     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's 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 bargraph during the upload and
     download phases providing a visual indication
     of progress, as well as the amount of available
     event storage.


DIAGNOSE
     This token invokes the CP-290's built-in
     diagnostic firmware.  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 (XA.INI - see pg. 51).
     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: "Advanced
     Programming" and "IF/ELSE/ENDIF Statements"):

        IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
          XACMD M_W_F.CMD
        ELSE
          XACMD XA.CMD
        ENDIF

{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 >= 8/21) AND (CDATE <=  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 <  11:15 PM)
            GOTO :WAIT
          ENDIF
          DOS PROCOMM OPTIONS... # INVOKE PROCOMM
                                 # WITH COMMAND
                                 # LINE PARAMETERS...


{ [variable = ] SPAWN command_string}
     Like the DOS token, SPAWN allows you to execute
     any DOS command from within XA, however SPAWN
     returns an optional "errorlevel" code allowing
     XA to react to the status of the spawned
     process.


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, 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 transition 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.
     

{ [STATE = ] HOUSE-UNIT STATUS }
     These tokens allow you to evaluate the state of   This is new  
     a selected module.  XA will examine the CP-       to Version 3.0
     290's event schedule (using X10.DAT) to
     determine what state the module is currently
     in.  You could then use this information to
     program certain actions. Returned values are:
     
     Returned 
      Value     Command
     ========   ===============================================
        0       OFF  (issued  from an ALL_UNITS_OFF command)
        1       ON   (issued  from an ALL_LIGHTS_ON command)
        2       ON   (standard ON command)
        3       OFF  (standard OFF command)
        4       DIM  (standard DIM command)
        5***    DIM  (standard  DIM  command)  
                      High byte  contains  dim level  (0...F),
                      Low byte contains 5 (Dim command).
        6       OFF  (issued from an ALL_LIGHTS_OFF command 
                      - not supported by XA)
        7       UNKNOWN command
            Table 3 - Module State Values


     ***Note:  When XA returns the status of a
               module that is currently DIM, the brightness
               level (0...F) is placed in the upper byte of
               the status value.  The DIM command (5) is
               placed in the lower byte.  The following table
               lists the returned dimmed values and their
               associated brightness level.


             Returned Value    Brightness Level
             (upper byte)
             ===============   ================
                  0                 100%
                  1                 94-99
                  2                 87-93
                  3                 80-86
                  4                 74-79
                  5                 67-73
                  6                 60-66
                  7                 53-59
                  8                 47-53
                  9                 40-46
                 10 (A)             34-39
                 11 (B)             27-33
                 12 (C)             20-26
                 13 (D)             14-19
                 14 (E)             7-13
                 15 (F)             0-6

                Table 4 - Dimming Ranges

     Assume module B2 was programmed to a brightness
     level of 75%.  The STATUS command would return
     a value of 45 hexadecimal (or 69 decimal).  The
     `4' in the upper bytes indicates the brightness
     level in the range of 74...79, and the `5' in
     the lower byte describes the last X10 command
     which was DIM.
     
     To examine the current state of A3, and turn it
     OFF if it is currently ON:

          A3_STATE = A3 STATUS
          IF (A3_STATE == 2)  # IF A3 IS ON
            A3 OFF            # ...TURN IT OFF
          ENDIF
     
     Refer to LO.CMD for another example.  This
     sample command file performs several
     interesting functions.  The primary service is
     to "logoff" (shut down) the computer.  Prior to
     turning the computer off, it checks to see what
     the current time is (using CTIME - see pg. 47).
     If it's late evening or early morning, and
     several CP-290 controlled lights were turned
     off because they were scheduled to,  then XA
     turns them back on for a 2 minute period so I
     don't have walk in a darkened room.  In this
     example, we are only concerned with the state
     of the module (ON, OFF, or DIM), not its
     brightness level.  Therefore we "mask off" the
     brightness value in the upper byte.  This can
     be accomplished with bitwise AND ("&") operator
     (described in detail on page 49).
     
          DEFINE  X10_OFF  3
          DECLARE  VAR  STAIRS_STATE
          #   MASK OFF UPPER BYTE (POSSIBLE DIM LEVEL)
          STAIRS_STATE  = (H1 STATUS & 0FH)
          
          DISPLAY ON
          IF ((SUNSET < CTIME) || (CTIME < SUNRISE))
            #
            # DETERMINE IF IT'S NECESSARY TO ACTIVATE ANY LIGHTS...
            #
            IF (STAIRS_STATE == X10_OFF)  # IS IT OFF?
              STAIRS ON                   # YES, TURN IT ON NOW
              STAIRS OFF NOW 2            # ...AND TURN IT OFF IN 2 MINS
            ENDIF
          ENDIF



Reporting Tokens
--------------------------------------------------------------------------

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.


==========================================================================
11. 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

There  are  two token statements which 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 DEHUMIDIFIER

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

          XA "IGNORE BEDROOM_LAMP" -P


==========================================================================
12.  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  such  as
IF/ELSE, DATE/THRU/EXCEPT were evaluated by XA  just
by looking at the display.

{VIDEO1 Foreground Background}
     IF or ELSE expression is TRUE.

{VIDEO2 Foreground Background}
     IF or ELSE expression is FALSE, 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}
     Other non event or command statements processed
     by XA.

{VIDEO7 Foreground Background}
     Bargraph display (event upload, event
     utilization).

{VIDEO8 Foreground Background}
     Comments - commands the begin with `#'
     character.
     
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

You  can  prevent  certain types of statements  from
being  displayed  on the screen.   Simply  set  both
attributes to the same color.  For example, to  turn
off  all lines beginning with comments `#', set  the
VIDEO8 statement to:

          VIDEO8 BLACK BLACK


==========================================================================
13.  Advanced Programming
==========================================================================


Variables
--------------------------------------------------------------------------
Variables   are  user-defined  objects   which   are
assigned  a  value.  You can assign numbers,  dates,
times,  port data, true/false data into a  variable.
Later,  these  variables  can  be  substituted   for
certain  tokens  in a command.   They  may  also  be
evaluated                                      using
relational/boolean/logical/arithmetic operations.

Prior  to  their  usage  in a command,  user-defined
variables  must  first  be  declared.   Declaring  a
variable  simply tells XA how the variable  will  be
used  later on.  Currently, XA supports 4  types  of
variables:   DATE,  TIME, DAY, and general  purpose.
You   can  declare  a  variable  using  one  of  the
following statements:

    {DECLARE  DATE  VARIABLE_NAME  [ = MM/DD/YYYY ] }
    {DECLARE  TIME VARIABLE_NAME  [ = HH:MM ] }
    {DECLARE  DAY VARIABLE_NAME  [ = MON | TUE | ... SUN ] }
    {DECLARE  VAR VARIABLE_NAME  [ = VALUE] }
          
Internally, variables are treated as 32 bit  integer
values.   If  a  variable  is  created  without   an
initializer,  it  is  set  to  0.   Otherwise,   the
variable   is  assigned  the  value  following   the
assignment ( = ) operator.

The  following example creates a date type  variable
called `vacation'.  It is not initialized until  the
second statement:

          DECLARE DATE VACATION
          VACATION = 7/14/95

The  same variable could be declared and initialized
in the same statement:

          DECLARE DATE VACATION =  7/14/95
          DECLARE DATE VACATION_END = VACATION + 14

Use  these variables in your program just  like  you
would use regular dates.

          DEN ON SUNSET VACATION THRU VACATION_END EXPAND
          DEN OFF 11:30 RANDOM 10 VACATION THRU VACATION_END EXPAND

When declaring variables, 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_


--------------------------------------------------------------------------
                    IMPORTANT
Prior  to Version 3.0, XA would automatically create
variables  whenever the parser encountered  a  token
that  was  not  part of its language.   However,  an
inadvertent  spelling mistake could  turn  an  event
into  a  direct  command or a  comment  without  any
explanation.  This can make debugging a command file
very  frustrating.  Now, declaring a variable  as  a
TIME,  DATE, DAY, or general purpose variable, makes
XA much more powerful, and more robust.
--------------------------------------------------------------------------

{DECLARE DATE variable_name  [ = mm/dd/yyyy ] }
     DATE variables allow you to perform simple date
     arithmetic much easier.  A great example of how
     to use DATE variables and perform arithmetic
     operations on them is shown below.  It Is
     possible to calculate important dates in the
     Hebrew calendar because most of the holidays
     can be calculated as a fixed number of days
     from the first day of Passover.

          DECLARE DATE YTREF = 3/26/94
          DECLARE DATE YOM_KIPPOR_EVE = YTREF + 172
          DECLARE DATE YOM_KIPPOR = YTREF + 173
          
          A10 ON SUNSET YOM_KIPPOR_EVE

{DECLARE TIME variable_name  [ = hh:mm ] }
     Use a variable of type TIME to program a chime
     module to activate every hour at the top of the
     hour between 8:00 am and 10:00 pm weekdays.
     Note how the declared variable "hour" is
     adjusted by 1 hour in the loop.

          DECLARE  TIME HOUR = 8:00
          :HOUR_LOOP
          CHIME ON HOUR WEEKDAY
          HOUR = HOUR + 1:00
          IF (HOUR <= 10:00 PM)
            GOTO :HOUR_LOOP
          ENDIF

{DECLARE DAY variable_name  [ = day [day...] ] }
     The next example lets you activate a module on
     random days.  Use CDATE and CTIME to generate a
     random number. Then mask off the lower 7 bits
     to create a 7 day bitpattern for the programmed
     days.

          DECLARE  DAY RAND_DAY
          RAND_DAY = (CDATE * CTIME) & 7FH
          A1 ON SUNSET RAND_DAY EXPAND

{DECLARE VAR variable_name  [ = value] }
     Use this declaration for all other types of
     data.  For instance, to read input from the
     joystick port:
     
          DECLARE VAR JOYSTICK
          JOYSTICK = INPORT 201H

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


IMPORTANT
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 >=  11/25) AND (CDATE <= 12/31))
            INCLUDE XMAS.CMD
          ENDIF

CMONTH
     The current month (1=January, 2=February,
     12=December).

CMONTHDAY
     The current day of the month (1...31).

CYEAR
     The current year (1994...xxxxx).

CYEARDAY
     The current day of the year (1...365, 366
     during leap years).

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 >=  11:30 PM)
                  GOTO EXIT
              ENDIF
          ELSE
              IF (CTIME >=  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 5 - 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 6 - 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 7 - 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 8 - 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 9 - Bitwise Logical Operators



==========================================================================
14. IF/ELSE/ENDIF Statements
==========================================================================

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 5:30 WEEKDAYS RANDOM 10 EXPAND
             OUTSIDE_PORCH_LIGHTS OFF SUNRISE WEEKDAYS EXPAND
             LIVING_ROOM_LAMP ON 5:35 WEEKDAYS RANDOM 10 EXPAND
             LIVING_ROOM_LAMP OFF SUNRISE WEEKDAYS OFFSET 10 EXPAND
          ENDIF


==========================================================================
15.  Menus / Functions Keys
==========================================================================

XA  allows  you  to  activate special  X10  lighting
sequences or other actions with a simple press of  a
function  key.   For instance, download  a  complete
schedule  update,  or turn on the  TV  and  dim  the
lights  at  the press of a key.  Up to  48  function
keys  may  be programmed (F1...F12, Shift F1...Shift
F12, Ctrl F1...Ctrl F12, and Alt F1...Alt F12)..

Use  the  INKEY token to read data from the keyboard
and  store  it  into a user-defined  variable.  This
variable must be declared prior to its usage:

          DECLARE  VAR  KEY

{variable = INKEY}
     These tokens will read the keyboard and store
     the latest keypress value in a user defined
     variable.  `Variable' must have been previously
     declared or an error message will be displayed.

          KEY = INKEY

F1KEY...F12KEY
SF1KEY...SF12KEY
CF1KEY...CF12KEY
AF1KEY...AF12KEY
     XA handles all of the normal function keys, F1
     through F10 (F11 and F12 if your keyboard
     supports them).  You can access a total of 48
     function keys by pressing either Shift, Ctrl,
     or Alt in unison with the function key.  That
     is, press <Shift> and <F1> together.
     
     Use a series of IF/ELSE statements to determine
     the keypress and the resulting action to be
     taken.

          DECLARE VAR KEY
          :LOOP
          KEY = INKEY
          IF (KEY == F1KEY)
            INCLUDE XA.CMD   # DOWNLOAD XA.CMD
          ENDIF
          IF (KEY == SF1KEY)
            DOS XA "MONITOR" # MONITOR EVENTS
          ENDIF
          IF (KEY == AF1KEY)
            A1 ON            # TURN ON PORCH
          ENDIF
          IF (KEY == CF1KEY)
            A1 OFF           # TURN OFF PORCH
          ENDIF
          GOTO :LOOP         # LOOP UNTIL <ESC> PRESSED
     
     Refer to the sample command files "KEY.CMD" and
     "ALL_KEY.CMD" for examples of programming these
     function keys.  Note that these files use
     repeated looping so that additional sequences
     can be handled after each function.  Press the
     <ESC> key to exit the loop.

     Note how monitoring is activated when the         If you want to 
     <SHIFT><F1> keys are pressed in the sample code   control logging, 
     shown above.  If you had used the single token    reporting, or
     "MONITOR", then XA would have queued the          powerfail recovery
     request and would not have invoked monitoring     features via a 
     until all direct commands and events were         function key, you
     processed.  Since the program loops               must use the DOS 
     continuously, the monitor request won't be        token as well.
     handled until the <ESC> key is pressed.  The
     trick to initiating monitoring immediately is
     to invoke another copy of XA with the monitor
     request as a command line parameter.  The "DOS"
     token loads and starts another program in the
     computer's memory (in this case, XA).  Since
     "MONITOR" is the only argument on the command
     line, XA begins monitoring immediately.  When
     you want to end monitoring, press the <ESC>
     key.  The second copy of XA is terminated
     returning control to the original copy of XA.
     


==========================================================================
16. 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
          DECLARE ...   - CERTAIN VARIABLES MAY BE DECLARED HERE

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 -
pg.  9)  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 (see next section).

You  may place comments in your initialization file.
A  comment is delineated by the pound sign character
"#".   The  comment  symbol may  be  placed  in  any
column,  however  XA  will not display  the  comment
symbol if it appears in the 1st 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
Windows   "NOTEPAD"  are  excellent  utilities   for
modifying these files.


==========================================================================
17. 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.   Also,  specific  date
information may 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 Christmas 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 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

Prior  to Version 2.0, XA would only execute  either   You can pass parameters
command files or commands passed as arguments to  XA   to your *.CMD files 
on  the  DOS command line - NOT  BOTH.  With version   allowing IF/ELSE 
2.x,  you  can execute both types at the same  time,   evaluation.
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.  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

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

          XA F=XA.CMD "VACATION = 1"

XA's  new error handling requires that all variables
must  be declared before they can be used.   In  the
above example, if you invoke XA with the statement:

          XA F=XA.CMD "VACATION = 1"

then  the  variable "VACATION" must have  been  pre-
declared.   The best way to accomplish  this  is  to
place  the  declaration of VACATION  in  the  XA.INI
file.  This way, you will avoid an error message  if
you the variable is not declared.

          DECLARE VAR VACATION

Remember, only variables that you intend to pass  on
XA's  command line should be declared in the  XA.INI
file.  


==========================================================================
18. 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 A5

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  initialization
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, DECLARE, 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 by 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  later evaluated so special actions can be taken
inside  your command file. See the previous  section
for more details.


==========================================================================
19. 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.

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 it's 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 "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).   If
you  specify the '-e' command line option, then  the
events  will  not be downloaded, but  they  will  be
assigned an event number.  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 3.0
Copyright 1991-1995 by Bruce Christensen. All Rights Reserved.
Registered to: Your name here - Your town here.

Event report prepared: 12/14/94 10:09 PM

Saturday - September 25, 1993     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 3.0
Copyright 1991-1995 by Bruce Christensen. All Rights Reserved.
Registered to: Your name here - Your town here.

Event report prepared: 12/14/94 10:09 PM

Saturday - September 25, 1993     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)*


==========================================================================
20. 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 A1
          DEFINE PLANT_GROW_LIGHTS A 5
          DEFINE FAMILY_ROOM_TV A6
          DEFINE BASEMENT_COMPUTER A7

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 so, 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

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 (pg.  9)  for
more information about the XA environment variable.


==========================================================================
21.  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  during  your  computer's  boot
phase.  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 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


==========================================================================
22.  FINDX10  Utility
==========================================================================

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.

                    IMPORTANT!
FindX10  may not work properly if run from a Windows
DOS shell.  You must exit Windows completely and run
standalone  DOS.  Also, because of the wide  variety
of  hardware  in  use, FINDX10 may not  be  able  to
locate the CP-290.


==========================================================================
23.  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.0  and  later)  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 command 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  (pg.  64).   Look   for
X10FX100.ZIP (the version number - 1.00) is the last
3 digits of the ZIP filename.


==========================================================================
24.  Acknowledgments
==========================================================================

I would like to thank the following 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 this round of beta testers: Evan Willner
and  Dennis Contat..  Finally, I'd like to thank all
the  folks who have taken the time to register  this
program and offer suggestions.


==========================================================================
25. 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, documentation, utilities,
and  additional support files are Copyright  1991-
1995 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, you are granted the  right,  in
fact  encouraged,  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 the registration fee to
the  address  below.   You may  also  register  this
product  with  Public software Library  (PsL).   PsL
accepts  Discover,  Visa, MasterCard,  and  American
Express.  If you are a member of CompuServe, you may
register    XA   using   their   on-line   shareware
registration  service.  Refer  to  REGISTER.TXT  for
complete  details.  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 "X10XA300.ZIP".
The  last 3 digits of the filename will indicate the
revision level (in this case, 3.00).

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.

PC-Ohio BBS - The Best BBS in the U.S.  Subscription
required. 1-(216)-381-3320.


==========================================================================
26. 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
  EXPAND - Expands a single event into multiple events
  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
  {SPAWN command} - Shell to DOS, returns "errorcode".
  {variable = House/Unit STATUS} - determines programmed state of module
  {DISPLAY ON/OFF} - Turn XA output display on or off.
  DIAGNOSE - CP-290 performs internal diagnostics.
  {XACMD filename} - defines default command file.

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.
  {VIDEO7 Foreground Background} - Bargraph display
  {VIDEO8 Foreground Background} - Comments
  
  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

Variables
  {DECLARE DATE variable_name [=mm/dd/yy] - Declare, initialize date var.
  {DECLARE TIME variable_name [=hh:mm] - Declare, initialize time var.
  {DECLARE DAY variable_name [=MON|TUE...] - Declare, initialize day var.
  {DECLARE VAR variable_name [=value] - Declare, initialize general purpose var.

Pre-defined Variables
  CDAY - The current day (Mon, Tue)
  CTIME - The current time
  CDATE - The current date
  CMONTH - The current month (1=Jan, 2=Feb)
  CMONTHDAY - The current day of the month (1...31)
  CYEAR - The current year (1994...)
  CYEARDAY - The current day of the year (1...366)

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


Menus / Function Keys
  {varaible = INKEY} - Read a keystroke.
  F1KEY...F12KEY - Normal Function keys.
  SF1KEY...SF12KEY - <Shift> Function keys.
  CF1KEY...CF12KEY - <Ctrl> Function keys.
  AF1KEY...AF12KEY - <Alt> Function keys.


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

By  default,  XA will only accept input from  either
the  DOS  command line (i.e., 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"


==========================================================================
28. 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.
