ph_natlang

Argument	Description
as_cmd	String. The English command to be analyzed and interpreted
ai_type	Integer. This parameter controls how the command is analyzed against the PowerHome database. A number of options represented by numbers can be added together to achieve the desired combination of options to be analyzed. This value will end up being a number between 1 and 1023. The individual options (represented by binary values) and their associated functions are detailed in the Usage section below
ai_tables	Integer. This parameter controls which tables and views are used in the analysis of the command. This will be a number from 0 to 15 and is derived by adding binary identfiers representing the tables and views that will be used to create the dynamic SQL
ai_execute	Integer. This parameter specifies whether or not to execute the command in as_cmd for the top ranking match. A value of -1 means to never execute. A value of 0 means to always execute. Any other positive number represents the minimum "rank" value the top ranked match must meet in order to execute the command. Whether a command is executed or not depends upon both this parameter and the ai_certainty parameter
ai_certainty	Integer. This parameter specifies whether or not to execute the command based upon the difference in rank between the top and second ranked matches. A value of 0 means to always execute if the ai_execute parameter conditions are met. Any other positive values indicates the minimum difference in rank between the top and second matches before executing. It is a combination of this parameter and the ai_execute parameter that determines if a command is actually executed
ai_fullresult	Integer. Specifies how to display the internal results of the match analysis. A value of 0 means to discard the results. A value of 1 means to place the results in the clipboard. A value of 2 will open a results window similar to a SQL Query and display the results. A value of 3 will place the results in the clipboard AND open a results window
ai_rettype	Integer. Specifies the string data to be returned by the function. A value of 0 returns the top ranked match details. A value of 1 returns the full results (the same contents that would be sent to the clipboard if ai_fullresult = 1). A value of 2 returns the answer/results of the execution of the top ranked match if it is executed (this is the value most likely to be used in normal usage)
ai_vars	Integer. Specifies a starting system variable to return the function "return value" and details of the top ranked match. Use 0 to not update a system variable. Use 1 to 10 for [LOCAL1] thru [LOCAL10]. Use 101 thru 110 for [TEMP1] thru [TEMP10]. Use 1001 thru 1100 for [GLOBAL1] thru [GLOBAL100]. A total of up to 6 data items will be returned. If ai_vars = 2 then the first data item will be in [LOCAL2], the second data item in [LOCAL3], etc. The data items returned (in order) are the numeric function return value (see Return value below for the possible return values), the top rank match "Rank", "Type", "ID", "Keynum", and "Description"

String. Returns a number of different results/data dependent upon the value in the ai_rettype parameter. In normal usage, the ai_rettype parameter will by 2 and the function will return the results or answer of the execution of the top ranked match if the execution actually occurs (determined by the ai_execute and ai_certainty parameters). An ai_rettype of 0 will return the function "return value" followed by the following top ranked match details all separated by a tab (~t) character: rank, type, id, keynum, description. An ai_rettype of 1 will return tab separated lines of the results of the match analysis. The "return value" for the function which will be returned as the first piece of data if the ai_rettype = 0 will be a number representing the results of the analysis. The possible return values are:

0 - Success
1 - Error: as_cmd is blank
2 - Error: ai_type out of range
3 - Error: ai_tables out of range
4 - Error: dynamic SQL generation failed
5 - Error: dynamic SQL create failed
6 - Error: no data found for dynamic SQL
7 - Error: below minimum rank level in ai_execute
8 - Error: below minimum certainty level (difference in rank between the top and second matches) in ai_certainty

Use this function to pass natural language commands to PowerHome for execution and the return of the results. This natural language can be generated from an email, webpage, text, smart assistant, etc. The function works by searching for keywords in the command such as play, run, execute, do, what, give, set, etc. to determine the desired control action and then searches the PowerHome database for the closest matching entity to execute the desired action upon. The function is capable of returning various sets of data through the return value of the function, data placed in the clipboard, and data returned into system variables.

The function will return a string of data based upon the value in the ai_rettype parameter. See the Return Value section above for details on the data that can appear in this string. The function also provides two other mechanisms for returning data that can be processed by the user. If the ai_fullresults parameter is 1, 2, or 3, you'll get access to the full analysis results of the database matching in either the clipboard, a separate window, or both. If the ai_vars parameter specifies an appropriate starting system variable number, then you will get the numeric function return result as well as details on the top ranked match assuming the function return result is not an error. In normal usage, the ai_fullresult parameter will be set to 0 and the ai_rettype parameter will be set to 2. In this case, you'll want to set the ai_vars value to a valid system variable number in order to get the results of the analysis (with ai_rettype = 2, the function return value will be the result of the execution of the command and not the results of the analysis). When debugging to determine the best settings for the parameters based upon how you've configured PowerHome and your usage patterns, you'll probably set the ai_execute parameter to -1 (you don't want to execute during testing) and the ai_fullresults to 2 so you can easily see the analysis results and how your tweaking of parameters such as ai_type and ai_tables have affected the outcome.

The function builds dynamic SQL to execute upon the database based upon the individual words in the command, the SQL options specified in ai_type, and the tables / views specified in the ai_tables parameters. Depending upon the options chosen in ai_types and how many of those options result in a match, the sum of the matches will become the "rank" for the match. The higher the "rank" value, the more options were matched and a higher certainty that the command was properly interpreted. Each match is returned in a table sorted by rank from highest to lowest. If you configure the function such to return the "full results", you will be able to see and analyze this data. The match with the highest rank can be executed if the criteria for the ai_execute and ai_certainty parameters are met. The ai_execute parameter can define a minimum "rank" level that the top match must meet before an execution can occur. The ai_certainty parameter can control by how much the top match rank and the second match rank must differ before an execution can occur. If the top matched rank is 400 and the second rank is 290 (a difference of 110) then you can be fairly certain that the top match is definitely what you want to execute. If the top rank is 400 and the second rank is 398 (a difference of 2), then you may want not want to execute the command because it is so close in matching to the second ranked match.

The binary values to be added together for the desired options in the ai_type parameter are detailed below:

Value	Description
1	Perform a DB similar search for each command word without spaces in the "ID" field
2	Perform a DB similar search for each command word with spaces in the "Description" field
4	Perform a DB similar search for each command word without spaces in the "Description" field
8	Perform a DB similar search for each command word with spaces in the "ID" field
16	Perform a DB similar search for full buildup of all command words without spaces in "ID" field
32	Perform a DB similar search for full buildup of all command words with spaces in "Description" field
64	Perform a DB similar search for full buildup of all command words without spaces in "Description" field
128	Perform a DB similar search for full buildup of all command words with spaces in "ID" field
256	Searches for the existance of each word in the command in the "ID" field
512	Searches for the existance of each word in the command in the "Description" field

The binary values to be added together for the desired tables / views to perform the database search on in the ai_tables parameter are detailed below:

Value	Description
0	If the ai_tables parameter is 0, then PowerHome will automatically determine the tables/views to search based upon the command action words
1	Include the Device Status view in the search. This would include any type of device that appears on the Device Status screen
2	Include the Macro Header table in the search
4	Include the IR table in the search
8	Include the Global Variables table in the search