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.

Note

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.

Commands

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.

Tip

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

Comments

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.

Data types

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.

Expressions

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

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.

Note

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.

Example

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.

Variables

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

Note

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.

Using variables

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.

Control structures

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.

Conditional logic

ACLScript implements conditional logic as an IF command and as an optional parameter on many commands in the language.

Tip

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 command

IF v_counter > 10 CLASSIFY ON customer_no

IF parameter

CLASSIFY ON customer_no IF state = 'NY'

Looping

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

[ Back to top ]

(C) ACL Services Ltd. All Rights Reserved. Thursday, October 4, 2018