ACL scripting basics
ACLScript is a command language that allows you to program and automate ACL commands. The structure and components of ACLScript are simple yet powerful.
If you are completely new to scripting, consider visiting the ACL Academy for some basic training before jumping into this content. For courses on scripting and using ACL Analytics, visit accounts.aclgrc.com.
Every line in a script executes an ACLScript command and starts with the command name. A command is an instruction to execute an operation in ACL.
The command name is followed by one or more parameters that are specified as parameter_name parameter_value.
Depending on the command, some parameters are required and some are optional. You do not need to specify optional parameters. If they are omitted, the command executes without them. However, if you omit a required parameter, ACL uses the default value for that parameter.
Example using the CLASSIFY command
The following example shows the CLASSIFY command along with following parameters:
- ON – specifies which field of the table to classify on
- SUBTOTAL – specifies optional fields to subtotal in the output
- TO – specifies the table to write the results of the CLASSIFY command to
Notice how each parameter is followed by one or more parameter values:
Important command syntax notes
- the first word in a script line must be a command name
- for most commands, the order of parameters that follow the command name does not matter
- most commands require that you open the target table before executing the command, precede these commands with OPEN table_name
Like any scripting language, you can add comments in ACLScript With the COMMENT keyword. Use comments to make your code easier to understand and to communicate with anyone who may try to read, use, or understand your script. ACLScript supports two types of comments:
- single line comments all text following COMMENT is ignored until the end of the line is reached
- multiple line comment blocks begin with COMMENT and each subsequent line is ignored until the END keyword, or a blank line, is reached
For more information and examples, see Comments.
ACLScript supports four basic data types:
- logical the simplest data type. Logical data expresses a truth value of either true or false
- numeric contain digits from 0 to 9 and, optionally, a negative sign and a decimal point
- character a series of one or more characters
- datetime a date, datetime, or time value expressed in a supported format
Each data type is treated differently by ACL and can be used in different commands and functions. For more information about data types, see Data types.
An expression is any statement that has a value. The simplest form of expression is a literal such as 2 or "test", however expressions usually appear as calculations and can be as complex as any valid combination of operators, conditions, functions, and values that you can imagine:
((2 + (3 - 2)) * 2) > ROOT(9,0)
Expressions are typically used in ACL to populate computed fields or as input for conditional logic. For more information about expressions, see Expressions.
Functions are built-in routines that accept a given number of parameters and return a single value. Use functions to manipulate field contents and variables that are used in commands.
Functions do not modify field data, functions generate and return a new value based on a calculation or algorithm that uses field data or variables as input. Use the value the function returns as input for a command.
Functions start with the function name followed directly by an opening parenthesis, a comma-separated list of 0 or more values that are passed into the function as arguments, and a closing parenthesis.
The BETWEEN(value, min, max) function takes three arguments and returns true if the value falls within the range or false if it falls outside the range:
- value – the expression or field to test
- min – the minimum of the range
- max – the maximum of the range
BETWEEN(amount, 500, 5000)
For more information about functions, see Functions.
A variable is temporary storage location used to hold a value. Variables have an associated identifier that lets you reference and work with the value stored in your computer's memory.
ACLScript uses the ASSIGN command to create a variable and assign it a value at the same time:
ASSIGN v_age_in_years = 3
For simplicity you can omit the ASSIGN keyword, however ASSIGN is implicitly used and the same command runs:
v_age_in_years = 3
ACLScript does not support null values. All variables must have an associated value of one of the supported data types. The script interpreter evaluates the data type using the data format and qualifier you use to assign the value. For more information, see Data types.
Once a variable is created, you can reference it anywhere you reference field names or variables. You can also reassign it a new value using the ASSIGN command.
EXTRACT RECORD TO 'result.fil' IF age > v_age_in_years v_age_in_years = 5
You can also use string interpolation, or variable substitution, to include a variable in a string literal by wrapping the variable name in % characters. When ACL encounters the substituted variable, it replaces the placeholder with its corresponding value:
ASSIGN v_table = erp_data OPEN %v_table%
For more information about variables, see Variables.
A control structure is a component of a script that decides which direction to take based on given parameters. ACLScript provides both conditional logic and looping structures.
ACLScript implements conditional logic as an IF command and as an optional parameter on many commands in the language.
You use the IF command to control if a command runs or not while you use the IF parameter to decide which records in a table a command runs against.
IF v_counter > 10 CLASSIFY ON customer_no
CLASSIFY ON customer_no IF state = 'NY'
The LOOP command provides the looping control structure in ACLScript. This command processes the statements inside the loop for as long as the control test expression evaluates to true.
For more information about control structures, see Control structures