











      
      XA
      X10 Command Interpreter
      Version 2.1 - January, 1994
      Copyright 1991-1994 by Bruce Christensen. All Rights Reserved.
      

      1. Shareware ..................................................  1 
      2. Introduction ...............................................  1 
         What is XA? ................................................  1 
         Registered vs. Shareware ...................................  2 
      3. Summary of NEW Features for Version 2.01 ...................  3
         Other Features .............................................  5 
         Miscellaneous Features .....................................  5 
      4. Utilities supplied with XA .................................  6 
      5. Installation ...............................................  7 
      6. Getting Started ............................................  8 
      7. XA Syntax and Command Line Arguments ....................... 10 
      8. XA Tokens .................................................. 14 
         What are tokens? ........................................... 14 
      9. Tokens in Detail ........................................... 15 
         Action Tokens .............................................. 15 
         Module Address Tokens ...................................... 16 
         Coordinate Tokens .......................................... 17 
         Clock Tokens ............................................... 19 
         Day Tokens ................................................. 20 
         Specific Date Tokens ....................................... 21 
         Time Tokens ................................................ 24 
         Direct Command Control Tokens .............................. 27 
         Communications Tokens ...................................... 31
         I/O Port Control ........( ** Registered Version Only ** ).. 32 
         Miscellaneous Tokens ....................................... 33
         Reporting Tokens ........................................... 37
         Powerfail Recovery ......................................... 38
         Screen Color Control ....................................... 40
     10. Programming Additions ...( ** Registered Version Only ** ).. 41
         Variables .................................................. 41 
         Hexadecimal Notation ....................................... 42 
         Pre-Defined Variables ...................................... 42 
         Operators .................................................. 44
     11. XA.INI - Initialization file ............................... 46 
     12. Command Files .............................................. 47 
     13. Initialization file, Command files, Command Line Options ... 49 
     14. Report Files ............................................... 50
         Report Style 1 - Sort by Day and Time ...................... 51
         Report Style 2 - Sort by Day, Module, and Time ............. 52
     15. Monitoring and Logging events .............................. 53
     16. POWERUP Utility ............................................ 55
     17. FINDX10.EXE ................................................ 56
     18. Other Programs and X10 Information ......................... 56 
         XT - Memory Resident Software for the CP-290 ............... 56 
         Other Information .......................................... 57 
     19. Acknowledgements ........................................... 57
     20. Warranty, Copyright, and Registration Policy ............... 58
         Registration ............................................... 59 
         Future Updates ............................................. 59 
     Appendix A. Tokens - Quick Reference ........................... 60 
     Appendix B. Returned Error Codes ............................... 64
     Appendix C. Passing arguments to your command file ............. 66
     Appendix D. Running XA in Windows .............................. 67
     Appendix E. Updating from Version 1.07b to 2.01 ................ 68


                XA - X10 Command Interpreter - Version 2.1                   1  
      
      
      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 "Warranty,
      Copyright, and Registration Policy" 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


                XA - X10 Command Interpreter - Version 2.1                   2  
      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.01.  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.
      
                XA - X10 Command Interpreter - Version 2.1                   3  
      
      3.   Summary of NEW Features for Version 2.00 and 2.01
      
      
      XA Version 2.00 has been completely rewritten, allowing such
      features as conditional statements, operators, and
      user-variables to be supported.  Also, XA performs sun-related
      calculations much faster.  The following list highlights the
      major enhancements of Version 2.01.  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, Boolean 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).
      

                XA - X10 Command Interpreter - Version 2.1                   4  
      * 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.
        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 or when event dates fall within the specified range.
        You may also 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.
      

                XA - X10 Command Interpreter - Version 2.1                   5  
      Other Features
      
      
      - Supports COM1...COM4  (Interrupt-driven or Polling)
        Fully configurable communications. COM1...COM4. Interrupt driven
        or polling.
      
      - SUNRISE-SUNSET calculations
        XA calculates precise sunrise/sunset times for your location
        based on the latitude and longitude of your city.
      
      - Specific DATE handling
        Request any event to occur days, months, even years from now. XA
        expands X10's time base by allowing you to program an event for
        any day in the future, or you can schedule an event to occur
        between two defined dates. You can also program modules to NOT
        activate on certain dates.
      
      - Time synchronization
        XA can keep the internal clocks of your PC and CP-290 accurate
        to within 1 second of each other.  You can set either clock
        based on the time maintained by the other clock.
      
      Miscellaneous Features
      
      
      - 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.
      

                XA - X10 Command Interpreter - Version 2.1                   6  
      
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   7  
      
      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.
      
      Important Note:
      
      Please read the file READ.ME that was distributed on this floppy
      disk (or compressed archive). This file contains any last minute
      information that was not included in the printed documentation
      (or XA_201.TXT file).
      

                XA - X10 Command Interpreter - Version 2.1                   8  
      
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   9  
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   10 
      
      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"
      
      

                XA - X10 Command Interpreter - Version 2.1                   11 
      [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
      

                XA - X10 Command Interpreter - Version 2.1                   12 
      
      [i=irq#]
      
        Interrupt-driven: i=(3,4,5...).  For polling, use: i=0
        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.
      
        If the token XACMD appears in your XA.INI file, or you specifed
        a command file with f=file.cmd, then monitoring occurs after the
        command file has been parsed.  To skip parsing of the command
        file, you can use the "monitor" token instead:
      
              XA "monitor"
      
        See also:
           Reporting tokens: MONITOR
           "Monitoring and Logging Events"
      
      
      [+l]
      
        This option will append any monitoring information to the file
        XA.LOG.  The report file will be saved on the same drive and
        directory as was specified by the XA environment variable
        (discussed  in "Installation").
      
        See also:
           Reporting tokens: LOG
           "Monitoring and Logging Events"
      
      
      [+r1]
      
        This option will produce a report file (called XA.RPT) of all
        events that were just processed by the interpreter.  The format
        of the report contains a sorted list of events (based on time)
        for each day of the week.
      
        See also:
           Reporting tokens: REPORT1
           "Report Files"
      
      

                XA - X10 Command Interpreter - Version 2.1                   13 
      [+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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   14 
      
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   15 
      
      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"
      
      

                XA - X10 Command Interpreter - Version 2.1                   16 
      {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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   17 
      {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.
      

                XA - X10 Command Interpreter - Version 2.1                   18 
      {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
      
      

                XA - X10 Command Interpreter - Version 2.1                   19 
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   20 
      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.
      
      
      

                XA - X10 Command Interpreter - Version 2.1                   21 
        Notes:
           * If you leave off a DAY token when downloading an event to the
             CP-290, XA will assign the command as a TODAY-only event.
             Therefore, at midnight the event will be cleared from the
             CP-290's memory. The following command will take place at 11:00
             tonight and be deleted at midnight since it was given "TODAY"
             status (no other DAY was specified):
      
                 XA "FAN ON TIME 11:00 PM"
      
           * Registered Users - Using the "CDAY" token in conjunction with
             "SAT,SUN MON, TUE, WED, THU, FRI, WEEKEND, WEEKDAY" tokens
             allows you to program special functions based on the current
             day. For example, the statements below will the initialize the
             default command file (using XACMD) based on the current day.
             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.
      
        * XA makes use of screen color control (see VIDEO) to show you if
          scheduled event meets date criterion.
      
      To guarantee that specific dates will be evaluated and events
      will be triggered at the proper time in the future, plug your
      computer into an Appliance module and have the CP-290 turn your
      computer on automatically on a once-per-week basis.  By using
      XA.EXE in conjunction with POWERUP.EXE (supplied with this
      package) you can have a new set of events automatically
      downloaded to the CP-290.  Now you'll never forget to update
      your CP-290, your computer  does it for you automatically.  This
      is what "automation" is all about.  See  section "Powerup" for
      more details.


                XA - X10 Command Interpreter - Version 2.1                   22 
      
      When using the following "DATE" tokens, you should include the
      "ERASE" token at the beginning of your command file.  ERASE will
      clear the entire contents of the CP-290, removing all event
      information. The reason you want to erase its memory is because
      once XA downloads an event to the CP-290, it will remain there
      until it is deleted or overwritten.  The next time XA is run
      (next week) the event may still remain and trigger itself again
      and again until it is either manually deleted, or eventually
      overwritten by a new event. ERASE ensures that the data is
      cleared and that the interface will contain fresh information.
      Also, since all your information is stored in a command file,
      the relevant information will always be placed in the CP-290.
      
      
      {DATE mm/dd/yyyy}
      
        Event occurs on specified date.  You must specify the date in
        the following format:
      
           Month - none, 1, or 2 digits (1 = Jan ...  12 = Dec)
           Day   - none, 1, or 2 digits
           Year  - none, 2, or 4 digits
      
        To specify module A5 ON July 4, 1994 at 5:00 pm:
      
              A5 ON DATE 7/4/1994 TIME 5:00 PM
      
        You may omit fields which is the equivalent of specifying any
        month, day, or year.  Each field must be delineated by a
        separator, either a '/' or '-' character.   For example, to
        specify module A5 to turn OFF on the 4th of every month at 6:00 AM:
      
              DATE /4/ A5 OFF TIME 6:00 AM
      
        To specify module A5 to turn ON every 4th of July at sunset,
        leave off the "yyyy" field:
      
              DATE 7/4/ A5 ON SUNSET
      
        An exception to the separator requirement arises when the "yyyy"
        is not being programmed -simply omit the '/' or '-' character
        between the "dd" and "yyyy" fields. The above statement could be
        written as:
      
              DATE 7/4 A5 ON SUNSET
      
        You may specify multiple dates in the same command:
      
              DATE 7/4 DATE 7/6 DATE 7/8 A5 ON SUNSET
      
      

                XA - X10 Command Interpreter - Version 2.1                   23 
      {DATE mm/dd/yyyy THRU [DATE] 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 Thanksgiving
        and New Years Eve, turn them OFF at 10:00PM on weekdays, and
        turn them off at 11:30 during the weekends:
      
              DEFINE THANKSGIVING DATE 11/24/94
              DEFINE NEW_YEARS_EVE DATE 12/31/95
              THANKSGIVING THRU NEW_YEARS_EVE  XMAS ON SUNSET
              THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 10:00 PM WEEKDAYS
              THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 11:30 PM WEEKENDS
      
      EXCEPT
      
        Once XA parses this token, any DATE (or DATE...THRU) statements
        become "exceptions", that is, events will not be scheduled to
        activate during that date (or period). For example, to turn a
        lamp (A7) on every weeknight except Memorial Day:
      
              A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31
      
        You may specify multiple exception dates in the same command:
      
              A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1
      
      
        Notes:
           *  Events that are not downloaded because they do not meet the
              range criteria will be displayed using the VIDEO2 screen
              attributes (to signify a FALSE condition).
      
      
              Use the format:
           *  {EXCEPT DATE mm/dd/yyyy THRU [DATE] mm/dd/yyyy (DAY)}
      
              to  prevent an event from occurring between two dates. EVERYDAY
              will be assumed unless you place specific DAY tokens within the
              command.  For example, to prevent the porch lights from coming
              on while your Christmas lights are on:
      
                 PORCH ON SUNSET EXCEPT DATE 12/1/1994 THRU 1/1/1995
      
              Special Note: When dates "rollover" into the next year, you must
              specify the "year" within the date statement (as in the above
              example).
      

                XA - X10 Command Interpreter - Version 2.1                   24 
           Use the format:
           *  {DATE mm/dd/yy THRU [DATE]  mm/dd/yy EXCEPT DATE mm/dd/yy THRU
               [DATE] mm/dd/yy}
      
              to specify a range of dates that a module should not activate,
              within a range of dates that it should be activated.  For
              instance, turn on deck lights only during the summer, except
              while you are on vacation:
      
                 DECK ON SUNSET DATE 6/21 THRU 9/22 EXCEPT DATE 7/1 THRU 7/14
      
      
      Time Tokens
      
      
      Use of these tokens indicate a timed event, i.e., the complete
      command will be downloaded to the interface and stored there for
      later activation.
      
      {TIME hh:mm (AM/PM)}
      
        Schedule event at a certain time.
      
              XA "D1 ON SUNDAY TIME 12:30 AM"
      
        AM is the default. You may specify military-style time as
        follows:
      
              XA "D1 ON SUNDAY TIME 23:34 "
      
      
      SUNRISE
      SUNSET
      
        These tokens will calculate the sunrise or sunset for the day
        token in the command.  The use of these tokens also requires the
        LATITUDE, LONGITUDE, and TIMEZONE (and optional DST) tokens to
        be included in  the XA.INI file.
      
              D1 ON MONDAY SUNSET
      
        If multiple day tokens appear in the command line, the sunrise
        or sunset time will be the average sunrise/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
      
      

                XA - X10 Command Interpreter - Version 2.1                   25 
      {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 CP-290 turn it off 14 hrs later
      
        Earlier versions of XA required the use of the EVENT token in
        order to prevent overwriting existing events in the CP-290's
        memory.  XA Version 2.00 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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   26 
      {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 on either
        side of SUNSET:
      
                                       # Sunset @ 9:00 PM
              SUNSET RANDOM 1:30      # TIME ranges between 7:30 PM ... 10:30 PM
      
        RANDOM, as well as OFFSET, will automatically change the day if
        the adjustment causes a rollover into the previous or next day.
      
      
      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"
      
      

                XA - X10 Command Interpreter - Version 2.1                   27 
      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 hh:mm:ss.s
      
        This token informs XA to issue a command when the internal timer
        reaches "hh:mm:ss.s".  The built-in timer is initialized to 0
        when XA is invoked, or whenever a key press follows a PAUSE
        command, or when the token "RESET" is parsed. All subsequent
        TIMER commands are evaluated from the point at which the
        internal timer was initialized.
      
        One very useful application of the PAUSE and TIMER commands is
        to synchronize X10-controlled lighting sequences with
        pre-recorded  music.  For instance, you could assign each song
        its own command  file.  Each file would start off with a PAUSE
        (Registered version may use INPORT) token to intialize the
        timer, as well as provide a means to start the music and command
        chain from a common point.  TIMER statements would specify the
        exact times that the CP-290 would trigger an X10 command at an
        appropriate moment in the song.
      
              PAUSE                   # Wait for any key press, reset timer
              A1 ON TIMER 0:0:10.0    # At 10 seconds, turn on A1
              A1 DIM 0 TIMER 0:0:20.5 # At 20.5 seconds, fade light out.
      
        In this example, the PAUSE waits for a cue to start the
        sequence. 10 seconds later, A1 is activated. 20.5 seconds after
        the cue, A1 is DIMMED to a level 0.
      
        XA will automatically anticipate and adjust for any delays that
        may be caused by the CP-290.  For instance,  the amount of time
        it takes to turn on a lamp may take as much as 1.4 seconds. Even
        worse, the CP-290 forces a lamp module to go to the fully BRIGHT
        state before allowing the module to be dimmed - delaying the
        actual effect by 6 seconds.  In order to have XA compensate for
        these delays, you should place an X10 command on the same line
        just prior to the timer command.  For example, the following
        line turns the lamp on after 7 seconds. However, XA actually
        issues the command at 5.6 seconds:


                XA - X10 Command Interpreter - Version 2.1                   28 
      
              A1 ON TIMER 0:0:7.0
      
        Likewise, to completely dim a module to 0% after 10 seconds, XA
        will begin issuing the command after approximately 4 seconds
        have elapsed.
      
              A1 DIM 0 TIMER 0:0:10.0
      
        If no commands are programmed on the same line as the TIMER
        statement, then a default adjustment of 1.4 seconds will be used
        for  commands that appear later.
      
        It is very important that you program the 'hour' and 'minute'
        fields, even if they are zero. Otherwise, XA will convert the
        'seconds' field to minutes, and you'll be waiting a long time.
        For example, do this:
      
              TIMER 0:0:15.5   <--- Do this
              TIMER 15.5      <--- NOT this
      
      
      RESET
      
        When the RESET token is parsed, the internal timer 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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   29 
      :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
      

                XA - X10 Command Interpreter - Version 2.1                   30 
        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
      

                XA - X10 Command Interpreter - Version 2.1                   31 
      FAST
      
        By default, XA always waits for an acknowledgement message from
        the CP-290 after sending a direct command. You can avoid this
        wait and speed up the overall execution of XA by including the
        token "FAST" in your command:
      
              XA "PHONE_IN_USE  ON  FAST"
      
        FAST is best used in single command statements. If you attempt
        to send multiple direct commands using the FAST token, XA will
        be forced to wait for the acknowledgement message before issuing
        the remaining commands.
      
        Some computers may experience problems when XA executes a single
        statement in a batch file using the FAST token. Avoid using the
        FAST token when the TSR program "XT.EXE" is installed.  In some
        instances, XA may restore the old communication interrupt
        vectors while the acknowledgement message is in transit from the
        CP-290. This may result in XT reading an incomplete message.  It
        may take several messages for XT to correct itself.  You should
        experiment with your computer to see if this affects your setup.
      
      
      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
      
      
      XA was designed to work using interrupt-driven communications
      allowing features such as "monitoring" to operate effectively.
      Since some users are unable to dedicate a unique IRQ for the
      CP-290 serial port, XA can be configured to to communicate in a
      "polled" fashion. Simply use the "i=0" command line option or
      "IRQ 0" statement in your XA.INI file.
      
      

                XA - X10 Command Interpreter - Version 2.1                   32 
      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
      
        Use IRQ 0  for "polling mode" communications if you can't
        configure your system with a free IRQ for the CP-290 port. Note
        that operations such as Monitoring and Logging may not operate
        correctly in polled mode.
      
      
      I/O Port Control             ( ** Registered Version Only ** )
      
      
      XA can read and write to most of the I/O ports. Of particular
      interest is the Joystick or Game port. This port (location 201
      Hex) provides up to four digital inputs. XA can read the state
      of these ports and react accordingly. 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.
      

                XA - X10 Command Interpreter - Version 2.1                   33 
      {(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.
      

                XA - X10 Command Interpreter - Version 2.1                   34 
        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.
      

                XA - X10 Command Interpreter - Version 2.1                   35 
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   36 
        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...
      
      

                XA - X10 Command Interpreter - Version 2.1                   37 
      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.
      
        "Monitor" and its command line counterpart "+m" may operate
        differently based on your XA configuration.  See section -
        "Monitoring and Logging Events" for more information.
      
      
      LOG
      
        This token appends the monitored information in the file XA.LOG.
      
      
      REPORT1
      
        This token will produce a report file with events sorted by day
        and  time.
      
      

                XA - X10 Command Interpreter - Version 2.1                   38 
      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.
      
      Use the command line option "-e" in conjunction with powerfail
      recovery to see how XA would have restored each module without
      sending any X10 commands:
      
              XA -e -p
      
      There are two token statements which can override powerfail's
      determined module state. These overrides may be used for certain
      modules that do not have any programmed events stored in the
      CP-290.
      
      
      {FORCE module state}
      
        Forces a module to a desired state, no matter what powerfail
        recovery  thinks it should be in. "Module"  can be a module
        address (A1) or pre-defined name (STAIRS). "State" can be any of
        the following X10 commands:
      
                 ON, OFF, DIM %%
      
      

                XA - X10 Command Interpreter - Version 2.1                   39 
        Example (from XA.INI):
      
              FORCE P_C ON
      
      
      
        You can "force" a module from the command line too, thus
        overriding the calculated state:
      
              XA "FORCE DEN OFF" -P
      
      
      {IGNORE module}
      
        Ignores sending any command to module during a powerfail
        recovery.
      
        "Module" can be a module address or pre-defined name
      
        Example:
      
              IGNORE DEHUMIDIFIER
      
        You can tell XA to ignore any actions to a module from the
        command line too:
      
              XA "IGNORE BEDROOM_LAMP" -P
      
      

                XA - X10 Command Interpreter - Version 2.1                   40 
      Screen Color Control
      
      
      Screen color control lets you program how commands should be
      displayed.  You will be able to tell at a glance how certain
      conditional statements IF/ELSE, DATE/THRU/EXCEPT were evaluated
      by XA just by looking at the display.
      
      {VIDEO1 Foreground Background}
      
        IF or ELSE expression is TRUE (registered version).
      
      
      {VIDEO2 Foreground Background}
      
        IF or ELSE expression is FALSE (registered version), or
        DATE/THRU/EXCEPT evaluates to FALSE.
      
      
      {VIDEO3 Foreground Background}
      
        Statements resulting in DIRECT commands being sent to CP-290
      
      
      {VIDEO4 Foreground Background}
      
        Statements resulting in EVENTS being sent to CP-290.
      
      
      {VIDEO5 Foreground Background}
      
        Important messages reported by XA.
      
      
      {VIDEO6 Foreground Background}
      
        All other non event or command statements processed by XA.
      
        FOREGROUND may be any of the following:
              BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
              DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
              LIGHTMAGENTA, YELLOW, WHITE
      
        BACKGROUND may be any of the following:
              BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
      
        To display a "TRUE" IF/ELSE statement in GREEN foreground
        characters on a BLACK background, and  a "FALSE" IF/ELSE (or
        DATE/THRU/EXCEPT) statement in RED foreground characters on a
        BLACK background:
              VIDEO1 GREEN BLACK
              VIDEO2 RED BLACK
      
        To display a DIRECT command (XA "P1 ON") in YELLOW on BLACK:
              VIDEO3 YELLOW BLACK
      

                XA - X10 Command Interpreter - Version 2.1                   41 
      
      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
      
      

                XA - X10 Command Interpreter - Version 2.1                   42 
      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.
      
             H - 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
      
      

                XA - X10 Command Interpreter - Version 2.1                   43 
        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.
      

                XA - X10 Command Interpreter - Version 2.1                   44 
      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
      
      
      
      
      

                XA - X10 Command Interpreter - Version 2.1                   45 
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   46 
      
      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 because they
      will not be executed.  XA is only looking for tokens that
      describe your particular setup.  Events and direct commands
      should be placed in command files (see next section).
      

                XA - X10 Command Interpreter - Version 2.1                   47 
      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
      

                XA - X10 Command Interpreter - Version 2.1                   48 
      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"
      
      

                XA - X10 Command Interpreter - Version 2.1                   49 
      
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   50 
      
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   51 
      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)*
      
      

                XA - X10 Command Interpreter - Version 2.1                   52 
      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)*
      
      
      

                XA - X10 Command Interpreter - Version 2.1                   53 
      
      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
      
      In the first example, "MONITOR" is the only command that XA
      processes. XA ignores the default command file if it has been
      specified with XACMD.  In the second example, XA would process
      the default command file (if specified) and then initiate the
      monitor sequence.
      
      When XA begins to monitor, it displays the following message:
      
              Monitor events.  Press <ESC> when finished...
      
      XA then waits for messages from the CP-290.  You may exit this
      function by pressing the <ESC> key.
      
      When the CP-290 executes an event, it sends a message to the PC
      with the following information; the HOUSE code, UNIT code, and
      the event FUNCTION (ON, OFF, DIM).  XA takes this information
      and adds the time and date information from your PC's clock and
      prints the following  message to the monitor:
      
              Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON
      
      This message is semi-useful; it describes what just occurred but
      if you forgot what was addressed as HOUSE A UNIT 5 then the
      message is meaningless.  You can give this module a more
      descriptive name by using a command file that includes DEFINE
      statements for all your modules.  Below is sample command file
      (MONITOR.CMD - supplied with  this package) that describes what
      we're talking about:
      
              DEFINE Porch/Garage_Lights HOUSE A UNIT 1
              DEFINE Plant_Grow_Lights HOUSE A UNIT 5
              DEFINE Family_Room_TV HOUSE A UNIT 6
              DEFINE Basement_Computer HOUSE A UNIT 7
      

                XA - X10 Command Interpreter - Version 2.1                   54 
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   55 
      
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   56 
        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.
      

                XA - X10 Command Interpreter - Version 2.1                   57 
      XT (version 1.2) now comes with utility package called XTS.EXE.
      XTS has direct access to XT's database of 256 module states.
      Every command issued by the CP-290 is captured and stored by XT.
      XTS can return these module states (via errorlevel statements),
      allowing you to write batch files that react to a module's X10
      status.
      
      XA (2.0) 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. First of all, thanks go to my wife
      and kids for letting me spend the time to pursue this hobby.
      Next, my thanks go out to the beta testers - Dave Mabry, Ed
      Christie, David Huras, Nira Johnson, and to Arnold Sprague for
      proofreading the documentation.  Finally, my thanks go out to
      all the folks who have taken the time to register this program
      and offer suggestions.
      
      

                XA - X10 Command Interpreter - Version 2.1                   58 
      
      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-1994 by Bruce Christensen. All rights
      reserved.
      
      Any specific hardware/software names used in this document are
      trademarks of specific manufacturers.
      
      Regardless of the method of marketing, XA is not in the public
      domain. It is copyrighted by Bruce Christensen. All rights are
      reserved. Copying, duplicating, selling or otherwise
      distributing the registered version of this product is a
      violation of the Law. However, we grant you the right, in fact
      encourage you to make and distribute as many copies of the
      SHAREWARE version of XA as you wish, using any acceptable medium
      of exchange, with the following provisions:
      
      Please feel free to distribute this SHAREWARE version as often
      as you like, to any interested parties.
      
      Please do not distribute this program without all of its
      original related files, addendum files, documentation and this
      notice. Please do not alter the program or documentation in any
      manner.
      
      DISTRIBUTION of the REGISTERED USER version of the program is in
      violation of license agreements and copyright Law!
      

                XA - X10 Command Interpreter - Version 2.1                   59 
      Registration
      
      
      If you are still using XA beyond the initial 45-day trial
      period, you must register this software with the author. Please
      use the included registration form (REGISTER.TXT) and send a $29
      registration fee to the address below.  Your registration will
      entitle you to the latest full-featured registered version of
      this program, and a printed copy of this user manual.
      
      The registered version of XA and its utilities are licensed for
      individual personal use for an unlimited time.
      
      This is a "living" program - new features are added from time to
      time.  Your input is the basis for future improvements.  Send
      any comments to the address given below, or you may contact me
      on CompuServe, Prodigy,  America On-line, or Internet.
      
           Bruce Christensen
           6594 Hudson Avenue
           Mentor, OH.  44060-4545
      
           CompuServe: 73201,1531
           Prodigy ID:  MHNC39A
           America On-line: AuggieBen
           Internet: auggieben@aol.com
      
      
      
      Future Updates
      
      
      Future updates of the shareware version XA can be found on
      CompuServe, America On-Line, as well as the following BBS's as
      they become available. The current version of XA will be named
      "X10XA201.ZIP". The last 3 digits of the filename will indicate
      the revision level (in this case, 2.01).
      
      Dave Mabry, a sysop of the "Going Down BBS" has offered free
      access to his BBS to anyone interested in X10 - Home Automation.
      Users can gain immediate access to the home automation files
      by logging on with a userid and password of "X10". This BBS can
      be reached at:  1-(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.
      
      Home Automation Laboratories (HAL) has the best mail-order
      catalog for home automation equipment. Call 1-(800)-YEL-4HAL to
      request a catalog.  HAL's BBS # is 1-(404)-319-6227.
      
      

                XA - X10 Command Interpreter - Version 2.1                   60 
      
      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
      
      

                XA - X10 Command Interpreter - Version 2.1                   61 
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   62 
      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)
      
      

                XA - X10 Command Interpreter - Version 2.1                   63 
      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
      
      
        {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
        {VIDEO5 Foreground Background} - Important XA messages
        {VIDEO6 Foreground Background} - Statements that are non-event
                                         or non-commands.
      
        where FOREGROUND may be any of the following:
           BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
           DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
           LIGHTMAGENTA, YELLOW, WHITE
      
        and BACKGROUND may be any of the following:
           BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
      
      
      I/O Port Control                    ( ** 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
      

                XA - X10 Command Interpreter - Version 2.1                   64 
      
      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. 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.
      

                XA - X10 Command Interpreter - Version 2.1                   65 
      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.
      

                XA - X10 Command Interpreter - Version 2.1                   66 
      
      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"
      
      

                XA - X10 Command Interpreter - Version 2.1                   67 
      
      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.
      
      

                XA - X10 Command Interpreter - Version 2.1                   68 
      
      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.
      
