Formulas
Formulas are where most of
your automation power is derived. Formulas are used throughout PowerHome
and are an essential component of Macros,
Triggers, Timed Events, Analog IO device, PSP (PowerHome Server Pages),
and others. Formulas can return text, numeric, date, time, and datetime values.
Before a formula is evaluated, variable substitution is performed upon
it. Once variable substitution is complete, the formula is passed
to the formula evaluator. The results of the formula are then passed
back. Formulas themselves can contain a number of functions. You can
achieve most PowerHome tasks by calling a series of formula functions. The
available Formula Functions are documented within the Formulas section.
The key thing to remember with
formulas is that it's basically a math equation. You can add, subtract,
multiply, and divide numerics ( + - / * ). You can also add
strings. Functions
can return either numeric, string, date, time, or datetime
values. You can use parenthesis to force a particular order of evaluation. Strings
can be delimited by either single quotes or double quotes.
If you need an embedded double quote, delimit your string with
single quotes and vice versa. Within a formula, all operands
must be of the same type. It is best to separate operators
from operands/function with a space character. When using subtraction (the -
sign), you MUST have a space precede the - sign or sometimes your
formula can fail.
The simplest formula would be just the number one like this:
1
From there, you can do some simple math such as 1 + 1. Another
formula is just a simple string. You can have:
"Test"
and then add strings together
to get a combined string:
"This is" + char(32) + "a test"
The char() function returns a string so were
adding 3 string operands.
A formula can also evaluate to a boolean
(true/false) value so this is also a valid formula:
2 < 3
This will evaluate to
true.
One thing you cant do is assignment (like you can in most
programming languages). You must use either a function or a macro command
to perform an assignment. If you have a global variable with an ID of
TEST, you can't
do this:
TEST = "This is" + char(32) + "a test"
To do the assignment, you would have to do
this:
ph_setglobal_s("TEST","This is" + char(32)
+ "a test")
In addtion to the standard
operators ( + - / * ) all of the standard comparison
operators are also available: <, >, <=
, >= , <>, etc.
When
creating formulas, it is a good idea to always "check" them for proper
functionality.
If a formula has a
syntax error, it will return the following string: "-=*SYNTAX ERROR*=-". It
should be noted that a particular formula evaluation may result in a syntax
error even though the function is syntactically correct. This often happens when
using Variable Substitution. Consider the following formula:
[LOCAL1] * [LOCAL2]
If LOCAL1 and LOCAL2 do
NOT contain numeric values, you will get a syntax error. If both LOCAL1 and
LOCAL2 contain numbers, then you get a successful return. This is why it is
recommended to instead use the ph_getvar_?( ) functions as these functions will
ALWAYS return the correct datatype. Consider the equivalent formula below:
ph_getvar_n(1,1) *
ph_getvar_n(1,2)
In the above formula, you will ALWAYS get
a valid value returned no matter what data might actually be in the LOCAL1 and LOCAL2
variables.