home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxcp290.zip / cp290.INF (.txt) < prev    next >
OS/2 Help File  |  1996-05-06  |  86KB  |  1,810 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. The X-10 company has for years provided a cost-effective and popular means for 
  5. control of the lights and appliances in the home, by means of the X-10 Home 
  6. Control System. X-10's CP290 Home Control Interface provides the hardware 
  7. required to control the X-10 modules from your computer's serial port. Now you 
  8. can combine the capabilities of the X-10 system with the Power and Flexibility 
  9. of OS/2, and OS/2's REXX language, with RxCP290 - the REXX Interface to X-10 
  10. Home Control. 
  11.  
  12. RxCP290 is an extension of OS/2's built-in REXX language that provides 
  13. functions for communicating to the CP290 Home Control Interface for X-10. This 
  14. allows you to control X-10 modules and functions in your home or office from 
  15. OS/2 REXX Programs. 
  16.  
  17. The RxCP290 package consists of the following: 
  18.  
  19.      The RxCP290 REXX Functions, in the form of a Dynamic Link Library (DLL). 
  20.  
  21.      This documentation, in both online and printed formats. 
  22.  
  23.      REXX Example programs, including: 
  24.  
  25.         -  SmallTest.CMD - a minimal program that demonstrates the simple 
  26.            turning on of a X-10 Module. 
  27.  
  28.         -  TestCP.CMD - A REXX program with examples and explanation of proper 
  29.            usage of all of the RxCP290 Functions. 
  30.  
  31.         -  SaveRest.CMD - a REXX program with procedures for saving and 
  32.            restoring CP290 Timer events to and from disk files. 
  33.  
  34.         -  CP29Web.CMD - An example REXX CGI program that works in conjunction 
  35.            with CP290.html to allow control of any X-10 module from an 
  36.            OS/2-Hosted World Wide Web site. 
  37.  
  38.         -  CP290.RXX - the REXX source to the CP290.EXE X-10 control program 
  39.            included in the package. This program was written with the DrDialog 
  40.            Application Enabler package. 
  41.  
  42.      The CP290.EXE program, a WorkPlace Shell program based on OS/2's Notebook 
  43.       control, with support for all of the basic functions of the CP290 Home 
  44.       Control Interface. This was written in REXX with the DrDialog package. 
  45.  
  46.      An installation program, written in REXX, for installing the RxCP290 
  47.       package 
  48.  
  49.  
  50. ΓòÉΓòÉΓòÉ 2. Installation ΓòÉΓòÉΓòÉ
  51.  
  52. Installation consists of two phases - software installation, and hardware 
  53. installation. These are described below. 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 2.1. Installing the software ΓòÉΓòÉΓòÉ
  57.  
  58. The RXCP290 software may be installed automatically via INSTALL.CMD, or 
  59. manually. These methods are described below. 
  60.  
  61.  
  62. ΓòÉΓòÉΓòÉ 2.1.1. Automatic Installation ΓòÉΓòÉΓòÉ
  63.  
  64. Automatic installation may be accomplished by using the Install.cmd REXX 
  65. program included with the distribution. This installation program will copy the 
  66. RxCP290 DLL to \OS2\APPS\DLL on your boot drive, and will create a 
  67. \RxCP290 directory on your boot drive for the rest of the package. 
  68.  
  69. Should you not wish the rest of the package be installed to this directory, you 
  70. may specify a directory to install the RxCP290 Utilities, Example Programs, and 
  71. Documentation to on the command line. For example, to install these in a 
  72. directory named F:\X10Stuff, you would start install.cmd like this: 
  73.  
  74. A:\>install F:\X10Stuff
  75.  
  76. Once started, the Install.cmd program will display the From and To directory 
  77. information for the installation, and will prompt for a Y/N response. Pressing 
  78. 'y' or 'Y' will continue the installation, anything else will abort. 
  79.  
  80. The RxCP290 utilities are ready to run immediately upon completion of the 
  81. installation process. 
  82.  
  83.  
  84. ΓòÉΓòÉΓòÉ 2.1.2. Manual Installation ΓòÉΓòÉΓòÉ
  85.  
  86. If you do not desire to have the RxCP290 DLL in your \OS2\APPS\DLL directory, 
  87. you may simply copy the dll file to the directory of your choice. If this 
  88. directory is not included in the LIBPATH as specified in your CONFIG.SYS file, 
  89. then only REXX programs started in this directory will be able to find and use 
  90. the RxCP290 functions in this DLL file. 
  91.  
  92. The remaining RxCP290 Documentation, Example Program, and Utility files may be 
  93. installed anywhere the user desires. 
  94.  
  95.  
  96. ΓòÉΓòÉΓòÉ 2.2. Connecting the CP290 Interface ΓòÉΓòÉΓòÉ
  97.  
  98. The CP290 interface should be connected to the PC's serial port in accordance 
  99. with instructions furnished by X-10 with the CP290 unit. 
  100.  
  101.  
  102. ΓòÉΓòÉΓòÉ 3. Some Notes On REXX ΓòÉΓòÉΓòÉ
  103.  
  104. This document is not intended as a REXX tutorial or language reference. If you 
  105. are learning the REXX language, the following texts are highly recommended: 
  106.  
  107.      The REXX Language - M. F. Cowlishaw 
  108.       ISBN 0-13-780735-X Prentice-Hall, 1985 
  109.       ISBN 0-13-780651-5 (Second edition), 1990 
  110.  
  111.     
  112.  
  113.  
  114. ΓòÉΓòÉΓòÉ 3.1. REXX Extensions ΓòÉΓòÉΓòÉ
  115.  
  116. RxCP290 is a set of REXX External Functions, packaged as a DLL. Some notes on 
  117. this follow, adapted from the IBM REXX User's Guide: 
  118.  
  119. In addition to the REXX built-in functions, you can use functions external to 
  120. REXX in your REXX programs. An external function may be simply another REXX 
  121. program, or it may be a function written in a compiled language. Before you can 
  122. use a function in a compiled language, you must tell REXX where the function is 
  123. located with the RxFuncAdd function. 
  124.  
  125. For example, the IBM Extended Services/2 product provides a REXX function for 
  126. the Emulator High Level Language Application Programming Interface (EHLLAPI). 
  127. The EHLLAPI function is in an OS/2 dynamic link library module named 
  128. SAAHLAPI.DLL. The function routine within SAAHLAPI.DLL is HllApiSrv. To use the 
  129. EHLLAPI function, you must first tell REXX where the function is found: 
  130.  
  131. call RxFuncAdd 'hllapi', 'saahlapi', 'hllapisrv'
  132.  
  133. You can now use the function HLLAPI in your REXX programs: 
  134.  
  135. rc = hllapi("Set_session_parms","CONPHYS")
  136. rc = hllapi("Connect",session)
  137. if (rc <> 0) then return rc
  138. rc = hllapi("Start_keystroke_intercept",session,"L")
  139.  
  140. You only need to register HLLAPI with RxFuncAdd one time. Once registered, a 
  141. function is available from anywhere on your OS/2 system. 
  142.  
  143.  
  144. ΓòÉΓòÉΓòÉ 3.2. Compound Symbols and Variables in REXX ΓòÉΓòÉΓòÉ
  145.  
  146. RxCP290 makes extensive use of a feature of the REXX Language known as Compound 
  147. Symbols. Here is a small example/discussion of the topic, adapted from the IBM 
  148. REXX User's Guide. 
  149.  
  150. There is a special class of symbols, called compound symbols, in which 
  151. variables and constants are combined to create groups of variables for easy 
  152. processing. A variable containing a period is treated as a compound symbol. 
  153. Some examples of compound symbols are: 
  154.  
  155. fred.3
  156. row.column
  157. array.I.J.
  158. gift.day
  159.  
  160. You can use compound symbols to create a collection of variables that can be 
  161. processed by their derived names. An example of a collection is: 
  162.  
  163. gift.1 = 'A partridge in a pear tree'
  164. gift.2 = 'Two turtle doves'
  165. gift.3 = 'Three French hens'
  166. gift.4 = 'Four calling birds', etc, etc
  167.  
  168. If you know what day it is, you know what gift will be given. Assign a variable 
  169. called DAY a value of 3. 
  170.  
  171. day = 3
  172.  
  173. Then the instruction 'say gift.day', as in the program shown below, displays 
  174. 'Three French hens' on the screen. When the REXX program is run, and the 
  175. expression 'gift.day' is evaluated, the following occurs: 
  176.  
  177.    1. REXX recognizes the symbol gift.day as compound because it contains a 
  178.       period. 
  179.  
  180.    2. REXX checks if the characters following the period form the name of a 
  181.       variable. In this example, it is the variable name day. 
  182.  
  183.    3. The value of day is substituted for its name, producing a derived name of 
  184.       gift.3. 
  185.  
  186.    4. The value of the variable gift.3 is the literal string 'Three French 
  187.       hens'. 
  188.  
  189.  If day had never been given a value, its value would have been its own name; 
  190.  day and the derived name of the compound symbol gift.day would have been 
  191.  GIFT.DAY. 
  192.  
  193.  The following whimsical program illustrates simple use of Compound Symbols: 
  194.  
  195.   /* What my true love sent ... */
  196.  
  197.   /* First, assign the gifts to the days   */
  198.   gift.1  = 'A partridge in a pear tree'
  199.   gift.2  = 'Two turtle doves'
  200.   gift.3  = 'Three French hens'
  201.   gift.4  = 'Four calling birds'
  202.   gift.5  = 'Five golden rings'
  203.   gift.6  = 'Six geese a-laying'
  204.   gift.7  = 'Seven swans a-swimming'
  205.   gift.8  = 'Eight maids a-milking'
  206.   gift.9  = 'Nine ladies dancing'
  207.   gift.10 = 'Ten lords a-leaping'
  208.   gift.11 = 'Eleven pipers piping'
  209.   gift.12 = 'Twelve drummers drumming'
  210.  
  211.   /* list all gifts from the 12th day to   */
  212.   /* the 1st day                               */
  213.  
  214.   do day=12 to 1
  215.    say gift.day
  216.   end
  217.  
  218.   /* now display the gift for a chosen day */
  219.   say "Type a number from 1 to 12."
  220.   pull day
  221.  
  222.   /* check for proper input */
  223.  
  224.   if  \ datatype(day,n) then      /* if the entry is not a number */
  225.     exit                          /* then exit the program        */
  226.  
  227.   if day < 1 | day > 12 then     /* same if it is out of range    */
  228.    exit
  229.  
  230.   say gift.day
  231.  
  232.  Some terminology in regard to Compound Symbols in REXX: 
  233.  
  234.  The stem of a compound symbol is the portion up to and including the first 
  235.  period. That is, it is a valid variable name that ends with a period. 
  236.  
  237.  The stem is followed by a tail, comprised of one or more valid symbols 
  238.  (constants or variables) separated by periods. You can refer to all the 
  239.  variables in an array by using the stem of the array. For example: 
  240.  
  241.   player. = 0
  242.   say player.1 player.2 player.golf      /* displays '0 0 0'  */
  243.  
  244.  It is often convenient to set all variables in an array to 0 in this way. 
  245.  
  246.  
  247. ΓòÉΓòÉΓòÉ 4. The RxCP290 Functions ΓòÉΓòÉΓòÉ
  248.  
  249. The RxCP290 REXX External Functions are explained here 
  250.  
  251.  
  252. ΓòÉΓòÉΓòÉ 4.1. RxLoadFuncsCP290 - Load the RxCP290 Functions into REXX ΓòÉΓòÉΓòÉ
  253.  
  254. Description: 
  255.  
  256. This function loads the RxCP290 X-10 communications functions, so that they are 
  257. available to REXX programs. Execution of this command makes these functions 
  258. available to all REXX programs in all sessions under 
  259. OS/2. These functions will remain available until explicitly dropped by the 
  260. RxDropFuncsCP290 function. 
  261.  
  262. Parameters: 
  263.  
  264. None 
  265.  
  266. Returns: 
  267.  
  268. 0 if successful. Non-zero returns indicate that none of the RxCP290 functions 
  269. have been loaded. 
  270.  
  271. Example: 
  272.  
  273.                                                /* Load RxLoadFuncsCP290      */
  274. call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
  275. call RxLoadFuncsCP290                          /* Call the RxCP290 function  */
  276.  
  277.  
  278. ΓòÉΓòÉΓòÉ 4.2. RxDropFuncsCP290 - Drop the RxCP290 Functions from REXX ΓòÉΓòÉΓòÉ
  279.  
  280. Description: 
  281.  
  282. This function drops the RxCP290 X-10 communications functions, so that they are 
  283. no longer available to REXX programs. Execution of this command makes these 
  284. functions unavailable to all REXX programs in all sessions in OS/2. These 
  285. functions will remain unavailable until explicitly loaded by the 
  286. RxLoadFuncsCP290 function. 
  287.  
  288. Parameters: 
  289.  
  290. None. 
  291.  
  292. Returns: 
  293.  
  294. 0 if successful. 
  295.  
  296. Example: 
  297.  
  298. call RxDropFuncsCP290
  299. say 'RxDropFuncsCP290, CP290rc:  'CP290rc
  300.  
  301.  
  302. ΓòÉΓòÉΓòÉ 4.3. RxInitCP290 - Initialize the Serial Port for the CP290 interface ΓòÉΓòÉΓòÉ
  303.  
  304. Description: 
  305.  
  306. RxInitCP290 initializes the serial port for communications with the CP290. It 
  307. initializes a Com Port Handle, which is used by all of the RxCP290 functions to 
  308. determine which serial port to communicate with. This Comm Handle variable 
  309. should be initialized in the REXX environment before using this function. 
  310.  
  311. Parameters: 
  312.  
  313. This function takes two parameters. The first parameter is a string with the 
  314. name of the serial port the CP290 is connected to. For this example, the CP290 
  315. is connected to COM2, so the parameter is 'COM2'. Note that this parameter must 
  316. be in all caps. 
  317.  
  318. The second parameter is the name of a REXX variable to store the Com Port 
  319. Handle in. This variable should have been initialized prior to calling 
  320. function. 
  321.  
  322. Returns: 
  323.  
  324. This function returns 0 when successful. Non-zero results indicate the port was 
  325. not opened. 
  326.  
  327. Example: 
  328.  
  329. CP290 = ''                                    /* Init Com Port Handle var    */
  330. rc = RxInitCP290('COM2', 'CP290')             /* Call the function           */
  331.  
  332.  
  333. ΓòÉΓòÉΓòÉ 4.4. RxCloseCP290 - Close the Serial Port for the CP290 Interface ΓòÉΓòÉΓòÉ
  334.  
  335. Description: 
  336.  
  337. RxCloseCP290 closes the serial port specified by the Com Port Handle, freeing 
  338. the port for use by other OS/2 applications. 
  339.  
  340. Parameters: 
  341.  
  342. This function takes one parameter, the Comm Port handle to close. 
  343.  
  344. Returns: 
  345.  
  346. Returns 0 if successful. 
  347.  
  348. Example: 
  349.  
  350. rc = RxCloseCP290(CP290)
  351.  
  352.  
  353. ΓòÉΓòÉΓòÉ 4.5. RxDiagCP290 - Run CP290 self-diagnostics ΓòÉΓòÉΓòÉ
  354.  
  355. Description 
  356.  
  357. This function commands the CP290 to perform it's internal diagnostic routines. 
  358. Execution of these routines will take about 10 seconds. All information in the 
  359. CP290 will be erased as a result of the execution of this function. 
  360.  
  361. Parameters 
  362.  
  363. This function takes a single parameter, the Com Port Handle produced by the 
  364. RxInitCP290 function. 
  365.  
  366. Returns 
  367.  
  368. This function returns zero if successful. A return code of 1 indicates a CP290 
  369. diagnostics failure not related to the serial communications. A return code of 
  370. less than zero indicates a communications failure, which may or may not be due 
  371. to CP290 failure. 
  372.  
  373. Example 
  374.  
  375. rc = RxDiagCP290(CP290)                        /* Call Function              */
  376.  
  377.  
  378. ΓòÉΓòÉΓòÉ 4.6. RxSetHCodeCP290 - Set CP290 House Code ΓòÉΓòÉΓòÉ
  379.  
  380. Description 
  381.  
  382. RxSetHcodeCP290 sets the CP290's Base Housecode. All information in the CP290 
  383. will be erased as a result of this function's execution. 
  384.  
  385. Parameters 
  386.  
  387. This function takes two parameters. The first parameter is the Comm Port 
  388. handle. 
  389.  
  390. The second parameter is a REXX string containing the new Housecode letter. 
  391. Valid housecodes are in the range "A" to "P". 
  392.  
  393. Returns 
  394.  
  395. RxSetHcode returns the CP290 ack status after execution. This value will be 
  396. zero if no information has been downloaded to the CP290. It will be a 1 after 
  397. download of any command. This can be used to determine if the CP290 has been 
  398. powered off. A return code of -1 indicates a communication error with the 
  399. CP290. 
  400.  
  401. Example 
  402.  
  403. rc = RxSetHCodeCP290(CP290, "D")               /* Set Housecode "D"          */
  404.  
  405.  
  406. ΓòÉΓòÉΓòÉ 4.7. RxSetTimeCP290 - Set CP290 Clock from Computer Clock ΓòÉΓòÉΓòÉ
  407.  
  408. Description 
  409.  
  410. RxSetTimeCP290 sets the CP290's internal clock from the host computer's 
  411. internal clock. 
  412.  
  413. Parameters 
  414.  
  415. This function takes one parameter, the Comm Port handle. 
  416.  
  417. Returns 
  418.  
  419. RxSetTime returns the CP290 ack status after execution. This value will be zero 
  420. if no information has been downloaded to the CP290. It will be a 1 after 
  421. download of any command. This can be used to determine if the CP290 has been 
  422. powered off. A return code of -1 indicates a communication error with the 
  423. CP290. 
  424.  
  425. Example 
  426.  
  427. rc = RxSetTimeCP290(CP290)                     /* Set current Computer Time  */
  428.  
  429.  
  430. ΓòÉΓòÉΓòÉ 4.8. RxGetTimeCP290 - Get current value of CP290 Clock and Housecode ΓòÉΓòÉΓòÉ
  431.  
  432. Description 
  433.  
  434. RxGetTimeCP290 returns the CP290's internal clock time and House Code. 
  435.  
  436. Parameters 
  437.  
  438. This function takes two parameters. The first parameter is the Comm Port 
  439. handle. 
  440.  
  441. The second parameter is the stem name of a REXX compound variable to receive 
  442. the results. The format of this stem variable is as follows: 
  443.  
  444.      <StemName>.0 = CP290 Acknowledge status 
  445.  
  446.      <StemName>.1 = Current Minutes Value from CP290. Will range from 0 to 59. 
  447.  
  448.      <StemName>.2 = Current Hours value from CP290. Will range from 0 to 23. 
  449.  
  450.      <StemName>.3 = Day of Week. One of the following: "MON", "TUE", "WED", 
  451.       "THU", "FRI", "SAT", or "SUN". 
  452.  
  453.      <StemName>.4 = Base Housecode, in range "A" to "P". 
  454.  
  455.  Returns 
  456.  
  457.  RxGetTimeCP290 returns the number of characters received. This should be equal 
  458.  to 12 for a normal call. 
  459.  
  460.  Example 
  461.  
  462.   rc = RxGetTimeCP290(CP290, 'result')    /* Get CP290 time                    */
  463.   say 'RxGetTimeCP290: ' rc               /* Print return code                 */
  464.  
  465.   say 'Status   - Result.0: 'result.0     /* CP290 Ack Status                  */
  466.   say 'Minutes  - Result.1: 'result.1     /* Minutes:  valid 00 - 59           */
  467.   say 'Hours    - Result.2: 'result.2     /* Hours:    valid 00 - 23           */
  468.   say 'Day Week - Result.3: 'result.3     /* Day of Week: in "MON","TUE","WED" */
  469.                                           /* "THU","FRI","SAT","SUN"           */
  470.   say 'Base     - Result.4: 'result.4     /* Base Housecode: valid "A" - "P"   */
  471.  
  472.  
  473. ΓòÉΓòÉΓòÉ 4.9. RxDirCmdCP290 - Send a Direct Command to a Single X-10 Module ΓòÉΓòÉΓòÉ
  474.  
  475. Description 
  476.  
  477. RxDirCmdCP290 sends a direct command to a single X-10 module. 
  478.  
  479. Parameters 
  480.  
  481. This function takes five parameters. The first parameter is the Comm Port 
  482. handle. 
  483.  
  484. The second parameter is the dim level, for the DIM function. Valid Values range 
  485. from 00(dimmest) to 15(brightest). 
  486.  
  487. The third parameter is the function code. This can be one of "ON", "OFF", or 
  488. "DIM". 
  489.  
  490. The fourth parameter is a REXX string containing the new Housecode letter. 
  491. Valid housecodes are in the range "A" to "P". 
  492.  
  493. Finally, the last parameter is the module number to affect. Valid values are in 
  494. the range 1 through 16. 
  495.  
  496. Returns 
  497.  
  498. RxDirCmd returns the CP290 ack status after execution. This value will be zero 
  499. if no information has been downloaded to the CP290. It will be a 1 after 
  500. download of any command. This can be used to determine if the CP290 has been 
  501. powered off. A return code of -1 indicates a communication error with the 
  502. CP290. 
  503.  
  504. Example 
  505.  
  506. rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4)     /* Turn on Module D4          */
  507.  
  508.  
  509. ΓòÉΓòÉΓòÉ 4.10. RxDirCmdManyCP290 - Send a Direct command to several X-10 Modules ΓòÉΓòÉΓòÉ
  510.  
  511. Description 
  512.  
  513. RxDirCmdManyCP290 sends a direct command to a series of X-10 modules. 
  514.  
  515. Parameters 
  516.  
  517. This function takes five parameters. The first parameter is the Comm Port 
  518. handle. 
  519.  
  520. The second parameter is the dim level, for the DIM function. Valid Values range 
  521. from 00(dimmest) to 15(brightest). 
  522.  
  523. The third parameter is the function code. This can be one of "ON", "OFF", or 
  524. "DIM". 
  525.  
  526. The fourth parameter is a REXX string containing the new Housecode letter. 
  527. Valid housecodes are in the range "A" to "P". 
  528.  
  529. Finally, the last parameter is the stem name of a REXX compound variable that 
  530. contains a list of the modules to command. The format of this variable is as 
  531. follows: 
  532.  
  533.      <StemName>.0 = Number of Modules to send command to. Valid values are 1 
  534.       to 16. 
  535.  
  536.      <StemName>.1 = First Module Number for command. Valid Values are 1 to 16. 
  537.       Modules need not be listed in any order. 
  538.  
  539.      <StemName>.2 = Second Module Number for command. Valid Values are 1 to 
  540.       16. Modules need not be listed in any order. 
  541.  
  542.      <StemName>.n = First Module Number for command. Valid Values are 1 to 16. 
  543.       Modules need not be listed in any order. n here stands for the value in 
  544.       <StemName>.0. 
  545.  
  546.  Returns 
  547.  
  548.  RxDirCmdMany returns the CP290 ack status after execution. This value will be 
  549.  zero if no information has been downloaded to the CP290. It will be a 1 after 
  550.  download of any command. This can be used to determine if the CP290 has been 
  551.  powered off. A return code of -1 indicates a communication error with the 
  552.  CP290. 
  553.  
  554.  Example 
  555.  
  556.   dcom.0 = 5                             /* 5 modules to command               */
  557.   dcom.1 = 4                             /* 1st module - Module  4             */
  558.   dcom.2 = 5                             /* 2nd module - Module  5             */
  559.   dcom.3 = 16                            /* 3rd module - Module 16             */
  560.   dcom.4 = 10                            /* 4th module - Module 10             */
  561.   dcom.5 = 7                             /* 5th module - Module  7             */
  562.  
  563.   rc = RxDirCmdManyCP290(CP290, 8, "OFF" ,"D", "dcom")  /* call the function   */
  564.  
  565.  
  566. ΓòÉΓòÉΓòÉ 4.11. RxCmdUploadCP290 - Get CP290 Command Execution Report ΓòÉΓòÉΓòÉ
  567.  
  568. Description 
  569.  
  570. Every time the CP290 executes a command to an X-10 module, it sends a Command 
  571. Upload to the host computer. This is true whether the action was caused by a 
  572. RxDirCmdCP290 REXX Function, an event execution in the CP290, or manual control 
  573. from the CP290 keypad. This function receives this report, and formats the 
  574. uploaded information in a REXX compound variable. 
  575.  
  576. Parameters 
  577.  
  578. This function takes two parameters. The first parameter is the Comm Port 
  579. handle. 
  580.  
  581. The second parameter is the stem name of a REXX compound variable to receive 
  582. the results. The format of this stem variable is as follows: 
  583.  
  584.      <StemName>.0 = CP290 Ack Status 
  585.  
  586.      <StemName>.1 = CP290 Base HouseCode. Valid Values are "A" through "P". 
  587.  
  588.      <StemName>.2 = Function executed by CP290. Will be either "ON", "OFF", or 
  589.       "DIM". 
  590.  
  591.      <StemName>.3.0 = Number of Modules affected by command. Valid Values are 
  592.       in range 1 to 16. 
  593.  
  594.      <StemName>.3.1 = First Module affected by command. Valid values are in 
  595.       range 1 to 16. 
  596.  
  597.      <StemName>.3.n = Nth Module affected by command, where n = 
  598.       <StemName>.3.0. Valid values are in range 1 to 16. 
  599.  
  600.  Returns 
  601.  
  602.  RxCmd UploadCP290 returns the number of characters received. This should be 
  603.  equal to 12 for a normal call. If no command upload has been received, this 
  604.  function will return 0. 
  605.  
  606.  Example 
  607.  
  608.  In this example, the call to RxCmdUploadCP290 is contained within a do while 
  609.  loop. This waits until the command is received by the REXX program before 
  610.  continuing. If the com port is left open for any period of time, this function 
  611.  should be called periodically to check to see if any events that would cause a 
  612.  report (such as manual key presses, or timer events) have occured. This will 
  613.  keep the serial input and output buffers synchronized. 
  614.  
  615.   do while rc < 5
  616.      rc = RxCmdUploadCP290(CP290, 'result')
  617.   end
  618.  
  619.   say 'Status       - Result.0:   'result.0     /* CP290 ack status           */
  620.   say 'Hcode        - Result.1:   'result.1     /* House code: "A"-"P"        */
  621.   say 'Function     - Result.2:   'result.2     /* Function: "ON","OFF","DIM" */
  622.   say '# of Modules - Result.3.0: 'result.3.0   /* Number of modules affected */
  623.   do i = 1 to result.3.0
  624.      say 'Module 'i'     - Result.3.'i': 'result.3.i /* Module number         */
  625.   end
  626.   say 'Base          - Result.4:   'result.4     /* CP290 Base Housecode       */
  627.  
  628.  
  629. ΓòÉΓòÉΓòÉ 4.12. RxDwnLdEvtCP290 - Download a Timer Event to the CP290 ΓòÉΓòÉΓòÉ
  630.  
  631. Description 
  632.  
  633. RxDwnLdEvtCP290 downloads a Timer event to the CP290 for later execution. 
  634.  
  635. Parameters 
  636.  
  637. This function takes three parameters. The first parameter is the Comm Port 
  638. handle. 
  639.  
  640. The second parameter is the event number. Valid Values range from 0 to 127. 
  641.  
  642. Finally, the last parameter is the stem name of a REXX compound variable that 
  643. contains the timer event information. Note the similarity of this compound 
  644. variable format to the one used by RxGetEventsCP290. The format of this 
  645. compound variable is as follows: 
  646.  
  647.      <StemName>.0 = 0. This is not used by RxDwnLdEvtCP290, but is present for 
  648.       compatibility with the format of the compound variable used by 
  649.       RxgetEventsCP290. 
  650.  
  651.      <StemName>.1 = Timer Mode - valid entries are "NORMAL", "SECURITY", 
  652.       "TODAY", "TOMORROW", or "CLEAR". 
  653.  
  654.      <StemName>.2.0 = Number of Days for event, valid range is 1 to 7. 
  655.  
  656.      <StemName>.2.1 = First Day for Timed Event. Days need not be in any 
  657.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  658.       "SUN". 
  659.  
  660.      <StemName>.2.2 = Second Day for Timed Event. Days need not be in any 
  661.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  662.       "SUN". 
  663.  
  664.      <StemName>.2.n = Nth Day for Timed Event, where n = <StemName>.2.0. Days 
  665.       need not be in any order. Valid values are "MON", "TUE", "WED", "THU", 
  666.       "FRI", "SAT", or "SUN". 
  667.  
  668.      <StemName>.3 = Event Time - Hours: Range 0-23. 
  669.  
  670.      <StemName>.4 = Event Time - Minutes: Range 0-59. 
  671.  
  672.      <StemName>.5.0 = Number of Modules for Event. Valid range is 1 to 16. 
  673.  
  674.      <StemName>.5.1 = First Module for Event. Valid range is 1 to 16. Modules 
  675.       need not be listed in any order. 
  676.  
  677.      <StemName>.5.2 = Second Module for Event. Valid range is 1 to 16. Modules 
  678.       need not be listed in any order. 
  679.  
  680.      <StemName>.5.n = Nth Module for Event, where n = <StemName>.5.0. Valid 
  681.       range is 1 to 16. Modules need not be listed in any order. 
  682.  
  683.      <StemName>.6 = HouseCode for Event. Valid range is "A" to "P". 
  684.  
  685.      <StemName>.7 = Dim Level for Event. Valid range is 0 (dimmest) to 15 
  686.       (brightest). 
  687.  
  688.      <StemName>.8 = Function for Event. Valid values are one of "ON", "OFF", 
  689.       or "DIM". 
  690.  
  691.  Returns 
  692.  
  693.  RxDwnLdEvt returns the CP290 ack status after execution. This value will be 
  694.  zero if no information has been downloaded to the CP290. It will be a 1 after 
  695.  download of any command. This can be used to determine if the CP290 has been 
  696.  powered off. A return code of -1 indicates a communication error with the 
  697.  CP290. 
  698.  
  699.  Example 
  700.  
  701.   event.0   = 0                /* Not used - here for compatibility with       */
  702.                                /* RxGetEventsCP290 Compound Variable.          */
  703.  
  704.   event.1   = "NORMAL"         /* Timer Mode - valid entries are "NORMAL",     */
  705.                                /* "SECURITY","TODAY","TOMORROW", and "CLEAR"   */
  706.  
  707.   event.2.0 = 4                /* Number of Days for Event: range 1-7          */
  708.  
  709.   event.2.1 = "WED"            /* First Day - one of "MON","TUE","WED","THU",  */
  710.   event.2.2 = "THU"            /* "SAT", or "SUN".                             */
  711.   event.2.3 = "FRI"
  712.   event.2.4 = "MON"
  713.  
  714.   event.3   = 15               /* Event Time - Hours:   Range  0-23            */
  715.  
  716.   event.4   = 25               /* Event Time - Minutes: Range  0-59            */
  717.  
  718.   event.5.0 = 4                /* Number of Modules for Event: Range 1-16      */
  719.   event.5.1 = 4                /* First Module: Range 1-16                     */
  720.   event.5.2 = 3                /* 2nd Module                                   */
  721.   event.5.3 = 16               /* 3rd Module                                   */
  722.   event.5.4 = 10               /* 4th Module                                   */
  723.  
  724.   event.6   = "D"              /* Housecode: Range "A"-"P"                     */
  725.  
  726.   event.7   = 7                /* Dim Level: Range 0(dimmest)-15(brightest)    */
  727.  
  728.   event.8   = "DIM"            /* Function - One of "ON","OFF","DIM            */
  729.  
  730.   rc = RxDwnldEvtCP290(CP290, 1,event)  /* call the function                   */
  731.  
  732.  
  733. ΓòÉΓòÉΓòÉ 4.13. RxGetEventsCP290 - Get All Active Timer Events from the CP290 ΓòÉΓòÉΓòÉ
  734.  
  735. Description 
  736.  
  737. This function gets all the Timer Event information from the CP290, and makes it 
  738. available to the calling REXX program in the form of a large compound variable. 
  739.  
  740. Parameters 
  741.  
  742. This function takes two parameters. The first parameter is the Comm Port 
  743. handle. 
  744.  
  745. The second parameter is the stem name of a REXX compound variable to receive 
  746. the results. This compound variable consists of several structures in the same 
  747. format as the compound variable used by RxDwnLdEvtCP290, for convenience. The 
  748. format of this compound variable is as follows: 
  749.  
  750.      <StemName>.0.0 = This will be 0 if Timer Event 0 does not exist, and 1 if 
  751.       it does. In the event that Timer Event 0 does not exist, there will be no 
  752.       data associated with <StemName>.0.1 through <StemName>.0.8. 
  753.  
  754.      <StemName>.0.1 = Timer Mode for Event 0 - valid entries are "NORMAL", 
  755.       "SECURITY", "TODAY", "TOMORROW", or "CLEAR". 
  756.  
  757.      <StemName>.0.2.0 = Number of Days for Event 0, valid range is 1 to 7. 
  758.  
  759.      <StemName>.0.2.1 = First Day for Timed Event 0. Days need not be in any 
  760.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  761.       "SUN". 
  762.  
  763.      <StemName>.0.2.2 = Second Day for Timed Event 0. Days need not be in any 
  764.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  765.       "SUN". 
  766.  
  767.      <StemName>.0.2.n = Nth Day for Timed Event 0, where n = <StemName>.0.2.0. 
  768.       Days need not be in any order. Valid values are "MON", "TUE", "WED", 
  769.       "THU", "FRI", "SAT", or "SUN". 
  770.  
  771.      <StemName>.0.3 = Event 0 Time - Hours: Range 0-23. 
  772.  
  773.      <StemName>.0.4 = Event 0 Time - Minutes: Range 0-59. 
  774.  
  775.      <StemName>.0.5.0 = Number of Modules for Event 0. Valid range is 1 to 16. 
  776.  
  777.      <StemName>.0.5.1 = First Module for Event 0. Valid range is 1 to 16. 
  778.       Modules need not be listed in any order. 
  779.  
  780.      <StemName>.0.5.2 = Second Module for Event 0. Valid range is 1 to 16. 
  781.       Modules need not be listed in any order. 
  782.  
  783.      <StemName>.0.5.n = Nth Module for Event 0, where n = <StemName>.0.5.0. 
  784.       Valid range is 1 to 16. Modules need not be listed in any order. 
  785.  
  786.      <StemName>.0.6 = HouseCode for Event 0. Valid range is "A" to "P". 
  787.  
  788.      <StemName>.0.7 = Dim Level for Event 0. Valid range is 0 (dimmest) to 15 
  789.       (brightest). 
  790.  
  791.      <StemName>.0.8 = Function for Event 0. Valid values are one of "ON", 
  792.       "OFF", or "DIM". 
  793.  
  794.      <StemName>.n.0 = This will be 0 if Timer Event n does not exist, and 1 if 
  795.       it does. In the event that Timer Event n does not exist, there will be no 
  796.       data associated with <StemName>.n.1 through <StemName>.n.8. This pattern 
  797.       continues for n = 1 to 127. 
  798.  
  799.      <StemName>.n.1 = Timer Mode for Event n - valid entries are "NORMAL", 
  800.       "SECURITY", "TODAY", "TOMORROW", or "CLEAR". 
  801.  
  802.      <StemName>.n.2.0 = Number of Days for Event n, valid range is 1 to 7. 
  803.  
  804.      <StemName>.n.2.1 = First Day for Timed Event n. Days need not be in any 
  805.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  806.       "SUN". 
  807.  
  808.      <StemName>.2.2 = Second Day for Timed Event n. Days need not be in any 
  809.       order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or 
  810.       "SUN". 
  811.  
  812.      <StemName>.n.2.m = Mth Day for Timed Event n, where m = <StemName>.n.2.0. 
  813.       Days need not be in any order. Valid values are "MON", "TUE", "WED", 
  814.       "THU", "FRI", "SAT", or "SUN". 
  815.  
  816.      <StemName>.n.3 = Event n Time - Hours: Range 0-23. 
  817.  
  818.      <StemName>.n.4 = Event n Time - Minutes: Range 0-59. 
  819.  
  820.      <StemName>.n.5.0 = Number of Modules for Event n. Valid range is 1 to 16. 
  821.  
  822.      <StemName>.n.5.1 = First Module for Event n. Valid range is 1 to 16. 
  823.       Modules need not be listed in any order. 
  824.  
  825.      <StemName>.n.5.2 = Second Module for Event n. Valid range is 1 to 16. 
  826.       Modules need not be listed in any order. 
  827.  
  828.      <StemName>.n.5.m = Mth Module for Event n, where m = <StemName>n.5.0. 
  829.       Valid range is 1 to 16. Modules need not be listed in any order. 
  830.  
  831.      <StemName>.n.6 = HouseCode for Event n. Valid range is "A" to "P". 
  832.  
  833.      <StemName>.n.7 = Dim Level for Event n. Valid range is 0 (dimmest) to 15 
  834.       (brightest). 
  835.  
  836.      <StemName>.n.8 = Function for Event n. Valid values are one of "ON", 
  837.       "OFF", or "DIM". 
  838.  
  839.  Returns 
  840.  
  841.  RxGetEventsCP290 returns the number of characters received. 
  842.  
  843.  Example 
  844.  
  845.   rc = RxGetEventsCP290(CP290, 'bigevt')    /* Call the function               */
  846.   say 'RxGetEventsCP290:  'rc
  847.  
  848.   do i=0 to 127
  849.    if BigEvt.i.0 = 1 then Do                /* If this value = 1, there is a   */
  850.                                             /* corresponding event number.     */
  851.                                             /* Otherwise, value is 0           */
  852.     say 'BigEvt.'i'.0  :  'BigEvt.i.0       /* 1 = event, 0 = no event         */
  853.     say 'BigEvt.'i'.1  :  'BigEvt.i.1       /* Timer Mode Sel - as RxDwnLdEvt  */
  854.     say 'BigEvt.'i'.2.0:  'BigEvt.i.2.0     /* Number of Days - as RxDwnLdEvt  */
  855.     Do j = 1 to BigEvt.i.2.0
  856.      say 'BigEvt.'i'.2.'j':  'BigEvt.i.2.j  /* Day info - as RxDwnLdEvt        */
  857.     end
  858.     say 'BigEvt.'i'.3  :  'BigEvt.i.3       /* Hours:                          */
  859.     say 'BigEvt.'i'.4  :  'BigEvt.i.4       /* Minutes:                        */
  860.     say 'BigEvt.'i'.5.0:  'BigEvt.i.5.0     /* Number of Modules               */
  861.     Do j = 1 to BigEvt.i.5.0
  862.      say 'BigEvt.'i'.5.'j':  'BigEvt.i.5.j  /* Module number                   */
  863.     end
  864.     say 'BigEvt.'i'.6  :  'BigEvt.i.6       /* Housecode                       */
  865.     say 'BigEvt.'i'.7  :  'BigEvt.i.7       /* Dim Level                       */
  866.     say 'BigEvt.'i'.8  :  'Bigevt.i.8       /* Function                        */
  867.     end
  868.   end
  869.  
  870.  
  871. ΓòÉΓòÉΓòÉ 5. RxCP290 Example Programs ΓòÉΓòÉΓòÉ
  872.  
  873. The REXX example programs shipped with teh RxCP290 package are described here 
  874.  
  875.  
  876. ΓòÉΓòÉΓòÉ 5.1. Smalltst.cmd - A Small Example Program ΓòÉΓòÉΓòÉ
  877.  
  878. Smalltst.cmd is provided as a minimal example - it simply loads the RxCP290 
  879. functions, opens the comm port, turns on a single module, closes the comm port, 
  880. and de-registers the functions. This is an example of what a CMD file called 
  881. from cron, or any other OS/2 program that executes programs at specific times, 
  882. might look like. 
  883.  
  884. If you are going to be using the RxCP290 functions a lot, it might be better to 
  885. register the functions in STARTUP.CMD, so that they are always available to all 
  886. REXX programs in the system. 
  887.  
  888. /*                Small Rexx Program to Demo RXCP290                          */
  889.  
  890. /* This small program Loads the RXCP290 Functions, opens COM2 for comms to    */
  891. /* the CP290, turns on Module D4, receives the acknowledgement from the CP290 */
  892. /* closes the comport, and Drops the RxCP290 Functions.                       */
  893.  
  894. call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
  895. call RxLoadFuncsCP290                      /* Load RxCP290 Routines           */
  896. CP290 = ''                                 /* Initialize Com Port Handle Var  */
  897. rc = RxInitCP290('COM2', 'CP290')          /* Initialize Com Port             */
  898. rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4) /* Issue a direct command          */
  899. do while rc < 5
  900.    rc = RxCmdUploadCP290(CP290, 'result')  /* Get the Report upon completion  */
  901. end
  902. rc = RxCloseCP290(CP290)                   /* Close Communications            */
  903. call RxDropFuncsCP290                      /* Drop RXCP290 Functions          */
  904.  
  905.  
  906. ΓòÉΓòÉΓòÉ 5.2. TestCP.Cmd - Working Examples of All RxCP290 Functions ΓòÉΓòÉΓòÉ
  907.  
  908. TestCP.CMD provides working examples of all the functions in RxCP290, by 
  909. sending a variety of commands to module D4. You may wish to edit this script to 
  910. use a different module before running this. Return codes and results of all 
  911. function calls are printed to the screen. 
  912.  
  913. /*****************************************************************************/
  914. /*    TestCP.CMD A REXX Program to test all of the RxCP290 Functions         */
  915. /*****************************************************************************/
  916. /* This program demonstrates the proper use of all of the RxCP290 functions. */
  917. /* Each Function has it's input and output parameters described here, along  */
  918. /* with usage guidelines. Output from each function is printed to the screen */
  919. /*****************************************************************************/
  920.  
  921. /*****************************************************************************/
  922. /* Return Codes:                                                             */
  923. /*                                                                           */
  924. /* All RxCP290 functions return a value indicating success or failure. This  */
  925. /* return code is returned via the normal REXX Function return procedure     */
  926. /* (ie - rc = RxFunc() ).  The return code from an RxCP290 function is also  */
  927. /* placed in the special variable CP290rc.  In all cases the returned value  */
  928. /* will be the same in these two locations.                                  */
  929. /*****************************************************************************/
  930.  
  931. /*****************************************************************************/
  932. /*          RxLoadFuncsCP290 - Load the RxCP290 Functions into REXX          */
  933. /*****************************************************************************/
  934. /* Description:                                                              */
  935. /*                                                                           */
  936. /* This function loads the RxCP290 X-10 communications functions, so that    */
  937. /* they are available to REXX programs.  Execution of this command makes     */
  938. /* these functions available to all REXX programs in alll sessions under     */
  939. /* OS/2.  These functions will remain available until explicitly dropped by  */
  940. /* The RxDropFuncsCP290 function.                                            */
  941. /*****************************************************************************/
  942. /* Parameters:                                                               */
  943. /*                                                                           */
  944. /* None                                                                      */
  945. /*****************************************************************************/
  946. /* Returns:                                                                  */
  947. /*                                                                           */
  948. /* 0 if successful                                                           */
  949. /* Non- zero returns indicate that none of the RxCP290 functions have been   */
  950. /* loaded.                                                                   */
  951. /*****************************************************************************/
  952. /* Example:                                                                  */
  953.  
  954.                                                /* Load RxLoadFuncsCP290      */
  955. call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
  956. call RxLoadFuncsCP290                          /* Call the RxCP290 function  */
  957. say 'RxLoadFuncsCP290, CP290rc:   'CP290rc     /* Show results               */
  958.  
  959. /*****************************************************************************/
  960. /*                RxInitCP290 - Initialize Communication Port                */
  961. /*****************************************************************************/
  962. /* Description:                                                              */
  963. /*                                                                           */
  964. /* RxInitCP290 initializes the serial port for communications with the CP290.*/
  965. /* It initializes a Com Port Handle, which is used by all of the RxCP290     */
  966. /* functions to determine which serial port to communicate with.  This Comm  */
  967. /* Handle variable should be initialized in the REXX environment before      */
  968. /* using this function.                                                      */
  969. /*****************************************************************************/
  970. /* Parameters:                                                               */
  971. /*                                                                           */
  972. /* This function takes two parameters. The first parameter is a string with  */
  973. /* the name of the serial port the CP290 is connected to.  For this example, */
  974. /* the CP290 is connected to COM2, so the parameter is 'COM2'. Note that     */
  975. /* This parameter must be in all caps.                                       */
  976. /*                                                                           */
  977. /* The second parameter is the name of a REXX variable to store the Com Port */
  978. /* Handle in.  This variable should have been initialized prior to calling   */
  979. /* function.                                                                 */
  980. /*****************************************************************************/
  981. /* Returns:                                                                  */
  982. /*                                                                           */
  983. /* This function returns 0 when successful. Non-zero results indicate the    */
  984. /* was not opened.                                                           */
  985. /*****************************************************************************/
  986. /* Example:                                                                  */
  987.  
  988. CP290 = ''                                    /* Init Com Port Handle var    */
  989. rc = RxInitCP290('COM2', 'CP290')             /* Call the function           */
  990. say 'RxInitCP290:   'rc', CP290rc:   'CP290rc /* print the results           */
  991.  
  992. /*****************************************************************************/
  993. /*                   RxDiagCP290 - Perform CP290 Self-Test                   */
  994. /*****************************************************************************/
  995. /* Description:                                                              */
  996. /*                                                                           */
  997. /* This function commands the CP290 to perform it's internal diagnostic      */
  998. /* routines.  Execution of these routines will take about 10 seconds.   All  */
  999. /* information in the CP290 will be erased as a result of the execution of   */
  1000. /* this function.                                                            */
  1001. /*****************************************************************************/
  1002. /* Parameters:                                                               */
  1003. /*                                                                           */
  1004. /* This function takes a single parameter, the Com Port Handle produced by   */
  1005. /* the RxInitCP290 function.                                                 */
  1006. /*****************************************************************************/
  1007. /* Returns:                                                                  */
  1008. /*                                                                           */
  1009. /* This function returns zero if successful.  A return code of 1 indicates   */
  1010. /* a CP290 diagnostics failure not related to the serial communications.  A  */
  1011. /* return code of less than zero indicates a communications failure, which   */
  1012. /* may or may not be due to CP290 failure.                                   */
  1013. /*****************************************************************************/
  1014. /* Example:                                                                  */
  1015.  
  1016. rc = RxDiagCP290(CP290)                        /* Call Function              */
  1017. say 'RxDiagCP290:   'rc', CP290rc:   'CP290rc  /* Print return code          */
  1018.  
  1019. /*****************************************************************************/
  1020. /*                RxSetHCodeCP290 - Set CP290 Base House Code                */
  1021. /*****************************************************************************/
  1022. /* Description:                                                              */
  1023. /*                                                                           */
  1024. /* RxSetHcodeCP290 sets the CP290's Base Housecode.  All information in the  */
  1025. /* CP290 will be erased as a result of this function's execution.            */
  1026. /*****************************************************************************/
  1027. /* Parameters:                                                               */
  1028. /*                                                                           */
  1029. /* This function takes two parameters. The first parameter is the Comm Port  */
  1030. /* handle.                                                                   */
  1031. /*                                                                           */
  1032. /* The second parameter is a REXX string containing the new Housecode letter.*/
  1033. /* Valid housecodes are in the range "A" to "P".                             */
  1034. /*****************************************************************************/
  1035. /* Returns:                                                                  */
  1036. /*                                                                           */
  1037. /* RxSetHcode returns the CP290 ack status after execution. This value will  */
  1038. /* be zero if no information has been downloaded to the CP290. It will be a  */
  1039. /* 1 after download of any command.  This can be used to determine if the    */
  1040. /* CP290 has been powered off. A return code of -1 indicates a communication */
  1041. /* error with the CP290.                                                     */
  1042. /*****************************************************************************/
  1043. /* Example:                                                                  */
  1044.  
  1045. rc = RxSetHCodeCP290(CP290, "D")               /* Set Housecode "D"          */
  1046. say 'RxSetHCodeCP290: 'rc                      /* Print the results          */
  1047.  
  1048. /*****************************************************************************/
  1049. /*                 RxSetTimeCP290 - Set CP290 Base House Code                */
  1050. /*****************************************************************************/
  1051. /* Description:                                                              */
  1052. /*                                                                           */
  1053. /* RxSetTimeCP290 sets the CP290's internal clock from the host computer's   */
  1054. /* internal clock.                                                           */
  1055. /*****************************************************************************/
  1056. /* Parameters:                                                               */
  1057. /*                                                                           */
  1058. /* This function takes one parameter, the Comm Port handle                   */
  1059. /*****************************************************************************/
  1060. /* Returns:                                                                  */
  1061. /*                                                                           */
  1062. /* RxSetTime returns the CP290 ack status after execution. This value will   */
  1063. /* be zero if no information has been downloaded to the CP290. It will be a  */
  1064. /* 1 after download of any command.  This can be used to determine if the    */
  1065. /* CP290 has been powered off. A return code of -1 indicates a communication */
  1066. /* error with the CP290.                                                     */
  1067. /*****************************************************************************/
  1068. /* Example:                                                                  */
  1069.  
  1070. rc = RxSetTimeCP290(CP290)                     /* Set current Computer Time  */
  1071. say 'RxSetTimeCP290: ' rc                      /* Print the results          */
  1072.  
  1073. /*****************************************************************************/
  1074. /*                RxGetTimeCP290 - Get CP290 Time and House Code             */
  1075. /*****************************************************************************/
  1076. /* Description:                                                              */
  1077. /*                                                                           */
  1078. /* RxGetTimeCP290 returns the CP290's internal clock time and House Code.    */
  1079. /*****************************************************************************/
  1080. /* Parameters:                                                               */
  1081. /*                                                                           */
  1082. /* This function takes two parameters. The first parameter is the Comm Port  */
  1083. /* handle.                                                                   */
  1084. /*                                                                           */
  1085. /* The second parameter is the stem name of a REXX compound variable to      */
  1086. /* receive the results. The format of this stem variable is shown below, in  */
  1087. /* section that prints the results.                                          */
  1088. /*****************************************************************************/
  1089. /* Returns:                                                                  */
  1090. /*                                                                           */
  1091. /* RxGetTimeCP290 returns the number of characters received.  This should be */
  1092. /* equal to 12 for a normal call.                                            */
  1093. /*****************************************************************************/
  1094. /* Example:                                                                  */
  1095.  
  1096. rc = RxGetTimeCP290(CP290, 'result')    /* Get CP290 time                    */
  1097. say 'RxGetTimeCP290: ' rc               /* Print return code                 */
  1098.  
  1099. say 'Status   - Result.0: 'result.0     /* CP290 Ack Status                  */
  1100. say 'Minutes  - Result.1: 'result.1     /* Minutes:  valid 00 - 59           */
  1101. say 'Hours    - Result.2: 'result.2     /* Hours:    valid 00 - 23           */
  1102. say 'Day Week - Result.3: 'result.3     /* Day of Week: in "MON","TUE","WED" */
  1103.                                         /* "THU","FRI","SAT","SUN"           */
  1104. say 'Base     - Result.4: 'result.4     /* Base Housecode: valid "A" - "P"   */
  1105.  
  1106. /*****************************************************************************/
  1107. /*                 RxDirCmdCP290 - Send CP290 direct command                 */
  1108. /*****************************************************************************/
  1109. /* Description:                                                              */
  1110. /*                                                                           */
  1111. /* RxDirCmdCP290 sends a direct command to a single X-10 module              */
  1112. /*****************************************************************************/
  1113. /* Parameters:                                                               */
  1114. /*                                                                           */
  1115. /* This function takes five parameters. The first parameter is the Comm Port */
  1116. /* handle.                                                                   */
  1117. /*                                                                           */
  1118. /* The second parameter is the dim level, for the DIM function. Valid Values */
  1119. /* range from 00(dimmest) to 15(brightest).                                  */
  1120. /*                                                                           */
  1121. /* The third parameter is the function code. This can be one of "ON", "OFF", */
  1122. /* or "DIM".                                                                 */
  1123. /*                                                                           */
  1124. /* The fourth parameter is a REXX string containing the new Housecode letter.*/
  1125. /* Valid housecodes are in the range "A" to "P".                             */
  1126. /*                                                                           */
  1127. /* Finally, the last parameter is the module number to affect. Valid values  */
  1128. /* are in the range 1 through 16.                                            */
  1129. /*****************************************************************************/
  1130. /* Returns:                                                                  */
  1131. /*                                                                           */
  1132. /* RxDirCmd returns the CP290 ack status after execution. This value will    */
  1133. /* be zero if no information has been downloaded to the CP290. It will be a  */
  1134. /* 1 after download of any command.  This can be used to determine if the    */
  1135. /* CP290 has been powered off. A return code of -1 indicates a communication */
  1136. /* error with the CP290.                                                     */
  1137. /*****************************************************************************/
  1138. /* Example:                                                                  */
  1139.  
  1140. rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4)     /* Turn on Module D4          */
  1141. say 'RxDirCmdCP290: 'rc', CP290rc:   'CP290rc
  1142.  
  1143. /*****************************************************************************/
  1144. /*                RxCmdUploadCP290 - Get CP290 execution report              */
  1145. /*****************************************************************************/
  1146. /* Description:                                                              */
  1147. /*                                                                           */
  1148. /* Every time the CP290 executes a command to an X-10 module, it sends a     */
  1149. /* Command Upload to the host computer. This is true whether the action was  */
  1150. /* caused by a RxDirCmdCP290 REXX Function, an event execution in the CP290, */
  1151. /* or manual control from the CP290 keypad.  This function receives this     */
  1152. /* report, and formats the uploaded information in a REXX compound variable. */
  1153. /*****************************************************************************/
  1154. /* Parameters:                                                               */
  1155. /*                                                                           */
  1156. /* This function takes two parameters. The first parameter is the Comm Port  */
  1157. /* handle.                                                                   */
  1158. /*                                                                           */
  1159. /* The second parameter is the stem name of a REXX compound variable to      */
  1160. /* receive the results. The format of this stem variable is shown below, in  */
  1161. /* section that prints the results.                                          */
  1162. /*****************************************************************************/
  1163. /* Usage Notes:                                                              */
  1164. /*                                                                           */
  1165. /* In this example, the call to RxCmdUploadCP290 is contained within a do    */
  1166. /* while loop. This waits until the command is received by the REXX program  */
  1167. /* before continuing.  If the com  port is left open for any period of time, */
  1168. /* this function should be called periodically to check to see if any events */
  1169. /* that would cause a report (such as manual key presses, or timer events).  */
  1170. /* This will keep the serial input and output buffers synchronized.          */
  1171. /*****************************************************************************/
  1172. /* Returns:                                                                  */
  1173. /*                                                                           */
  1174. /* RxCmd UploadCP290 returns the number of characters received.  This should */
  1175. /* be equal to 12 for a normal call. If no command upload has been received, */
  1176. /* this function will return 0.                                              */
  1177. /*****************************************************************************/
  1178. /* Example:                                                                  */
  1179.  
  1180. do while rc < 5
  1181.    rc = RxCmdUploadCP290(CP290, 'result')
  1182. end
  1183.  
  1184. say 'Status       - Result.0:   'result.0     /* CP290 ack status           */
  1185. say 'Hcode        - Result.1:   'result.1     /* House code: "A"-"P"        */
  1186. say 'Function     - Result.2:   'result.2     /* Function: "ON","OFF","DIM" */
  1187. say '# of Modules - Result.3.0: 'result.3.0   /* Number of modules affected */
  1188. do i = 1 to result.3.0
  1189.    say 'Module 'i'     - Result.3.'i': 'result.3.i /* Module number         */
  1190. end
  1191. say 'Base          - Result.4:   'result.4     /* CP290 Base Housecode       */
  1192.  
  1193. /*****************************************************************************/
  1194. /*       RxDirCmdManyCP290 - Send Direct Command to Many X-10 Modules        */
  1195. /*****************************************************************************/
  1196. /* Description:                                                              */
  1197. /*                                                                           */
  1198. /* RxDirCmdManyCP290 sends a direct command to a series of X-10 modules      */
  1199. /*****************************************************************************/
  1200. /* Parameters:                                                               */
  1201. /*                                                                           */
  1202. /* This function takes five parameters. The first parameter is the Comm Port */
  1203. /* handle.                                                                   */
  1204. /*                                                                           */
  1205. /* The second parameter is the dim level, for the DIM function. Valid Values */
  1206. /* range from 00(dimmest) to 15(brightest).                                  */
  1207. /*                                                                           */
  1208. /* The third parameter is the function code. This can be one of "ON", "OFF", */
  1209. /* or "DIM".                                                                 */
  1210. /*                                                                           */
  1211. /* The fourth parameter is a REXX string containing the new Housecode letter.*/
  1212. /* Valid housecodes are in the range "A" to "P".                             */
  1213. /*                                                                           */
  1214. /* Finally, the last parameter is the stem name of a REXX compound variable  */
  1215. /* that contains a list of the modules to command. The format of this        */
  1216. /* variable is demonstrated in the example below.                            */
  1217. /*****************************************************************************/
  1218. /* Returns:                                                                  */
  1219. /*                                                                           */
  1220. /* RxDirCmdMany returns the CP290 ack status after execution. This value will*/
  1221. /* be zero if no information has been downloaded to the CP290. It will be a  */
  1222. /* 1 after download of any command.  This can be used to determine if the    */
  1223. /* CP290 has been powered off. A return code of -1 indicates a communication */
  1224. /* error with the CP290.                                                     */
  1225. /*****************************************************************************/
  1226. /* Example:                                                                  */
  1227.  
  1228. dcom.0 = 5                             /* 5 modules to command               */
  1229. dcom.1 = 4                             /* 1st module - Module  4             */
  1230. dcom.2 = 5                             /* 2nd module - Module  5             */
  1231. dcom.3 = 16                            /* 3rd module - Module 16             */
  1232. dcom.4 = 10                            /* 4th module - Module 10             */
  1233. dcom.5 = 7                             /* 5th module - Module  7             */
  1234.  
  1235. rc = RxDirCmdManyCP290(CP290, 8, "OFF" ,"D", "dcom")  /* call the function   */
  1236. say 'RxDirCmdManyCP290: 'rc', CP290rc:   'CP290rc
  1237.  
  1238. do while rc < 5
  1239.    rc = RxCmdUploadCP290(CP290, 'result')
  1240. end
  1241.  
  1242. say 'Status        - Result.0:   'result.0
  1243. say 'Hcode         - Result.1:   'result.1
  1244. say 'Function      - Result.2:   'result.2
  1245. say '# of Modules  - Result.3.0: 'result.3.0
  1246. do i = 1 to result.3.0
  1247.    say 'Module 'i'      - Result.3.'i': 'result.3.i
  1248. end
  1249. say 'Base          - Result.4:   'result.4
  1250.  
  1251. /*****************************************************************************/
  1252. /*            RxDwnLdEvtCP290 - Download a Timer Event to the CP290          */
  1253. /*****************************************************************************/
  1254. /* Description:                                                              */
  1255. /*                                                                           */
  1256. /* RxDwnLdEvtCP290 downloads a Timer event to the CP290 for later execution. */
  1257. /*****************************************************************************/
  1258. /* Parameters:                                                               */
  1259. /*                                                                           */
  1260. /* This function takes three parameters.  The first parameter is the Comm    */
  1261. /* Port handle.                                                              */
  1262. /*                                                                           */
  1263. /* The second parameter is the event number.  Valid Values range from 0 to   */
  1264. /* 127.                                                                      */
  1265. /*                                                                           */
  1266. /* Finally, the last parameter is the stem name of a REXX compound variable  */
  1267. /* that contains the timer event information. The format of this variable is */
  1268. /* demonstrated in the example below. Note the similarity of this variable   */
  1269. /* format to the one used by RxGetEventsCP290.                               */
  1270. /*****************************************************************************/
  1271. /* Returns:                                                                  */
  1272. /*                                                                           */
  1273. /* RxDwnLdEvt returns the CP290 ack status after execution. This value will  */
  1274. /* be zero if no information has been downloaded to the CP290. It will be a  */
  1275. /* 1 after download of any command.  This can be used to determine if the    */
  1276. /* CP290 has been powered off. A return code of -1 indicates a communication */
  1277. /* error with the CP290.                                                     */
  1278. /*****************************************************************************/
  1279. /* Example:                                                                  */
  1280.  
  1281. event.0   = 0                /* Not used - here for compatibility with       */
  1282.                              /* RxGetEventsCP290 Compound Variable.          */
  1283.  
  1284. event.1   = "NORMAL"         /* Timer Mode - valid entries are "NORMAL",     */
  1285.                              /* "SECURITY","TODAY","TOMORROW", and "CLEAR"   */
  1286.  
  1287. event.2.0 = 4                /* Number of Days for Event: range 1-7          */
  1288.  
  1289. event.2.1 = "WED"            /* First Day - one of "MON","TUE","WED","THU",  */
  1290. event.2.2 = "THU"            /* "SAT", or "SUN".                             */
  1291. event.2.3 = "FRI"
  1292. event.2.4 = "MON"
  1293.  
  1294. event.3   = 15               /* Event Time - Hours:   Range  0-23            */
  1295.  
  1296. event.4   = 25               /* Event Time - Minutes: Range  0-59            */
  1297.  
  1298. event.5.0 = 4                /* Number of Modules for Event: Range 1-16      */
  1299. event.5.1 = 4                /* First Module: Range 1-16                     */
  1300. event.5.2 = 3                /* 2nd Module                                   */
  1301. event.5.3 = 16               /* 3rd Module                                   */
  1302. event.5.4 = 10               /* 4th Module                                   */
  1303.  
  1304. event.6   = "D"              /* Housecode: Range "A"-"P"                     */
  1305.  
  1306. event.7   = 7                /* Dim Level: Range 0(dimmest)-15(brightest)    */
  1307.  
  1308. event.8   = "DIM"            /* Function - One of "ON","OFF","DIM            */
  1309.  
  1310. rc = RxDwnldEvtCP290(CP290, 1,event)  /* call the function                   */
  1311. say 'RxDwnldEvtCP290:  'rc
  1312.  
  1313. /*****************************************************************************/
  1314. /*                RxGetEventsCP290 - Get CP290 Timer Events                  */
  1315. /*****************************************************************************/
  1316. /* Description:                                                              */
  1317. /*                                                                           */
  1318. /* This function gets all the Timer Event information from the CP290, and    */
  1319. /* makes it available to the calling REXX program in the form of a large     */
  1320. /* compound variable.                                                        */
  1321. /*****************************************************************************/
  1322. /* Parameters:                                                               */
  1323. /*                                                                           */
  1324. /* This function takes two parameters. The first parameter is the Comm Port  */
  1325. /* handle.                                                                   */
  1326. /*                                                                           */
  1327. /* The second parameter is the stem name of a REXX compound variable to      */
  1328. /* receive the results. The format of this compound variable is shown below, */
  1329. /* in the section that prints the results. This compound variable consists   */
  1330. /* of several structures in the same format as the compound variable used by */
  1331. /* RxDwnLdEvtCP290, for convenience.                                         */
  1332. /*****************************************************************************/
  1333. /* Returns:                                                                  */
  1334. /*                                                                           */
  1335. /* RxGetEventsCP290 returns the number of characters received.               */
  1336. /*****************************************************************************/
  1337. /* Example:                                                                  */
  1338.  
  1339. rc = RxGetEventsCP290(CP290, 'bigevt')    /* Call the function               */
  1340. say 'RxGetEventsCP290:  'rc
  1341.  
  1342. do i=0 to 127
  1343.  if BigEvt.i.0 = 1 then Do                /* If this value = 1, there is a   */
  1344.                                           /* corresponding event number.     */
  1345.                                           /* Otherwise, value is 0           */
  1346.   say 'BigEvt.'i'.0  :  'BigEvt.i.0       /* 1 = event, 0 = no event         */
  1347.   say 'BigEvt.'i'.1  :  'BigEvt.i.1       /* Timer Mode Sel - as RxDwnLdEvt  */
  1348.   say 'BigEvt.'i'.2.0:  'BigEvt.i.2.0     /* Number of Days - as RxDwnLdEvt  */
  1349.   Do j = 1 to BigEvt.i.2.0
  1350.    say 'BigEvt.'i'.2.'j':  'BigEvt.i.2.j  /* Day info - as RxDwnLdEvt        */
  1351.   end
  1352.   say 'BigEvt.'i'.3  :  'BigEvt.i.3       /* Hours:                          */
  1353.   say 'BigEvt.'i'.4  :  'BigEvt.i.4       /* Minutes:                        */
  1354.   say 'BigEvt.'i'.5.0:  'BigEvt.i.5.0     /* Number of Modules               */
  1355.   Do j = 1 to BigEvt.i.5.0
  1356.    say 'BigEvt.'i'.5.'j':  'BigEvt.i.5.j  /* Module number                   */
  1357.   end
  1358.   say 'BigEvt.'i'.6  :  'BigEvt.i.6       /* Housecode                       */
  1359.   say 'BigEvt.'i'.7  :  'BigEvt.i.7       /* Dim Level                       */
  1360.   say 'BigEvt.'i'.8  :  'Bigevt.i.8       /* Function                        */
  1361.   end
  1362. end
  1363.  
  1364. /*****************************************************************************/
  1365. /*                   RxCloseCP290 - Close CP290 Serial Port                  */
  1366. /*****************************************************************************/
  1367. /* Description:                                                              */
  1368. /*                                                                           */
  1369. /* RxCloseCP290 closes the serial port specified by the Com Port Handle,     */
  1370. /* freeing the port for use by other OS/2 applications.                      */
  1371. /*****************************************************************************/
  1372. /* Parameters:                                                               */
  1373. /*                                                                           */
  1374. /* This function takes one parameter, the Comm Port handle                   */
  1375. /*****************************************************************************/
  1376. /* Returns:                                                                  */
  1377. /*                                                                           */
  1378. /* Returns 0 if successful                                                   */
  1379. /*****************************************************************************/
  1380. /* Example:                                                                  */
  1381.  
  1382. rc = RxCloseCP290(CP290)
  1383. say 'RxCloseCP290:  'rc', CP290rc:   'CP290rc
  1384.  
  1385. /*****************************************************************************/
  1386. /*          RxDropFuncsCP290 - Drop the RxCP290 Functions from REXX          */
  1387. /*****************************************************************************/
  1388. /* Description:                                                              */
  1389. /*                                                                           */
  1390. /* This function drops the RxCP290 X-10 communications functions, so that    */
  1391. /* they are no longer available to REXX programs.  Execution of this command */
  1392. /* makes these functions unavailable to all REXX programs in all sessions    */
  1393. /* in OS/2.  These functions will remain unavailable until explicitly loaded */
  1394. /* by the RxLoadFuncsCP290 function.                                         */
  1395. /*****************************************************************************/
  1396. /* Parameters:                                                               */
  1397. /*                                                                           */
  1398. /* None                                                                      */
  1399. /*****************************************************************************/
  1400. /* Returns:                                                                  */
  1401. /*                                                                           */
  1402. /* 0 if successful                                                           */
  1403. /*****************************************************************************/
  1404. /* Example:                                                                  */
  1405.  
  1406. call RxDropFuncsCP290
  1407. say 'RxDropFuncsCP290, CP290rc:  'CP290rc
  1408.  
  1409.  
  1410. ΓòÉΓòÉΓòÉ 5.3. SaveRest.CMD - Example REXX Procedures for saving and Restoring Events Information from Files ΓòÉΓòÉΓòÉ
  1411.  
  1412. This example program shows how the Timer Event information returned by 
  1413. RxGetEventsCP290() can be saved to a disk file and then restored. It retrieves 
  1414. all of the Timer Events from the CP290 via the RXGetEventsCP290() call, and 
  1415. then saves them via an example REXX Procedure named SaveEvents. The events 
  1416. variable is then erased, and reloaded from the disk file by an example REXX 
  1417. Procedure named RetrvEvents. The CP290 then has it's Timer Event information 
  1418. erased as a side effect of the RxSetHCodeCP290() function, and restored by 
  1419. calling RxDwnLdEvtCP290() for each existing event. 
  1420.  
  1421. /* Rexx Program to Test RXCP290 Routines */
  1422.  
  1423. /* Load RxCP290 Routines                 */
  1424.  
  1425. call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
  1426. call RxLoadFuncsCP290
  1427. say 'RxLoadFuncsCP290, CP290rc:   'CP290rc
  1428.  
  1429. /* Initialize Com Port Handle Variable  */
  1430. CP290 = ''
  1431.  
  1432. /* Initialize Com Port                  */
  1433.  
  1434. rc = RxInitCP290('COM2', 'CP290')
  1435. say 'RxInitCP290:   'rc', CP290rc:   'CP290rc
  1436.  
  1437.  
  1438. /* Get All Events from CP290 */
  1439.  
  1440. rc = RxGetEventsCP290(CP290, 'events')
  1441. say 'RxGetEventsCP290:  'rc
  1442.  
  1443. /* Print Out events information */
  1444.  
  1445. say
  1446.  
  1447. do i=0 to 127
  1448.   if events.i.0 = 1 then
  1449.      Do
  1450.        say 'events.'i'.0  :  'events.i.0
  1451.        say 'events.'i'.1  :  'events.i.1
  1452.        say 'events.'i'.2.0:  'events.i.2.0
  1453.        Do j = 1 to events.i.2.0
  1454.       say 'events.'i'.2.'j':  'events.i.2.j
  1455.        end
  1456.        say 'events.'i'.3  :  'events.i.3
  1457.        say 'events.'i'.4  :  'events.i.4
  1458.        say 'events.'i'.5.0:  'events.i.5.0
  1459.        Do j = 1 to events.i.5.0
  1460.       say 'events.'i'.5.'j':  'events.i.5.j
  1461.        end
  1462.        say 'events.'i'.6  :  'events.i.6
  1463.        say 'events.'i'.7  :  'events.i.7
  1464.        say 'events.'i'.8  :  'events.i.8
  1465.      end
  1466. end
  1467.  
  1468. /* Save the events information        */
  1469.  
  1470. file = "testfile.sav"
  1471. call SaveEvents file
  1472.  
  1473.  
  1474. /* Erase the internal events structure */
  1475. events. = 0
  1476.  
  1477. /* Retrieve the Events from a file     */
  1478.  
  1479. call RtrvEvents file
  1480.  
  1481. /* Print out Events retrieved   */
  1482.  
  1483. say
  1484. do i=0 to 127
  1485.   if events.i.0 = 1 then
  1486.      Do
  1487.        say 'events.'i'.0  :  'events.i.0
  1488.        say 'events.'i'.1  :  'events.i.1
  1489.        say 'events.'i'.2.0:  'events.i.2.0
  1490.        Do j = 1 to events.i.2.0
  1491.       say 'events.'i'.2.'j':  'events.i.2.j
  1492.        end
  1493.        say 'events.'i'.3  :  'events.i.3
  1494.        say 'events.'i'.4  :  'events.i.4
  1495.        say 'events.'i'.5.0:  'events.i.5.0
  1496.        Do j = 1 to events.i.5.0
  1497.       say 'events.'i'.5.'j':  'events.i.5.j
  1498.        end
  1499.        say 'events.'i'.6  :  'events.i.6
  1500.        say 'events.'i'.7  :  'events.i.7
  1501.        say 'events.'i'.8  :  'events.i.8
  1502.      end
  1503. end
  1504.  
  1505. /* Erase CP290 Timer Events              */
  1506.  
  1507. rc = RxSetHCodeCP290(CP290, "D")
  1508.  
  1509. /* Reload CP290 Events from events.      */
  1510.  
  1511. do i = 0 to 127
  1512.    if events.i.0 = 1 then
  1513.     do
  1514.       /* Create name of events entry - events.1, events.2, etc. */
  1515.       evt = 'events.'||i
  1516.       rc = RxDwnLdEvtCP290(CP290, i, evt)
  1517.       say 'RxDwnLdEvtCP290: rc = 'rc ' Event number: 'i
  1518.     end
  1519. end
  1520.  
  1521. /* Close Communications                  */
  1522.  
  1523. rc = RxCloseCP290(CP290)
  1524. say 'RxCloseCP290:  'rc', CP290rc:   'CP290rc
  1525.  
  1526. /* Drop RXCP290 Functions */
  1527.  
  1528. call RxDropFuncsCP290
  1529. say 'RxDropFuncsCP290, CP290rc:  'CP290rc
  1530.  
  1531. exit
  1532.  
  1533. SaveEvents: Procedure Expose events.
  1534.    arg filenm
  1535.  
  1536. call lineout filenm, ,1
  1537. do i=0 to 127
  1538.    call lineout filenm,  events.i.0
  1539.    if events.i.0 = 1 then
  1540.       Do
  1541.        call lineout filenm,  events.i.1
  1542.        call lineout filenm,  events.i.2.0
  1543.        Do j = 1 to events.i.2.0
  1544.       call lineout filenm,  events.i.2.j
  1545.        end
  1546.        call lineout filenm,  events.i.3
  1547.        call lineout filenm,  events.i.4
  1548.        call lineout filenm,  events.i.5.0
  1549.        Do j = 1 to events.i.5.0
  1550.       call lineout filenm,  events.i.5.j
  1551.        end
  1552.        call lineout filenm,  events.i.6
  1553.        call lineout filenm,  events.i.7
  1554.        call lineout filenm,  events.i.8
  1555.      end
  1556. end
  1557. call lineout(filenm)
  1558. return
  1559.  
  1560. RtrvEvents: Procedure Expose events.
  1561.    arg filenm
  1562.  
  1563. call linein filenm, ,0
  1564. do i=0 to 127
  1565.    events.i.0 = linein(filenm)
  1566.    if events.i.0 = 1 then
  1567.       Do
  1568.        events.i.1 = linein(filenm)
  1569.        events.i.2.0 = linein(filenm)
  1570.        Do j = 1 to events.i.2.0
  1571.           events.i.2.j = linein(filenm)
  1572.        end
  1573.        events.i.3 = linein(filenm)
  1574.        events.i.4 = linein(filenm)
  1575.        events.i.5.0 = linein(filenm)
  1576.        Do j = 1 to events.i.5.0
  1577.           events.i.5.j = linein(filenm)
  1578.        end
  1579.        events.i.6 = linein(filenm)
  1580.        events.i.7 = linein(filenm)
  1581.        events.i.8 = linein(filenm)
  1582.      end
  1583. end
  1584. return
  1585.  
  1586.  
  1587. ΓòÉΓòÉΓòÉ 5.4. CP290Web.Cmd - A REXX CGI Program for Access to X-10 Commands from the World Wide Web ΓòÉΓòÉΓòÉ
  1588.  
  1589. Also provided as an example program is CP290web.cmd, and the companion 
  1590. CP290.html. CP290.html provides a simple World Wide Web page consisting of a 
  1591. form that allows the selection of Housecode, Module, Function, and dim level, 
  1592. and then issues a direct command to the CP290 via the CP290web.cmd program, 
  1593. called via the WWW server's CGI Interface. These have been tested with GoServe, 
  1594. an excellent Web Server available as IBM Employee Written Software, using the 
  1595. GoHTTP CGI/IMAP enhancements. 
  1596.  
  1597.  
  1598. ΓòÉΓòÉΓòÉ 5.5. CP290.EXE - An OS/2 Program for basic CP290 X-10 Control written with RxCP290 ΓòÉΓòÉΓòÉ
  1599.  
  1600. Finally, a larger example program has been created using DrDialog, an IBM EWS 
  1601. tool that allows the creation of WorkPlace Shell programs in REXX. The REXX 
  1602. Source for this is included in the distribution of RxCP290, but as it is quite 
  1603. specific to the DrDialog tool, may be of limited utility. The usage of 
  1604. CP290.EXE is described in the next section. 
  1605.  
  1606.  
  1607. ΓòÉΓòÉΓòÉ 6. Using CP290.EXE ΓòÉΓòÉΓòÉ
  1608.  
  1609. The RxCP290 package comes with an application written with DrREXX, an IBM EWS 
  1610. program, that allows basic control of all of the CP290 X10 controller functions 
  1611. from a PM program. This program is shipped with the executable, CP290.EXE, the 
  1612. RES file produced by DrREXX, CP290.RES, and a source listing, CP290.RXX. 
  1613. CP290.RES would be useful for those users wishing to extend the functionality 
  1614. of this package. 
  1615.  
  1616.  
  1617. ΓòÉΓòÉΓòÉ 6.1. Starting the Program ΓòÉΓòÉΓòÉ
  1618.  
  1619. Start this program like any other OS/2 program, from the command line or by 
  1620. double-clicking on the program object. 
  1621.  
  1622.  
  1623. ΓòÉΓòÉΓòÉ 6.2. The Init Page - Initializing the program and CP290 Interface ΓòÉΓòÉΓòÉ
  1624.  
  1625. When first started, the Init page of the Notebook will be on top. It looks like 
  1626. this: 
  1627.  
  1628. The following tasks may be accomplished from this screen: 
  1629.  
  1630. Setting the Communications Port 
  1631.  
  1632. The serial port used by this program may be set on this screen. When the Set 
  1633. ComPort button is pressed, the program saves the comport specified in OS2.INI, 
  1634. so this only needs to be done once. 
  1635.  
  1636. Setting the serial port to the port the CP290 is actually connected to should 
  1637. be done first, as all the other commands require communications with the CP290 
  1638. unit. 
  1639.  
  1640. Setting the Base Housecode 
  1641.  
  1642. The Base Housecode of the CP290 may be set by entering the desired Housecode 
  1643. and pressing the Set HouseCode button. 
  1644.  
  1645. Note: The CP290 must be connected to the serial port specified on this page for 
  1646. this function to work correctly. 
  1647.  
  1648. Setting the CP290 Clock 
  1649.  
  1650. Pressing the Set Time button sets the CP290's internal clock to the time and 
  1651. day of week on the PC. 
  1652.  
  1653.  
  1654. ΓòÉΓòÉΓòÉ 6.3. The Direct Command Page - Sending Direct X-10 Commands ΓòÉΓòÉΓòÉ
  1655.  
  1656. The Direct Command Notebook page looks like this: 
  1657.  
  1658. This page allows direct control of a single X-10 module. Pressing the Execute 
  1659. button sends the command. 
  1660.  
  1661.  
  1662. ΓòÉΓòÉΓòÉ 6.4. The File Menu - Saving and Restoring CP290 Timer Events ΓòÉΓòÉΓòÉ
  1663.  
  1664. The File menu allows the user to save and restore files of CP290 Timer Events. 
  1665. Up to 127 events may be stored in a single file. 
  1666.  
  1667. The files used by CP290.EXE are in ASCII format, and are similar to the files 
  1668. produced by the SaveRest.CMD example program. 
  1669.  
  1670.  
  1671. ΓòÉΓòÉΓòÉ 6.4.1. Creating a New Event Table ΓòÉΓòÉΓòÉ
  1672.  
  1673. Selecting the New entry under the File Menu clears out all events stored in the 
  1674. Notebook. A single page for Event 0 is left, for the user to start filling out 
  1675. new events from. 
  1676.  
  1677.  
  1678. ΓòÉΓòÉΓòÉ 6.4.2. Retrieving Events from Disk ΓòÉΓòÉΓòÉ
  1679.  
  1680. Selecting the Open entry under the File Menu opens a standard OS/2 File Dialog. 
  1681. This allows the user to retrieve previously saved files of events. 
  1682.  
  1683.  
  1684. ΓòÉΓòÉΓòÉ 6.4.3. Saving Events to Disk ΓòÉΓòÉΓòÉ
  1685.  
  1686. Both the Save and Save As entries under the File Menu open a standard OS/2 File 
  1687. dialog, allowing the user to save the current events in the notebook. 
  1688.  
  1689.  
  1690. ΓòÉΓòÉΓòÉ 6.4.4. Exiting the Program ΓòÉΓòÉΓòÉ
  1691.  
  1692. Finally, as is considered normal in OS/2 programs, selecting the Quit option 
  1693. will exit the program. The program may also be exited by double-clicking on the 
  1694. upper left corner of the window. 
  1695.  
  1696.  
  1697. ΓòÉΓòÉΓòÉ 6.5. The Events Menu - Managing CP290 Timer Events and Event Pages ΓòÉΓòÉΓòÉ
  1698.  
  1699. The remaining pages of the Notebook are Event Pages, one for each Timer Event 
  1700. to be sent to the CP290. The Event Pages look like this: 
  1701.  
  1702. Events may be added, deleted, sent to the CP290, or retrieved from the CP290 
  1703. unit by the Event Menu entries. Each new event adds a new Event page to the 
  1704. NoteBook. 
  1705.  
  1706. Creating a New Event 
  1707.  
  1708. Selecting New Event under the Event Menu creates a new event page. The number 
  1709. of the new event page will be the lowest event number not currently used, so if 
  1710. there are gaps in the numbering of events, these gaps will be filled. 
  1711.  
  1712. Deleting an Event 
  1713.  
  1714. Selecting Del Event under the Event Menu deletes the event page currently 
  1715. displayed on the top of the Notebook. 
  1716.  
  1717. Note: In addition to deleting the event information, this function deletes the 
  1718. currently displayed page. Selecting Del Event when the Init or Direct Command 
  1719. page is displayed will result in these pages being deleted from the Notebook 
  1720. for the remainder of the session. Restarting the CP290.EXE program will restore 
  1721. the missing pages. 
  1722.  
  1723. Getting Events from the CP290 
  1724.  
  1725. Selecting GetEvents from the Events Menu will retrieve all events from the 
  1726. CP290 unit. All events shown in the notebook prior to this will be lost, 
  1727. replaced by the CP290 events. 
  1728.  
  1729. Storing Events to the CP290 
  1730.  
  1731. Pressing StoreEvents under the Events menu stores the events shown in the 
  1732. NoteBook to the CP290 unit. The CP290 immediately begins executing the new set 
  1733. of Timer Events. 
  1734.  
  1735.  
  1736. ΓòÉΓòÉΓòÉ 7. Additional Information ΓòÉΓòÉΓòÉ
  1737.  
  1738. Additional information 
  1739.  
  1740.  
  1741. ΓòÉΓòÉΓòÉ 7.1. Trademarks ΓòÉΓòÉΓòÉ
  1742.  
  1743. X-10 and CP290 Home Control Interface are registered trade marks of X-10 (USA) 
  1744. Inc. 
  1745.  
  1746.  
  1747. ΓòÉΓòÉΓòÉ 7.2. Disclaimer ΓòÉΓòÉΓòÉ
  1748.  
  1749. THERE IS NO WARRANTY FOR THIS PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE 
  1750. LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING DECKER AUTOMATION PROVIDES THE 
  1751. PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 
  1752. INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
  1753. FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 
  1754. PERFORMANCE OF THE PROGRAM LIES WITH THE USER. IN NO EVENT UNLESS REQUIRED BY 
  1755. APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER 
  1756. PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE 
  1757. LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 
  1758. CONSEQUENTIAL DAMANGES ARISING OUT OF THE USE OF INABILITY TO USE THE PROGRAM 
  1759. (INCLUDING BUT NOT LIMITED TO THE LOSS OF DATA OR DATA BEING RENDERED INACURATE 
  1760. OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO 
  1761. OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 
  1762. ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 
  1763.  
  1764.  
  1765. ΓòÉΓòÉΓòÉ 7.3. About X-10 ΓòÉΓòÉΓòÉ
  1766.  
  1767. The X-10 Home Control System is a popular system for automating the control of 
  1768. lights and appliances in the home. X-10 modules and controllers are sold by a 
  1769. number of companies, under a num,ber of labels. For more information, you may 
  1770. wish to contact X-10, at the following: 
  1771.  
  1772. X-10 (USA) Inc.
  1773. 185A LeGrande Ave
  1774. Northvale, NJ 07647
  1775. (201) 784-9700
  1776.  
  1777. X-10 Home Controls Inc
  1778. 1200 Aerowood Drive, Unit 20
  1779. Mississauga, Ontario L4W 2S7
  1780. (416) 624-4446
  1781.  
  1782.  
  1783. ΓòÉΓòÉΓòÉ 7.4. About Decker Automation ΓòÉΓòÉΓòÉ
  1784.  
  1785. Decker Automation is a Factory Floor Automation Software and Networking 
  1786. consulting firm. We have extensive experience with all aspects of the software 
  1787. side of factory-floor automation, from programming simple PLCs through 
  1788. designing complete automation network architectures. Our experience also 
  1789. includes the design of PLCs and PLC-like languages and systems, design and 
  1790. implementation of several different Fieldbuses, and communications device 
  1791. driver creation for various operating systems including DOS, Windows, OS/2, and 
  1792. VMS. Our experience with the WorldFIP fieldbus is particularly extensive. 
  1793.  
  1794. In addition, Decker Automation has contributed several programs to the OS/2 
  1795. community. These include the other World Wide Web Browser for OS/2, 
  1796. <B>Lynx/2</B>, and an Internet retrieval tool, <B>GetURL</B>. We are also 
  1797. working on expanding our REXX-based Home Automation line of products - look for 
  1798. support for a PC to IR Remote control interface, and the new X-10 CM10A Home 
  1799. Controller in the near future! 
  1800.  
  1801. Decker Automation may be contacted at: 
  1802.  
  1803.         Decker Automation
  1804.         833 Penny Lane
  1805.         Lexington, KY 40509
  1806.  
  1807.         Tel/Fax:  606/263-8560
  1808.         Email:    djd@cris.com
  1809.         WWW Page: http://www.cris.com/~djd
  1810.