Using Functions
In the VTScada documentation, each function description includes information that you will need to use the function correctly. Look for the following:
Library Name
Not all functions are part of a library, but for those that are, you must scope to the library to use the function. Use the backslash operator before the library name and the dot operator before the function: System.Bevel(). The backslash scope operator means (roughly) "keep looking until you find this" while the dot scope operator means "look only within this specific library".
Returns
Used most often by functions that are subroutines. For many functions (example: GetTagHistory) data is returned through parameters that are passed by reference, rather than as a return value from the function.
Usage Rules - Script or Steady State
VTScada code runs in two modes: Script or Steady State. Many functions will work in only one mode. The "Usage" line in each function description tells you the mode where the function can be used.
Just because a function can be used in a given situation, does not mean that it should be. For example:
* Graphics functions work in steady state but it makes no sense to use one in a Calculation tag's expression. Optimized tag parameter expressions can use script-only functions, but you would never use the speak function here.
* MatchKeys will capture keystrokes only when used in a window or page, not in a service or Calculation tag.
Usage Examples. If you are writing...
General Expressions (Calc. tags)
If you are writing an expression for a Calculation tag, or anywhere that you have the option "Constant / Expression / Tag". Similarly for expressions for image and shape parameters when defined in the Idea Studio.
If the function is marked as "Script Only" then you cannot use it here.
If the function works in Steady State, then it will compile when used in a Calc tag expression, but it may or may not be useful there. For example, any of the functions that display a graphic object are not useful as a tag parameter.
Tag Parameter Expressions - Optimized
Only functions that can be used in Script may be used for optimized tag parameter expressions. These expressions are evaluated as the tag is initialized, either on start-up or whenever the tag or one of its parents is re-initialized. You cannot use Steady State-only functions in this situation.
Tag Parameter Expressions - Not Optimized
Only functions that can be used in both Script and Steady State may be used for non-optimized tag parameter expressions. These expressions are re-evaluated whenever any of the values referenced by the expression change. This means that the tag (and all of its child tags) will refresh each time a parameter value changes. (A somewhat heavy process of running code that assembles parameter values, and detects and reacts to parameter changes.) You cannot use Script-only functions in this situation.
Page Code, Services, Reports, etc.
These are full VTScada modules, declared in the application's AppRoot file. The full VTScada language and function list can be used.
Function Groups
A general classification of functions. Many belong to more than one group, and some are difficult to classify as a member of any. May be helpful when trying to find similar functions.
Related to
A list of similar or complementary functions.
The format line for each function description provides an example of how the function is to be used. Optional parameters are shown within square brackets in the format example. You may copy the format example for use within your code, replacing parameters with values as required.
System.Bevel(X1, Y1, X2, Y2 [,Title, AlignTitle, Color])
If your application predates version 11.2, the Settings.Startup property LocalScopeSyntax = 0 will prevent the use of the dot scope operator. If you are sure that you have not used a dot in any tag, widget, page or other name, you can set LocalScopeSyntax to 1 to allow this operator.
Note the use of commas to separate parameters when more than one is required. If a function does not require parameters, you may omit the parenthesis, although this is discouraged as a matter of practice. If a function has optional parameters, you can omit them from the call. If you need to provide only the nth optional parameter, use Invalid as a place-holder for each optional parameter you are not specifying, filling from left to right.
Most parameters to functions can be expressions including other functions. While there is no limit to how deeply these can be nested, you should avoid making your code difficult to follow by nesting too many levels deep.
Parameter Descriptions
A description of each parameter used by the function, identifying whether it is required, the data type, and relevant notes.
Will This Function Work in a Script Application?
Do not assume that any function will work in a script application until you have tested it.
Most development work is done within standard applications (those based on the VTScada layer), and the documentation is written from that point of view. Script applications do not have access to function libraries that were created explicitly for the VTScada layer.
It is possible to offer general guidelines for recognizing which functions are likely to work in a script application, but again, you should always test first. When testing the function in a script application, try first with the format as shown. If the test fails, try using the function with the prefix \Layer\.
- Functions that are part of the \System layer will work in script applications.
- Most, but not all, of the basic string handling, math, time, and date functions will work in a script application.
- If the format example begins with a backslash (\) and is not part of the \System layer, then it is likely that the function will not work in a script application, but test to be sure.
