home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 18 REXX
/
18-REXX.zip
/
rxcp290.zip
/
cp290.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1996-05-06
|
86KB
|
1,810 lines
ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
The X-10 company has for years provided a cost-effective and popular means for
control of the lights and appliances in the home, by means of the X-10 Home
Control System. X-10's CP290 Home Control Interface provides the hardware
required to control the X-10 modules from your computer's serial port. Now you
can combine the capabilities of the X-10 system with the Power and Flexibility
of OS/2, and OS/2's REXX language, with RxCP290 - the REXX Interface to X-10
Home Control.
RxCP290 is an extension of OS/2's built-in REXX language that provides
functions for communicating to the CP290 Home Control Interface for X-10. This
allows you to control X-10 modules and functions in your home or office from
OS/2 REXX Programs.
The RxCP290 package consists of the following:
The RxCP290 REXX Functions, in the form of a Dynamic Link Library (DLL).
This documentation, in both online and printed formats.
REXX Example programs, including:
- SmallTest.CMD - a minimal program that demonstrates the simple
turning on of a X-10 Module.
- TestCP.CMD - A REXX program with examples and explanation of proper
usage of all of the RxCP290 Functions.
- SaveRest.CMD - a REXX program with procedures for saving and
restoring CP290 Timer events to and from disk files.
- CP29Web.CMD - An example REXX CGI program that works in conjunction
with CP290.html to allow control of any X-10 module from an
OS/2-Hosted World Wide Web site.
- CP290.RXX - the REXX source to the CP290.EXE X-10 control program
included in the package. This program was written with the DrDialog
Application Enabler package.
The CP290.EXE program, a WorkPlace Shell program based on OS/2's Notebook
control, with support for all of the basic functions of the CP290 Home
Control Interface. This was written in REXX with the DrDialog package.
An installation program, written in REXX, for installing the RxCP290
package
ΓòÉΓòÉΓòÉ 2. Installation ΓòÉΓòÉΓòÉ
Installation consists of two phases - software installation, and hardware
installation. These are described below.
ΓòÉΓòÉΓòÉ 2.1. Installing the software ΓòÉΓòÉΓòÉ
The RXCP290 software may be installed automatically via INSTALL.CMD, or
manually. These methods are described below.
ΓòÉΓòÉΓòÉ 2.1.1. Automatic Installation ΓòÉΓòÉΓòÉ
Automatic installation may be accomplished by using the Install.cmd REXX
program included with the distribution. This installation program will copy the
RxCP290 DLL to \OS2\APPS\DLL on your boot drive, and will create a
\RxCP290 directory on your boot drive for the rest of the package.
Should you not wish the rest of the package be installed to this directory, you
may specify a directory to install the RxCP290 Utilities, Example Programs, and
Documentation to on the command line. For example, to install these in a
directory named F:\X10Stuff, you would start install.cmd like this:
A:\>install F:\X10Stuff
Once started, the Install.cmd program will display the From and To directory
information for the installation, and will prompt for a Y/N response. Pressing
'y' or 'Y' will continue the installation, anything else will abort.
The RxCP290 utilities are ready to run immediately upon completion of the
installation process.
ΓòÉΓòÉΓòÉ 2.1.2. Manual Installation ΓòÉΓòÉΓòÉ
If you do not desire to have the RxCP290 DLL in your \OS2\APPS\DLL directory,
you may simply copy the dll file to the directory of your choice. If this
directory is not included in the LIBPATH as specified in your CONFIG.SYS file,
then only REXX programs started in this directory will be able to find and use
the RxCP290 functions in this DLL file.
The remaining RxCP290 Documentation, Example Program, and Utility files may be
installed anywhere the user desires.
ΓòÉΓòÉΓòÉ 2.2. Connecting the CP290 Interface ΓòÉΓòÉΓòÉ
The CP290 interface should be connected to the PC's serial port in accordance
with instructions furnished by X-10 with the CP290 unit.
ΓòÉΓòÉΓòÉ 3. Some Notes On REXX ΓòÉΓòÉΓòÉ
This document is not intended as a REXX tutorial or language reference. If you
are learning the REXX language, the following texts are highly recommended:
The REXX Language - M. F. Cowlishaw
ISBN 0-13-780735-X Prentice-Hall, 1985
ISBN 0-13-780651-5 (Second edition), 1990
ΓòÉΓòÉΓòÉ 3.1. REXX Extensions ΓòÉΓòÉΓòÉ
RxCP290 is a set of REXX External Functions, packaged as a DLL. Some notes on
this follow, adapted from the IBM REXX User's Guide:
In addition to the REXX built-in functions, you can use functions external to
REXX in your REXX programs. An external function may be simply another REXX
program, or it may be a function written in a compiled language. Before you can
use a function in a compiled language, you must tell REXX where the function is
located with the RxFuncAdd function.
For example, the IBM Extended Services/2 product provides a REXX function for
the Emulator High Level Language Application Programming Interface (EHLLAPI).
The EHLLAPI function is in an OS/2 dynamic link library module named
SAAHLAPI.DLL. The function routine within SAAHLAPI.DLL is HllApiSrv. To use the
EHLLAPI function, you must first tell REXX where the function is found:
call RxFuncAdd 'hllapi', 'saahlapi', 'hllapisrv'
You can now use the function HLLAPI in your REXX programs:
rc = hllapi("Set_session_parms","CONPHYS")
rc = hllapi("Connect",session)
if (rc <> 0) then return rc
rc = hllapi("Start_keystroke_intercept",session,"L")
You only need to register HLLAPI with RxFuncAdd one time. Once registered, a
function is available from anywhere on your OS/2 system.
ΓòÉΓòÉΓòÉ 3.2. Compound Symbols and Variables in REXX ΓòÉΓòÉΓòÉ
RxCP290 makes extensive use of a feature of the REXX Language known as Compound
Symbols. Here is a small example/discussion of the topic, adapted from the IBM
REXX User's Guide.
There is a special class of symbols, called compound symbols, in which
variables and constants are combined to create groups of variables for easy
processing. A variable containing a period is treated as a compound symbol.
Some examples of compound symbols are:
fred.3
row.column
array.I.J.
gift.day
You can use compound symbols to create a collection of variables that can be
processed by their derived names. An example of a collection is:
gift.1 = 'A partridge in a pear tree'
gift.2 = 'Two turtle doves'
gift.3 = 'Three French hens'
gift.4 = 'Four calling birds', etc, etc
If you know what day it is, you know what gift will be given. Assign a variable
called DAY a value of 3.
day = 3
Then the instruction 'say gift.day', as in the program shown below, displays
'Three French hens' on the screen. When the REXX program is run, and the
expression 'gift.day' is evaluated, the following occurs:
1. REXX recognizes the symbol gift.day as compound because it contains a
period.
2. REXX checks if the characters following the period form the name of a
variable. In this example, it is the variable name day.
3. The value of day is substituted for its name, producing a derived name of
gift.3.
4. The value of the variable gift.3 is the literal string 'Three French
hens'.
If day had never been given a value, its value would have been its own name;
day and the derived name of the compound symbol gift.day would have been
GIFT.DAY.
The following whimsical program illustrates simple use of Compound Symbols:
/* What my true love sent ... */
/* First, assign the gifts to the days */
gift.1 = 'A partridge in a pear tree'
gift.2 = 'Two turtle doves'
gift.3 = 'Three French hens'
gift.4 = 'Four calling birds'
gift.5 = 'Five golden rings'
gift.6 = 'Six geese a-laying'
gift.7 = 'Seven swans a-swimming'
gift.8 = 'Eight maids a-milking'
gift.9 = 'Nine ladies dancing'
gift.10 = 'Ten lords a-leaping'
gift.11 = 'Eleven pipers piping'
gift.12 = 'Twelve drummers drumming'
/* list all gifts from the 12th day to */
/* the 1st day */
do day=12 to 1
say gift.day
end
/* now display the gift for a chosen day */
say "Type a number from 1 to 12."
pull day
/* check for proper input */
if \ datatype(day,n) then /* if the entry is not a number */
exit /* then exit the program */
if day < 1 | day > 12 then /* same if it is out of range */
exit
say gift.day
Some terminology in regard to Compound Symbols in REXX:
The stem of a compound symbol is the portion up to and including the first
period. That is, it is a valid variable name that ends with a period.
The stem is followed by a tail, comprised of one or more valid symbols
(constants or variables) separated by periods. You can refer to all the
variables in an array by using the stem of the array. For example:
player. = 0
say player.1 player.2 player.golf /* displays '0 0 0' */
It is often convenient to set all variables in an array to 0 in this way.
ΓòÉΓòÉΓòÉ 4. The RxCP290 Functions ΓòÉΓòÉΓòÉ
The RxCP290 REXX External Functions are explained here
ΓòÉΓòÉΓòÉ 4.1. RxLoadFuncsCP290 - Load the RxCP290 Functions into REXX ΓòÉΓòÉΓòÉ
Description:
This function loads the RxCP290 X-10 communications functions, so that they are
available to REXX programs. Execution of this command makes these functions
available to all REXX programs in all sessions under
OS/2. These functions will remain available until explicitly dropped by the
RxDropFuncsCP290 function.
Parameters:
None
Returns:
0 if successful. Non-zero returns indicate that none of the RxCP290 functions
have been loaded.
Example:
/* Load RxLoadFuncsCP290 */
call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
call RxLoadFuncsCP290 /* Call the RxCP290 function */
ΓòÉΓòÉΓòÉ 4.2. RxDropFuncsCP290 - Drop the RxCP290 Functions from REXX ΓòÉΓòÉΓòÉ
Description:
This function drops the RxCP290 X-10 communications functions, so that they are
no longer available to REXX programs. Execution of this command makes these
functions unavailable to all REXX programs in all sessions in OS/2. These
functions will remain unavailable until explicitly loaded by the
RxLoadFuncsCP290 function.
Parameters:
None.
Returns:
0 if successful.
Example:
call RxDropFuncsCP290
say 'RxDropFuncsCP290, CP290rc: 'CP290rc
ΓòÉΓòÉΓòÉ 4.3. RxInitCP290 - Initialize the Serial Port for the CP290 interface ΓòÉΓòÉΓòÉ
Description:
RxInitCP290 initializes the serial port for communications with the CP290. It
initializes a Com Port Handle, which is used by all of the RxCP290 functions to
determine which serial port to communicate with. This Comm Handle variable
should be initialized in the REXX environment before using this function.
Parameters:
This function takes two parameters. The first parameter is a string with the
name of the serial port the CP290 is connected to. For this example, the CP290
is connected to COM2, so the parameter is 'COM2'. Note that this parameter must
be in all caps.
The second parameter is the name of a REXX variable to store the Com Port
Handle in. This variable should have been initialized prior to calling
function.
Returns:
This function returns 0 when successful. Non-zero results indicate the port was
not opened.
Example:
CP290 = '' /* Init Com Port Handle var */
rc = RxInitCP290('COM2', 'CP290') /* Call the function */
ΓòÉΓòÉΓòÉ 4.4. RxCloseCP290 - Close the Serial Port for the CP290 Interface ΓòÉΓòÉΓòÉ
Description:
RxCloseCP290 closes the serial port specified by the Com Port Handle, freeing
the port for use by other OS/2 applications.
Parameters:
This function takes one parameter, the Comm Port handle to close.
Returns:
Returns 0 if successful.
Example:
rc = RxCloseCP290(CP290)
ΓòÉΓòÉΓòÉ 4.5. RxDiagCP290 - Run CP290 self-diagnostics ΓòÉΓòÉΓòÉ
Description
This function commands the CP290 to perform it's internal diagnostic routines.
Execution of these routines will take about 10 seconds. All information in the
CP290 will be erased as a result of the execution of this function.
Parameters
This function takes a single parameter, the Com Port Handle produced by the
RxInitCP290 function.
Returns
This function returns zero if successful. A return code of 1 indicates a CP290
diagnostics failure not related to the serial communications. A return code of
less than zero indicates a communications failure, which may or may not be due
to CP290 failure.
Example
rc = RxDiagCP290(CP290) /* Call Function */
ΓòÉΓòÉΓòÉ 4.6. RxSetHCodeCP290 - Set CP290 House Code ΓòÉΓòÉΓòÉ
Description
RxSetHcodeCP290 sets the CP290's Base Housecode. All information in the CP290
will be erased as a result of this function's execution.
Parameters
This function takes two parameters. The first parameter is the Comm Port
handle.
The second parameter is a REXX string containing the new Housecode letter.
Valid housecodes are in the range "A" to "P".
Returns
RxSetHcode returns the CP290 ack status after execution. This value will be
zero if no information has been downloaded to the CP290. It will be a 1 after
download of any command. This can be used to determine if the CP290 has been
powered off. A return code of -1 indicates a communication error with the
CP290.
Example
rc = RxSetHCodeCP290(CP290, "D") /* Set Housecode "D" */
ΓòÉΓòÉΓòÉ 4.7. RxSetTimeCP290 - Set CP290 Clock from Computer Clock ΓòÉΓòÉΓòÉ
Description
RxSetTimeCP290 sets the CP290's internal clock from the host computer's
internal clock.
Parameters
This function takes one parameter, the Comm Port handle.
Returns
RxSetTime returns the CP290 ack status after execution. This value will be zero
if no information has been downloaded to the CP290. It will be a 1 after
download of any command. This can be used to determine if the CP290 has been
powered off. A return code of -1 indicates a communication error with the
CP290.
Example
rc = RxSetTimeCP290(CP290) /* Set current Computer Time */
ΓòÉΓòÉΓòÉ 4.8. RxGetTimeCP290 - Get current value of CP290 Clock and Housecode ΓòÉΓòÉΓòÉ
Description
RxGetTimeCP290 returns the CP290's internal clock time and House Code.
Parameters
This function takes two parameters. The first parameter is the Comm Port
handle.
The second parameter is the stem name of a REXX compound variable to receive
the results. The format of this stem variable is as follows:
<StemName>.0 = CP290 Acknowledge status
<StemName>.1 = Current Minutes Value from CP290. Will range from 0 to 59.
<StemName>.2 = Current Hours value from CP290. Will range from 0 to 23.
<StemName>.3 = Day of Week. One of the following: "MON", "TUE", "WED",
"THU", "FRI", "SAT", or "SUN".
<StemName>.4 = Base Housecode, in range "A" to "P".
Returns
RxGetTimeCP290 returns the number of characters received. This should be equal
to 12 for a normal call.
Example
rc = RxGetTimeCP290(CP290, 'result') /* Get CP290 time */
say 'RxGetTimeCP290: ' rc /* Print return code */
say 'Status - Result.0: 'result.0 /* CP290 Ack Status */
say 'Minutes - Result.1: 'result.1 /* Minutes: valid 00 - 59 */
say 'Hours - Result.2: 'result.2 /* Hours: valid 00 - 23 */
say 'Day Week - Result.3: 'result.3 /* Day of Week: in "MON","TUE","WED" */
/* "THU","FRI","SAT","SUN" */
say 'Base - Result.4: 'result.4 /* Base Housecode: valid "A" - "P" */
ΓòÉΓòÉΓòÉ 4.9. RxDirCmdCP290 - Send a Direct Command to a Single X-10 Module ΓòÉΓòÉΓòÉ
Description
RxDirCmdCP290 sends a direct command to a single X-10 module.
Parameters
This function takes five parameters. The first parameter is the Comm Port
handle.
The second parameter is the dim level, for the DIM function. Valid Values range
from 00(dimmest) to 15(brightest).
The third parameter is the function code. This can be one of "ON", "OFF", or
"DIM".
The fourth parameter is a REXX string containing the new Housecode letter.
Valid housecodes are in the range "A" to "P".
Finally, the last parameter is the module number to affect. Valid values are in
the range 1 through 16.
Returns
RxDirCmd returns the CP290 ack status after execution. This value will be zero
if no information has been downloaded to the CP290. It will be a 1 after
download of any command. This can be used to determine if the CP290 has been
powered off. A return code of -1 indicates a communication error with the
CP290.
Example
rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4) /* Turn on Module D4 */
ΓòÉΓòÉΓòÉ 4.10. RxDirCmdManyCP290 - Send a Direct command to several X-10 Modules ΓòÉΓòÉΓòÉ
Description
RxDirCmdManyCP290 sends a direct command to a series of X-10 modules.
Parameters
This function takes five parameters. The first parameter is the Comm Port
handle.
The second parameter is the dim level, for the DIM function. Valid Values range
from 00(dimmest) to 15(brightest).
The third parameter is the function code. This can be one of "ON", "OFF", or
"DIM".
The fourth parameter is a REXX string containing the new Housecode letter.
Valid housecodes are in the range "A" to "P".
Finally, the last parameter is the stem name of a REXX compound variable that
contains a list of the modules to command. The format of this variable is as
follows:
<StemName>.0 = Number of Modules to send command to. Valid values are 1
to 16.
<StemName>.1 = First Module Number for command. Valid Values are 1 to 16.
Modules need not be listed in any order.
<StemName>.2 = Second Module Number for command. Valid Values are 1 to
16. Modules need not be listed in any order.
<StemName>.n = First Module Number for command. Valid Values are 1 to 16.
Modules need not be listed in any order. n here stands for the value in
<StemName>.0.
Returns
RxDirCmdMany returns the CP290 ack status after execution. This value will be
zero if no information has been downloaded to the CP290. It will be a 1 after
download of any command. This can be used to determine if the CP290 has been
powered off. A return code of -1 indicates a communication error with the
CP290.
Example
dcom.0 = 5 /* 5 modules to command */
dcom.1 = 4 /* 1st module - Module 4 */
dcom.2 = 5 /* 2nd module - Module 5 */
dcom.3 = 16 /* 3rd module - Module 16 */
dcom.4 = 10 /* 4th module - Module 10 */
dcom.5 = 7 /* 5th module - Module 7 */
rc = RxDirCmdManyCP290(CP290, 8, "OFF" ,"D", "dcom") /* call the function */
ΓòÉΓòÉΓòÉ 4.11. RxCmdUploadCP290 - Get CP290 Command Execution Report ΓòÉΓòÉΓòÉ
Description
Every time the CP290 executes a command to an X-10 module, it sends a Command
Upload to the host computer. This is true whether the action was caused by a
RxDirCmdCP290 REXX Function, an event execution in the CP290, or manual control
from the CP290 keypad. This function receives this report, and formats the
uploaded information in a REXX compound variable.
Parameters
This function takes two parameters. The first parameter is the Comm Port
handle.
The second parameter is the stem name of a REXX compound variable to receive
the results. The format of this stem variable is as follows:
<StemName>.0 = CP290 Ack Status
<StemName>.1 = CP290 Base HouseCode. Valid Values are "A" through "P".
<StemName>.2 = Function executed by CP290. Will be either "ON", "OFF", or
"DIM".
<StemName>.3.0 = Number of Modules affected by command. Valid Values are
in range 1 to 16.
<StemName>.3.1 = First Module affected by command. Valid values are in
range 1 to 16.
<StemName>.3.n = Nth Module affected by command, where n =
<StemName>.3.0. Valid values are in range 1 to 16.
Returns
RxCmd UploadCP290 returns the number of characters received. This should be
equal to 12 for a normal call. If no command upload has been received, this
function will return 0.
Example
In this example, the call to RxCmdUploadCP290 is contained within a do while
loop. This waits until the command is received by the REXX program before
continuing. If the com port is left open for any period of time, this function
should be called periodically to check to see if any events that would cause a
report (such as manual key presses, or timer events) have occured. This will
keep the serial input and output buffers synchronized.
do while rc < 5
rc = RxCmdUploadCP290(CP290, 'result')
end
say 'Status - Result.0: 'result.0 /* CP290 ack status */
say 'Hcode - Result.1: 'result.1 /* House code: "A"-"P" */
say 'Function - Result.2: 'result.2 /* Function: "ON","OFF","DIM" */
say '# of Modules - Result.3.0: 'result.3.0 /* Number of modules affected */
do i = 1 to result.3.0
say 'Module 'i' - Result.3.'i': 'result.3.i /* Module number */
end
say 'Base - Result.4: 'result.4 /* CP290 Base Housecode */
ΓòÉΓòÉΓòÉ 4.12. RxDwnLdEvtCP290 - Download a Timer Event to the CP290 ΓòÉΓòÉΓòÉ
Description
RxDwnLdEvtCP290 downloads a Timer event to the CP290 for later execution.
Parameters
This function takes three parameters. The first parameter is the Comm Port
handle.
The second parameter is the event number. Valid Values range from 0 to 127.
Finally, the last parameter is the stem name of a REXX compound variable that
contains the timer event information. Note the similarity of this compound
variable format to the one used by RxGetEventsCP290. The format of this
compound variable is as follows:
<StemName>.0 = 0. This is not used by RxDwnLdEvtCP290, but is present for
compatibility with the format of the compound variable used by
RxgetEventsCP290.
<StemName>.1 = Timer Mode - valid entries are "NORMAL", "SECURITY",
"TODAY", "TOMORROW", or "CLEAR".
<StemName>.2.0 = Number of Days for event, valid range is 1 to 7.
<StemName>.2.1 = First Day for Timed Event. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.2.2 = Second Day for Timed Event. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.2.n = Nth Day for Timed Event, where n = <StemName>.2.0. Days
need not be in any order. Valid values are "MON", "TUE", "WED", "THU",
"FRI", "SAT", or "SUN".
<StemName>.3 = Event Time - Hours: Range 0-23.
<StemName>.4 = Event Time - Minutes: Range 0-59.
<StemName>.5.0 = Number of Modules for Event. Valid range is 1 to 16.
<StemName>.5.1 = First Module for Event. Valid range is 1 to 16. Modules
need not be listed in any order.
<StemName>.5.2 = Second Module for Event. Valid range is 1 to 16. Modules
need not be listed in any order.
<StemName>.5.n = Nth Module for Event, where n = <StemName>.5.0. Valid
range is 1 to 16. Modules need not be listed in any order.
<StemName>.6 = HouseCode for Event. Valid range is "A" to "P".
<StemName>.7 = Dim Level for Event. Valid range is 0 (dimmest) to 15
(brightest).
<StemName>.8 = Function for Event. Valid values are one of "ON", "OFF",
or "DIM".
Returns
RxDwnLdEvt returns the CP290 ack status after execution. This value will be
zero if no information has been downloaded to the CP290. It will be a 1 after
download of any command. This can be used to determine if the CP290 has been
powered off. A return code of -1 indicates a communication error with the
CP290.
Example
event.0 = 0 /* Not used - here for compatibility with */
/* RxGetEventsCP290 Compound Variable. */
event.1 = "NORMAL" /* Timer Mode - valid entries are "NORMAL", */
/* "SECURITY","TODAY","TOMORROW", and "CLEAR" */
event.2.0 = 4 /* Number of Days for Event: range 1-7 */
event.2.1 = "WED" /* First Day - one of "MON","TUE","WED","THU", */
event.2.2 = "THU" /* "SAT", or "SUN". */
event.2.3 = "FRI"
event.2.4 = "MON"
event.3 = 15 /* Event Time - Hours: Range 0-23 */
event.4 = 25 /* Event Time - Minutes: Range 0-59 */
event.5.0 = 4 /* Number of Modules for Event: Range 1-16 */
event.5.1 = 4 /* First Module: Range 1-16 */
event.5.2 = 3 /* 2nd Module */
event.5.3 = 16 /* 3rd Module */
event.5.4 = 10 /* 4th Module */
event.6 = "D" /* Housecode: Range "A"-"P" */
event.7 = 7 /* Dim Level: Range 0(dimmest)-15(brightest) */
event.8 = "DIM" /* Function - One of "ON","OFF","DIM */
rc = RxDwnldEvtCP290(CP290, 1,event) /* call the function */
ΓòÉΓòÉΓòÉ 4.13. RxGetEventsCP290 - Get All Active Timer Events from the CP290 ΓòÉΓòÉΓòÉ
Description
This function gets all the Timer Event information from the CP290, and makes it
available to the calling REXX program in the form of a large compound variable.
Parameters
This function takes two parameters. The first parameter is the Comm Port
handle.
The second parameter is the stem name of a REXX compound variable to receive
the results. This compound variable consists of several structures in the same
format as the compound variable used by RxDwnLdEvtCP290, for convenience. The
format of this compound variable is as follows:
<StemName>.0.0 = This will be 0 if Timer Event 0 does not exist, and 1 if
it does. In the event that Timer Event 0 does not exist, there will be no
data associated with <StemName>.0.1 through <StemName>.0.8.
<StemName>.0.1 = Timer Mode for Event 0 - valid entries are "NORMAL",
"SECURITY", "TODAY", "TOMORROW", or "CLEAR".
<StemName>.0.2.0 = Number of Days for Event 0, valid range is 1 to 7.
<StemName>.0.2.1 = First Day for Timed Event 0. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.0.2.2 = Second Day for Timed Event 0. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.0.2.n = Nth Day for Timed Event 0, where n = <StemName>.0.2.0.
Days need not be in any order. Valid values are "MON", "TUE", "WED",
"THU", "FRI", "SAT", or "SUN".
<StemName>.0.3 = Event 0 Time - Hours: Range 0-23.
<StemName>.0.4 = Event 0 Time - Minutes: Range 0-59.
<StemName>.0.5.0 = Number of Modules for Event 0. Valid range is 1 to 16.
<StemName>.0.5.1 = First Module for Event 0. Valid range is 1 to 16.
Modules need not be listed in any order.
<StemName>.0.5.2 = Second Module for Event 0. Valid range is 1 to 16.
Modules need not be listed in any order.
<StemName>.0.5.n = Nth Module for Event 0, where n = <StemName>.0.5.0.
Valid range is 1 to 16. Modules need not be listed in any order.
<StemName>.0.6 = HouseCode for Event 0. Valid range is "A" to "P".
<StemName>.0.7 = Dim Level for Event 0. Valid range is 0 (dimmest) to 15
(brightest).
<StemName>.0.8 = Function for Event 0. Valid values are one of "ON",
"OFF", or "DIM".
<StemName>.n.0 = This will be 0 if Timer Event n does not exist, and 1 if
it does. In the event that Timer Event n does not exist, there will be no
data associated with <StemName>.n.1 through <StemName>.n.8. This pattern
continues for n = 1 to 127.
<StemName>.n.1 = Timer Mode for Event n - valid entries are "NORMAL",
"SECURITY", "TODAY", "TOMORROW", or "CLEAR".
<StemName>.n.2.0 = Number of Days for Event n, valid range is 1 to 7.
<StemName>.n.2.1 = First Day for Timed Event n. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.2.2 = Second Day for Timed Event n. Days need not be in any
order. Valid values are "MON", "TUE", "WED", "THU", "FRI", "SAT", or
"SUN".
<StemName>.n.2.m = Mth Day for Timed Event n, where m = <StemName>.n.2.0.
Days need not be in any order. Valid values are "MON", "TUE", "WED",
"THU", "FRI", "SAT", or "SUN".
<StemName>.n.3 = Event n Time - Hours: Range 0-23.
<StemName>.n.4 = Event n Time - Minutes: Range 0-59.
<StemName>.n.5.0 = Number of Modules for Event n. Valid range is 1 to 16.
<StemName>.n.5.1 = First Module for Event n. Valid range is 1 to 16.
Modules need not be listed in any order.
<StemName>.n.5.2 = Second Module for Event n. Valid range is 1 to 16.
Modules need not be listed in any order.
<StemName>.n.5.m = Mth Module for Event n, where m = <StemName>n.5.0.
Valid range is 1 to 16. Modules need not be listed in any order.
<StemName>.n.6 = HouseCode for Event n. Valid range is "A" to "P".
<StemName>.n.7 = Dim Level for Event n. Valid range is 0 (dimmest) to 15
(brightest).
<StemName>.n.8 = Function for Event n. Valid values are one of "ON",
"OFF", or "DIM".
Returns
RxGetEventsCP290 returns the number of characters received.
Example
rc = RxGetEventsCP290(CP290, 'bigevt') /* Call the function */
say 'RxGetEventsCP290: 'rc
do i=0 to 127
if BigEvt.i.0 = 1 then Do /* If this value = 1, there is a */
/* corresponding event number. */
/* Otherwise, value is 0 */
say 'BigEvt.'i'.0 : 'BigEvt.i.0 /* 1 = event, 0 = no event */
say 'BigEvt.'i'.1 : 'BigEvt.i.1 /* Timer Mode Sel - as RxDwnLdEvt */
say 'BigEvt.'i'.2.0: 'BigEvt.i.2.0 /* Number of Days - as RxDwnLdEvt */
Do j = 1 to BigEvt.i.2.0
say 'BigEvt.'i'.2.'j': 'BigEvt.i.2.j /* Day info - as RxDwnLdEvt */
end
say 'BigEvt.'i'.3 : 'BigEvt.i.3 /* Hours: */
say 'BigEvt.'i'.4 : 'BigEvt.i.4 /* Minutes: */
say 'BigEvt.'i'.5.0: 'BigEvt.i.5.0 /* Number of Modules */
Do j = 1 to BigEvt.i.5.0
say 'BigEvt.'i'.5.'j': 'BigEvt.i.5.j /* Module number */
end
say 'BigEvt.'i'.6 : 'BigEvt.i.6 /* Housecode */
say 'BigEvt.'i'.7 : 'BigEvt.i.7 /* Dim Level */
say 'BigEvt.'i'.8 : 'Bigevt.i.8 /* Function */
end
end
ΓòÉΓòÉΓòÉ 5. RxCP290 Example Programs ΓòÉΓòÉΓòÉ
The REXX example programs shipped with teh RxCP290 package are described here
ΓòÉΓòÉΓòÉ 5.1. Smalltst.cmd - A Small Example Program ΓòÉΓòÉΓòÉ
Smalltst.cmd is provided as a minimal example - it simply loads the RxCP290
functions, opens the comm port, turns on a single module, closes the comm port,
and de-registers the functions. This is an example of what a CMD file called
from cron, or any other OS/2 program that executes programs at specific times,
might look like.
If you are going to be using the RxCP290 functions a lot, it might be better to
register the functions in STARTUP.CMD, so that they are always available to all
REXX programs in the system.
/* Small Rexx Program to Demo RXCP290 */
/* This small program Loads the RXCP290 Functions, opens COM2 for comms to */
/* the CP290, turns on Module D4, receives the acknowledgement from the CP290 */
/* closes the comport, and Drops the RxCP290 Functions. */
call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
call RxLoadFuncsCP290 /* Load RxCP290 Routines */
CP290 = '' /* Initialize Com Port Handle Var */
rc = RxInitCP290('COM2', 'CP290') /* Initialize Com Port */
rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4) /* Issue a direct command */
do while rc < 5
rc = RxCmdUploadCP290(CP290, 'result') /* Get the Report upon completion */
end
rc = RxCloseCP290(CP290) /* Close Communications */
call RxDropFuncsCP290 /* Drop RXCP290 Functions */
ΓòÉΓòÉΓòÉ 5.2. TestCP.Cmd - Working Examples of All RxCP290 Functions ΓòÉΓòÉΓòÉ
TestCP.CMD provides working examples of all the functions in RxCP290, by
sending a variety of commands to module D4. You may wish to edit this script to
use a different module before running this. Return codes and results of all
function calls are printed to the screen.
/*****************************************************************************/
/* TestCP.CMD A REXX Program to test all of the RxCP290 Functions */
/*****************************************************************************/
/* This program demonstrates the proper use of all of the RxCP290 functions. */
/* Each Function has it's input and output parameters described here, along */
/* with usage guidelines. Output from each function is printed to the screen */
/*****************************************************************************/
/*****************************************************************************/
/* Return Codes: */
/* */
/* All RxCP290 functions return a value indicating success or failure. This */
/* return code is returned via the normal REXX Function return procedure */
/* (ie - rc = RxFunc() ). The return code from an RxCP290 function is also */
/* placed in the special variable CP290rc. In all cases the returned value */
/* will be the same in these two locations. */
/*****************************************************************************/
/*****************************************************************************/
/* RxLoadFuncsCP290 - Load the RxCP290 Functions into REXX */
/*****************************************************************************/
/* Description: */
/* */
/* This function loads the RxCP290 X-10 communications functions, so that */
/* they are available to REXX programs. Execution of this command makes */
/* these functions available to all REXX programs in alll sessions under */
/* OS/2. These functions will remain available until explicitly dropped by */
/* The RxDropFuncsCP290 function. */
/*****************************************************************************/
/* Parameters: */
/* */
/* None */
/*****************************************************************************/
/* Returns: */
/* */
/* 0 if successful */
/* Non- zero returns indicate that none of the RxCP290 functions have been */
/* loaded. */
/*****************************************************************************/
/* Example: */
/* Load RxLoadFuncsCP290 */
call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
call RxLoadFuncsCP290 /* Call the RxCP290 function */
say 'RxLoadFuncsCP290, CP290rc: 'CP290rc /* Show results */
/*****************************************************************************/
/* RxInitCP290 - Initialize Communication Port */
/*****************************************************************************/
/* Description: */
/* */
/* RxInitCP290 initializes the serial port for communications with the CP290.*/
/* It initializes a Com Port Handle, which is used by all of the RxCP290 */
/* functions to determine which serial port to communicate with. This Comm */
/* Handle variable should be initialized in the REXX environment before */
/* using this function. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes two parameters. The first parameter is a string with */
/* the name of the serial port the CP290 is connected to. For this example, */
/* the CP290 is connected to COM2, so the parameter is 'COM2'. Note that */
/* This parameter must be in all caps. */
/* */
/* The second parameter is the name of a REXX variable to store the Com Port */
/* Handle in. This variable should have been initialized prior to calling */
/* function. */
/*****************************************************************************/
/* Returns: */
/* */
/* This function returns 0 when successful. Non-zero results indicate the */
/* was not opened. */
/*****************************************************************************/
/* Example: */
CP290 = '' /* Init Com Port Handle var */
rc = RxInitCP290('COM2', 'CP290') /* Call the function */
say 'RxInitCP290: 'rc', CP290rc: 'CP290rc /* print the results */
/*****************************************************************************/
/* RxDiagCP290 - Perform CP290 Self-Test */
/*****************************************************************************/
/* Description: */
/* */
/* This function commands the CP290 to perform it's internal diagnostic */
/* routines. Execution of these routines will take about 10 seconds. All */
/* information in the CP290 will be erased as a result of the execution of */
/* this function. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes a single parameter, the Com Port Handle produced by */
/* the RxInitCP290 function. */
/*****************************************************************************/
/* Returns: */
/* */
/* This function returns zero if successful. A return code of 1 indicates */
/* a CP290 diagnostics failure not related to the serial communications. A */
/* return code of less than zero indicates a communications failure, which */
/* may or may not be due to CP290 failure. */
/*****************************************************************************/
/* Example: */
rc = RxDiagCP290(CP290) /* Call Function */
say 'RxDiagCP290: 'rc', CP290rc: 'CP290rc /* Print return code */
/*****************************************************************************/
/* RxSetHCodeCP290 - Set CP290 Base House Code */
/*****************************************************************************/
/* Description: */
/* */
/* RxSetHcodeCP290 sets the CP290's Base Housecode. All information in the */
/* CP290 will be erased as a result of this function's execution. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes two parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is a REXX string containing the new Housecode letter.*/
/* Valid housecodes are in the range "A" to "P". */
/*****************************************************************************/
/* Returns: */
/* */
/* RxSetHcode returns the CP290 ack status after execution. This value will */
/* be zero if no information has been downloaded to the CP290. It will be a */
/* 1 after download of any command. This can be used to determine if the */
/* CP290 has been powered off. A return code of -1 indicates a communication */
/* error with the CP290. */
/*****************************************************************************/
/* Example: */
rc = RxSetHCodeCP290(CP290, "D") /* Set Housecode "D" */
say 'RxSetHCodeCP290: 'rc /* Print the results */
/*****************************************************************************/
/* RxSetTimeCP290 - Set CP290 Base House Code */
/*****************************************************************************/
/* Description: */
/* */
/* RxSetTimeCP290 sets the CP290's internal clock from the host computer's */
/* internal clock. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes one parameter, the Comm Port handle */
/*****************************************************************************/
/* Returns: */
/* */
/* RxSetTime returns the CP290 ack status after execution. This value will */
/* be zero if no information has been downloaded to the CP290. It will be a */
/* 1 after download of any command. This can be used to determine if the */
/* CP290 has been powered off. A return code of -1 indicates a communication */
/* error with the CP290. */
/*****************************************************************************/
/* Example: */
rc = RxSetTimeCP290(CP290) /* Set current Computer Time */
say 'RxSetTimeCP290: ' rc /* Print the results */
/*****************************************************************************/
/* RxGetTimeCP290 - Get CP290 Time and House Code */
/*****************************************************************************/
/* Description: */
/* */
/* RxGetTimeCP290 returns the CP290's internal clock time and House Code. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes two parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is the stem name of a REXX compound variable to */
/* receive the results. The format of this stem variable is shown below, in */
/* section that prints the results. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxGetTimeCP290 returns the number of characters received. This should be */
/* equal to 12 for a normal call. */
/*****************************************************************************/
/* Example: */
rc = RxGetTimeCP290(CP290, 'result') /* Get CP290 time */
say 'RxGetTimeCP290: ' rc /* Print return code */
say 'Status - Result.0: 'result.0 /* CP290 Ack Status */
say 'Minutes - Result.1: 'result.1 /* Minutes: valid 00 - 59 */
say 'Hours - Result.2: 'result.2 /* Hours: valid 00 - 23 */
say 'Day Week - Result.3: 'result.3 /* Day of Week: in "MON","TUE","WED" */
/* "THU","FRI","SAT","SUN" */
say 'Base - Result.4: 'result.4 /* Base Housecode: valid "A" - "P" */
/*****************************************************************************/
/* RxDirCmdCP290 - Send CP290 direct command */
/*****************************************************************************/
/* Description: */
/* */
/* RxDirCmdCP290 sends a direct command to a single X-10 module */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes five parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is the dim level, for the DIM function. Valid Values */
/* range from 00(dimmest) to 15(brightest). */
/* */
/* The third parameter is the function code. This can be one of "ON", "OFF", */
/* or "DIM". */
/* */
/* The fourth parameter is a REXX string containing the new Housecode letter.*/
/* Valid housecodes are in the range "A" to "P". */
/* */
/* Finally, the last parameter is the module number to affect. Valid values */
/* are in the range 1 through 16. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxDirCmd returns the CP290 ack status after execution. This value will */
/* be zero if no information has been downloaded to the CP290. It will be a */
/* 1 after download of any command. This can be used to determine if the */
/* CP290 has been powered off. A return code of -1 indicates a communication */
/* error with the CP290. */
/*****************************************************************************/
/* Example: */
rc = RxDirCmdCP290(CP290, 8, "ON" ,"D", 4) /* Turn on Module D4 */
say 'RxDirCmdCP290: 'rc', CP290rc: 'CP290rc
/*****************************************************************************/
/* RxCmdUploadCP290 - Get CP290 execution report */
/*****************************************************************************/
/* Description: */
/* */
/* Every time the CP290 executes a command to an X-10 module, it sends a */
/* Command Upload to the host computer. This is true whether the action was */
/* caused by a RxDirCmdCP290 REXX Function, an event execution in the CP290, */
/* or manual control from the CP290 keypad. This function receives this */
/* report, and formats the uploaded information in a REXX compound variable. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes two parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is the stem name of a REXX compound variable to */
/* receive the results. The format of this stem variable is shown below, in */
/* section that prints the results. */
/*****************************************************************************/
/* Usage Notes: */
/* */
/* In this example, the call to RxCmdUploadCP290 is contained within a do */
/* while loop. This waits until the command is received by the REXX program */
/* before continuing. If the com port is left open for any period of time, */
/* this function should be called periodically to check to see if any events */
/* that would cause a report (such as manual key presses, or timer events). */
/* This will keep the serial input and output buffers synchronized. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxCmd UploadCP290 returns the number of characters received. This should */
/* be equal to 12 for a normal call. If no command upload has been received, */
/* this function will return 0. */
/*****************************************************************************/
/* Example: */
do while rc < 5
rc = RxCmdUploadCP290(CP290, 'result')
end
say 'Status - Result.0: 'result.0 /* CP290 ack status */
say 'Hcode - Result.1: 'result.1 /* House code: "A"-"P" */
say 'Function - Result.2: 'result.2 /* Function: "ON","OFF","DIM" */
say '# of Modules - Result.3.0: 'result.3.0 /* Number of modules affected */
do i = 1 to result.3.0
say 'Module 'i' - Result.3.'i': 'result.3.i /* Module number */
end
say 'Base - Result.4: 'result.4 /* CP290 Base Housecode */
/*****************************************************************************/
/* RxDirCmdManyCP290 - Send Direct Command to Many X-10 Modules */
/*****************************************************************************/
/* Description: */
/* */
/* RxDirCmdManyCP290 sends a direct command to a series of X-10 modules */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes five parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is the dim level, for the DIM function. Valid Values */
/* range from 00(dimmest) to 15(brightest). */
/* */
/* The third parameter is the function code. This can be one of "ON", "OFF", */
/* or "DIM". */
/* */
/* The fourth parameter is a REXX string containing the new Housecode letter.*/
/* Valid housecodes are in the range "A" to "P". */
/* */
/* Finally, the last parameter is the stem name of a REXX compound variable */
/* that contains a list of the modules to command. The format of this */
/* variable is demonstrated in the example below. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxDirCmdMany returns the CP290 ack status after execution. This value will*/
/* be zero if no information has been downloaded to the CP290. It will be a */
/* 1 after download of any command. This can be used to determine if the */
/* CP290 has been powered off. A return code of -1 indicates a communication */
/* error with the CP290. */
/*****************************************************************************/
/* Example: */
dcom.0 = 5 /* 5 modules to command */
dcom.1 = 4 /* 1st module - Module 4 */
dcom.2 = 5 /* 2nd module - Module 5 */
dcom.3 = 16 /* 3rd module - Module 16 */
dcom.4 = 10 /* 4th module - Module 10 */
dcom.5 = 7 /* 5th module - Module 7 */
rc = RxDirCmdManyCP290(CP290, 8, "OFF" ,"D", "dcom") /* call the function */
say 'RxDirCmdManyCP290: 'rc', CP290rc: 'CP290rc
do while rc < 5
rc = RxCmdUploadCP290(CP290, 'result')
end
say 'Status - Result.0: 'result.0
say 'Hcode - Result.1: 'result.1
say 'Function - Result.2: 'result.2
say '# of Modules - Result.3.0: 'result.3.0
do i = 1 to result.3.0
say 'Module 'i' - Result.3.'i': 'result.3.i
end
say 'Base - Result.4: 'result.4
/*****************************************************************************/
/* RxDwnLdEvtCP290 - Download a Timer Event to the CP290 */
/*****************************************************************************/
/* Description: */
/* */
/* RxDwnLdEvtCP290 downloads a Timer event to the CP290 for later execution. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes three parameters. The first parameter is the Comm */
/* Port handle. */
/* */
/* The second parameter is the event number. Valid Values range from 0 to */
/* 127. */
/* */
/* Finally, the last parameter is the stem name of a REXX compound variable */
/* that contains the timer event information. The format of this variable is */
/* demonstrated in the example below. Note the similarity of this variable */
/* format to the one used by RxGetEventsCP290. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxDwnLdEvt returns the CP290 ack status after execution. This value will */
/* be zero if no information has been downloaded to the CP290. It will be a */
/* 1 after download of any command. This can be used to determine if the */
/* CP290 has been powered off. A return code of -1 indicates a communication */
/* error with the CP290. */
/*****************************************************************************/
/* Example: */
event.0 = 0 /* Not used - here for compatibility with */
/* RxGetEventsCP290 Compound Variable. */
event.1 = "NORMAL" /* Timer Mode - valid entries are "NORMAL", */
/* "SECURITY","TODAY","TOMORROW", and "CLEAR" */
event.2.0 = 4 /* Number of Days for Event: range 1-7 */
event.2.1 = "WED" /* First Day - one of "MON","TUE","WED","THU", */
event.2.2 = "THU" /* "SAT", or "SUN". */
event.2.3 = "FRI"
event.2.4 = "MON"
event.3 = 15 /* Event Time - Hours: Range 0-23 */
event.4 = 25 /* Event Time - Minutes: Range 0-59 */
event.5.0 = 4 /* Number of Modules for Event: Range 1-16 */
event.5.1 = 4 /* First Module: Range 1-16 */
event.5.2 = 3 /* 2nd Module */
event.5.3 = 16 /* 3rd Module */
event.5.4 = 10 /* 4th Module */
event.6 = "D" /* Housecode: Range "A"-"P" */
event.7 = 7 /* Dim Level: Range 0(dimmest)-15(brightest) */
event.8 = "DIM" /* Function - One of "ON","OFF","DIM */
rc = RxDwnldEvtCP290(CP290, 1,event) /* call the function */
say 'RxDwnldEvtCP290: 'rc
/*****************************************************************************/
/* RxGetEventsCP290 - Get CP290 Timer Events */
/*****************************************************************************/
/* Description: */
/* */
/* This function gets all the Timer Event information from the CP290, and */
/* makes it available to the calling REXX program in the form of a large */
/* compound variable. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes two parameters. The first parameter is the Comm Port */
/* handle. */
/* */
/* The second parameter is the stem name of a REXX compound variable to */
/* receive the results. The format of this compound variable is shown below, */
/* in the section that prints the results. This compound variable consists */
/* of several structures in the same format as the compound variable used by */
/* RxDwnLdEvtCP290, for convenience. */
/*****************************************************************************/
/* Returns: */
/* */
/* RxGetEventsCP290 returns the number of characters received. */
/*****************************************************************************/
/* Example: */
rc = RxGetEventsCP290(CP290, 'bigevt') /* Call the function */
say 'RxGetEventsCP290: 'rc
do i=0 to 127
if BigEvt.i.0 = 1 then Do /* If this value = 1, there is a */
/* corresponding event number. */
/* Otherwise, value is 0 */
say 'BigEvt.'i'.0 : 'BigEvt.i.0 /* 1 = event, 0 = no event */
say 'BigEvt.'i'.1 : 'BigEvt.i.1 /* Timer Mode Sel - as RxDwnLdEvt */
say 'BigEvt.'i'.2.0: 'BigEvt.i.2.0 /* Number of Days - as RxDwnLdEvt */
Do j = 1 to BigEvt.i.2.0
say 'BigEvt.'i'.2.'j': 'BigEvt.i.2.j /* Day info - as RxDwnLdEvt */
end
say 'BigEvt.'i'.3 : 'BigEvt.i.3 /* Hours: */
say 'BigEvt.'i'.4 : 'BigEvt.i.4 /* Minutes: */
say 'BigEvt.'i'.5.0: 'BigEvt.i.5.0 /* Number of Modules */
Do j = 1 to BigEvt.i.5.0
say 'BigEvt.'i'.5.'j': 'BigEvt.i.5.j /* Module number */
end
say 'BigEvt.'i'.6 : 'BigEvt.i.6 /* Housecode */
say 'BigEvt.'i'.7 : 'BigEvt.i.7 /* Dim Level */
say 'BigEvt.'i'.8 : 'Bigevt.i.8 /* Function */
end
end
/*****************************************************************************/
/* RxCloseCP290 - Close CP290 Serial Port */
/*****************************************************************************/
/* Description: */
/* */
/* RxCloseCP290 closes the serial port specified by the Com Port Handle, */
/* freeing the port for use by other OS/2 applications. */
/*****************************************************************************/
/* Parameters: */
/* */
/* This function takes one parameter, the Comm Port handle */
/*****************************************************************************/
/* Returns: */
/* */
/* Returns 0 if successful */
/*****************************************************************************/
/* Example: */
rc = RxCloseCP290(CP290)
say 'RxCloseCP290: 'rc', CP290rc: 'CP290rc
/*****************************************************************************/
/* RxDropFuncsCP290 - Drop the RxCP290 Functions from REXX */
/*****************************************************************************/
/* Description: */
/* */
/* This function drops the RxCP290 X-10 communications functions, so that */
/* they are no longer available to REXX programs. Execution of this command */
/* makes these functions unavailable to all REXX programs in all sessions */
/* in OS/2. These functions will remain unavailable until explicitly loaded */
/* by the RxLoadFuncsCP290 function. */
/*****************************************************************************/
/* Parameters: */
/* */
/* None */
/*****************************************************************************/
/* Returns: */
/* */
/* 0 if successful */
/*****************************************************************************/
/* Example: */
call RxDropFuncsCP290
say 'RxDropFuncsCP290, CP290rc: 'CP290rc
ΓòÉΓòÉΓòÉ 5.3. SaveRest.CMD - Example REXX Procedures for saving and Restoring Events Information from Files ΓòÉΓòÉΓòÉ
This example program shows how the Timer Event information returned by
RxGetEventsCP290() can be saved to a disk file and then restored. It retrieves
all of the Timer Events from the CP290 via the RXGetEventsCP290() call, and
then saves them via an example REXX Procedure named SaveEvents. The events
variable is then erased, and reloaded from the disk file by an example REXX
Procedure named RetrvEvents. The CP290 then has it's Timer Event information
erased as a side effect of the RxSetHCodeCP290() function, and restored by
calling RxDwnLdEvtCP290() for each existing event.
/* Rexx Program to Test RXCP290 Routines */
/* Load RxCP290 Routines */
call RxFuncAdd 'RxLoadFuncsCP290', 'RxCP290', 'RxLoadFuncsCP290'
call RxLoadFuncsCP290
say 'RxLoadFuncsCP290, CP290rc: 'CP290rc
/* Initialize Com Port Handle Variable */
CP290 = ''
/* Initialize Com Port */
rc = RxInitCP290('COM2', 'CP290')
say 'RxInitCP290: 'rc', CP290rc: 'CP290rc
/* Get All Events from CP290 */
rc = RxGetEventsCP290(CP290, 'events')
say 'RxGetEventsCP290: 'rc
/* Print Out events information */
say
do i=0 to 127
if events.i.0 = 1 then
Do
say 'events.'i'.0 : 'events.i.0
say 'events.'i'.1 : 'events.i.1
say 'events.'i'.2.0: 'events.i.2.0
Do j = 1 to events.i.2.0
say 'events.'i'.2.'j': 'events.i.2.j
end
say 'events.'i'.3 : 'events.i.3
say 'events.'i'.4 : 'events.i.4
say 'events.'i'.5.0: 'events.i.5.0
Do j = 1 to events.i.5.0
say 'events.'i'.5.'j': 'events.i.5.j
end
say 'events.'i'.6 : 'events.i.6
say 'events.'i'.7 : 'events.i.7
say 'events.'i'.8 : 'events.i.8
end
end
/* Save the events information */
file = "testfile.sav"
call SaveEvents file
/* Erase the internal events structure */
events. = 0
/* Retrieve the Events from a file */
call RtrvEvents file
/* Print out Events retrieved */
say
do i=0 to 127
if events.i.0 = 1 then
Do
say 'events.'i'.0 : 'events.i.0
say 'events.'i'.1 : 'events.i.1
say 'events.'i'.2.0: 'events.i.2.0
Do j = 1 to events.i.2.0
say 'events.'i'.2.'j': 'events.i.2.j
end
say 'events.'i'.3 : 'events.i.3
say 'events.'i'.4 : 'events.i.4
say 'events.'i'.5.0: 'events.i.5.0
Do j = 1 to events.i.5.0
say 'events.'i'.5.'j': 'events.i.5.j
end
say 'events.'i'.6 : 'events.i.6
say 'events.'i'.7 : 'events.i.7
say 'events.'i'.8 : 'events.i.8
end
end
/* Erase CP290 Timer Events */
rc = RxSetHCodeCP290(CP290, "D")
/* Reload CP290 Events from events. */
do i = 0 to 127
if events.i.0 = 1 then
do
/* Create name of events entry - events.1, events.2, etc. */
evt = 'events.'||i
rc = RxDwnLdEvtCP290(CP290, i, evt)
say 'RxDwnLdEvtCP290: rc = 'rc ' Event number: 'i
end
end
/* Close Communications */
rc = RxCloseCP290(CP290)
say 'RxCloseCP290: 'rc', CP290rc: 'CP290rc
/* Drop RXCP290 Functions */
call RxDropFuncsCP290
say 'RxDropFuncsCP290, CP290rc: 'CP290rc
exit
SaveEvents: Procedure Expose events.
arg filenm
call lineout filenm, ,1
do i=0 to 127
call lineout filenm, events.i.0
if events.i.0 = 1 then
Do
call lineout filenm, events.i.1
call lineout filenm, events.i.2.0
Do j = 1 to events.i.2.0
call lineout filenm, events.i.2.j
end
call lineout filenm, events.i.3
call lineout filenm, events.i.4
call lineout filenm, events.i.5.0
Do j = 1 to events.i.5.0
call lineout filenm, events.i.5.j
end
call lineout filenm, events.i.6
call lineout filenm, events.i.7
call lineout filenm, events.i.8
end
end
call lineout(filenm)
return
RtrvEvents: Procedure Expose events.
arg filenm
call linein filenm, ,0
do i=0 to 127
events.i.0 = linein(filenm)
if events.i.0 = 1 then
Do
events.i.1 = linein(filenm)
events.i.2.0 = linein(filenm)
Do j = 1 to events.i.2.0
events.i.2.j = linein(filenm)
end
events.i.3 = linein(filenm)
events.i.4 = linein(filenm)
events.i.5.0 = linein(filenm)
Do j = 1 to events.i.5.0
events.i.5.j = linein(filenm)
end
events.i.6 = linein(filenm)
events.i.7 = linein(filenm)
events.i.8 = linein(filenm)
end
end
return
ΓòÉΓòÉΓòÉ 5.4. CP290Web.Cmd - A REXX CGI Program for Access to X-10 Commands from the World Wide Web ΓòÉΓòÉΓòÉ
Also provided as an example program is CP290web.cmd, and the companion
CP290.html. CP290.html provides a simple World Wide Web page consisting of a
form that allows the selection of Housecode, Module, Function, and dim level,
and then issues a direct command to the CP290 via the CP290web.cmd program,
called via the WWW server's CGI Interface. These have been tested with GoServe,
an excellent Web Server available as IBM Employee Written Software, using the
GoHTTP CGI/IMAP enhancements.
ΓòÉΓòÉΓòÉ 5.5. CP290.EXE - An OS/2 Program for basic CP290 X-10 Control written with RxCP290 ΓòÉΓòÉΓòÉ
Finally, a larger example program has been created using DrDialog, an IBM EWS
tool that allows the creation of WorkPlace Shell programs in REXX. The REXX
Source for this is included in the distribution of RxCP290, but as it is quite
specific to the DrDialog tool, may be of limited utility. The usage of
CP290.EXE is described in the next section.
ΓòÉΓòÉΓòÉ 6. Using CP290.EXE ΓòÉΓòÉΓòÉ
The RxCP290 package comes with an application written with DrREXX, an IBM EWS
program, that allows basic control of all of the CP290 X10 controller functions
from a PM program. This program is shipped with the executable, CP290.EXE, the
RES file produced by DrREXX, CP290.RES, and a source listing, CP290.RXX.
CP290.RES would be useful for those users wishing to extend the functionality
of this package.
ΓòÉΓòÉΓòÉ 6.1. Starting the Program ΓòÉΓòÉΓòÉ
Start this program like any other OS/2 program, from the command line or by
double-clicking on the program object.
ΓòÉΓòÉΓòÉ 6.2. The Init Page - Initializing the program and CP290 Interface ΓòÉΓòÉΓòÉ
When first started, the Init page of the Notebook will be on top. It looks like
this:
The following tasks may be accomplished from this screen:
Setting the Communications Port
The serial port used by this program may be set on this screen. When the Set
ComPort button is pressed, the program saves the comport specified in OS2.INI,
so this only needs to be done once.
Setting the serial port to the port the CP290 is actually connected to should
be done first, as all the other commands require communications with the CP290
unit.
Setting the Base Housecode
The Base Housecode of the CP290 may be set by entering the desired Housecode
and pressing the Set HouseCode button.
Note: The CP290 must be connected to the serial port specified on this page for
this function to work correctly.
Setting the CP290 Clock
Pressing the Set Time button sets the CP290's internal clock to the time and
day of week on the PC.
ΓòÉΓòÉΓòÉ 6.3. The Direct Command Page - Sending Direct X-10 Commands ΓòÉΓòÉΓòÉ
The Direct Command Notebook page looks like this:
This page allows direct control of a single X-10 module. Pressing the Execute
button sends the command.
ΓòÉΓòÉΓòÉ 6.4. The File Menu - Saving and Restoring CP290 Timer Events ΓòÉΓòÉΓòÉ
The File menu allows the user to save and restore files of CP290 Timer Events.
Up to 127 events may be stored in a single file.
The files used by CP290.EXE are in ASCII format, and are similar to the files
produced by the SaveRest.CMD example program.
ΓòÉΓòÉΓòÉ 6.4.1. Creating a New Event Table ΓòÉΓòÉΓòÉ
Selecting the New entry under the File Menu clears out all events stored in the
Notebook. A single page for Event 0 is left, for the user to start filling out
new events from.
ΓòÉΓòÉΓòÉ 6.4.2. Retrieving Events from Disk ΓòÉΓòÉΓòÉ
Selecting the Open entry under the File Menu opens a standard OS/2 File Dialog.
This allows the user to retrieve previously saved files of events.
ΓòÉΓòÉΓòÉ 6.4.3. Saving Events to Disk ΓòÉΓòÉΓòÉ
Both the Save and Save As entries under the File Menu open a standard OS/2 File
dialog, allowing the user to save the current events in the notebook.
ΓòÉΓòÉΓòÉ 6.4.4. Exiting the Program ΓòÉΓòÉΓòÉ
Finally, as is considered normal in OS/2 programs, selecting the Quit option
will exit the program. The program may also be exited by double-clicking on the
upper left corner of the window.
ΓòÉΓòÉΓòÉ 6.5. The Events Menu - Managing CP290 Timer Events and Event Pages ΓòÉΓòÉΓòÉ
The remaining pages of the Notebook are Event Pages, one for each Timer Event
to be sent to the CP290. The Event Pages look like this:
Events may be added, deleted, sent to the CP290, or retrieved from the CP290
unit by the Event Menu entries. Each new event adds a new Event page to the
NoteBook.
Creating a New Event
Selecting New Event under the Event Menu creates a new event page. The number
of the new event page will be the lowest event number not currently used, so if
there are gaps in the numbering of events, these gaps will be filled.
Deleting an Event
Selecting Del Event under the Event Menu deletes the event page currently
displayed on the top of the Notebook.
Note: In addition to deleting the event information, this function deletes the
currently displayed page. Selecting Del Event when the Init or Direct Command
page is displayed will result in these pages being deleted from the Notebook
for the remainder of the session. Restarting the CP290.EXE program will restore
the missing pages.
Getting Events from the CP290
Selecting GetEvents from the Events Menu will retrieve all events from the
CP290 unit. All events shown in the notebook prior to this will be lost,
replaced by the CP290 events.
Storing Events to the CP290
Pressing StoreEvents under the Events menu stores the events shown in the
NoteBook to the CP290 unit. The CP290 immediately begins executing the new set
of Timer Events.
ΓòÉΓòÉΓòÉ 7. Additional Information ΓòÉΓòÉΓòÉ
Additional information
ΓòÉΓòÉΓòÉ 7.1. Trademarks ΓòÉΓòÉΓòÉ
X-10 and CP290 Home Control Interface are registered trade marks of X-10 (USA)
Inc.
ΓòÉΓòÉΓòÉ 7.2. Disclaimer ΓòÉΓòÉΓòÉ
THERE IS NO WARRANTY FOR THIS PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING DECKER AUTOMATION PROVIDES THE
PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM LIES WITH THE USER. IN NO EVENT UNLESS REQUIRED BY
APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER
PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMANGES ARISING OUT OF THE USE OF INABILITY TO USE THE PROGRAM
(INCLUDING BUT NOT LIMITED TO THE LOSS OF DATA OR DATA BEING RENDERED INACURATE
OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
ΓòÉΓòÉΓòÉ 7.3. About X-10 ΓòÉΓòÉΓòÉ
The X-10 Home Control System is a popular system for automating the control of
lights and appliances in the home. X-10 modules and controllers are sold by a
number of companies, under a num,ber of labels. For more information, you may
wish to contact X-10, at the following:
X-10 (USA) Inc.
185A LeGrande Ave
Northvale, NJ 07647
(201) 784-9700
X-10 Home Controls Inc
1200 Aerowood Drive, Unit 20
Mississauga, Ontario L4W 2S7
(416) 624-4446
ΓòÉΓòÉΓòÉ 7.4. About Decker Automation ΓòÉΓòÉΓòÉ
Decker Automation is a Factory Floor Automation Software and Networking
consulting firm. We have extensive experience with all aspects of the software
side of factory-floor automation, from programming simple PLCs through
designing complete automation network architectures. Our experience also
includes the design of PLCs and PLC-like languages and systems, design and
implementation of several different Fieldbuses, and communications device
driver creation for various operating systems including DOS, Windows, OS/2, and
VMS. Our experience with the WorldFIP fieldbus is particularly extensive.
In addition, Decker Automation has contributed several programs to the OS/2
community. These include the other World Wide Web Browser for OS/2,
<B>Lynx/2</B>, and an Internet retrieval tool, <B>GetURL</B>. We are also
working on expanding our REXX-based Home Automation line of products - look for
support for a PC to IR Remote control interface, and the new X-10 CM10A Home
Controller in the near future!
Decker Automation may be contacted at:
Decker Automation
833 Penny Lane
Lexington, KY 40509
Tel/Fax: 606/263-8560
Email: djd@cris.com
WWW Page: http://www.cris.com/~djd