Macros

Macros are the heart of the PowerHome program. It is here that most actions are defined and if-then logic is performed. Having well defined and thought out macros will enable you to maximize your use of the PowerHome Program. From within macros you can: control Insteon, UPB, and X10 devices, send infrared commands, call other macros, set global variables, set certain system variables, launch applications, switch to other applications, perform a Send Keys, initiate a dial-up connection, disconnect a dial-up connection, send Email, perform Text to Speech, create timed events, play a CD jukebox playlist, perform delays, trim the event log, get input, post a messagebox, perform direct SQL on the database, retrieve data from the database, clear the X10 history variables, and nearly any other function for automation control. The Formula language used within macros allows for sophisticated if-then-else logic and looping. Macros are defined within the Macro section of the PowerHome Explorer.

The available Macro commands are detailed below:

This command allows you to send an infrared code that is already learned by the system. You will need to select the equipment and the infrared button.

This command allows you send raw X10 commands via a connected X10 controller. You'll need to supply the Controller ID, the House code, and the Unit Code / Command. It will typically take 2 of these commands to perform any one X10 action (first selecting house/unit code and then sending a house/command). In the case of sending dim or bright commands, you will also need to input a formula which will evaluate to a number from 1 to 100 as the relative dim/bright percentage.

The X10 command enables you to control X10 devices that have already been defined in the X10 Devices screen. Since the X10 device is predefined, you just need to select the X10 Device ID and the command you would like performed.

You can launch another macro from within this macro. When you do this, the current macros execution is either suspended and the new macro is executed or the new macro is posted to the execution queue to be executed sometime after the current macro completes. You will need to select the macro ID you would like to execute and whether or not to execute the macro immediately or have it posted. When you execute a macro using the "Macro" command, the new macro gets a copy of the current macro System variables with the [LOCAL?] variables blanked. Changes made to the System variables in the called macro will NOT be reflected in the original macro System variables when the called macro terminates. It should be noted that if a "Wait" command is executed from within a macro that is called using the "Macro" command, the macro that is waiting is effectively terminated meaning that control will be transferred back to the calling macro and execution will continue. If this is not the desired outcome and you want a called macro to Wait without control being returned to the calling macro, use the SubMacro command instead.

You can set the value of a global variable. You will specify the ID of the global variable and a formula to be evaluated. The result of the formula will be assigned to the global variable. All values in global variables are stored in character format. More information on formulas can be found in the formula section.

You can set the value of certain system variables. You will specify the system variable and a formula whose result will be assigned to the system variable.

You can launch another application on the computer. You will specify the full path and executable of the application to be launched as a formula. If the executable is known at design time and not determined dynamically, merely enclose the full path and executable name within single or double quotes.

You can switch to another currently running application and make it the foreground application. This is useful if you want PowerHome to send keystrokes to the application to control it. You will specify the type of application switching by selecting either Class Name or Window Name in the value field. Choosing Class Name means to use the class name of the running application for switching purposes. You would typically use this method on applications that do not have a constant window name such as Winamp. Winamp’s window name will change based upon the current song playing, however the class name of an application will not change. To find the class name of an application you need to use a program such as spy. The class name for Winamp by the way is “Winamp v1.x” without the quotes and paying attention to the capitalization. For other applications whose window name remains the same (such as PowerHome), use Window Name for the value field. When you switch to an application from PowerHome and Send Keys to it, you will want to switch back to PowerHome when you are done. The window name for PowerHome is a single space followed by the word PowerHome followed by two spaces. The class name or window name must be entered as a formula within the Send Keys field.

You can simulate keystrokes with this command as if you were typing at the keyboard. Whatever is the current foreground application will receive the keystrokes. If you want to Send Keystrokes to an application other than PowerHome you must first launch it and switch to it. You also have the option to either have the keys sent immediately or be posted to the execution queue. If the Send Keys is posted to the execution queue, the entire formula is posted. After the Send Keys formula is serviced by the execution queue, the Send Keys formula will then be evaluated and the result sent to the Send Keys interpreter. It is important to note that the formula is NOT evaluated before going to the execution queue if you choose post. You will enter the Send Keys formula in the Send Keys field. An explanation of the valid Send Keys will be explained in the Send Keys section.

This command is obsolete in todays modern internet connected environment but can still be useful in legacy applications. With this command you can launch an already defined dialup connection. You must select either Continue or Wait in the value field. A value of Continue will launch the dialup connection in the background while the macro continues to run. A value of Wait will launch the dialup connection and force the macro to suspend execution until the connection is established. Enter a formula that evaluates to the exact name of the Dialup connection in the Send Keys field.

This command is the Disconnect command for a Dialup Connection is also obsolete but still available. This command enables you to disconnect a currently connected dialup session. You must select either Continue or Wait in the value field. A value of Continue will close the dialup connection in the background while the macro continues to run. A value of Wait will suspend execution of the macro until the dialup connection is disconnected.

Allows for the sending of email through a default MAPI mail client. This command would not typically be used in todays environment as better alternatives exist for sending email such as using one of the ph_sendsmtpemail functions. In order to use this command you must first set the email system variables. This is accomplished by doing a Set System for [EMAILNAME] and a Set System for [EMAILSUBJECT]. Once these system variables are set, you can then do a Send Email. Remember, that system variables are reset everytime PowerHome starts so you will usually set these system variables every time just before you do the Send Email. With this command, you must enter a formula that evaluates to the text of the email message you would like to send in the Send Keys field. This can be as simple as the text that you would like sent surrounded by single or double quotes. This command uses standard MAPI mail calls. You must have a default MAPI mail client declared for this function to work. This will usually be your default mail client such as Microsoft Outlook. Check the options of your mail client and verify that you have a default MAPI client assigned.

This command will use your default MAPI client to receive EMail. If you have enabled EMail control in the Setup area of the PowerHome Explorer, it will also process any EMail intended to control PowerHome. This command takes no arguments.

Allows you to send Text to Speech. If you have configured and enabled text to speech in the Setup section of PowerHome Explorer, you can have the PowerHome computer speak to you. You must enter a formula that evaluates to the message you would like to have spoken in the Send Keys field.

You can create timed events. The timed event will always have an action type of macro and will always have a frequency of one shot. Select the macro to be assigned to the timed event in the ID field and enter a formula that evaluates to the time the timed event will fire in the Send Keys field. This formula must evaluate to a valid timestamp in the form of yyyy-mm-dd hh:mm:ss or a number representing the number of minutes in the future from the current time. Since the time that this command was created, much more robust methods of creating Timed Events have become available via the ph_createtimedevent functions.

The jump command is a basic command that handles if-then-else type processing. Normally, a macro is executed starting at line 1 and every line is executed in order all the way to the last line. The jump command allows you change this normal execution order and jump to a different line within the current macro. The jump command expects a formula in the Send Keys field that evaluates to a positive or negative integer. If the formula evaluates to 2, the jump command will transfer execution down 2 lines, in effect skipping the line just below the jump command. A negative integer causes control to transfer above the jump line. If the formula does not return an integer, the jump will be ignored and control will transfer to the next line. This allows the user to create their own error handling by placing any error code on the line immediately after the jump. To exit the current macro immediately with no further processing, have the formula return a positive integer beyond the last line of the macro. The important thing to remember with the jump command is that the line jumped to is relative to the current jump line. You cannot jump to an absolute macro line. See the Label and Goto Label commands for additional flow control processing.

This command is obsolete but still available. This command allows you to have a predefined playlist programmed into your CD jukebox. Select the playlist to be programmed in the ID field and either Normal or Randomize in the Value field. A value of Normal will cause the playlist to be programmed in the order of the playlist. A value of Randomize will first randomize the songs in the playlist and then send the infrared commands to the jukebox.

This command will clear the X10 history variable buffers. You can select whether to clear the Global Buffer, All Buffers, or a particular housecode buffer. When you clear a buffer, you can clear just the first entry which will place a string of five zeroes into the first multi-x entry or clear the entire buffer which will place zeros in the entire multi-x buffer. It will not blank out the times associated with these variables. Starting with version 1.00.1, PowerHome has expanded the global buffer to 20 entries and added a 20 entry buffer for each housecode. Version 1.01.1 has expanded the system variables to access all 20 of the global buffers commands and times. To access the housecode buffers, use the new functions ph_multix and ph_multixtime.

Delays macro execution for the specified number of milliseconds. Enter the number of milliseconds of delay you want as a formula in the Send Keys field. There are 1000 milliseconds in 1 second. For a delay of 2 seconds, enter 2000 in the Send Keys field. Delays should be used very sparingly as nothing else will execute while in a delay. If you want an effect such that a macro is launched when a motion sensor is triggered so that a light is turned on for 60 seconds and then back off, don’t use a delay to achieve this. Instead, launch a macro to turn the light on and then either create a timed event for 60 seconds in the future to turn the light off or use the Wait command. This way other processing can continue while PowerHome is counting down to turn the light off.

This command is useful for keeping the event log a manageable size. Enter a formula resolving to the number of days you wish to keep in the log in the Send Keys field. A value of 1 in this field will erase all entries in the event and web log except for the entries dated from midnight forward of the current day. If you set this up to execute on a daily basis at 12:05 am and place a value of 2 in the Send Keys field, then you will only have entries for the previous day and all 5 minutes worth of the current day.

This command should be used with GREAT CARE and only by those who are very familiar with SQL database programming. This command allows you to directly manipulate almost any table within the PowerHome database. Enter a formula that evaluates to a SQL statement (update, insert, delete) into the Send Keys field. The SQL statement is executed and any changes are commited immediately. There is NO chance of a rollback in case of errors.

This command allows you to display information to someone who is monitoring the PowerHome program. You do not have to worry about using message boxes and hanging the system until you respond. A message box can optionally timeout by setting the [TIMEOUT] system variable to the number of seconds you wish the box to appear. If you set this value to zero, then the box will never timeout, however the system will still not be hung as the macro which launched the message box is terminated so other items in the execution queue will continue to be executed. Once the message box is closed, the macro that spawned the box will resume where it left off. Select whether or not you want the text displayed in the message box to also be sent to the Text to Speech engine. Select the buttons to appear on the message box in the value field. Next, enter a formula evaluating to the message you wish displayed (and optionally sent to TTS) in the Send Keys field. When the message box is acknowledged or times out, the system variable [MBRET] will contain the number of the button that was pressed or a zero in the case of a timeout. In the case of a button type of YESNOCANCEL, pressing the Yes button will place a 1 in the [MBRET] variable. Pressing No will return a 2, and pressing Cancel will return a 3 and a timeout will return a zero. The message box will have the window title the same as the macro ID.

This command operates the same as the Message Box command in respect to time outs and the execution queue continuing to process events while a box is open. This box will obtain input from the user. You can enter a formula that evaluates to a brief message that will appear in the input box (and optionally sent to TTS) in the Send Keys field. Once the input box is opened, the user may enter up to 256 characters in the input field. Input is accepted and the box is closed once the user clicks OK. The user inputted text will then be available in the [INPUTRET] system variable. If any text is currently already in the [INPUTRET] variable when the input box is called, then this text will be pre-entered into the input field of the input box. Remember that system variables are reinitialized everytime PowerHome is started. If you want to have a default value in your input box, you should set the [INPUTRET] variable using the set system command prior to calling the input box command. The input box will have the window title the same as the macro ID.

The label command works in conjunction with the Goto Label command and allows you to label sections of your macros with any name you want so that you can later transfer control to this label without having to use the jump function and count the number of lines between your jumps. You enter your label in the Send Keys field. This is not a formula and no substitution of any kind is performed. What you type is what you get for a label so you would NOT use single or double quotes for the label string. When a label command is encountered in normal macro processing, it is merely skipped.

The goto label command allows you to transfer control to a label within the current macro. This can be easier than keeping track of the number of lines between statements like you have to do when using the jump command. It should be noted however that the jump command is more efficient than the Goto Label command but the difference will be negligible. You enter a formula that evaluates to the label that you want to transfer control to in the Send Keys field. Since this field is a formula, you can use a case statement or similar to transfer control to multiple locations. Keep in mind if you have a line labeled abc, when you jump to it with a Goto Label command, you must use “abc” in quotes so that the formula in Goto Label is evaluated as a string. If the label is a number, then you don’t have to place the number in quotes in the formula field of Goto Label. When a goto label command is encountered, execution continues at the line immediately following the matching label. If the label does not exist, control is just transferred to the line following the Goto Label command.

This command works in conjunction with the Destroy Select command and allows the user to directly query the PowerHome database on the fly. This command should only be used by individuals familiar with SQL programming and intimate with the structure of the PowerHome database. The PowerHome system includes 20 global database retrieval areas. You must select which of the 20 database retrieval areas your SQL Select command will retrieve to. If the database retrieval area is not initialized, it will automatically be created for you. If it already exists and has data, it will be overwritten with the new data. The database retrieval areas and its data utilize system memory and will persist until destroyed with a Destroy Select statement. There are 20 system variables associated with the database retrieval areas ([SQLROWS1] thru [SQLROWS20]) and contain the number of rows currently retrieved in the retrieval areas. There are also several formula functions (such as ph_getdata and ph_finddata) which allow you full manipulation of your retrieved data. When using this command you must select the data retrieval area number and then enter a formula that evaluates to a valid SQL select statement in the Send Keys field.

This command is used to return memory to the system when you are done with the data in a data retrieval area that was previously retrieved with a SQL Select command. Enter the data retrieval area that you wish to have destroyed.

This command will suspend execution of the current macro but is different from the Delay command in that it will NOT stop the execution queue from processing waiting commands. The macro is actually terminated but the System Variables [LOCAL1] thru [LOCAL10], [TEMP1] thru [TEMP10], and others are stored and a timer started. When the timer is up, the macro is reinserted into the execution queue and will resume processing at the statement following the Wait command. Enter a formula that evaluates to the number of seconds you would like to wait in the Send Keys field. Remember that the Delay command works in milliseconds, the Wait command works in seconds.

This command will create a user message event within the event log if the logging of user messages is enabled within the PowerHome preferences. Enter a formula that evaluates to the text of the user message within the Send Keys Field.

This command allows you to add a comment to your macro. You may place the text of your comment within the Send Keys Field. This is not a formula and will not be evaluated. Comment commands are simply skipped during macro execution.

This command allows you to have a formula entered in the Send Keys field evaluated. The results of the formula are discarded. In this formula you can use any of the defined formula functions. The formula can either be evaluated immediately or posted to the end of the execution queue.

This command is obsolete and is a holdover from the time when PowerHome did not have formula functions. This command is used to control a CD jukebox player via Infrared commands and is intended to move the player to a particular CD slot. This command expects that the IR commands to control CD player have already been defined in the IR section of PowerHome Explorer and the CD screen in the Setup section of PowerHome Explorer has been configured. The ID column is set to the ID of the defined IR device. The Send Keys field should contain the "offset" to the number 0 in the IR device for controlling the CD changer. Before calling this command, you must first set [LOCAL1] to the slot number you wish to be sent to the CD player. This command is easily replaced by using a formula containing the ph_irnumseq( ) function.

This command is obsolete and is a holdover from the time when PowerHome did not have formula functions. This command is used to control a CD jukebox player via Infrared commands and is intended to tell the player to load a particular CD track in the current slot. This command expects that the IR commands to control CD player have already been defined in the IR section of PowerHome Explorer and the CD screen in the Setup section of PowerHome Explorer has been configured. The ID column is set to the ID of the defined IR device. The Send Keys field should contain the "offset" to the number 0 in the IR device for controlling the CD changer. Before calling this command, you must first set [LOCAL1] to the track number you wish to be sent to the CD player. This command is easily replaced by using a formula containing the ph_irnumseq( ) function.

Another obsolete command related to the programming of Playlists into a CD jukebox changer. This command is used in conjunction with the Slot and Track commands to program a playlist defined in the Playlists section of PowerHome Explorer. Before calling this command, [LOCAL3] is expected to contain the ID of the Playlist to be programmed. When this command is first encountered, it queries the database for the Playlist ID in [LOCAL3] and loads the slot number for the first entry in [LOCAL1] and the track number in [LOCAL2]. Between the "Start Playlist Loop" command and the "End Playlist Loop" command is expected to be commands to "Slot" and "Track" to program the values in [LOCAL1] and [LOCAL2].

This command is the second half of the "Start Playlist Loop" command is obsolete. When this command is encountered, control is sent back to the "Start Playlist Loop" command and the next entry in the Playlist is retrieved with the Slot and Track values loaded into [LOCAL1] and [LOCAL2]. The macro will loop until the complete Playlist is programmed or until the maximum songs in a playlist value is reached.

This command allows you to prematurely end execution of the current macro and is useful for Jump and Goto Label commands to terminate a loop and the macro running it when user defined conditions are met. Equivalent to a Jump command to a line beyond the end of the macro.

This command allows you to execute another macro as an "extension" of the current macro. The entire System variable structure of the calling macro is available from within the SubMacro. Changes made to the System variables within the SubMacro will be reflected in the System variables of the calling macro. This is different from executing the "Macro" command where the new macro gets a copy of the current macro System variables minus the [LOCAL?] variables ([LOCAL1] thru [LOCAL10] are set to blank for the new macro). When the macro called by the "Macro" command terminates, control is transferred back to the calling macro which will have the same System variable values it had (including the [LOCAL?] values) before calling the new macro (changes made to System variables in the new macro will NOT be available to the calling macro). Unlike a macro executed using the "Macro" command, a "Wait" command will NOT cause control to be transferred back to the calling macro. For all intents and purposes, a SubMacro is treated as a part of the macro that is calling it.

This command allows you to execute a formula that has been predefined in the "Formulas" section of the PowerHome Explorer. All of the System variables in the current macro will be available to the formula called by this command. Select the ID of the predefined formula in the ID column.

Allows you to control a predefined Insteon device that has been created on the "Devices" tab of the Insteon Explorer.

Allows you to control a predefined Insteon group that has been declared in the "PLC/PLM Groups" tab of the Insteon Explorer.

This command allows you to control an Insteon group even if it hasnt been already defined in the Insteon Explorer. You'll enter the Insteon controller ID, the group number and the command you wish to be sent.

This command allows you to execute a Device Control string. These strings provide an easy way to control a multitude of devices that have already been defined within PowerHome. Doubleclick the Send Keys column or right-click the Send Keys column and select "Device Control" to open a window that allows you build these strings.