Function Builder
Index
Opening the Function Builder
The Function Builder helps you to quickly build function calls in your scripts. You can invoke the builder at the cursor position in your script or on a selected script fragment. If the latter, the selected fragment becomes the input to the function's first parameter.
To open the Function Builder dialog, click the Insert Function button and select function builder.
You can then click in the FUNCTION field and select the required function from the dropdown list.
Note
The list automatically filters when you type in the field. The dropdown list shown above contains only three functions because diff is typed in the field. When you first click in the field, the dropdown contains all available functions.
Function Builder dialog
When you select a function, the Function Builder dialog automatically changes to reflect your selection. Along with a short summary of what the function does, the Function Builder provides brief descriptions for each parameter. You can select parameter entries from the dropdown menus or type values (including ATL expressions) into the parameter fields.
The dialog includes a Preview control, allowing you to check that your function is behaving as expected before you save.
When the function is specified to your satisfaction, click INSERT to add it to your script. If you attempt to leave the Function Builder without inserting the function, you are asked to confirm that you do not want to save your work.
Note
The dialog provides very brief descriptions of the function and its parameters. If you require further guidance, click on the ? icon at the top of the dialog. This opens the reference documentation for the selected function.
Function Builder menu
To open the Function Builder dialog with a function preselected, click the Insert Function button and select a function from the menu.
The menu is divided into these submenus:
Note
Not every ATL function is supported in every project type. For example, certain data access functions don't work in "Describe Each Row" projects; therefore, these don't appear in the menu when your project is that type.
Tip
Studio also has Advanced functions that aren't supported by the Function Builder.
Specifying string parameters
When the Function Builder states that a parameter input should be a STRING, it is not necessary to enclose the string value in quotation marks. If you do, the builder will consider the quotation marks to be part of your input string.
For example, 'exceeded' is processed as a 10-character string starting and ending with a quotation mark — not as a 8-character string.
If you enter your string values correctly (without quotation marks), insert the function, and then view the function code in ATL View, you will see that the Function Builder adds the delimiting quotation marks for you.
You must type these quotation marks yourself when writing function calls in ATL — i.e. without the aid of the Function Builder.
Important
The above guidance also applies when entering a number in string form. To enter 123 as your STRING parameter, don’t type quotes around it in the Function Builder parameter field; just type 123.
Specifying list parameters
Some ATL functions take a list of items in one or more parameters. Typically, you enter a row or column variable (or, in JSON projects, a JSON path to an array); however, on occasion you might want to manually enter a list of items to test the function.
When entering a list manually in the Function Builder, ensure that the list is enclosed inside brackets and that each item is separated by commas. See the screenshot below.
Entering multiple column variables or aggregation functions
The groupByTable function allows you to input a list of column variables to the second and third parameters, and input a list of aggregation functions to the fourth parameter.
When doing this in the Function Builder, be careful to ensure the column variables and aggregation functions are separated by commas and enclosed inside brackets, as shown below.
The ATL code for the above is: [[groupByTable(WholeTable,(RegionColumn,TypeColumn),(SalesColumn,ProfitColumn),(sum(),mean()))]]
