** SIMPLE USE
ph_postexequeue(2,0,"KITCHEN MACRO")
The above example will enqueue the KITCHEN MACRO macro to the very top of
the execution queue.
** COMPLEX USE WITH TRIGGERS
| Argument | Description |
| ai_priority | Integer (Optional). Determines where in the queue the formula is to be placed. See usage below. If this parameter is omitted, a value of 0 will be used |
| ai_type | Integer (Optional). The type of formula to place in the execution queue. Use 0 for macros, 1 for sendkeys, 2 for raw formulas, and 3 for Device control strings. Any other value will cause the function to return a value of 2. If this parameter is omitted, a value of 2 (raw formula) will be used |
| as_formula | String. Contains either a macro ID, sendkeys string, raw formula, or a device control string (determined by the ai_type parameter). |
| 0 | A type parameter of 0 will insert the process into the queue using standard priority. This is a first in, first out queue and is the normal mechanism for putting items in the queue. |
| 1 | A type parameter of 1 will insert the process into the priority queue. |
| 2 | A type parameter of 2 will insert the process at the very top of the queue. |
The execution queue is a single queue with 3 logical sections. Enqueued
processes are executed starting at the top of the queue. The priority
parameter determines where in the queue the process is inserted. A Top
priority will always go to the top of the queue. This ensures that the
process will execute before any priority or normal queue items. However,
if a top queue item has not yet executed and another Top priority
process is enqueued, the previous Top queue process will now be second
after the most recent Top queue process. Inserting as a Top priority
ALWAYS inserts the process at the top of the queue. A priority queue
item (type parameter = 1) will be inserted after anyTop processes and
after any existing priority processes. It will be inserted before any
normal priority processes. A normal process will always go to the end of
the queue.
This function is useful to insert priority execution items ahead of any
normally queued items.
In order to get items in the queue ahead of other items, this function typically needs to be executed in the Boolean field of either a trigger or timed event (but it doesnt have to be. It can be executed anywhere any other function can be executed). The ph_postexequeue function is just a function and doesnt "change" any PowerHome processing rules.
In normal operation, all processes (formulas, macros, etc) are added to the end of the execution queue unless the new formula, macro, etc. is executed from within a currently running formula or macro. The execution queue is serviced in the background and is FIFO (First In, First Out) and the queued processes are executed. When a web request is processed, or a timed event is fired, or a trigger is triggered, etc. the action is always placed into the execution queue. The caveat however is that timed events and triggers also have the boolean field.
The boolean formula field never goes to the execution queue and is executed immediately. It was originally intended to never perform any actual "actions" because these could corrupt the processing of events in an orderly fashion and was merely a mechanism for the user to define additional criteria for whether the action of the trigger/timed event should actually be added to the queue.
In order to get certain actions ahead of other queued actions, the ph_postexequeue() function was created.
Instead of putting items in the queue at the end, it can put it to the top or ahead of others. This works without corrupting the execution queue processing because the formula that is passed along with the ph_postexequeue function is executed from the queue (and not from the boolean)...just ahead of other queued items but still via the queue. The thing to remember is that the ph_postexequeue function is just a function like any other. It performs its intended purpose and returns a value (integer in this case). It doesnt interrupt or change any other processing.
The other thing to keep in mind is that the boolean formula is just a formula but PowerHome is expecting it to return an integer or a true/false. Any other value would confuse PowerHome. The boolean formula is never queued and always executed immediately when the timed event or trigger is fired. No direct actions should be performed in the boolean field (such as a ph_insteon function or similar...simple math or comparisons are acceptable as well as this function).
If you want to get an item ahead of other items in the queue, your only option is to do it in a formula (using the ph_postexequeue function) that is executed immediately (that is not itself queued...the boolean field). If you intend to have your Timed Event or Trigger perform its desired action via a ph_postexequeue function in the boolean field, there is really no need for the action field to be enqueued (unless you also want an additional action that would go to the end of the queue). If the action is not needed, you can set the action type to Raw Formula and set the Formula field to 0 (the formula field MUST still be a valid formula and a 0 is about as simple as it gets).
If you're performing your actual action via ph_postexequeue in the boolean field, you can ensure that your action field NEVER executes by making sure that the boolean field ultimately evaluates to a 0 (zero) or false value. This can be easily accomplished by multiplying your ph_postexequeue function by 0.
** SIMPLE USE
ph_postexequeue(2,0,"KITCHEN MACRO")
The above example will enqueue the KITCHEN MACRO macro to the very top of
the execution queue.
** COMPLEX USE WITH TRIGGERS