XA
X10 Command Interpreter
Version 2.00 - October 1993
Copyright 1993 by Bruce Christensen. All Rights Reserved.



1.   Shareware


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


2.   Introduction 


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


What is XA?


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

     XA "PORCH ON"

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

     XA "WARNING_LAMP ON"        
     TELIX (or ProComm) statements here        
     XA "WARNING_LAMP OFF"
     
XA will also process X10 commands and events contained in a file. 
This is ideal for maintaining the CP-290's event schedule, or for
running a Christmas "lightshow".  Simply tell XA which file to read,
and XA does all the work.  For instance, to download my event
schedule to the CP-290, type:

     XA f=XA.CMD

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


Registered vs. Shareware


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


3.   Summary of NEW Features for Version 2.00 


The last "official" release of XA was Version 1.07b (dated July,
1992).  Version 2.00 is a complete re-write, allowing such features
as conditional statements, operators, and user-variables to be
supported.  Also, XA performs sun-related calculations much faster. 
The following list highlights the major enhancements of Version
2.00.  Additional details may be found in later sections.

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

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

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

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

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

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

* Variable assignments                   (Registered Version Only)
  Variables may be used as temporary storage locations.  These
  variables may then be evaluated later using IF/ELSE constructs to
  trigger a DIRECT command or to program an EVENT.

* Logical, Arithmetic operators.         (Registered Version Only)
  Operations may be performed on variables and later evaluated.

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

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

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

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

* Nested DEFINE support.
  In the past, XA could not handle a statement with multiple
  DEFINE substitutions.  The following is now permitted:

     DEFINE PORCH A1
     DEFINE GARAGE A2
     DEFINE OUTSIDE PORCH GARAGE

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

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

* Conditional COLOR highlighting.          (Registered Version Only)
  XA can optionally display each line of the XA.INI and command
  file as it's parsed. In addition, you can define your own color
  attributes for conditional statements that evaluate TRUE or
  FALSE, as well as define special color attributes for EVENTS and
  DIRECT commands.

* Shell to DOS capability.
  XA can invoke a copy of COMMAND.COM allowing you to execute a
  DOS program, batch file, etc. from within a command file. 
  
* Utility to locate CP-290 port connection.
  A new utility called FINDX10.EXE searches all 4 COM ports for
  the CP-290 interface.  If it is found, you are asked whether you
  would like the parameters stored in the XA.INI file for you.  

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

Other Features 


- 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


- You can program the CP-290 to repeat a series of commands to 
  produce unique lighting effects.  

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

- The ability to change the base housecode 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).

- Comments are allowed in the file to properly document its
  content.


4.   Utilities supplied with XA


POWERUP.EXE


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


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 address and IRQ of the port and attempts to
communicate with the CP-290. If it successfully  locates the
CP-290, it displays the port setup and prompts you if it is OK
to save the data in your XA.INI file.



5.   Installation 


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

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

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

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

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

     SET XA=C:\X10

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

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



6.   Getting Started 


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

Method 1 - The "HELP" screen.


At the DOS prompt, enter:

     XA

XA will display the first of many different "help" screens.
These screens include a brief synopsis of XA, and a list of
available commands that it recognizes.

NOTE: This method will not work if the token XACMD is defined in
your XA.INI file. The default XA.INI file shipped on this floppy
will have XACMD "commented out" (or undefined).   


Method 2 - The "HELP" screen.


At the DOS prompt, enter:

     XA /?
     XA /H
     XA /h

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


Method 3 - Executing a DIRECT Command from DOS.


At the DOS prompt, enter:

     XA "A1 OFF"

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


Method 4 - Storing an EVENT into the CP-290's memory via DOS.


At the DOS prompt, enter:

     XA "A1 ON MONDAY SUNSET"

XA will determine which event slot is available in the CP-290's
memory. The event will be downloaded for later execution. 
Events are distinguished from direct commands by the fact that
events normally contain a DAY modifier (in this case MONDAY -
but you could also use TODAY or TOMORROW) and a TIME modifier
(SUNSET is a special TIME token). 


Method 5 - Executing a Command File


At the DOS prompt, enter:

     XA f=XA.CMD

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




7.   XA Syntax and Command Line Arguments


XA understands the following command line options:

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

Options appearing on the command line always override any
options that have been specified in XA's command and
initialization files.  This gives you the final "say" when
overriding defaults.

Options and commands are parsed from left to right. Under normal
circumstances, options may appear in any order without any
conflict.  Many of these options have equivalent tokens that can
be embedded within a command file or the XA initialization file
(XA.INI). Therefore, you won't have to specify these options
every time you execute XA.


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

     XA "A1 ON"

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

     XA "A1 ON" "A1 OFF" "A1 ON" "A1 OFF"


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

     XA f=monitor.cmd

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

  You can specify a default command file using the "XACMD" token
  in the XA.INI initialization file (described in greater detail
  later).

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


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


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

     XA c=3

  If not specified, the default port will be COM1.  

  When using this option, you are actually specifying both an IO
  address as well as the IRQ vector for this port. See the table
  listed in the "Communications Tokens" section, later in this
  document.  

  See also:
     Communication tokens: COM1...COM4
     Command Line options: [o=io_addr]


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

      XA o=2E8H

  See also:
     Communication tokens: IO x


[i=irq]
  Interrupt-driven: i=irq (3,4,5...)  

  Default: i=4  (for COM1).

  See also:
     Communication tokens: IRQ x


[+m] 
  This option will monitor the comm port for any events reported
  by the CP-290.  Press the <ESC> key to terminate. 

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


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

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

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

  See also:
     Reporting tokens: REPORT1
     "Report Files"


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

     XA +r1 +r2

  See also:
     Reporting tokens: REPORT2     
     "Report Files"


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

[-p]
  Immediate recovery based on stored events, no parsing of command
  file takes place.

  Powerfail recovery allows you to restore each module to its
  scheduled state. By default, XA uses the last 7 days to
  determine the state.  You can tell XA to use fewer days if
  necessary. Simply append a number between 1and 6 to the command.
  If you want XA to review the event schedule of the previous 2
  days in order to determine the correct state, then append a 2 to
  the command, for example:

     XA -p2

  Use "-e" in conjunction with either "+p" or "-p" to see how XA
  would restore each module without actually sending any X10
  commands.

  See also:
     "Powerfail Recovery"

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




8.   XA Tokens 


What are tokens?

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

     XA "A1 ON"    may also be constructed as:        
     XA "ON A1"

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

     XA "SYNCHRONIZE PC"      <---This is legal

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

     XA "PC SYNCHRONIZE"      <---This is illegal

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

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



9.   Tokens in Detail 


Action Tokens 


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

        XA "A1 ON"


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

        XA "A1 OFF"


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

        XA "A1 DIM 50"


  {ALL_UNITS_OFF HOUSE x}
     These tokens will issue the X10 "ALL_UNITS_OFF" command for the
     selected housecode. This command affects Appliance-style and
     Lamp Dimmer/Wall Switch modules.

        XA "ALL_UNITS_OFF HOUSE A"

     Using this command is faster than issuing (as described in the
     next section):

        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"



     Notes:
      * 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 were 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"     or use the faster method:
        XA "HOUSE P ALL_UNITS_OFF"


     Notes:
      * 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 (described later). For instance, place the
        following line in your XA.INI file:

           DEFINE COFFEE HOUSE A UNIT 10
           
        To turn the coffee pot ON from your computer, all you have to
        type is:

           XA "COFFEE ON" or   
           XA "A10 ON"


Coordinate Tokens 


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

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

        LATITUDE 41d35m20s   -or-        
        LATITUDE 4135'20"


  {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 81d20m45s     -or-        
        LONGITUDE 8120'45"


  {TIMEZONE x}
     Exact calculations depend on the local time.  Use the following
     table to determine your time zone. Previous versions of XA
     included "Daylight Savings" values in this table. It is no
     longer necessary to manually change these tokens. Use the DST
     token to automatically adjust time changes.

               ZONE      TIMEZONE 
           ============= ========
           Eastern           5 
           Central           6 
           Mountain          7 
           Pacific           8 
           Alaska/Hawaii    10 
           Aleutian         11 

        TIMEZONE 5


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

        TIMEZONE 5  DST



Clock Tokens 


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

        XA "SYNCHRONIZE PC"

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

        XA "SYNCHRONIZE PC EXACT"


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

        XA "SYNCHRONIZE X10"

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

        XA "SYNCHRONIZE X10 EXACT"

     Notes:
      * 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
     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 MONDAY TUESDAY WEDNESDAY THURSDAY  FRIDAY.

  EVERYDAY
     Event occurs MON TUE WED THU FRI SAT SUN.

  TODAY
     Event will occur today only at the specified time.  It is then
     deleted from the interface after midnight.  If "OFFSET hh:mm" is
     also programmed causing the event to trigger after midnight, the
     event will be modified for TOMORROW status.

  TOMORROW
     Event will occur tomorrow only at the specified time.  It is
     then deleted from the interface after midnight.  If "OFFSET
     hh:mm" is also programmed causing the event to trigger before
     midnight, the event  will be modified for TODAY status.  

  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 XA's
     memory. The following command will take place at 11:00 tonight
     and be deleted at midnight since it was given "TODAY" status (no
     other DAY was specified):

        XA "FAN ON TIME 11:00 PM"

   * Registered Users - Using the "CDAY" token in conjunction with
     "SAT,SUN MON, TUE, WED, THU, FRI, WEEKEND, WEEKDAY" tokens
     allows you to program special functions based on the current
     day. For example, the statements below will the initialize the
     default command file (using XACMD) based on the current day.
     Note: Use of the IF/ELSE/ENDIF and CDAY tokens, as well as the
     "==" and "OR" operators will be discussed later in this 
     document.

        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.

To guarantee that specific dates will be evaluated and events
will be triggered at the proper time in the future, plug your
computer into an Appliance module and have the CP-290 turn your
computer on automatically on a once-per-week basis.  By using
XA.EXE in conjunction with POWERUP.EXE (supplied with this
package) you can have a new set of events automatically
downloaded to the CP-290. Now you'll never forget to update your
CP-290, your computer  does it for you automatically.  This is
what "automation" is all about.  See  section "Powerup" for more
details.

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


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

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

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

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

        DATE /4/ A5 OFF TIME 6:00 AM

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

        DATE 7/4/ A5 ON SUNSET

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

        DATE 7/4 A5 ON SUNSET

     You may specify multiple dates in the same command:

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


  {DATE mm/dd/yyyy THRU mm/dd/yyyy (DAY)}
     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, 1994 and August
     1, 1994, and you want the bedroom lights (A3) turned ON and OFF
     every weekday in a random fashion during the evenings:

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

     To turn ON your Christmas lights everyday between Dec. 1st and
     Jan. 1st. Turn them OFF at 10:00PM on weekdays, turn them off at
     11:30 during the weekends:

        DATE 12/1 THRU 1/1 XMAS ON SUNSET
        DATE 12/1 THRU 1/1 XMAS OFF TIME 10:00 PM WEEKDAYS
        DATE 12/1 THRU 1/1 XMAS OFF TIME 11:30 PM WEEKENDS


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

        A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31

     You may specify multiple exception dates in the same command:

        A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1


     Notes:
      - Use the format:

      {EXCEPT DATE mm/dd/yyyy THRU mm/dd/yyyy (DAY)}
        to prevent an event from occurring between two dates. EVERYDAY
        will be assumed unless you place specific DAY tokens within the
        command.  For example, to prevent the porch lights from coming
        on while your Christmas lights are on:

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

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

     - Use the format:

     {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT DATE mm/dd/yyyy THRU mm/dd/yyyy} 
        to specify a range of dates that a module should not activate,
        within a range of dates that they should be activated.  For
        instance, turn on deck lights only during the summer, except
        while you are on  vacation:

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

           
Time Tokens


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

  {TIME hh:mm (AM/PM)}
     Schedule event at a certain time.

        XA "D1 ON SUNDAY TIME 12:30 AM"

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

        XA "D1 ON SUNDAY TIME 23:34 "


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

        D1 ON MONDAY SUNSET

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

        MONDAY TUESDAY WEDNESDAY ON SUNSET D1

     If more accuracy is needed, then break each daily event into its
     own command.

        MONDAY ON SUNSET D1
        TUESDAY ON SUNSET D1
        WEDNESDAY ON SUNSET D1


  {OFFSET +/-hh:mm}
  {OFFSET +/-mins}
     Push or postpone the scheduled event by up to 24 hours (1440
     minutes).  This token is useful if you want to activate lights
     at dusk rather than sunset, or to deactivate lights at dawn
     rather than sunrise.  The '+' sign is the default condition, you
     must specify the  '-' if needed.  To turn ON lights 30 minutes
     after sunset:

        MONDAY ON SUNSET D1 OFFSET 30

     Turn lights OFF 1 hour before sunrise:

        MONDAY OFF SUNRISE D1 OFFSET -1:00

     See section Miscellaneous Tokens - DEFINE for another way of 
     specifying DUSK or DAWN using the DEFINE token.  For example:

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


  {NOW +mm}
  {NOW +hh:mm}
     Creates a one-shot event based on the current DOS day and time
     and the hh:mm offset specified in the token. The event will
     initially be given a "TODAY" status.  If the added offset causes
     the event to be scheduled past midnight, the event will be
     converted to "TOMORROW" status.  In either case, the event will
     be deleted from the CP-290 at midnight following its activation.
 
     The following command file example shows how to activate a
     battery charger and then turn it off 14 hours later. This 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 hours 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.  XA Version 2.0 automatically appends the command to
     current schedule,  eliminating the need to figure this out
     manually.


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


  {RANDOM +/-hh:mm}
  {RANDOM +/-mins}
     Prior to Version 1.07, RANDOM used to be synonymous with the
     SECURITY token, which merely activated the CP-290 built-in time
     adjustment.  This feature would pseudo-randomly select a time
     for event activation anytime within the programmed hour.  
     "RANDOM hh:mm" now gives you complete control over the random
     window.  "hh:mm" is the number of hours and minutes that a
     random offset should be added/subtracted from the programmed
     time. This offset should be in the range of 1 minute to 24 hours
     (1440  mins).  If "hh:mm" is programmed with a "+" sign, then
     the calculated random value will be added to the programmed
     time. The following example will add between 0 and 9 minutes to
     the requested time, that is, anywhere between 5:00 PM and 5:09 PM.

        A5 ON TIME 5:00 PM RANDOM +9

     If "mm" is programmed with a "-" sign, then the calculated
     random value will be subtracted from the programmed time. The
     following example will subtract between 0 and 15 minutes from
     the calculated SUNRISE time. If SUNRISE occurs at 6:00 AM, then
     the resulting time could be anywhere in the range of 5:45
     through 6:00.

        SUNRISE RANDOM -:15

     If "mm" is programmed without any sign, then the calculated
     random value will either be added or subtracted to/from the
     programmed time.  For example, to allow 90 minutes of either
     side of SUNSET:
     
                                # Sunset @ 9:00 PM
        SUNSET RANDOM 1:30       # TIME ranges between 7:30 PM ... 10:30 PM

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


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

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

        
Direct Command Control Tokens


The following tokens may be used within an XA command file so
you can use the CP-290 to perform a series of lighting effects.
Certain commands may be repeated a limited number of times or
forever.  Commands may also be synchronized with a key press,
allowing special effects with a high degree of accuracy.  The
"registered" version of XA can also read data from an I/O port,
allowing X10 commands to be synchonized with an external event.


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

        "Press any key to continue..."

     When a key press is detected, an internal timer 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 mm:ss.s
     This token informs XA to issue a command when the internal timer
     reaches "mm:ss.s".  The built-in timer is initialized to 0 when
     XA is invoked, or whenever a key press follows a PAUSE command,
     or when the token "RESET" is parsed. All subsequent TIMER
     commands are evaluated from the point at which the internal
     timer was initialized.  

     One very useful application of the PAUSE and TIMER commands is
     to synchronize X10-controlled lighting sequences with
     pre-recorded  music.  For instance, you could assign each song
     its own command  file.  Each file would start off with a PAUSE
     (Registered version may use INPORT) token to intialize the 
     timer, as well as provide a means to start the music and command
     chain from a common point.  TIMER statements would specify the
     exact times that the CP-290 would trigger an X10 command at an
     appropriate moment in the song.


        PAUSE                      # Wait for any key press, reset timer
        A1 ON TIMER 0:10.0          # At 10 seconds, turn on A1
        A1 DIM 0 TIMER 0:20.5      # At 20.5 seconds, fade light out.
        
     In this example, the PAUSE waits for a cue to start the
     sequence. 10 seconds later, A1 is activated. 20.5 seconds after
     the cue, A1 is DIMMED to a level 0.

     XA will automatically anticipate and adjust for any delays that
     may be caused by the CP-290.  For instance,  the amount of time
     it takes to turn on a lamp may take as much as 1.4 seconds. Even
     worse, the CP-290 forces a lamp module to go to the fully BRIGHT
     state before allowing the module to be dimmed - delaying the
     actual effect by 6 seconds.  In order to have XA compensate for
     these delays, you should place an X10 command on the same line
     just prior to the timer command.  For example, the following
     line turns the lamp on after 7 seconds. However, XA actually
     issues the command at 5.6 seconds:

        A1 ON TIMER 0: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: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 'minutes' field, even
     if it is zero. Otherwise, XA will convert the 'seconds' field to
     minutes, and you'll be waiting a long time. For example, do this:
  
        TIMER 0:15.5   <--- Do this
        TIMER 15.5      <--- NOT this


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


  {DELAY hh:mm:ss}
     These tokens allow you wait for the specified number of hours,
     minutes and seconds to pass before executing the next command. 
     These delays are relative to the present time and do not work in
     conjunction with the TIMER or PAUSE tokens.  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.  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".

     NOTE: Earlier versions of XA used the following syntax:

        GOTO :label times         

     where "times" acted as a counter.  This method is no longer
     supported. Use the conditional statements (IF/ELSE -
     "registered" versions only) instead to control looping.
  
     The following code flashes (turns ON and OFF) a module addressed
     as A1  three times. It uses a variable (see Section - Variables)
     named "COUNTER" that is incremented and tested every time the
     loop is executed. When COUNTER reaches 3, the IF portion of the
     test is no longer true, so XA continues with the rest of the
     program:

        COUNTER = 0           # Declare and initialize COUNTER to 0
        :loop
        A1 ON
        A1 OFF
        COUNTER = COUNTER + 1
        IF (COUNTER < 3)
           GOTO :loop
        ENDIF
        :EXIT
        A1 OFF

     Note the special use of the :EXIT label in the above example. If
     the user pressed the <ESC> during execution inside the loop, XA
     would abort the loop and search for the :EXIT label. If found,
     XA would execute the "A1 OFF" statement ensuring that the module
     was in a known state. Without :EXIT, XA would abort and possibly
     leave A1 in  the ON state.

     By using the LABEL and GOTO constructs, you can produce some
     pretty sophisticated lighting displays.  One application where
     this could be put to use is for Christmas lighting.  Consider
     placing solid color Christmas tree light strands on individual
     lamp dimmers.  Vary the brightness levels of each strand for an
     everchanging lighting effect. See the sample file XMAS.CMD for
     an example.


  {GOSUB :label}
  (statements go here...)
  RETURN
     These statements instruct XA to jump to a sequence of commands
     identified by ":label" and begin executing them. XA continues
     executing all remaining statements until it reaches the "RETURN"
     token. XA then returns control of the program to the point from
     which it came. 

     If XA has encountered ":label" previously, it will immediately
     jump to that location. Otherwise, XA will begin searching for
     ":label" in the remaining portion of the current file, or within
     other files that  may have been "INCLUDED". 

     Placing a subroutine in a program allows you to repeat a
     sequence of statements in several places without writing the
     same statements several times.

     It is good practice to place subroutines in the beginning of the
     command file so that searching will be minimized. See the sample
     "XMAS.CMD" command file for an example. 

     XA may call subroutines that are present in the current file, or
     any previously "included" file. You may nest up to 20 subroutine
     levels.

     The previous "flash" example (using GOTO's) could be rewritten
     to use GOSUBS as follows:

        GOSUB :flash   # Once...
        GOSUB :flash   # ...Twice
        GOSUB :flash   #    ...Three times
        STOP            # Tell XA to stop (prevents running into subroutine)

        :flash         # Start of subroutine
         A1 ON
         A1 OFF
         RETURN         # Return to original caller

        :EXIT            # Special shutdown sequence...
        A1 OFF         # ...Ensure A1 is OFF


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

     FAST is best used in single command statements. If you attempt
     to send multiple direct commands using the FAST token, XA will
     be forced to wait for the acknowledgement message before issuing
     the remaining commands. 

     Some computers may experience problems when XA executes a single
     statement in a batch file using the FAST token. 
     
     
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 


  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 using HEXADECIMAL numbers, you must specify the H.  This is
        no longer implied.

      * 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
        

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


XA can read and write to most of the I/O ports. Of particular
interest is the Joystick or Game port. This port (location 201
Hex) provides up to four digital inputs. XA can read the state
of these ports and react accordingly. 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.


  {(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  you might possibly
inflict on you or your computer.  




Miscellaneous Tokens 


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

        "XMAS_ON" 

     to an equivalent group of tokens, such as:

        "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY" 

     as follows:

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

     Notice that the "x" portion uses underscore characters "_" to 
     separate the words but to keep the string contiguous.  This is
     important because the XA interpreter looks for the first SPACE
     character to separate the "x" and "z" components.  All
     subsequent SPACE characters are ignored.
  
     Later in the command file, you can use the following command to
     activate your Christmas lights:

        XMAS_ON

     Internally, XA will convert this string to its equivalent:

        HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY

     More Examples:

                 :
        DEFINE PLANT_GROW_LIGHTS A8
        DEFINE OUTSIDE_LIGHTS A1
        DEFINE ALL_ON ALL_LIGHTS_ON HOUSE A ON
                 :
        PLANT_GROW_LIGHTS ON TIME 6:00 AM EVERYDAY 
        PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY
                 :
        OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
                 :
        ALL_ON SUNDAY TIME 7:30 PM

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


  {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. 
     If you produced a report file while using the "-e" (no command
     execution), then the event number displayed will be -1,
     signifying that the event is not stored in the CP-290.  


  {CLEAR EVENT xxx}
     These tokens delete the specified event from the computer
     interface.  See description for EVENT xxx above. Only 1 event
     may be cleared per command.

        XA "CLEAR EVENT 100" "CLEAR EVENT 101" 

     When an event is cleared from the interface, the actual memory
     locations it occupied are cleared to zero.  All subsequent
     events remain in their assigned memory locations.  Use the
     report listing to display each events number (or location) in
     the CP-290. This number is printed in the right-most column of
     the report.  Any event numbers that are followed by an asterisk
     "*" indicate that the event  will be  triggered on multiple
     days.  


  ERASE
     This token erases all events from the CP-290 memory. If you use
     XA to maintain you CP-290 schedules, then this token should
     appear at the beginning of the command file. This is important
     because XA tries to append new events to the existing events in
     the CP-290.  If you do not erase the CP-290 memory, you will
     exceed its 128 event capacity.

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


  {BASECODE x}
     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"

     XA displays a bar graph during the upload and download phases
     providing a visual indication of progress, as well as the amount
     of available event storage.


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

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

        XACMD EVENTS.CMD

     Then each time XA is invoked without any arguments, the file
     "EVENTS.CMD" will be parsed and executed.  

     The following examples show how you can specify unique command
     files based on the day of the week (see later section for
     IF/ELSE programming):

        IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
           XACMD M_W_F.CMD
        ELSE
           XACMD XA.CMD
        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 >= DATE 8/21) AND (CDATE <= DATE 8/28))
           INCLUDE VACATION.CMD
        ENDIF


  {DOS command_string}
     The DOS token allows you to execute any DOS command from within
     XA.  The following line (taken from JOYSTICK.CMD) tells the
     SoundBlaster to play the GREETING.VOC file:

        DOS c:\sblaster\vplay c:\sblaster\greeting.voc

     Display a directory:
        
        DOS dir

     Use XA to kickoff a communications program at a precise time
     (see PHONE.CMD):

        # At 11:15, Call BBS...        
        DISPLAY OFF        
        :WAIT        
        IF (CTIME < TIME 11:15 PM)          
           GOTO :WAIT        
        ENDIF        

        DOS PROCOMM options...     # Invoke PROCOMM with command line    
                                   # parameters...

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


  {DISPLAY ON}
  {DISPLAY OFF}
     XA will display just about every statement as its parsed. There
     may be instances where you don't want the display active, for
     instance, parsing the XA.INI file, comments, or when critical
     loops are being  processed. XA allows you to control the display
     with the commands:

        DISPLAY ON              
        DISPLAY OFF

     In some instances, it will be necessary to turn the command
     display off because of time considerations. If you are in a
     tight loop monitoring an IO port for a bit to change, you may
     miss the toggle while XA is printing the current statement to
     the CRT. By turning the display off, you allow XA to execute
     much faster, virtually eliminating any bottlenecks that may
     cause XA to miss an event from the port.

     The sample XA.INI file shipped with this version has the display
     turned off at the start of the file, and restores the display at
     the  end of the file.


Reporting Tokens 


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



Powerfail Recovery 


Powerfail recovery allows you to restore each module to its
scheduled state. By default, XA uses the last 6 days to
determine the state.  You can tell XA to use additional 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.  

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:

        FORCE P_C ON


  {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


     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

        
Screen Color Control           ( ** Registered Version Only ** ) 


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

  {VIDEO1 Foreground Background}
     IF or ELSE evaluates to TRUE  

  {VIDEO2 Foreground Background}
     IF or ELSE evaluates to FALSE

  {VIDEO3 Foreground Background}
     Sending DIRECT commands to CP-290

  {VIDEO4 Foreground Background}
     Sending EVENTS to CP-290

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


10.  Programming Additions          ( ** Registered Version Only ** )


Variables


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

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

     vacation = WEEKEND

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

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

     DEFINE TRUE    1
     DEFINE FALSE   0        
     ATHOME = TRUE

First, we define constants TRUE and FALSE to be 1 and 0
respectively.  Next, we declare a variable called ATHOME.
Internally, the variable is created and initialized to 0. The
statement is parsed further, the assignment operator "=" sets
ATHOME equal to TRUE (or 1).

When declaring variable, the first character in its name should
begin with an ALPHA character, that is, A...Z. You can then use
numbers as part of the name, but they must not start the name.
All characters are  converted to UPPERCASE.  The list of legal
characters are:

     ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_



Examples:

     BIRTHDAY    <--- This is OK!
     1_BIRTHDAY  <--- Can't start with a numeric value        
     BIRTH,DAY   <--- Comma not a valid character

     
Hexadecimal Notation


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

  0 NNNNNNN H

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

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

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

  Example:

     IO 3E8H


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


Pre-Defined Variables:


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

  CDATE
     The current date (month-day-year).

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

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


     When comparing dates with CDATE, make sure you specify the DATE
     token:

        IF (CDATE == 12/25)      <--- This is WRONG!
        IF (CDATE == DATE 12/25)   <--- This is CORRECT!



  CDAY
     The current day of the week (MON, TUE, WED...)

     Internally, XA maintains the current day as an X10 bit-pattern,
     that is MON = 1, TUE = 2, WED = 4, ...SUN = 40Hex. The Day
     Tokens (MON, TUE... SUN) are also mapped to these values, so you
     can use them in conjunction with logical operations when
     determining special days. The file XMAS.CMD performs a test on
     CDAY to see if its FRI or SAT, thus allowing the Christmas
     lights to stay on longer:

        IF ((CDAY == FRI) OR (CDAY == SAT))
           IF (CTIME >= TIME 11:30 PM)
              GOTO EXIT
           ENDIF
        ELSE
           IF (CTIME >= TIME 10:30 PM)
              GOTO EXIT
           ENDIF
        ENDIF
        GOTO LOOP         # It's not time yet, repeat the loop.


  CTIME
     The current time (in 24-hour format)

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

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

Arithmetic Operators


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


Relational Operators


     Operator    Function 
     ========    =============================
        =        Assigns a value to a variable 
        <        Less than 
        >        Greater than 
        <=       Less than or equal 
        >=       Greater than or equal 
        <>       Not equal  
        ==       Equals (values match) 


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 


Truth Table for logical operators


        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 





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 


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.



11.  XA.INI - Initialization file 


XA supports the use of an initialization file called XA.INI. 
This file is intended to hold tokens and communication
parameters that you use regularly.  For instance, the following
tokens are ideal candidates for inclusion in the initialization
file:

  COMx           - Communication port
  IO x           - Special IO port address
  IRQ x          - Special IRQ level 
  DEFINE x y     - Place as many DEFINE statements as you want 
  LATITUDE dms   - The latitude of your city
  LONGITUDE dms  - The longitude of your city
  TIMEZONE x     - Your timezone
  DST            - If Daylight Savings is observed
  XACMD file     - The command file to use as a default

This file, always called XA.INI, is the very first file that the
XA parser looks for.  If it is found in the current directory
(or the directory specified by the XA environment variable - see
Installation) then the file is scanned for all tokens described
above. These tokens are then used to define modules or override
default communication parameters.

The following example is taken from the file XA.INI distributed
with this software.

     DEFINE P_C C1
     DEFINE DEN A5
     DEFINE GARAGE A1
        :
     LATITUDE 4135'
     LONGITUDE 8120'
     TIMEZONE 5 DST
        :
     COM3
     IRQ 5
     
Since XA.INI is always parsed, this allows you to send
descriptive X10 commands that don't rely on your memory for the
actual house and unit codes.  For instance:

     XA "DEN ON"

turns ON the unit at Housecode A Unit 5.

Do not place events or direct commands in this file, or they
will be executed every time you invoke XA.  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 appear in any column. Once XA sees the comment, the
rest of the line is ignored.  Therefore, comments can be placed
in front of tokens you do not want to be parsed by the
interpreter at this time

     # This is an example comment. Place them after statements too:
     LATITUDE  4135'          # Latitude of Mentor, OH.

When creating this file, use an editor or word processor that
stores its files in pure ascii format.  Otherwise the formatting
characters that the word processor embeds within the file will
confuse the XA parser.

The token XACMD specifies the default command file that should
be executed if no direct command was included at the DOS prompt.
 The next section describes what command files are and how they
are used with XA.




12.  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 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.  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 command files
or commands passed as arguments to XA on the DOS command line -
NOT  BOTH.  With version 2.0, you can execute both types at the
same time, however the file must be specified using the
"f=filename" syntax.  This is very useful when you want to pass
a variable to a command file (Registered version only). For
example, suppose your normal command file (XA.CMD) contains
special lighting events that you activate when you plan on
vacationing for the weekend:

  XA.CMD:
     # Normal Events...
     GARAGE ON SUNSET WEEKDAYS
        ...
     # Special Vacation Events...
     if (vacation)
        HALLWAY ON TIME 9:30 PM WEEKENDS SECURITY
        HALLWAY OFF TIME 11:30 WEEKENDS RANDOM 10
        STEREO ON TIME 3:30 PM WEEKENDS RANDOM 15
        STEREO OFF TIME 11:15 PM WEEKENDS RANDOM 5
     endif


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

     XA f=XA.CMD "VACATION = 1"



13.  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 (including 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 intialization file.  If your
computer communicates with the CP-290 via COM3 serial port, then
you may place the token "COM3" within the XA.INI too.  XA always
looks at  this file before attempting any communication with the
CP-290.  Other tokens that XA looks for are:

     IRQ, IO, LATITUDE, LONGITUDE, TIMEZONE, DST, XACMD, DEFINE, COMx

After parsing the XA.INI file, XA then looks to see if the
"f=filename" option was specified on the command line. This
allows you to override the default command file you may have
specified by using the XACMD token in the XA.INI file.  Next,
the command line options are scanned. Any options defined here
will override all previous options declared 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.



14.  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 DEFINE must include
both the HOUSE and UNIT tokens when  describing a module.  You
should not use the short cut method, such as:

     DEFINE Porch_Lights A 1             <=== will NOT work.
     DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.  

The "Event" column displays the actual location of the event in
the CP-290's memory.  Event locations range anywhere from 0 to
127.  Use  this information if you want to CLEAR an event from
the CP-290  interface (see EVENT, and CLEAR EVENT).  If you
specify the '-e' command line option, then the events will not
be downloaded, and all  event numbers will be set to -1.  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.



  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.


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

        


15.  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 as well as 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 -e

In the first example, XA "MONITOR",  the command "MONITOR"
informs XA to watch for any transmissions from the CP-290.  The
second example uses command line options and has the same
effect, but remember that if no commands were actually present,
the XA utility will try to open the default command file and
process the commands found in there.  If you don't want that to
happen, use the "-e" option which tells XA not to execute (or
download) those commands.

When XA begins to monitor, it displays the following message:

     Monitor events.  Press <ESC> when finished...

XA then waits for messages from the CP-290.  You may exit this
function by pressing the <ESC> key.

When the CP-290 executes an event, it sends a message to the PC
with the following information; the HOUSE code, UNIT code, and
the event FUNCTION (ON, OFF, DIM).  XA takes this information
and adds the time and date information from your PC's clock and
prints the following  message to the monitor:

     Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON

This message is semi-useful; it describes what just occurred but
if you forgot what was addressed as HOUSE A UNIT 5 then the
message is meaningless.  You can give this module a more
descriptive name by using a command file that includes DEFINE
statements for all your modules.  Below is sample command file
(MONITOR.CMD - supplied with  this package) that describes what
we're talking about:

     DEFINE Porch/Garage_Lights HOUSE A UNIT 1
     DEFINE Plant_Grow_Lights HOUSE A UNIT 5
     DEFINE Family_Room_TV HOUSE A UNIT 6
     DEFINE Basement_Computer HOUSE A UNIT 7

Now when a message is sent by the CP-290, a scan of all the
definitions will be made to see if the HOUSE and UNIT codes
match. If 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

In the above messages, a combined House and Unit code (A6) is
automatically provided, you don't have to include it as part of
the DEFINE token.

Also, the DEFINE must include both the HOUSE and UNIT tokens
when describing an object.  You can not use the short cut
method, such as:

     DEFINE Porch_Lights A 1             <=== will NOT work.
     DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.

If different modules are controlled by a single event, the
module which has the lowest UNIT code will be displayed.
Therefore, if modules C9 and C10 are programmed as a single
event, only C9 will be displayed.  

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.




16.  POWERUP Utility 


The POWERUP utility is provided in this package to help you
perform unattended, automatic, event downloads to the CP-290 if
your computer is controlled by an Appliance module.  POWERUP
should be placed in your AUTOEXEC.BAT file so it will always be
executed after your computer boots.  This way, it can decide
whether or not it's time to perform any updates to your
interface, and it prevents you from needlessly sending commands
when you don't need to.

The POWERUP command has the following form:

     POWERUP d=day [[d=day]...] [w=1,2,3,4,5] s=hh:mm e=hh:mm

The command line parameters may appear in any order, and they
must all be present (except for "w="):

  d=day
     This is the text string for the day you want to check for. 
     Legal strings are:

        MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, 
        WEEKDAYS, WEEKDAY, WEEKENDS, WEEKEND, EVERYDAY.

  [w=week]
     This optional argument allows you to optionally specify the week
     of the month you want POWERUP to check for. For instance, to
     have POWERUP check for the 3rd SUNDAY of the month, specify:

        POWERUP d=SUNDAY w=3 s=2:55 e=3:05

     You may not specify multiple weeks, however the default
     condition (not specifying the w= command) will still check every
     week.

  s=hh:mm
     This is the "window" start time.  Hours must be entered in 24
     hour format only.

  e=hh:mm
     This is the "window" end time.  (24 hr format). For example:

        POWERUP d=SUNDAY s=2:55 e=3:05

     If the "day" specified matches the day reported by DOS, and the
     time reported by DOS falls within the specified "window", then
     POWERUP will return an ERRORLEVEL of 1, otherwise a 0 is
     returned. Therefore, by placing the proper batch file commands
     in AUTOEXEC.BAT, you can now execute a variety of functions at
     certain times.
     
     You may enter multiple 'd=day' parameters.  For instance, to
     have Powerup check for a window beginning at NOON and lasting
     until 1:00 pm every MONDAY, WEDNESDAY, and FRIDAY, you would
     enter:
     
        POWERUP d=MONDAY d=WEDNESDAY d=FRIDAY s=12:00 e=13:00
        if errorlevel == 1 echo It's time!

If your computer is controlled by an Appliance module, you can
now automatically download revised event times.  See the sample
AUTOEXEC.BAT file included in this package.


17.  FINDX10.EXE 


A new utility has been added to help determine the configuration
of the serial port the CP-290 is connected to. After searching
all ports in your system, FINDX10 determines the IRQ of the port
and attempts to communicate with the CP-290. If it finds the
CP-290, it displays the port setup and prompts you if it is OK
to save the data in your XA.INI file.  If you select 'Y', the IO
address and the IRQ level tokens are placed at the end of your
XA.INI file.

Because of the wide variety of hardware in use, FINDX10 may not
be able to locate the CP-290.



18.  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 1.2) now comes with utility package called XTS.EXE. 
XTS has direct access to XT's database of 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) 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".  This function analyzes all events
stored in the CP-290 and sets each module to its proper state
based on this information.  This feature can be activated during
program installation, or whenever the menu is displayed.  


Other Information


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

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

There is a charge for Steves paper. You may contact Steve via:
     Steve Mueller
     Silicon Valley Video Group
     335 Bodega Way
     San Jose, CA. 95119-1603

     or via Prodigy - SJCR28A




19.  Acknowledgements 


I would like to thank the following people for their help in
making XA a better program. The beta testers - Dave Mabry, Ed
Christie, David Huras, Nira Johnson.  Also, my thanks to Arnold
Sprague for proofreading the documentation.  Finally, to all the
folks who have taken the time to register this program and offer
suggestions.


20.  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, its utilities and this document is
Copyright (C) 1991-1993 by Bruce Christensen. All rights
reserved. 

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

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

Please feel free to distribute this SHAREWARE version as often
as you like, to any interested parties.

Please do not distribute this program without all of its
original related files, addendum files, documentation and this
notice.

Please do not alter the program or documentation in any manner.

DISTRIBUTION of the REGISTERED USER version of the program is in
violation of license agreements and copyright Law!



Registration


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

The registered version of XA and its utilities are licensed for
individual personal use for an unlimited time.

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

     Bruce Christensen
     6594 Hudson Avenue
     Mentor, OH.  44060-4545


     Prodigy ID:  MHNC39A
     America On-line: AuggieBen
     Internet: auggieben@aol.com 



Future Updates


Future updates of the shareware version XA can be found on these
BBS's as they become available. The current version of XA will
be named "X10XA200.ZIP". The last 3 digits of the filename will
indicate the revision level (in this case, 2.00).

Dave Mabry, a sysop of the "Going Down BBS" has offered free
access to his BBS to anyone interested in X10 - Home Automation.
You will be granted access once you have completed a short
questionnaire.  The new user password is currently "DRYSUIT".
This BBS can be reached at:  1-(313)-576-7882.

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

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






X-10 is a registered trademark of X-10 (USA) Inc.

Prodigy is a registered service mark and trademark of Prodigy
  Services Co.

America On-line is a registered service mark of Quantum Computer
  Services, Inc. 



Appendix A. Tokens - Quick Reference


Action tokens


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

Module address tokens


  A1...P16
  HOUSE A...P
  UNIT 1...16
  UNIT ALL

  
Coordinate tokens


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


Clock tokens


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


Day tokens

  
  SUNDAY, SUN - Specific day for event to occur
  MONDAY, MON -    "
  TUESDAY, TUE -   "
  WEDNESDAY, WED - "
  THURSDAY, THU -  "   
  FRIDAY, FRI -    "   
  SATURDAY, SAT -  "
  EVERYDAY - Event occurs everyday
  TODAY - Event occurs once today only
  TOMORROW - Event occurs once tomorrow only
  WEEKDAY, WEEKDAYS - Event occurs only on weekdays
  WEEKEND, WEEKENDS - Event occurs only on weekends  
  
  
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 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 mm/dd/yyyy (SUNDAY...SATURDAY)} - 
        Event does NOT occur between two dates
  {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT mm/dd/yyyy THRU mm/dd/yyyy} -
        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   
  {DEFINE x z}      - Substitute string 'x' for 'z'
  {XACMD file.cmd} - Specify default command file.
  {INCLUDE filenme} - Specify another file to parse.   
  {CLEAR EVENT xxx} - Clear event xxx from CP-290 memory
  ERASE - Erase ALL events from CP-290 memory
  {EVENT xxx} - Place event xxx in a known location of CP-290 memory
  BEEP - Causes PC speaker to beep.
  {DOS command} - Shell to DOS
  {DISPLAY ON/OFF} - Turn XA output display on or off.
  DIAGNOSE - CP-290 performs internal diagnostics. 


Reporting tokens


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


Direct Command Control Tokens


  :LABEL - Identify an area to "goto/gosub" later.
  {GOTO label } - Jump to location identified by "label".
  {GOSUB label} - Execute subroutine identified by "label". Upon
        returning, continue with the rest of the cmd file.
  RETURN - from subroutine (used with GOSUB).
  STOP - Force XA to stop execution
  :EXIT - Special shutdown location jumped to when <ESC> pressed.
  {DELAY hh:mm:ss} - Wait for time to pass before executing the
        next cmd.
  PAUSE - Halt execution of direct commands until key pressed,
        then reset internal timer and resume direct commands. 
  {TIMER hh:mm:ss} - 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              ( ** Registered Version Only **) 


  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                 ( ** Registered Version Only ** ) 


  *   Multiply      A = B * C
  /   Divide      B = A / C
  +   Addition   C = A + B
  -   Subtraction   A = C - B
  -   Unary minus   A = -B



Relational Operators                 ( ** Registered Version Only ** ) 


  =   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                   ( ** Registered Version Only ** ) 


  AND  Logical AND
  &&   Logical AND
  OR   Logical OR
  ||   Logical OR
  !    NOT

Bitwise Logical Operators             ( ** Registered Version Only ** ) 


  &   Bit "AND"
  |   Bit "OR"


Screen Color Control                 ( ** Registered Version Only ** ) 


  {VIDEO1 Foreground Background} - IF or ELSE evaluates to TRUE
  {VIDEO2 Foreground Background} - IF or ELSE evaluates to FALSE
  {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-290
  {VIDEO4 Foreground Background} - Sending EVENTS to CP-290

  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                    ( ** Registered Version Only ** ) 


  {(variable =) INPORT io_port} - read status of port
  {OUTPORT io_port value} - output value to port


Pre-defined Variables


  CDAY - The current day
  CTIME - The current time
  CDATE - The current date


Powerfail Recovery module status overrides 


  {IGNORE HOUSE UNIT} - Leave module in its present state
  {FORCE HOUSE-UNIT state} - Force module to ON, OFF, DIM state



Appendix B. Returned Error Codes 


The following is a list of Error messages that XA may generate.
Also included is a specific error code that XA returns when it
is finished. These error codes may be examined using ERRORLEVEL 
parameter in batch files.

Code: 0   "Completed OK."
           Normal operation, XA ran successfully.

Code: 1   "No commands to execute."
           The "-e" command line option was used, preventing any commands
           or events to be sent to the CP-290. Note that a report file
           (XA.RPT) may have been generated, however the X10.DAT file was
           not updated.

Code: 2   "Timeout occurred. Check your cables."
           First, make sure the CP-290 is connected to the correct serial
           port. Also, make sure you are using the proper communication
           settings.

Code: 3   "Illegal comm port - Use 1...4."
           Use i=1...4 only!

Code: 4   "Timeout occurred or interface defective."
           XA waited for the CP-290 to return a status code after
           initiating it's internal diagnostics. First, check to see if the
           CP-290 is properly connected to the PC. If the connection is OK,
           then the CP-290 may be defective. All events stored in the
           CP-290 have been deleted.

Code: 5   "Interface FAILED diagnostic."
           The CP-290 has failed its internal diagnostics. All events
           stored in the CP-290 have been deleted.

Code: 6   "XA.EXE is corrupt."
           XA has detected a change in its internal code. This may be the
           result of a possible virus, or other problem with the file.
           Re-install XA from the distribution diskette.

Code: 7   "Timeout occurred. Check cable, irq, and i_o settings."
           First, make sure the CP-290 is connected to the correct serial
           port. Also, make sure you are using the proper communication
           settings.  This type of problem is usually caused by specifying
           an improper interrupt vector. Run the utility FINDX10.EXE to
           assist you in determining the proper configuration of your
           serial port.

Code: 8    (No error assigned) 

Code: 9   "Not enough memory."
           XA reserves memory for "variable" storage, "define" statements,
           "labels" (for GOTO/GOSUB), and "include" filenames. When this
           error occurs, try reducing these statements. 

Code: 10   "<ESC> key pressed. Exiting..."
           XA was aborted due to operator intervention. A file may not have
           been downloaded to the CP-290 properly.

Code: 11   "XA internal date stack overflow."
           More than 100 dates were specified in a single statement. 
           Reduce the number of dates, or use DATE ... THRU.

Code: 12   "XA internal date stack underflow."
           Try rewriting statement, contact author.

Code: 13   "XA internal stack overflow."
           More than 100 tokens were specified in a single statement.
           Reduce complexity of statement. 

Code: 14   "XA internal stack underflow."
           Try rewriting statement, contact author.

Code: 15   "XA internal gosub stack overflow."
           Too many levels of subroutines called. Rewrite your command
           files. 

Code: 16   "XA internal gosub underflow."
           Try rewriting statement, contact author.

Code: 17   "Not enough FILE handles, or file not found."
           An attempt was made to read or write to a file. The file could
           not opened because it:               
              1) does not exist, 
              2) you need to increase the number of files that can be opened.
           See DOS manual -          
              command: FILES=??? (normally in your  CONFIG.SYS).

Code: 18   "XA internal except date stack overflow."
           More than 100 "EXCEPT" dates were specified in a single
           statement. Reduce the number of dates, or use DATE ... THRU.

Code: 19   "XA internal except date stack underflow."
           Try rewriting statement, contact author.


Appendix C. Passing arguments to your command file.


By default, XA will only accept input from either the DOS
command line (ie, commands enclosed in "parentheses"), or via a
file.

     XA "P1 OFF"   <=== DOS command line arguments.
     XA F=XA.CMD   <=== XA Command File.

You may now override this feature and have XA interpret commands
from the DOS command line as well as a file by using the
following format:

     XA "command" f=file.cmd   -or- 
     XA f=file.cmd "command"   (The order is not important).
     XA "P1 OFF" f=XA.CMD

This form of operation is very useful if you wish to pass
special arguments into your command file and allow XA to
activate special sequences. Your normal command file (XA.CMD)
could contain some special commands that are only activated when
you define a variable to be a certain value. The following
sample code is included in the SPECIAL.CMD file and 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"



Appendix D. 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):

 * Run "Program Manger"

 * In the MAIN group, run "Control Panel"

 * Run "Ports"

 * Select the COM port that the CP-290 is connected to. This should
   match the COM token in you XA.INI file. Press "Settings".

 * Set the Baud Rate to 600, Data Bits to 8, Parity to None, Stop 
   Bits to 1, and Flow Control to None.

 * 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".

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



Appendix E. Updating from Version 1.07b to 2.00 


There are a few differences with some of the commands in this 
version. 

 * GOTO label "x_times"  is no longer supported.  You may either
   use GOSUBS, or condition statements and counters.

 * TIMEZONE changes.  Use DST in conjunction with your "Standard
   Time" timezone. 

 * DELAY hh:mm:ss  (not DELAY mm:ss)

 * TIMER mm:ss.hs  Place action tokens before the TIMER tokens:
     A1 ON TIMER 0:20.5 
     TIMER 0:20.5 A1 ON     <--- Not this way

 * DEFINES must be declared prior to their usage in a command.  XA
   is no longer a multi-pass parser.

 * X10DAT is no longer supported. The file X10.DAT is always 
   created.

 * ADJUST token is no longer supported.
