Site Tools

한국어

comfilehmi:hmieditor_function:index

System Functions

The functions listed here can be used in expressions in Comfile Studio.

Math Functions

• `asin(value)` : Arc-Sine
• `acos(value)` : Arc-Cosine
• `atan(value)` : Arc-Tangent
• `avg(x,y,z,…)` : Returns the average of all values in the argument list
• `ceil(value)` : Rounds number up to the nearest integer value.
• `cos(value)` : Cosine
• `cosh(value)` : Hyperbolic Cosine
• `exp(value)` : e raised to a given exponent
• `fabs(value)` : absolute value
• `fmod(x,y)` : the remainder of x divided by y.
• `floor(value)` : Rounds number down to the nearest integer value.
• `log(value)` : Natural Logarithm
• `log10(value)` : Log base 10
• `max(x,y,z,…)` : Returns the largest value from the argument list
• `min(x,y,z,…)` : Returns the smallest value from the argument list
• `max_index(x,y,z,…)` : Returns the index of the largest value in the argument list
• `min_index(x,y,z,…)` : Returns the index of the smallest value in the argument list
• `pow(x,y)` : x raised to the power y
• `sin(value)` : Sine
• `sinh(value)` : Hyperbolic Sine
• `sqrt(value)` : square root
• `stdev(x,y,z,…)` : Returns the standard deviation of all values in the argument list
• `tan(value)` : Tangent
• `tanh(value)` : Hyperbolic Tangent

Bit Manipulation Functions

• `bit(subject, bitIndex)` : Returns the value of the bit at `bitIndex` in `subject`. `subject` can be an expression or a variable name, but if it is a variable name, it must must be enclosed in double quotes. `bitIndex` can be an integer from 0 through 31.
```bitValue = bit("a", 3)
bitValue = bit(a + 3, 1)```
• `set_bit("variable_name", bitIndex, value = 1)` : Sets the value of the bit at `bitIndex` in `variable_name` to `value`. `variable_name` is a variable name that must be enclosed in double quotes. `bitIndex` can be an integer from 0 through 31. `value` is optional and defaults to 1.
`set_bit("a", 3, 1)`
• `toggle_bit("variable_name", bitIndex, value)` : Toggles the value of the bit at `bitIndex` in `variable_name`. `variable_name` is a variable name that must be enclosed in double quotes. `bitIndex` can be an integer from 0 through 31.
`toggle_bit("a", 3)`

String Functions

• `find_text(string_to_search, string_to_find)` : Returns the character index of `string_to_find` in `string_to_search`. Returns `-1` if not found.
• `num_to_text_int(number)` : Prints a number as a base 10 integer character string.
• `num_to_text_int(number, digits)` : Prints a number as a base 10 integer character string with leading 0's. Ex: `num_to_text_int(3.14, 4)` prints “0003”.
• `num_to_text_hex(number)` : Prints a number as a base 16 integer character string.
• `num_to_text_hex(number, digits)` : Prints a number as a base 16 integer character string with leading 0's
• `text_hex_to_num(hexadecimal_string)` : Returns the binary number corresponding to `hexadecimal_string`. For example, if `hexadecimal_string` is “FF”, 255 will be returned.
• `num_to_text_dec(number, fractional digits)` : Prints a number as a base 10 character string with a given number of fractional digits. Ex: `num_to_text_dec(3.14159, 4)` = “3.1416”
• `text_starts_with(target_string, prefix, ignore_case)`: Returns `1` if `target_string` begins with `prefix`. Returns `0` otherwise. If `ignore_case` is non-zero it will do a case-insensitive search. `ignore_case` defaults to `0`.
```text_starts_with("BREAKFAST", "break")    // Returns 0
text_starts_with("BREAKFAST", "BREAK")    // Returns 1
text_starts_with("BREAKFAST", "break", 1) // Returns 1
text_starts_with("BREAKFAST", "break", 0) // Returns 0```
• `text_ends_with(target_string, suffice, ignore_case)`: Returns `1` if `target_string` ends with `suffix`. Returns `0` otherwise. If `ignore_case` is non-zero it will do a case-insensitive search. `ignore_case` defaults to `0`.
```text_ends_with("BREAKFAST", "fast")    // Returns 0
text_ends_with("BREAKFAST", "FAST")    // Returns 1
text_ends_with("BREAKFAST", "fast", 1) // Returns 1
text_ends_with("BREAKFAST", "fast", 0) // Returns 0```
• `text_to_num(string)` : Parses a character string in base 10.
• `replace_text(string_to_search, string_to_find, replacement)` : Replaces any occurrence of `string_to_find` in `string_to_search` with `replacement`. String variable names must be enclosed in double quotes with the `\$` prefix omitted.
`\$var = "I ate lunch."; Replace_text("var", "lunch", "dinner")`

Text Memory Functions

Text memory is a specific string memory area in the HMI runtime. The contents are lost when the panel PC is powered off. It is similar to internal memory except it stores strings. The default capacity of the text memory is 1024 strings (0 ~ 1023) and each string is default initialized to an empty string. The capacity can be expanded with the `set_tmem_size` function.

• `set_tmem_size(maximum possible number of strings)`: Sets the maximum capacity of text memory up to 100,000 strings.
• `tmem(address)`: Reads a value from a specific address (i.e. index) in text memory.
• `set_tmem(address, "string value")`: Writes a string at a specific address (i.e. index) in text memory. You can increase the parameters by concatenating them with commas to record the string consecutively. Example: `set_tmem(10,"one","two","three")` will set strings at address 10, 11, and 12 respectively.
• `text_split("string","separator", start address to contain the result, maximum number of results)`: Divides the string with a specific separator and writes the result to text memory. The maximum number of outputs is optional. Example: If `text_split("a#b#c#d"),"#",10,3)` is executed, “a” will be written to address 10, “b” will be written to address 11, and “c” will be written tot address 12.
• `text_merge(start address, number, "separator")`: Concatenates strings in text memory joined by a separator and returns the result as a single string. Example: If `text_merge(10,3,"-")` is executed when “aa” is at address 10, “b” is at address 11, and 'c' is at address 12, the string “aa-bc” is returned.

Communication Functions

The following functions can be used to detect communication problems between the ComfileHMI and the PLC.

• `timeout_result()` : Returns 1 if the last communication resulted in a timeout waiting for a response. Return 0 if no timeout occurred.
• `timeout_count()` : Returns the total number of times a communication timeout occurred since the project was executed.
• `reset_timeout_count()` : Resets the timeout count returned from `timeout_count()` to 0.

Internal Memory Functions

The following functions are used to read from and write to internal memory.

• `set_mem(index, value)` : Writes `value` to internal memory at `index`.
• `mem(index)` : Reads the value current stored in internal memory at `index`.
• `set_mem(index, value1, value2, …, valueN)`

File Functions

• `base64_to_file(base64_string, file_path, append)` : Decodes `base64_string` and saves it to the the file specified by `file_path`. If `append` is `1` the data is appended to the end of the file. If `append` is `0`, the file is overwritten.
`base64_to_file(\$base64_data, "storage card\myfile.bin", 1)`
• `delete_file(file_path)`: Deletes the file from the file system.
• `delete_folder(folder_path)` : Deletes the folder and all containing subfolders from the file system.
`delete_folder("storage card\folder1")`
• `ensure_folder_exist(folder_path)` : Ensures a folder exists. The folder, and any required parent folders, are created if it does not exist.
`ensure_folder_exist("storage card\folder1\folder2")`
• `file_exists(file_path)`: Returns `1` if `file_path` exists, `0` if not.
`file_exists("storage card\myfile.txt") == 1`
• `file_to_base64(file_path)`: Returns the contents of the file specified by `file_path` as a base 64 string.
`\$base64_data=file_to_base64(“storage card\data.bin")`
• `file_to_text(file_path)`: Returns the contents of `file_path` as a string. If the file's contents have the byte-order mark `FF FE`, the contents of the file will be Unicode encoded.
`\$content = file_to_text("storage card\myfile.txt")`
• `text_to_file(string, file_path)`: Stores string variable `string` to the file `file_path`.
`text_to_file(\$content, "storage card\myfile.txt")`
• `file_size(file_path)`: Returns the size of the given file in bytes.
• `rename_file(existing_file_path, new_file_path)`: Renames `existing_file_path` to `new_file_path`.

Remote Script Functions

• `write_byte(value)`: Writes a single byte of binary data to the response of a remote script. Returns 1 on success and 0 on failure.
• `write_word(value)`: Writes 2 bytes of binary data in little endian to the response of a remote script. Returns 1 on success and 0 on failure.
• `write_dword(value)`: Writes 4 bytes of binary data in little endian to the response of a remote script. Returns 1 on success and 0 on failure.
• `write_text(string)`: Writes a UTF-8 string to the response of a remote script. Returns 1 on success and 0 on failure.
• `write_file_contents(file path)`: Writes at most 1MB of binary data from a file to the response of a remote script. Returns 1 on success and 0 on failure.

Trend Graph Functions

• `trendgraph_restart(trendgraph_alias)` : Clears the trend graph identified by `trendgraph_alias` and begins sampling.
`trendgraph_restart("my_graph")`
• `trendgraph_stop(trendgraph_alias, clear = 0)` : Stops the trend graph identified by `trendgraph_alias` and optionally clears the trend graph according to the `clear` flag (default 0).
```trendgraph_stop("my_graph")
trendgraph_stop("my_graph", 1)```

Type Conversion Functions

Functions to convert between data types.

• `bytes_to_float("variable1", "variable2", "variable3", "variable4")` : Assembles a floating point value from the provided byte variables. `variable1` is the least significant byte and `variable4` is the most significant byte. `variable`s are case-sensitive and must be enclosed in double quotes. Example: `float_to_bytes(3.14, "a", "b", "c", "d");result = bytes_to_float("a", "b", "c", "d")``result` will contain the value `3.14`.
• `float_to_bytes(floatValue, "variable1", "variable2", "variable3", "variable4")` : Decomposes a floating point value into its composed bytes. Afterward the bytes can be manipulated in various ways to, for example, change the byte order and store the values in addressable internal memory. `variable1` is the least significant byte and `variable4` is the most significant byte. `variable`s are case-sensitive and must be enclosed in double quotes.

Conditional Branching Functions

• `select_if(conditional_expression, Value1, Value2)`: Returns `value1` if `conditional_expression` is true, or `value2` if `conditional_expression` is false.
• `select_case (default_value, conditional_expression_1, value_1, conditional_expression_2, value_2, conditional_expression_3, value_3, …)`: Arguments are evaluated sequentially. If `conditional_expression_1` is true, `value_1` is returned. Else, if `conditional_expression_2` is true, `value_2` is returned. Else, if `conditional_expression_3` is true, `value_3` is returned, etc. If none of the conditional expressions are satisfied, `default_value` is returned. `value_{index}` arguments may can be strings, but in that case, they must all be strings.
(Example 1) `select_case (1000, a>5, 100, \$b==” APPLE”, 200)``100` is returned if `a` is greater than 5, `200` is returned if the value of the internal string variable `\$b` is `“APPLE”`, and 1000 is returned if neither case is true.
(Example 2) `select_case (“NORMAL”, temp>100, ”HOT”, temp<0, ”ICE”)` ⇒ If `temp` is greater than 100, `“HOT”` is returned, and if `temp` is less than 0, `“ICE”` is returned. If neither condition is true `“NORMAL”` is returned.
• `select_by_key(default_value, key_expression, key_1, value_1, key_2, value_2, key_3, value_3, …)` If `key_expression` is equal to 2, `value_2` is returned, if `key_expression` is equal to `key_3`, `value_3` is returned, etc. (The return value, `default_value`, and `value_{index}` can be strings, but in that case they must all be strings.
(Example 1) `select_by_key(-1,a+b,10,100, 20,200, 30,300)` ⇒ If `a+b` is 10 `100` is returned, if it is 20 200 is returned, if it is 30 300 is returned, otherwise -1 is returned.
(Example 2) `select_by_key(0, \$a+\$b,”ONE”,1 ,”TWO”,2 , “THREE”,3)` ⇒ If `\$a+\$b` is `“ONE”` 1 is returned, if `“TWO”` 2 is returned, if `“THREE”` 3 is returned, otherwise 0 is returned.
(Example 3) `\$a=select_by_key(“NOTHING”, a+b,1,”ONE” ,2,”TWO”, 3,“THREE”)` ⇒ If `a+b` is 1 `“ONE”` is returned, if it is 2 `“TWO”` is returned, if it is 3 `“THREE”` is returned , otherwise `“NOTHING”` is returned.
• `select_by_index(default_value, index_expression, start_index, value_1, value_2, value_3, …)` If `index expression` evaluates to the `start index` `value_1` is returned, if `index_expression` evaluates to `start index + 1` value 2 is returned, if `index_expression` evaluates to `start_index + 2` `value_2` is returned, etc. Otherwise, `default_value` is returned. (The return value, `default_value`, `value_{index}` can be strings, but in that case, they must all be strings)
(Example 1) `var = select_by_index(-1,a,5,100,200,300)` ⇒ If `a` is 5 100 is returned, if 6 200 is returned, and if 7 300 is returned. Otherwise -1 is returned.
(Example 2) `\$result = select_by_index(“NOTHING”,a,5,”A”,”B”,”C”)`⇒ If `a` is 5 `“A”` is returned, if `a` is 6 `“B”` is returned, If `a` is 7, `“C”` is returned, otherwise `“NOTHING”` is returned.

System Functions

Functions associated with the system.

• `action_group_repeat_index()` : Retrieves the number of times a user event was executed.
• `backlight_state()`: Returns whether or not the LCD backlight is on. `1` for on, `0` for off.
• `beep()`: Causes the panel PC to emit an audible beep sound.
• `bitwise_not(value)`: Returns the binary complement of `value`.
• `change_screen(screen_number)`: Transitions to the screen identified by `screen_number`.
• `cpu_usage()` : Returns the current CPU utilization as a percentage.
• `enable_modbus_batching(enable = 1)`: Enables or disables the Modbus optimization feature that batches adjacent Modbus addresses into a single Modbus query. The feature is enabled by default and is recommended for best performance, but there are limited situations where it may not be needed, such as a device that only supports processing one address per query. In such a case, `enable_modbus_batching(0)` can be used to make the Modbus queries compatible. Typically this function does not need to called. The `enable` argument is optional and defaults to `1`.
• `exit_project()`: Causes the current project to exit. This is the same effect as touching the upper right corner of the screen 5 times in quick succession.
• `enable_status_monitoring(enable = 1)`: Enables status monitoring messages to appear overlaid on the panel PC's screen. The `enable` argument is optional and defaults to `1`.
• `free_memory_bytes()`: Returns the amount of free system memory in bytes.
• `firmware_version()` : Retrieves the firmware version running on the panel PC. For example `273` corresponds to v2.73.
• `idle_seconds()` : Returns the number of seconds since the screen was last touched.
• `idle_minutes()` : Returns the number of minutes since the screen was last touched. Note: Calling `set_backlight_state(1)` will reinitialize the idle timer.
• `is_pc()`: Returns `1` if the project is currently running on a PC or `0` if not.
• `is_status_monitoring_enabled()`: Returns `1` if status monitoring is enabled or `0` if it is not enabled.
• `keypad_state()`: Returns whether the current keypad is opened. `1` if opened, `0` if not.
• `keypad_text()`: Returns the most recently entered keypad value as text. This function applies to both numeric and alpha-numeric keypads.
• `keypad_text_length()`: Returns the length of the string returned by `keypad_text()`.
• `keypad_value()`: Returns the most recently entered keypad value.
• `prev_screen_id()` : Returns the id of the screen that the current screen navigated from.
• `queries_per_sec()` : Returns the number of external device queries sent per second.
• `rand()` : returns a random number in the range of 0~32767 (0x7FFF)
• `reboot_system()` : Reboots the panel PC
• `restore_field_resource_color (resource number)`: Restores the color field resource to the original color set by the editor. Example) `restore_field_resource_color(3)`
• `scale(input, minimum input, maximum input, minimum output, maximum output)` : Scales `input` proportionally to (`maximum input` - `minimum input`) / (`maximum output` - `minimum output`).
• `screen_id()` : Returns the id of the current screen.
• `self_ip_addr()` - Returns the IP address of the panel PC as a string (for example: 192.68.0.50). Note: This function returns a null string in the simulator.
• `set_backlight_state(value)`: Sets the state of the LCD backlight on or off. If `value` is `1` the LCD backlight turns on, if `value` is `0` the LCD backlight is turns off.
• `set_data_processing_period(value)` : This function can be used to throttle CPU usage. If the CPU usage for a project is too high, the data processing period can be increased to throttle back the amount of resources that the HMI software dedicates to processing data. `value` is in units of milliseconds. This function can be useful when the CPU utilization increases due to an increase in the number of events or actions in the project. Typically, it would only be called once at the start of a project, but it can be called multiple times in a project to adjust the CPU utilization dynamically. Setting this value to 0ms will cause the data processing to run as fast as possible, but will also cause the highest CPU utilization. Values below 50ms should be used with caution. If the CPU utilization is approaching 100%, set this value to approximately 100ms, and the communication interval to 30ms as a reasonable starting point. Beginning with firmware v3.87, this value defaults to 50ms. In prior versions the default is 0ms.
• `set_field_resource_color(resource number,R,G,B)` : You can change the color of color field resource in real time. (Caution: Only predefined colors can be changed in the editor.) Ex) `set_field_resource_color(3,255,0,0)` Changes color resource number 3 to red.
• `set_modbus_word_write_always_multi(active_status_flag = 1)`: When `active_status_flag` is `1` or omitted, this function causes all Modbus register (16-bit word) writes to use function code 16 (Write Multiple Registers) even when the number of registers to write is 1.
• `set_viewer_browser_title(title)`: Sets the title of the web browser so the desired text appears in the title bar of the web browser when using the remote viewer from a web browser.
• `srand(seed)` : Sets the seed value for generating random numbers with the `rand()` function. It is recommended to call `srand(tick_count())` to seed the random number generator before using `rand()`.
• `start_action_group(action_group_name)`: Executes the action group identified by `action_group_name`.
• `status_monitoring_message()`: Returns the current status monitoring message.
• `tick_count()` : The number of milliseconds since the system was powered on. This is a 32-bit millisecond timer that will overflow every 49.7 days.
• `touch_duration()` : The number of milliseconds since the last time the screen was touched. If the screen has never been touched -1 is returned.
• `verify_developer_key(value)` : Using the ComfileHMI panel PC's runtime configuration screen, a unique key can be assigned to a individual device or group of devices. `verify_developer_key` can then be used at runtime within a project to test which device a project is running on and dynamically offer a different experience. The developer key cannot be read; one can only check if `value` matches the developer key assigned to the device. This function returns `1` if the `value` matches the developer key assigned to the device or `0` if it does not. This feature is only supported on PCs with a software licensing USB dongle.

In the Add Action –> Run Action Group properties, in the Advanced Options is the ability to pass a primary and secondary parameter to the actions (Add Action Parameter and Add Secondary Action Parameter respectively) .

The parameters can then be read from within the executing action using the following functions.

• `action_param` : Retrieves the primary parameter passed to an action.
• `sub_action_param` : Retrieves the secondary parameter passed to an action group.

RTC Functions

Functions with no argument.

• `year()` : The current year
• `month()` : The current month (1~12)
• `day()` : The day of the month
• `day_of_week()` : The day of the week (0~6), 0 = Sunday
• `hour()` : The hour of the day (0~23)
• `minute()` : The minute component of the current hour (0~59)
• `second()` : The second component of the current minute (0~59)
• `last_day_of_month(year, month)` : returns the last day of the given `month` for the given `year`

Functions that take 1 argument but return no value.

• `set_year(value)` : Sets the current year
• `set_month(value)` : Sets the current month (1~12)
• `set_day(value)` : Sets the day of the month
• `set_hour(value)` : Sets the hour of the day (0~23)
• `set_minute(value)` : Sets the minute component of the current hour (0~59)
• `set_second(value)` : Sets the second component of the current minute (0~59)

Web API Functions

The following functions be used in the `{expression}` part of the ComfileHMI's Web API.

• `vars_to_json(variable_names)` : Returns the values of the supplied `variable_names` in JSON format. `vars_to_json("a|b|\$c")`
• `mem_to_json(start_address, length, decimal_places = 6)` : Returns `length` values for the internal memory starting at `start_address` with `decimal_places` decimal places in JSON format. `mem_to_json(10,3)` will return values for internal memory at addresses 10, 11, and 12, with 6 decimal places.
• `filenames_to_json(directory_paths)`: Returns the list of files in JSON format from the directories specified by `directory_paths`. Multiple paths are separated by a `|`. `filenames_to_json("storage card\logs|storage card\data1")` returns the list of files in both the storage card\logs directory and the storage card\data1 directory.
• `dirnames_to_json(directory_path)` : Returns the list of subdirectories in JSON format from the directories specified by `directory_path`. The format of the response is the same as `filenames_to_json` but the result only includes subdirectories.
• `last_http_status_code()`: Returns the integer HTTP status code from the last received HTTP response.
• `last_json_result()` : Returns a success or fail result of the most recent query. `1` for success; `0` for failure. For example, if there is a syntax error in the query, the password does not match, or non-existent file path is submitted, 0 is returned.
• `last_json_error_code()` : Returns the numeric error code of the most recent query.
• `last_json_error_message()` : Returns the error message of the most recent query.