home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / UTILS2 / X10XA2.ZIP / XA_201.TXT < prev    next >
Text File  |  1994-01-15  |  159KB  |  3,628 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.       
  13.       XA
  14.       X10 Command Interpreter
  15.       Version 2.1 - January, 1994
  16.       Copyright 1991-1994 by Bruce Christensen. All Rights Reserved.
  17.       
  18.  
  19.       1. Shareware ..................................................  1 
  20.       2. Introduction ...............................................  1 
  21.          What is XA? ................................................  1 
  22.          Registered vs. Shareware ...................................  2 
  23.       3. Summary of NEW Features for Version 2.01 ...................  3
  24.          Other Features .............................................  5 
  25.          Miscellaneous Features .....................................  5 
  26.       4. Utilities supplied with XA .................................  6 
  27.       5. Installation ...............................................  7 
  28.       6. Getting Started ............................................  8 
  29.       7. XA Syntax and Command Line Arguments ....................... 10 
  30.       8. XA Tokens .................................................. 14 
  31.          What are tokens? ........................................... 14 
  32.       9. Tokens in Detail ........................................... 15 
  33.          Action Tokens .............................................. 15 
  34.          Module Address Tokens ...................................... 16 
  35.          Coordinate Tokens .......................................... 17 
  36.          Clock Tokens ............................................... 19 
  37.          Day Tokens ................................................. 20 
  38.          Specific Date Tokens ....................................... 21 
  39.          Time Tokens ................................................ 24 
  40.          Direct Command Control Tokens .............................. 27 
  41.          Communications Tokens ...................................... 31
  42.          I/O Port Control ........( ** Registered Version Only ** ).. 32 
  43.          Miscellaneous Tokens ....................................... 33
  44.          Reporting Tokens ........................................... 37
  45.          Powerfail Recovery ......................................... 38
  46.          Screen Color Control ....................................... 40
  47.      10. Programming Additions ...( ** Registered Version Only ** ).. 41
  48.          Variables .................................................. 41 
  49.          Hexadecimal Notation ....................................... 42 
  50.          Pre-Defined Variables ...................................... 42 
  51.          Operators .................................................. 44
  52.      11. XA.INI - Initialization file ............................... 46 
  53.      12. Command Files .............................................. 47 
  54.      13. Initialization file, Command files, Command Line Options ... 49 
  55.      14. Report Files ............................................... 50
  56.          Report Style 1 - Sort by Day and Time ...................... 51
  57.          Report Style 2 - Sort by Day, Module, and Time ............. 52
  58.      15. Monitoring and Logging events .............................. 53
  59.      16. POWERUP Utility ............................................ 55
  60.      17. FINDX10.EXE ................................................ 56
  61.      18. Other Programs and X10 Information ......................... 56 
  62.          XT - Memory Resident Software for the CP-290 ............... 56 
  63.          Other Information .......................................... 57 
  64.      19. Acknowledgements ........................................... 57
  65.      20. Warranty, Copyright, and Registration Policy ............... 58
  66.          Registration ............................................... 59 
  67.          Future Updates ............................................. 59 
  68.      Appendix A. Tokens - Quick Reference ........................... 60 
  69.      Appendix B. Returned Error Codes ............................... 64
  70.      Appendix C. Passing arguments to your command file ............. 66
  71.      Appendix D. Running XA in Windows .............................. 67
  72.      Appendix E. Updating from Version 1.07b to 2.01 ................ 68
  73.  
  74.  
  75.                 XA - X10 Command Interpreter - Version 2.1                   1  
  76.       
  77.       ═════════════════════════════════════════════════════════════════════
  78.       1.   Shareware
  79.       ═════════════════════════════════════════════════════════════════════
  80.       
  81.       This floppy contains a set of useful DOS utilities for X10's
  82.       CP-290 Computer Interface.  These programs are being marketed
  83.       using the SHAREWARE concept which allows you a complete
  84.       evaluation of the product before you are required to register.
  85.       Shareware provides you with low-cost, high-performance software
  86.       and support.  Shareware also provides incentives for programmers
  87.       to continue to develop new products.  If you find XA and its
  88.       support files useful and you continue to use them after a trial
  89.       period not to exceed 45 days, you must make a registration
  90.       payment of $29 to the author.  When you register, you will
  91.       receive the latest, full-featured version of XA along with a
  92.       printed User's Manual.  For more information, see "Warranty,
  93.       Copyright, and Registration Policy" and register your copy of XA.
  94.       
  95.       ═════════════════════════════════════════════════════════════════════
  96.       2.   Introduction
  97.       ═════════════════════════════════════════════════════════════════════
  98.       
  99.       You are probably familiar with the menu-driven program (X10.EXE)
  100.       supplied with your CP-290.  The software approach used in that
  101.       implementation is great for beginners since it offers a
  102.       fool-proof method of organizing commands and events.
  103.       Unfortunately, that method also becomes a bottle-neck every time
  104.       you want to activate a single module via your computer.  It gets
  105.       even worse when trying to maintain a schedule of lighting events
  106.       that vary due to seasonal changes.  XA is a shareware package
  107.       designed to alleviate many of the frustrations you may have
  108.       experienced with the X10-supplied software.  In addition, XA
  109.       makes schedule maintenance a breeze.  Soon, your computer will
  110.       automatically handle the monotony of CP-290 scheduling for you.
  111.       Be sure to read this manual to take full advantage of XA's power.
  112.       
  113.       
  114.       What is XA?
  115.       ─────────────────────────────────────────────────────────────────────
  116.       
  117.       The XA program is an interpreter.  XA translates English-like
  118.       sentences into commands that are understood by the CP-290.  For
  119.       instance, you can quickly tell XA to turn on a set of lights
  120.       with the  following DOS command:
  121.       
  122.            XA "PORCH ON"
  123.       
  124.       
  125.       
  126.       XA knows that the PORCH lights are addressed at HOUSE A UNIT 9,
  127.       or whatever address you choose (you define modules and their
  128.       addresses in the file XA.INI, discussed later).  Since XA
  129.       accepts commands from  the DOS prompt, you can place statements
  130.       like these in your batch files too.  For instance, I use an
  131.       X10-controlled nightlight near our downstairs phone to warn
  132.  
  133.                 XA - X10 Command Interpreter - Version 2.1                   2  
  134.       other family members if I'm "on-line" with a remote computer or
  135.       BBS.  The light is turned on prior to the session, and turned
  136.       off when I'm finished.  Here's the sample PHONE.BAT with  X10
  137.       commands:
  138.       
  139.            XA "WARNING_LAMP ON"
  140.            TELIX (or ProComm) statements here
  141.            XA "WARNING_LAMP OFF"
  142.       
  143.       
  144.       XA will also process X10 commands and events contained in a
  145.       file.  This is ideal for maintaining the CP-290's event
  146.       schedule, or for running a Christmas "lightshow".  Simply tell
  147.       XA which file to read, and XA does all the work.  For instance,
  148.       to download my event schedule to the CP-290, type:
  149.       
  150.            XA f=XA.CMD
  151.       
  152.       XA calculates sunrise and sunset times based on your latitude
  153.       and longitude, and automatically compensates for any Daylight
  154.       Savings changes.  XA can be programmed to handle events for
  155.       special dates that  may be weeks, months, or years in the
  156.       future.  Best of all, XA can automatically update the CP-290 on
  157.       a once-per-week basis without any intervention on your part (an
  158.       Appliance module is needed to control  your PC).
  159.       
  160.       Registered vs. Shareware
  161.       ─────────────────────────────────────────────────────────────────────
  162.       
  163.       The next section highlights the many additions to XA Version
  164.       2.01.  Note that some items are reserved only for "registered"
  165.       users.  The "shareware" version of XA provides all the features
  166.       of past versions, plus many newer features.  When you register
  167.       your copy of XA, you will receive a floppy with a "registered"
  168.       status allowing full use of the commands described in this
  169.       manual.
  170.                        XA - X10 Command Interpreter - Version 2.1                   3  
  171.       ═════════════════════════════════════════════════════════════════════
  172.       3.   Summary of NEW Features for Version 2.00 and 2.01
  173.       ═════════════════════════════════════════════════════════════════════
  174.       
  175.       XA Version 2.00 has been completely rewritten, allowing such
  176.       features as conditional statements, operators, and
  177.       user-variables to be supported.  Also, XA performs sun-related
  178.       calculations much faster.  The following list highlights the
  179.       major enhancements of Version 2.01.  Additional details may be
  180.       found in later sections.
  181.       
  182.       * Improved HELP screens
  183.         Type "XA /?" at the DOS prompt to get on-line information about
  184.         XA's syntax and features.
  185.       
  186.       * Power-fail recovery mode.
  187.         This feature allows you to restore the programmed state of each
  188.         module in the eventuality of a power failure, or other
  189.         circumstance.  XA determines the latest state of the module by
  190.         examining the CP-290's event schedule.  Selected modules may be
  191.         excluded from recovery, others can be forced to a particular
  192.         state no matter what XA determines.
  193.       
  194.       * Improved DATE handling.
  195.         A new token "EXCEPT" has been added which allows to program
  196.         events to occur EXCEPT when certain dates arrive:
  197.       
  198.              DEFINE MEMORIAL_DAY DATE 5/31
  199.              BEDROOM_LIGHTS ON WEEKDAYS 6:30 EXCEPT MEMORIAL_DAY
  200.       
  201.       * Automatic Daylight Savings Time adjustment.
  202.         Use the token DST to have XA determine when changes for Daylight
  203.         Savings or Standard Time should go into effect. This means you
  204.         only have to specify a single timezone token in your
  205.         initialization file (XA.INI).
  206.       
  207.       * IF/ELSE/ENDIF constructs.              (Registered Version Only)
  208.         Finally! Support for conditional statements within your  command
  209.         files.  Now you can perform a test to see whether SUNRISE  falls
  210.         within a certain time period, and schedule events based on the
  211.         result.  IF/ELSE statements may be nested up to 100 levels deep.
  212.       
  213.       * Variable assignments                   (Registered Version Only)
  214.         Variables may be used as temporary storage locations.  These
  215.         variables may then be evaluated later using IF/ELSE constructs
  216.         to trigger a DIRECT command or to program an EVENT.
  217.       
  218.       * Logical, Arithmetic, Boolean operators.(Registered Version Only)
  219.         Operations may be performed on variables and later evaluated.
  220.       
  221.       * Appends new events automatically.
  222.         You may now easily append a new event from the command line
  223.         without having to figure out where the next "free" event resides
  224.         in the CP-290.  XA finds the empty event slot for you.
  225.       
  226.       * GOSUB/RETURN
  227.         In addition to GOTO statements, XA now supports calling
  228.         subroutines (GOSUB), and returning to the original calling
  229.         statement (RETURN).
  230.       
  231.                 XA - X10 Command Interpreter - Version 2.1                   4  
  232.       * INPUT/OUTPUT (I/O) control.            (Registered Version Only)
  233.         Use your Joystick port, LPT port (or any other port) as a
  234.         general purpose Input/Output port. Connect switches and/or
  235.         relays to these ports and program XA to react to real-world
  236.         events.
  237.       
  238.       * INCLUDE files
  239.         Use the INCLUDE token to instruct the XA parser to read
  240.         additional initialization or command files. Different files may
  241.         be included based on the results of conditional IF/ELSE
  242.         statements.
  243.       
  244.       * Nested DEFINE support.
  245.         In the past, XA could not handle a statement with multiple
  246.         DEFINE substitutions.  The following is now permitted:
  247.       
  248.               DEFINE PORCH A1
  249.               DEFINE GARAGE A2
  250.               DEFINE OUTSIDE PORCH GARAGE
  251.       
  252.       * "ALL_LIGHTS_ON", "ALL_UNITS_OFF".
  253.         These "undocumented" CP-290 commands are fully supported.
  254.       
  255.       * Faster execution.
  256.         XA reduces the number of passes required to process a file.
  257.         Sunrise/set calculations are faster. Also, a new token "FAST"
  258.         can be included in a direct command which informs XA to ignore
  259.         the CP-290 acknowledgement message thus speeding up overall
  260.         execution time.
  261.       
  262.       * Conditional COLOR highlighting.
  263.         XA can optionally display each line of the XA.INI and command
  264.         file as it's parsed. In addition, you can define your own color
  265.         attributes for conditional statements that evaluate TRUE or
  266.         FALSE or when event dates fall within the specified range.
  267.         You may also define special color attributes for EVENTS and
  268.         DIRECT commands.
  269.       
  270.       * Shell to DOS capability.
  271.         XA can invoke a copy of COMMAND.COM allowing you to execute a
  272.         DOS program, batch file, etc. from within a command file.
  273.       
  274.       * Utility to locate CP-290 port connection.
  275.         A new utility called FINDX10.EXE searches all 4 COM ports for
  276.         the CP-290 interface.  If it is found, you are asked whether you
  277.         would like the parameters stored in the XA.INI file for you.
  278.       
  279.       * Expanded POWERUP.EXE Utility
  280.         An additional "week" argument has been added allowing you to
  281.         detect certain conditions. For example, on the 2nd Friday of the
  282.         month,  update the CP-290 and backup all hard drives.
  283.       
  284.                 XA - X10 Command Interpreter - Version 2.1                   5  
  285.       Other Features
  286.       ─────────────────────────────────────────────────────────────────────
  287.       
  288.       - Supports COM1...COM4  (Interrupt-driven or Polling)
  289.         Fully configurable communications. COM1...COM4. Interrupt driven
  290.         or polling.
  291.       
  292.       - SUNRISE-SUNSET calculations
  293.         XA calculates precise sunrise/sunset times for your location
  294.         based on the latitude and longitude of your city.
  295.       
  296.       - Specific DATE handling
  297.         Request any event to occur days, months, even years from now. XA
  298.         expands X10's time base by allowing you to program an event for
  299.         any day in the future, or you can schedule an event to occur
  300.         between two defined dates. You can also program modules to NOT
  301.         activate on certain dates.
  302.       
  303.       - Time synchronization
  304.         XA can keep the internal clocks of your PC and CP-290 accurate
  305.         to within 1 second of each other.  You can set either clock
  306.         based on the time maintained by the other clock.
  307.       
  308.       Miscellaneous Features
  309.       ─────────────────────────────────────────────────────────────────────
  310.       
  311.       - You can program the CP-290 to repeat a series of commands to
  312.         produce unique lighting effects.
  313.       
  314.       - X10.EXE compatible - creates X10.DAT file with the same module
  315.         names and events that were downloaded by XA.
  316.       
  317.       - Initialization file - XA.INI contains all module definitions,
  318.         communication parameters, location coordinates, and other
  319.         information that will greatly reduce redundant data used in
  320.         command files.
  321.       
  322.       - The tokens "TIMER", and "PAUSE" let you trigger X10 commands
  323.         after a number of seconds have elapsed, useful for synchronizing
  324.         X10-controlled lights with pre-recorded music.  "NOW" allows you
  325.         to program an event relative to the current time (for instance,
  326.         turn off a battery charger 14 hours from now).  "RANDOM"
  327.         provides an even better security mode by offering precise
  328.         control of random event times.
  329.       
  330.       - Better reporting facilities.  XA has 2 report formats to
  331.         document the events you downloaded to the CP-290.
  332.       
  333.       - Monitor events as the CP-290 executes them and optionally log
  334.         them to a file.
  335.       
  336.       - The ability to change the base housecode without losing all the
  337.         data already stored in the interface.
  338.       
  339.       - String substitution in the command file allows you to equate a
  340.         device (FAMILY_ROOM_LAMP) with its module address (A3).
  341.       
  342.       - Comments are allowed in the file to properly document its content.
  343.       
  344.                 XA - X10 Command Interpreter - Version 2.1                   6  
  345.       ═════════════════════════════════════════════════════════════════════
  346.       4.   Utilities supplied with XA
  347.       ═════════════════════════════════════════════════════════════════════
  348.       
  349.       POWERUP.EXE
  350.       ─────────────────────────────────────────────────────────────────────
  351.       
  352.       This utility is provided for those of you who control your
  353.       computer with an X10 Appliance module.  Powerup is designed to
  354.       be called from your AUTOEXEC.BAT file.  You pass arguments to
  355.       Powerup that specify a "window" of time based on day, week, and
  356.       time. If your computer begins its boot phase during this window,
  357.       it returns an errorlevel of 1, otherwise it returns a 0. This
  358.       errorlevel can then be evaluated by simple batch file statements
  359.       and a number of special functions can be executed.  For
  360.       instance, you can have X10 turn on your computer at 3:00 AM
  361.       every Sunday morning and automatically update the CP-290 with an
  362.       entirely new schedule of events.  Your computer can then perform
  363.       disk optimizations, disk backups, communications, etc., without
  364.       any operator intervention. When all is done, a command can be
  365.       called to turn the computer off (XA "COMPUTER OFF").  All this
  366.       can take place while you sleep.  This is what automation is all
  367.       about.  For more  information, refer to the section - "Powerup
  368.       Utility".
  369.       
  370.       
  371.       FINDX10.EXE
  372.       ─────────────────────────────────────────────────────────────────────
  373.       
  374.       This new utility is provided to help you determine the
  375.       configuration of the serial port your CP-290 is connected to.
  376.       After FINDX10 searches all COM ports in your system, it
  377.       determines the address and IRQ of the port and attempts to
  378.       communicate with the CP-290. If it successfully  locates the
  379.       CP-290, it displays the port setup and prompts you if it is OK
  380.       to save the data in your XA.INI file.
  381.       
  382.       
  383.                 XA - X10 Command Interpreter - Version 2.1                   7  
  384.       ═════════════════════════════════════════════════════════════════════
  385.       5.   Installation
  386.       ═════════════════════════════════════════════════════════════════════
  387.       
  388.       First, copy the contents of this floppy to the same drive and
  389.       directory in which your X10 software resides.  For example, if
  390.       your X10 files are located on Drive C in the directory "X10",
  391.       and the XA installation floppy disk is inserted in Drive A, you
  392.       would type at the DOS prompt:
  393.       
  394.            C:
  395.            CD \X10
  396.            COPY A:\*.* C:
  397.       
  398.       If you haven't already done so, include this drive and directory
  399.       within your PATH statement of the AUTOEXEC.BAT file.  The "PATH"
  400.       statement tells DOS where to locate frequently used executable
  401.       files.
  402.       
  403.            SET PATH=C:\DOS;C:\X10;...
  404.       
  405.       You should set the XA environment variable to the drive and
  406.       directory of your command files.  This environment variable,
  407.       which can also be placed in your AUTOEXEC.BAT file, tells XA
  408.       where to find its initialization and command files.
  409.       
  410.            SET XA=C:\X10
  411.       
  412.       If you don't understand the concepts of the PATH or SET command,
  413.       refer to your DOS User's Guide and Reference manual. Also, see
  414.       the AUTOEXEC.BAT supplied with this package for an example.
  415.       
  416.       Finally, let XA's utility program "FINDX10" search your
  417.       computer's serial ports for the CP-290. FINDX10 will determine
  418.       the IO port address and IRQ (interrupt vector) for that
  419.       particular port. These parameters are important for the
  420.       successful operation of XA. If the CP-290 is located, you will
  421.       be prompted if it's OK for FINDX10 to write those parameters
  422.       into your XA.INI initialization file. Enter 'Y' for YES if you
  423.       agree with these values.  You can always edit these statements
  424.       later. See the chapters dealing with XA.INI - INITIALIZATION
  425.       FILE, and FINDX10.EXE later in this manual for more details.
  426.       
  427.       Important Note:
  428.       
  429.       Please read the file READ.ME that was distributed on this floppy
  430.       disk (or compressed archive). This file contains any last minute
  431.       information that was not included in the printed documentation
  432.       (or XA_201.TXT file).
  433.       
  434.                 XA - X10 Command Interpreter - Version 2.1                   8  
  435.       ═════════════════════════════════════════════════════════════════════
  436.       6.   Getting Started
  437.       ═════════════════════════════════════════════════════════════════════
  438.       
  439.       XA may be invoked several different ways.  How you configured
  440.       XA, or the types of parameters that you use with it, determine
  441.       how XA behaves.
  442.       
  443.       Method 1 - The "HELP" screen.
  444.       ─────────────────────────────────────────────────────────────────────
  445.       
  446.       At the DOS prompt, enter:
  447.       
  448.            XA
  449.       
  450.       XA will display the first of many different "help" screens.
  451.       These screens include a brief synopsis of XA, and a list of
  452.       available commands that it recognizes.
  453.       
  454.       NOTE: This method will not work if the token XACMD is defined in
  455.       your XA.INI file. The default XA.INI file shipped on this floppy
  456.       will have XACMD "commented out" (or undefined).
  457.       
  458.       
  459.       Method 2 - The "HELP" screen.
  460.       ─────────────────────────────────────────────────────────────────────
  461.       
  462.       At the DOS prompt, enter:
  463.       
  464.            XA /?
  465.            XA /H
  466.            XA /h
  467.       
  468.       Again, XA will display the first of many different "help"
  469.       screens.  Use this method if your XA.INI file utilizes the XACMD
  470.       token and you wish to see the help screens.
  471.       
  472.       
  473.       Method 3 - Executing a DIRECT Command from DOS.
  474.       ─────────────────────────────────────────────────────────────────────
  475.       
  476.       At the DOS prompt, enter:
  477.       
  478.            XA "A1 OFF"
  479.       
  480.       The above is a direct command which sends an X10 Off command to
  481.       the module with a House-Unit code of A1. Direct commands are
  482.       always executed immediately.
  483.       
  484.       
  485.                 XA - X10 Command Interpreter - Version 2.1                   9  
  486.       Method 4 - Storing an EVENT into the CP-290's memory via DOS.
  487.       ─────────────────────────────────────────────────────────────────────
  488.       
  489.       At the DOS prompt, enter:
  490.       
  491.            XA "A1 ON MONDAY SUNSET"
  492.       
  493.       XA will determine which event slot is available in the CP-290's
  494.       memory. The event will be downloaded for later execution.
  495.       Events are distinguished from direct commands by the fact that
  496.       events normally contain a DAY modifier (in this case MONDAY -
  497.       but you could also use TODAY or TOMORROW) and a TIME modifier
  498.       (SUNSET is a special TIME token).
  499.       
  500.       
  501.       Method 5 - Executing a Command File
  502.       ─────────────────────────────────────────────────────────────────────
  503.       
  504.       At the DOS prompt, enter:
  505.       
  506.            XA f=XA.CMD
  507.       
  508.       The file XA.CMD contains a series of EVENT or DIRECT command
  509.       statements.  These statements are either executed immediately as
  510.       they are parsed, or sent to the CP-290 to be activated at some
  511.       future time.
  512.       
  513.       
  514.                 XA - X10 Command Interpreter - Version 2.1                   10 
  515.       ═════════════════════════════════════════════════════════════════════
  516.       7.   XA Syntax and Command Line Arguments
  517.       ═════════════════════════════════════════════════════════════════════
  518.       
  519.       XA understands the following command line options:
  520.       
  521.             XA ["commands"...] [f=filename] [-e] [+l] [+m] [+p] [-p]
  522.               [+r1] [+r2] [c=comm port] [i=irq] [o=io_addr] [/?]
  523.       
  524.       Options appearing on the command line always override any
  525.       options that have been specified in XA's command and
  526.       initialization files.  This gives you the final "say" when
  527.       overriding defaults.
  528.       
  529.       Options and commands are parsed from left to right. Under normal
  530.       circumstances, options may appear in any order without any
  531.       conflict.  Many of these options have equivalent tokens that can
  532.       be embedded within a command file or the XA initialization file
  533.       (XA.INI). Therefore, you won't have to specify these options
  534.       every time you execute XA.
  535.       
  536.       
  537.       ["commands"]
  538.       
  539.         "commands" consist of one or more tokens (see "Tokens" later in
  540.         this document) that describe an event or direct command.  When
  541.         you send a DIRECT command or EVENT via the DOS command line, a
  542.         command consisting of several tokens must be enclosed in
  543.         "quotation marks".   The quotation marks inform XA to treat the
  544.         tokens as a group, not individual commands. For example:
  545.       
  546.               XA "A1 ON"
  547.       
  548.         In the above example, A1 and ON are tokens. Together they form a
  549.         single command.  Multiple commands may appear in the command
  550.         line as long as they are enclosed in their own quotation marks.
  551.         The next example shows the use of multiple commands to create a
  552.         flashing effect.
  553.       
  554.               XA "A1 ON" "A1 OFF" "A1 ON" "A1 OFF"
  555.       
  556.       
  557.                 XA - X10 Command Interpreter - Version 2.1                   11 
  558.       [f=filename]
  559.       
  560.         This is the name of the file containing the commands to be
  561.         interpreted by XA.  To use XA in its file mode with a command
  562.         file called MONITOR.CMD, you would type:
  563.       
  564.               XA f=monitor.cmd
  565.       
  566.         Commands contained in files do not have to be enclosed in
  567.         "quotation marks".
  568.       
  569.         You can specify a default command file using the "XACMD" token
  570.         in the XA.INI initialization file (described in greater detail
  571.         later).
  572.       
  573.         See also:
  574.            Miscellaneous tokens: XACMD
  575.            XA.INI - Initialization file
  576.       
  577.       [-e]
  578.       
  579.         This option is used to prevent any communications to the
  580.         interface.  When you use this option, the parser verifies every
  581.         statement, but does not send any event information or direct
  582.         commands to the CP-290.  Use this option for testing new command
  583.         files.
  584.       
  585.       [c=comm_port]
  586.       
  587.         This allows you to select the serial port for communications
  588.         with the interface.  You may select ports 1...4. For example, if
  589.         your CP-290 is connected to COM3:
  590.       
  591.               XA c=3
  592.       
  593.         If not specified, the default port will be COM1.
  594.       
  595.         When using this option, you are actually specifying both an IO
  596.         address as well as the IRQ vector for this port. See the table
  597.         listed in the "Communications Tokens" section, later in this
  598.         document.
  599.       
  600.         See also:
  601.            Communication tokens: COM1...COM4
  602.            Command Line options: [o=io_addr]
  603.       
  604.       
  605.       [o=io_addr]
  606.       
  607.         This option allows you to select a different IO address from the
  608.         default 3F8 hex.  If your serial port is setup for 2E8 hex, then
  609.         use:
  610.       
  611.               XA o=2E8H
  612.       
  613.         See also:
  614.            Communication tokens: IO x
  615.       
  616.                 XA - X10 Command Interpreter - Version 2.1                   12 
  617.       
  618.       [i=irq#]
  619.       
  620.         Interrupt-driven: i=(3,4,5...).  For polling, use: i=0
  621.         Default: i=4  (for COM1).
  622.       
  623.         See also:
  624.            Communication tokens: IRQ x
  625.       
  626.       
  627.       [+m]
  628.       
  629.         This option will monitor the comm port for any events reported
  630.         by the CP-290.  Press the <ESC> key to terminate.
  631.       
  632.         If the token XACMD appears in your XA.INI file, or you specifed
  633.         a command file with f=file.cmd, then monitoring occurs after the
  634.         command file has been parsed.  To skip parsing of the command
  635.         file, you can use the "monitor" token instead:
  636.       
  637.               XA "monitor"
  638.       
  639.         See also:
  640.            Reporting tokens: MONITOR
  641.            "Monitoring and Logging Events"
  642.       
  643.       
  644.       [+l]
  645.       
  646.         This option will append any monitoring information to the file
  647.         XA.LOG.  The report file will be saved on the same drive and
  648.         directory as was specified by the XA environment variable
  649.         (discussed  in "Installation").
  650.       
  651.         See also:
  652.            Reporting tokens: LOG
  653.            "Monitoring and Logging Events"
  654.       
  655.       
  656.       [+r1]
  657.       
  658.         This option will produce a report file (called XA.RPT) of all
  659.         events that were just processed by the interpreter.  The format
  660.         of the report contains a sorted list of events (based on time)
  661.         for each day of the week.
  662.       
  663.         See also:
  664.            Reporting tokens: REPORT1
  665.            "Report Files"
  666.       
  667.       
  668.                 XA - X10 Command Interpreter - Version 2.1                   13 
  669.       [+r2]
  670.       
  671.         This option will produce a report file (called XA.RPT) of all
  672.         events just processed by the interpreter.  The format of the
  673.         report contains a sorted list of events (based on time), for
  674.         each module, for each day of the week.  The report file will be
  675.         saved on the same drive and directory as was specified by the XA
  676.         environment variable (discussed in "Installation").  Any
  677.         existing reports called XA.RPT will be overwritten.  You may
  678.         specify both report types to be included in the same file, as in
  679.         the following example.
  680.       
  681.               XA +r1 +r2
  682.       
  683.         See also:
  684.            Reporting tokens: REPORT2
  685.            "Report Files"
  686.       
  687.       
  688.       [+p]
  689.       
  690.         Parses command file, then performs powerfail recovery.
  691.       
  692.       
  693.       [-p]
  694.       
  695.         Immediate recovery based on stored events, no parsing of command
  696.         file  takes place.
  697.       
  698.         Powerfail recovery allows you to restore each module to its
  699.         scheduled state. By default, XA uses the last 7 days to
  700.         determine the state.  You can tell XA to use fewer days if
  701.         necessary. Simply append a number between 1and 6 to the command.
  702.         If you want XA to review the event schedule of the previous 2
  703.         days in order to determine the correct state, then append a 2 to
  704.         the command, for example:
  705.       
  706.               XA -p2
  707.       
  708.         Use "-e" in conjunction with either "+p" or "-p" to see how XA
  709.         would restore each module without actually sending any X10
  710.         commands.
  711.       
  712.         See also:
  713.            "Powerfail Recovery"
  714.       
  715.       
  716.       [/?]
  717.       [/h]
  718.       [/H]
  719.       
  720.         Displays a summary of the options described above, along with a
  721.         list of all supported tokens recognized by the interpreter.
  722.       
  723.       
  724.                 XA - X10 Command Interpreter - Version 2.1                   14 
  725.       ═════════════════════════════════════════════════════════════════════
  726.       8.   XA Tokens
  727.       ═════════════════════════════════════════════════════════════════════
  728.       
  729.       What are tokens?
  730.       
  731.       A token is to an X10 command as a word is to an English
  732.       sentence.  Individual words are constructed to form a complete
  733.       sentence - tokens are constructed to form a complete command.
  734.       This section will describe each token that is recognized by the
  735.       interpreter. Some tokens may appear anywhere in the command.
  736.       For example, the command
  737.       
  738.            XA "A1 ON"    may also be constructed as:
  739.            XA "ON A1"
  740.       
  741.       In other instances, tokens must be arranged in groups.  Their
  742.       order is important.  For example, the command to set your PC's
  743.       internal clock to the time that is maintained by the CP-290 is:
  744.       
  745.            XA "SYNCHRONIZE PC"      <---This is legal
  746.       
  747.       If the tokens SYNCHRONIZE and PC were reordered as in the
  748.       following command:
  749.       
  750.            XA "PC SYNCHRONIZE"      <---This is illegal
  751.       
  752.       The interpreter would respond with a message indicating the
  753.       token it did not recognize the token. Therefore, throughout this
  754.       documentation any tokens that must be arranged in a certain
  755.       order will be contained in curly braces {..}.  Other tokens may
  756.       be optional and will be contained in parentheses (..).
  757.       
  758.       Most or the examples in the next chapter describe how the tokens
  759.       may be used from the DOS command line. Therefore, the tokens
  760.       that make up a complete command will be enclosed in "quotation
  761.       marks".  Other examples show how the tokens may be used in a
  762.       file, therefore, quotation marks are not used, or needed.
  763.       
  764.                 XA - X10 Command Interpreter - Version 2.1                   15 
  765.       ═════════════════════════════════════════════════════════════════════
  766.       9.   Tokens in Detail
  767.       ═════════════════════════════════════════════════════════════════════
  768.       
  769.       Action Tokens
  770.       ─────────────────────────────────────────────────────────────────────
  771.       
  772.       
  773.       ON
  774.       
  775.         This token informs the interface to turn ON the selected modules.
  776.       
  777.               XA "A1 ON"
  778.       
  779.       
  780.       OFF
  781.       
  782.         This token informs the interface to turn OFF the selected
  783.         modules.
  784.       
  785.               XA "A1 OFF"
  786.       
  787.       
  788.       {DIM %%}
  789.       
  790.         These two tokens specify the intensity level of the selected
  791.         lamp or wall switch module.  The modules will turn on, brighten
  792.         to full intensity, then dim to the percentage specified in the
  793.         second token.  There are 16 different brightness levels
  794.         available, the percentage you choose (0 to 100) is mapped to one
  795.         of these levels. The percentage level you select may not
  796.         correspond exactly with level reported by the X10-supplied
  797.         program X10.EXE.
  798.       
  799.               XA "A1 DIM 50"
  800.       
  801.       
  802.       {ALL_UNITS_OFF HOUSE x}
  803.       
  804.         These tokens will issue the X10 "ALL_UNITS_OFF" command for the
  805.         selected housecode. This command affects Appliance-style and
  806.         Lamp Dimmer/Wall Switch modules.
  807.       
  808.               XA "ALL_UNITS_OFF HOUSE A"
  809.       
  810.         Using this command is faster than issuing (as described in the
  811.         next section):
  812.       
  813.               XA "HOUSE A UNIT ALL OFF"
  814.       
  815.       
  816.                 XA - X10 Command Interpreter - Version 2.1                   16 
  817.       {ALL_LIGHTS_ON HOUSE x}
  818.       
  819.         These tokens will issue the X10 "ALL_LIGHTS_ON" command for the
  820.         selected housecode. This command affects only Lamp Dimmer/Wall
  821.         Switch modules.
  822.       
  823.               XA "ALL_LIGHTS_ON HOUSE A"
  824.       
  825.       
  826.         Notes:
  827.       
  828.            * Only one token in this category should appear in a command. If
  829.              two or more of these tokens appear, only the last one will be
  830.              processed.  For example:
  831.       
  832.                  XA "A1 ON OFF"  -  will be interpreted as:
  833.                  XA "A1 OFF"
  834.       
  835.              If you were trying to flash the lights, the proper way to
  836.              perform this action is:
  837.       
  838.                  XA "A1 ON"  "A1 OFF"
  839.       
  840.            * You may activate as many modules as you want in a single command
  841.              providing these modules share the same HOUSE code:
  842.       
  843.                  XA "A1 A2 A3 A4 A5 A6 ON"
  844.       
  845.            * To activate modules with different HOUSE codes, use separate
  846.              commands:
  847.       
  848.                  XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"
  849.       
  850.       
  851.       Module Address Tokens
  852.       ─────────────────────────────────────────────────────────────────────
  853.       
  854.       A1...P16
  855.       
  856.         This is a shortcut method of specifying both HOUSE and UNIT
  857.         tokens.  The house code must appear first, followed by  the unit
  858.         code.  Specifying ALL is not permitted.
  859.       
  860.               XA "A1 ON"  "P16 OFF"
  861.       
  862.       {HOUSE x}
  863.       
  864.         These two tokens specify the HOUSE code of the module you want
  865.         to select.  There are 16 HOUSE codes available,  lettered A
  866.         through P.  This method of selecting addresses requires the use
  867.         of the UNIT token.  Only one HOUSE token should appear in a
  868.         command.
  869.       
  870.       
  871.                 XA - X10 Command Interpreter - Version 2.1                   17 
  872.       {UNIT y}
  873.       {UNIT ALL}
  874.       
  875.         These two tokens specify the UNIT code of the module you want to
  876.         select.  There are 16 UNIT codes available, numbered 1 through 16.
  877.         Specifying UNIT ALL operates on all 16 modules addressed by
  878.         the HOUSE token.  This method of module addressing requires the
  879.         use of the HOUSE token:
  880.       
  881.               XA "HOUSE A UNIT 1 ON"   or,
  882.               XA "UNIT 1 HOUSE A ON"
  883.       
  884.         Multiple UNITs may appear in a single command:
  885.       
  886.               XA "HOUSE A UNIT 1 UNIT 2 UNIT 3 ON"
  887.       
  888.         Turn off all units on HOUSE P:
  889.       
  890.               XA "HOUSE P UNIT ALL OFF"     or use the faster method:
  891.               XA "HOUSE P ALL_UNITS_OFF"
  892.       
  893.       
  894.         Notes:
  895.       
  896.            * You may activate as many modules as you want in a single command
  897.              providing these modules share the same HOUSE code:
  898.       
  899.                  XA "A1 A2 A3 A4 A5 A6 ON"
  900.       
  901.              To activate modules with different HOUSE codes, use separate
  902.              commands:
  903.       
  904.                  XA "A1 A2 A3 ON"  "B1 B2 ON"  "C1 OFF"
  905.       
  906.            * You can give your module's more descriptive names by using the
  907.              DEFINE token (described later). For instance, place the
  908.              following line in your XA.INI file:
  909.       
  910.                  DEFINE COFFEE HOUSE A UNIT 10
  911.       
  912.              To turn the coffee pot ON from your computer, all you have to
  913.              type is:
  914.       
  915.                  XA "COFFEE ON" or
  916.                  XA "A10 ON"
  917.       
  918.       Coordinate Tokens
  919.       ─────────────────────────────────────────────────────────────────────
  920.       
  921.       This group of tokens enable the precise calculation of sunrise
  922.       and sunset times for your location.  This information can be
  923.       found in almanacs, or extrapolated from maps.  Coordinates for
  924.       major U.S. cities may be found in the file US_LATIT.TXT supplied
  925.       with XA. Your local library or city hall may also have your
  926.       city's precise coordinates.  These tokens should be placed in
  927.       your XA.INI file so that all command files will be able to
  928.       calculate sun-related events.
  929.       
  930.                 XA - X10 Command Interpreter - Version 2.1                   18 
  931.       {LATITUDE dms}
  932.       {LATITUDE ° ' "}
  933.       
  934.         Your latitude in degrees (0...+/-90), minutes (0...59) and,
  935.         optionally, seconds (0...59).
  936.       
  937.               LATITUDE 41d35m20s   -or-
  938.               LATITUDE 41°35'20"
  939.       
  940.       
  941.       {LONGITUDE dms}
  942.       {LONGITUDE ° ' "}
  943.       
  944.         Your longitude in degrees (0...+-180), minutes (0...59) and,
  945.         optionally, seconds. Longitudes West of the prime meridian are
  946.         positive, those East of the prime meridian are negative.  In the
  947.         US, all longitudes are positive.
  948.       
  949.               LONGITUDE 81d20m45s     -or-
  950.               LONGITUDE 81°20'45"
  951.       
  952.       
  953.       {TIMEZONE x}
  954.       
  955.         Exact calculations depend on the local time.  Use the following
  956.         table to determine your time zone. Previous versions of XA
  957.         included "Daylight Savings" values in this table. It is no
  958.         longer necessary to manually change these tokens. Use the DST
  959.         token to automatically adjust time changes.
  960.       
  961.                              ZONE      TIMEZONE
  962.                          ============= ========
  963.                          Eastern           5
  964.                          Central           6
  965.                          Mountain          7
  966.                          Pacific           8
  967.                          Alaska/Hawaii    10
  968.                          Aleutian         11
  969.       
  970.               TIMEZONE 5
  971.       
  972.       
  973.       DST
  974.       
  975.         Use the token DST to have XA determine when changes for Daylight
  976.         Savings or Standard Time should go into effect. This means you
  977.         only have to specify a single timezone token in your
  978.         initialization file  (XA.INI).
  979.       
  980.               TIMEZONE 5  DST
  981.       
  982.       
  983.                 XA - X10 Command Interpreter - Version 2.1                   19 
  984.       Clock Tokens
  985.       ─────────────────────────────────────────────────────────────────────
  986.       
  987.       {SYNCHRONIZE PC (EXACT)}
  988.       
  989.         These tokens instruct XA to set your computer's clock based on
  990.         the current time retrieved from the CP-290.  It will not affect
  991.         the computer's date.
  992.       
  993.               XA "SYNCHRONIZE PC"
  994.       
  995.         Use the optional "EXACT" token to wait for the X10 time to
  996.         rollover to the next minute.  This provides a synchronization
  997.         within 1 second, but forces you to wait for up to one minute for
  998.         this rollover to happen.
  999.       
  1000.               XA "SYNCHRONIZE PC EXACT"
  1001.       
  1002.       
  1003.       {SYNCHRONIZE X10 (EXACT)}
  1004.       
  1005.         These tokens instruct XA to set the time and day of the CP-290
  1006.         internal clock based on the current time retrieved from your
  1007.         computer.
  1008.       
  1009.               XA "SYNCHRONIZE X10"
  1010.       
  1011.         Using "EXACT" will force XA to wait until the PC's clock to
  1012.         rollover to the next minute.  This provides a synchronization
  1013.         within 1 second, but forces you to wait for up to one minute for
  1014.         this rollover to happen.
  1015.       
  1016.               XA "SYNCHRONIZE X10 EXACT"
  1017.       
  1018.         Notes:
  1019.       
  1020.            * You might want to include the command XA "SYNCHRONIZE PC" in
  1021.              your AUTOEXEC.BAT file to set your PC's internal clock if your
  1022.              system lacks an on-board battery backed-up clock.  Note that
  1023.              this command will not set up the date since the CP-290 does not
  1024.              contain a real-time calendar.
  1025.       
  1026.            * Use XA "SYNCHRONIZE PC" or XA "SYNCHRONIZE X10" in your
  1027.              AUTOEXEC.BAT file if either your PC or CP-290 does not keep
  1028.              accurate time.
  1029.       
  1030.       
  1031.                 XA - X10 Command Interpreter - Version 2.1                   20 
  1032.       Day Tokens
  1033.       ─────────────────────────────────────────────────────────────────────
  1034.       
  1035.       Use of these tokens indicates a timed event, i.e., the complete
  1036.       command will be downloaded to the interface and stored there for
  1037.       later activation.
  1038.       
  1039.       SUNDAY, SUN
  1040.       MONDAY, MON
  1041.       TUESDAY, TUE
  1042.       WEDNESDAY, WED
  1043.       THURSDAY, THU
  1044.       FRIDAY, FRI
  1045.       SATURDAY, SAT
  1046.       
  1047.         These tokens describe the specific day of the event. Multiple
  1048.         tokens may appear within a command.
  1049.       
  1050.               XA "MONDAY FRIDAY A1 ON TIME 7:30 AM"
  1051.       
  1052.       
  1053.       WEEKENDS, WEEKEND
  1054.       
  1055.         Event occurs on SATURDAY and SUNDAY.
  1056.       
  1057.       
  1058.       WEEKDAYS, WEEKDAY
  1059.       
  1060.         Event occurs MONDAY TUESDAY WEDNESDAY THURSDAY  FRIDAY.
  1061.       
  1062.       
  1063.       EVERYDAY
  1064.       
  1065.         Event occurs MON TUE WED THU FRI SAT SUN.
  1066.       
  1067.       
  1068.       TODAY
  1069.       
  1070.         Event will occur today only at the specified time.  It is then
  1071.         deleted from the interface after midnight.  If "OFFSET hh:mm" is
  1072.         also programmed causing the event to trigger after midnight, the
  1073.         event  will be modified for TOMORROW status.
  1074.       
  1075.       
  1076.       TOMORROW
  1077.       
  1078.         Event will occur tomorrow only at the specified time.  It is
  1079.         then deleted from the interface after midnight.  If "OFFSET
  1080.         hh:mm" is also programmed causing the event to trigger before
  1081.         midnight, the event  will be modified for TODAY status.
  1082.       
  1083.       
  1084.       
  1085.                 XA - X10 Command Interpreter - Version 2.1                   21 
  1086.         Notes:
  1087.            * If you leave off a DAY token when downloading an event to the
  1088.              CP-290, XA will assign the command as a TODAY-only event.
  1089.              Therefore, at midnight the event will be cleared from the
  1090.              CP-290's memory. The following command will take place at 11:00
  1091.              tonight and be deleted at midnight since it was given "TODAY"
  1092.              status (no other DAY was specified):
  1093.       
  1094.                  XA "FAN ON TIME 11:00 PM"
  1095.       
  1096.            * Registered Users - Using the "CDAY" token in conjunction with
  1097.              "SAT,SUN MON, TUE, WED, THU, FRI, WEEKEND, WEEKDAY" tokens
  1098.              allows you to program special functions based on the current
  1099.              day. For example, the statements below will the initialize the
  1100.              default command file (using XACMD) based on the current day.
  1101.              Note: Use of the IF/ELSE/ENDIF and CDAY tokens, as well as the
  1102.              "==" and "OR" operators will be discussed later in this
  1103.              document.
  1104.       
  1105.                  IF ((CDAY == SAT) OR (CDAY == SUN))
  1106.                     XACMD WEEKEND.CMD
  1107.                  ELSE
  1108.                     XACMD WEEKDAY.CMD
  1109.                  ENDIF
  1110.       
  1111.       Specific Date Tokens
  1112.       ─────────────────────────────────────────────────────────────────────
  1113.  
  1114.       Since the CP-290 does not contain an on-board calendar, there is
  1115.       no direct method of storing an event that occurs more than 1
  1116.       week away.  However, XA has the ability to evaluate dates and as
  1117.       long as XA is run at least once a week it can determine the
  1118.       appropriate time to download the event.  This feature allows you
  1119.       specify an event weeks, months, or years in advance.
  1120.       
  1121.       Date features:
  1122.         * You can specify an event to occur on specific days of each month
  1123.           (such as every 10th day of the month), or annually (every 4th of
  1124.           July)
  1125.       
  1126.         * Events may be scheduled to trigger on selected days between
  1127.           specific dates (such as Christmas and New Year's).  You can also
  1128.           program an event to NOT happen on an individual date, or between
  1129.           certain dates.
  1130.       
  1131.         * XA makes use of screen color control (see VIDEO) to show you if
  1132.           scheduled event meets date criterion.
  1133.       
  1134.       To guarantee that specific dates will be evaluated and events
  1135.       will be triggered at the proper time in the future, plug your
  1136.       computer into an Appliance module and have the CP-290 turn your
  1137.       computer on automatically on a once-per-week basis.  By using
  1138.       XA.EXE in conjunction with POWERUP.EXE (supplied with this
  1139.       package) you can have a new set of events automatically
  1140.       downloaded to the CP-290.  Now you'll never forget to update
  1141.       your CP-290, your computer  does it for you automatically.  This
  1142.       is what "automation" is all about.  See  section "Powerup" for
  1143.       more details.
  1144.  
  1145.                 XA - X10 Command Interpreter - Version 2.1                   22 
  1146.       
  1147.       When using the following "DATE" tokens, you should include the
  1148.       "ERASE" token at the beginning of your command file.  ERASE will
  1149.       clear the entire contents of the CP-290, removing all event
  1150.       information. The reason you want to erase its memory is because
  1151.       once XA downloads an event to the CP-290, it will remain there
  1152.       until it is deleted or overwritten.  The next time XA is run
  1153.       (next week) the event may still remain and trigger itself again
  1154.       and again until it is either manually deleted, or eventually
  1155.       overwritten by a new event. ERASE ensures that the data is
  1156.       cleared and that the interface will contain fresh information.
  1157.       Also, since all your information is stored in a command file,
  1158.       the relevant information will always be placed in the CP-290.
  1159.       
  1160.       
  1161.       {DATE mm/dd/yyyy}
  1162.       
  1163.         Event occurs on specified date.  You must specify the date in
  1164.         the following format:
  1165.       
  1166.            Month - none, 1, or 2 digits (1 = Jan ...  12 = Dec)
  1167.            Day   - none, 1, or 2 digits
  1168.            Year  - none, 2, or 4 digits
  1169.       
  1170.         To specify module A5 ON July 4, 1994 at 5:00 pm:
  1171.       
  1172.               A5 ON DATE 7/4/1994 TIME 5:00 PM
  1173.       
  1174.         You may omit fields which is the equivalent of specifying any
  1175.         month, day, or year.  Each field must be delineated by a
  1176.         separator, either a '/' or '-' character.   For example, to
  1177.         specify module A5 to turn OFF on the 4th of every month at 6:00 AM:
  1178.       
  1179.               DATE /4/ A5 OFF TIME 6:00 AM
  1180.       
  1181.         To specify module A5 to turn ON every 4th of July at sunset,
  1182.         leave off the "yyyy" field:
  1183.       
  1184.               DATE 7/4/ A5 ON SUNSET
  1185.       
  1186.         An exception to the separator requirement arises when the "yyyy"
  1187.         is not being programmed -simply omit the '/' or '-' character
  1188.         between the "dd" and "yyyy" fields. The above statement could be
  1189.         written as:
  1190.       
  1191.               DATE 7/4 A5 ON SUNSET
  1192.       
  1193.         You may specify multiple dates in the same command:
  1194.       
  1195.               DATE 7/4 DATE 7/6 DATE 7/8 A5 ON SUNSET
  1196.       
  1197.       
  1198.                 XA - X10 Command Interpreter - Version 2.1                   23 
  1199.       {DATE mm/dd/yyyy THRU [DATE] mm/dd/yyyy (DAY)}
  1200.       
  1201.         Event will occur EVERYDAY between the two dates unless you place
  1202.         specific DAY tokens within the command.  Use the same date
  1203.         format conventions as described above.
  1204.       
  1205.         If you will be going on vacation between July 1, 1994 and August
  1206.         1, 1994, and you want the bedroom lights (A3) turned ON and OFF
  1207.         every weekday in a random fashion during the evenings:
  1208.       
  1209.               DATE 7/1/1994 THRU 8/1/1994  ON A3 TIME 9:00 PM SECURITY WEEKDAYS
  1210.               DATE 7/1/1994 THRU 8/1/1994 OFF A3 TIME 11:30 PM WEEKDAYS
  1211.       
  1212.         To turn ON your Christmas lights everyday between Thanksgiving
  1213.         and New Years Eve, turn them OFF at 10:00PM on weekdays, and
  1214.         turn them off at 11:30 during the weekends:
  1215.       
  1216.               DEFINE THANKSGIVING DATE 11/24/94
  1217.               DEFINE NEW_YEARS_EVE DATE 12/31/95
  1218.               THANKSGIVING THRU NEW_YEARS_EVE  XMAS ON SUNSET
  1219.               THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 10:00 PM WEEKDAYS
  1220.               THANKSGIVING THRU NEW_YEARS_EVE XMAS OFF TIME 11:30 PM WEEKENDS
  1221.       
  1222.       EXCEPT
  1223.       
  1224.         Once XA parses this token, any DATE (or DATE...THRU) statements
  1225.         become "exceptions", that is, events will not be scheduled to
  1226.         activate during that date (or period). For example, to turn a
  1227.         lamp (A7) on every weeknight except Memorial Day:
  1228.       
  1229.               A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31
  1230.       
  1231.         You may specify multiple exception dates in the same command:
  1232.       
  1233.               A7 ON WEEKDAYS SUNSET EXCEPT DATE 5/31 DATE 7/1
  1234.       
  1235.       
  1236.         Notes:
  1237.            *  Events that are not downloaded because they do not meet the
  1238.               range criteria will be displayed using the VIDEO2 screen
  1239.               attributes (to signify a FALSE condition).
  1240.       
  1241.       
  1242.               Use the format:
  1243.            *  {EXCEPT DATE mm/dd/yyyy THRU [DATE] mm/dd/yyyy (DAY)}
  1244.       
  1245.               to  prevent an event from occurring between two dates. EVERYDAY
  1246.               will be assumed unless you place specific DAY tokens within the
  1247.               command.  For example, to prevent the porch lights from coming
  1248.               on while your Christmas lights are on:
  1249.       
  1250.                  PORCH ON SUNSET EXCEPT DATE 12/1/1994 THRU 1/1/1995
  1251.       
  1252.               Special Note: When dates "rollover" into the next year, you must
  1253.               specify the "year" within the date statement (as in the above
  1254.               example).
  1255.       
  1256.                 XA - X10 Command Interpreter - Version 2.1                   24 
  1257.            Use the format:
  1258.            *  {DATE mm/dd/yy THRU [DATE]  mm/dd/yy EXCEPT DATE mm/dd/yy THRU
  1259.                [DATE] mm/dd/yy}
  1260.       
  1261.               to specify a range of dates that a module should not activate,
  1262.               within a range of dates that it should be activated.  For
  1263.               instance, turn on deck lights only during the summer, except
  1264.               while you are on vacation:
  1265.       
  1266.                  DECK ON SUNSET DATE 6/21 THRU 9/22 EXCEPT DATE 7/1 THRU 7/14
  1267.       
  1268.       
  1269.       Time Tokens
  1270.       ─────────────────────────────────────────────────────────────────────
  1271.       
  1272.       Use of these tokens indicate a timed event, i.e., the complete
  1273.       command will be downloaded to the interface and stored there for
  1274.       later activation.
  1275.       
  1276.       {TIME hh:mm (AM/PM)}
  1277.       
  1278.         Schedule event at a certain time.
  1279.       
  1280.               XA "D1 ON SUNDAY TIME 12:30 AM"
  1281.       
  1282.         AM is the default. You may specify military-style time as
  1283.         follows:
  1284.       
  1285.               XA "D1 ON SUNDAY TIME 23:34 "
  1286.       
  1287.       
  1288.       SUNRISE
  1289.       SUNSET
  1290.       
  1291.         These tokens will calculate the sunrise or sunset for the day
  1292.         token in the command.  The use of these tokens also requires the
  1293.         LATITUDE, LONGITUDE, and TIMEZONE (and optional DST) tokens to
  1294.         be included in  the XA.INI file.
  1295.       
  1296.               D1 ON MONDAY SUNSET
  1297.       
  1298.         If multiple day tokens appear in the command line, the sunrise
  1299.         or sunset time will be the average sunrise/set time for the next
  1300.         seven days.
  1301.       
  1302.               MONDAY TUESDAY WEDNESDAY ON SUNSET D1
  1303.       
  1304.         If more accuracy is needed, then break each daily event into its
  1305.         own command.
  1306.       
  1307.               MONDAY ON SUNSET D1
  1308.               TUESDAY ON SUNSET D1
  1309.               WEDNESDAY ON SUNSET D1
  1310.       
  1311.       
  1312.                 XA - X10 Command Interpreter - Version 2.1                   25 
  1313.       {OFFSET +/-hh:mm}
  1314.       {OFFSET +/-mins}
  1315.       
  1316.         Push or postpone the scheduled event by up to 24 hours (1440
  1317.         minutes).  This token is useful if you want to activate lights
  1318.         at dusk rather than sunset, or to deactivate lights at dawn
  1319.         rather than sunrise.  The '+' sign is the default condition, you
  1320.         must specify the  '-' if needed.  To turn ON lights 30 minutes
  1321.         after sunset:
  1322.       
  1323.               MONDAY ON SUNSET D1 OFFSET 30
  1324.       
  1325.         Turn lights OFF 1 hour before sunrise:
  1326.       
  1327.               MONDAY OFF SUNRISE D1 OFFSET -1:00
  1328.       
  1329.         See section Miscellaneous Tokens - DEFINE for another way of
  1330.         specifying DUSK or DAWN using the DEFINE token.  For example:
  1331.       
  1332.               DEFINE DUSK SUNSET OFFSET 30
  1333.               DEFINE DAWN SUNRISE OFFSET -1:00
  1334.                      :
  1335.               MONDAY ON DUSK D1
  1336.               MONDAY OFF DAWN D1
  1337.       
  1338.       
  1339.       {NOW +mm}
  1340.       {NOW +hh:mm}
  1341.       
  1342.         Creates a one-shot event based on the current DOS day and time
  1343.         and the hh:mm offset specified in the token. The event will
  1344.         initially be given a "TODAY" status.  If the added offset causes
  1345.         the event to be scheduled past midnight, the event will be
  1346.         converted to "TOMORROW" status.  In either case, the event will
  1347.         be deleted from the CP-290 at midnight following its activation.
  1348.       
  1349.       
  1350.         The following command file example shows how to activate a
  1351.         battery charger and then turn it off 14 hours later. This file
  1352.         is called CHARGER.CMD.
  1353.       
  1354.               DEFINE CHARGER H1
  1355.               CHARGER ON              # Turn the charger on...
  1356.               CHARGER OFF NOW 14:00   # Have CP-290 turn it off 14 hrs later
  1357.       
  1358.         Earlier versions of XA required the use of the EVENT token in
  1359.         order to prevent overwriting existing events in the CP-290's
  1360.         memory.  XA Version 2.00 automatically appends the command to
  1361.         current schedule,  eliminating the need to figure this out
  1362.         manually.
  1363.       
  1364.       
  1365.       NORMAL
  1366.       
  1367.         This token activates the event at the specified time.  It is the
  1368.         default mode, therefore it does not need to be specified.
  1369.       
  1370.       
  1371.                 XA - X10 Command Interpreter - Version 2.1                   26 
  1372.       {RANDOM +/-hh:mm}
  1373.       {RANDOM +/-mins}
  1374.       
  1375.         Prior to Version 1.07, RANDOM used to be synonymous with the
  1376.         SECURITY token, which merely activated the CP-290 built-in time
  1377.         adjustment.  This feature would pseudo-randomly select a time
  1378.         for event activation anytime within the programmed hour.
  1379.         "RANDOM hh:mm" now gives you complete control over the random
  1380.         window.  "hh:mm" is the number of hours and minutes that a
  1381.         random offset should be added/subtracted from the programmed
  1382.         time. This offset should be in the range of 1 minute to 24 hours
  1383.         (1440 mins).
  1384.       
  1385.         If "hh:mm" is programmed with a "+" sign, then the calculated
  1386.         random value will be added to the programmed time. The following
  1387.         example will add between 0 and 9 minutes to the requested time,
  1388.         that is, anywhere between 5:00 PM and 5:09 PM.
  1389.       
  1390.               A5 ON TIME 5:00 PM RANDOM +9
  1391.       
  1392.         If "mm" is programmed with a "-" sign, then the calculated
  1393.         random value will be subtracted from the programmed time. The
  1394.         following example will subtract between 0 and 15 minutes from
  1395.         the calculated SUNRISE time. If SUNRISE occurs at 6:00 AM, then
  1396.         the resulting time could be anywhere in the range of 5:45
  1397.         through 6:00.
  1398.       
  1399.               SUNRISE RANDOM -:15
  1400.       
  1401.         If "mm" is programmed without any sign, then the calculated
  1402.         random value will either be added or subtracted to/from the
  1403.         programmed time.  For example, to allow 90 minutes on either
  1404.         side of SUNSET:
  1405.       
  1406.                                        # Sunset @ 9:00 PM
  1407.               SUNSET RANDOM 1:30      # TIME ranges between 7:30 PM ... 10:30 PM
  1408.       
  1409.         RANDOM, as well as OFFSET, will automatically change the day if
  1410.         the adjustment causes a rollover into the previous or next day.
  1411.       
  1412.       
  1413.       SECURITY
  1414.       
  1415.         This token allows the CP-290 to randomly select the activation
  1416.         time of the event.  This activation occurs within the hour of
  1417.         the programmed time.  Therefore, if the downloaded time was for
  1418.         7:18 PM, actual activation time could range from 7:00 PM through
  1419.         7:59 PM. This mode provides a security feature giving your
  1420.         lighting a more lived-in look.
  1421.       
  1422.               XA "A1 ON TIME 7:30 PM SECURITY EVERYDAY"
  1423.       
  1424.       
  1425.                 XA - X10 Command Interpreter - Version 2.1                   27 
  1426.       Direct Command Control Tokens
  1427.       ─────────────────────────────────────────────────────────────────────
  1428.       The following tokens may be used within an XA command file so
  1429.       you can use the CP-290 to perform a series of lighting effects.
  1430.       Certain commands may be repeated a limited number of times or
  1431.       forever.  Commands may also be synchronized with a key press,
  1432.       allowing special effects with a high degree of accuracy.  The
  1433.       "registered" version of XA can also read data from an I/O port,
  1434.       allowing X10 commands to be synchonized with an external event.
  1435.       
  1436.       PAUSE
  1437.         When this token is executed, it displays a message and halts
  1438.         further execution of the command file.:
  1439.               "Press any key to continue..."
  1440.  
  1441.         When a key press is detected, an internal timer is reset to
  1442.         ZERO, and any remaining commands are executed. The internal
  1443.         timer is used in conjunction with the TIMER token.  This command
  1444.         is useful for synchronizing a series of commands to an external
  1445.         event.  See TIMER below, for an example.
  1446.       
  1447.       [module command] TIMER hh:mm:ss.s
  1448.       
  1449.         This token informs XA to issue a command when the internal timer
  1450.         reaches "hh:mm:ss.s".  The built-in timer is initialized to 0
  1451.         when XA is invoked, or whenever a key press follows a PAUSE
  1452.         command, or when the token "RESET" is parsed. All subsequent
  1453.         TIMER commands are evaluated from the point at which the
  1454.         internal timer was initialized.
  1455.       
  1456.         One very useful application of the PAUSE and TIMER commands is
  1457.         to synchronize X10-controlled lighting sequences with
  1458.         pre-recorded  music.  For instance, you could assign each song
  1459.         its own command  file.  Each file would start off with a PAUSE
  1460.         (Registered version may use INPORT) token to intialize the
  1461.         timer, as well as provide a means to start the music and command
  1462.         chain from a common point.  TIMER statements would specify the
  1463.         exact times that the CP-290 would trigger an X10 command at an
  1464.         appropriate moment in the song.
  1465.       
  1466.               PAUSE                   # Wait for any key press, reset timer
  1467.               A1 ON TIMER 0:0:10.0    # At 10 seconds, turn on A1
  1468.               A1 DIM 0 TIMER 0:0:20.5 # At 20.5 seconds, fade light out.
  1469.       
  1470.         In this example, the PAUSE waits for a cue to start the
  1471.         sequence. 10 seconds later, A1 is activated. 20.5 seconds after
  1472.         the cue, A1 is DIMMED to a level 0.
  1473.       
  1474.         XA will automatically anticipate and adjust for any delays that
  1475.         may be caused by the CP-290.  For instance,  the amount of time
  1476.         it takes to turn on a lamp may take as much as 1.4 seconds. Even
  1477.         worse, the CP-290 forces a lamp module to go to the fully BRIGHT
  1478.         state before allowing the module to be dimmed - delaying the
  1479.         actual effect by 6 seconds.  In order to have XA compensate for
  1480.         these delays, you should place an X10 command on the same line
  1481.         just prior to the timer command.  For example, the following
  1482.         line turns the lamp on after 7 seconds. However, XA actually
  1483.         issues the command at 5.6 seconds:
  1484.  
  1485.                 XA - X10 Command Interpreter - Version 2.1                   28 
  1486.       
  1487.               A1 ON TIMER 0:0:7.0
  1488.       
  1489.         Likewise, to completely dim a module to 0% after 10 seconds, XA
  1490.         will begin issuing the command after approximately 4 seconds
  1491.         have elapsed.
  1492.       
  1493.               A1 DIM 0 TIMER 0:0:10.0
  1494.       
  1495.         If no commands are programmed on the same line as the TIMER
  1496.         statement, then a default adjustment of 1.4 seconds will be used
  1497.         for  commands that appear later.
  1498.       
  1499.         It is very important that you program the 'hour' and 'minute'
  1500.         fields, even if they are zero. Otherwise, XA will convert the
  1501.         'seconds' field to minutes, and you'll be waiting a long time.
  1502.         For example, do this:
  1503.       
  1504.               TIMER 0:0:15.5   <--- Do this
  1505.               TIMER 15.5      <--- NOT this
  1506.       
  1507.       
  1508.       RESET
  1509.       
  1510.         When the RESET token is parsed, the internal timer is preset to
  1511.         0.  The PAUSE token also presets the internal timer to 0, but
  1512.         only after a key has been pressed. This token may be useful when
  1513.         used in conjunction with the "INPORT port" statement. (INPORT
  1514.         can monitor a  bit of a selected port and force a RESET when the
  1515.         bit goes TRUE. INPORT is only available in the "registered"
  1516.         version).
  1517.       
  1518.       
  1519.       {DELAY hh:mm:ss}
  1520.       
  1521.         These tokens allow you wait for the specified number of hours,
  1522.         minutes and seconds to pass before executing the next command.
  1523.         These delays are relative to the present time and do not work in
  1524.         conjunction with the TIMER or PAUSE tokens.  To wait 5 seconds
  1525.         between commands, use:
  1526.       
  1527.               A1 OFF
  1528.               DELAY 0:0:5
  1529.               A2 ON
  1530.       
  1531.       
  1532.       STOP
  1533.       
  1534.         Normally, XA stops execution when it reaches the end of a
  1535.         command file.  The STOP token forces XA to immediately stop
  1536.         execution. It may be placed anywhere in the command file. See
  1537.         the GOSUB example below for an example.
  1538.       
  1539.       
  1540.                 XA - X10 Command Interpreter - Version 2.1                   29 
  1541.       :LABEL
  1542.       
  1543.         This token identifies a location in your command file that you
  1544.         may GOTO or GOSUB later.  Each label must start with a colon ":"
  1545.         character.  Normally, labels will occupy a line by themselves,
  1546.         however they may appear in a line containing other tokens.
  1547.       
  1548.       
  1549.       :EXIT
  1550.       
  1551.         This special label has been reserved for providing controlled
  1552.         shutdown commands.  This label must begin with the colon ":"
  1553.         character.  Whenever the <ESC> key is pressed, the interpreter
  1554.         will jump to the location where the :EXIT label is located and
  1555.         execute any commands placed after the label. Therefore, the
  1556.         :EXIT label should appear towards the end of the command file.
  1557.         Note that the :EXIT label is not mandatory.  If <ESC> is pressed
  1558.         and the :EXIT label does not appear in the file, then the
  1559.         interpreter simply aborts the remaining commands.  Examine the
  1560.         use of :EXIT in the next example below.
  1561.       
  1562.       
  1563.       {GOTO :label}
  1564.       
  1565.         These statements instruct XA to jump to a sequence of commands
  1566.         identified by the ":label" and begin executing them.  XA
  1567.         continues executing all remaining statements from that point.
  1568.         If XA has encountered ":label" previously, it will immediately
  1569.         jump to that location. Otherwise, XA will begin searching for
  1570.         ":label" in the remaining portion of the current file, or within
  1571.         other files that may have been "INCLUDED".
  1572.       
  1573.         NOTE: Earlier versions of XA used the following syntax:
  1574.       
  1575.               GOTO :label times
  1576.       
  1577.         where "times" acted as a counter.  This method is no longer
  1578.         supported. Use the conditional statements (IF/ELSE -
  1579.         "registered" versions only) instead to control looping.
  1580.       
  1581.         The following code flashes (turns ON and OFF) a module addressed
  1582.         as A1  three times. It uses a variable (see Section - Variables)
  1583.         named "COUNTER" that is incremented and tested every time the
  1584.         loop is executed. When COUNTER reaches 3, the IF portion of the
  1585.         test is no longer true, so XA continues with the rest of the
  1586.         program:
  1587.       
  1588.               COUNTER = 0         # Declare and initialize COUNTER to 0
  1589.            :loop
  1590.               A1 ON
  1591.               A1 OFF
  1592.               COUNTER = COUNTER + 1
  1593.               IF (COUNTER < 3)
  1594.                  GOTO :loop
  1595.               ENDIF
  1596.            :EXIT
  1597.               A1 OFF
  1598.       
  1599.                 XA - X10 Command Interpreter - Version 2.1                   30 
  1600.         Note the special use of the :EXIT label in the above example. If
  1601.         the user pressed the <ESC> during execution inside the loop, XA
  1602.         would abort the loop and search for the :EXIT label. If found,
  1603.         XA would execute the "A1 OFF" statement ensuring that the module
  1604.         was in a known state. Without :EXIT, XA would abort and possibly
  1605.         leave A1 in  the ON state.
  1606.       
  1607.         By using the LABEL and GOTO constructs, you can produce some
  1608.         pretty sophisticated lighting displays.  One application where
  1609.         this could be put to use is for Christmas lighting.  Consider
  1610.         placing solid color Christmas tree light strands on individual
  1611.         lamp dimmers.  Vary the brightness levels of each strand for an
  1612.         everchanging lighting effect. See the sample file XMAS.CMD for
  1613.         an example.
  1614.       
  1615.       {GOSUB :label}
  1616.       (statements go here...)
  1617.       RETURN
  1618.       
  1619.         These statements instruct XA to jump to a sequence of commands
  1620.         identified by ":label" and begin executing them. XA continues
  1621.         executing all remaining statements until it reaches the "RETURN"
  1622.         token. XA then returns control of the program to the point from
  1623.         which  it came.
  1624.       
  1625.         If XA has encountered ":label" previously, it will immediately
  1626.         jump to that location. Otherwise, XA will begin searching for
  1627.         ":label" in the remaining portion of the current file, or within
  1628.         other files that  may have been "INCLUDED".
  1629.       
  1630.         Placing a subroutine in a program allows you to repeat a
  1631.         sequence of statements in several places without writing the
  1632.         same statements several times.
  1633.       
  1634.         It is good practice to place subroutines in the beginning of the
  1635.         command file so that searching will be minimized. See the sample
  1636.         "XMAS.CMD" command file for an example.
  1637.       
  1638.         XA may call subroutines that are present in the current file, or
  1639.         any previously "included" file. You may nest up to 20 subroutine
  1640.         levels.
  1641.       
  1642.         The previous "flash" example (using GOTO's) could be rewritten
  1643.         to use GOSUBS as follows:
  1644.  
  1645.               GOSUB :flash      # Once...
  1646.               GOSUB :flash      # ...Twice
  1647.               GOSUB :flash      #    ...Three times
  1648.               STOP              # Tell XA to stop (prevents running into
  1649.                                 # subroutine)                      
  1650.             :flash              # Start of subroutine
  1651.               A1 ON
  1652.               A1 OFF
  1653.               RETURN            # Return to original caller
  1654.       
  1655.             :EXIT               # Special shutdown sequence...
  1656.               A1 OFF            # ...Ensure A1 is OFF
  1657.       
  1658.                 XA - X10 Command Interpreter - Version 2.1                   31 
  1659.       FAST
  1660.       
  1661.         By default, XA always waits for an acknowledgement message from
  1662.         the CP-290 after sending a direct command. You can avoid this
  1663.         wait and speed up the overall execution of XA by including the
  1664.         token "FAST" in your command:
  1665.       
  1666.               XA "PHONE_IN_USE  ON  FAST"
  1667.       
  1668.         FAST is best used in single command statements. If you attempt
  1669.         to send multiple direct commands using the FAST token, XA will
  1670.         be forced to wait for the acknowledgement message before issuing
  1671.         the remaining commands.
  1672.       
  1673.         Some computers may experience problems when XA executes a single
  1674.         statement in a batch file using the FAST token. Avoid using the
  1675.         FAST token when the TSR program "XT.EXE" is installed.  In some
  1676.         instances, XA may restore the old communication interrupt
  1677.         vectors while the acknowledgement message is in transit from the
  1678.         CP-290. This may result in XT reading an incomplete message.  It
  1679.         may take several messages for XT to correct itself.  You should
  1680.         experiment with your computer to see if this affects your setup.
  1681.       
  1682.       
  1683.       Communications Tokens
  1684.       ─────────────────────────────────────────────────────────────────────
  1685.       
  1686.       This group of tokens allow you configure XA for your particular
  1687.       computers communications setup. The following table lists the
  1688.       "standard" I/O port addresses as well as typical IRQ assignments
  1689.       for the first (4) serial ports.  Note the potential IRQ conflict
  1690.       that might arise with devices COM1/COM3 and COM2/COM4 because of
  1691.       the shared IRQ's.  If you have more than 2 devices attached to
  1692.       your computers serial ports, beware of this conflict and resolve
  1693.       it by assigning a different IRQ to the offending port.
  1694.       
  1695.                  Comm Port    I/O Address   IRQ Level
  1696.                  ---------   -----------   ---------
  1697.                     COM1      3F8H (Hex)       4
  1698.                     COM2      2F8H             3
  1699.                     COM3      3E8H             4
  1700.                     COM4      2E8H             3
  1701.       
  1702.       
  1703.       XA was designed to work using interrupt-driven communications
  1704.       allowing features such as "monitoring" to operate effectively.
  1705.       Since some users are unable to dedicate a unique IRQ for the
  1706.       CP-290 serial port, XA can be configured to to communicate in a
  1707.       "polled" fashion. Simply use the "i=0" command line option or
  1708.       "IRQ 0" statement in your XA.INI file.
  1709.       
  1710.       
  1711.                 XA - X10 Command Interpreter - Version 2.1                   32 
  1712.       COMx
  1713.       
  1714.         This token allows you to specify which comm port the interface
  1715.         is attached to.  This token was intended to be placed in the XA
  1716.         initialization and/or command files.
  1717.       
  1718.               COM3
  1719.       
  1720.         If your port IO address does not match those in the above table,
  1721.         then use the command line parameter [o=xxx], or the file mode
  1722.         token "IO" (see below) to customize the communication
  1723.         characteristics.
  1724.       
  1725.       
  1726.       {IO x}
  1727.       
  1728.         This option allows you to select a different IO address from the
  1729.         default 3F8H (hex).  If your serial port is setup for 2E8H, then
  1730.         use the following line in your command file:
  1731.       
  1732.               IO 2E8H
  1733.       
  1734.         Notes:
  1735.            *  When using HEXADECIMAL numbers, you must specify the H.  This is
  1736.               no longer implied.
  1737.       
  1738.            *  These tokens were intended to be placed in the initialization or
  1739.               command files.
  1740.  
  1741.       
  1742.       {IRQ x}
  1743.       
  1744.         This option allows you to select a different IRQ level from the
  1745.         default interrupt 4.  To use COM3 (an IO address of 3E8) with an
  1746.         IRQ level 5, use the following commands in the XA initialization
  1747.         file:
  1748.       
  1749.               IO 3E8H
  1750.               IRQ 5
  1751.       
  1752.         Use IRQ 0  for "polling mode" communications if you can't
  1753.         configure your system with a free IRQ for the CP-290 port. Note
  1754.         that operations such as Monitoring and Logging may not operate
  1755.         correctly in polled mode.
  1756.       
  1757.       
  1758.       I/O Port Control             ( ** Registered Version Only ** )
  1759.       ─────────────────────────────────────────────────────────────────────
  1760.       
  1761.       XA can read and write to most of the I/O ports. Of particular
  1762.       interest is the Joystick or Game port. This port (location 201
  1763.       Hex) provides up to four digital inputs. XA can read the state
  1764.       of these ports and react accordingly. See the sample command
  1765.       file "JOYSTICK.CMD" for an example of turning a light on or off
  1766.       based on the state of the joystick switch settings.
  1767.       
  1768.                 XA - X10 Command Interpreter - Version 2.1                   33 
  1769.       {(variable =) INPORT io_port}
  1770.       
  1771.         Read the status of the selected port, and optionally store it
  1772.         into a variable for later processing.  Example: Read the status
  1773.         of the Joystick port (201H) and save it into a variable called
  1774.         "joy_port".
  1775.       
  1776.               joy_port = INPORT 201H
  1777.       
  1778.       
  1779.       {OUTPORT io_port value}
  1780.       
  1781.         Output a byte value to the selected io_port.
  1782.       
  1783.       
  1784.       
  1785.                * * * * *   IMPORTANT NOTE    * * * * *
  1786.       
  1787.       When dealing with IO ports, make sure you know what you are
  1788.       doing.  Connecting devices that should not be connected to a
  1789.       port may cause damage to your computer, its peripherals, even
  1790.       you. Be careful that you are writing to the proper ports,
  1791.       otherwise you may crash your system.  If you are not sure what
  1792.       you are doing, then you better not do it. I will in no way be
  1793.       responsible for your use, misuse, or abuse  you might possibly
  1794.       inflict on you or your computer.
  1795.       
  1796.       
  1797.       
  1798.       Miscellaneous Tokens
  1799.       ─────────────────────────────────────────────────────────────────────
  1800.       
  1801.       {DEFINE x z}
  1802.       
  1803.         This token is designed to be used in initialization or command
  1804.         files.  It allows you to substitute several tokens into a single
  1805.         token of your choice. It will help to make command files more
  1806.         readable.  For example, you can assign the token:
  1807.       
  1808.               "XMAS_ON"
  1809.       
  1810.         to an equivalent group of tokens, such as:
  1811.       
  1812.               "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY"
  1813.       
  1814.         as follows:
  1815.       
  1816.               DEFINE   XMAS_ON   HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
  1817.                        <--x-->   <----------------- z ----------------->
  1818.       
  1819.         Notice that the "x" portion uses underscore characters "_" to
  1820.         separate the words but to keep the string contiguous.  This is
  1821.         important because the XA interpreter looks for the first SPACE
  1822.         character to separate the "x" and "z" components.  All
  1823.         subsequent SPACE characters are ignored.
  1824.       
  1825.                 XA - X10 Command Interpreter - Version 2.1                   34 
  1826.         Later in the command file, you can use the following command to
  1827.         activate your Christmas lights:
  1828.       
  1829.               XMAS_ON
  1830.       
  1831.         Internally, XA will convert this string to its equivalent:
  1832.       
  1833.               HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
  1834.       
  1835.         More Examples:
  1836.                  :
  1837.               DEFINE PLANT_GROW_LIGHTS A8
  1838.               DEFINE OUTSIDE_LIGHTS A1
  1839.               DEFINE ALL_ON ALL_LIGHTS_ON HOUSE A ON
  1840.                  :
  1841.               PLANT_GROW_LIGHTS ON TIME 6:00 AM EVERYDAY
  1842.               PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY
  1843.                  :
  1844.               OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
  1845.                  :
  1846.               ALL_ON SUNDAY TIME 7:30 PM
  1847.       
  1848.         The use of DEFINES is helpful if you want to monitor the CP-290
  1849.         for events as they occur.  See Section - Monitoring.
  1850.       
  1851.       {EVENT xxx}
  1852.       
  1853.         The CP-290 can store up to 128 events in its memory.  Each event
  1854.         occupies fixed locations in memory.  Prior to XA Version 2.0 you
  1855.         were required to assign a unique event number if you did not
  1856.         want to overwrite an existing event.  Since XA now automatically
  1857.         determines the next available slot for you, there is little need
  1858.         for these tokens.  However, these tokens remain as part of XA
  1859.         should you need to overwrite a particular event.
  1860.       
  1861.         When you produce a report file, the event number assigned to
  1862.         each event is printed in the right-most column of the  listing.
  1863.         If you produced a report file while using the "-e" (no command
  1864.         execution), then the event number displayed will be -1,
  1865.         signifying that the event is not stored in the CP-290.
  1866.       
  1867.       {CLEAR EVENT xxx}
  1868.       
  1869.         These tokens delete the specified event from the computer
  1870.         interface.  See description for EVENT xxx above. Only 1 event
  1871.         may be cleared per  command.
  1872.       
  1873.               XA "CLEAR EVENT 100" "CLEAR EVENT 101"
  1874.       
  1875.         When an event is cleared from the interface, the actual memory
  1876.         locations it occupied are cleared to zero.  All subsequent
  1877.         events remain in their assigned memory locations.  Use the
  1878.         report listing to display each events number (or location) in
  1879.         the CP-290. This number is printed in the right-most column of
  1880.         the report.  Any event numbers that are followed by an asterisk
  1881.         "*" indicate that the event  will be  triggered on multiple days.
  1882.       
  1883.                 XA - X10 Command Interpreter - Version 2.1                   35 
  1884.       ERASE
  1885.       
  1886.         This token erases all events from the CP-290 memory. If you use
  1887.         XA to maintain you CP-290 schedules, then this token should
  1888.         appear at the beginning of the command file. This is important
  1889.         because XA tries to append new events to the existing events in
  1890.         the CP-290.  If you do not erase the CP-290 memory, you will
  1891.         exceed its 128 event capacity.
  1892.       
  1893.         Always use this token when specific dates (declared by the
  1894.         DATE/THRU tokens) are present in your command file.  This way,
  1895.         once the date has come and gone, it will be deleted from the
  1896.         CP-290 memory automatically.
  1897.       
  1898.       
  1899.       {BASECODE x}
  1900.       
  1901.         These tokens change the base housecode of the interface WITHOUT
  1902.         losing the data stored in the interface. Prior to changing the
  1903.         housecode, a complete upload of all events stored in the
  1904.         interface is  performed.  The housecode is changed, then all
  1905.         events are downloaded  back into the interface.  Valid
  1906.         housecodes are A...P.
  1907.       
  1908.               XA "BASECODE D"
  1909.       
  1910.         XA displays a bar graph during the upload and download phases
  1911.         providing a visual indication of progress, as well as the amount
  1912.         of  available event storage.
  1913.       
  1914.       
  1915.       DIAGNOSE
  1916.       
  1917.         This token triggers the CP-290's built-in diagnostic routine.
  1918.         You will be informed of the results after a few seconds.  Since
  1919.         the diagnostics overwrite any existing events, XA first uploads
  1920.         the contents of the CP-290 memory prior to the diagnostic.  If
  1921.         the diagnostics report an OK status, then the events are
  1922.         downloaded back to the CP-290.
  1923.       
  1924.       
  1925.       {XACMD filename}
  1926.       
  1927.         This token is intended to be placed inside the XA initialization
  1928.         file (XA.INI - see next section).  It defines the default
  1929.         command file that XA should parse and execute if no other
  1930.         commands files or direct commands are present.  If your XA.INI
  1931.         file contains the following  line:
  1932.       
  1933.               XACMD EVENTS.CMD
  1934.       
  1935.         Then each time XA is invoked without any arguments, the file
  1936.         "EVENTS.CMD" will be parsed and executed.
  1937.       
  1938.                 XA - X10 Command Interpreter - Version 2.1                   36 
  1939.         The following examples show how you can specify unique command
  1940.         files based on the day of the week (see later section for
  1941.         IF/ELSE  programming):
  1942.       
  1943.               IF ((CDAY == MON) OR (CDAY == WED) OR (CDAY == FRI))
  1944.                  XACMD M_W_F.CMD
  1945.               ELSE
  1946.                  XACMD XA.CMD
  1947.               ENDIF
  1948.       
  1949.       
  1950.       {INCLUDE filename}
  1951.       
  1952.         These tokens allow XA to parse additional files.  When XA reads
  1953.         the "INCLUDE filename" statement, it begins to parse the
  1954.         requested file.  Upon reaching the end of the new file, XA will
  1955.         begin parsing the original file at the statement following the
  1956.         INCLUDE.  This concept  is similar to calling and returning from
  1957.         a subroutine.
  1958.       
  1959.         The include file may be called from your XA.INI as well as
  1960.         XA.CMD (or any other file). Include files may be nested up to 20
  1961.         levels deep.  The following example shows you how XA.CMD could
  1962.         include VACATION.CMD if the current date (CDATE) falls between
  1963.         AUG 21 and AUG 28.
  1964.       
  1965.               IF ((CDATE >= DATE 8/21) AND (CDATE <= DATE 8/28))
  1966.                  INCLUDE VACATION.CMD
  1967.               ENDIF
  1968.       
  1969.       
  1970.       {DOS command_string}
  1971.       
  1972.         The DOS token allows you to execute any DOS command from within
  1973.         XA.  The following line (taken from JOYSTICK.CMD) tells the
  1974.         SoundBlaster to play the GREETING.VOC file:
  1975.       
  1976.               DOS c:\sblaster\vplay c:\sblaster\greeting.voc
  1977.       
  1978.         Display a directory:
  1979.       
  1980.               DOS dir
  1981.       
  1982.         Use XA to kickoff a communications program at a precise time
  1983.         (see PHONE.CMD):
  1984.       
  1985.               # At 11:15, Call BBS...
  1986.               DISPLAY OFF
  1987.               :WAIT
  1988.               IF (CTIME < TIME 11:15 PM)
  1989.                  GOTO :WAIT
  1990.               ENDIF
  1991.               DOS PROCOMM options...     # Invoke PROCOMM with command line
  1992.                                          # parameters...
  1993.       
  1994.       
  1995.                 XA - X10 Command Interpreter - Version 2.1                   37 
  1996.       BEEP
  1997.       
  1998.         The BEEP token will issue a short tone through your PC's speaker.
  1999.       
  2000.       
  2001.       {DISPLAY ON}
  2002.       {DISPLAY OFF}
  2003.       
  2004.         XA will display just about every statement as its parsed. There
  2005.         may be instances where you don't want the display active, for
  2006.         instance, parsing the XA.INI file, comments, or when critical
  2007.         loops are being  processed. XA allows you to control the display
  2008.         with the commands:
  2009.       
  2010.               DISPLAY ON
  2011.               DISPLAY OFF
  2012.       
  2013.         In some instances, it will be necessary to turn the command
  2014.         display off because of time considerations. If you are in a
  2015.         tight loop monitoring an IO port for a bit to change, you may
  2016.         miss the toggle while XA is printing the current statement to
  2017.         the CRT. By turning the display off, you allow XA to execute
  2018.         much faster, virtually eliminating any bottlenecks that may
  2019.         cause XA to miss an event from the port.
  2020.       
  2021.         The sample XA.INI file shipped with this version has the display
  2022.         turned off at the start of the file, and restores the display at
  2023.         the  end of the file.
  2024.       
  2025.       
  2026.       
  2027.       Reporting Tokens
  2028.       ─────────────────────────────────────────────────────────────────────
  2029.       
  2030.       MONITOR
  2031.       
  2032.         This token informs XA to continuously monitor the communications
  2033.         port for any messages sent by the CP-290 when it executes a
  2034.         stored event or when one of the panel buttons is pressed.
  2035.       
  2036.         "Monitor" and its command line counterpart "+m" may operate
  2037.         differently based on your XA configuration.  See section -
  2038.         "Monitoring and Logging Events" for more information.
  2039.       
  2040.       
  2041.       LOG
  2042.       
  2043.         This token appends the monitored information in the file XA.LOG.
  2044.       
  2045.       
  2046.       REPORT1
  2047.       
  2048.         This token will produce a report file with events sorted by day
  2049.         and  time.
  2050.       
  2051.       
  2052.                 XA - X10 Command Interpreter - Version 2.1                   38 
  2053.       REPORT2
  2054.       
  2055.         This token will produce a report file with events sorted by day,
  2056.         module, and time.
  2057.       
  2058.       
  2059.       Powerfail Recovery
  2060.       ─────────────────────────────────────────────────────────────────────
  2061.       
  2062.       Powerfail recovery allows you to restore each module to its
  2063.       scheduled state. By default, XA uses the last 6 days to
  2064.       determine the state.  You can tell XA to use additional days if
  2065.       necessary.  Also, you can tell XA to FORCE a module to a
  2066.       particular state overriding the calculated state, or have XA
  2067.       IGNORE the calculated state and not send any command to the
  2068.       module.
  2069.       
  2070.       Powerfail recovery may be invoked from the command line using
  2071.       the following parameters:
  2072.       
  2073.         +P   - parses command file, then performs recovery.
  2074.       
  2075.         -P   - immediate recovery, no parsing of command file.
  2076.       
  2077.       If you want XA to review the event schedule of the previous 4
  2078.       days in order to determine the correct state, then append a 4 to
  2079.       the command, for example -P4 or +P4.  The maximum number of days
  2080.       that XA can scan is 6.  XA uses the information stored in the
  2081.       file X10.DAT for the schedule calculations because it's faster
  2082.       than uploading all the data from the CP-290.  Also, if you
  2083.       change your schedule with X10's original software package
  2084.       (X10.EXE), those changes will be reflected properly.  If XA can
  2085.       not find the X10.DAT, then XA will upload the data from the
  2086.       CP-290.
  2087.       
  2088.       Use the command line option "-e" in conjunction with powerfail
  2089.       recovery to see how XA would have restored each module without
  2090.       sending any X10 commands:
  2091.       
  2092.               XA -e -p
  2093.       
  2094.       There are two token statements which can override powerfail's
  2095.       determined module state. These overrides may be used for certain
  2096.       modules that do not have any programmed events stored in the
  2097.       CP-290.
  2098.       
  2099.       
  2100.       {FORCE module state}
  2101.       
  2102.         Forces a module to a desired state, no matter what powerfail
  2103.         recovery  thinks it should be in. "Module"  can be a module
  2104.         address (A1) or pre-defined name (STAIRS). "State" can be any of
  2105.         the following X10 commands:
  2106.       
  2107.                  ON, OFF, DIM %%
  2108.       
  2109.       
  2110.                 XA - X10 Command Interpreter - Version 2.1                   39 
  2111.         Example (from XA.INI):
  2112.       
  2113.               FORCE P_C ON
  2114.       
  2115.       
  2116.       
  2117.         You can "force" a module from the command line too, thus
  2118.         overriding the calculated state:
  2119.       
  2120.               XA "FORCE DEN OFF" -P
  2121.       
  2122.       
  2123.       {IGNORE module}
  2124.       
  2125.         Ignores sending any command to module during a powerfail
  2126.         recovery.
  2127.       
  2128.         "Module" can be a module address or pre-defined name
  2129.       
  2130.         Example:
  2131.       
  2132.               IGNORE DEHUMIDIFIER
  2133.       
  2134.         You can tell XA to ignore any actions to a module from the
  2135.         command line too:
  2136.       
  2137.               XA "IGNORE BEDROOM_LAMP" -P
  2138.       
  2139.       
  2140.                 XA - X10 Command Interpreter - Version 2.1                   40 
  2141.       Screen Color Control
  2142.       ─────────────────────────────────────────────────────────────────────
  2143.       
  2144.       Screen color control lets you program how commands should be
  2145.       displayed.  You will be able to tell at a glance how certain
  2146.       conditional statements IF/ELSE, DATE/THRU/EXCEPT were evaluated
  2147.       by XA just by looking at the display.
  2148.       
  2149.       {VIDEO1 Foreground Background}
  2150.       
  2151.         IF or ELSE expression is TRUE (registered version).
  2152.       
  2153.       
  2154.       {VIDEO2 Foreground Background}
  2155.       
  2156.         IF or ELSE expression is FALSE (registered version), or
  2157.         DATE/THRU/EXCEPT evaluates to FALSE.
  2158.       
  2159.       
  2160.       {VIDEO3 Foreground Background}
  2161.       
  2162.         Statements resulting in DIRECT commands being sent to CP-290
  2163.       
  2164.       
  2165.       {VIDEO4 Foreground Background}
  2166.       
  2167.         Statements resulting in EVENTS being sent to CP-290.
  2168.       
  2169.       
  2170.       {VIDEO5 Foreground Background}
  2171.       
  2172.         Important messages reported by XA.
  2173.       
  2174.       
  2175.       {VIDEO6 Foreground Background}
  2176.       
  2177.         All other non event or command statements processed by XA.
  2178.       
  2179.         FOREGROUND may be any of the following:
  2180.               BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
  2181.               DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
  2182.               LIGHTMAGENTA, YELLOW, WHITE
  2183.       
  2184.         BACKGROUND may be any of the following:
  2185.               BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
  2186.       
  2187.         To display a "TRUE" IF/ELSE statement in GREEN foreground
  2188.         characters on a BLACK background, and  a "FALSE" IF/ELSE (or
  2189.         DATE/THRU/EXCEPT) statement in RED foreground characters on a
  2190.         BLACK background:
  2191.               VIDEO1 GREEN BLACK
  2192.               VIDEO2 RED BLACK
  2193.       
  2194.         To display a DIRECT command (XA "P1 ON") in YELLOW on BLACK:
  2195.               VIDEO3 YELLOW BLACK
  2196.       
  2197.                 XA - X10 Command Interpreter - Version 2.1                   41 
  2198.       ═════════════════════════════════════════════════════════════════════
  2199.       10.  Programming Additions          ( ** Registered Version Only ** )
  2200.       ═════════════════════════════════════════════════════════════════════
  2201.       
  2202.       Variables
  2203.       ─────────────────────────────────────────────────────────────────────
  2204.       
  2205.       Variables are user-defined objects which may be assigned values,
  2206.       or examined. You can assign numbers, dates, times, port data,
  2207.       true/false data into a variable.
  2208.       
  2209.       Variables are dynamically created at the first instance when XA
  2210.       parses a token that is not part of the normal XA language. For
  2211.       instance, the following statement declares a variable called
  2212.       VACATION, because VACATION is not part of XA's syntax.
  2213.       
  2214.            vacation = WEEKEND
  2215.       
  2216.       Internally, variables are treated as 32 bit integer values. When
  2217.       variables are created they are initialized to 0 as soon as they
  2218.       are parsed. However, they may be assigned a different value in
  2219.       the declaring statement. In the above example, "VACATION" was
  2220.       assigned the value WEEKEND (the internal value is set to 96, or
  2221.       60 Hex - but you  don't really need to know that).
  2222.       
  2223.       The next example declares a variable called "ATHOME", assigning
  2224.       it a value of 1.
  2225.       
  2226.               DEFINE TRUE    1
  2227.               DEFINE FALSE   0
  2228.               ATHOME = TRUE
  2229.       
  2230.       First, we define constants TRUE and FALSE to be 1 and 0
  2231.       respectively.  Next, we declare a variable called ATHOME.
  2232.       Internally, the variable is created and initialized to 0. The
  2233.       statement is parsed further, the assignment operator "=" sets
  2234.       ATHOME equal to TRUE (or 1).
  2235.       
  2236.       When declaring variable, the first character in its name should
  2237.       begin with an ALPHA character, that is, A...Z. You can then use
  2238.       numbers as part of the name, but they must not start the name.
  2239.       All characters are  converted to UPPERCASE.  The list of legal
  2240.       characters are:
  2241.       
  2242.               ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_
  2243.       
  2244.       
  2245.       Examples:
  2246.       
  2247.               BIRTHDAY   <--- This is OK!
  2248.               1_BIRTHDAY   <--- Can't start with a numeric value
  2249.               BIRTH,DAY   <--- Comma not a valid character
  2250.       
  2251.       
  2252.                 XA - X10 Command Interpreter - Version 2.1                   42 
  2253.       Hexadecimal Notation
  2254.       ─────────────────────────────────────────────────────────────────────
  2255.       
  2256.       Hexadecimal notation specifies an integer value in base 16 or
  2257.       "hex" (hexadecimal).  When writing computer programs, it is
  2258.       sometimes easier  to work in this base than the normal base 10.
  2259.       A hex value has 3  parts:
  2260.       
  2261.         0 NNNNNNN H
  2262.       
  2263.         where:
  2264.       
  2265.              0 - A leading zero is required if the first digit of the hex
  2266.                  number is an alphabetic character (A...F) so that XA can
  2267.                  distinguish it as a number and not a variable name. A leading
  2268.                  zero may also be used in front of a numeric character in the
  2269.        hex
  2270.                  number just as in a normal integer constant (0987H = 987H).
  2271.       
  2272.        NNNNNNN - The eight Ns represent the 8 hexadeciaml digits in the
  2273.                  range of 0...F.
  2274.       
  2275.              H - The trailing H indicates the number is hex and is always
  2276.                  required.
  2277.       
  2278.       
  2279.         Example:
  2280.       
  2281.               IO 3E8H
  2282.       
  2283.       
  2284.       
  2285.       Note: previous versions of XA assumed hex numbers for certain
  2286.       tokens (such as IO). This is no longer the case!
  2287.       
  2288.       
  2289.       Pre-Defined Variables:
  2290.       ─────────────────────────────────────────────────────────────────────
  2291.       
  2292.       XA maintains several built-in variables that are accessible by
  2293.       your programs. These variables are:
  2294.       
  2295.       CDATE
  2296.       
  2297.         The current date (month-day-year).
  2298.       
  2299.         Internally, XA maintains the current date as a 32 bit long
  2300.         integer. CDATE is actually the number of days since 1/1/1970.
  2301.         You can perform simple math and logical operations to this
  2302.         variable to test for special conditions. For instance, to run a
  2303.         special command file called XMAS.CMD between Thanksgiving and
  2304.         New Years Eve:
  2305.       
  2306.               IF ((CDATE >= DATE 11/25) AND (CDATE <= DATE 12/31))
  2307.                  INCLUDE XMAS.CMD
  2308.               ENDIF
  2309.       
  2310.       
  2311.                 XA - X10 Command Interpreter - Version 2.1                   43 
  2312.         When comparing dates with CDATE, make sure you specify the DATE
  2313.         token:
  2314.       
  2315.               IF (CDATE == 12/25)      <--- This is WRONG!
  2316.               IF (CDATE == DATE 12/25) <--- This is CORRECT!
  2317.       
  2318.       
  2319.       
  2320.       CDAY
  2321.       
  2322.         The current day of the week (MON, TUE, WED...)
  2323.       
  2324.         Internally, XA maintains the current day as an X10 bit-pattern,
  2325.         that is MON = 1, TUE = 2, WED = 4, ...SUN = 40Hex. The Day
  2326.         Tokens (MON, TUE... SUN) are also mapped to these values, so you
  2327.         can use them in conjunction with logical operations when
  2328.         determining special days. The file XMAS.CMD performs a test on
  2329.         CDAY to see if its FRI or SAT, thus allowing the Christmas
  2330.         lights to stay on longer:
  2331.       
  2332.               IF ((CDAY == FRI) OR (CDAY == SAT))
  2333.                  IF (CTIME >= TIME 11:30 PM)
  2334.                     GOTO EXIT
  2335.                  ENDIF
  2336.               ELSE
  2337.                  IF (CTIME >= TIME 10:30 PM)
  2338.                     GOTO EXIT
  2339.                  ENDIF
  2340.               ENDIF
  2341.               GOTO LOOP         # It's not time yet, repeat the loop.
  2342.       
  2343.       
  2344.       
  2345.       CTIME
  2346.       
  2347.         The current time (in 24-hour format)
  2348.       
  2349.         Internally, XA maintains the current time as the number of
  2350.         seconds since midnight.  You can perform arithmetic and logical
  2351.         operations on this variable by using the TIME token. See the
  2352.         previous example for a way of leaving Christmas lights on until
  2353.         11:30 pm on FRI and SAT nights, all other nights they are
  2354.         shutdown at 10:30 pm.
  2355.         
  2356.       Operators
  2357.       ─────────────────────────────────────────────────────────────────────
  2358.       
  2359.         Operators allow some kind of operation to be performed to
  2360.         variables and constants. Operators are evaluated as they are
  2361.         parsed from left to right.  When an expression is contained in
  2362.         parentheses, that expression will be evaluated first. When
  2363.         nested parentheses are present, the inner most expression is
  2364.         evaluated, then the one immediately outside of it, and so on.
  2365.       
  2366.                 XA - X10 Command Interpreter - Version 2.1                   44 
  2367.       Arithmetic Operators
  2368.       ─────────────────────────────────────────────────────────────────────
  2369.       
  2370.       
  2371.            Operator    Function    Example
  2372.            ========    ========    =========
  2373.               *        Multiply    A = B * C
  2374.               /        Divide      B = A / C
  2375.               +        Addition    C = A + B
  2376.               -        Subtraction A = C - B
  2377.               -        Unary Minus A = -B
  2378.       
  2379.       
  2380.       Relational Operators
  2381.       ─────────────────────────────────────────────────────────────────────
  2382.       
  2383.            Operator    Function
  2384.            ========    =============================
  2385.               =        Assigns a value to a variable
  2386.               <        Less than
  2387.               >        Greater than
  2388.               <=       Less than or equal
  2389.               >=       Greater than or equal
  2390.               <>       Not equal
  2391.               ==       Equals (values match)
  2392.       
  2393.       
  2394.       Logical Operators
  2395.       ─────────────────────────────────────────────────────────────────────
  2396.       
  2397.       Produce either a FALSE (0) or TRUE (1) result
  2398.       
  2399.            Operator    Function
  2400.            ========    =============================
  2401.               AND      Logical AND
  2402.               &&       Logical AND (same as AND)
  2403.               OR       Logical OR
  2404.               ||       Logical OR (same as OR)
  2405.               !        NOT
  2406.       
  2407.       
  2408.       Truth Table for logical operators
  2409.       ─────────────────────────────────────────────────────────────────────
  2410.       
  2411.               A    B   A AND B   A OR B    ! A
  2412.              ===  ===  =======  =======    ===
  2413.               0    0      0        0        1
  2414.               0    1      0        1        1
  2415.               1    0      0        1        0
  2416.               1    1      1        1        0
  2417.       
  2418.       
  2419.       
  2420.       
  2421.       
  2422.                 XA - X10 Command Interpreter - Version 2.1                   45 
  2423.       Bitwise Logical Operators
  2424.       ─────────────────────────────────────────────────────────────────────
  2425.       These operators are used to mask off some set of bits (AND), or
  2426.       to turn on some bits (OR). You will need these when using XA in
  2427.       conjunction with IO ports.
  2428.       
  2429.            Operator    Function
  2430.            ========    =============================
  2431.               |        Bitwise OR
  2432.               &        Bitwise AND
  2433.       
  2434.       IF/ELSE/ENDIF Statements
  2435.       ─────────────────────────────────────────────────────────────────────
  2436.       
  2437.       The IF/ELSE/ENDIF statement provides a transfer of control based
  2438.       on the result of a relational or comparison expression. The
  2439.       IF/ELSE/ENDIF statement has the following format:
  2440.       
  2441.            IF (expression)
  2442.               statements
  2443.            [ ELSE
  2444.               statements ]
  2445.            ENDIF
  2446.       
  2447.       The expression within parentheses is evaluated. If the
  2448.       expression evaluates to TRUE, then the series of statements
  2449.       starting on the next line are executed. If the expression
  2450.       evaluates to FALSE, and there is an ELSE clause, then the series
  2451.       of statements on the lines following the ELSE will be executed.
  2452.       The ELSE clause is optional. If there is no ELSE clause, then
  2453.       execution continues immediately following the ENDIF statement.
  2454.       
  2455.       Conditional IF/ELSE/ENDIF statements may be nested up to 100
  2456.       levels deep.
  2457.       
  2458.            IF (1 < 2)
  2459.               IF (2 < 3)
  2460.                  IF (3 < 4)
  2461.                     A = 5
  2462.                  ENDIF
  2463.               ENDIF
  2464.            ENDIF
  2465.       
  2466.       Each conditional expression must finish with an ENDIF clause so
  2467.       the parser can evaluate further statements.
  2468.       
  2469.       Indentation is used throughout these examples and you are urged
  2470.       to indent your programs too. Proper indentation makes your
  2471.       program much easier to read.  Complex conditional statements may
  2472.       be evaluated. The above example could be rewritten as:
  2473.       
  2474.            IF ((1 < 2) AND (2 < 3) AND (3 < 4))
  2475.               A = 5
  2476.            ENDIF
  2477.       
  2478.       Use parentheses () to group individual expressions. Grouping
  2479.       ensures that expressions are evaluated correctly, as well as
  2480.       makes your program more readable.
  2481.       
  2482.                 XA - X10 Command Interpreter - Version 2.1                   46 
  2483.       ═════════════════════════════════════════════════════════════════════
  2484.       11.  XA.INI - Initialization file
  2485.       ═════════════════════════════════════════════════════════════════════
  2486.       
  2487.       XA supports the use of an initialization file called XA.INI.
  2488.       This file is intended to hold tokens and communication
  2489.       parameters that you use regularly.  For instance, the following
  2490.       tokens are ideal candidates for inclusion in the initialization
  2491.       file:
  2492.       
  2493.               COMx           - Communication port
  2494.               IO x           - Special IO port address
  2495.               IRQ x          - Special IRQ level
  2496.               DEFINE x y     - Place as many DEFINE statements as you want
  2497.               LATITUDE dms   - The latitude of your city
  2498.               LONGITUDE dms  - The longitude of your city
  2499.               TIMEZONE x     - Your timezone
  2500.               DST            - If Daylight Savings is observed
  2501.               XACMD file     - The command file to use as a default
  2502.       
  2503.       This file, always called XA.INI, is the very first file that the
  2504.       XA parser looks for.  If it is found in the current directory
  2505.       (or the directory specified by the XA environment variable - see
  2506.       Installation) then the file is scanned for all tokens described
  2507.       above. These tokens are then used to define modules or override
  2508.       default communication parameters.
  2509.       
  2510.       The following example is taken from the file XA.INI distributed
  2511.       with this software.
  2512.       
  2513.               DEFINE P_C C1
  2514.               DEFINE DEN A5
  2515.               DEFINE GARAGE A1
  2516.                  :
  2517.               LATITUDE 41°35'
  2518.               LONGITUDE 81°20'
  2519.               TIMEZONE 5 DST
  2520.                  :
  2521.               COM3
  2522.               IRQ 5
  2523.       
  2524.       Since XA.INI is always parsed, this allows you to send
  2525.       descriptive X10 commands that don't rely on your memory for the
  2526.       actual house and unit codes.  For instance:
  2527.       
  2528.               XA "DEN ON"
  2529.       
  2530.       turns ON the unit at Housecode A Unit 5.
  2531.       
  2532.       Do not place events or direct commands in this file because they
  2533.       will not be executed.  XA is only looking for tokens that
  2534.       describe your particular setup.  Events and direct commands
  2535.       should be placed in command files (see next section).
  2536.       
  2537.                 XA - X10 Command Interpreter - Version 2.1                   47 
  2538.       You may place comments in your initialization file.  A comment
  2539.       is delineated by the pound sign character "#".  The comment
  2540.       symbol may appear in any column. Once XA sees the comment, the
  2541.       rest of the line is ignored.  Therefore, comments can be placed
  2542.       in front of tokens you do not want to be parsed by the
  2543.       interpreter at this time.
  2544.       
  2545.            # This is an example comment. Place them after statements too:
  2546.            LATITUDE  41°35'          # Latitude of Mentor, OH.
  2547.       
  2548.       When creating this file, use an editor or word processor that
  2549.       stores its files in pure ascii format.  Otherwise the formatting
  2550.       characters that the word processor embeds within the file will
  2551.       confuse the XA parser.
  2552.       
  2553.       The token XACMD specifies the default command file that should
  2554.       be executed if no direct command was included at the DOS prompt.
  2555.        The next section describes what command files are and how they
  2556.       are used with XA.
  2557.       
  2558.       
  2559.       
  2560.       ═════════════════════════════════════════════════════════════════════
  2561.       12.  Command Files
  2562.       ═════════════════════════════════════════════════════════════════════
  2563.       
  2564.       Since the CP-290 is only capable of storing a single weeks worth
  2565.       of events, command files were created to allow easy updates of
  2566.       the events that may need to be revised due to ever-changing
  2567.       conditions such as sunrise and sunset times.  Also, specific
  2568.       date information may be contained within this file.  XA has the
  2569.       capability to interpret these dates and update the CP-290
  2570.       accordingly. See the sample command  file "XA.CMD" (included in
  2571.       this package) I use for automating events  in my home.
  2572.       
  2573.       Command files work very well for executing a series of direct
  2574.       commands too. See the sample file XMAS.CMD for an example of an
  2575.       X10 lighting script.
  2576.       
  2577.       Command files should only be created with an editor or word
  2578.       processor  that saves files in pure ASCII format.  Any
  2579.       extraneous characters or control codes will cause the XA
  2580.       interpreter to ignore your commands.  XA defaults to reading a
  2581.       command file if there are no commands in the command line and as
  2582.       long as the statement  "XACMD filename" was included in your
  2583.       XA.INI file. You may override the default command file by using
  2584.       the "f=filename" option when starting XA.  For example, if you
  2585.       wanted to execute the commands found in a file called
  2586.       'MONITOR.CMD', you would start the XA utility as:
  2587.       
  2588.               XA f=MONITOR.CMD
  2589.       
  2590.                 XA - X10 Command Interpreter - Version 2.1                   48 
  2591.       Prior to Version 2.0, XA would only execute either command files
  2592.       or commands passed as arguments to XA on the DOS command line -
  2593.       NOT  BOTH.  With version 2.0, you can execute both types at the
  2594.       same time, however the file must be specified using the
  2595.       "f=filename" syntax.  This is very useful when you want to pass
  2596.       a variable to a command file (Registered version only). For
  2597.       example, suppose your normal command file (XA.CMD) contains
  2598.       special lighting events that you activate when you plan on
  2599.       vacationing for the weekend:
  2600.       
  2601.           XA.CMD:
  2602.       
  2603.               # Normal Events...
  2604.               GARAGE ON SUNSET WEEKDAYS
  2605.                  ...
  2606.               # Special Vacation Events...
  2607.               if (vacation)
  2608.                  HALLWAY ON TIME 9:30 PM WEEKENDS SECURITY
  2609.                  HALLWAY OFF TIME 11:30 WEEKENDS RANDOM 10
  2610.                  STEREO ON TIME 3:30 PM WEEKENDS RANDOM 15
  2611.                  STEREO OFF TIME 11:15 PM WEEKENDS RANDOM 5
  2612.               endif
  2613.       
  2614.       
  2615.       To activate the vacation sequence, you must specify both XA.CMD
  2616.       and set the vacation variable to TRUE:
  2617.       
  2618.               XA f=XA.CMD "VACATION = 1"
  2619.       
  2620.       
  2621.                 XA - X10 Command Interpreter - Version 2.1                   49 
  2622.       ═════════════════════════════════════════════════════════════════════
  2623.       13.  Initialization file, Command files, and Command Line Options
  2624.       ═════════════════════════════════════════════════════════════════════
  2625.       
  2626.       This section tries to clear any confusion you may have about the
  2627.       initialization file, command files, and command line options.
  2628.       Each serves a unique purpose, offering a very easy and flexible
  2629.       means of  controlling your X10 equipment.  As discussed earlier,
  2630.       XA provides the mechanism for controlling the CP-290 via the DOS
  2631.       prompt (including batch files) or from a text-based file.  XA
  2632.       distinguishes which mode of operation it takes by examining the
  2633.       way you invoked XA.  If any direct (or immediate) commands are
  2634.       present, then XA sends the command directly to the CP-290.  For
  2635.       instance, the following is a direct command:
  2636.       
  2637.               XA "A5 ON"
  2638.       
  2639.       It's nicer to assign a meaningful name to your modules, so XA
  2640.       allows you to place these names in an initialization file called
  2641.       "XA.INI".  You define a module using the following token syntax:
  2642.       
  2643.       
  2644.               DEFINE DEN A5
  2645.       
  2646.       Now you can activate the same module using a descriptive (and
  2647.       easier  to remember) name:
  2648.       
  2649.               XA "DEN ON"
  2650.       
  2651.       Other items may also appear in the intialization file.  If your
  2652.       computer communicates with the CP-290 via COM3 serial port, then
  2653.       you may place the token "COM3" within the XA.INI too.  XA always
  2654.       looks at  this file before attempting any communication with the
  2655.       CP-290.  Other tokens that XA looks for are:
  2656.       
  2657.               IRQ, IO, LATITUDE, LONGITUDE, TIMEZONE, DST, XACMD, DEFINE, COMx
  2658.       
  2659.       After parsing the XA.INI file, XA then looks to see if the
  2660.       "f=filename" option was specified on the command line. This
  2661.       allows you to override the default command file you may have
  2662.       specified by using the XACMD token in the XA.INI file.  Next,
  2663.       the command line options are scanned. Any options defined here
  2664.       will override all previous options declared by the
  2665.       initialization file.  If a file and a series of commands are
  2666.       placed in the XA command line, then XA will execute the command
  2667.       and the file.  This allows you to set variables to a specific
  2668.       value and later evaluated so special actions can be taken inside
  2669.       your command file. See the previous section for more details.
  2670.       
  2671.       
  2672.                 XA - X10 Command Interpreter - Version 2.1                   50 
  2673.       ═════════════════════════════════════════════════════════════════════
  2674.       14.  Report Files
  2675.       ═════════════════════════════════════════════════════════════════════
  2676.       
  2677.       XA can produce a report of all events that were just parsed by
  2678.       the interpreter.  These reports come in 2 styles:
  2679.       
  2680.            *  Events sorted by day and time
  2681.       
  2682.            *  Events sorted by day, module, and time.
  2683.       
  2684.       You have the option of selecting any style, or both styles.  The
  2685.       report file will be created after the events have been
  2686.       downloaded to the CP-290.  The file is named "XA.RPT", and is
  2687.       located in the same drive and directory that your "XA"
  2688.       environment variable is set to.
  2689.       
  2690.       Each report file will contain a header containing the XA
  2691.       copyright notice, revision number, and the date and time the
  2692.       file was created.   Next, the event list will be generated
  2693.       starting with today's events.  Each day will have it's own
  2694.       heading, and if the LATITUDE, LONGITUDE, and TIMEZONE tokens
  2695.       were included in either of the initialization or command files,
  2696.       then the sunrise and sunset times for this day will be added to
  2697.       the report.
  2698.       
  2699.       The format of the report is self-explanatory, but a few items
  2700.       are worth noting. The "Description" column retrieves the module
  2701.       definition via the "DEFINE" statement. The DEFINE must include
  2702.       both the HOUSE and UNIT tokens when  describing a module.  You
  2703.       should not use the short cut method, such as:
  2704.       
  2705.               DEFINE Porch_Lights A 1             <=== will NOT work.
  2706.               DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.
  2707.       
  2708.       The "Event" column displays the actual location of the event in
  2709.       the CP-290's memory.  Event locations range anywhere from 0 to
  2710.       127.  Use  this information if you want to CLEAR an event from
  2711.       the CP-290  interface (see EVENT, and CLEAR EVENT).  If you
  2712.       specify the '-e' command line option, then the events will not
  2713.       be downloaded, and all  event numbers will be set to -1.  An
  2714.       asterisk (*) following the event number is a flag to warn you
  2715.       that the event is triggered on multiple days.  Therefore, if you
  2716.       do CLEAR this event, the event will be deleted for the other
  2717.       days as well.
  2718.       
  2719.       
  2720.                 XA - X10 Command Interpreter - Version 2.1                   51 
  2721.       Report Style 1 - Sort by Day and Time
  2722.       ─────────────────────────────────────────────────────────────────────
  2723.       
  2724.       Use the REPORT1 token in the command file (or use +r1 on the
  2725.       command line) to produce a report file which sorts every event
  2726.       by the day it  takes place and the time it occurs.  The
  2727.       following is a condensed sample of this style.
  2728.       
  2729.       
  2730.         Saturday - September 25, 1993     Sunrise: 7:15:27  Sunset: 7:18:53
  2731.       
  2732.         Time      Cmd   Mode Module Address/Description    Event
  2733.         ========  ===   ==== ==========================    =====
  2734.         1:30 am   OFF        (A3) BEDROOM_LIGHT            ( 75)
  2735.         5:00 am   ON         (B2) DEHUMIDIFIER             ( 77)*
  2736.         6:45 am   OFF        (A6) STAIRS                   ( 84)*
  2737.         6:45 am   OFF        (H1) HALLWAY                  ( 81)*
  2738.         9:00 am   OFF        (B2) DEHUMIDIFIER             ( 78)*
  2739.        12:30 pm   OFF        (A8) LIVING_ROOM_LAMP         ( 56)
  2740.        12:30 pm   OFF        (A4) FAMILY_ROOM_LAMP         ( 61)
  2741.         5:00 pm   ON         (B2) DEHUMIDIFIER             ( 79)*
  2742.         6:18 pm   ON         (A4) FAMILY_ROOM_LAMP         ( 72)
  2743.         7:18 pm   DIM        (A9) OUTSIDE_PORCH_LIGHT      ( 66)
  2744.         7:23 pm   ON         (A1) DECK_LIGHTS_1            ( 69)
  2745.         7:48 pm   DIM        (A6) STAIRS                   ( 82)*
  2746.         7:48 pm   DIM        (A1) DECK_LIGHTS_1            ( 70)
  2747.         7:48 pm   ON         (A8) LIVING_ROOM_LAMP         ( 67)
  2748.         8:48 pm   OFF        (A1) DECK_LIGHTS_1            ( 71)
  2749.         9:00 pm   OFF        (B2) DEHUMIDIFIER             ( 80)*
  2750.         9:45 pm   DIM        (H1) HALLWAY                  ( 86)*
  2751.        10:34 pm   ON         (A3) BEDROOM_LIGHT            ( 74)
  2752.        10:43 pm   OFF        (A9) OUTSIDE_PORCH_LIGHT      ( 76)
  2753.        11:00 pm   DIM        (A6) STAIRS                   ( 83)*
  2754.       
  2755.       
  2756.                 XA - X10 Command Interpreter - Version 2.1                   52 
  2757.       Report Style 2 - Sort by Day, Module, and Time
  2758.       ─────────────────────────────────────────────────────────────────────
  2759.       
  2760.       Use the REPORT2 token in the command file (or use +r2 on the
  2761.       command line) to produce a report file which sorts every event
  2762.       by the day it takes place, the module, and the time it occurs.
  2763.       The following is a condensed sample of this style.
  2764.       
  2765.       
  2766.         Saturday - September 25, 1993     Sunrise: 7:15:27  Sunset: 7:18:53
  2767.       
  2768.             Module  Time      Function   Mode     Event
  2769.       
  2770.             (A1) DECK_LIGHTS_1
  2771.                     7:23 pm     ON                ( 69)
  2772.                     7:48 pm     DIM               ( 70)
  2773.                     8:48 pm     OFF               ( 71)
  2774.       
  2775.             (A3) BEDROOM_LIGHT
  2776.                     1:30 am     OFF               ( 75)
  2777.                    10:30 pm     ON                ( 74)
  2778.       
  2779.             (A4) FAMILY_ROOM_LAMP
  2780.                    12:30 pm     OFF               ( 61)
  2781.                     6:18 pm     ON                ( 72)
  2782.       
  2783.             (A6) STAIRS
  2784.                     6:48 am     OFF               ( 84)*
  2785.                     7:43 pm     DIM               ( 82)*
  2786.                    11:00 pm     DIM               ( 83)*
  2787.       
  2788.             (A8) LIVING_ROOM_LAMP
  2789.                    12:30 pm     OFF               ( 56)
  2790.                     7:48 pm     ON                ( 67)
  2791.       
  2792.             (A9) OUTSIDE_PORCH_LIGHTS
  2793.                     7:18 pm     DIM               ( 66)
  2794.                    10:31 pm     OFF               ( 76)
  2795.       
  2796.             (B2) DEHUMIDIFIER
  2797.                     5:00 am     ON                ( 77)*
  2798.                     9:00 am     OFF               ( 78)*
  2799.                     5:00 pm     ON                ( 79)*
  2800.                     9:00 pm     OFF               ( 80)*
  2801.       
  2802.             (H1) HALLWAY
  2803.                     6:48 am     OFF               ( 81)*
  2804.                     9:45 pm     DIM               ( 86)*
  2805.       
  2806.       
  2807.       
  2808.                 XA - X10 Command Interpreter - Version 2.1                   53 
  2809.       ═════════════════════════════════════════════════════════════════════
  2810.       15.  Monitoring and Logging events
  2811.       ═════════════════════════════════════════════════════════════════════
  2812.       
  2813.       The CP-290 sends a message to your computer after it processes a
  2814.       direct command (via XA.EXE or X10.EXE), or after one of its
  2815.       eight keys has been pressed, or when it executes an event stored
  2816.       in its memory.  Most software packages (including X10.EXE
  2817.       shipped with the CP-290) will ignore these messages.  XA allows
  2818.       you to monitor as well as log these transmissions if desired.
  2819.       
  2820.       XA will enter its monitor mode after all other commands have
  2821.       been processed.  You can activate the monitor feature in two
  2822.       ways: as a  command, or as a command line parameter.
  2823.       
  2824.       Command example:
  2825.       
  2826.               XA "MONITOR"
  2827.       
  2828.       Command line parameter example:
  2829.       
  2830.               XA +m
  2831.       
  2832.       In the first example, "MONITOR" is the only command that XA
  2833.       processes. XA ignores the default command file if it has been
  2834.       specified with XACMD.  In the second example, XA would process
  2835.       the default command file (if specified) and then initiate the
  2836.       monitor sequence.
  2837.       
  2838.       When XA begins to monitor, it displays the following message:
  2839.       
  2840.               Monitor events.  Press <ESC> when finished...
  2841.       
  2842.       XA then waits for messages from the CP-290.  You may exit this
  2843.       function by pressing the <ESC> key.
  2844.       
  2845.       When the CP-290 executes an event, it sends a message to the PC
  2846.       with the following information; the HOUSE code, UNIT code, and
  2847.       the event FUNCTION (ON, OFF, DIM).  XA takes this information
  2848.       and adds the time and date information from your PC's clock and
  2849.       prints the following  message to the monitor:
  2850.       
  2851.               Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON
  2852.       
  2853.       This message is semi-useful; it describes what just occurred but
  2854.       if you forgot what was addressed as HOUSE A UNIT 5 then the
  2855.       message is meaningless.  You can give this module a more
  2856.       descriptive name by using a command file that includes DEFINE
  2857.       statements for all your modules.  Below is sample command file
  2858.       (MONITOR.CMD - supplied with  this package) that describes what
  2859.       we're talking about:
  2860.       
  2861.               DEFINE Porch/Garage_Lights HOUSE A UNIT 1
  2862.               DEFINE Plant_Grow_Lights HOUSE A UNIT 5
  2863.               DEFINE Family_Room_TV HOUSE A UNIT 6
  2864.               DEFINE Basement_Computer HOUSE A UNIT 7
  2865.       
  2866.                 XA - X10 Command Interpreter - Version 2.1                   54 
  2867.       Now when a message is sent by the CP-290, a scan of all the
  2868.       definitions will be made to see if the HOUSE and UNIT codes
  2869.       match. If so, then that description will be used instead of the
  2870.       codes.  Therefore, you would get the following message on your
  2871.       screen:
  2872.       
  2873.               Sun Mar 24 07:00:13 1991 (A6) Plant_Grow_Lights ON
  2874.               Sun Mar 24 08:43:13 1991 (A1) Porch/Garage_Lights ON
  2875.       
  2876.       In the above messages, a combined House and Unit code (A6) is
  2877.       automatically provided, you don't have to include it as part of
  2878.       the DEFINE token.
  2879.       
  2880.       Also, the DEFINE must include both the HOUSE and UNIT tokens
  2881.       when describing an object.  You can not use the short cut
  2882.       method, such as:
  2883.       
  2884.               DEFINE Porch_Lights A 1             <=== will NOT work.
  2885.               DEFINE Porch_Lights HOUSE A UNIT 1  <=== will work.
  2886.       
  2887.       If different modules are controlled by a single event, the
  2888.       module which has the lowest UNIT code will be displayed.
  2889.       Therefore, if modules C9 and C10 are programmed as a single
  2890.       event, only C9 will be displayed.
  2891.       
  2892.       You can also log these events to a file called XA.LOG by
  2893.       specifying either the LOG token in a command file or the [+l]
  2894.       option on the command line.  Each event reported by the CP-290
  2895.       will be displayed on  the screen, and also be appended to the
  2896.       file XA.LOG.  By appending the information, all previous events
  2897.       will be saved.
  2898.       
  2899.                 XA - X10 Command Interpreter - Version 2.1                   55 
  2900.       ═════════════════════════════════════════════════════════════════════
  2901.       16.  POWERUP Utility
  2902.       ═════════════════════════════════════════════════════════════════════
  2903.       
  2904.       The POWERUP utility is provided in this package to help you
  2905.       perform unattended, automatic, event downloads to the CP-290 if
  2906.       your computer is controlled by an Appliance module.  POWERUP
  2907.       should be placed in your AUTOEXEC.BAT file so it will always be
  2908.       executed after your computer boots.  This way, it can decide
  2909.       whether or not it's time to perform any updates to your
  2910.       interface, and it prevents you from needlessly sending commands
  2911.       when you don't need to.
  2912.       
  2913.       The POWERUP command has the following form:
  2914.       
  2915.               POWERUP d=day [[d=day]...] [w=1,2,3,4,5] s=hh:mm e=hh:mm
  2916.       
  2917.       The command line parameters may appear in any order, and they
  2918.       must all be present (except for "w="):
  2919.       
  2920.       d=day
  2921.       
  2922.         This is the text string for the day you want to check for.
  2923.         Legal strings are:
  2924.       
  2925.               MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY,
  2926.               WEEKDAYS, WEEKDAY, WEEKENDS, WEEKEND, EVERYDAY.
  2927.       
  2928.       [w=week]
  2929.       
  2930.         This optional argument allows you to optionally specify the week
  2931.         of the month you want POWERUP to check for. For instance, to
  2932.         have POWERUP check for the 3rd SUNDAY of the month, specify:
  2933.       
  2934.               POWERUP d=SUNDAY w=3 s=2:55 e=3:05
  2935.       
  2936.         You may not specify multiple weeks, however the default
  2937.         condition (not specifying the w= command) will still check every
  2938.         week.
  2939.       
  2940.       s=hh:mm
  2941.       
  2942.         This is the "window" start time.  Hours must be entered in 24
  2943.         hour format only.
  2944.       
  2945.       e=hh:mm
  2946.       
  2947.         This is the "window" end time.  (24 hr format). For example:
  2948.       
  2949.             POWERUP d=SUNDAY s=2:55 e=3:05
  2950.       
  2951.         If the "day" specified matches the day reported by DOS, and the
  2952.         time reported by DOS falls within the specified "window", then
  2953.         POWERUP will return an ERRORLEVEL of 1, otherwise a 0 is
  2954.         returned. Therefore, by placing the proper batch file commands
  2955.         in AUTOEXEC.BAT, you can now execute a variety of functions at
  2956.         certain times.
  2957.       
  2958.                 XA - X10 Command Interpreter - Version 2.1                   56 
  2959.         You may enter multiple 'd=day' parameters.  For instance, to
  2960.         have Powerup check for a window beginning at NOON and lasting
  2961.         until 1:00 pm every MONDAY, WEDNESDAY, and FRIDAY, you would
  2962.         enter:
  2963.       
  2964.               POWERUP d=MONDAY d=WEDNESDAY d=FRIDAY s=12:00 e=13:00
  2965.               if errorlevel == 1 echo It's time!
  2966.       
  2967.         If your computer is controlled by an Appliance module, you can
  2968.         now automatically download revised event times.  See the sample
  2969.         AUTOEXEC.BAT file included in this package.
  2970.       
  2971.       
  2972.       ═════════════════════════════════════════════════════════════════════
  2973.       17.  FINDX10.EXE
  2974.       ═════════════════════════════════════════════════════════════════════
  2975.       
  2976.       A new utility has been added to help determine the configuration
  2977.       of the serial port the CP-290 is connected to. After searching
  2978.       all ports in your system, FINDX10 determines the IRQ of the port
  2979.       and attempts to communicate with the CP-290. If it finds the
  2980.       CP-290, it displays the port setup and prompts you if it is OK
  2981.       to save the data in your XA.INI file.  If you select 'Y', the IO
  2982.       address and the IRQ level tokens are placed at the end of your
  2983.       XA.INI file.
  2984.       
  2985.       Because of the wide variety of hardware in use, FINDX10 may not
  2986.       be able to locate the CP-290.
  2987.       
  2988.       ═════════════════════════════════════════════════════════════════════
  2989.       18.  Other Programs and X10 Information
  2990.       ═════════════════════════════════════════════════════════════════════
  2991.       
  2992.       XT - Memory Resident Software for the CP-290
  2993.       ─────────────────────────────────────────────────────────────────────
  2994.       
  2995.       XA is just one of a series of programs that have been developed
  2996.       for the X10 CP-290.  If you received XA on a floppy disk, then
  2997.       you should have also received a program called XT, a
  2998.       terminate-stay-resident  program (or TSR) that sits silently in
  2999.       the background waiting for you to activate it with the proper
  3000.       keystroke.  This means you can instantly call it from any
  3001.       text-based application.  When activated, it displays a list of
  3002.       all modules that you can control with the CP-290.  Each line on
  3003.       the list contains a description of the module, its address, and
  3004.       its current status.  You select the module you want to control,
  3005.       and then choose the action (ON, OFF, DIM).
  3006.       
  3007.       Since XT is resident, it continuously monitors the serial port
  3008.       for any communication transmitted by the CP-290 (such as when an
  3009.       event is issued or when one of the buttons on the unit is
  3010.       pressed).  The  status of each module will always be properly
  3011.       reflected in the pop-up menu.
  3012.       
  3013.                 XA - X10 Command Interpreter - Version 2.1                   57 
  3014.       XT (version 1.2) now comes with utility package called XTS.EXE.
  3015.       XTS has direct access to XT's database of 256 module states.
  3016.       Every command issued by the CP-290 is captured and stored by XT.
  3017.       XTS can return these module states (via errorlevel statements),
  3018.       allowing you to write batch files that react to a module's X10
  3019.       status.
  3020.       
  3021.       XA (2.0) communicates with XT too.  Whenever XA executes a
  3022.       direct command, (or monitors X10 activity), it sends the
  3023.       information along to XT so the new state is reflected in the
  3024.       XT's database.
  3025.       
  3026.       Another feature of XT is its ability to perform a limited
  3027.       "power-fail  recovery".  This function analyzes all events
  3028.       stored in the CP-290 and sets each module to its proper state
  3029.       based on this information.  This feature can be activated during
  3030.       program installation, or whenever the menu is displayed.
  3031.       
  3032.       
  3033.       Other Information
  3034.       ─────────────────────────────────────────────────────────────────────
  3035.       
  3036.       If you would like further information about the X10 system, then
  3037.       contact Steve Mueller of the Silicon Valley Video Group.  Steve
  3038.       has put together a paper (currently 60 pages) which covers such
  3039.       topics as:
  3040.       
  3041.       X10 transmission theory, undocumented functions of the CP-290,
  3042.       debugging spurious failures, modifying X10 devices (local
  3043.       dimming), descriptions of the PL-513 and TW-523 modules,  CP-290
  3044.       Users and Programming Guides, and manufacturers/retailers of X10
  3045.       compatible equipment.
  3046.       
  3047.       There is a charge for Steves paper. You may contact Steve via:
  3048.       
  3049.            Steve Mueller
  3050.            Silicon Valley Video Group
  3051.            335 Bodega Way
  3052.            San Jose, CA. 95119-1603
  3053.       
  3054.            or via Prodigy - SJCR28A
  3055.       
  3056.       
  3057.       
  3058.       ═════════════════════════════════════════════════════════════════════
  3059.       19.  Acknowledgements
  3060.       ═════════════════════════════════════════════════════════════════════
  3061.       
  3062.       I would like to thank the following people for their help in
  3063.       making XA a better program. First of all, thanks go to my wife
  3064.       and kids for letting me spend the time to pursue this hobby.
  3065.       Next, my thanks go out to the beta testers - Dave Mabry, Ed
  3066.       Christie, David Huras, Nira Johnson, and to Arnold Sprague for
  3067.       proofreading the documentation.  Finally, my thanks go out to
  3068.       all the folks who have taken the time to register this program
  3069.       and offer suggestions.
  3070.       
  3071.       
  3072.                 XA - X10 Command Interpreter - Version 2.1                   58 
  3073.       ═════════════════════════════════════════════════════════════════════
  3074.       20.  Warranty, Copyright, and Registration Policy
  3075.       ═════════════════════════════════════════════════════════════════════
  3076.       
  3077.       Limited Warranty
  3078.       ─────────────────────────────────────────────────────────────────────
  3079.       THIS PRODUCT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
  3080.       THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM
  3081.       IS ASSUMED BY YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND
  3082.       NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY
  3083.       SERVICING, REPAIR OR CORRECTION.  FURTHER, THE AUTHOR DOES NOT
  3084.       WARRANT, GUARANTEE, OR MAKE REPRESENTATIONS REGARDING THE USE
  3085.       OF, OR THE RESULTS OF THE USE OF THIS PROGRAM IN TERMS OF
  3086.       CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS, OR OTHERWISE;
  3087.       AND YOU RELY ON THE PROGRAM AND IT'S RESULTS SOLELY AT YOUR OWN
  3088.       RISK.  THE AUTHOR CANNOT ACCEPT RESPONSIBILITY FOR SYSTEM
  3089.       DAMAGE, LOSS OF PROFIT, OR ANY OTHER SPECIAL, INCIDENTAL, OR
  3090.       CONSEQUENTIAL DAMAGE RESULTING FROM THE USE OR INABILITY TO USE
  3091.       THIS PRODUCT.
  3092.       
  3093.       The author DOES warrant to the original licensee of a REGISTERED
  3094.       product that the program disk(s) on which the program is
  3095.       recorded be free from defects in materials and workmanship under
  3096.       normal use and service for a period of ninety (90) days from the
  3097.       date of delivery. The author's entire liability and your
  3098.       exclusive remedy shall be replacement of the disk not meeting
  3099.       this Limited Warranty.
  3100.       
  3101.       Copyright
  3102.       ─────────────────────────────────────────────────────────────────────
  3103.       
  3104.       The XA software package, its utilities and this document is
  3105.       Copyright (C) 1991-1994 by Bruce Christensen. All rights
  3106.       reserved.
  3107.       
  3108.       Any specific hardware/software names used in this document are
  3109.       trademarks of specific manufacturers.
  3110.       
  3111.       Regardless of the method of marketing, XA is not in the public
  3112.       domain. It is copyrighted by Bruce Christensen. All rights are
  3113.       reserved. Copying, duplicating, selling or otherwise
  3114.       distributing the registered version of this product is a
  3115.       violation of the Law. However, we grant you the right, in fact
  3116.       encourage you to make and distribute as many copies of the
  3117.       SHAREWARE version of XA as you wish, using any acceptable medium
  3118.       of exchange, with the following provisions:
  3119.       
  3120.       Please feel free to distribute this SHAREWARE version as often
  3121.       as you like, to any interested parties.
  3122.       
  3123.       Please do not distribute this program without all of its
  3124.       original related files, addendum files, documentation and this
  3125.       notice. Please do not alter the program or documentation in any
  3126.       manner.
  3127.       
  3128.       DISTRIBUTION of the REGISTERED USER version of the program is in
  3129.       violation of license agreements and copyright Law!
  3130.       
  3131.                 XA - X10 Command Interpreter - Version 2.1                   59 
  3132.       Registration
  3133.       ─────────────────────────────────────────────────────────────────────
  3134.       
  3135.       If you are still using XA beyond the initial 45-day trial
  3136.       period, you must register this software with the author. Please
  3137.       use the included registration form (REGISTER.TXT) and send a $29
  3138.       registration fee to the address below.  Your registration will
  3139.       entitle you to the latest full-featured registered version of
  3140.       this program, and a printed copy of this user manual.
  3141.       
  3142.       The registered version of XA and its utilities are licensed for
  3143.       individual personal use for an unlimited time.
  3144.       
  3145.       This is a "living" program - new features are added from time to
  3146.       time.  Your input is the basis for future improvements.  Send
  3147.       any comments to the address given below, or you may contact me
  3148.       on CompuServe, Prodigy,  America On-line, or Internet.
  3149.       
  3150.            Bruce Christensen
  3151.            6594 Hudson Avenue
  3152.            Mentor, OH.  44060-4545
  3153.       
  3154.            CompuServe: 73201,1531
  3155.            Prodigy ID:  MHNC39A
  3156.            America On-line: AuggieBen
  3157.            Internet: auggieben@aol.com
  3158.       
  3159.       
  3160.       
  3161.       Future Updates
  3162.       ─────────────────────────────────────────────────────────────────────
  3163.       
  3164.       Future updates of the shareware version XA can be found on
  3165.       CompuServe, America On-Line, as well as the following BBS's as
  3166.       they become available. The current version of XA will be named
  3167.       "X10XA201.ZIP". The last 3 digits of the filename will indicate
  3168.       the revision level (in this case, 2.01).
  3169.       
  3170.       Dave Mabry, a sysop of the "Going Down BBS" has offered free
  3171.       access to his BBS to anyone interested in X10 - Home Automation.
  3172.       Users can gain immediate access to the home automation files
  3173.       by logging on with a userid and password of "X10". This BBS can
  3174.       be reached at:  1-(313)-576-7882.
  3175.       
  3176.       Baran-Harper, a Canadian home automation mail order outfit, also
  3177.       runs a very popular BBS. There are many programs for the CP-290
  3178.       for PC's, Mac's, and other computers. The Baran Harper BBS is a
  3179.       free BBS, their number is: 1-(905)-471-6776, or 1-(905)-471-9574.
  3180.       
  3181.       Circuit Cellar Inc. publishes "The Computer Applications
  3182.       Journal", and runs occasional articles on X10.  Their BBS number
  3183.       is 1-(203)-871-1988.
  3184.       
  3185.       Home Automation Laboratories (HAL) has the best mail-order
  3186.       catalog for home automation equipment. Call 1-(800)-YEL-4HAL to
  3187.       request a catalog.  HAL's BBS # is 1-(404)-319-6227.
  3188.       
  3189.       
  3190.                 XA - X10 Command Interpreter - Version 2.1                   60 
  3191.       ═════════════════════════════════════════════════════════════════════
  3192.       Appendix A. Tokens - Quick Reference
  3193.       ═════════════════════════════════════════════════════════════════════
  3194.       
  3195.       Action tokens
  3196.       ─────────────────────────────────────────────────────────────────────
  3197.       
  3198.         ON - turns ON the specified modules.
  3199.         OFF - turns OFF the specified modules.
  3200.         {DIM %%} - DIM to a % (percentage) level of brightness.
  3201.         {ALL_UNITS_OFF HOUSE x} - turns OFF all modules on selected
  3202.               HOUSEcode.
  3203.         {ALL_LIGHTS_ON HOUSE x} - turns ON all lamp/wallswitch modules
  3204.               on selected HOUSEcode.
  3205.       
  3206.       Module address tokens
  3207.       ─────────────────────────────────────────────────────────────────────
  3208.       
  3209.         A1...P16
  3210.         HOUSE A...P
  3211.         UNIT 1...16
  3212.         UNIT ALL
  3213.       
  3214.       
  3215.       Coordinate tokens
  3216.       ─────────────────────────────────────────────────────────────────────
  3217.       
  3218.         {LATITUDE dms} - your LATITUDE in Degrees and Minutes
  3219.         {LONGITUDE dms} - your LONGITUDE in Degrees and Minutes
  3220.         {TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings)
  3221.         DST - Automatic Daylight Savings adjustments
  3222.       
  3223.       
  3224.       Clock tokens
  3225.       ─────────────────────────────────────────────────────────────────────
  3226.       
  3227.         {SYNCHRONIZE PC (EXACT)} - set PC time based on X10 time
  3228.         {SYNCHRONIZE X10 (EXACT)} - set X10 time based on PC time
  3229.       
  3230.       
  3231.       Day tokens
  3232.       ─────────────────────────────────────────────────────────────────────
  3233.       
  3234.         SUNDAY, SUN - Specific day for event to occur
  3235.         MONDAY, MON -    "
  3236.         TUESDAY, TUE -   "
  3237.         WEDNESDAY, WED - "
  3238.         THURSDAY, THU -  "
  3239.         FRIDAY, FRI -    "
  3240.         SATURDAY, SAT -  "
  3241.         EVERYDAY - Event occurs everyday
  3242.         TODAY - Event occurs once today only
  3243.         TOMORROW - Event occurs once tomorrow only
  3244.         WEEKDAY, WEEKDAYS - Event occurs only on weekdays
  3245.         WEEKEND, WEEKENDS - Event occurs only on weekends
  3246.       
  3247.       
  3248.                 XA - X10 Command Interpreter - Version 2.1                   61 
  3249.       Time tokens
  3250.       ─────────────────────────────────────────────────────────────────────
  3251.       
  3252.         {TIME hh:mm (AM)(PM)} - Schedule event time
  3253.         SUNRISE - Calculate time of sunrise
  3254.         SUNSET - Calculate time of sunset
  3255.         {OFFSET +/-hh:mm} - Event occurs +/- 23h59m of prog time
  3256.         NORMAL - Event occurs at specified time
  3257.         SECURITY - Event occurs within the hour
  3258.         {RANDOM +/-hh:mm} - Event occurs within a random offset +/-23h59m.
  3259.         {NOW hh:mm} - Event occurs with respect to current time.
  3260.       
  3261.       
  3262.       Specific Date tokens
  3263.       ─────────────────────────────────────────────────────────────────────
  3264.       
  3265.         {DATE mm/dd/yyyy} - Event occurs on specified date
  3266.         {DATE mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} -
  3267.               Event occurs between two dates
  3268.         {EXCEPT mm/dd/yyyy} - Event does NOT occur on specified date
  3269.         {EXCEPT mm/dd/yyyy THRU mm/dd/yyyy (SUNDAY...SATURDAY)} -
  3270.               Event does NOT occur between two dates
  3271.         {DATE mm/dd/yyyy THRU mm/dd/yyyy EXCEPT mm/dd/yyyy THRU mm/dd/yyyy} -
  3272.               Special exceptions within a given range.
  3273.       
  3274.       
  3275.       Communication tokens
  3276.       ─────────────────────────────────────────────────────────────────────
  3277.       
  3278.         {COMx} - send commands via COM1...COM4
  3279.         {IRQ x} - customize IRQ level for port.
  3280.         {IO x}  - customize port address (in hex).
  3281.       
  3282.       
  3283.       Miscellaneous tokens
  3284.       ─────────────────────────────────────────────────────────────────────
  3285.       
  3286.         {BASECODE x} - Change BASECODE to A...P
  3287.         {DEFINE x z}      - Substitute string 'x' for 'z'
  3288.         {XACMD file.cmd} - Specify default command file.
  3289.         {INCLUDE filenme} - Specify another file to parse.
  3290.         {CLEAR EVENT xxx} - Clear event xxx from CP-290 memory
  3291.         ERASE - Erase ALL events from CP-290 memory
  3292.         {EVENT xxx} - Place event xxx in a known location of CP-290 memory
  3293.         BEEP - Causes PC speaker to beep.
  3294.         {DOS command} - Shell to DOS
  3295.         {DISPLAY ON/OFF} - Turn XA output display on or off.
  3296.         DIAGNOSE - CP-290 performs internal diagnostics.
  3297.       
  3298.       
  3299.       Reporting tokens
  3300.       ─────────────────────────────────────────────────────────────────────
  3301.       
  3302.         LOG - Append event info to file XA.LOG
  3303.         MONITOR - Watch events as the CP-290 executes them.
  3304.         REPORT1 - Produce report file based on daily events.
  3305.         REPORT2 - Produce report file based on a module by module basis.
  3306.       
  3307.                 XA - X10 Command Interpreter - Version 2.1                   62 
  3308.       Direct Command Control Tokens
  3309.       ─────────────────────────────────────────────────────────────────────
  3310.       
  3311.         :LABEL - Identify an area to "goto/gosub" later.
  3312.         {GOTO label } - Jump to location identified by "label".
  3313.         {GOSUB label} - Execute subroutine identified by "label". Upon
  3314.               returning, continue with the rest of the cmd file.
  3315.         RETURN - from subroutine (used with GOSUB).
  3316.         STOP - Force XA to stop execution
  3317.         :EXIT - Special shutdown location jumped to when <ESC> pressed.
  3318.         {DELAY hh:mm:ss} - Wait for time to pass before executing the
  3319.               next cmd.
  3320.         PAUSE - Halt execution of direct commands until key pressed,
  3321.               then reset internal timer and resume direct commands.
  3322.         {TIMER hh:mm:ss} - Wait until "seconds" have elapsed (relative
  3323.               to the internal timer).
  3324.         RESET - Reset internal timer.
  3325.         FAST - ignore ack message from CP-290, speeds up single cmds.
  3326.       
  3327.       
  3328.       Conditional Expressions              ( ** Registered Version Only **)
  3329.       ─────────────────────────────────────────────────────────────────────
  3330.       
  3331.         IF (expression)       When expression evaluates TRUE...
  3332.            statements          ...execute the following statements
  3333.         [ELSE                 Otherwise...
  3334.            statements]         ...optionally execute the following statements
  3335.         ENDIF                 Must always terminate conditional statements.
  3336.       
  3337.       
  3338.       Arithmetic Operators                 ( ** Registered Version Only ** )
  3339.       ─────────────────────────────────────────────────────────────────────
  3340.       
  3341.         *   Multiply      A = B * C
  3342.         /   Divide        B = A / C
  3343.         +   Addition      C = A + B
  3344.         -   Subtraction   A = C - B
  3345.         -   Unary minus   A = -B
  3346.       
  3347.       
  3348.       
  3349.       Relational Operators                 ( ** Registered Version Only ** )
  3350.       ─────────────────────────────────────────────────────────────────────
  3351.       
  3352.         =   Assign
  3353.         <   Less than
  3354.         >   Greater than
  3355.         <=  Less than or equal to
  3356.         <>  Not equal to
  3357.         >=  Greater than or equal to
  3358.         ==  Equals (not to be confused with '=' assignment operator)
  3359.       
  3360.       
  3361.                 XA - X10 Command Interpreter - Version 2.1                   63 
  3362.       Logical Operators                   ( ** Registered Version Only ** )
  3363.       ─────────────────────────────────────────────────────────────────────
  3364.       
  3365.         AND  Logical AND
  3366.         &&   Logical AND
  3367.         OR   Logical OR
  3368.         ||   Logical OR
  3369.         !    NOT
  3370.       
  3371.       Bitwise Logical Operators             ( ** Registered Version Only ** )
  3372.       ─────────────────────────────────────────────────────────────────────
  3373.       
  3374.         &   Bit "AND"
  3375.         |   Bit "OR"
  3376.       
  3377.       
  3378.       Screen Color Control
  3379.       ─────────────────────────────────────────────────────────────────────
  3380.       
  3381.         {VIDEO1 Foreground Background} - IF or ELSE evaluates to TRUE
  3382.         {VIDEO2 Foreground Background} - IF or ELSE evaluates to FALSE
  3383.         {VIDEO3 Foreground Background} - Sending DIRECT commands to CP-290
  3384.         {VIDEO4 Foreground Background} - Sending EVENTS to CP-290
  3385.         {VIDEO5 Foreground Background} - Important XA messages
  3386.         {VIDEO6 Foreground Background} - Statements that are non-event
  3387.                                          or non-commands.
  3388.       
  3389.         where FOREGROUND may be any of the following:
  3390.            BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
  3391.            DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
  3392.            LIGHTMAGENTA, YELLOW, WHITE
  3393.       
  3394.         and BACKGROUND may be any of the following:
  3395.            BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY
  3396.       
  3397.       
  3398.       I/O Port Control                    ( ** Registered Version Only ** )
  3399.       ─────────────────────────────────────────────────────────────────────
  3400.       
  3401.         {(variable =) INPORT io_port} - read status of port
  3402.         {OUTPORT io_port value} - output value to port
  3403.       
  3404.       
  3405.       Pre-defined Variables
  3406.       ─────────────────────────────────────────────────────────────────────
  3407.       
  3408.         CDAY - The current day
  3409.         CTIME - The current time
  3410.         CDATE - The current date
  3411.       
  3412.       
  3413.       Powerfail Recovery module status overrides
  3414.       ─────────────────────────────────────────────────────────────────────
  3415.       
  3416.         {IGNORE HOUSE UNIT} - Leave module in its present state
  3417.         {FORCE HOUSE-UNIT state} - Force module to ON, OFF, DIM state
  3418.       
  3419.                 XA - X10 Command Interpreter - Version 2.1                   64 
  3420.       ═════════════════════════════════════════════════════════════════════
  3421.       Appendix B. Returned Error Codes
  3422.       ═════════════════════════════════════════════════════════════════════
  3423.       
  3424.       The following is a list of Error messages that XA may generate.
  3425.       Also included is a specific error code that XA returns when it
  3426.       is finished. These error codes may be examined using ERRORLEVEL
  3427.       parameter in batch files.
  3428.       
  3429.       Code: 0   "Completed OK."
  3430.                  Normal operation, XA ran successfully.
  3431.       
  3432.       Code: 1   "No commands to execute."
  3433.                  The "-e" command line option was used, preventing any commands
  3434.                  or events to be sent to the CP-290. Note that a report file
  3435.                  (XA.RPT) may have been generated, however the X10.DAT file was
  3436.                  not updated.
  3437.       
  3438.       Code: 2   "Timeout occurred. Check your cables."
  3439.                  First, make sure the CP-290 is connected to the correct serial
  3440.                  port. Also, make sure you are using the proper communication
  3441.                  settings.
  3442.       
  3443.       Code: 3   "Illegal comm port - Use 1...4."
  3444.                  Use i=1...4 only!
  3445.       
  3446.       Code: 4   "Timeout occurred or interface defective."
  3447.                  XA waited for the CP-290 to return a status code after
  3448.                  initiating it's internal diagnostics. Check to see if the
  3449.                  CP-290 is properly connected to the PC. If the connection is
  3450.                  OK, then the CP-290 may be defective. All events stored in the
  3451.                  CP-290 have been deleted.
  3452.       
  3453.       Code: 5   "Interface FAILED diagnostic."
  3454.                  The CP-290 has failed its internal diagnostics. All events
  3455.                  stored in the CP-290 have been deleted.
  3456.       
  3457.       Code: 6   "XA.EXE is corrupt."
  3458.                  XA has detected a change in its internal code. This may be the
  3459.                  result of a possible virus, or other problem with the file.
  3460.                  Re-install XA from the distribution diskette.
  3461.       
  3462.       Code: 7   "Timeout occurred. Check cable, irq, and i_o settings."
  3463.                  First, make sure the CP-290 is connected to the correct serial
  3464.                  port. Also, make sure you are using the proper communication
  3465.                  settings.  This type of problem is usually caused by specifying
  3466.                  an improper interrupt vector. Run the utility FINDX10.EXE to
  3467.                  assist you in determining the proper configuration of your
  3468.                  serial port.
  3469.       
  3470.       Code: 8    (No error assigned)
  3471.       
  3472.       Code: 9   "Not enough memory."
  3473.                  XA reserves memory for "variable" storage, "define" statements,
  3474.                  "labels" (for GOTO/GOSUB), and "include" filenames. When this
  3475.                  error occurs, try reducing these statements.
  3476.       
  3477.                 XA - X10 Command Interpreter - Version 2.1                   65 
  3478.       Code: 10   "<ESC> key pressed. Exiting..."
  3479.                  XA was aborted due to operator intervention. A file may not
  3480.                  have been downloaded to the CP-290 properly.
  3481.       
  3482.       Code: 11   "XA internal date stack overflow."
  3483.                  More than 100 dates were specified in a single statement.
  3484.                  Reduce the number of dates, or use DATE ... THRU.
  3485.       
  3486.       Code: 12   "XA internal date stack underflow."
  3487.                  Try rewriting statement, contact author.
  3488.       
  3489.       Code: 13   "XA internal stack overflow."
  3490.                  More than 100 tokens were specified in a single statement.
  3491.                  Reduce complexity of statement.
  3492.       
  3493.       Code: 14   "XA internal stack underflow."
  3494.                  Try rewriting statement, contact author.
  3495.       
  3496.       Code: 15   "XA internal gosub stack overflow."
  3497.                  Too many levels of subroutines called. Rewrite your command
  3498.                  files.
  3499.       
  3500.       Code: 16   "XA internal gosub underflow."
  3501.                  Try rewriting statement, contact author.
  3502.       
  3503.       Code: 17   "Not enough FILE handles, or file not found."
  3504.                  An attempt was made to read or write to a file. The file could
  3505.                  not opened because it:
  3506.                     1) does not exist,
  3507.                     2) you need to increase the number of files that can be
  3508.                        opened.
  3509.                  See DOS manual -
  3510.                     command: FILES=??? (normally in your  CONFIG.SYS).
  3511.       
  3512.       Code: 18   "XA internal except date stack overflow."
  3513.                  More than 100 "EXCEPT" dates were specified in a single
  3514.                  statement. Reduce the number of dates, or use DATE ... THRU.
  3515.       
  3516.       Code: 19   "XA internal except date stack underflow."
  3517.                  Try rewriting statement, contact author.
  3518.       
  3519.                 XA - X10 Command Interpreter - Version 2.1                   66 
  3520.       ═════════════════════════════════════════════════════════════════════
  3521.       Appendix C. Passing arguments to your command file.
  3522.       ═════════════════════════════════════════════════════════════════════
  3523.       
  3524.       By default, XA will only accept input from either the DOS
  3525.       command line (ie, commands enclosed in "parentheses"), or via a
  3526.       file.
  3527.       
  3528.            XA "P1 OFF"   <=== DOS command line arguments.
  3529.            XA F=XA.CMD   <=== XA Command File.
  3530.       
  3531.       You may now override this feature and have XA interpret commands
  3532.       from the DOS command line as well as a file by using the
  3533.       following format:
  3534.       
  3535.            XA "command" f=file.cmd   -or-
  3536.            XA f=file.cmd "command"   (The order is not important).
  3537.            XA "P1 OFF" f=XA.CMD
  3538.       
  3539.       This form of operation is very useful if you wish to pass
  3540.       special arguments into your command file and allow XA to
  3541.       activate special sequences. Your normal command file (XA.CMD)
  3542.       could contain some special commands that are only activated when
  3543.       you define a variable to be a certain value. The following
  3544.       sample code is included in the SPECIAL.CMD file and is executed
  3545.       when the variable "Babysitter" is set TRUE:
  3546.       
  3547.            IF (BABYSITTER)
  3548.               FOYER_LIGHTS ON DUSK TODAY
  3549.               HALLWAY ON SUNSET TODAY
  3550.               DECK_LIGHTS ON SUNSET TODAY
  3551.            ENDIF
  3552.       
  3553.       To have XA execute the above sequence, you must program the
  3554.       command file name AND the variable assignment statement:
  3555.       
  3556.            XA F=SPECIAL.CMD "BABYSITTER = TRUE"
  3557.       
  3558.       
  3559.                 XA - X10 Command Interpreter - Version 2.1                   67 
  3560.       ═════════════════════════════════════════════════════════════════════
  3561.       Appendix D. Running XA in Windows
  3562.       ═════════════════════════════════════════════════════════════════════
  3563.       
  3564.       XA may be run in the Windows environment. A major advantage is
  3565.       the ability to multi-task your applications while XA monitors
  3566.       the CP-290, downloads new event schedules, or performs a special
  3567.       lighting sequences.
  3568.       
  3569.       In order to use XA successfully in Windows, you must ensure that
  3570.       Windows understands your COM port configuration. Follow these
  3571.       steps (applies to Windows 3.1):
  3572.       
  3573.        * Run "Program Manger"
  3574.       
  3575.        * In the MAIN group, run "Control Panel"
  3576.       
  3577.        * Run "Ports"
  3578.       
  3579.        * Select the COM port that the CP-290 is connected to. This should
  3580.          match the COM token in you XA.INI file. Press "Settings".
  3581.       
  3582.        * Set the Baud Rate to 600, Data Bits to 8, Parity to None, Stop
  3583.          Bits to 1, and Flow Control to None.
  3584.       
  3585.        * If you use the tokens "IO, IRQ, i=, o=" in your XA.INI file (or
  3586.          command line), you should press "Advanced..." button to verify
  3587.          these settings.  Make sure the Base I/O Port Address matches the
  3588.          address of your COM port. See the table in the XA documentation
  3589.          for typical addresses of the COM ports.  Next, ensure that the
  3590.          IRQ is set properly. Select "OK".
  3591.       
  3592.        * Select OK.  Windows may need to reboot your machine in order to
  3593.          activate these parameters.
  3594.       
  3595.       Several PIF files were included with XA to perform such
  3596.       functions as downloading events, monitoring CP-290 activity, and
  3597.       recovering from a power failure. You will need to customize
  3598.       these files based on your installation.
  3599.       
  3600.       
  3601.                 XA - X10 Command Interpreter - Version 2.1                   68 
  3602.       ═════════════════════════════════════════════════════════════════════
  3603.       Appendix E. Updating from Version 1.07b to 2.00
  3604.       ═════════════════════════════════════════════════════════════════════
  3605.       
  3606.       There are a few differences with some of the commands in this
  3607.       version.
  3608.       
  3609.        * GOTO label "x_times"  is no longer supported.  You may either
  3610.          use GOSUBS, or condition statements and counters.
  3611.       
  3612.        * TIMEZONE changes.  Use DST in conjunction with your "Standard
  3613.          Time" timezone.
  3614.       
  3615.        * DELAY hh:mm:ss  (not DELAY mm:ss)
  3616.       
  3617.        * TIMER mm:ss.hs  Place action tokens before the TIMER tokens:
  3618.            A1 ON TIMER 0:20.5
  3619.            TIMER 0:20.5 A1 ON     <--- Not this way
  3620.       
  3621.        * DEFINES must be declared prior to their usage in a command.  XA
  3622.          is no longer a multi-pass parser.
  3623.       
  3624.        * X10DAT is no longer supported. The file X10.DAT is always
  3625.          created.
  3626.       
  3627.        * ADJUST token is no longer supported.
  3628.