0% found this document useful (0 votes)

37 views

Scripting Guide PDF PDF

Uploaded by

drazen

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

37 views

Scripting Guide PDF PDF

Uploaded by

drazen

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 934

ACL Scripting Reference

Version: 14.1
Published Wednesday, June 19, 2019

© 2019 ACL Services Ltd. dba Galvanize

Table of contents

Table of contents
Table of contents 3
Getting started 13
Analytics scripting basics 14
Comments 19
Data types 21
Expressions 22
Defining computed fields with expressions 24
Functions 26
Variables 28
Control structures 30
Grouping and looping 33
Top 30 Analytics functions 41
Commands 53
ACCEPT command 54
ACCESSDATA command 59
ACTIVATE command 66
AGE command 68
APPEND command 72
ASSIGN command 80
BENFORD command 83
CALCULATE command 87
CLASSIFY command 89
CLOSE command 94
CLUSTER command 96
COMMENT command 99
COUNT command 101
CREATE LAYOUT command 103
CROSSTAB command 105
CVSEVALUATE command 109
CVSPREPARE command 113

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 3 of 934
Table of contents

CVSSAMPLE command 117

DEFINE COLUMN command 120
DEFINE FIELD command 123
DEFINE FIELD . . . COMPUTED command 129
DEFINE RELATION command 135
DEFINE REPORT command 138
DEFINE TABLE DB command 139
DEFINE VIEW command 142
DELETE command 144
DIALOG command 148
DIRECTORY command 156
DISPLAY command 161
DO REPORT command 165
DO SCRIPT command 166
DUMP command 168
DUPLICATES command 170
ESCAPE command 175
EVALUATE command 177
EXECUTE command 181
EXPORT command 188
EXTRACT command 197
FIELDSHIFT command 202
FIND command 204
FUZZYDUP command 206
FUZZYJOIN command 211
GAPS command 217
GROUP command 221
HELP command 227
HISTOGRAM command 228
IF command 232
IMPORT ACCESS command 234
IMPORT DELIMITED command 236
IMPORT EXCEL command 244

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 4 of 934
Table of contents

IMPORT GRCPROJECT command 250

IMPORT GRCRESULTS command 255
IMPORT LAYOUT command 262
IMPORT MULTIDELIMITED command 264
IMPORT MULTIEXCEL command 271
IMPORT ODBC command 278
IMPORT PDF command 281
IMPORT PRINT command 290
IMPORT SAP command 298
IMPORT XBRL command 305
IMPORT XML command 309
INDEX command 313
JOIN command 316
LIST command 322
LOCATE command 325
LOOP command 328
MERGE command 330
NOTES command 334
NOTIFY command 336
OPEN command 339
OUTLIERS command 342
PASSWORD command 350
PAUSE command 352
PREDICT command 354
PRINT command 357
PROFILE command 359
QUIT command 361
RANDOM command 362
RCOMMAND command 365
REFRESH command 372
RENAME command 376
REPORT command 378
RETRIEVE command 382

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 5 of 934
Table of contents

SAMPLE command 384

SAVE command 392
SAVE LAYOUT command 394
SAVE LOG command 398
SAVE TABLELIST command 400
SAVE WORKSPACE command 402
SEEK command 403
SEQUENCE command 405
SET command 408
SIZE command 418
SORT command 422
STATISTICS command 427
STRATIFY command 431
SUMMARIZE command 436
TOP command 443
TOTAL command 444
TRAIN command 446
VERIFY command 451
Functions 454
ABS( ) function 455
AGE( ) function 456
ALLTRIM( ) function 461
ASCII( ) function 463
AT( ) function 465
BETWEEN( ) function 468
BINTOSTR( ) function 475
BIT( ) function 477
BLANKS( ) function 479
BYTE( ) function 481
CDOW( ) function 483
CHR( ) function 486
CLEAN( ) function 488
CMOY( ) function 490

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 6 of 934
Table of contents

COS( ) function 493

CTOD( ) function 495
CTODT( ) function 502
CTOT( ) function 508
CUMIPMT( ) function 513
CUMPRINC( ) function 515
DATE( ) function 517
DATETIME( ) function 521
DAY( ) function 525
DBYTE( ) function 528
DEC( ) function 530
DHEX( ) function 533
DICECOEFFICIENT( ) function 535
DIGIT( ) function 541
DOW( ) function 543
DTOU( ) function 546
EBCDIC( ) function 549
EFFECTIVE( ) function 551
EOMONTH( ) function 553
EXCLUDE( ) function 556
EXP( ) function 558
FILESIZE( ) function 560
FIND( ) function 562
FINDMULTI( ) function 566
FREQUENCY( ) function 570
FTYPE( ) function 572
FVANNUITY( ) function 575
FVLUMPSUM( ) function 578
FVSCHEDULE( ) function 581
GETOPTIONS( ) function 583
GOMONTH( ) function 585
HASH( ) function 588
HEX( ) function 593

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 7 of 934
Table of contents

HOUR( ) function 595

HTOU( ) function 597
INCLUDE( ) function 599
INSERT( ) function 601
INT( ) function 603
IPMT( ) function 604
ISBLANK( ) function 606
ISDEFINED( ) function 608
ISFUZZYDUP( ) function 610
LAST( ) function 614
LEADING( ) function 616
LENGTH( ) function 618
LEVDIST( ) function 620
LOG( ) function 624
LOWER( ) function 626
LTRIM( ) function 628
MAP( ) function 630
MASK( ) function 634
MATCH( ) function 636
MAXIMUM( ) function 643
MINIMUM( ) function 646
MINUTE( ) function 649
MOD( ) function 652
MONTH( ) function 654
NOMINAL( ) function 657
NORMDIST( ) function 659
NORMSINV( ) function 661
NOW( ) function 662
NPER( ) function 663
OCCURS( ) function 666
OFFSET( ) function 668
OMIT( ) function 670
PACKED( ) function 674

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 8 of 934
Table of contents

PI( ) function 676

PMT( ) function 678
PPMT( ) function 681
PROPER( ) function 683
PROPERTIES( ) function 685
PVANNUITY( ) function 689
PVLUMPSUM( ) function 692
PYDATE( ) function 695
PYDATETIME( ) function 697
PYLOGICAL( ) function 699
PYNUMERIC( ) function 701
PYSTRING( ) function 703
PYTIME( ) function 705
RAND( ) function 707
RATE( ) function 709
RDATE( ) function 712
RDATETIME( ) function 715
RECLEN( ) function 718
RECNO( ) function 719
RECOFFSET( ) function 721
REGEXFIND( ) function 723
REGEXREPLACE( ) function 730
REMOVE( ) function 738
REPEAT( ) function 741
REPLACE( ) function 743
REVERSE( ) function 746
RJUSTIFY( ) function 747
RLOGICAL( ) function 748
RNUMERIC( ) function 751
ROOT( ) function 754
ROUND( ) function 756
RSTRING( ) function 758
RTIME( ) function 761

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 9 of 934
Table of contents

SECOND( ) function 764

SHIFT( ) function 766
SIN( ) function 768
SOUNDEX( ) function 770
SOUNDSLIKE( ) function 774
SPLIT( ) function 777
STOD( ) function 781
STODT( ) function 785
STOT( ) function 789
STRING( ) function 793
SUBSTR( ) function 796
TAN( ) function 799
TEST( ) function 801
TIME( ) function 803
TODAY( ) function 808
TRANSFORM( ) function 809
TRIM( ) function 811
UNSIGNED( ) function 813
UPPER( ) function 815
UTOD( ) function 817
VALUE( ) function 821
VERIFY( ) function 824
WORKDAY( ) function 826
YEAR( ) function 830
ZONED( ) function 832
ZSTAT( ) function 836
Analytics 839
Analytic scripts 840
Analytic headers and tags 843
ANALYTIC 846
FILE 848
TABLE 850
FIELD 852

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 10 of 934
Table of contents

PARAM 854
PASSWORD 866
DATA 869
RESULT 873
PUBLISH 877
Developing analytics 878
Adding analytic headers 882
Analytic development best practices 885
Packaging analysis apps 891
Sample analytic scripts (analysis app) 894
Appendix 899
System requirements 900
Installing ACL for Windows 903
Configuring Python for use with Analytics 905
Unicode versus non-Unicode editions 908
Converting analytics to Unicode 909
Checking for Unicode compatibility 912
Running R scripts on AX Server 914
Running Python scripts on AX Server 918
Analytic engine error codes 922
Variables created by Analytics commands 929
Reserved keywords 933

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 11 of 934
Getting started

Getting started

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 13 of 934
Getting started

Analytics scripting basics

ACLScript is a command language that allows you to program and automate Analytics commands. The
structure and components of ACLScript are simple yet powerful.
Note
If you are completely new to scripting, consider visiting the Academy for some basic train-
ing before jumping into this content. For courses on scripting and using Analytics, visit
www.highbond.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 Analytics.
The command name is followed by one or more parameters that are specified as parameter_name para-
meter_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, Analytics uses the default value
for that parameter.

Example using the CLASSIFY command

The following example shows the CLASSIFY command along with following parameters:
l ON – specifies which field of the table to classify on
l SUBTOTAL – specifies optional fields to subtotal in the output
l 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:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 14 of 934
Getting started

Important command syntax notes

l the first word in a script line must be a command name
l for most commands, the order of parameters that follow the command name does not matter
l 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 com-
ments 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:
l single line comments – all text following COMMENT is ignored until the end of the line is reached
l 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" on page 19.

Data types
ACLScript supports four basic data types:
l logical – the simplest data type. Logical data expresses a truth value of either true or false
l numeric – contain digits from 0 to 9 and, optionally, a negative sign and a decimal point
l character – a series of one or more characters
l datetime – a date, datetime, or time value expressed in a supported format
Each data type is treated differently by Analytics and can be used in different commands and functions. For
more information about data types, see "Data types" on page 21.

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 Analytics to populate computed fields or as input for conditional logic. For
more information about expressions, see "Expressions" on page 22.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 15 of 934
Getting started

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 func-
tion 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:
l value – the expression or field to test
l min – the minimum of the range
l max – the maximum of the range

BETWEEN(amount, 500, 5000)

For more information about functions, see "Functions" on page 26.

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 com-
mand runs:

v_age_in_years = 3

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 16 of 934
Getting started

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" on
page 21.

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 wrap-
ping the variable name in % characters. When Analytics 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" on page 28.

Control structures
A control structure is a component of a script that decides which direction to take based on given para-
meters. 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 com-
mands in the language.
Tip
You use the IF command to control if a command runs or not while you use the IF para-
meter to decide which records in a table a command runs against.

IF command

IF v_counter > 10 CLASSIFY ON customer_no

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 17 of 934
Getting started

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" on page 30

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 18 of 934
Getting started

Comments
Like an scripting language, you can add comments in ACLScript With the COMMENT keyword. Use com-
ments to make your code easier to understand and to communicate with anyone who may try to read, use,
or understand your script.

Comment types
ACLScript supports two types of comments:
l single line comments – all text following COMMENT is ignored until the end of the line is reached
l multiple line comment blocks – begin with COMMENT and each subsequent line is ignored until the
END keyword, or a blank line, is reached

Single line comments

Use single line comments to describe individual steps in your script or to describe variables:

COMMENT *** the start date for the analysis period

v_Start_Date = `20150101`

Multiple line comment blocks

Use multiple line comment blocks to describe scripts or script sections.

COMMENT
**********************
** This section of the script prepares data for import
**********************
END

Header comment blocks

It is good practice to include a header comment block that contains key script information at the start of each
script:

COMMENT
************************************************************
*** Script Name: {App_ID}{Script name}
*** Parameters: {Detailed description}

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 19 of 934
Getting started

*** Output: {Describe parameters}

*** Written By: {Name}, ABC Corporation, {Month YYYY}
*** Modified By: {Name}, ABC Corporation, script purpose and logic
*** Version: 1.1.1 {app_ver.script_ver.defect.fix}
************************************************************
END

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 20 of 934
Getting started

Data types
ACLScript supports four basic data types: logical, numeric, character, and datetime.

Type Description Limit Qualifier Examples

Character A series of one or more characters. 32,767 Single quotation o 'John Doe'
bytes marks, or double o "John Doe"
quotation marks

Numeric Numeric values contain digits from 0 to 22 digits No qualifier o 100

9 and, optionally, a negative sign and a o -5
decimal point. o 5.01
o 22222.1232

Datetime A date, datetime, or time value o Min- o Backquotes o `20160101`

expressed in a supported format. imum = o Leading 't', or a o `141231`
1900- single blank o `t2359`
01-01 space, for time o `20141231T23595-
o Max- values 9`
imum = o `20141231
9999- 235959`
12-31

Logical The simplest data type. Logical data o T No qualifier ASSIGN v_truth = 5 > 4
expresses a truth value of either true or o F evaluates to T
false.
Comparison operators such as '=', '>',
and '<' return logical values.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 21 of 934
Getting started

Expressions
An expression is any statement that has a value. The simplest form of expression is a literal, however
expressions can be as complex as any legal combination of operators, conditions, functions, and values
you can imagine.

Expression components
Literal values
A literal value is a value written exactly as it is meant to be interpreted, such as the character literal 'my
value'. For information about literals, see "Data types" on the previous page.

Operators
Operators are symbols that tell the script interpreter to perform arithmetic, string, comparison, or logical
evaluation of the specified values:

Operator type in order of pre-

cedence Operators in order of precedence Examples

Parenthesis o () specifies precedence (5 + 3) * 2

o () function operator

Unary o NOT logical v_truth = NOT (3 < 2)

o - negation

Arithmetic o ^ exponentiation 1+5-3*2

o * multiplies, / divides
o + adds, - subtracts
Note
Multiplicative operators
have equal precedence
with each other and eval-
uate from left to right.
Additive operators have
equal precedence with
each other and evaluate
from left to right.

String + concatenates "This is" + " my script"

Comparative o < less than IF amount <> 100

o > greater than
o = equality
o >= greater than or equal to

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 22 of 934
Getting started

Operator type in order of pre-

cedence Operators in order of precedence Examples

o <= less than or equal to

o <> not equal
Note
Comparative operators
have equal precedence
with each other and eval-
uate from left to right.

Binary logical o AND or & IF amount > 5 AND amount < 10

o OR or |

Functions
Expressions are evaluated using the values returned by functions. Functions execute with the highest pre-
cedence of any expression component. For more information about functions, see "Functions" on page 26.

Example expressions
Evaluates to 6
(2 + (3 - 2)) * 2

Evaluates to true
((2 + (3 - 2)) * 2) > ROOT(9,0)

Evaluates to 'ACLScript tutorial'

'AC' + 'LScri' + 'pt ' + 'tutorial'

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 23 of 934
Getting started

Defining computed fields with expres-

sions
Use computed fields to create additional data fields in the currently open table with an expression. A com-
puted field is a field that is appended to the open table and populated with the value of the specified expres-
sion.

Computed field syntax

DEFINE FIELD name COMPUTED expression

l name – the name of the computed field to generate

l expression – the computation or calculation used to generate the value for the field

Example computed field

DEFINE FIELD c_full_name COMPUTED first_name + ' ' + last_name

Tip
Prefix computed field names with c_ to identify them as computed data rather than original
source data.

Defining conditional computed field values

You can also use conditions with computed fields to define the value for different cases:

DEFINE FIELD c_total COMPUTED

amount * ca_tax_rate IF state = 'CA'

amount * ny_tax_rate IF state = 'NY' OR state = 'NJ'
amount * general_rate

When the first conditional expression evaluates to true, the value specified for that case is used. In this
example, amount * general_rate is the default value used when neither of the conditional expressions eval-
uate to true.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 24 of 934
Getting started

Note
You must add an empty line between the line command and the conditions unless you
include the IF , WIDTH, PIC, or AS parameters on the DEFINE FIELD command. For
more information, see "DEFINE FIELD . . . COMPUTED command" on page 129.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 25 of 934
Getting started

Function syntax
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.

BETWEEN(amount, 500, 5000)

Function arguments
An argument of a function is a specific input value passed into the function.
Function arguments are passed to functions via an argument list. This is a comma-delimited list of literal
values, variables, or expressions that evaluate to values of the parameter data type. For more information
about working with data types, see "Data types" on page 21.
Note
If your project works with European number formats, or if you are writing scripts that are
portable across regions, separate function arguments with a space character instead of a
comma unless you are passing in a signed numeric value. Functions accepting signed
numeric values require an explicit delimiter.

Functions vs commands
The distinction between commands and functions is subtle but critical to using ACLScript:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 26 of 934
Getting started

Functions Commands

Use fields, values, or records as input and generate a new Use tables as input and generate new records and tables.
value that is returned.

Used in expressions, computed fields, command para- Used to analyze data, import data, and produce results.
meter values, variables, and filters to assist and modify
command execution.

Cannot be an independent step in a script. Can be an independent step in a script.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 27 of 934
Getting started

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.

How variables work in ACLScript

Creating a variable and assigning a value
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 com-
mand 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" on page 21.

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

ASSIGN v_table = erp_data

OPEN %v_table%

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 28 of 934
Getting started

Types of variables
Analytics uses the following types of variables:
l system-generated variables – automatically created after executing a command
l permanent variables – remain in your computer's memory until you delete them and persist after clos-
ing the Analytics project
Note
To define a permanent variable, prefix the identifier with an '_': _v_company_name =
'Acme'.
l session variables – remain in your computer's memory until you delete them or until the
Analytics project is closed

Variable identifiers
Variable identifiers are case-insensitive and follow certain conventions related to the type of variable:
l system-generated variable identifiers use all caps: OUTPUTFOLDER
l permanent variable identifiers must have a '_' prefix: _v_permanent
l session variable identifiers use the format v_varname by convention but you are not restricted to this
naming convention

Viewing variable values

During script development or while debugging, it can be useful to track variable values as the script
executes. To capture variable values in the script log file, use the DISPLAY command:

DISPLAY v_age_in_years

When the script encounters this command, it writes the command to the log file. To view the variable value
at that stage of script execution, click the entry in the log.
Tip
You can also use variables to help debug by inserting breakpoints in your script and inspect-
ing the variable values on the Variables tab of the Navigator.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 29 of 934
Getting started

Control structures
A control structure is a component of a script that decides which direction to take based on given para-
meters. ACLScript provides both conditional IF logic and looping structures.

Conditional logic using IF

ACLScript implements conditional logic as an IF command and as an optional parameter on many com-
mands in the language:
l command – controls whether or not a command runs
l parameter – decides which records in a table to execute the command against

The IF command
When using the IF command, you specify a conditional expression followed by the command to execute if
the expression evaluates to true:

IF v_counter > 10 CLASSIFY ON customer_no

This conditional structure controls which code executes, so you can use the IF command when you want to
process an entire table based on the test expression. If the expression evaluates as true, the command is
run against all records in the table. For more information about the IF command, see "IF command" on
page 232.

IF parameter
Many commands accept an optional IF parameter that you can use to filter which records the command is
executed against:

CLASSIFY ON customer_no IF state = 'NY'

When this statement executes, the script classifies all records in the table where the value of the state field
is 'NY'.

Looping
The LOOP command
The LOOP command provides the looping control structure in ACLScript.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 30 of 934
Getting started

Note
The LOOP command must execute within the GROUP command, it cannot standalone.
This command processes the statements inside the loop for as long as the specified WHILE expression is
true:

ASSIGN v_counter = 10
GROUP
LOOP WHILE v_counter > 0
v_total = v_total + amount
v_counter = v_counter - 1
END
END

This structure iterates 10 times and adds the value of the amount field to the variable v_total. At the end of
each iteration, the v_counter variable is decremented by 1 and then tested in the WHILE expression. Once
the expression evaluates to false, the loop completes and the script progresses.
When the loop completes, v_total holds the sum of the 10 records' amount fields.
For more information about looping, see "LOOP command" on page 328.

LOOPING with a subscript
Sometimes the LOOP command does not provide the exact looping functionality you may require. In this
case, you can also call a separate Analytics script to execute a loop using the DO SCRIPT command: DO
SCRIPT scriptName WHILE conditionalTest.
You can use one of the following common methods to control when your loop ends:
l flag – the loop continues until the logical flag variable is set to FALSE
l counter – the loop continues until an incrementing or decrementing variable crosses a conditional
threshold
For more information about calling subscripts, see "DO SCRIPT command" on page 166.

Example
You need to import all the CSV files in the C:\data folder into your project. You can use the DIRECTORY
command to get a list of files from the folder, however you cannot use the IMPORT command inside the
GROUP structure. You need an alternative way of looping through the table that DIRECTORY creates.
To achieve this, you create a main script that:
1. Executes the DIRECTORY command and saves the results to a table.
2. Gets the number of records in the table to use as a counter.
3. Calls a subscript once per record in the table to execute the IMPORT command against the current
record.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 31 of 934
Getting started

Main script

COMMENT Main script

DIRECTORY "C:\data\*.csv" TO T_Table_To_Loop

OPEN T_Table_To_Loop
COUNT
v_Num_Records = COUNT1
v_Counter = 1
DO SCRIPT Import_Subscript WHILE v_Counter <= v_Num_Records

Import subscript

COMMENT Import_Subscript

OPEN T_Table_To_Loop
LOCATE RECORD v_Counter

COMMENT code to import CSV file in record goes here...

ASSIGN v_Counter = v_Counter + 1

Variables are shared among all scripts that run in the project, so the main script calls the subscript until the
value of v_Counter exceeds the value of v_Num_Records. Each time the subscript executes, it incre-
ments v_Counter.
This structure allows you to call the IMPORT command against each record while looping through the
table. When the main script completes, you have imported all CSV files from the C:\data folder.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 32 of 934
Getting started

Grouping and looping

The GROUP and LOOP commands provide two ways to execute a series of commands repeatedly.
GROUP performs a single iteration of one or more commands against each record. LOOP performs mul-
tiple iterations of a series of commands against a single record, and can only be used inside a
GROUP block.

A simple example of GROUP

You have a table of invoice data called Ap_Trans . Using this data, you need to calculate a running total of
invoice amounts:

Vendor_ Vendor_ Invoice_ Invoice_ Invoice_ Unit_

Number Vendor_Name City Number Date Amount Quantity Cost

11663 More Power Indus- Los 5981807 2000-11- 618.30 90 6.87

tries Angeles 17

13808 NOVATECH Des 2275301 2000-11- 6705.12 976 6.87

Wholesale Moines 17

12433 Koro International Sheveport 6585673 2000-11- 7955.46 1158 6.87

To calculate this amount, you use the GROUP command. Inside each iteration of GROUP, you:
1. Calculate the running total as of the current record.
2. Extract the invoice number, amount, date, and running total to a results table.

OPEN Ap_Trans

COMMENT set the initial value of running total to zero

ASSIGN v_running_total = 0.00

COMMENT iterate over each record in the table and then calculate and extract the running total
GROUP
ASSIGN v_running_total = v_running_total + Invoice_Amount
EXTRACT Invoice_Number, Invoice_Amount, Invoice_Date, v_running_total AS "Running total" TO
results1
END

When the script runs, the commands inside the GROUP block are processed against each record in the
table, from top to bottom, and the running total is calculated and extracted. If we could walk through
GROUP as it runs, this is how it would look:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 33 of 934
Getting started

First iteration of GROUP: running total = 0.00 + 618.30

The GROUP adds the invoice amount of the first record to the initial running total of 0.00 and extracts the
fields to the results table:

Vendor_ Vendor_ Invoice_ Invoice_ Invoice_ Unit_

Number Vendor_Name City Number Date Amount Quantity Cost

11663 More Power Indus- Los 5981807 2000-11- 618.30 90 6.87

tries Angeles 17

13808 NOVATECH Des 2275301 2000-11- 6705.12 976 6.87

Wholesale Moines 17

12433 Koro International Sheveport 6585673 2000-11- 7955.46 1158 6.87

Second iteration of GROUP: running total = 618.30 +

6705.12
The GROUP block adds the invoice amount of the second record to the new running total of 618.30 and
extracts the fields to the results table:

Vendor_ Vendor_ Invoice_ Invoice_ Invoice_ Unit_

Number Vendor_Name City Number Date Amount Quantity Cost

11663 More Power Indus- Los 5981807 2000-11- 618.30 90 6.87

tries Angeles 17

13808 NOVATECH Des 2275301 2000-11- 6705.12 976 6.87

Wholesale Moines 17

12433 Koro International Sheveport 6585673 2000-11- 7955.46 1158 6.87

Third iteration of GROUP: running total = 7323.42 +

7955.46
The GROUP block adds the invoice amount of the third record to the new running total of 7323.42 and
extracts the fields to the results table:

Vendor_ Vendor_ Invoice_ Invoice_ Invoice_ Unit_

Number Vendor_Name City Number Date Amount Quantity Cost

11663 More Power Indus- Los 5981807 2000-11- 618.30 90 6.87

tries Angeles 17

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 34 of 934
Getting started

Vendor_ Vendor_ Invoice_ Invoice_ Invoice_ Unit_

Number Vendor_Name City Number Date Amount Quantity Cost

13808 NOVATECH Des 2275301 2000-11- 6705.12 976 6.87

Wholesale Moines 17

12433 Koro International Sheveport 6585673 2000-11- 7955.46 1158 6.87

Final results table

After GROUP has processed the final record in the table, you have the following results table:

Invoice_Number Invoice_Amount Invoice_Date Running_total

5981807 618.30 2000-11-17 618.30

2275301 6705.12 2000-11-17 7323.42

6585673 7955.46 2000-11-17 15278.88

Handling different cases using GROUP IF

Using the same AP_Trans table as above, you now need to calculate running totals for three types of
invoices:
l High value (greater than or equal to 1000.00)
l Medium value (between 100.00 and 1000.00)
l Low value (less than 100.00)
The GROUP command provides an IF/ELSE structure to handle different cases. You provide the con-
ditional expressions to test, and if a record evaluates to true, then the commands inside the block run.

How cases are tested

Cases are tested from top to bottom , and a record can only be processed by one IF/ELSE block. The first
case that evaluates to true for the record is the one that processes the record:
1. When GROUP processes the first record, it tests it against the first IF condition (Invoice_Amount >=
1000). If this evaluates to true, then the code for this case runs and no other cases are tested.
2. If the first case evaluates to false, then the next ELSE IF condition (Invoice_Amount >= 100) is
tested. Likewise, if this test evaluates to true, then the code for this case runs and no other cases are
tested.
3. Finally, if none of the IF or ELSE IF cases evaluate to true, then the default case in the ELSE block
processes the record.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 35 of 934
Getting started

Note
If a record evaluates to true for more than one case, the record is only processed by the
first IF/ELSE block that tests it. Records are never processed by more than one IF/ELSE
block in a GROUP command.

OPEN Ap_Trans

COMMENT set initial values for running totals

ASSIGN v_running_total_hi = 0.00
ASSIGN v_running_total_med = 0.00
ASSIGN v_running_total_low = 0.00

COMMENT use GROUP IF to run different ASSIGN and EXTRACT commands depending on invoice
amount
GROUP IF Invoice_Amount >= 1000
ASSIGN v_running_total_hi = v_running_total_hi + Invoice_Amount
EXTRACT Invoice_Number, Invoice_Amount, Invoice_Date, v_running_total_hi AS "Running total"
TO results_hi
ELSE IF Invoice_Amount >= 100
ASSIGN v_running_total_med = v_running_total_med + Invoice_Amount
EXTRACT Invoice_Number, Invoice_Amount, Invoice_Date, v_running_total_med AS "Running
total" TO results_med
ELSE
ASSIGN v_running_total_low = v_running_total_low + Invoice_Amount
EXTRACT Invoice_Number, Invoice_Amount, Invoice_Date, v_running_total_low AS "Running
total" TO results_low
END

When the script runs, the GROUP command tests the invoice amount for each record. Depending on the
amount, the record is used to update one of three running totals (low, medium, high) and three result
tables are produced.

LOOP inside a GROUP

When using GROUP to process the records in a table, you can use a LOOP command to execute a series
of commands on a single record multiple times. LOOP is a second iteration that happens inside the iter-
ation of GROUP, and it runs until a test condition that you specify evaluates to false.

Using the LOOP to split a field

You have the following table containing invoice data and you need to isolate specific information for invoice
amounts per department. One invoice may be related to more than one department, and department
codes are stored in comma-delimited format in the table:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 36 of 934
Getting started

Vendor_Number Invoice_Number Invoice_Date Invoice_Amount Department_Code

11663 5981807 2000-11-17 618.30 CCD,RDR

13808 2275301 2000-11-17 6705.12 CCD

12433 6585673 2000-11-17 7955.46 CCD,LMO,RDR

To extract the invoice amounts per department, you:

1. Use a GROUP command to process the table record by record.
2. Calculate the number of departments (n) associated with each record.
3. Use the LOOP command to iterate n times over the record to extract data for each department asso-
ciated with the record.
Note
You must increment the v_counter variable inside LOOP. If you do not, the WHILE test
always evaluates to true and the script enters an infinite loop. You can include a
SET LOOP command in your scripts to guard against infinite loops. For more information,
see "SET command" on page 408.

COMMENT
use GROUP to count commas in each department code field as a way of identifying how many depart-
ments are associated with the record
"LOOP" over each record for each code in the field, extracting each code into its own record
END
GROUP
v_department_count = OCCURS(Department_Code,',')
v_counter = 0
LOOP WHILE v_counter <= v_department_count
v_dept = SPLIT(Department_Code, ',', (v_counter + 1))
EXTRACT FIELDS Invoice_Number, Invoice_Amount, v_dept AS "Department" TO result1
v_counter = v_counter + 1
END
END

When the script runs, the commands inside the GROUP block are processed against each record in the
table, from top to bottom. For each record, the LOOP command iterates over the record once per depart-
ment code in the comma-delimited list and then extracts a record. If we could walk through GROUP and
LOOP as they run, this is how it would look:

First iteration of GROUP: 2 iterations of LOOP

Vendor_Number Invoice_Number Invoice_Date Invoice_Amount Department_Code

11663 5981807 2000-11-17 618.30 CCD,RDR

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 37 of 934
Getting started

Vendor_Number Invoice_Number Invoice_Date Invoice_Amount Department_Code

13808 2275301 2000-11-17 6705.12 CCD

12433 6585673 2000-11-17 7955.46 CCD,LMO,RDR

For the first record in the table, the value of v_department_count is 1, so LOOP iterates twice:
1. For the first iteration of the LOOP:
l v_counter = 0

l v_depart = CCD

The following record is extracted and the value of v_counter is incremented to 1, therefore LOOP
iterates again:

5981807 618.30 CCD

2. For the second iteration of LOOP:

l v_counter = 1

l v_depart = RDR

The following record is extracted and the value of v_counter is incremented to 2, therefore LOOP
does not iterate again and GROUP proceeds to the next record:

5981807 618.30 RDR

Second iteration of GROUP: 1 iteration of LOOP

Vendor_Number Invoice_Number Invoice_Date Invoice_Amount Department_Code

11663 5981807 2000-11-17 618.30 CCD,RDR

13808 2275301 2000-11-17 6705.12 CCD

12433 6585673 2000-11-17 7955.46 CCD,LMO,RDR

For the second record in the table, the value of v_department_count is 0, so LOOP iterates once:
l v_counter = 0
l v_depart = CCD
The following record is extracted and the value of v_counter is incremented to 1, therefore LOOP does not
iterate again and GROUP proceeds to the next record:

2275301 6705.12 CCD

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 38 of 934
Getting started

Third iteration of GROUP: 3 iterations of LOOP

Vendor_Number Invoice_Number Invoice_Date Invoice_Amount Department_Code

11663 5981807 2000-11-17 618.30 CCD,RDR

13808 2275301 2000-11-17 6705.12 CCD

12433 6585673 2000-11-17 7955.46 CCD,LMO,RDR

For the third record in the table, the value of v_department_count is 2, so LOOP iterates three times:
1. For the first iteration of LOOP:
l v_counter = 0

l v_depart = CCD

The following record is extracted and the value of v_counter is incremented to 1, therefore LOOP iter-
ates again:

6585673 7955.46 CCD

2. For the second iteration of LOOP:

l v_counter = 1

l v_depart = LMO

The following record is extracted and the value of v_counter is incremented to 2, therefore LOOP iter-
ates again:

6585673 7955.46 LMO

3. For the third iteration of LOOP:

l v_counter = 2

l v_depart = RDR

The following record is extracted and the value of v_counter is incremented to 3, therefore LOOP
does not iterate again and GROUP reaches the end of the table:

6585673 7955.46 RDR

Final results table

After GROUP has processed each record in the table, and LOOP has iterated though all the department
codes, you have the following results table:

Invoice_Number Invoice_Amount Department

5981807 618.30 CCD

5981807 618.30 RDR

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 39 of 934
Getting started

Invoice_Number Invoice_Amount Department

2275301 6705.12 CCD

6585673 7955.46 CCD

6585673 7955.46 LMO

6585673 7955.46 RDR

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 40 of 934
Getting started

Top 30 Analytics functions
The top 30 functions in ACLScript are useful across a number of different tasks. Use these functions reg-
ularly to help you prepare, parse, convert, and harmonize data in your scripts.

Removing leading and trailing space

Character fields in Analytics tables often contain leading or trailing spaces because the field widths are fixed
length. When you need to perform an operation using the data from a character field, you can remove these
spaces so that the string only contains the actual data.

ALLTRIM( )
Returns a string with leading and trailing spaces removed from the input string.
Note
It is good practice to use ALLTRIM() on any character field that you are using as input for
another function so that no leading or trailing spaces affect the returned value.

Example
The Vendor_Number field contains the value " 1254". You need to remove this extra space from Vendor_
Number so that you can harmonize the field with data in another table.

COMMENT returns "1254"

ALLTRIM(Vendor_Number)

Synchronizing alphabetic case

String comparison in Analytics is case-sensitive, therefore it is useful to synchronize the casing of all data in
a field before you perform any comparisons, joins, or relations using the data.

UPPER( )
Returns a string with alphabetic characters converted to uppercase.

Example
The Last_Name field contains the value "Smith". You need to make this value uppercase to compare with
an uppercase value from another table.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 41 of 934
Getting started

COMMENT returns "SMITH"

UPPER(Last_Name)

LOWER( )
Returns a string with alphabetic characters converted to lowercase.

Example
The Last_Name field contains the value "Smith". You need to make this value lowercase to compare with
an lowercase value from another table.

COMMENT returns "smith"

LOWER(Last_Name)

PROPER( )
Returns a string with the first character of each word set to uppercase and the remaining characters set to
lowercase.

Example
The Last_Name field contains the value "smith". You need to display it as a proper noun in your output.

COMMENT returns "Smith"

PROPER(Last_Name)

Calculating and separating strings

When you need to extract a segment of data from a longer string, or test some information about the string
such as its length or contents, use these functions.

SUBSTR( )
Returns a specified substring from a string.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to extract the first three
bytes, or characters, from the string.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 42 of 934
Getting started

COMMENT returns "001"

ASSIGN v_start_pos = 1
ASSIGN v_length = 3
SUBSTR(GL_Account_Code, v_start_pos, v_length)

LAST( )
Returns a specified number of characters from the end of a string.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to extract the last two bytes,
or characters, from the string.

COMMENT returns "99"

ASSIGN v_num_chars = 2
LAST(GL_Account_Code, v_num_chars)

SPLIT( )
Returns a specified segment from a string.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to extract the second seg-
ment of the code from the string.

COMMENT returns "458"

ASSIGN v_delimiter = "-"
ASSIGN v_segment_num = 2
SPLIT(GL_Account_Code, v_delimiter, v_segment_num)

AT( )
Returns a number specifying the starting location of a particular occurrence of a substring within a character
value.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to determine the starting byte
position of the value "458" to test whether the GL code's second segment is "458" (start position "5").

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 43 of 934
Getting started

COMMENT returns "5"

ASSIGN v_occurrence = 1
ASSIGN v_substring = "458"
AT(v_occurrence, v_substring, GL_Account_Code)

OCCURS( )
Returns a count of the number of times a substring occurs in a specified character value.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to determine that the
GL code is correctly formatted by ensuring the data contains three hyphen characters.

COMMENT returns "3"

ASSIGN v_substring = "-"
OCCURS(GL_Account_Code, v_substring)

LENGTH( )
Returns the number of characters in a string.

Example
The GL_Account_Code field contains the value "001-458-873-99". You need to determine that the
GL code is correctly formatted by ensuring the data contains 14 characters.

COMMENT returns "14"

LENGTH(GL_Account_Code)

Converting data types

Depending on the data source and import statements that produced the Analytics table, you may need to
convert values in a field from one data type to another so that an operation is possible. For example, to per-
form arithmetic on data that was imported as character ("12345"), you must convert it to numeric.

STRING( )
Converts a numeric value to a character string.

Example
The Invoice_Amount field contains the value 12345.67. You need to convert this to character data.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 44 of 934
Getting started

COMMENT returns "12345.67"

ASSIGN v_str_length = 8
STRING(Invoice_Amount, v_str_length)

VALUE( )
Converts a character string to a numeric value.
Tip
VALUE( ) is often used with ZONED( ) to add leading zeros.

Example
The Invoice_Amount field contains the value "12345.67". You need to convert this to numeric data.

COMMENT returns 12345.67

VALUE(Invoice_Amount, 2)

CTOD( )
Converts a character or numeric date value to a date. Can also extract the date from a character or numeric
datetime value and return it as a date. Abbreviation for "Character to Date".

Example
The Submission_Date field contains the value "April 25, 2016". You need to convert this to datetime data.

COMMENT returns `20160425`

ASSIGN v_date_format = "mmm dd, yyyy"
CTOD(Submission_Date, v_date_format)

DATE( )
Extracts the date from a specified date or datetime and returns it as a character string. Can also return the
current operating system date.

Example
The Submission_Date field contains the value `20160425`. You need to convert this to character data.

COMMENT returns "04/25/2016"

ASSIGN v_date_format = "MM/DD/YYYY"
DATE(Submission_Date, v_date_format)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 45 of 934
Getting started

Adding leading zeros

Convert numeric data to character data and adds leading zeros to the output when you need to harmonize
fields that require leading zeros.

ZONED( )
Converts numeric data to character data and adds leading zeros to the output.

Example
The Employee_Number field contains the value "254879". You need to convert the value to a 10-digit
string with leading zeros.
Tip
You must use the VALUE() function to convert the character to numeric data before using
the numeric as input for ZONED().

COMMENT returns "0000254879"

ASSIGN v_str_length = 10
ASSIGN v_num_decimals = 0
ZONED(VALUE(Employee_Number, v_num_decimals), v_str_length)

BINTOSTR( )
Returns Unicode character data converted from ZONED or EBCDIC character data. Abbreviation for "Bin-
ary to String".
Note
Unicode edition only. For non-Unicode editions, see ZONED() above.

COMMENT returns "0000254879"

ASSIGN v_str_length = 10
ASSIGN v_num_decimals = 0

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 46 of 934
Getting started

ASSIGN v_str_type = "A"

BINTOSTR(ZONED(VALUE(Employee_Number, v_num_decimals), v_str_length), v_str_type)

Extracting datetime parts

Use these functions to isolate and extract specific components of a datetime value.

MONTH( )
Extracts the month from a specified date or datetime and returns it as a numeric value (1 to 12).

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the month as char-
acter data with a leading zero.

COMMENT returns "08"

ASSIGN v_str_length = 2
ZONED(MONTH(Transaction_Date), v_str_length)

DAY( )
Extracts the day of the month from a specified date or datetime and returns it as a numeric value (1 to 31).

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the day as char-
acter data.

COMMENT returns "15"

ASSIGN v_str_length = 2
STRING(DAY(Transaction_Date), v_str_length)

YEAR( )
Extracts the year from a specified date or datetime and returns it as a numeric value using the YYYY format.

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the year as a
numeric value.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 47 of 934
Getting started

COMMENT returns 2016

YEAR(Transaction_Date)

HOUR( )
Extracts the hour from a specified time or datetime and returns it as a numeric value using the 24-hour
clock.

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the hours as a
numeric value.

COMMENT returns 10
HOUR(Transaction_Date)

MINUTE( )
Extracts the minutes from a specified time or datetime and returns it as a numeric value.

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the minutes as a
numeric value.

COMMENT returns 2
MINUTE(Transaction_Date)

SECOND( )
Extracts the seconds from a specified time or datetime and returns it as a numeric value.

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the seconds as a
numeric value.

COMMENT returns 52
SECOND(Transaction_Date)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 48 of 934
Getting started

CDOW( )
Returns the name of the day of the week for a specified date or datetime. Abbreviation for "Character Day of
Week".

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the name of the
day as character data.

COMMENT returns "Mon"

CDOW(Transaction_Date, 3)

CMOY( )
Returns the name of the month of the year for a specified date or datetime. Abbreviation for "Character
Month of Year".

Example
The Transaction_Date field contains the value `20160815 100252`. You need to extract the name of the
month as character data.

COMMENT returns "Aug"

CMOY(Transaction_Date, 3)

Manipulating strings
Remove or replace segments of character fields using these functions.

INCLUDE( )
Returns a string that includes only the specified characters.

Example
The Address field contains the value "12345 ABC Corporation". You need to extract the address number
and exclude the name of the company.

COMMENT returns "12345"

ASSIGN v_chars_to_return = "0123456789"
INCLUDE(Address, v_chars_to_return)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 49 of 934
Getting started

EXCLUDE( )
Returns a string that excludes the specified characters.

Example
The Address field contains the value "12345 ABC Corporation". You need to extract the name of the com-
pany and exclude the address number.

COMMENT returns "ABC Corporation"

ASSIGN v_chars_to_exclude = "0123456789"
EXCLUDE(Address, v_chars_to_exclude)

REPLACE( )
Replaces all instances of a specified character string with a new character string.

Example
The Address field contains the value "12345 Acme&Sons". You need to replace the "&" character with the
word " and ".

COMMENT returns "12345 Acme and Sons"

ASSIGN v_target_char = "&"
ASSIGN v_replacement_char = " and "
REPLACE(Address, v_target_char, v_replacement_char)

OMIT( )
Returns a string with one or more specified substrings removed.

Example
The Address field contains the value "12345 Fake St". You need to extract the address without the street
suffix.

COMMENT returns "12345 Fake"

ASSIGN v_chars_to_omit = "St"
OMIT(Address, v_chars_to_omit)

REVERSE( )
Returns a string with the characters in reverse order.

Example

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 50 of 934
Getting started

The Report_Line field contains the value "001 Correction 5874.39 CR ". You need to reverse the value and
omit any leading or trailing spaces.

COMMENT returns "RC 93.4785 noitcerroC 100"

REVERSE(ALLTRIM(Report_Line))

BLANKS( )
Returns a string containing a specified number of blank spaces.

Example
You need to create a computed field for a region name based on a value in the region_code field. You must
ensure that the default value you specify at the end of the command is at least as long as the longest input
value.

COMMENT BLANKS returns a string of 8 " " chars

ASSIGN v_length = 8
DEFINE FIELD region COMPUTED

"Southern" IF region_code = 1
"Northern" IF region_code = 2
"Eastern" IF region_code = 3
"Western" IF region_code = 4
BLANKS(v_length)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 51 of 934
Commands

Commands

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 53 of 934
Commands

ACCEPT command
Creates a dialog box that interactively prompts users for one or more script input values. Each input value
is stored in a named character variable.
Note
Using the ACCEPT command to enter passwords is not secure. You should use the
"PASSWORD command" on page 350 instead.
The ACCEPT command is not supported in AX Server analytics.
You can create a more advanced interactive dialog box with the "DIALOG command" on
page 148.

Syntax
ACCEPT {message_text <FIELDS project_item_category> TO variable_name} <...n>

Parameters
Name Description

message_text The label displayed in the dialog box used to prompt for input. Must be a quoted string
or a character variable.
When entering multiple prompts, you can separate them with commas. Using commas
improves script readability, but it is not required:

ACCEPT "Specify a start date:" TO v_start_date, "Specify an end date:" TO v_end_

date

FIELDS project_item_cat- Creates a drop-down list of project items for user input instead of a text box. The user
egory can select a single project item, field, or variable from the list.
optional project_item_category specifies which item types to display in the list. For example, spe-
cifying xf displays all the project tables in the list. Enclose project_item_category in quo-
tation marks:

FIELDS "xf"

For the codes used to specify categories, see "Codes for project item categories" on
page 57.
You can specify more than one code in the same prompt, but you cannot mix project
items, fields, or variables.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 54 of 934
Commands

Name Description

TO variable_name The name of the character variable to use to store the user input. If the variable does not
exist, it is created.
If the variable already exists, its current value is displayed in the dialog box as the
default value.
Note
You cannot use non-English characters, such as é, in the names of vari-
ables that will be used in variable substitution. Variable names that con-
tain non-English characters will cause the script to fail.
The ACCEPT command creates character variables only. If you need
input of another data type, you must convert the character variable to the
required type in subsequent processing in a script. For more information,
see "Input data type" on page 57.

Examples
Prompting the user to select the Analytics table to open
You require a dialog box that prompts the user to select the name of the table to open. The script then opens
the table the user selects:

ACCEPT "Select the table to open:" FIELDS "xf" TO v_table_name

OPEN %v_table_name%

The percent signs are required because they indicate that the table name to open is stored in the v_table_
name variable. If the percent signs are omitted, the script attempts to open a table called "v_table_name".

Using multiple dialog boxes to gather required input

You want to create a separate dialog box for each value that the script user must enter.
You use a single prompt string in each instance of the ACCEPT command. The script generates separate
dialog boxes for specifying each of the following:
l a table name
l a field on which to sample
l a sampling interval
l a random start value

ACCEPT "Enter the name of the table to analyze" TO v_table_name

OPEN %v_table_name%
ACCEPT "Select the field to sample" FIELDS "N" to v_field_to_sample
ACCEPT "Enter the sampling interval" TO v_sampling_interval
ACCEPT "Enter the random start value" TO v_random_start_value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 55 of 934
Commands

SAMPLE ON %v_field_to_sample% INTERVAL v_sampling_interval FIXED v_random_start_value

RECORD TO Sample_output OPEN

When the script runs

1. The first dialog box prompts for the table name.
2. The second dialog box, with FIELDS "N" , prompts for a field selection from a drop-down list of
numeric fields.
3. The third dialog box prompts for the interval value.
4. The fourth dialog box prompts for the random start value.

Using a single dialog box with multiple prompts to gather required input
You want to create a single dialog box for all values that the script user must enter.
You use multiple prompts separated by commas in the ACCEPT command to ask the user for multiple
input values. The same dialog box contains prompts for the start date and the end date of a date range:

ACCEPT "Specify a start date:" TO v_start_date, "Specify an end date:" TO v_end_date

Remarks
Interactivity
Use ACCEPT to create an interactive script. When the ACCEPT command is processed, the script
pauses and a dialog box is displayed that prompts the user for input that Analytics uses in subsequent pro-
cessing.
You can create separate dialog boxes that prompt for one item at a time, or you can create one dialog box
that prompts for multiple items.

DIALOG versus ACCEPT

The DIALOG command allows you to create a more advanced interactive dialog box that can have one or
more of the following types of controls:
l text box
l check box
l radio buttons
l drop-down list of customized values
l project item list
You also have the flexibility to customize the layout of the dialog box. For more information, see "DIALOG
command" on page 148.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 56 of 934
Commands

Codes for project item categories

Use the following codes to specify the category of project item to display in a drop-down list.

Project categories

Code Category

xf Tables

xb Scripts

xi Indexes

xr Views and reports

xw Workspaces

Field categories

Code Category

C Character fields

N Numeric fields

D Datetime fields

L Logical fields

Variable categories

Code Category

c Character variables

n Numeric variables

d Datetime variables

l Logical variables

Input data type

ACCEPT stores the user input in one or more character variables. If you need numeric or datetime input,
you can use the VALUE( ) or CTOD( ) functions to convert the contents of a character variable to a numeric

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 57 of 934
Commands

or datetime value:

SET FILTER TO BETWEEN(%v_date_field%, CTOD(%v_start_date%), CTOD(%v_end_date%))

In the example, the start and end dates for this filter are stored as character values. They must be con-
verted to date values in order to be used with a date field that uses a Datetime data type.
Enclosing the variable name in percent signs (%) substitutes the character value contained by the variable
for the variable name. The CTOD( ) function then converts the character value to a date value.

Position of the ACCEPT command

It is good practice to place all ACCEPT commands at the beginning of a script, if possible. If you ask for all
input at the beginning, the script can then run unimpeded once the user enters the necessary information.
Note
You cannot use the ACCEPT command inside the GROUP command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 58 of 934
Commands

ACCESSDATA command
Imports data from a variety of ODBC-compliant data sources.
The command takes the form ACCESSDATA64 or ACCESSDATA32 depending on whether you are using
a 64-bit or 32-bit ODBC driver.

Syntax
{ACCESSDATA64 | ACCESSDATA32} {CONNECTOR | ODBC {"Driver"|"Dsn"|"File"}} NAME value
<USER user_id> <PASSWORD num | PROMPT_PASSWORD> TO table_name CHARMAX max_
field_length MEMOMAX max_field_length <ALLCHARACTER> SOURCE (connection_settings)
<HASH(salt_value, fields)>
SQL_QUERY
(SQL_syntax)
END_QUERY

Parameters
Name Description

CONNECTOR | ODBC The type of ODBC connection you want to make:

{"Driver"|"Dsn"|"File"} o CONNECTOR – connect using a native Analytics data connector
o ODBC "Driver" – connect using a Windows ODBC driver installed on your computer
o ODBC "Dsn" – connect using a saved DSN (data source name) on your computer
o ODBC "File" – connect using a file DSN (a saved .dsn file)

NAME value The name of the Analytics data connector, the ODBC driver, or the DSN.
For example:
o NAME "Amazon Redshift"
o NAME "Microsoft Access Driver (*.mdb, *.accdb)"
o NAME "My Excel DSN"
o NAME "excel.dsn"

USER user_id The user ID for data sources that require a user ID.
optional

PASSWORD num | For data sources that require a password:

PROMPT_PASSWORD o PASSWORD num – use the numbered password definition
optional o PROMPT_PASSWORD – displays a password prompt
The password prompt also allows the user_id to be changed.
If you use PASSWORD num, you must specify a previously created password definition.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 59 of 934
Commands

Name Description

For more information, see "PASSWORD command" on page 350 and "SET command" on
page 408.
Tip
Using the PASSWORD command with PASSWORD num is similar to
using PROMPT_PASSWORD. Both approaches prompt the user for a
password. PROMPT_PASSWORD has the benefit of allowing updating of
the user_id.

TO table_name The location to send the results of the command to:

o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.

CHARMAX max_field_ The maximum length in characters for any field in the Analytics table that originates as
length character data in the source from which you are importing.
The default value is 50. Data that exceeds the maximum field length is truncated when
imported to Analytics.

MEMOMAX max_field_ The maximum length in characters for text, note, or memo fields you are importing.
length
The default value is 100. Data that exceeds the maximum field length is truncated when
imported to Analytics.

ALLCHARACTER Automatically assign the Character data type to all imported fields.
optional Once the data is in Analytics, you can assign different data types, such as Numeric or Dat-
etime, to the fields, and specify format details.
Tip
ALLCHARACTER is useful if you are importing a table that contains
numeric ID values. You can use ALLCHARACTER to prevent Analytics
automatically assigning the Numeric data type to values that should use
the Character data type.

SOURCE connection_set- The connection settings (connection string) required to connect to the data source.
tings

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 60 of 934
Commands

Name Description

HASH(salt_value, fields) Imports the specified fields as cryptographic hash values. Hash values are one-way trans-
formations and cannot be decoded after you import the fields:
optional
o salt_value – an alphanumeric string that is concatenated with the source data values
to strengthen the hashing of the values in the fields. Enter the hash value as a quoted
string.
The salt value is limited to 128 characters. Do not use any of the following characters:
( ) "
o fields – a list of one or more fields to hash. Enter the fields as a quoted string and sep-
arate each field with a comma.
You must specify the field name you see in the Data Access window preview and sta-
ging area, not the physical field name in the data source.
Note
The field name that is shown in the Data Access window preview is the
field alias value in the SQL query ("field_name" AS "alias"). You must
use the alias value to reference fields.

HASH("QZ3x7", "SSN_NO, CC_NO, Last_Name")

For information about comparing values hashed during import to values hashed in
ACLScript, see "Comparing data hashed with ACCESSDATA to data hashed with the
ACLScript HASH( ) function" on page 65.

SQL_QUERY (SQL_ The SQL import statement.

syntax) END_QUERY
Everything inside the parentheses is part of the SQL query and must be valid SQL.

Examples
Importing data using a native Analytics data connector
You need to import data from the Amazon Redshift cloud data service. To do so, you use the
Analytics Amazon Redshift data connector:

ACCESSDATA64 CONNECTOR NAME "Amazon Redshift" USER "ACL_user" PROMPT_

PASSWORD TO "Entitlement_History.FIL" CHARMAX 50 MEMOMAX 100
SOURCE( boolsaschar-
=0;cache-
size-
=100;dat-
abase-
=usage-

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 61 of 934
Commands

;de-
clarefetch-
mode=0;maxbytea=255;maxlongvarchar=8190;maxvarchar=255;port=5439;servername=acl_
test.high-
bond.-
com;sin-
glerowmode=1;sslmode=require;textaslongvarchar=0;usemultiplestatments=0;useunicode=1)
SQL_QUERY(
SELECT
"entitlement_history"."organization" AS "organization",
"entitlement_history"."user_email" AS "user_email",
"entitlement_history"."plan_id" AS "plan_id",
"entitlement_history"."date_from" AS "date_from",
"entitlement_history"."date_to" AS "date_to"
FROM
"prm"."entitlement_history" "entitlement_history"
) END_QUERY

Importing data using a Windows ODBC driver

You need to import data from a Microsoft Access database. To do so, you use a Windows ODBC driver to
connect to MS Access and complete the import:

ACCESSDATA32 ODBC "Driver" NAME "Microsoft Access Driver (*.mdb)" TO "Invoices.FIL"

CHARMAX 50 MEMOMAX 100
SOURCE( dbq=C:\Users\lachlan_murray\Documents\ACL Data\Sample Data Files\Sample.m-
db;defaultdir=C:\Users\lachlan_murray\Documents\ACL Data\Sample Data Files;driv-
erid=281;fil=MS
Access;maxbuf-
fersize=2048;maxscanrows=8;pagetimeout=5;safetransactions=0;threads=3;usercommitsync=Yes)
SQL_QUERY(
SELECT
`Customer`.`CustID` AS `CustID`,
`Customer`.`Company` AS `Company`,
`Customer`.Àddress` AS Àddress`,
`Customer`.`City` AS `City`,
`Customer`.`Region` AS `Region`,
`Customer`.`PostalCode` AS `PostalCode`,
`Customer`.`Country` AS `Country`,
`Customer`.`Phone` AS `Phone`,
Òrders`.ÒrderID` AS ÒrderID`,
Òrders`.`CustID` AS Òrders_CustID`,
Òrders`.`ProdID` AS `ProdID`,
Òrders`.ÒrderDate` AS ÒrderDate`,

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 62 of 934
Commands

Òrders`.`Quantity` AS `Quantity`,
`Product`.`ProdID` AS `Product_ProdID`,
`Product`.`ProdName` AS `ProdName`,
`Product`.ÙnitPrice` AS ÙnitPrice`,
`Product`.`Descript` AS `Descript`,
`Product`.`ShipWt` AS `ShipWt`
FROM
(`Customer` `Customer`
INNER JOIN
Òrders` Òrders`
ON `Customer`.`CustID` = Òrders`.`CustID`
)
INNER JOIN
`Product` `Product`
ON Òrders`.`ProdID` = `Product`.`ProdID`
WHERE
(
`Customer`.`Region` = 'BC'
OR `Customer`.`Region` = 'WA'
)
) END_QUERY

Importing data using a Windows DSN (data source name)

You need to import data from a Microsoft Excel file. To do so, you use a Windows DSN to connect to Excel
and complete the import:

ACCESSDATA32 ODBC "Dsn" NAME "Excel Files" TO "Trans_April_15_cutoff.FIL" CHARMAX 50

MEMOMAX 100
SOURCE( dbq=C:\Users\lachlan_murray\Documents\ACL Data\Sample Data Files\Trans_
April.xls;defaultdir=C:\Users\lachlan_murray\Documents\ACL Data\Sample Data Files;driv-
erid=1046;maxbuffersize=2048;pagetimeout=5)
SQL_QUERY(
SELECT
`Trans_Apr_`.`CARDNUM` AS `CARDNUM`,
`Trans_Apr_`.`AMOUNT` AS `AMOUNT`,
`Trans_Apr_`.`TRANS_DATE` AS `TRANS_DATE`,
`Trans_Apr_`.`CODES` AS `CODES`,
`Trans_Apr_`.`CUSTNO` AS `CUSTNO`,
`Trans_Apr_`.`DESCRIPTION` AS `DESCRIPTION`
FROM
`Trans_Apr$` `Trans_Apr_`
WHERE
(

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 63 of 934
Commands

`Trans_Apr_`.`TRANS_DATE` <= {ts '2003-04-15 00:00:00'}

)
) END_QUERY

Remarks
Note
For more information about how this command works, see the Analytics Help.

Creating ODBC connection settings and SQL import state-

ments
ODBC connection settings, and SQL import statements, are often quite lengthy and involved, as shown in
the examples.
The easiest way to create these portions of the ACCESSDATA command is to first use the Data Access
window in Analytics to connect to the target data source, and import data. You can then copy the entire
ACCESSDATA command from the log, including the connection settings and import statement, and cus-
tomize the command in any way you require.

Password value suppressed

When you use the Data Access window in Analytics to run the ACCESSDATA command, and provide a
password, the password value is not written to the log. Instead, the PROMPT_PASSWORD parameter is
substituted.

ACCESSDATA log files

Two log files record the transactions associated with the ACCESSDATA command, and can be used for
troubleshooting if a data connection fails:
l ServerDataAccess.log – records all activities and errors prior to importing the data
Location: C:\Users\<user account>\AppData\Local\ACL\ACL for Windows\Data
Access\ServerDataAccess.log
Note
The "Server" in ServerDataAccess.log refers to the data access component
of Analytics running locally on the computer where Analytics is installed.
l DataAccess.log – records information about the import operation and the Analytics project that you
are importing data to
Location: ..\<Analytics project folder>\DataAccess.log

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 64 of 934
Commands

Comparing data hashed with ACCESSDATA to data

hashed with the ACLScript HASH( ) function
Even though you cannot read the raw values of hashed data, it is still useful when combining or analyzing
data.
If you want to compare values that are hashed by ACCESSDATA during import with values that are hashed
using ACLScript's HASH( ) function, you must convert any numeric or datetime Analytics fields to character
values and trim all leading and trailing spaces before hashing the data.
Datetime fields must use the following formats when converted to character:
l Datetime – "YYYY-MM-DD hh:mm:ss"
l Date – "YYYY-MM-DD"
l Time – "hh:mm:ss"
The following example uses the STRING( ) and ALLTRIM( ) functions to convert a numeric credit card num-
ber field to character data before hashing the value using ACLScript's HASH( ) function:

COMMENT ACL HASH function used after importing data

HASH(ALLTRIM(STRING(CC_No, 16)), "QZ3x7")

Once you hash the Analytics values, you can compare them with values hashed as part of the
ACCESSDATA command import.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 65 of 934
Commands

ACTIVATE command
Adds field definitions stored in an Analytics workspace to the existing set of field definitions in an Analytics
table layout.

Syntax
ACTIVATE <WORKSPACE> workspace_name <OK>

Parameters
Name Description

WORKSPACE work- The name of the workspace to activate.

space_name

OK Deletes or overwrites items without asking you to confirm the action.

optional If there is a field in the table with an identical name to one in the activated workspace, it
will be overwritten without confirmation. You cannot replace any field that is referenced
by a computed field.

Examples
Activating a workspace in your Analytics project
You activate the ComplexFormulas workspace:

ACTIVATE WORKSPACE ComplexFormulas OK

Activating a workspace saved as a file (.wsp) in the same folder as your Ana-
lytics project
You activate the ComplexFormulas workspace that was saved to a .wsp file:

ACTIVATE WORKSPACE ComplexFormulas.WSP OK

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 66 of 934
Commands

Remarks
How it works
ACTIVATE makes workspace field definitions available to the active table. Once you activate a workspace,
its fields remain available for use with the active table until you close the table.

Editing table layouts

The workspace fields are permanently added to the table layout if:
l you edit the table layout after you activate a workspace
l you make a change that causes the table layout to be saved
Once the workspace fields are saved in the table layout, you can:
1. Use the DEFINE COLUMN command to add the fields to a view.
2. Use the SAVE command to save your changes.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 67 of 934
Commands

AGE command
Groups records into aging periods based on values in a date or datetime field. Counts the number of
records in each period, and also subtotals specified numeric fields for each period.

Syntax
AGE <ON> date_field <CUTOFF cutoff_date> <INTERVAL days <,...n>> <SUPPRESS>
<SUBTOTAL numeric_field <...n> |SUBTOTAL ALL> <IF test> <WHILE test> <FIRST
range|NEXT range> <TO {SCREEN|filename|GRAPH|PRINT}> <KEY break_field>
<HEADER header_text> <FOOTER footer_text> <APPEND> <LOCAL> <STATISTICS>

Parameters
Name Description

ON date_field The name of the date or datetime field or the expression to be aged.
Although you can age on a datetime field, only the date portion of datetime values is
considered. The time portion is ignored. You cannot age on time data alone.

CUTOFF cutoff_date The date that values in date_field are compared against.
optional You must specify cutoff_date as an unquoted string in YYMMDD or YYYYMMDD format,
regardless of the format of the date field. For example: CUTOFF 20141231
If you omit CUTOFF, the current system date is used as the cutoff date.

INTERVAL days <,...n> The date intervals (that is, number of days) to use in calculating the aging periods.
optional days represents the beginning of each aging period measured backward in time from
cutoff_date:
o the first days value identifies the beginning of the first aging period
o a first days value of '0' specifies that the first aging period begins on the specified
cutoff_date
o the last days value identifies the end of the final aging period
You must specify the intervals as an unquoted string with comma separated values:

INTERVAL
0,90,180,270,365

The default aging periods are 0, 30, 60, 90, 120, and 10,000 days. An interval of 10,000
days is used to isolate records with dates that are probably invalid.
If required, date intervals can be customized to mirror other internal aging reports.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 68 of 934
Commands

Name Description

SUPPRESS Suppresses dates that fall outside the aging period from the command output.
optional

WHILE test A conditional expression that must be true in order to process each record. The com-
mand is executed until the condition evaluates as false, or the end of the table is
optional
reached.
Note
If you use WHILE in conjunction with FIRST or NEXT, record processing
stops as soon as one limit is reached.

FIRST range | NEXT range The number of records to process:

TO SCREEN | filename | The location to send the results of the command to:
GRAPH | PRINT o SCREEN – displays the results in the Analytics display area
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o GRAPH – displays the results in a graph in the Analytics display area
o PRINT – sends the results to the default printer

KEY break_field The field or expression that groups subtotal calculations. A subtotal is calculated each
time the value of break_field changes.
optional
break_field must be a character field or expression. You can specify only one field, but

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 69 of 934
Commands

Name Description

you can use an expression that contains more than one field.

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

APPEND Appends the command output to the end of an existing file instead of overwriting it.
optional Note
You must ensure that the structure of the command output and the exist-
ing file are identical:
l the same fields
l the same field order
l matching fields are the same length
l matching fields are the same data type
Analytics appends output to an existing file regardless of its structure. If
the structure of the output and the existing file do not match, jumbled,
missing, or inaccurate data can result.

LOCAL Saves the output file in the same location as the Analytics project.
optional Note
Applicable only when running the command against a server table with
an output file that is an Analytics table.

STATISTICS Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates average, minimum, and maximum values for all SUBTOTAL fields.

Examples
Age invoices with subtotaled amounts
You want to age an accounts receivable table on the Invoice_Date field and subtotal the Invoice_Amount
field.
Invoices are grouped into 30-day periods:
l from the cutoff date to 29 days previous
l from 30 days previous to 59 days previous
l so on

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 70 of 934
Commands

The results include the total outstanding invoice amount for each period:

OPEN Ar
AGE ON Invoice_Date CUTOFF 20141231 INTERVAL 0,30,60,90,120,10000 SUBTOTAL Invoice_
Amount TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Aging periods
The AGE command groups records into aging periods based on values in a date or datetime field. The out-
put results contain a single record for each period, with a count of the number of records in the source table
that fall into each period.

Interval measurement
Aging periods are based on date intervals (that is, number of days) measured backward in time from the cur-
rent system date, or from a cutoff date you specify such as a fiscal period end date.

Future periods
You can create aging periods more recent than the cutoff date by entering negative values for date inter-
vals. For example, the following creates aging periods running forward and backward from the cutoff date:

INTERVAL -60,-30,0,30,60,90

This approach creates a date profile of all the records in a table using different points in time.

Common use cases

Common uses of aging include evaluating sales trends, looking at transaction volumes, and grouping
invoices by the number of days outstanding.
Analytics automatically creates one or two additional aging periods for any dates that fall outside the spe-
cified aging periods, assuming you are not using SUPPRESS.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 71 of 934
Commands

APPEND command
Combines records from two or more Analytics tables by appending them in a new Analytics table.

Syntax
APPEND table_1, table_2, <...n> TO table_name <COMMONFIELDS> <OPEN> <ASCHAR>
<ALLCHAR>

Parameters
Name Description

table_1, table_2, <...n> The tables to append.

The records from each table are appended in the order in which you specify the tables.
The output table contains the records from table_1, followed by the records from table_
2, and so on.
The source tables can have different or identical record structures, and can be sorted or
unsorted.

TO table_name The location to send the results of the command to:

o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Output.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.

COMMONFIELDS Only those fields that are common to all tables being appended are included in the out-
put table.
optional
If you omit COMMONFIELDS, all fields from all tables are included in the output table.
Blank values appear in the output table where no fields exist in the source tables.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 72 of 934
Commands

Name Description

Tip
For diagrams and screen captures illustrating the two options, see
Appending tables.
Note
The APPEND command does not support appending computed fields.
For more information, see "Computed fields not supported" on page 76.

What makes fields common?

For fields to be considered common they must:
o occur in every source table
o have an identical physical name
o belong to the same data category:
l Character
l Numeric
l Datetime
l Logical

Identical name, different data category

If two fields have an identical name but belong to different data categories, an error mes-
sage appears and the APPEND command is not executed.
The error message contains all data category conflicts in the set of tables specified by
APPEND. The message is saved to the command log.
Note
You can avoid this situation by using either ASCHAR or ALLCHAR to
harmonize data categories.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

ASCHAR Harmonizes fields with identical names but different data categories by converting non-
character fields to the character data category.
optional
For example, you append two tables in which the Employee_ID field is character data in
one table, and numeric data in the other. The numeric Employee_ID field is converted to
character data and the two fields are appended without an error.
ASCHAR is ignored if ALLCHAR is also specified.

ALLCHAR Converts all non-character fields in all tables being appended to the character data cat-
egory.
optional
This global conversion to character data ensures that all identically named fields are
appended without error.
Note
After appending, you can change the data category of an entire appen-
ded field if appropriate for the data contained by the field.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 73 of 934
Commands

Examples
Append three monthly transaction tables
The example below appends three monthly transaction tables and outputs a quarterly transaction table
that includes all fields from the three source tables:

APPEND Trans_Jan, Trans_Feb, Trans_Mar TO Trans_Q1

Append three employee tables and include only common fields

The example below appends three divisional employee tables and outputs a master employee table that
includes only common fields from the three source tables:

APPEND Employees_central, Employees_east, Employees_west TO Employees_master

COMMONFIELDS

Append three employee tables and harmonize fields with different data cat-
egories
The examples below append three divisional employee tables in which some identically named fields use
different data categories.
The first example converts non-character fields to the character data category only when required for har-
monization:

APPEND Employees_central, Employees_east, Employees_west TO Employees_master ASCHAR

The second example converts all non-character fields to the character data category whether required for
harmonization or not:

APPEND Employees_central, Employees_east, Employees_west TO Employees_master ALLCHAR

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
The APPEND command combines records from two or more tables by appending them and creating a
new table. Appending means to add one group of records to the bottom of another group of records.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 74 of 934
Commands

Source table fields with identical physical names and identical data categories are directly appended to one
another.
Fields with physical names that are unique across all the source tables are added to the output table but not
directly appended to any other field.
Tip
If you want to directly append inconsistently named fields, standardize the physical names
of the fields in the table layouts before appending. (Assumes that the fields belong to the
same data category, or that you use ASCHAR or ALLCHAR to harmonize the data cat-
egory of the fields.)

When to use APPEND

Use APPEND when you want to combine data from multiple tables with an identical or similar structure. For
example, APPEND is a good choice for combining monthly or quarterly tables into an annual table.
Tip
A single execution of the APPEND command can replace multiple executions of the
EXTRACT command with the APPEND option.

Not a substitute for JOIN or DEFINE RELATION

APPEND is generally not a substitute for the JOIN or DEFINE RELATION commands because it does not
allow you to include or exclude records based on matched or unmatched values in a common key field. With
APPEND, all records from each source table are included in the output table.

Appending completely dissimilar tables

You can append completely dissimilar tables – that is, two or more tables that do not have any fields in com-
mon. While not the primary intended use of the APPEND command, there may be instances in which
appending dissimilar tables serves an analytical purpose.

Appending datetime fields

For two or more datetime fields to be appended, the following conditions must be met:
l identical physical names
l identical data category (Datetime)
l identical data subtypes (date, datetime, or time)
l identical use of time zone indicator – either used, or not used, by all fields being appended
If two datetime fields have an identical name but fail to meet one of the other conditions an error message
appears and the APPEND command is not executed.
The error message contains all failed conditions in the set of tables specified by APPEND. The message is
saved to the command log.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 75 of 934
Commands

Note
You can harmonize dissimilar datetime fields by converting them to the character data cat-
egory, and then append them. This approach allows you to combine the data in a single
table. However, depending on the nature of the source data, you may not be able to con-
vert the combined data back to datetime data.

Automatic harmonization
In some situations the APPEND command automatically harmonizes fields in order to append them:

Data category of
fields Harmonization performed

Character o Different field lengths are harmonized.

o Different character data types such as Custom, PCASCII, and EBCDIC are harmonized by
converting the fields to the ASCII or UNICODE data type.

Numeric o Different field lengths are harmonized. The fields are converted to the ACL data type.
o A different number of defined decimal places are harmonized. Decimal places are stand-
ardized on the greatest number of places, with trailing zeros added to numeric values
where necessary. The fields are converted to the ACL data type.
o Different numeric data types such as Print, Float, EBCDIC, and Micro are harmonized by
converting the fields to the ACL data type.

Datetime o Different date, datetime, or time formats in the source data are harmonized by converting
the fields to the Analytics default formats:
l YYYYMMDD
l YYYYMMDD hh:mm:ss
l hh:mm:ss

When automatic harmonization is not performed

Analytics does not automatically harmonize fields in the following situations. An error message appears
and the append operation is not executed.
l Two fields with an identical name belong to different data categories.
l Two datetime fields with an identical name belong to different datetime subtypes (date, datetime, or
time).
l Two datetime fields with an identical name are inconsistent in their use of the time zone indicator.
Note
User-specified harmonization of fields with identical names but different data categories is
explained above. For more information, see "ASCHAR" on page 73 and "ALLCHAR" on
page 73.

Computed fields not supported

The APPEND command does not support appending computed fields. When you append tables, any com-
puted fields in the source tables are automatically excluded from the output table.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 76 of 934
Commands

If a computed field in a source table has the same name as a physical field in another source table, an error
message appears and the APPEND command is not executed.
Tip
You can append a computed field by first extracting it to convert the field to a physical field.
(For more information, see "EXTRACT command" on page 197.) You then use the extrac-
ted table in the append operation.
Another approach is to recreate the computed field in the appended output table.

Record Note fields not supported

The APPEND command does not support appending Record Note fields. When you append tables, any
Record Note fields in the source tables are automatically excluded from the output table.
If a Record Note field in a source table has the same name as a physical field in another source table, an
error message appears and the APPEND command is not executed.
A Record Note field is automatically generated by Analytics when you add a note to a record.

Record length
If you include all fields from all source tables when appending, the record length in the output table can be
longer than the longest record in the source tables.
An error message appears if the output record length exceeds the Analytics maximum of 32 KB.

Appending and decimal places

Specific behavior governs the appending of numeric fields that include decimal places.

The Decimal setting

The APPEND command uses the number of decimal places defined in the Dec setting in the field definition
in the table layout.
Note
The Dec setting may not be the same as the actual number of decimal places in the source
data. Decimal places that exceed the Dec setting are undefined, and are rounded in cal-
culations.

Inconsistent Decimal settings

If appended numeric fields have inconsistent Dec settings, the fields are converted to the ACL data type and
automatically harmonized on the longest Dec setting.
Any decimal places in source data files that exceed the longest Dec setting are excluded from the output
table generated by APPEND.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 77 of 934
Commands

Consistent Decimal setting

If appended numeric fields have a consistent Dec setting, no data type conversion or harmonization
occurs.
Any decimal places in source data files that exceed the Dec setting are included in the output table gen-
erated by APPEND.

Sorting
Any existing sort orders in the source tables are separately maintained in the respective record sets in the
output table.
Even if the records in all source tables are sorted, the output table is considered unsorted because the
source records are appended as groups, without consideration of any existing sort order in other source
tables.
For example, if you append monthly or quarterly tables to create an annual table, any internal sorting of
the monthly or quarterly data is retained. If required, you can sort the output table after performing the
append operation.

How field order works

Common fields
Common fields in source tables do not have to be in the same order to be appended.
For example, these fields are correctly appended even though they are in a different order:

Table Fields

table_1 Last_name | First_name | Middle_name

table_2 First_name | Middle_name | Last_name

The first table specified in the APPEND command dictates the order of the fields in the output table. So in
the example above, the order in the output table is:
l Last_name | First_name | Middle_name

Non-common fields
Non-common fields in source tables appear in the output table in the order that they appear in the selected
group of source tables.
For example, when appending these two tables:

Table Fields

table_1 Title | Last_name | First_name | Middle_name

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 78 of 934
Commands

Table Fields

table_2 First_name | Middle_name | Last_name | Date_of_birth

the order in the output table is:

l Title | Last_name | First_name | Middle_name | Date_of_birth

Alternate Column Title

Alternate column titles in source tables appear in the output table. If more than one source table has an
alternate column title for the same field, the title from the first selected table takes precedence.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 79 of 934
Commands

ASSIGN command
Creates a variable and assigns a value to the variable.

Syntax
ASSIGN variable_name = value <IF test>

Tip
You can omit the ASSIGN keyword because Analytics automatically interprets the fol-
lowing syntax as an assignment operation:

variable_name = value

Parameters
Name Description

variable_name The name of the variable to assign the value to. If the variable does not exist, it is cre-
ated. If the variable already exists, it is updated with the new value.
Do not use non-English characters, such as é, in the names of variables. Variable
names that contain non-English characters will cause scripts to fail.
Note
Variable names are limited to 31 alphanumeric characters. The name
can include the underscore character ( _ ), but no other special char-
acters, or any spaces. The name cannot start with a number.

value The value to assign to the variable. If a new variable is created, the variable type is
based on the data type in value.

IF test A conditional expression that must be true to create the variable or assign the value to
the variable.
Optional

Examples
Assigning a value to a variable
You assign the value of the Amount field in the current record to a variable named v_current_amount.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 80 of 934
Commands

Because v_current_amount is a variable, its value does not change unless explicitly changed by another
ASSIGN command:

ASSIGN v_current_amount = Amount

Conditionally assigning a value to a variable

You want to update the value of a variable called v_quantity to 1, but only if the value in another variable
called v_counter is less than 10.
If v_counter is greater than or equal to 10, no assignment is made and the value of v_quantity remains
unchanged.
Note that the optional ASSIGN keyword is omitted:

v_quantity = 1 IF v_counter < 10

Remarks
Duration of variables
Variables with names that are not prefaced with an underscore are retained for the duration of the current
Analytics session only.
If you want a variable to be permanently saved with an Analytics project, preface the variable name with an
underscore:

ASSIGN value = _variable_name

Reassigning variables used in a computed field or GROUP

If you assign a value to an existing variable in the following situations, then the new value is assigned but the
previous value's length and decimal count are retained:
l variables used in computed fields
l variables reassigned inside a GROUP
The length of the new value is padded or truncated and the decimals are adjusted if required.
If you reassign a variable in any other context, then the previous value as well as its length and decimal spe-
cifications are overwritten.

Variables created by Analytics commands

When you execute certain commands, either by entering information in dialog boxes in Analytics or by run-
ning scripts, system variables are automatically created by Analytics. You can use these variables, and the

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 81 of 934
Commands

values they contain, when processing subsequent Analytics commands.

The value in a system variable is replaced with an updated value if you execute the same command again.
For more information, see "Variables created by Analytics commands" on page 929.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 82 of 934
Commands

BENFORD command
Counts the number of times each leading digit (1–9) or leading digit combination occurs in a field, and com-
pares the actual count to the expected count. The expected count is calculated using the Benford formula.

Syntax
BENFORD <ON> numeric_field <LEADING n> <IF test> <BOUNDS> <TO {SCREEN|table_
name|GRAPH|PRINT}> <HEADER header_text> <FOOTER footer_text> <WHILE test> <FIRST
range|NEXT range> <APPEND> <OPEN> <LOCAL>

Parameters
Name Description

ON numeric_field The numeric field to analyze.

Note
Select a field that contains "naturally occurring numbers", such as trans-
action amounts. Benford analysis is not suitable for numeric data that is
constrained in any way.
For more information, see "What data can I test using Benford analysis?"
on page 85

LEADING n The number of leading digits to analyze. The value of n must be from 1 to 6.
optional If LEADING is omitted, the default value of 1 is used.

IF test A conditional expression that must be true in order to process each record. The command
is executed on only those records that satisfy the condition.
optional
Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).

BOUNDS Includes computed upper and lower bound values in the output results.
optional If the actual count of more than one digit or digit combination in the output results
exceeds either of the bounds, the data may have been manipulated and should be invest-
igated.

TO SCREEN | table_name The location to send the results of the command to:
| GRAPH | PRINT o SCREEN – displays the results in the Analytics display area
optional o table_name – saves the results to an Analytics table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 83 of 934
Commands

Name Description

Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.
o GRAPH – displays the results in a graph in the Analytics display area
o PRINT – sends the results to the default printer

HEADER header_text The text to insert at the top of each page of a report.
optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

WHILE test A conditional expression that must be true in order to process each record. The command
is executed until the condition evaluates as false, or the end of the table is reached.
optional
Note
If you use WHILE in conjunction with FIRST or NEXT, record processing
stops as soon as one limit is reached.

FIRST range | NEXT range The number of records to process:

APPEND Appends the command output to the end of an existing file instead of overwriting it.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 84 of 934
Commands

Name Description

Note
You must ensure that the structure of the command output and the exist-
ing file are identical:
l the same fields
l the same field order
l matching fields are the same length
l matching fields are the same data type
Analytics appends output to an existing file regardless of its structure. If
the structure of the output and the existing file do not match, jumbled, miss-
ing, or inaccurate data can result.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Outputting results to graph
You run the BENFORD command against the Amount field and output the results to a graph:

BENFORD ON Amount LEADING 2 BOUNDS TO GRAPH

Remarks
What data can I test using Benford analysis?
You should only use Benford analysis for testing numeric data composed of "naturally occurring numbers",
such as accounting amounts, transaction amounts, expenses, or address numbers. Benford analysis is not
suitable for numeric data that is constrained in any way.
Follow these guidelines for identifying numeric data that is suitable for Benford analysis:
l Size of the data set – The data set must be large enough to support a valid distribution. Benford ana-
lysis may not give reliable results for fewer than 500 records.
l Leading digit requirement – All numbers from 1 to 9 must have the possibility of occurring as the lead-
ing digit.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 85 of 934
Commands

l Leading digit combination requirement – All numbers from 0 to 9 must have the possibility of occur-
ring as the second leading digit, and as any additional digits being analyzed.
l Constrained data – Numeric data that is assigned or generated according to a pre-ordained pattern
is not suitable for Benford analysis. For example, do not use Benford to analyze:
l sequential check or invoice numbers

l social security numbers or telephone numbers that map to a specific pattern

l any numbering scheme with a range that prevents certain numbers from appearing

l Random numbers – Numbers generated by a random number generator are not suitable for Ben-
ford analysis.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 86 of 934
Commands

CALCULATE command
Calculates the value of one or more expressions.

Syntax
CALCULATE expression <AS result_label> <,...n>

Parameters
Name Description

expression The expression to calculate.

The expression can be any of the four types:
o character
o numeric
o datetime
o logical
Separate multiple expressions with a comma:

CALCULATE 4.7 * 18.5, 1 + 2, "a" + "b"

AS result_label The name of the result when displayed on screen and in the Analytics command log.
optional result_label must be a quoted string or a valid character expression.
If omitted, the expression being calculated is used as the result name.

Examples
Performing a simple calculation
You use CALCULATE to multiply 4.70 by 18.50, returning the result 86.95:

CALCULATE 4.70 * 18.50

Naming the results of a calculation

You use CALCULATE to derive the gross margin for the currently selected record using previously defined
fields for sale price and unit cost:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 87 of 934
Commands

CALCULATE Sale_price - Unit_cost AS "Margin"

The result is identified on screen, and in the log, as "Margin".

Remarks
How it works
CALCULATE provides the functionality of a calculator combined with access to Analytics functions, vari-
ables, and the data in the currently selected record.

Command output
Depending on where you run CALCULATE, the results are output to different locations:
l From the command line – the result is displayed on screen
l From within a script – the result is recorded in the log
The result_label value is not a variable that you can use in a script. It is only used to identify the calculation
on screen or in the log.

Number of decimal places in output

In a numeric calculation, the result has as many decimal places as the expression component with the
greatest number of decimal places.
Returns 1:

CALCULATE 365/52/7

Returns 1.0027:

CALCULATE 365.0000/52/7

Working with table input

If the expression contains a field value, the table the field belongs to must be open. You can use the FIND,
SEEK, or LOCATE commands to move to the record to be analyzed by CALCULATE.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 88 of 934
Commands

CLASSIFY command
Groups records based on identical values in a character or numeric field. Counts the number of records in
each group, and also subtotals specified numeric fields for each group.

Syntax
CLASSIFY <ON> key_field <SUBTOTAL numeric_field <...n> |SUBTOTAL ALL> <INTERVALS num-
ber> <SUPPRESS> <TO {SCREEN|table_name|GRAPH|PRINT}> <IF test> <WHILE test> <FIRST
range|NEXT range> <HEADER header_text> <FOOTER footer_text> <KEY break_field> <OPEN>
<APPEND> <LOCAL> <STATISTICS>

Parameters
Name Description

ON key_field The character or numeric field to classify.

Maximum key field length is 2048 characters.
If you want to classify a table using a key field longer than 2048 characters, use the
SUMMARIZE command. It does not restrict key field length.

INTERVALS number The maximum number of groups in the output result.

optional If the number of sets of identical values in the field being classified exceeds the specified
maximum, sets are used starting from the top of the column.
Sets exceeding the maximum are grouped together in a group called "OTHER".
If INTERVALS is omitted, a group is created for each set of identical values in the field
being classified.
Note
This parameter is not available in the Analytics user interface and can
only be used as part of ACLScript syntax in a script or the command line.

SUPPRESS Note
optional Cannot be used unless INTERVALS is also specified. SUPPRESS is not
available in the Analytics user interface and can only be used as part of
ACLScript syntax in a script or the command line.
Excludes sets of identical values exceeding the maximum specified by INTERVALS from

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 89 of 934
Commands

Name Description

the command output.

TO SCREEN | table_name The location to send the results of the command to:
| GRAPH | PRINT o SCREEN – displays the results in the Analytics display area
o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.
o GRAPH – displays the results in a graph in the Analytics display area
o PRINT – sends the results to the default printer

FIRST range | NEXT range The number of records to process:

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 90 of 934
Commands

Name Description

HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

STATISTICS Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates average, minimum, and maximum values for all SUBTOTAL fields.

Examples
Total transaction amount per customer
You want to classify an accounts receivable table on the Customer_Number field and subtotal the Trans_
Amount field. The output results are grouped by customer, and include the total transaction amount for
each customer:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 91 of 934
Commands

OPEN Ar
CLASSIFY ON Customer_Number SUBTOTAL Trans_Amount TO "Customer_total.FIL"

Total, average, minimum, and maximum transaction amounts per customer

As with the previous example, you classify an accounts receivable table on the Customer_Number field
and subtotal the Trans_Amount field.
Now you include STATISTICS to calculate the average, minimum, and maximum transaction amounts for
each customer:

OPEN Ar
CLASSIFY ON Customer_Number SUBTOTAL Trans_Amount TO "Customer_stats.FIL"
STATISTICS

Identical invoice amounts

You need to identify invoice amounts that appear more than once in the Ap_Trans table.
To do this, you classify the table on the Invoice_Amount field. The output results are grouped by invoice
amount with an associated count that you can use to identify any invoice amounts that occur more than
once:

OPEN Ap_Trans
CLASSIFY ON Invoice_Amount TO "Grouped_invoice_amounts.FIL" OPEN
SET FILTER TO COUNT > 1

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
CLASSIFY groups records that have the same value in a character or numeric field.
Output contains a single record for each group, with a count of the number of records in the source table
that belong to the group.

Sorting and CLASSIFY

CLASSIFY can process either sorted or unsorted data. Output is automatically sorted in ascending order.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 92 of 934
Commands

Names of auto-generated subtotal and statistics fields

If you use STATISTICS to perform statistical calculations on one or more SUBTOTAL fields, and output the
results to an Analytics table, the fields auto-generated by the parameters have the following names:

Description of auto-gen- Alternate column title (display name) in output

erated field Field name in output table table

Subtotal field subtotaled field name in source Total + subtotaled alternate column title in source
table table

Average field a_ subtotaled field name in Average + subtotaled alternate column title in
source table source table

Minimum field m_ subtotaled field name in Minimum + subtotaled alternate column title in
source table source table

Maximum field x_ subtotaled field name in Maximum + subtotaled alternate column title in
source table source table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 93 of 934
Commands

CLOSE command
Closes an Analytics table, index file, or log file, or ends a Script Recorder session.

Parameters
Name Description

table_name The item to close:

|PRIMARY|SECONDARY|INDEX|LOG|LEARN o table_name – the name of the Analytics table to close
optional o PRIMARY – closes the primary Analytics table
Using CLOSE without any parameters also closes the primary
table.
o SECONDARY – closes the secondary Analytics table
o INDEX – closes the current index applied to the Analytics table
o LOG – returns the log file to the default command log, after the
SET LOG command has been used to specify another log file
o LEARN – ends the active Script Recorder session and prompts
you to save the script file the session was recorded to
LEARN can be used in scripts, but its intended use is in the com-
mand line. The Script Recorder records the ACLScript syntax for
commands that are executed using dialog boxes in the Analytics
user interface.

Examples
Closing a table by name
You want to close a table called Inventory :

CLOSE Inventory

Closing a table by type

You want to close the current secondary table:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 94 of 934
Commands

CLOSE SECONDARY

Restoring the default Analytics command log

You want to restore the default command log after using a separate log file to capture the data verification
phase of a script:

SET LOG TO "DataVerificationPhase.log"

COMMENT Execute data verification commands
CLOSE LOG

Remarks
When to use CLOSE
You typically do not need to close Analytics tables. The active Analytics table automatically closes when you
open another table. The primary table also closes automatically before the OPEN or QUIT commands
execute.
You cannot use CLOSE to close an Analytics project. Use QUIT instead.

Related fields and tables

When you close a primary or secondary table, all related field definitions are removed from memory. Any
changes to the table layout are saved before the table is closed.
If you have defined table relations in an Analytics project, the CLOSE command closes both the primary and
any secondary tables. It also closes the related tables.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 95 of 934
Commands

CLUSTER command
Groups records into clusters based on similar values in one or more numeric fields. Clusters can be uni-
dimensional or multidimensional.

Syntax
CLUSTER ON key_field <...n> KVALUE number_of_clusters ITERATIONS number_of_iterations
INITIALIZATIONS number_of_initializations <SEED seed_value> <OTHER field < ...n>> TO table_
name <IF test> <WHILE test> <FIRST range|NEXT range> OPEN {no_
keyword|NOCENTER|NOSCALE}

Parameters
Name Description

ON key_field <...n> One or more numeric fields to cluster. Multiple fields must be separated by spaces.

KVALUE number_of_ The number of clusters generated in the output results.

clusters

ITERATIONS number_of_ The maximum number of times the cluster calculation is re-performed.
iterations

INITIALIZATIONS num- The number of times to generate an initial set of random centroids.
ber_of_initializations

SEED seed_value The seed value to use to initialize the random number generator in Analytics.
optional If you omit SEED, Analytics randomly selects the seed value.

OTHER field <...n> One or more additional fields to include in the output.
optional Note
Key fields are automatically included in the output table, and do not
need to be specified using OTHER.

TO table_name The location to send the results of the command to:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 96 of 934
Commands

Name Description

Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.

FIRST range | NEXT range The number of records to process:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

no_keyword | NOCENTER The method for standardizing key field numeric values.
| NOSCALE o no_keyword – center key field values around zero (0), and scale the values to unit
variance when calculating the clusters
o NOCENTER – scale key field values to unit variance when calculating the clusters,
but do not center the values around zero (0)
o NOSCALE – use the raw key field values, unscaled, when calculating the clusters

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 97 of 934
Commands

Examples
Clustering on invoice amount
In addition to stratifying an accounts receivable table on the Invoice_Amount field, you also decide to
cluster on the same field.
l Stratifying groups the amounts into strata with predefined numeric boundaries – for example, $1000
intervals.
l Clustering discovers any organic groupings of amounts that exist in the data without requiring that
you decide on numeric boundaries in advance.

Open Ar
CLUSTER ON Invoice_Amount KVALUE 8 ITERATIONS 30 INITIALIZATIONS 10 OTHER No Due
Date Ref Type TO "Clustered_invoices" NOSCALE

As a quick way of discovering how many records are contained in each output cluster, you classify the
Clustered_invoices output table on the Cluster field.

OPEN Clustered_invoices
CLASSIFY ON Cluster TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 98 of 934
Commands

COMMENT command
Adds an explanatory note to a script without affecting processing.

Syntax
Single-line comments
COMMENT comment_text

Multiline comments
COMMENT
comment_text
<...n>
<END>

Note
Do not use a caret character ^ to preface lines of comment text. The caret has a special use
in the .acl project file, and comment text is not saved if you preface it with a caret.

Parameters
Name Description

comment_text The comment you are adding.

o single-line comment – enter the entire comment text without a line break
o multiline comment – enter as many lines of comment text as necessary starting on the
line immediately following the COMMENT command
Terminate a multiline comment with the END keyword on a separate line, or with a
blank line.

END The end of a multiline COMMENT command.

optional If you use END, it must be entered on the line immediately following the last comment
line. If you omit END, a blank line must follow the last comment line.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 99 of 934
Commands

Examples
Single-line comments
You use single-line comments before commands to add documentation for future users who will maintain
the script:

COMMENT Generate the standard deviation and average.

STATISTICS ON %v_amt% STD TO SCREEN NUMBER 5
COMMENT Create fields for storing standard deviation and average.
DEFINE FIELD Standard_Dev COMPUTED STDDEV1
DEFINE FIELD Average COMPUTED AVERAGE1

Multiline comment
You begin each script you write with a multiline comment that explains the purpose of the script:

COMMENT
  This analytic identifies multiple records having common
  transaction originator IDs (like vendor ID or merchant ID)
  where the transaction date values are either equal or one day apart.
  This analytic can be used for split invoices, split purchase orders,
  split requisitions, and split corporate card transactions.
END

Remarks
When to use COMMENT
Use COMMENT to include information about the purpose of a script, the logic used, and other information
such as the required inputs for the script and the purpose of each variable you define.
The comments in a script are written to the Analytics command log each time the script runs.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 100 of 934

Commands

COUNT command
Counts the total number of records in the current view, or only those records that meet the specified con-
dition.

Syntax
COUNT <IF test> <WHILE test> <FIRST range|NEXT range>

Parameters
Name Description

FIRST range | NEXT range The number of records to process:

Analytics output variables

Name Contains

COUNTn The record count calculated by the command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 101 of 934

Commands

Name Contains

o If the variable name is COUNT1, it is storing the record count for the most recent com-
mand executed.
o If the variable name is COUNTn, where n is greater than 1, the variable is storing the
record count for a command executed within a GROUP command.
The value of n is assigned based on the line number of the command in the GROUP.
For example, if the command is one line below the GROUP command it is assigned
the value COUNT2. If the command is four lines below the GROUP command, it is
assigned the value COUNT5.

Examples
Storing COUNT1
The result of the COUNT command is stored in the COUNT1 output variable. You can retrieve and store
this value in a user-defined variable.
The COUNT command overwrites the COUNT1 variable each time it is executed, so the value needs to be
stored in a user-defined variable before the command is executed for the second time after the filter is
applied to the table:

OPEN CustomerAddress
COUNT
TotalRec = COUNT1
SET FILTER TO ModifiedDate > '20100101'
COUNT
TotalFilteredRec = COUNT1

Remarks
When to use COUNT
Use the COUNT command to count the number of records in an Analytics table, or to count the number of
records that meet a particular test condition. If no test is specified, the total number of records in the Ana-
lytics table is displayed.

How filters affect COUNT

If a filter has been applied to a view, the command counts the number of records remaining in the view
after the filtering condition has been applied.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 102 of 934

Commands

CREATE LAYOUT command

Creates an empty Analytics table layout, which may be required in certain scripting situations.

Syntax
CREATE LAYOUT layout_name WIDTH characters <RECORD 0|RECORD 1>

Parameters
Name Description

layout_name The name of the layout.

WIDTH characters The record length in characters.

RECORD 0 | RECORD 1 o If you specify RECORD 0, or omit this parameter, the table layout is created without
any records or a source data file.
optional o If you specify RECORD 1 the table layout is created with a single empty record and a
source data file named layout_name.fil.

Examples
Creating an empty table layout without any records
You create an empty table layout with a record length of 100 characters:

CREATE LAYOUT empty_table WIDTH 100

Creating an empty table layout with one record

You create:
l an empty table layout with one empty record
l a record length of 50 characters
l an associated Analytics data file called empty_table.fil

CREATE LAYOUT empty_table WIDTH 50 RECORD 1

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 103 of 934

Commands

Remarks
The empty table layout is created with a single character field called Field_1. The field length is the same
as the record length you specify with WIDTH.
Note
This command is not supported for use in Analytics analytics run on AX Server.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 104 of 934

Commands

CROSSTAB command
Groups records based on identical combinations of values in two or more character or numeric fields, and
displays the resulting groups in a grid of rows and columns. Counts the number of records in each group,
and also subtotals specified numeric fields for each group.

Syntax
CROSSTAB <ON> row_field <...n> COLUMNS column_field <SUBTOTAL numeric_field
<...n>|SUBTOTAL ALL> TO {SCREEN|table_name|filename|GRAPH|PRINT} <IF test> <WHILE
test> <FIRST range|NEXT range> <APPEND> <COUNT> <OPEN> <LOCAL> <HEADER header_
text> <FOOTER footer_text>

Parameters
Name Description

ON row_field <...n> The field or expression to use for rows in the resulting grid of rows and columns. You can
specify one or more fields or expressions as the basis for the rows.

COLUMNS column_field The field or expression to use for columns in the resulting grid of rows and columns. You
can specify only one field or expression for the columns.

TO SCREEN | table_name The location to send the results of the command to:
| filename | GRAPH o SCREEN – displays the results in the Analytics display area
| PRINT o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 105 of 934

Commands

Name Description

Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o GRAPH – displays the results in a graph in the Analytics display area
o PRINT – sends the results to the default printer

FIRST range | NEXT range The number of records to process:

APPEND Appends the command output to the end of an existing file instead of overwriting it.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 106 of 934

Commands

Name Description

COUNT Includes record counts as columns. Counts are useful when you use SUBTOTAL.
optional Counts are automatically included if you do not select any subtotal fields.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

Examples
Cross-tabulating an accounts receivable table with SUBTOTAL
You want to cross-tabulate an accounts receivable table on the Customer Number and Transaction Type
fields. You also want to subtotal the Transaction Amount field.
The output is grouped by customer, and within each customer by transaction type. It includes the total trans-
action amount for each customer for each transaction type:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 107 of 934

Commands

OPEN Ar
CROSSTAB ON Customer_Number COLUMNS Trans_Type SUBTOTAL Trans_Amount COUNT
TO SCREEN

Cross-tabulating an accounts receivable table to find duplicate transactions

You need to find evidence of duplicate transactions in an accounts receivable table.
To do this, you cross-tabulate an accounts receivable table on the Transaction Amount and Transaction
Type fields. The output groups and counts identical transaction amounts for each transaction type:

OPEN Ar
CROSSTAB ON Trans_Amount COLUMNS Trans_Type TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
CROSSTAB groups records that have the same combination of values in two or more character or
numeric fields.
The output contains a grid of rows and columns similar to a pivot table. It includes a single row-column inter-
section for each group, with a count of the number of records in the source table that belong to the group.

Sorting and CROSSTAB

CROSSTAB can process either sorted or unsorted data. Both the row_field and the column_field in the
output are automatically sorted in ascending order.
If you specify more than one row_field, the fields use a nested sort, starting with the first row_field you spe-
cify.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 108 of 934

Commands

CVSEVALUATE command
For classical variables sampling, provides four different methods for projecting the results of sample ana-
lysis to the entire population.

Syntax
CVSEVALUATE BOOKED book_value_field AUDITED audit_value_field ETYPE
{MPU|DIFFERENCE|RATIO SEPARATE|RATIO COMBINED} STRATA boundary_value <,...n>
POPULATION stratum_count,stratum_book_value <,...n> CONFIDENCE confidence_level CUTOFF
value,certainty_stratum_count,certainty_stratum_book_value ERRORLIMIT number PLIMIT
{BOTH|UPPER|LOWER} <TO {SCREEN|filename}>

Parameters
Note
If you are using the output results of the CVSPREPARE and CVSSAMPLE commands as
input for the CVSEVALUATE command, a number of the parameter values are already
specified and stored in variables. For more information, see "CVSPREPARE command"
on page 113 and "CVSSAMPLE command" on page 117.
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

BOOKED book_value_ The numeric book value field to use in the evaluation.
field

AUDITED audit_value_ The numeric audit value field to use in the evaluation.
field

ETYPE MPU | The estimation type to use:

DIFFERENCE |
l MPU (Mean-per-unit)
RATIO SEPARATE | l Difference
RATIO COMBINED l Ratio Separate
l Ratio Combined
For more information, see "Which estimation type should I use?" on page 111

STRATA boundary_value The upper boundary values to use for stratifying the book_value_field.
<,...n>

POPULATION stratum_ The number of records and the total value for each stratum in the book_value_field.
count, stratum_value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 109 of 934

Commands

Name Description

<,...n>

CONFIDENCE con- The confidence level used during the preparation stage of the classical variables sample.
fidence_level

CUTOFF value, certainty_ o value – the certainty stratum cutoff value used during the preparation and sampling
stratum_count, certainty_ stage of the classical variables sample
stratum_book_value o certainty_stratum_count – the number of records in the certainty stratum
o certainty_stratum_book_value – the total book value of the records in the certainty
stratum

ERRORLIMIT number The minimum number of errors you expect in the sample.
Note
If the actual number of errors you found when you analyzed the sample is
less than the ERRORLIMIT number, the only evaluation method available
is mean-per-unit.

PLIMIT BOTH | UPPER | The type of precision limit to use:

LOWER o Both
o Upper
o Lower
For more information, see "CVSPREPARE command" on page 113.

TO SCREEN | filename The location to send the results of the command to:
o SCREEN – displays the results in the Analytics display area
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 110 of 934

Commands

CVSEVALUATE BOOKED invoice_amount AUDITED AUDIT_VALUE ETYPE DIFFERENCE

STRATA 4376.88,9248.74,16904.52,23864.32 POPULATION
1279,3382131.93,898,5693215.11,763,9987014.57,627,12657163.59,479,13346354.63
CONFIDENCE 95.00 CUTOFF 35000.00,36,1334318.88 ERRORLIMIT 6 PLIMIT BOTH TO
SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Which estimation type should I use?

The estimation type that you should use depends on the nature of the data: the sample book values, the
sample audit values, and the relation between them.

Guidelines
The guidelines below help you select an estimation type. You can repeat the evaluation stage with different
estimation types, and compare the results from each.

Presence of mis- Size of mis- Comparison of

Estimation type statements statements Sign of book values strata ratios

No misstatements, n/a n/a n/a

or very few mis-
statements
The only valid estim-
ation type if there are
no misstatements, or
very few mis-
statements, in the
audited sample pop-
Mean-per-unit ulation.

Misstatements Misstatements are n/a n/a

required non-proportional
Requires a number More suitable when
of misstatements in misstatements are
the audited sample non-proportional: the
population. size of a mis-
statement is not
For example, 5% or
related to the size of
more of the samples
the associated book
contain mis-
value.
statements.
Difference In other words, small

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 111 of 934

Commands

Presence of mis- Size of mis- Comparison of

Estimation type statements statements Sign of book values strata ratios

and large book val-

ues can have either
small or large mis-
statements.

Misstatements are Book values have Ratios vary

proportional the same sign
More suitable when
More suitable when All sample book val- the ratio of average
misstatements are ues must have the sample audit value
proportional: the size same sign: either all to average sample
of a misstatement is positive, or all neg- book value varies
related to the size of ative. widely between
Ratio Separate the associated book strata.
value.
In other words, small Ratios are con-
book values have sistent
small misstatements, More suitable when
and large book val- the ratio of average
ues have large mis- sample audit value
statements. to average sample
book value is rel-
atively consistent
Ratio Combined between strata.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 112 of 934

Commands

CVSPREPARE command
Stratifies a population, and calculates a statistically valid sample size for each stratum, for classical variables
sampling.

Syntax
CVSPREPARE ON book_value_field NUMSTRATA number MINIMUM minimum_strata_sample_size
PRECISION value CONFIDENCE confidence_level <CUTOFF value> NCELLS number PLIMIT
{BOTH|UPPER|LOWER} ERRORLIMIT number <MINSAMPSIZE minimum_sample_size> TO
{SCREEN|filename}

Parameters
Note
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

ON book_value_field The numeric book value field to use as the basis for preparing the classical variables
sample.

NUMSTRATA number The number of strata to use for numerically stratifying the book_value_field.
The minimum number of strata is 1, and the maximum is 256.
If you specify NUMSTRATA 1, and do not specify a CUTOFF, the population is unstratified
prior to drawing a sample.
Note
The number of strata cannot exceed 50% of the number of cells specified
for NCELLS.

MINIMUM minimum_ The minimum number of records to sample from each stratum.
strata_sample_size
Leave the default of zero (0) if you do not have a specific reason for specifying a min-
imum number.

PRECISION value The monetary amount that is the difference between the tolerable misstatement and the
expected misstatement in the account.
o Tolerable misstatement – the maximum total amount of misstatement that can occur in
the sample field without being considered a material misstatement
o Expected misstatement – the total amount of misstatement that you expect the sample
field to contain
The precision establishes the range of acceptability for an account to be considered fairly
stated.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 113 of 934

Commands

Name Description

Reducing the precision decreases the range of acceptability (the margin of error) which
requires an increased sample size.

CONFIDENCE con- The desired confidence level that the resulting sample is representative of the entire pop-
fidence_level ulation.
For example, specifying 95 means that you want to be confident that 95% of the time the
sample will in fact be representative. Confidence is the complement of "sampling risk". A
95% confidence level is the same as a 5% sampling risk.
o If PLIMIT is BOTH, the minimum confidence level is 10%, and the maximum is 99.5%.
o If PLIMIT is UPPER or LOWER, the minimum confidence level is 55%, and the max-
imum is 99.5%.

CUTOFF value A certainty stratum cutoff value.

optional Amounts in the book_value_field greater than or equal to the cutoff value are auto-
matically selected and included in the sample.
If you omit CUTOFF, a default cutoff value equal to the maximum amount in the book_
value_field is used.

NCELLS number The number of cells to use for pre-stratifying the book_value_field.
Cells are narrower numeric divisions than strata. Pre-stratification is part of an internal
process that optimizes the position of strata boundaries. Cells are not retained in the final
stratified output.
The minimum number of cells is 2, and the maximum is 999.
Note
The number of cells must be at least twice (2 x) the number of strata spe-
cified for NUMSTRATA.

PLIMIT BOTH | UPPER | The type of precision limit to use.

LOWER o BOTH – specify this option if:
l the account as a whole could be either overstated or understated
l you are interested in estimating whether misstatement in either direction exceeds
the specified PRECISION
o UPPER – specify this option if:
l the account as a whole is likely to be understated
l you are only interested in estimating whether the total amount of understatement
exceeds the specified PRECISION
o LOWER – specify this option if:
l the account as a whole is likely to be overstated
l you are only interested in estimating whether the total amount of overstatement
exceeds the specified PRECISION
Caution
Specify BOTH if you are not sure which option to specify.

ERRORLIMIT number The minimum number of errors you expect in the sample.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 114 of 934

Commands

Name Description

Note
If the actual number of errors you find when you analyze the sample is
less than the ERRORLIMIT number, the only evaluation method available
is mean-per-unit.

MINSAMPSIZE minimum_ The minimum number of records to sample from the entire population.
sample_size
Leave the default of zero (0) if you do not have a specific reason for specifying a min-
optional imum number.

Analytics output variables

Name Contains

CONFIDENCE The confidence level specified by the user.

ERRLIMIT The minimum number of errors specified by the user.

NSTRATA The number of strata specified by the user.

PLIMIT The type of precision limit specified by the user.

S_TOP The certainty stratum cutoff value specified by the user, or if none was specified, the
upper boundary of the top stratum calculated by the command.

SAMPLEFIELD The book value field specified by the user.

SBOTTOM The lower boundary of the bottom stratum calculated by the command.

SBOUNDARY All strata upper boundaries calculated by the command, and S_TOP. Does not store
SBOTTOM.

SPOPULATION The count of the number of records in each stratum, and the total monetary value for each
stratum. Excludes items above the certainty stratum cutoff.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 115 of 934

Commands

Name Contains

SSAMPLE The sample size for each stratum calculated by the command.

Examples
Prepare a classical variables sample
You have decided to use classical variables sampling to estimate the total amount of monetary mis-
statement in an account containing invoices.
Before drawing the sample, you must first stratify the population, and calculate a statistically valid sample
size for each stratum.
You want to be confident that 95% of the time the sample drawn by Analytics will be representative of the
population as a whole.
Using your specified confidence level, the example below stratifies a table based on the invoice_amount
field, and calculates the sample size for each stratum and the certainty stratum:

CVSPREPARE ON invoice_amount NUMSTRATA 5 MINIMUM 0 PRECISION 928003.97

CONFIDENCE 95.00 CUTOFF 35000 NCELLS 50 PLIMIT BOTH ERRORLIMIT 6 MINSAMPSIZE
0 TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Numeric length limitation

Several internal calculations occur during the preparation stage of classical variables sampling. These cal-
culations support numbers with a maximum length of 17 digits. If the result of any calculation exceeds 17
digits, the result is not included in the output, and you cannot continue with the sampling process.
Note that source data numbers of less than 17 digits can produce internal calculation results that exceed
17 digits.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 116 of 934

Commands

CVSSAMPLE command
Draws a sample of records using the classical variables sampling method.

Syntax
CVSSAMPLE ON book_value_field NUMSTRATA number <SEED seed_value> CUTOFF value
STRATA boundary_value <,...n> SAMPLESIZE number <,...n> POPULATION stratum_
count,stratum_value <,...n> TO table_name

Parameters
Note
If you are using the output results of the CVSPREPARE command as input for the
CVSSAMPLE command, a number of the parameter values are already specified and
stored in variables. For more information, see "CVSPREPARE command" on page 113.
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

ON book_value_field The numeric book value field to use as the basis for the sample.

NUMSTRATA number The number of strata to use for stratifying the book_value_field.

SEED seed_value The seed value to use to initialize the random number generator in Analytics.
optional If you omit SEED, Analytics randomly selects the seed value.

CUTOFF value A certainty stratum cutoff value.

Amounts in the book_value_field greater than or equal to the cutoff value are auto-
matically selected and included in the sample.

STRATA boundary_value The upper boundary values to use for stratifying the book_value_field.
<,...n>

SAMPLESIZE number The number of records to sample from each stratum.

<,...n>

POPULATION stratum_ The number of records in each stratum, and the total value for each stratum.
count, stratum_value
<,...n>

TO table_name The location to send the results of the command to:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 117 of 934

Commands

Name Description

o table_name – saves the results to an Analytics table

Analytics output variables

Name Contains

S_TOPEV The certainty stratum cutoff value specified by the user, or if none was specified, the
upper boundary of the top stratum previously calculated by the CVSPREPARE com-
mand.
Also stores the count of the number of records in the certainty stratum, and their total
monetary value.

SBOTTOMEV The lower boundary of the bottom stratum calculated by the command.

BOUNDARYEV All strata upper boundaries prefilled by the command, or specified by the user. Does not
store S_TOPEV or SBOTTOMEV.

SPOPULATION The count of the number of records in each stratum, and the total monetary value for
each stratum. Excludes items above the certainty stratum cutoff.

Examples
Draw a classical variables sample
You are going to use classical variables sampling to estimate the total amount of monetary misstatement
in an account containing invoices.
After stratifying the population, and calculating a statistically valid sample size for each stratum, you are
ready to draw the sample.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 118 of 934

Commands

The example below draws a stratified sample of records based on the invoice_amount field, and outputs
the sampled records to the Invoices_sample table:

CVSSAMPLE ON invoice_amount NUMSTRATA 5 SEED 12345 CUTOFF 35000.00 STRATA

4376.88,9248.74,16904.52,23864.32,35000.00 SAMPLESIZE 37,36,49,36,39 POPULATION
1279,3382131.93,898,5693215.11,763,9987014.57,627,12657163.59,479,13346354.63 TO
"Invoices_sample"

Remarks
Note
For more information about how this command works, see the Analytics Help.

System-generated fields
Analytics automatically generates four fields and adds them to the sample output table. For each record
included in the sample, the fields contain the following descriptive information:
l STRATUM – the number of the stratum to which the record is allocated
l ORIGIN_RECORD_NUMBER – the original record number in the source data table
l SELECTION_ORDER – on a per-stratum basis, the order in which the record was randomly selected
l SAMPLE_RECORD_NUMBER – the record number in the sample output table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 119 of 934

Commands

DEFINE COLUMN command

Creates and adds one or more columns to an existing view.

Syntax
DEFINE COLUMN view_name field_name <AS display_name> <POSITION n> <WIDTH
characters> <PIC format> <SORT|SORT D> <KEY> <PAGE> <NODUPS> <NOZEROS> <LINE
n>

Parameters
Name Description

view_name The view to add the column to.

field_name The field to create the column for.

To use a field from a related table, specify the field name as table_name.field_name.

AS display_name The display name (alternate column title) for the field in the view. If you want the display
name to be the same as the field name do not use AS.
optional
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title.

POSITION n The position of the column in the view numerically from left to right:
optional o if omitted, the column is placed as the rightmost column at the time that the column is
added
o if a position number is missing, column positions are adjusted so that the columns
are positioned sequentially
o if a position number is already in use, the new column is placed to the left of the
column already using the position number

WIDTH characters The display width of the field in characters.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 120 of 934

Commands

Name Description

Note
The characters specified by WIDTH are fixed-width characters. Every
character is allotted the same amount of space, regardless of the width
of the actual character.
By default, views in Analytics use a proportional width font that does not
correspond with fixed-width character spacing.
If you want a one-to-one correspondence between the WIDTH value and
the characters in the view, you can change the Proportional Font setting
in the Options dialog box to a fixed-width font such as Courier New.

PIC format Note

optional Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in
the source data. For example, if the source data is 12/31/2014, you
must enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.

SORT | SORT D Sorts the column:

optional o ascending order – SORT
o descending order – SORT D

KEY The column is designated as a break field in reports. Reports are subtotaled and sub-
divided when the value of the column changes. The following restrictions apply to break
optional
fields:
o must be a character field or expression
o if a break field is set in the view, it must be the leftmost column
o the last column in the view cannot be a break field
o if you have more than one break field, all of the columns to the left of any additional
break field must also be break fields

PAGE Inserts a page break each time the value in the break field changes.
optional

NODUPS Substitutes blank values for repeated values in the field.

optional For example, if the customer name is listed for each invoice record, the report is easier
to read if it shows only the first instance of each customer name.

NOZEROS Substitutes blank values for zero values in the field.

optional For example, if a report includes a large number of zero values in a field, the report is
easier to read if it only displays non-zero values.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 121 of 934

Commands

Name Description

LINE n The number of lines in the column. If no value is specified, the column defaults to a
single line. The value of n must be between 2 and 60.
optional

Examples
Defining a view with six columns
With the AR table open, you define a view called AR_Report, and define six columns. The columns are dis-
played in the listed order:

OPEN Ar
DEFINE VIEW AR_Report OK
DEFINE COLUMN AR_Report No AS "Customer Number" WIDTH 7 KEY
DEFINE COLUMN AR_Report Date AS "Invoice Date" WIDTH 10
DEFINE COLUMN AR_Report Due AS "Due Date" WIDTH 10
DEFINE COLUMN AR_Report Reference AS "Reference Number" WIDTH 6
DEFINE COLUMN AR_Report Type AS "Transaction Type" WIDTH 5
DEFINE COLUMN AR_Report Amount AS "Transaction Amount" WIDTH 12 PIC "-9999999999.99"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 122 of 934

Commands

DEFINE FIELD command

Defines a physical data field in an Analytics table layout.

Syntax
DEFINE FIELD field_name data_type start_position length < decimals|date_format> <NDATETIME>
<PIC format> <AS display_name> <WIDTH characters> <SUPPRESS> < field_note>

Parameters
Name Description

field_name The name of the field.

Note
Field names are limited to 256 upper and lowercase alphanumeric char-
acters. The name can include the underscore character ( _ ), but no other
special characters, or any spaces. The name cannot start with a number.
Analytics has a number of reserved keywords that cannot be used as field
names. For a complete list, see "Reserved keywords" on page 933.

data_type The data type to use when interpreting the data. For a list of supported data types, see
"Supported data types" on page 128.
For example, invoice numbers may be stored as numeric values in the data source. To
treat these values as strings rather than numbers, you can define the field as character
data instead.

start_position The starting byte position of the field in the Analytics data file.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) data 1 byte = 1 character

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, typically you should specify an odd-numbered starting

byte position. Specifying an even-numbered starting position can cause
characters to display incorrectly.

length The length of the field in bytes.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 123 of 934

Commands

Name Description

Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) data 1 byte = 1 character

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, specify an even number of bytes only. Specifying an

odd number of bytes can cause characters to display incorrectly.

decimals The number of decimals for numeric fields.

optional

date_format The date format in the source date fields.

optional For datetime or time fields, use PIC format instead. You can also use PIC format for date
fields.
If the source data includes separators such as slashes, you must include the separators
in date_format. For example, if the source data is 12/31/2014, you must enter the format
as MM/DD/YYYY. Do not enclose date_format in quotation marks.

NDATETIME Date, datetime, or time values stored in a numeric field are treated as datetime data.
optional NDATETIME requires that you also specify the source datetime format using PIC format.

PIC format Note

optional Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in the
source data. For example, if the source data is 12/31/2014, you must
enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.

WIDTH characters The display width of the field in characters.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 124 of 934

Commands

Name Description

If you omit WIDTH, the display width is set to the field length in characters.
Note
The characters specified by WIDTH are fixed-width characters. Every char-
acter is allotted the same amount of space, regardless of the width of the
actual character.
By default, views in Analytics use a proportional width font that does not
correspond with fixed-width character spacing.
If you want a one-to-one correspondence between the WIDTH value and
the characters in the view, you can change the Proportional Font setting
in the Options dialog box to a fixed-width font such as Courier New.

SUPPRESS Only applies to numeric fields.

optional Suppresses automatic totaling of a numeric field in Analytics reports.
Totaling of some numeric fields is not appropriate. For example, a unit cost field, or a dis-
count rate field.

field_note Field note text that is added to the field definition in the table layout.
optional field_note must be last, after all other required and optional parameters. The text cannot
be multiline. Quotation marks are not required.

Examples
Defining a character field
Defines a character field called ProdDesc . The column title in the view is Product Description.

non-Unicode Analytics
l Starts at: byte 12 (character position 12)
l Length: 24 bytes (24 characters)

DEFINE FIELD ProdDesc ASCII 12 24 AS "Product Description"

Unicode Analytics, extended ASCII (ANSI) data

l Starts at: byte 12
l Length: 24 bytes (24 characters)

DEFINE FIELD ProdDesc ASCII 12 24 AS "Product Description"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 125 of 934

Commands

Unicode Analytics, Unicode data

l Starts at: byte 13
l Length: 48 bytes (24 characters)

DEFINE FIELD ProdDesc UNICODE 13 48 AS "Product Description"

Defining a numeric field

Defines a numeric field called QtyOH. In the view, the column uses the specified display format, and the
title is Quantity On Hand.
l Starts at: byte 61
l Length: 10 bytes
l Decimal places: none

DEFINE FIELD QtyOH NUMERIC 61 10 0 PIC "(9,999,999)" AS "Quantity On Hand"

Defining a datetime field from character data

From source character data, the first two examples below define a datetime field called Transaction_date.
In the source data, the date format is DD/MM/YYYY. No column title is specified, so the column title
defaults to using the field name.
l Starts at: byte 20
l Length: 10 bytes
Here, the date format is specified using date_format:

DEFINE FIELD Transaction_date DATETIME 20 10 DD/MM/YYYY

Here, the date format is specified using PIC format:

DEFINE FIELD Transaction_date DATETIME 20 10 PIC "DD/MM/YYYY"

When defining datetime fields that include time data, you must use PIC format,
The example below defines a datetime field called email_timestamp. In the source data, the datetime
format is YYYY/MM/DD hh:mm:ss-hh:mm.
l Starts at: byte 1
l Length: 25 bytes

DEFINE FIELD email_timestamp DATETIME 1 25 PIC "YYYY/MM/DD hh:mm:ss-hh:mm"

Defining a datetime field from numeric data

From source numeric data, defines a datetime field called Receipt_timestamp that has the specified

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 126 of 934

Commands

datetime format in the source data.

l Starts at: byte 15
l Length: 15 bytes

DEFINE FIELD Receipt_timestamp DATETIME 15 15 PIC "YYYYMMDD.hhmmss"

Defining a "numeric" datetime field

From source numeric data, defines a numeric field called Receipt_timestamp that has the specified dat-
etime format in the source data.
The NDATETIME parameter allows datetime values stored in the numeric field to be treated as datetime
data by Analytics.
l Starts at: byte 15
l Length: 15 bytes
l Decimal places: 6

DEFINE FIELD Receipt_timestamp PRINT 15 15 6 NDATETIME PIC "YYYYMMDD.hhmmss"

Defining a physical data field that reads mainframe Packed data

You can use the NDATETIME option to create a physical data field that reads date values from a Packed
numeric field.
Analytics cannot recognize a date in a number that is compressed into fewer bytes than one per digit and
that displays no date format. Consequently, you must unpack the number with NDATETIME to obtain the
full number of digits, then specify the date format with PIC.
To accurately indicate which numbers represent the day, the month, and the year, you specify the same
date format as the one in the Packed record layout:

DEFINE FIELD date_field_name NUMERIC 1 8 0 NDATETIME PIC "YYYYMMDD"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Overwriting fields in a script

You can overwrite a field in a table layout by defining a field that uses the same name as the existing field. If
SET SAFETY is ON, a confirmation dialog box appears before overwriting the existing field.
To avoid interrupting a script, you can SET SAFETY to OFF. The existing field is overwritten without addi-
tional confirmation.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 127 of 934

Commands

Supported data types

Data category Data type

Character ASCII

CUSTOM

EBCDIC

NOTE

PCASCII

UNICODE

Numeric ACCPAC

ACL

BASIC

BINARY

FLOAT

HALFBYTE

IBMFLOAT

MICRO

NUMERIC

PACKED

UNISYS

UNSIGNED

VAXFLOAT

ZONED

Datetime DATETIME

Logical LOGICAL

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 128 of 934

Commands

DEFINE FIELD . . . COMPUTED com-

mand
Defines a computed field in an Analytics table layout.

Syntax
To define a computed field:

DEFINE FIELD field_name COMPUTED expression

To define a computed field with optional parameters:

DEFINE FIELD field_name COMPUTED

<IF test> <STATIC> <PIC format> <AS display_name> <WIDTH characters> <SUPPRESS> < field_
note>
expression

To define a conditional computed field:

DEFINE FIELD field_name COMPUTED

*** BLANK_LINE ***
value IF condition
< value IF condition>
<...n>
default_value

To define a conditional computed field with optional parameters:

DEFINE FIELD field_name COMPUTED

<IF test> <STATIC> <PIC format> <AS display_name> <WIDTH characters> <SUPPRESS> < field_
note>
value IF condition
< value IF condition>
<...n>
default_value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 129 of 934

Commands

Note
Multiline syntax must be structured exactly as shown in the generic syntax above and the
examples below.

Parameters
Name Description

field_name The name of the computed field.

Note
Field names are limited to 256 upper and lowercase alphanumeric char-
acters. The name can include the underscore character ( _ ), but no
other special characters, or any spaces. The name cannot start with a
number.
Analytics has a number of reserved keywords that cannot be used as
field names. For a complete list, see "Reserved keywords" on page 933.

expression A valid Analytics expression that defines the value of the computed field.

STATIC The field displays the same value on every line of the table until a new value is
encountered.
optional
For example, if there is a Last Name field in the source data where:
o the first record displays the value "Smith"
o the next five records display blank lines
o the seventh record displays the value "Wong"
In this case, "Smith" displays on six consecutive lines, then "Wong" displays on the sev-
enth line.

PIC format Note

optional Applies to numeric fields only.
The display format of numeric values in Analytics views and reports.
format must be enclosed in quotation marks.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 130 of 934

Commands

Name Description

WIDTH characters The display width of the field in characters.

optional The specified value controls the display width of the field in Analytics views and reports.
The display width never alters data, however it can hide data if it is shorter than the field
length.
The display width cannot be less than the length of field_name, or display_name.
If you omit WIDTH, the display width is set to the field length in characters.
Note
The characters specified by WIDTH are fixed-width characters. Every
character is allotted the same amount of space, regardless of the width
of the actual character.
By default, views in Analytics use a proportional width font that does not
correspond with fixed-width character spacing.
If you want a one-to-one correspondence between the WIDTH value and
the characters in the view, you can change the Proportional Font setting
in the Options dialog box to a fixed-width font such as Courier New.

SUPPRESS Applies to numeric fields only.

optional Suppresses automatic totaling of numeric computed fields in Analytics reports.
Totaling of some numeric fields is not appropriate. For example, a unit cost field, or a dis-
count rate field.

value IF condition Conditional computed field only.

o value – the computed field value or expression to use if the condition evaluates to
true
o condition – the logical test that is evaluated

default_value Conditional computed field only.

The value or expression to use in the computed field if none of the conditions evaluate
to true.
Note
The decimal precision of all numeric computed values is controlled by
the precision of default_value. For example, if you specify a default value
of 0.00, all computed values are calculated to two decimal places, and
rounded if necessary. For greater precision, increase the number of
decimal places in default_value.

Examples
Defining a computed field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 131 of 934

Commands

You define a computed field named Value that is the product of the Cost and Quantity fields:

DEFINE FIELD Value COMPUTED Cost * Quantity

Defining a computed field with options

You define a computed field named Value_03, with several options defined. You include an IF condition
that limits which records are processed by the computed field:

DEFINE FIELD Value_03 COMPUTED

IF Product_Class = "03" PIC "($9,999,999.99)" AS "Value Prod Class 3" Value is cost times quantity
Cost * Quantity

Defining a conditional computed field

You define a conditional computed field named Sales_tax that calculates a different sales tax depending
on the state in which the transaction occurred. Transactions that occurred outside the three states have a
default sales tax of $0.00.
Note
The second line must be left blank because there are no optional parameters.

DEFINE FIELD Sales_tax COMPUTED

.0750 * Sale_amount IF State = "CA"

.0400 * Sale_amount IF State = "NY"
.0625 * Sale_amount IF State = "TX"
0.00

Defining a conditional computed field with options

You define a conditional computed field named Sales_tax_100 that calculates a different sales tax
depending on the state in which the transaction occurred. The field only calculates tax on amounts of $100
or greater.
Transactions that occurred outside the three states have a default sales tax of $0.00.
Note
When you specify optional parameters, do not leave any lines blank.

DEFINE FIELD Sales_tax_100 COMPUTED

IF Sale_amount >= 100
.0750 * Sale_amount IF State = "CA"
.0400 * Sale_amount IF State = "NY"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 132 of 934

Commands

.0625 * Sale_amount IF State = "TX"

0.00

Remarks
Note
For more information about how this command works, see the Analytics Help.

Two types of computed fields

There are two types of computed fields:
l standard computed field
A standard computed field performs the same calculation on every record in a table.
For example, in an Inventory table you could create a computed field that multiplies the value in the
Cost field by the value in the Quantity field to calculate the Inventory Value at Cost for each record.
l conditional computed field
A conditional computed field is capable of performing different calculations on the records in a table,
based on a set of conditions that you specify. The calculation performed on a record depends on
which condition the record meets.
For example, in a Transactions table, you could create a conditional computed field that calculates
sales tax using a rate that is adjusted based on the state in which the transaction occurred. Conditions
such as IF State = "CA" and IF State = "NY" would test each record to identify which rate to use.

Guidelines for creating a conditional computed field

Note
When defining a conditional computed field, if you do not specify any of the optional para-
meters on the second line, you must leave the second line blank .
In addition to a default value, conditional computed fields require at least one conditional value. You must
use the following multiline syntax to define a conditional computed field:
l optional parameters appear on the second line
l if there are no optional parameters, the second line must be left blank
l the first condition statement appears on the third line
l each additional condition statement requires a separate line
l the default value appears on the last line

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 133 of 934

Commands

Overwriting field definitions

You can overwrite a field definition in a table layout by defining a field that uses the same name as the exist-
ing field.
If SET SAFETY is ON, Analytics displays a confirmation dialog box before overwriting the existing field. To
avoid interrupting a script, you can SET SAFETY to OFF, and Analytics overwrites the existing field
without asking for confirmation.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 134 of 934

Commands

DEFINE RELATION command

Defines a relation between two Analytics tables.
Note
You can relate up to 18 Analytics tables and access and analyze data from any combination
of fields in the related tables as if they existed in a single table. You must specify a separate
DEFINE RELATION command for each pair of related tables.

Syntax
DEFINE RELATION key_field WITH related_table_name INDEX index_name <AS relation_name>

Parameters
Name Description

key_field The key field in the parent table.

You can select only one key field for each relation.
Note
When creating relations between parent tables and grandchild tables, you
must specify a fully qualified key field name in the format table_
name.field_name.
In "Relate three tables" on the next page, see: Vouchers.created_by

WITH related_table_name The name of the related table.

INDEX index_name The name of the index for the key field in the related table.
You must index the related table on the key field before you can relate the table.

AS relation_name A unique name for the relation.

optional By default, the name of the child table is used as the relation name. If you are defining
additional relations to the same child table, you must specify a unique name.

Examples
Relate two tables
The example below relates the open table to the Customer table by using the customer number field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 135 of 934

Commands

(CustNum ) as the key field:

DEFINE RELATION CustNum WITH Customer INDEX Customer_on_CustNum

Customer_on_CustNum is the name of the child table index on the key field. A child table index is
required when you relate tables.
If the child table index does not already exist when you run the DEFINE RELATION command, an error
message appears and the relation is not performed.
Tip
If you define a relation in the Analytics user interface, the child table index is automatically
created for you.

Create a child table index before relating two tables

If required, you can create a child table index immediately before relating two tables. The example below
shows creating an index for the Customer child table before relating the Ar table to the Customer table.

OPEN Customer
INDEX ON CustNum TO Customer_on_CustNum
Open Ar
DEFINE RELATION CustNum WITH Customer INDEX Customer_on_CustNum

Relate three tables

The example below relates three tables in the ACL_Rockwood.ACL sample project:
l Vouchers_items – the parent table
l Vouchers – the child table
l Employees – the grandchild table
By using the Vouchers table as an intermediary table in the relation, you can relate each voucher item with
the employee who processed the item.

OPEN Vouchers
INDEX ON voucher_number TO "Vouchers_on_voucher_number"
OPEN Vouchers_items
DEFINE RELATION voucher_number WITH Vouchers INDEX Vouchers_on_voucher_number
OPEN Employees
INDEX ON employee_number TO "Employees_on_employee_number"
OPEN Vouchers_items
DEFINE RELATION Vouchers.created_by WITH Employees INDEX Employees_on_employee_
number

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 136 of 934

Commands

Explanation of the syntax logic

1. Open the Vouchers table and index it on the voucher_number field.
2. Open the Vouchers_items table and relate it to the Vouchers table using voucher_number as the
key field.
3. Open the Employees table and index it on the employee_number field.
4. Open the Vouchers_items table and relate it to the Employees table using Vouchers.created_by as
the key field.
Note
Vouchers.created_by is available as a key field in the second relation because you
already related Vouchers_items and Vouchers in the first relation.

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 137 of 934

Commands

DEFINE REPORT command

Creates a new view or opens an existing view.

Syntax
DEFINE REPORT view_name

Parameters
Name Description

view_name The name of a new view or an existing view.

o new view – creates a blank view with the specified name in the open table
Any spaces in the view name are replaced with underscore characters.
o existing view – opens the specified view in the open table

Examples
Creating a new view
You create a new view called Q4_AR_review:

DEFINE REPORT Q4_AR_review

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 138 of 934

Commands

DEFINE TABLE DB command

Defines an Analytics server table by connecting to a database table using AX Connector. You can connect
to a Microsoft SQL Server, Oracle, or DB2 database.

Syntax
DEFINE TABLE DB {SOURCE database_profile <PASSWORD num> <PASSWORD num> |
SERVER server_profile <PASSWORD num>} <FORMAT format_name> SCHEMA schema
<TITLED acl_table_name> <PRIMARY|SECONDARY> DBTABLE db_tablename FIELDS {field_
names|ALL} <...n> <WHERE condition> <ORDER field_names>

Parameters
SOURCE database_profile The Analytics database profile to use to access the database engine.
Database profiles include information required to connect to the database engine, includ-
ing:
o a reference to the associated server profile
o the database type
o the database name
o user account information
Note
DEFINE TABLE DB supports connecting to only the following
databases: Microsoft SQL Server, Oracle, or DB2.

PASSWORD num The password definition to use.

optional You do not use PASSWORD num to prompt for, or specify, an actual password. The pass-
word definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2 spe-
cifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 139 of 934

Commands

The password is only required if the database profile does not contain saved passwords.
Use PASSWORD twice after the SOURCE keyword. The first password logs you on to the
server, and the second one logs you on to the database.

SERVER server_profile No longer used.

Prior to version 10.0 of Analytics, used when connecting to ACL Server Edition for z/OS.
From version 10.0 of Analytics, ACL Server Edition for z/OS is no longer included.

FORMAT format_name The name of an Analytics table, or table layout file (.layout), with a table layout that you
want to use.
optional

SCHEMA schema The schema to connect to. You must enclose the schema name in quotation marks.

TITLED acl_table_name The name of the Analytics table to create.

optional acl_table_name must be a quoted string. If you omit TITLED, Analytics uses the database
table name. When you access more than one table at a time, Analytics uses the name of
the first one.

PRIMARY | SECONDARY Use the table as either a primary or secondary table in multi-file commands. If neither
option is specified, the default value of PRIMARY is used.
optional

DBTABLE database_table The database table that you want to access. database_table must be a quoted string.

FIELDS field_names | ALL The fields to include in the output:

o FIELDS field_names – use the specified fields
field_names must be a quoted string.
o ALL – use all fields in the table
To use fields from more than one table:
a. Enter the first table name followed by the fields from that table.
b. Enter the next table name followed by the fields from that table.
c. For each additional table, repeat step b.

DBTABLE "DSN1310" FIELDS "Field_A Field_B Field_C"

DBTABLE "DSN2516" FIELDS "Field_L Field_M Field_N"

Note
Using AX Connector, you can access an unlimited number of related
tables, but no more than five is recommended. Processing time increases
when you access multiple tables.

WHERE condition An SQL WHERE clause that limits the data to those records that meet the specified con-
dition.
optional
You must use valid SQL syntax entered as a quoted string.
When you join tables, Analytics displays the condition of the join in the WHERE clause:

"Table_1.First_name = Table_2.First_name"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 140 of 934

Commands

ORDER field_names The fields the database engine uses to sort records. field_names must be a quoted string.
optional The command takes longer to run when sorting records. Only use ORDER when sorting
is important.

Examples
Example
You want to access data from a Microsoft SQL Server database via AX Connector. To do this, you use the
DEFINE TABLE DB command. You include the SOURCE parameter to connect to AX Connector through a
database profile:

DEFINE TABLE DB SOURCE "SQLServer_Audit" SCHEMA "HR" TITLED "Payroll" DBTABLE

"HR.Employee" FIELDS "EmployeeID" DBTABLE "HR.EmployeePayHistory" FIELDS "Rate PayFre-
quency" WHERE "HR.Employee.EmployeeID=HR.EmployeePayHistory.EmployeeID"

Remarks
How it works
The Analytics server table is defined as a query that uses a database profile to connect to a database table.

Suppressing the time portion of datetime values

Preface the DEFINE TABLE DB command with the SET SUPPRESSTIME command to suppress the time
portion of datetime values.
Using SET SUPPRESSTIME ON is for pre-version-10.0 Analytics scripts that assume the time portion of
datetime values will be truncated. If SET SUPPRESSTIME ON is not added to these scripts, they cannot
run in the datetime-enabled version of Analytics.
For more information, see the "SET SUPPRESSTIME" section in "SET command" on page 408.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 141 of 934

Commands

DEFINE VIEW command

Defines a new view or overwrites an existing view.

Syntax
DEFINE VIEW view_name <RLINES n> <ALL> <SUPPRESS> <SUMMARIZED> <IF test>
<WHILE test> <HEADER header_text> <FOOTER footer_text> <TO report_file_name <HTML>>
<OK>

Parameters
Name Description

view_name The name of the view to create or overwrite.

Note:
View names are limited to 64 alphanumeric characters. The name can
include the underscore character ( _ ), but no other special characters, or
any spaces. The name cannot start with a number.

RLINES n The line spacing for detail records in views and reports. By default, detail lines are
single spaced.
optional

ALL All fields in the active Analytics table layout are added to the view.
optional

SUPPRESS Suppresses blank detail lines in reports generated from the view. When the report is
generated the blank detail lines will be omitted from the output. This option applies to
optional
reports based on multiline views.

SUMMARIZED Specifies that reports generated from the view should include subtotals and totals, but
not include the detail lines.
optional
The subtotals are generated based on the break fields defined in the view. If this option
is not selected, the report includes detail lines, as well as subtotals for each of the spe-
cified break fields.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 142 of 934

Commands

Name Description

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.

optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

TO report_filename HTML The filename and type for reports created from this view.
optional Use the HTML keyword to save reports generated from this view as HTML files (.htm).
By default, generated reports are output as ASCII text files.

OK Deletes or overwrites items without asking you to confirm the action.

optional

Examples
Creating a view
You open the Ar table and create a view called AR_Report, which includes all of the fields in the table layout:

OPEN Ar
DEFINE VIEW AR_Report HEADER "AR Report" ALL OK

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 143 of 934

Commands

DELETE command
Deletes an Analytics project item, a field from a table layout, a variable, one or more table history entries, a
relation between tables, or a file in a Windows folder. Also removes a column from a view.

Syntax
Purpose Syntax

To delete an Analytics project item

DELETE item_type item_name <OK>

To delete a field from a table layout

DELETE field_name <OK>

To remove a column from a view

DELETE COLUMN view_name field_name <ALL> <OK>

To delete a variable or all variables

DELETE {variable_name|ALL} <OK>

To delete the history for the current Analytics table

DELETE HISTORY <retain_history_entries> <OK>

To delete a relation between two tables

DELETE RELATION <child_table_name|relation_name>
<OK>

To delete a file
DELETE file_name <OK>

To delete all record notes, and the auto-generated

RecordNote field, from the open table DELETE NOTES <OK>

Parameters
Name Description

item_type item_name The type and name of the item to delete.

Specify one of the following item types:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 144 of 934

Commands

Name Description

o FOLDER – the specified project folder and all its contents

o FORMAT – the specified table layout, all its views, and its associated indexes and
relations
Any other table layouts for the associated table are retained.
The data file (.fil) associated with the table layout is not deleted unless the Delete
Data File with Table option is selected in the Table tab in the Options dialog box
(Tools > Options).
You can also use the SET DELETE_FILE {ON|OFF} command in a script or on the
command line to turn this option on or off. For more information, see "SET command"
on page 408.
Caution
Use caution when turning on the Delete Data File with Table option.
It may be an original data file that is deleted along with the table lay-
out.
Data files are deleted outright. They are not sent to the Windows
Recycle Bin.
o REPORT – the specified view
You cannot delete a view if it is currently active.
o COLUMN – the specified column
o SCRIPT (or BATCH) – the specified script
o WORKSPACE – the specified workspace
o INDEX – the specified index
o NOTES – all record notes from the open table, and the RecordNote field from the
table layout

field_name ALL Delete a field

The name of the field to delete from the current Analytics table layout.
You can delete a field from a table layout even if the field is included in the current view.
Note
You cannot delete a field referenced by a computed field unless you first
delete the computed field.

Remove a column
The name of the column to remove from the specified view.
Note
Use the physical field name, not the column display name.
o ALL included – removes all occurrences of the column in the view
o ALL omitted – removes the first (leftmost) occurrence of the column in the view

view_name The name of the view to remove a column from.

variable_name | ALL The name of the variable to delete. Use ALL to delete all variables.
If you specify ALL, all occurrences of the following types of the variables are deleted

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 145 of 934

Commands

Name Description

from the project:

o system variables
o temporary user-defined variables
o permanent user-defined variables
Note
You cannot delete a variable referenced by a computed field unless you
first delete the computed field.

HISTORY retain_history_ Deletes all table history entries except for the number of most recent entries specified by
entries retain_history_entries.
Omit retain_history_entries to delete all entries.

RELATION child_table_ Deletes any relation that has no dependent relations and no related fields referenced in
name | relation_name either the active view or in an active computed field.
Use the options to specify which relation to delete:
o child_table_name – use when the relation was not specifically named (default name
when a relation is created)
o relation_name – use when the relation was specifically named when it was created.
Otherwise, use child_table_name
If you do not use either option, the last relation that was defined gets deleted.

file_name The name of a physical file to delete.

You can specify an absolute or relative path to a file you want to delete. If the path has
spaces, enclose it in double quotation marks.

OK Deletes items without presenting a confirmation dialog box.

optional

Examples
Deleting a date field
You delete the Date field from the table layout associated with the Ar table:

OPEN Ar
DELETE Date

Deleting multiple columns from a view

You delete two columns from the AR_Report view associated with the Ar table. You specify OK for both
DELETE commands so that no confirmation prompt is displayed when the script runs:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 146 of 934

Commands

OPEN Ar
DELETE COLUMN AR_Report Date OK
DELETE COLUMN AR_Report Invoice_Date OK

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 147 of 934

Commands

DIALOG command
Creates a custom dialog box that interactively prompts users for one or more script input values. Each
input value is stored in a named variable.
Note
Using the DIALOG command to enter passwords is not secure. You should use the
"PASSWORD command" on page 350 instead.
The DIALOG command is not supported in AX Server analytics.
You can create a basic interactive dialog box with the "ACCEPT command" on page 54.
Tip
The easiest way to create custom dialog boxes is with the Dialog Builder. For more
information, see Creating custom dialog boxes.

Syntax
DIALOG (DIALOG TITLE title_text WIDTH pixels HEIGHT pixels) (BUTTONSET TITLE
"&OK;&Cancel" AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels> DEFAULT item_num <HORZ>)
<[label_syntax]|[text_box_syntax]|[check_box_syntax]|[radio_button_syntax]|[drop_down_list_syn-
tax]|[project_item_list_syntax]> <...n>

label_syntax ::=
(TEXT TITLE title_text AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels> <CENTER|RIGHT>)

text_box_syntax ::=
(EDIT TO var_name AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels> <DEFAULT string>)

check_box_syntax ::=
(CHECKBOX TITLE title_text TO var_name AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels>
<CHECKED>)

radio_button_syntax ::=
(RADIOBUTTON TITLE value_list TO var_name AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels>
<DEFAULT item_num> <HORZ>)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 148 of 934

Commands

drop_down_list_syntax ::=
(DROPDOWN TITLE value_list TO var_name AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels>
<DEFAULT item_num>)

project_item_list_syntax ::=
(ITEM TITLE project_item_category TO var_name AT x_pos y_pos <WIDTH pixels> <HEIGHT pixels>
<DEFAULT string>)

Parameters
General parameters
Name Description

DIALOG TITLE title_text Creates the main dialog box and the dialog box title.
title_text must be specified as a quoted string.

BUTTONSET TITLE The labels for the OK and Cancel buttons in the dialog box.
"&OK;&Cancel"
The values should normally not be edited, but if you do edit the values make sure that the
positive value comes before the negative value. For example: "&Yes;&No"

WIDTH pixels The width of the individual control, or the width of the dialog box if specified for the
DIALOG control.
The value is specified in pixels. If no value is specified for a control the width is calculated
based on the longest value contained by the control.

HEIGHT pixels The height of the individual control, or the height of the dialog box if specified for the
DIALOG control.
The value is specified in pixels.

AT x_posy_pos The location of the top left corner of the control in the custom dialog box:
o x_pos is the horizontal distance in pixels from the left-hand side of the dialog box
o y_pos is the vertical distance in pixels from the top of the dialog box

DEFAULT item_num The numeric value that corresponds to the BUTTONSET value that you want to select as
the default.
For example, if the BUTTONSET values are "&OK;&Cancel", specify DEFAULT 1 to select
OK by default.

HORZ Displays the values for the BUTTONSET control horizontally. Values are displayed ver-
tically by default.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 149 of 934

Commands

Note
For most of the control types, the DIALOG command creates a variable to store user
input. You cannot use non-English characters, such as é, in the names of variables that
will be used in variable substitution. Variable names that contain non-English characters
will cause the script to fail.
By default, some of the DIALOG variables are created as character variables. If you use a
character variable to store numeric or datetime values, you must convert the variable to
the required data type in subsequent processing in a script. For more information, see
"Input data type" on page 154.

Label parameters
Name Description

TEXT Creates a text label to identify, notify, or instruct.

TITLE title_text The control label.

title_text must be specified as a quoted string.

CENTER | RIGHT The alignment of the text in the control.

optional If you omit CENTER or RIGHT, left alignment is used by default.

Text box parameters

Name Description

EDIT Creates a text box for user input.

TO var_name The name of the character variable that stores the input specified by the user.
If the variable already exists, the specified value is assigned. If the variable does not
exist, it is created, and the specified value is assigned.

DEFAULT string The default text string to display in the control.

optional string must be specified as a quoted string.

Check box parameters

Name Description

CHECKBOX Creates a check box to present an option to the user.

TITLE title_text The control label.

title_text must be specified as a quoted string.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 150 of 934

Commands

Name Description

TO var_name The name of the logical variable that stores the True or False value specified by the
user.
If the variable already exists, the specified value is assigned. If the variable does not
exist, it is created, and the specified value is assigned.

CHECKED Sets the control to checked by default.

optional

Radio button parameters

Name Description

RADIOBUTTON Creates radio buttons to present mutually exclusive options to the user.

TITLE value_list The list of values displayed for the control.

The values must be specified as a quoted string. Separate each value with a semi-colon
(;).

TO var_name The name of the numeric variable that stores the numeric position of the radio button
value selected by the user.
If the variable already exists, the specified value is assigned. If the variable does not
exist, it is created, and the specified value is assigned.

DEFAULT item_num The numeric value that corresponds to the list item that you want to select as the default.
optional For example, if value_list is "Red;Green;Blue", specify DEFAULT 2 to select Green by
default.

HORZ Displays the values for the control horizontally. Values are displayed vertically by default.
optional

Drop-down list parameters

Name Description

DROPDOWN Creates a drop-down list to present a list of options to the user.

TITLE value_list The list of values displayed for the control.

The values must be specified as a quoted string. Separate each value with a semi-colon
(;).

TO var_name The name of the character variable that stores the drop-down list value selected by the
user.
If the variable already exists, the specified value is assigned. If the variable does not

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 151 of 934

Commands

Name Description

exist, it is created, and the specified value is assigned.

Project item list parameters

Name Description

ITEM Creates a project item list to present a list of Analytics project items, such as fields, to the
user.

TITLE project_item_cat- The category of project item to include in the control.

egory
You can specify one or more categories. The user can select a single value from the pro-
ject item list.
Enclose project_item_category in quotation marks, with no space or punctuation
between categories.
For the codes used to specify categories, see "Codes for project item categories" on the
facing page.
Note
Do not mix dissimilar categories in the same ITEM control, unless you
have a reason for doing so. For example, do not mix tables and fields.
The resulting project item list is potentially confusing for the user.

TO var_name The name of the character variable that stores the name of the project item selected by
the user.
If the variable already exists, the specified value is assigned. If the variable does not
exist, it is created, and the specified value is assigned.

DEFAULT string The exact name of the project item that you want to select as the default.
optional string must be specified as a quoted string.

Examples
Prompting the user for a table and script
In your script, you need to prompt the user to select the Analytics table and script to use to run an analysis .
You specify that the Metaphor_Inventory_2012 table from the ACL_Demo.acl project is selected by
default as the Analytics table, but the user can select any table in the project.
The script to run must also be selected from the list of scripts in the Analytics project:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 152 of 934

Commands

DIALOG (DIALOG TITLE "Inventory analysis" WIDTH 500 HEIGHT 200 ) (BUTTONSET TITLE
"&OK;&Cancel" AT 370 12 DEFAULT 1 ) (TEXT TITLE "Choose the Analytics project items to analyze."
AT 50 16 ) (TEXT TITLE "Table:" AT 50 50 ) (ITEM TITLE "f" TO "v_table" AT 50 70 DEFAULT "Meta-
phor_Inventory_2012" ) (TEXT TITLE "Script:" AT 230 50 ) (ITEM TITLE "b" TO "v_script" AT 230 70 )

Remarks
Note
For more information about how this command works, see the Analytics Help.

Interactivity
Use DIALOG to create an interactive script. When the DIALOG command is processed, the script pauses
and a dialog box is displayed that prompts the user for input that Analytics uses in subsequent processing.
You can create separate dialog boxes that prompt for one item at a time, or you can create one dialog box
that prompts for multiple items.

ACCEPT versus DIALOG
The ACCEPT command allows you to create a basic interactive dialog box that can have one or more of the
following types of controls:
l text box
l project item list
For basic interactivity, ACCEPT may be all you need. For more information, see "ACCEPT command" on
page 54.

Codes for project item categories

Use the following codes to specify the category of project item to display in a project item list.

Project categories

Code Category

f Tables

b Scripts

i Indexes

r Views and reports

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 153 of 934

Commands

Code Category

w Workspaces

Field categories

Code Category

C Character fields

N Numeric fields

D Datetime fields

L Logical fields

Variable categories

Code Category

c Character variables

n Numeric variables

d Datetime variables

l Logical variables

Input data type

Some of the controls in the DIALOG command store user input in character variables. If you need numeric
or datetime input, you can use the VALUE( ) or CTOD( ) functions to convert the contents of a character
variable to a numeric or datetime value:

SET FILTER TO BETWEEN(%v_date_field%, CTOD(%v_start_date%), CTOD(%v_end_date%))

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 154 of 934

Commands

Position of the DIALOG command

It is good practice to place all DIALOG commands at the beginning of a script, if possible. If you ask for all
input at the beginning, the script can then run unimpeded once the user enters the necessary information.
Note
You cannot use the DIALOG command inside the GROUP command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 155 of 934

Commands

DIRECTORY command
Generates a list of files and folders in the specified directory.

Syntax
DIRECTORY < file_spec> <SUPPRESS> <SUBDIRECTORY> <APPEND> <TO table_name|file-
name>

Parameters
Name Description

file_spec The Windows folder or files to list and display information for.
optional You can use the asterisk wildcard (*) to list all files with a particular extension, all files
that start with a particular string, or all files in a folder. For example:
o *.fil – lists all files with the .fil extension (Analytics data files)
o Inv*.* – lists all files that begin with "Inv" regardless of what file extension they have
o Results\* or Results\*.* – lists all files in the Results folder
To limit the files listed to a particular folder, you can specify a path relative to the Ana-
lytics project folder, or specify a full path. For example:
o Results\*.* – displays the contents of the Results subfolder in the Analytics project
folder
o C:\ACL Data\Results\*.* – displays the contents of the specified folder
Note
The wildcard character cannot be used in intermediary levels of a spe-
cified file path. It can only be used in the final level of the path, as shown
above.
Paths or file names that contain spaces must be enclosed in double quo-
tation marks.
If you use file_spec, it must be placed before any of the other parameters. If file_spec
appears in any other position, the DIRECTORY command is not processed and an error
is generated.
If you omit file_spec, all files in the folder containing the Analytics project are listed. You
cannot use any of the other parameters if you omit file_spec.

SUPPRESS Suppresses path information in the output, leaving only the file names and properties.
optional

SUBDIRECTORY Includes the contents of subfolders in the directory listing.

optional For example, if file_spec specifies Results\*.fil, the Results folder, and all sub-

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 156 of 934

Commands

Name Description

folders contained in the Results folder, are searched for .fil files.
Depending on the number of subfolders and files that need to be listed, using
SUBDIRECTORY may result in a delay while the subfolders are searched. Analytics dis-
plays a dialog box showing progress of the command.

TO table_name | filename The location to send the results of the command to:
optional o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Output.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
If you omit TO, the directory listing appears in the Analytics display area.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 157 of 934

Commands

Examples
Different options for listing files
The ability to list files is useful for ad hoc investigation, and for incorporating in scripting.
A number of different options for listing files with the DIRECTORY command appear below.

List all files

Lists all the files in the folder containing the Analytics project:

List all the files of a specific type

Lists all the .fil files (Analytics data files) in the folder containing the Analytics project:

DIRECTORY *.fil

Use wildcards to list files

Lists all the file names beginning with "Inv" in the folder containing the Analytics project:

DIRECTORY Inv*.*

List all the files in a subfolder relative to the Analytics project folder
Lists all the files in the Results subfolder in the folder containing the Analytics project:

DIRECTORY "Results\*"

List all the files in a specified folder

Lists all the files in the Results subfolder:

DIRECTORY "C:\ACL Data\Results\*"

List all the files of a specific type in a specified location

Lists all the .fil files (Analytics data files) in the specified folder and any subfolders:

DIRECTORY "C:\ACL Data\Results\*.fil" SUBDIRECTORY

List all the files in a specified folder and output the list to an Analytics table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 158 of 934

Commands

Lists all the files in the Results folder and outputs the list to an Analytics table in the folder containing the
Analytics project:

DIRECTORY "C:\ACL Data\Results\*" TO Results_Folder_Contents.fil

The new table Results_Folder_Contents is added to the open project.

List all the files in one folder and output the list to an Analytics table in
another folder
Lists all the files in the ACL Data\Results folder and outputs the list to an Analytics table in the GL
Audit 2014\Results folder:

DIRECTORY "C:\ACL Data\Results\*" TO "C:\ACL Projects\GL Audit 2014\Results\Results_Folder_

Contents.fil"

The new table Results_Folder_Contents is added to the open project. The associated data file (Res-
ults_Folder_Contents.fil) is created in the specified output folder, which may or may not be the
folder containing the Analytics project.

Remarks
Properties displayed by DIRECTORY
The DIRECTORY command is similar to the DIR command in Windows. In addition to listing files and sub-
folders in a folder, the DIRECTORY command also displays the following file and folder properties:

o File Size o Create Date o Access Date o Modified Date

o Attributes o Create Time o Access Time o Modified Time
o the total number of files
and folders that match
the specified criteria

Uses for DIRECTORY in a script

When used in a script, the DIRECTORY command provides the ability to examine the file system. For
example, you could use DIRECTORY in conjunction with other commands to detect the presence or
absence of files, check a file's size, or make decisions based on other file properties.

Outputting the results of DIRECTORY

You can run the command from the command line to display a directory listing on screen, or save the listing
to an Analytics table or .txt file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 159 of 934

Commands

How to open table-based results of DIRECTORY

The DIRECTORY command does not include the OPEN parameter. If you are using the command in a
script and outputting the results to an Analytics table, and you want to open the resulting table, follow the
DIRECTORY command with the OPEN command. For example:

DIRECTORY "C:\ACL Data\Results\*" TO Results_Folder_Contents.fil

OPEN Results_Folder_Contents

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 160 of 934

Commands

DISPLAY command
Displays information about the specified Analytics item type. Can also display the result of an expression, or
the output of a function.

Syntax and parameters

Syntax Purpose

Displays the field definitions, and any related child tables, for the currently
DISPLAY active Analytics table.

Displays a list of open Analytics tables and project files.

DISPLAY OPEN
o Analytics tables – displays the name of the source data file, not the table
layout name.
o multiple-table mode – the source data file identified as PRIMARY is asso-
ciated with the currently active table.
o related tables – if the parent table is open, displays the source data file for
both the parent and the child tables, even if the child table is not open in
the View tab.

Displays the name and table layout information for the primary or secondary
DISPLAY table.
{<PRIMARY>|SECONDARY}
o PRIMARY (or no keyword specified) – display information for the currently
active table.
o SECONDARY – display information for the secondary table.
In multiple-table mode, SECONDARY refers to the secondary table asso-
ciated with the currently active table.
The information displayed includes:
o the table layout name
o the source data file name
o any relations between the table and other tables
o the field definition information from the table layout

Displays the table history for the currently active Analytics table.
DISPLAY HISTORY
Note
A table may or may not have associated table history.

Displays relation information for the currently active Analytics table:

DISPLAY RELATION
o the names of any child tables
o key field names
o index names

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 161 of 934

Commands

Syntax Purpose

Displays the value of a single variable or all variables.

DISPLAY {variable_
name|VARIABLES} o variable_name – the name of a single variable to display the value of.
o VARIABLES – display the values of all system and user-defined variables,
and the remaining memory available to store variables.

Displays information in the following format about the installed version of

DISPLAY VERSION Analytics:
o Version – major version number.minor version number
o Patch – patch number
o Type – 000 (non-Unicode), or 001 (Unicode) edition of Analytics
o Build – software build number

Displays the current operating system date and time.

DISPLAY {DATE|TIME}
DATE | TIME – specify either keyword. The two keywords do the same thing.

Displays the amount of physical memory (RAM) available for use by Ana-
DISPLAY {FREE|SPACE} lytics.
The amount displayed does not include memory reserved for variables. By
default, Analytics reserves 60 KB of physical memory to store variables, but
the amount is automatically increased as necessary.
FREE | SPACE – specify either keyword. The two keywords do the same
thing.

Displays the result of an expression.

DISPLAY expression
expression – the expression to display the result of.

Displays the output of a function.

DISPLAY function
function – the function to display the output of.

Examples
Display the layout of an Analytics table
Displaying the layout of a table can be useful in a number of circumstances. For example, you may want to
combine two or more tables, and you need to examine field lengths and data types.
The example below displays the layout of the Ap_Trans table:

OPEN Ap_Trans
DISPLAY

The DISPLAY command produces the output to screen shown below.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 162 of 934

Commands

Note
If you enter DISPLAY directly in the Analytics command line, the output appears imme-
diately.
If you run DISPLAY in a script, double-click the corresponding DISPLAY entry in the com-
mand log to display the output.

Output to screen
Relationship
'Vendor' related by 'Vendor_No' using index 'Vendor_on_Vendor_No'
File
'Ap_Trans.fil' (format 'Ap_Trans') is your PRIMARY file.
The record length is 59
Fields

Name Type Start Length Decimals Field explanation

Vendor_No ASCII 1 5 AS "Vendor;Number" WIDTH 7

Invoice_No ASCII 6 15 AS "Invoice;Number"

Invoice_Date DATETIME 21 8 PICTURE "MM/DD/YY" AS "Invoice;Date" WIDTH 8

Invoice_ NUMERIC 29 12 2 PICTURE "(9,999,999.99)" AS "Invoice;Amount"

Amount WIDTH 12

Prodno ASCII 41 9 AS "Product;Number"

Quantity MICRO 50 4 0 PICTURE "(9,999,999)"

Unit_Cost NUMERIC 54 6 2 PICTURE "(9,999,999)" AS "Unit;Cost" SUPPRESS

Display the values of all variables in an Analytics project

DISPLAY VARIABLES generates the same information that appears in the Variables tab in the Navigator.
One benefit of using DISPLAY VARIABLES is that you can copy-and-paste the displayed information.
The example below creates two user-defined variables and two system variables and then displays the val-
ues of the variables:

ASSIGN v_table_name = "Ap_Trans"

ASSIGN v_field_name = "Invoice_Amount"
OPEN %v_table_name%
TOTAL FIELDS %v_field_name%
DISPLAY VARIABLES

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 163 of 934

Commands

The DISPLAY command produces the output to screen shown below.

Note
If you enter DISPLAY VARIABLES directly in the Analytics command line, the output
appears immediately.
If you run DISPLAY VARIABLES in a script, double-click the corresponding DISPLAY
VARIABLES entry in the command log to display the output.

Output to screen

Name Type Value

TOTAL1 N 278,641.33

OUTPUTFOLDER C "/Tables/Accounts_Payable"

v_field_name C "Invoice_Amount"

v_table_name C "Ap_Trans"

Display the result of an expression

For the selected record, the example below displays the result of multiplying the value in the Sale_Price
field by the value in the Quantity_on_Hand field:

DISPLAY Sale_Price * Quantity_on_Hand

Display the output of a function

For the selected record, the example below displays the number of days that have elapsed since the date
in the Invoice_Date field:

DISPLAY AGE(Invoice_Date)

Remarks
Location of command results
DISPLAY run from the Analytics command line – the results are displayed on screen.
DISPLAY executed in a script – the results are written to the Analytics command log. You can double-
click the command log entry to display the results on screen.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 164 of 934

Commands

DO REPORT command
Generates the specified Analytics report.

Syntax
DO REPORT report_name

Parameters
Name Description

report_name The name of the view to generate and print as a report.

Example
Printing the default view
You open the AP_Trans table and print the default view:

OPEN AP_Trans
DO REPORT Default_View

Remarks
Running DO REPORT on the command line vs in a script
The settings used to print the report depend on where you run the command:
l from the command line – the Print dialog box opens for you to select the pages to print and configure
other options for the report
l in a script – the report is printed immediately using the default settings for the report

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 165 of 934

Commands

DO SCRIPT command
Executes a secondary script, or an external script, from within an Analytics script.

Syntax
DO <SCRIPT> script_name {<IF test>|<WHILE test>}

Parameters
Name Description

SCRIPT script_name The name of the script to run. You can run secondary scripts in the Analytics project, or
external scripts stored in text files with extensions such as .aclscript, .txt. or .bat.
You can specify a file path to an external script. You must enclose the path in quotation
marks if it contains any spaces.
Note
You cannot call a script that is already running. For example, if ScriptA
calls ScriptB, ScriptB cannot call ScriptA. ScriptA is still running while it
waits for ScriptB to complete.

IF test A conditional expression that is evaluated one time to determine if the script should be
executed. If the condition evaluates to true the script runs, otherwise it does not.
optional
Cannot be used with WHILE in the same command. If both are used, WHILE is ignored
when the script is processed. A comment is entered in the log, but the script does not
stop executing.

WHILE test A conditional expression that is evaluated after the script runs to determine if the script
should be executed again. If the test evaluates to true the script runs again, otherwise it
optional
does not.
Note
If you use WHILE, ensure that your test eventually evaluates to false. If
you do not, the script enters an infinite loop. In case of an infinite loop,
press the Esc key to cancel script processing.
Cannot be used with IF in the same command. If both are used, WHILE is ignored when
the script is processed. A comment is entered in the log, but the script does not stop
executing.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 166 of 934

Commands

Examples
Executing a subscript repeatedly until the input is validated
You have a subscript that gathers user input using a dialog box. It does the following:
1. Prompts the user for the required values.
2. Checks the user input.
3. Sets the v_validated variable to true when the input values are validated.
To ensure that the user enters valid input, you use DO SCRIPT and include a WHILE condition so that the
script repeats this command until input is validated. Once the value of the variable changes, the main script
moves on to the next command:

DO SCRIPT GetUserInput WHILE v_validated = F

Running a subscript from a shared location

You maintain utility subscripts in a shared location. When you require one of the subscripts during an ana-
lysis, you reference it using the full path to the shared location:

DO SCRIPT "C:\My utility scripts\GetUserInput.aclscript" WHILE v_validated = F

Remarks
Related commands
DO SCRIPT is the equivalent of the DO BATCH command found in scripts created with earlier releases of
Analytics.
You cannot include the DO SCRIPT command inside a GROUP command.

Usefulness of an external script

Storing a script externally and calling it from within an Analytics script is useful if you want to reuse the same
subscript in different Analytics scripts and projects.
You can store a single copy of the script in one location, and make updates to it in one place, rather than
maintaining it in multiple locations.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 167 of 934

Commands

DUMP command
Displays the contents of a file, or the current record, in hexadecimal, ASCII, and EBCDIC character encod-
ings.
Note
This command can only be entered in the command line. It cannot be used in scripts.

Syntax
DUMP {RECORD|file_name} <SKIP bytes> <COLUMN bytes> <HORIZONTAL>

Parameters
Name Description

RECORD Displays the contents of the selected record.

Required if you do not specify a file_name.

file_name The name of the file you want to display.

Required if you do not specify RECORD.
Note
To display the character encodings for an Analytics table you must spe-
cify the name of the source data file and the file extension. For example:
Ap_Trans.fil

SKIP bytes The number of bytes to bypass before the dump begins. The default is 0.
optional

COLUMN bytes In the output, the width of the columns in bytes.

optional Note
The number specified by bytes refers to the bytes contained by the
Analytics record or table.
The encoded characters in the output may not have a one-to-one rela-
tion with the characters in the view. For example, the hexadecimal
encoding for the number 1 is 31.
The default is 16 bytes for each column in a vertical display, and 64 bytes for the single
column in a horizontal display. The maximum number of bytes you can specify is 255.

HORIZONTAL Displays the character encodings in horizontal rows rather than in side-by-side vertical
blocks (the default).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 168 of 934

Commands

Name Description

optional

Examples
Display the character encoding of the Inventory table
The example below displays the hexadecimal, ASCII, and EBCDIC character encoding of the data in the
Inventory table. The output is arranged in horizontal rows (hexadecimal encoding uses a double row). Each
row represents 97 bytes of data in the Analytics table:

DUMP Inventory.fil COLUMN 97 HORIZONTAL

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 169 of 934

Commands

DUPLICATES command
Detects whether duplicate values or entire duplicate records exist in an Analytics table.

Syntax
DUPLICATES <ON> {key_field <D> <...n>|ALL} <OTHER field <...n>|OTHER ALL>
<UNFORMATTED> <TO {SCREEN|table_name|filename|PRINT}> <APPEND> <IF test> <WHILE
test> <FIRST range|NEXT range> <HEADER header_text> <FOOTER footer_text> <PRESORT>
<OPEN> <LOCAL> <ISOLOCALE locale_code>

Parameters
Name Description

ON key_field D <...n> The key field or fields, or the expression, to test for duplicates.
| ALL o key_field – use the specified field or fields
If you test by more than one field, records identified as duplicates require identical
values in every specified field.
Include D to sort the key field in descending order. The default sort order is ascend-
ing.
o ALL – use all fields in the table
If you test by all the fields in a table, records identified as duplicates must be entirely
identical.
An ascending sort order is the only option for ALL.
Note
Undefined portions of records are not tested.

UNFORMATTED Suppresses page headings and page breaks when the results are output to a file.
optional

TO SCREEN | table_ The location to send the results of the command to:
name | filename | PRINT o SCREEN – displays the results in the Analytics display area
optional o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Output.FIL"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 170 of 934

Commands

Name Description

By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o PRINT – sends the results to the default printer

WHILE test A conditional expression that must be true in order to process each record. The com-
mand is executed until the condition evaluates as false, or the end of the table is
optional
reached.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 171 of 934

Commands

Name Description

Note
If you use WHILE in conjunction with FIRST or NEXT, record processing
stops as soon as one limit is reached.

FIRST range | NEXT range The number of records to process:

HEADER header_text The text to insert at the top of each page of a report.
optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

PRESORT Sorts the table on the key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

ISOLOCALE locale_code Note

optional Applicable in the Unicode edition of Analytics only.
The system locale in the format language_ country. For example, to use Canadian
French, enter fr_ca.
Use the following codes:
o language – ISO 639 standard language code
o country – ISO 3166 standard country code
If you do not specify a country code, the default country for the language is used.
If you do not use ISOLOCALE, the default system locale is used.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 172 of 934

Commands

Analytics output variables

Name Contains

GAPDUPn The total number of gaps, duplicates, or fuzzy duplicate groups identified by the com-
mand.

Examples
Test for duplicate values in one field
The following example:
l tests for duplicate values in the Invoice_Number field
l outputs any records that contain duplicate invoice numbers to a new Analytics table

DUPLICATES ON Invoice_Number OTHER Vendor_Number Invoice_Date Invoice_Amount

PRESORT TO "Duplicate_Invoices.FIL"

Test for duplicate values in two or more fields in combination

The following example:
l tests for duplicate combinations of values in the Invoice_Number and Vendor_Number fields
l outputs any records that contain the same invoice number and the same vendor number to a new
Analytics table
The difference between this test and the previous test is that a identical invoice number from two different
vendors is not reported as a false positive.

DUPLICATES ON Invoice_Number Vendor_Number OTHER Invoice_Date Invoice_Amount

PRESORT TO "Duplicate_Invoices.FIL"

Test for duplicate records

The following examples:
l test for duplicate values in every field in an Inventory table
l output any entirely identical records to a new Analytics table

DUPLICATES ON ProdNum ProdClass Location ProdDesc ProdStatus UnitCost CostDate SalePrice

PriceDate PRESORT TO "Duplicate_Inventory_Items.FIL"

You can simplify the syntax by using ALL :

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 173 of 934

Commands

DUPLICATES ON ALL PRESORT TO "Duplicate_Inventory_Items.FIL"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 174 of 934

Commands

ESCAPE command
Terminates the script being processed, or all scripts, without exiting Analytics.

Syntax
ESCAPE <ALL> <IF test>

Parameters
Name Description

ALL Terminates all active scripts. If omitted, the current script is terminated.
optional

IF test A test that must evaluate to true before the command is executed. If the test evaluates to
false the command does not run.
optional

Examples
Terminating a script conditionally
You count the number of records in a table, and use the ESCAPE command to terminate the script if the
number of records is less than 100:

COUNT
ESCAPE IF COUNT1 < 100

Remarks
When to use ESCAPE
Use ESCAPE to halt the execution of a script or subscript based on a condition, or to stop the execution of
all running scripts.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 175 of 934

Commands

Using ESCAPE in subscripts

If you execute ESCAPE inside a subscript, then the subscript stops executing and the main script resumes
processing from the DO SCRIPT command that invoked the subscript.
If you include the ALL option in the ESCAPE command in the subscript, then both the subscript and the
main script stop processing:

ESCAPE ALL

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 176 of 934

Commands

EVALUATE command
For record sampling or monetary unit sampling, projects errors found in sampled data to the entire pop-
ulation, and calculates upper limits on deviation rate, or misstatement amount.
Record samplingMonetary unit sampling

Syntax
EVALUATE RECORD CONFIDENCE confidence_level SIZE sample_size ERRORLIMIT number_
of_errors <TO {SCREEN|filename}>

Parameters
Note
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

RECORD Evaluate errors found in a record sample.

CONFIDENCE con- The same confidence level that you specified when you calculated the sample size.
fidence_level

SIZE sample_size The number of records in the sample.

Note
Specify the actual sample size as drawn, which might differ from the
sample size initially calculated by Analytics.

ERRORLIMIT number_of_ The total number of errors, or deviations, that you found in the sample.
errors

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 177 of 934

Commands

Analytics output variables

Name Contains

MLEn The Upper error limit frequency rate (computed upper deviation rate) calculated by the
command.

Examples
Project errors found in the sampled data to the entire population
You have completed your testing of the sampled data and recorded the control deviations you found. You
can now project the errors you found to the entire population.
The example below projects two errors found in the sampled data to the entire population, and calculates
an upper error limit frequency rate (computed upper deviation rate) of 6.63%.

EVALUATE RECORD CONFIDENCE 95 SIZE 95 ERRORLIMIT 2 TO SCREEN

For a detailed explanation of how Analytics calculates values when evaluating errors, see Evaluating
errors in a record sample.

Remarks
Note
For more information about how this command works, see the Analytics Help.

Syntax
EVALUATE MONETARY CONFIDENCE confidence_level <ERRORLIMIT book_value, mis-
statement_amount <,...n>> INTERVAL interval_value <TO {SCREEN|filename}>

Parameters
Note
Do not include thousands separators, or percentage signs, when you specify values.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 178 of 934

Commands

Name Description

MONETARY Evaluate errors found in a monetary unit sample.

CONFIDENCE con- The same confidence level that you specified when you calculated the sample size.
fidence_level

ERRORLIMIT book_ All misstatement errors that you found in the sample.
value,misstatement_
Specify the book value of the amount and the misstatement amount, separated by a
amount
comma. For example, if an amount has a book value of $1,000 and an audit value of
$930, specify 1000,70.
Specify overstatements as positive amounts, and understatements as negative amounts.
For example, if an amount has a book value of $1,250 and an audit value of $1,450, spe-
cify 1250,-200.
Separate multiple book_value, misstatement_amount pairs with a comma:

1000,70,1250,-200

INTERVAL interval_value The interval value that you used when you drew the sample.
Note
The interval value that you used might differ from the interval value initially
calculated by Analytics.

Analytics output variables

Name Contains

MLEn The Most Likely Error amount (projected misstatement) calculated by the command.

UELn The Upper Error Limit amount (upper misstatement limit) calculated by the command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 179 of 934

Commands

Examples
Project errors found in the sampled data to the entire population
You have completed your testing of the sampled data and recorded the misstatements you found. You
can now project the errors you found to the entire population.
The example below projects three errors found in the sampled data to the entire population, and calculates
several values, including:
l Basic Precision – the basic allowance for sampling risk (18,850.00)
l Most Likely Error – the projected misstatement amount for the population (1,201.69)
l Upper Error Limit – the upper misstatement limit for the population (22,624.32)

EVALUATE MONETARY CONFIDENCE 95 ERRORLIMIT 1000,70,1250,-200,3200,900

INTERVAL 6283.33 TO SCREEN

For a detailed explanation of how Analytics calculates values when evaluating errors, see Evaluating
errors in a monetary unit sample.

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 180 of 934

Commands

EXECUTE command
Executes an application or process external to Analytics. Emulates the Windows Run command. Can be
used to interact with the Windows command prompt.
Note
Because the EXECUTE command gives you the ability to interact with the operating sys-
tem and applications external to Analytics, technical issues may arise that are beyond the
scope of Analytics's native functionality.
Support can assist with operation of the EXECUTE command inside Analytics, but issues
that arise with processes and applications external to Analytics are not covered under Sup-
port.

Syntax
EXECUTE Windows_Run_command_syntax <ASYNC>

Parameters
Name Description

Windows_Run_com- The name of the application to execute, the folder or file to open, or the command to run,
mand_syntax followed by any required arguments or command switches.
Requires valid Windows Run command syntax enclosed by quotation marks.

ASYNC Runs the command in asynchronous mode.

optional In asynchronous mode, the Analytics script continues running without waiting for the pro-
cess started by the EXECUTE command to complete.
If you omit ASYNC, then the process started by the EXECUTE command must complete
before the Analytics script continues. Analytics is inaccessible while external processes
are running.
Note
When running EXECUTE from the Analytics command line, you must spe-
cify ASYNC.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 181 of 934

Commands

Analytics output variables

Name Contains

RETURN_CODE The code returned by an external application or process run using the EXECUTE com-
mand.

What are return codes?

Return codes are numbers generated by the external application or process and sent
back to Analytics to indicate the outcome of the external process. Analytics does not gen-
erate the return code, it only receives it.

Typical return codes

Typical return codes are integer values that map to specific notifications or error mes-
sages. For example, the return code "0" could mean "The operation completed suc-
cessfully". The return code "2" could mean "The system cannot find the file specified".

The meaning of specific return codes

Specific return codes and their meanings vary depending on the external application or
process. Lists of return codes, also called 'error codes' or 'exit codes', and their mean-
ings, can often be found in the documentation for the associated external application.
Lists of return codes can also be found on the Internet.

Variable created in default mode only

The RETURN_CODE variable is created when the EXECUTE command is run in
default mode. The variable is not created when the command is run in asynchronous
mode.

Examples
Open an application
Opens Microsoft Excel:

EXECUTE "Excel"

Opens Adobe Acrobat Reader:

EXECUTE "AcroRd32.exe"

Close an application
Closes Microsoft Excel:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 182 of 934

Commands

EXECUTE "TASKKILL /f /im Excel.exe"

Note
Use the /f switch with caution. It forces an application to close without presenting any dialog
boxes, such as those for saving changes.

Open a file
Opens the Excel workbook AP_Trans.xlsx:

EXECUTE '"C:\ACL Projects\Source Data\AP_Trans.xlsx"'

Create a new folder

Creates a new folder named Source Data:

EXECUTE 'cmd /c MD "C:\ACL Projects\Source Data"'

Run external scripts or non-Analytics batch files (.bat)

Runs the script My_Batch.bat:

EXECUTE '"C:\ACL Projects\Batch Files\My_Batch.bat"'

Pass parameters to a non-Analytics batch file

Passes two parameters to My_Batch.bat. Parameters can be literals or Analytics variables:

EXECUTE '"C:\ACL Projects\Batch Files\My_Batch.bat" param1%v_param2%'

Run Analytics scripts in other Analytics projects

Runs "AP_Trans_script" in AP Trans Tests.acl"

EXECUTE 'aclwin.exe "C:\ACL Projects\AP Trans Tests.acl" /b AP_Trans_script'

Note
Running an Analytics script in another project launches a second instance of Analytics. The
script in the second project should end with the QUIT command so that the second instance
of Analytics closes and control is returned to the initial instance of Analytics.

Incorporate a waiting period in an Analytics script

Both examples create a waiting period of 30 seconds:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 183 of 934

Commands

EXECUTE "TIMEOUT /t 30"

EXECUTE "cmd /c PING -n 31 127.0.0.1 > nul"

Remarks
Use EXECUTE to perform useful tasks
The EXECUTE command allows you to run Windows and DOS commands from the Analytics command
line or from an Analytics script.
You can use this ability to increase the automation of Analytics scripts by performing a variety of useful
tasks that are not possible using ACLScript syntax alone.

Examples of tasks that can be started using EXECUTE

Open other programs and Pass parameters to a Access data from network Incorporate Active Dir-
applications and perform batch file locations ectory account lists
tasks required by the Ana-
lytics script

Open any file in its default Run Analytics scripts in Use FTP to access data Integrate with VBScript
application other Analytics projects from remote locations

Perform file and folder Incorporate waiting peri- Zip or unzip data Integrate with SQL data-
administrative tasks such ods in Analytics scripts bases
as copying, moving, cre-
ating, deleting, or com-
paring files or folders that
exist outside of Analytics

Run external scripts or Incorporate Windows task Encrypt or decrypt data Open web pages
non-Analytics batch files scheduling in Analytics
(.bat) scripts

Note
Specific details of how to perform any of these tasks are beyond the scope of Galvanize Help doc-
umentation. For assistance, consult appropriate Windows operating system documentation, or other
third-party documentation.

Default mode and asynchronous mode

You can run the EXECUTE command in either default mode or asynchronous mode:
l Default mode – the process started by EXECUTE must complete before the Analytics script can con-
tinue.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 184 of 934

Commands

Analytics is inaccessible while external processes are running.

l Asynchronous mode – the Analytics script continues to run without waiting for the process started by
EXECUTE to complete.
Analytics continues to be accessible while external processes are running.
If you specify ASYNC, the EXECUTE command runs in asynchronous mode.

Which mode should I use?

When you create Analytics scripts that use the EXECUTE command you need to consider which mode of
operation is appropriate.

Use default mode Use asynchronous mode / ASYNC

o file and folder administrative tasks o external tasks cause an application interface or pop-up
o specifying waiting periods dialog box to open
o any task that subsequent tasks depend on
o subsequent script execution depends on the result in
the RETURN_CODE variable

Analytics scripts that run unattended

If you want an Analytics script that contains the EXECUTE command to run unattended, use one of the fol-
lowing methods:
l use asynchronous mode for any tasks that cause an application interface or pop-up dialog box to
open
l avoid opening interface elements in unattended scripts
Note
Until interface elements are closed, they represent processes that are still running. If these
interface elements are opened with EXECUTE in default mode, they prevent subsequent
lines in an Analytics script from executing, and cause the script to hang.

EXECUTE command in analytic scripts

If you want to use the EXECUTE command in analytic scripts in Robots or on AX Server, you must spe-
cifically configure the command to run. For more information, see:
l Robots –Configuring a Robots Agent
l AX Server –AX Server settings

Quotation marks
The Windows Run command syntax that you use with the EXECUTE command must be enclosed by either
single or double quotation marks.
The following example uses the Windows MD command to create a new folder:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 185 of 934

Commands

EXECUTE 'cmd /c md C:\New_Data_Folder'

Nested quotation marks

If any paths within the Run command syntax contain spaces, the paths must also be enclosed within quo-
tation marks.
You have two options when enclosing paths within quotation marks:
l Double quotation marks inside single quotation marks – Use single quotation marks to enclose
the entire Run command string, and use double quotation marks internally to enclose paths:

EXECUTE 'cmd /c md "C:\New Data Folder"'

You may find this method easier to read than the second method.
Note
Reversing the order of the nesting – using double quotation marks to enclose the
entire string, and single quotation marks to enclose paths – does not work.
l Two double quotation marks – Use double quotation marks to enclose the entire Run command
string, and use two double quotation marks internally to enclose paths:

EXECUTE "cmd /c md ""C:\New Data Folder"""

If you use this second method, the two double quotation marks used internally must be immediately
adjacent and cannot have a space between them.

Internal and external commands

Windows commands can be either internal or external .
l Internal commands – can be run from the command prompt only, which means that you have to
open the command shell using cmd /c or cmd /k before specifying the command.
l External commands – can be run from either the command prompt or directly using the EXECUTE
command, which means opening the command shell is an option, but not required.
The example below uses the internal Windows DIR command (displays the contents of a directory), and
the external Windows COMP command (compares two files), to illustrate the difference:

EXECUTE 'cmd /k dir "C:\ACL DATA\Sample Data Files"'

EXECUTE 'comp C:\File_1.txt C:\File_2.txt'

You can avoid this complication by creating external scripts or batch files to contain Windows commands,
and by using the EXECUTE command only to start the batch file. For example:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 186 of 934

Commands

EXECUTE 'C:\My_Batch.bat'

Multi-line Run command syntax

The EXECUTE command does not support multi-line Run command syntax. To incorporate multi-line Run
commands in an Analytics script, use one of the following methods:

Method Example

Repeat the EXECUTE com-

mand for each Run command. EXECUTE 'cmd /c md "C:\New Data Folder"'
EXECUTE 'cmd /c copy C:\File_1.txt "C:\New Data Folder"'

Combine Run commands

using '&'. EXECUTE 'cmd /c md "C:\New Data Folder" & copy C:\File_1.txt
"C:\New Data Folder"'

Create an external script or

batch file to contain multi-line EXECUTE 'C:\My_Batch.bat'
Run commands, and use the
EXECUTE command only to
start the batch file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 187 of 934

Commands

EXPORT command
Exports data from Analytics to the specified file format, or to Results in HighBond.

Syntax
EXPORT {<FIELDS> field_name <AS export_name> <...n>|<FIELDS> ALL} <UNICODE> export_
type <SCHEMA> PASSWORD num TO {filename|aclgrc_id} <OVERWRITE> <IF test> <WHILE
test> <{FIRST range|NEXT range}> <APPEND> <KEEPTITLE> <SEPARATOR character>
<QUALIFIER character> <WORKSHEET worksheet_name> <DISPLAYNAME>

Parameters
Name Description

FIELDS field_name AS The fields to export.

export_name <...n> | o field_name – export the specified field or fields
FIELDS ALL
Separate field names with spaces.
You can optionally include a different name for the field in the export file using AS
export_name. Enclose export_name in quotation marks.
If you are exporting to ACLGRC (HighBond), it is possible to combine AS with the
DISPLAYNAME parameter. For more information, see "How
DISPLAYNAME interacts with AS when exporting to HighBond Results" on
page 196.
o ALL – export all fields in the table

UNICODE Available in the Unicode edition of Analytics only. Applies to text (ASCII), delimited text
(DELIMITED), and XML files only, and to Windows Clipboard (CLIPBOARD) output.
optional
Exports Analytics data with Unicode UTF-16 LE character encoding applied.
o Specify UNICODE – if the data you are exporting contains characters that are not
supported by extended ASCII (ANSI)
o Do not specify UNICODE – if all the characters in the data you are exporting are sup-
ported by extended ASCII (ANSI)
The exported data is encoded as extended ASCII (ANSI).
Note
Any unsupported characters are omitted from the exported file.
For more information, see ACL Unicode products.

export_type The output file format or destination using one of the following options:
o ACCESS – Microsoft Access database file (.mdb)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 188 of 934

Commands

Name Description

By default, the data is exported as Unicode.

o ACLGRC – Results in HighBond
o ASCII – ASCII plain text (.txt)
o CLIPBOARD – Windows Clipboard
o DBASE – dBASE compatible file (.dbf)
o DELIMITED – delimited text file (.del)
o EXCEL – Microsoft Excel file (.xls) compatible with Excel 1997 to 2003
o JSON – JSON file (.json)
o LOTUS – Lotus 123 file
o WDPF6 – Wordperfect 6 file
o WORD – MS Word file (.doc)
o WP – Wordperfect file
o XLS21 – Microsoft Excel version 2.1 file
o XLSX – Microsoft Excel .xlsx file
By default, the data is exported as Unicode.
o XML – XML file (.xml)

SCHEMA Applies to XML file output only.

optional Include the XML schema in the exported XML file. The XML schema contains metadata
that describes the structure of the XML file, including the data type of the fields.
You can validate the file against the schema once the file has been exported.

PASSWORD num Note

Applies to HighBond Results only.
The password definition to use.
You do not use PASSWORD num to prompt for, or specify, an actual password. The
password definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2
specifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag
PASSWORD num must be placed immediately before TO, or at the end of the string of
command syntax. The password is an HighBond access token. For more information,
see "Exporting to HighBond Results" on page 195.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 189 of 934

Commands

Name Description

Note
PASSWORD may or may not be required, depending on the envir-
onment in which the script runs:

Analytics PASSWORD is not required.

(online activation) The current user's HighBond
access token is automatically
used.

Analytics PASSWORD is required.

(offline activation)

Robots

Analytics Exchange

Analysis App window

TO filename | aclgrc_id The destination for the export:

o TO filename – export data to a file
If required, you can include either an absolute or relative file path, but the Windows
folder must already exist. You must specify the filename value as a quoted string.
o TO aclgrc_id – export data to HighBond Results
The aclgrc_id value must include the control test ID number, and if you are exporting
to a data center other than North America, the data center code. The aclgrc_id value
must be enclosed in quotation marks.
The control test ID number and the data center code must be separated by the at
sign (@). For example, TO "99@eu".
If you do not know the control test ID number, use the Analytics user interface to
begin an export to Results. Cancel the export once you have identified the control
test ID number. For more information, see Exporting exceptions to ACL GRC.
The data center code specifies which regional HighBond server you are exporting
the data to:
l ap – Asia Pacific
l au – Australia
l ca – Canada
l eu – Europe
l us – North America
You can use only the data center code or codes authorized for your organization's
installation of HighBond. The North America data center is the default, so specifying
"@us" is optional.

OVERWRITE Applies to exporting to HighBond Results only.

optional Any existing data in the target control test (table) is overwritten by the exported data.
You must have a Professional Manager role in the target Collection to overwrite data.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 190 of 934

Commands

Name Description

If you omit OVERWRITE, and if data already exists in the target control test (table), the
exported data is appended to the existing data. For more information about appending
in Results, see the "Remarks" below.
Any interpretations related to the target control test (table) dynamically update to reflect
the imported data, whether you overwrite or append.

FIRST range | NEXT range The number of records to process:

APPEND Applies to text (ASCII) and delimited text (DELIMITED) files only.

optional Appends the command output to the end of an existing file instead of overwriting it.
Note
You must ensure that the structure of the command output and the exist-
ing file are identical:
l the same fields
l the same field order
l matching fields are the same length
l matching fields are the same data type
Analytics appends output to an existing file regardless of its structure. If
the structure of the output and the existing file do not match, jumbled,
missing, or inaccurate data can result.

KEEPTITLE Applies to text (ASCII) and delimited text (DELIMITED) files only.

optional Include the Analytics field names with the exported data. If omitted, no field names
appear in the output file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 191 of 934

Commands

Name Description

SEPARATOR character Applies to delimited text (DELIMITED) files only.

optional The character to use as the separator between fields. You must specify the character as
a quoted string.
By default, Analytics uses a comma.

QUALIFIER character Applies to delimited text (DELIMITED) files only.

optional The character to use as the text qualifier to wrap and identify field values. You must spe-
cify the character as a quoted string.
By default, Analytics uses double quotation marks.

WORKSHEET worksheet_ Applies to Microsoft Excel (.xlsx) files only.

name
The name of the Excel worksheet created in a new or existing Excel file.
optional
By default, Analytics uses the name of the Analytics table you are exporting as the work-
sheet name.
The worksheet_name can contain only alphanumeric characters or the underscore char-
acter ( _ ). The name cannot contain special characters, spaces, or start with a number.
Enclosing the value in quotation marks is optional.
For details about overwriting Excel workbooks and worksheets when exporting, see
"The WORKSHEET parameter and overwriting" on page 194.

DISPLAYNAME Applies to ACLGRC (HighBond) only.

optional Exports field names as field names and display names as display names so the display
names appear in column headings in Results without affecting the actual field name.
It is possible to combine DISPLAYNAME with AS. For more information see "How
DISPLAYNAME interacts with AS when exporting to HighBond Results" on page 196.

Examples
Export data to an Excel .xlsx file
You export specific fields from the Vendor table to an Excel .xlsx file:

OPEN Vendor
EXPORT FIELDS Vendor_No Vendor_Name Vendor_City XLSX TO "VendorExport"

Export data to an Excel .xlsx file and specify a worksheet name

You export specific fields from the Vendor table to a worksheet called Vendors_US in an Excel .xlsx file:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 192 of 934

Commands

OPEN Vendor
EXPORT FIELDS Vendor_No Vendor_Name Vendor_City XLSX TO "VendorExport" WORKSHEET
Vendors_US

Export all fields to a delimited file

You export all fields from the Vendor table to a delimited file:

OPEN Vendor
EXPORT FIELDS ALL DELIMITED TO "VendorExport"

Export data to multiple delimited files using GROUP

You export specific fields from the Vendor table to two delimited files:
l one file for vendor names from "A" to "M"
l one file for vendor names from "N" to "Z"
Using the GROUP command, you test the vendor name of each record with an IF condition:

GROUP
EXPORT FIELDS Vendor_No Vendor_Name DELIMITED TO "AtoM" IF BETWEEN(UPPER
(VENDOR_NAME), "A", "M")
EXPORT FIELDS Vendor_No Vendor_Name DELIMITED TO "NtoZ" IF BETWEEN(UPPER
(VENDOR_NAME), "N", "Z")
END

Export data to HighBond Results

You export specific fields from the AR_Exceptions table to HighBond Results. You overwrite existing data
in the target control test (table):

OPEN AR_Exceptions
EXPORT FIELDS No Due Date Ref Amount Type ACLGRC PASSWORD 1 TO "10926@us"
OVERWRITE

Remarks
Note
For more information about how this command works, see the Analytics Help.

Using EXPORT with the GROUP command

For most export formats, you can export data into multiple files simultaneously using the GROUP command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 193 of 934

Commands

Only one file can be created at a time when you are exporting data to Microsoft Excel and Microsoft
Access.

Exporting to Excel
The following limits apply when exporting data to an Excel file:

o Excel 2007 and later (*.xlsx) – a maximum of 1,048,576 records

o Excel 97 and 2003 – a maximum of 65,536 records
Analytics tables that exceed these maximums export successfully, but the excess
Number of records records are ignored and not exported.

o no specific field length limit

o combined field lengths cannot exceed the overall record length limit of 32 KB
(32,765 characters in non-Unicode Analytics, 16,382 characters in Unicode Ana-
lytics)
Length of fields o for Excel 2.1, a maximum of 247 characters

o a maximum of 64 characters
Length of field names o for Excel 2.1, a maximum of 248 characters

The WORKSHEET parameter and overwriting

The result of using or not using the WORKSHEET parameter when exporting from an Analytics table to an
Excel file is explained below:

WORKSHEET parameter WORKSHEET parameter

Matching Description used not used

No matching Excel file o TO filename value A new Excel file is created, A new Excel file is created,
name does not match any with a worksheet with the with a worksheet that uses
existing Excel file name specified name the name of the exported
Analytics table

Matching Excel file name o TO filename value, and A worksheet with the spe- The existing Excel file is
an existing Excel file cified name is added to the overwritten by a new Excel
No matching worksheet
name, are identical existing Excel file file, with a worksheet that
name o WORKSHEET work- uses the name of the
sheet_name does not exported Analytics table
match a worksheet
name in the Excel file

Matching Excel file name o TO filename value, and A worksheet with the spe- The existing Excel file is
and worksheet name an existing Excel file cified name overwrites the overwritten by a new Excel
name, are identical existing worksheet if it was file, with a worksheet that
o WORKSHEET work- originally created from uses the name of the
sheet_name matches a Analytics. exported Analytics table
worksheet name in the
An error message appears
Excel file
and the export operation is
canceled if the existing

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 194 of 934

Commands

WORKSHEET parameter WORKSHEET parameter

Matching Description used not used

worksheet was originally

created directly in Excel.

Exporting to HighBond Results

The table below contains additional information about exporting to a control test in Results.

Item Details

Required per- The ability to export results to a control test in Results requires a specific HighBond role assign-
missions ment, or administrative privileges:
o Users with a Professional User or Professional Manager role for a Results collection can
export results to any control test in the collection.
Note
Only users with the Professional Manager role can export and overwrite
existing data in a control test.
o HighBond System Admins and Results admins automatically get a Professional Manager
role in all collections in the HighBond organization or organizations they administer.

Export limits The following limits apply when exporting to a control test:
o A maximum of 100,000 records per export
o A maximum of 100,000 records per control test
o A maximum of 500 fields per record
o A maximum of 256 characters per field
You can export multiple times to the same control test, but you cannot exceed the overall limits.

Appending fields Regardless of their order in an Analytics table, exported fields are appended to existing fields in
a control test if they have matching physical field names.
In Analytics, the physical field name is the name in the table layout. Exported fields that do not
match the name of any existing field are added as additional columns to the table in Results.
Display names of fields in Analytics, and in Results, are not considered. However, if you use the
optional AS export_name parameter, the export_name value is used as the physical field name
if you do not use DISPLAYNAME.
When appending data to questionnaire fields, the display name of the column in Results
remains the name that is specified in the questionnaire configuration.
Note
If you are round-tripping data between Results and Analytics, and data ends up
misaligned in Results, you probably have mismatched field names.
For more information, see "Field name considerations when importing and
exporting Results data" on page 259.

Creating a password PASSWORD command

definition and spe-
If you use the PASSWORD command to create the numbered password definition for con-

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 195 of 934

Commands

Item Details

cifying a password necting to HighBond, no password value is specified, so a password prompt is displayed when
value the script attempts to connect.
For more information, see "PASSWORD command" on page 350.
SET PASSWORD command
If you use the SET PASSWORD command to create the numbered password definition for con-
necting to HighBond, a password value is specified, so no password prompt is displayed, which
is appropriate for scripts designed to run unattended.
For more information, see SET PASSWORD command.
HighBond access token
Regardless of which method you use to create the password definition, the required password
value is a HighBond access token:
o PASSWORD method – Users can acquire an access token by selecting Tools > HighBond
Access Token, and then signing in to HighBond. An access token is returned, which users
can copy and paste into the password prompt.
o SET PASSWORD method – To insert an access token into the SET PASSWORD command
syntax in an Analytics script, right-click in the Script Editor, select Insert > HighBond Token,
and sign in to HighBond. An access token is inserted into the script at the cursor position.
Caution
The returned access token matches the account used to sign in to HighBond.
As a scriptwriter, using your own access token may not be appropriate if you
are writing a script to be used by other people.

How DISPLAYNAME interacts with AS when exporting to HighBond Results

The matrix below shows how the DISPLAYNAME parameter interacts with AS when exporting field
names from Analytics to Results.

Without AS With AS

Field name and display name Field name and display name in Res-
in Results are the field name from ults are the display name in the AS
Without DISPLAYNAME Analytics. parameter.

Field name in Results is the field Field name in Results is the field
name from Analytics. Display name name from Analytics. Display name
in Results is the display name in Results is the display name in the
With DISPLAYNAME from Analytics. AS parameter.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 196 of 934

Commands

EXTRACT command
Extracts data from an Analytics table and outputs it to a new Analytics table, or appends it to an existing Ana-
lytics table. You can extract entire records or selected fields.

Syntax
EXTRACT {RECORD|FIELDS field_name <AS display_name> <...n>|FIELDS ALL} TO table_name
<IF test> <WHILE test> <FIRST range|NEXT range> <EOF> <APPEND> <OPEN> <LOCAL>

Parameters
Name Description

RECORD | FIELDS field_ The fields to include in the output:

name | FIELDS ALL o RECORD – use the entire record in the source data file: all fields in the table, and any
undefined portions of the record
Fields are used in the order that they appear in the table layout.
Preserves computed fields.
o FIELDS field_name – use the specified fields
Fields are used in the order that you list them.
Converts computed fields to physical fields of the appropriate data type in the des-
tination table – ASCII or Unicode (depending on the edition of Analytics), ACL (the nat-
ive numeric data type), Datetime, or Logical. Populates the physical fields with the
actual computed values.
o FIELDS ALL – use all fields in the table
Fields are used in the order that they appear in the table layout.
Converts computed fields to physical fields of the appropriate data type in the des-
tination table – ASCII or Unicode (depending on the edition of Analytics), ACL (the nat-
ive numeric data type), Datetime, or Logical. Populates the physical fields with the
actual computed values.

AS display_name Only used when extracting using FIELDS field_name.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 197 of 934

Commands

Name Description

Note
AS works only when extracting to a new table. If you are appending to an
existing table, the alternate column titles in the existing table take pre-
cedence.

TO table_name The location to send the results of the command to:

FIRST range | NEXT range The number of records to process:

EOF Execute the command one more time after the end of the file has been reached.
optional This ensures that the final record in the table is processed when inside a GROUP com-
mand. Only use EOF if all fields are computed fields referring to earlier records.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 198 of 934

Commands

Name Description

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Extracting all records in a table to a new table
You create an exact duplicate of the AR_Customer table by extracting all the records to a new Analytics
table. Any computed fields are preserved as computed fields:

OPEN AR_Customer
EXTRACT RECORD TO "AR_Customer_2"

Extracting all fields in a table to a new table

You extract all defined fields in the AR_Customer table to a new Analytics table. Any computed fields are
converted to physical fields and populated with the actual computed values:

OPEN AR_Customer
EXTRACT FIELDS ALL TO "AR_Customer_2"

Extracting all records in a table and appending them to an existing table

You extract all the records in the AR_Customer table and append them as a group to the end of the AR_

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 199 of 934

Commands

Customer_Master table:

OPEN AR_Customer
EXTRACT RECORD TO "AR_Customer_Master" APPEND

Extracting all records in a table and appending them to an existing table in a

different folder
You extract all the records in the AR_Customer table and append them as a group to the end of the AR_
Customer_Master table, which is in a folder other than the Analytics project folder:

OPEN AR_Customer
EXTRACT RECORD TO "C:\Users\Customer Data\AR_Customer_Master" APPEND

Extracting a subset of fields from a table to a new table

You extract three fields from the AR_Customer table to a new Analytics table:

OPEN AR_Customer
EXTRACT FIELDS Name Due Date TO "AR_Customer_Dates.fil"

Creating display names for extracted fields

You extract three fields from the AR_Customer table and create display names for the fields in the new
Analytics table:

OPEN AR_Customer
EXTRACT FIELDS Name AS "Customer;Name" Due AS "Due;Date" Date AS "Invoice;Date" TO
"AR_Customer_Dates.fil"

Extracting fields based on a condition

You extract three fields from the AR_Customer table to a new Analytics table if the date in the Due field is
before July 1, 2014:

OPEN AR_Customer
EXTRACT FIELDS Name Due Date IF Due < `20140701` TO "Overdue.fil"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 200 of 934

Commands

EXTRACT vs Copying a table

EXTRACT creates a new source data file (.fil) as well as a new table layout.
Copying a table using the Navigator (Edit > Copy ) creates a new table layout that remains associated with
the original source data file. It does not create a new data file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 201 of 934

Commands

FIELDSHIFT command
Shifts the start position of a field definition in a table layout.

Syntax
FIELDSHIFT START starting_position COLUMNS bytes_to_shift <FILTER data_filter_name> <OK>

Parameters
Name Description

START starting_position The starting byte position of the first field definition you want to shift.
All field definitions to the right of the specified field definition are also shifted.
If you specify a non-starting byte position, the next starting byte position is used.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) 1 byte = 1 character

data

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, typically you should specify an odd-numbered starting

byte position. Specifying an even-numbered starting position can cause
characters to display incorrectly.

COLUMNS bytes_to_shift The number of bytes to shift the field definition.

Enter a positive number to shift a field definition to the right. Enter a negative number to
shift a field definition to the left.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) 1 byte = 1 character

data

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, specify an even number of bytes only. Specifying an

odd number of bytes can cause characters to display incorrectly.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 202 of 934

Commands

Name Description

FILTER data_filter_name The name of the filter that identifies field definitions associated with a particular record
definition.
optional

OK Deletes or overwrites items without asking you to confirm the action.

optional

Examples
Shifting field definitions
You shift the field definition starting at byte 11, and any subsequent field definitions, 4 bytes to the right:

FIELDSHIFT START 11 COLUMNS 4

Remarks
Note
For more information about how this command works, see the Analytics Help.

Shifted field definitions must remain within the record length

When you shift one or more field definitions right or left, the fields cannot exceed the record length in either
direction.
Keep in mind that FIELDSHIFT moves both the specified field definition, and any field definitions to the right
of the specified definition. If the shifted block of definitions would exceed the record length in either direction,
an error message appears and the command is not executed.
Tip
If the error message is appearing because you are exceeding the end of the record, try
removing the final field definition to make room for the field definitions being shifted.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 203 of 934

Commands

FIND command
Searches an indexed character field for the first value that matches the specified character string.
Note
The FIND command and the FIND( ) function are two separate Analytics features with sig-
nificant differences. For information about the function, see "FIND( ) function" on
page 562.

Syntax
FIND search_value

Parameters
Name Description

search_value The character string to search for.

search_value is case-sensitive and cannot include leading spaces.
Do not enclose the value in quotation marks unless quotation marks are part of the data
being searched.

Examples
Searching for a specific value
You want to locate the first value in the Card_Number character field that exactly matches or starts with
"8590124".
First you index the Card_Number field in ascending order. Then you run FIND:

INDEX ON Card_Number TO "CardNum" OPEN

SET INDEX TO "CardNum"
FIND 8590124

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 204 of 934

Commands

Remarks
Note
For more information about how this command works, see the Analytics Help.

When to use FIND

Use the FIND command to move directly to the first record in a table containing the specified search_value
in the indexed character field.

INDEX requirement
To use the command, the table you are searching must be indexed on a character field in ascending order.
If multiple character fields are indexed in ascending order, only the first field specified in the index is
searched. The command cannot be used to search non-character index fields, or character fields indexed in
descending order.

Partial matching
Partial matching is supported. The search value can be contained by a longer value in the indexed field.
However, the search value must appear at the start of the field to constitute a match.

FIND output depending on match

The FIND command produces one of the following results, depending on whether the search value is found:
l search value is found – the first matching record in the table is selected
l search value is not found – the table is positioned at the first record with a greater value than the
search value
If there are no values in the indexed field greater than the search value, the table is positioned at the
first record. In both cases, the message "No index matched key" is displayed.
The FIND command is not affected by the Exact Character Comparisons option (SET EXACT ON/OFF).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 205 of 934

Commands

FUZZYDUP command
Detects nearly identical values (fuzzy duplicates) in a character field.
Note
To use fuzzy matching to combine fields from two Analytics tables into a new, single Ana-
lytics table, see "FUZZYJOIN command" on page 211.

Syntax
FUZZYDUP ON key_field <OTHER fields> LEVDISTANCE value <DIFFPCT percentage>
<RESULTSIZE percentage> <EXACT> <IF test> TO table_name <LOCAL> <OPEN>

Parameters
Name Description

ON key_field The character field or expression to test for fuzzy duplicates.

OTHER fields A list of fields or expressions to include in the output.

optional

LEVDISTANCE value The maximum allowable Levenshtein distance between two strings for them to be iden-
tified as fuzzy duplicates and included in the results.
The LEVDISTANCE value cannot be less than 1 or greater than 10. Increasing the
LEVDISTANCE value increases the number of results by including values with a greater
degree of fuzziness – that is, values that are more different from one another.
For more information, see "FUZZYDUP behavior" on page 209.

DIFFPCT percentage A threshold that limits the 'difference percentage' or the proportion of a string that can be
different.
optional
The percentage that results from an internal Analytics calculation performed on poten-
tial fuzzy duplicate pairs must be less than or equal to the DIFFPCT value for the pair to
be included in the results. The DIFFPCT value cannot be less than 1 or greater than 99.
If DIFFPCT is omitted the threshold is turned off and difference percentage is not con-
sidered during processing of the FUZZYDUP command.
For more information, see "FUZZYDUP behavior" on page 209.

RESULTSIZE percentage The maximum size of the set of output results as a percentage of the number of records
in the key field.
optional
For example, for a key field with 50,000 records, a RESULTSIZE of 3 would terminate
processing if the results exceeded 1500 fuzzy duplicates (50,000 x 0.03). No output

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 206 of 934

Commands

Name Description

table is produced if processing is terminated.

The RESULTSIZE value cannot be less than 1 or greater than 1000 (one thousand) per-
cent. The limit of 1000% is to accommodate the nature of many-to-many matching,
which can produce results that are more numerous than the original test data set.
If RESULTSIZE is omitted the threshold is turned off and result size is not considered
during processing of the FUZZYDUP command.
Caution
Omitting RESULTSIZE can produce an unduly large set of results that
takes a very long time to process, or can cause available memory to be
exceeded, which terminates processing. Omit RESULTSIZE only if you
are confident that the results will be of a manageable size.

EXACT Includes exact duplicates as well as fuzzy duplicates in the results.

optional

TO table_name The location to send the results of the command to:

OPEN Opens the table created by the command after the command executes. Only valid if the

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 207 of 934

Commands

Name Description

optional command creates an output table.

Analytics output variables

Name Contains

GAPDUPn The total number of gaps, duplicates, or fuzzy duplicate groups identified by the com-
mand.

Examples
Test a surname field for fuzzy duplicates
You test a surname field for fuzzy duplicates (the Last_Name field in the Employee_List table in
ACL DATA\Sample Data Files\Metaphor_Employee_Data.ACL). The results are output to a
new Analytics table.
l In addition to the test field, other fields are included in the results.
l The maximum allowable Levenshtein distance is 1.
l The proportion of a string that can be different is limited to 50%.
l The size of the results is limited to 20% of the test field size.
l In addition to fuzzy duplicates, exact duplicates are included.

FUZZYDUP ON Last_Name OTHER First_Name EmpNo LEVDISTANCE 1 DIFFPCT 50

RESULTSIZE 20 EXACT TO "Fuzzy_Last_Name" OPEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
The FUZZYDUP command finds nearly identical values (fuzzy duplicates), or locates inconsistent spelling
in manually entered data.
Unlike the ISFUZZYDUP( ) function, which identifies an exhaustive list of fuzzy duplicates for a single char-
acter value, the FUZZYDUP command identifies all fuzzy duplicates in a field, organizes them in groups,
and outputs non-exhaustive results.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 208 of 934

Commands

What non-exhaustive means

Non-exhaustive means that individual fuzzy duplicate groups in the results may not contain all the fuzzy
duplicates in a test field that are within the specified degree of difference of the group owner. However, if a
group owner is a fuzzy duplicate of another value in the test field, the two values will appear together in a
group somewhere in the results.
If producing an exhaustive list of fuzzy duplicates for a specific value in the test field is important to your ana-
lysis, you can use the ISFUZZYDUP( ) function for this purpose.

FUZZYDUP behavior
The FUZZYDUP command has two parameters that allow you to control the degree of difference between
fuzzy duplicates, and the size of the results:
l LEVDISTANCE
l DIFFPCT
You may need to try different combinations of settings for these two parameters to find out what works best
for a particular data set.

LEVDISTANCE (Levenshtein distance)

When processing data, the FUZZYDUP command calculates the Levenshtein distance between each eval-
uated pair of strings in the test field, and calculates the difference percentage. The Levenshtein distance is a
value representing the minimum number of single character edits required to make one string identical to
the other string. For more information, see "LEVDIST( ) function" on page 620.

DIFFPCT (Difference percentage)

The difference percentage is the percentage of the shorter of the two evaluated strings that is different, and
is the result of the following internal Analytics calculation, which uses the Levenshtein distance between the
two strings:
Levenshtein distance / number of characters in the shorter string × 100 = difference percentage

More information
For detailed information about the fuzzy duplicate difference settings, controlling result size, and fuzzy
duplicate groups, see Fuzzy duplicates overview.

Case-sensitivity
The FUZZYDUP command is not case-sensitive, so "SMITH" is equivalent to "smith."

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 209 of 934

Commands

Trailing blanks automatically trimmed

The FUZZYDUP command automatically trims trailing blanks in key_field, so there is no need to use the
TRIM( ) or ALLTRIM( ) function when specifying a single field for key_field.
If you concatenate fields for key_field, you should use ALLTRIM( ), as shown below.

Improving the effectiveness of FUZZYDUP

Concatenating fields
Concatenating two or more test fields can improve the effectiveness of the FUZZYDUP command by
increase the degree of uniqueness of the test values.
For example:

FUZZYDUP ON ALLTRIM(First_Name)+ALLTRIM(Last_Name) OTHER First_Name Last_Name

EmpNo LEVDISTANCE 4 DIFFPCT 50 RESULTSIZE 20 EXACT TO "Fuzzy_First_Name_Last_
Name" OPEN

The OMIT( ) function

The OMIT( ) function can also improve the effectiveness of the command by removing generic elements
such as "Corporation" or "Inc." from field values.
Removal of generic elements focuses the FUZZYDUP string comparison on just the portion of the strings
where a meaningful difference may occur.
For more information, see "OMIT( ) function" on page 670.

Other string comparison methods

l DICECOEFFICIENT( ) function – provides a method for comparing strings that de-emphasizes or
completely ignores the relative position of characters or character blocks.
l SOUNDSLIKE( ) and SOUNDEX( ) functions – provide a method for comparing strings based on
a phonetic comparison (sound) rather than on an orthographic comparison (spelling).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 210 of 934

Commands

FUZZYJOIN command
Uses fuzzy matching to combine fields from two Analytics tables into a new, single Analytics table.
Note
To detect nearly identical values (fuzzy duplicates) in a single character field, see
"FUZZYDUP command" on page 206.
For various options when joining tables using exactly matching key field values, see "JOIN
command" on page 316.

Syntax
FUZZYJOIN {DICE PERCENT percentage NGRAM n-gram_length|LEVDISTANCE DISTANCE
value} PKEY primary_key_field SKEY secondary_key_field {FIELDS primary_fields|FIELDS ALL}
<WITH secondary_fields|WITH ALL> <IF test> <OPEN> <FIRSTMATCH> TO table_name <WHILE
test> <FIRST range|NEXT range> <APPEND>

Note
You cannot run the FUZZYJOIN command locally against a server table.
You must specify the FUZZYJOIN command name in full. You cannot abbreviate it.

Parameters
Name Description

DICE PERCENT per- The fuzzy matching algorithm to use.

centage NGRAM n-gram_
DICE – use the Dice coefficient algorithm
length | LEVDISTANCE
DISTANCE value o PERCENT percentage – the minimum allowable Dice's coefficient of two strings for
them to qualify as a fuzzy match
Specify a decimal fraction, from 0.0000 to 1.0000 (for example, 0.7500). Use a max-
imum of four decimal places.
Decreasing the value increases the number of matches by including matches with a
greater degree of fuzziness – that is, strings that are more different from each another.
o NGRAM n-gram_length – the n-gram length to use
Specify a whole number, 1 or greater.
Increasing the n-gram length makes the criterion for similarity between two strings
stricter.
N-grams are overlapping substrings (character blocks) into which the comparison
strings are divided as part of the Dice's coefficient calculation.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 211 of 934

Commands

Name Description

Note
When you specify DICE, the FUZZYJOIN command uses the
DICECOEFFICIENT( ) function in an IF statement to conditionally join
key field values. For detailed information about the function, see
"DICECOEFFICIENT( ) function" on page 535.
LEVDISTANCE – use the Levenshtein distance algorithm
o DISTANCE value – the maximum allowable Levenshtein distance between two strings
for them to qualify as a fuzzy match
Specify a whole number, 1 or greater.
Increasing the value increases the number of matches by including matches with a
greater degree of fuzziness – that is, strings that are more different from each another.
Note
When you specify LEVDISTANCE, the FUZZYJOIN command uses the
LEVDIST( ) function in an IF statement to conditionally join key field val-
ues. For detailed information about the function, see "LEVDIST( ) func-
tion" on page 620.
Unlike the function, the Levenshtein distance algorithm in the
FUZZYJOIN command automatically trims leading and trailing blanks,
and is not case-sensitive.

PKEY primary_key_field The character key field, or expression, in the primary table.
You can specify only one primary key field.

SKEY secondary_key_ The character key field, or expression, in the secondary table.
field
You can specify only one secondary key field.

FIELDS primary_fields | The fields or expressions from the primary table to include in the joined output table.
FIELDS ALL o primary_fields – include the specified field or fields
o ALL – include all fields from the table
Note
You must explicitly specify the primary key field if you want to include it in
the joined table. Specifying ALL also includes it.

WITH secondary_fields | The fields or expressions from the secondary table to include in the joined output table.
WITH ALL o secondary_fields – include the specified field or fields
optional o ALL – include all fields from the table
Note
You must explicitly specify the secondary key field if you want to include it
in the joined table. Specifying ALL also includes it.

IF test A conditional expression that must be true in order to process each record. The command
is executed on only those records that satisfy the condition.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 212 of 934

Commands

Name Description

Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).
Note
The IF condition can reference the primary table, the secondary table, or
both.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

FIRSTMATCH Specifies that each primary key value is joined to only the first occurrence of any sec-
ondary key matches.
optional
If the first occurrence happens to be an exact match, any subsequent fuzzy matches for
the primary key value are not included in the joined output table.
If you omit FIRSTMATCH, the default behavior of FUZZYJOIN is to join each primary key
value to all occurrences of any secondary key matches.
FIRSTMATCH is useful if you only want to know if any matches, exact or fuzzy, exist
between two tables, and you want to reduce the processing time required to identify all
matches.
You can also use FIRSTMATCH if you are certain that at most only one match exists in
the secondary table for each primary key value.
Note
FIRSTMATCH is available only as an ACLScript parameter. The option is
not available in the Analytics user interface.

TO table_name The location to send the results of the command to:

WHILE test A conditional expression that must be true in order to process each record. The command
is executed until the condition evaluates as false, or the end of the table is reached.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 213 of 934

Commands

Name Description

Note
If you use WHILE in conjunction with FIRST or NEXT, record processing
stops as soon as one limit is reached.

FIRST range | NEXT range The number of records to process:

ISOLOCALE locale_code Note

Examples
Use fuzzy matching to join two tables as a way of discovering employees
who may also be vendors
The example below joins the Empmast and Vendor tables using address as the common key field (the
Address and Vendor_Street fields).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 214 of 934

Commands

The FUZZYJOIN command creates a new table with either exactly matched or fuzzy matched primary and
secondary records. The result is a list of any employees and vendors with either an identical address, or a
similar address.

FUZZYJOIN with the Dice coefficient algorithm

OPEN Empmast PRIMARY

OPEN Vendor SECONDARY
FUZZYJOIN DICE PERCENT 0.8000 NGRAM 2 PKEY Address SKEY Vendor_Street FIELDS
Employee_Number First_Name Last_Name Address WITH Vendor_Number Vendor_Name Vendor_
Street OPEN TO "Employee_Vendor_Match"

FUZZYJOIN with the Levenshtein distance algorithm

OPEN Empmast PRIMARY

OPEN Vendor SECONDARY
FUZZYJOIN LEVDISTANCE DISTANCE 5 PKEY Address SKEY Vendor_Street FIELDS Employee_
Number First_Name Last_Name Address WITH Vendor_Number Vendor_Name Vendor_Street
OPEN TO "Employee_Vendor_Match"

Include all fields

This version of the FUZZYJOIN command includes all fields from the primary and secondary tables in the
joined output table.

OPEN Empmast PRIMARY

OPEN Vendor SECONDARY
FUZZYJOIN LEVDISTANCE DISTANCE 5 PKEY Address SKEY Vendor_Street FIELDS ALL WITH
ALL OPEN TO "Employee_Vendor_Match"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Case sensitivity
The FUZZYJOIN command is not case-sensitive, regardless of which fuzzy matching algorithm you use. So
"SMITH" is equivalent to "smith."

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 215 of 934

Commands

Leading and trailing blanks

The FUZZYJOIN command automatically trims leading and trailing blanks in fields, regardless of which
fuzzy matching algorithm you use. There is no need to use the TRIM( ) or ALLTRIM( ) functions when spe-
cifying the primary and secondary key fields.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 216 of 934

Commands

GAPS command
Detects whether a numeric or datetime field in an Analytics table contains one or more gaps in sequential
data.

Syntax
GAPS <ON> key_field <D> <UNFORMATTED> <PRESORT> <MISSING limit> <HEADER header_
text> <FOOTER footer_text> <IF test> <WHILE test> <FIRST range|NEXT range> <TO
{SCREEN|table_name|filename|PRINT}> <APPEND> <LOCAL> <OPEN>

Parameters
Name Description

ON key_field D The fields or expressions to check for gaps.

Include D to sort the key field in descending order. The default sort order is ascending.

UNFORMATTED Suppresses page headings and page breaks when the results are output to a file.
optional

PRESORT Sorts the table on the key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.

MISSING limit The output results contain individual missing items rather than gap ranges.
optional The limit value specifies the maximum number of missing items to report for each iden-
tified gap. The default value is 5. If the limit is exceeded for a particular gap, the missing
items are reported as a range for that particular gap.
The limit value does not restrict the total number of missing items reported, it only restricts
the number of missing items reported within a specific gap.

HEADER header_text The text to insert at the top of each page of a report.
optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

IF test A conditional expression that must be true in order to process each record. The command

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 217 of 934

Commands

Name Description

optional is executed on only those records that satisfy the condition.

Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).

FIRST range | NEXT range The number of records to process:

TO SCREEN | table_name The location to send the results of the command to:
| filename | PRINT o SCREEN – displays the results in the Analytics display area
optional o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o PRINT – sends the results to the default printer

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 218 of 934

Commands

Name Description

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Analytics output variables

Name Contains

GAPDUPn The total number of gaps, duplicates, or fuzzy duplicate groups identified by the com-
mand.

Examples
Testing for missing invoice numbers
You use GAPS to ensure that there are no invoice numbers missing from an Invoices table:

OPEN Invoices
GAPS ON Inv_Num PRESORT TO "Invoices_Gaps.fil"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 219 of 934

Commands

Remarks
Using GAPS on character fields
In addition to testing numeric or datetime fields, you can also test for gaps in numeric data that appears in
a character field. For example, you can test check numbers, which are typically formatted as character
data.
If letters and numbers appear together in a character field, only the numbers are tested and the letters are
ignored.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 220 of 934

Commands

GROUP command
Executes one or more ACLScript commands on a record before moving to the next record in the table, with
only one pass through the table. Command execution can be controlled by conditions.

Syntax
GROUP <IF test> <WHILE test> <FIRST range|NEXT range>
command
<...n>
<ELSE IF test>
command
<...n>
<ELSE>
command
<...n>
END

Note
Some Analytics commands cannot be used with the GROUP command. For more inform-
ation, see "Commands that can be used inside the GROUP command" on page 225.

Parameters
Name Description

FIRST range | NEXT range The number of records to process:

optional o FIRST – start processing from the first record until the specified number of records is

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 221 of 934

Commands

Name Description

reached
o NEXT – start processing from the currently selected record until the specified number
of records is reached
Use range to specify the number of records to process.
If you omit FIRST and NEXT, all records are processed by default.

command <...n> One or more ACLScript commands to execute inside the GROUP. For a complete list of
commands supported inside GROUP, see "Commands that can be used inside the
GROUP command" on page 225.
If there is a preceding IF or ELSE IF, the test must evaluate to true.
If the command is listed under ELSE, the command is executed if there are records that
have not been processed by any of the preceding commands. You can include multiple
commands, with each command starting on a separate line.

ELSE IF test Opens an ELSE IF block for the GROUP command. The condition tests records that did
not match the GROUP command test, or any previous ELSE IF tests.
optional
You can include multiple ELSE IF tests and they are evaluated from top to bottom, until
the record evaluates to true and the commands that follow that ELSE IF statement are
executed.

ELSE Opens an ELSE block for the GROUP command. The commands that follow are executed
for records that evaluated to false for all of the previous tests.
optional

END The end of the GROUP command.

Examples
Simple GROUP
Simple groups start with a GROUP command, are followed by a series of commands, and terminate with
an END command:

GROUP
COUNT
HISTOGRAM ON Quantity MINIMUM 0 MAXIMUM 100 INTERVALS 10
CLASSIFY ON Location SUBTOTAL Quantity
END

GROUP IF
Conditional groups execute commands based on whether a condition is true or false. The following
GROUP command is executed only on records with a Product_class value less than 5:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 222 of 934

Commands

GROUP IF Product_class < "05"

COUNT
HISTOGRAM ON Quantity MINIMUM 0 MAXIMUM 100 INTERVALS 10
CLASSIFY ON Location SUBTOTAL Quantity
END

GROUP IF ...ELSE
Records that do not meet the test condition are ignored unless you include an ELSE block.
Any number of commands can follow an ELSE statement. In the following example, all records that do not
meet the condition are processed by having their Quantity field totaled:

GROUP IF Product_class < "05"

COUNT
HISTOGRAM ON Quantity MINIMUM 0 MAXIMUM 100 INTERVALS 10
CLASSIFY ON Location SUBTOTAL Quantity
ELSE
TOTAL Quantity
END

GROUP IF...ELSE IF...ELSE

You can include multiple ELSE IF blocks within a group, as long as each ELSE IF block contains a different
test. In the following example, the ELSE IF blocks, and the ELSE block, produce four totals:

GROUP IF Product_class < "05"

COUNT
HISTOGRAM ON Quantity MINIMUM 0 MAXIMUM 100 INTERVALS 10
CLASSIFY ON Location SUBTOTAL Quantity
ELSE IF Product_class = "05"
TOTAL Quantity
ELSE IF Product_class = "06"
TOTAL Quantity
ELSE IF Product_class = "07"
TOTAL Quantity
ELSE
TOTAL Quantity
END

Nested GROUP commands

Nested groups refer to groups contained within other groups. Nested groups provide a powerful way for you
to control which commands are executed for which records. Most applications do not require such an
advanced level of functionality, but it is available, if necessary.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 223 of 934

Commands

As with other groups, use the END command to terminate a nested group. Analytics starts processing the
data only after all group commands have been terminated:

GROUP IF Product_class < "05"

COUNT
STRATIFY ON Quantity SUBTOTAL Quantity MIN 0 MAX 100 INT 10
GROUP IF Quantity > 0
STATISTICS ON Quantity
HISTOGRAM ON Quantity
END
ELSE
TOTAL Quantity
END

In this example, all of the commands from COUNT up to and including the next GROUP are executed only
if Product_class is less than 05.
The STATISTICS and HISTOGRAM commands are executed if Quantity is greater than zero. However,
because the second GROUP command is nested, the STATISTICS and HISTOGRAM commands are
executed only for records that meet the conditions Product_class < "05" and Quantity > 0.

Generating system variables inside a GROUP

You can use GROUP to create multiple system variables for a single command.
Normally, when you run a command such as TOTAL, COUNT, or STATISTICS, only one system variable
is generated. Each time you run the command, you overwrite the value from the last execution of the com-
mand. Commands that run inside a GROUP create a specific variable for each instance of the command
inside the GROUP.
In this example, the TOTAL command calculates the sum of the Amount field for each product class in the
Metaphor_Trans_2002 table. When the code runs, the following variables are generated and can be used
in subsequent commands after the GROUP:
l TOTAL2 – the sum of the Amount field for product class 03
l TOTAL3 – the sum of the Amount field for product class 05
l TOTAL4 – the sum of the Amount field for product class 08
l TOTAL5 – the sum of the Amount field for product class 09

OPEN Metaphor_Trans_2002
GROUP
TOTAL AMOUNT IF PRODCLS = "03"
TOTAL AMOUNT IF PRODCLS = "05"
TOTAL AMOUNT IF PRODCLS = "08"
TOTAL AMOUNT IF PRODCLS = "09"
END
CLOSE Metaphor_Trans_2002

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 224 of 934

Commands

Remarks
Tip
For a detailed tutorial covering the GROUP and LOOP commands, see "Grouping and loop-
ing" on page 33.

Commands that can be used inside the GROUP command

The table below lists the Analytics commands that can be used inside the GROUP command.
If a command is not listed below, it cannot be used inside GROUP.

AGE ASSIGN BENFORD

CLASSIFY COMMENT COUNT

CROSSTAB DUPLICATES EXPORT

EXTRACT GAPS GROUP

HISTOGRAM JOIN LIST

LOOP MERGE PROFILE

REPORT SEQUENCE STATISTICS

STRATIFY SUMMARIZE TOTAL

VERIFY

Grouping and looping

The GROUP command allows you to execute several commands on a record before moving to the next
record in the table, which can significantly reduce processing time.
You can use the LOOP command inside the GROUP command if you need to execute a series of com-
mands more than once against a record.

Using variables with GROUP

User-defined variables
To use a variable inside the GROUP command, define the variable before you enter the GROUP block.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 225 of 934

Commands

Note
While you can initialize and define a variable inside a GROUP block, it is not recom-
mended. Variables initialized inside a GROUP may cause unexpected results when used.
Inside a GROUP, you can evaluate variables using variable substitution. The value of the variable remains
the same as when the GROUP is entered.
You cannot define a variable inside a GROUP and then reference it using variable substitution:

ASSIGN v_test = "hello"

GROUP
ASSIGN v_test2 = "%v_test% world"
COMMENT this would be invalid: v_test3 = "%v_test2% again"
END

System-defined variables
Certain commands such as TOTAL and STATISTICS generate system variables based on calculations
that the commands perform. If you use a GROUP to execute these commands, any system variables that
result are numbered consecutively, starting at the line number of the command inside the GROUP (exclud-
ing empty lines) and running to n. The value of n increases by 1 for each line number in the GROUP.
Note
You must wait until the GROUP completes before using any system generated variables
created inside the GROUP. The command must run against each record in the table
before the variable is available. Use these variables after the closing END keyword of the
GROUP.
In the following example, the first TOTAL command generates the variable TOTAL2 and the second gen-
erates TOTAL4. Both of these variables are available to use in subsequent commands once the
GROUP completes:

GROUP
TOTAL Discount IF Order_Priority = "Low"
ASSIGN v_var = "test"
TOTAL Discount IF Order_Priority = "High"
END

Syntax notes
l The multiline syntax listed for the GROUP command is required, and therefore the GROUP com-
mand cannot be entered in the command line.
l Each GROUP command must be terminated with an END command.
l When you use the GROUP command in your scripts, you can improve the readability of the com-
mand block by indenting the commands listed inside the group.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 226 of 934

Commands

HELP command
Launches the Analytics Help Docs in a browser.

Syntax
HELP

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 227 of 934

Commands

HISTOGRAM command
Groups records based on values in a character or numeric field, counts the number of records in each
group, and displays the groups and counts in a bar chart.

Syntax
HISTOGRAM {<ON> character_field|<ON> numeric_field MINIMUM value MAXIMUM value
{<INTERVALS number>|FREE interval_value <...n> last_interval}} <TO
{SCREEN|filename|GRAPH|PRINT}> <IF test> <WHILE test> <FIRST range|NEXT range>
<HEADER header_text> <FOOTER footer_text> <KEY break_field> <SUPPRESS> <COLUMNS
number> <APPEND> <LOCAL> <OPEN>

Parameters
Name Description

ON character_field The character field or expression to use for the histogram.

ON numeric_field The numeric field or expression to use for the histogram.

MINIMUM value Applies to numeric fields only. The minimum value of the first numeric interval.
MINIMUM is optional if you are using FREE, otherwise it is required.

MAXIMUM value Applies to numeric fields only. The maximum value of the last numeric interval.
MAXIMUM is optional if you are using FREE, otherwise it is required.

INTERVALS number Applies to numeric fields only.

optional The number of equal-sized intervals Analytics produces over the range specified by the
MINIMUM and MAXIMUM values. If you do not specify a number of intervals, the default
number is used.
The default is specified by the Intervals number on the Command tab in the Options dia-
log box.

FREE interval_value <...n> Applies to numeric fields only.

last_interval
Creates custom-sized intervals by specifying the start point of each interval and the end
optional point of the last interval.
If you specify MINIMUM and MAXIMUM values, those values are the start point of the
first interval and the end point of the last interval, and each interval_value creates an
additional interval within the range. The interval values you specify must be greater than
the MINIMUM value, and equal to or less than the MAXIMUM value.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 228 of 934

Commands

Name Description

Interval values must be in numeric sequence and cannot contain duplicate values:

FREE -1000, 0, 1000, 2000, 3000

If you specify both FREE and INTERVALS, then INTERVALS is ignored.

FIRST range | NEXT range The number of records to process:

HEADER header_text The text to insert at the top of each page of a report.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 229 of 934

Commands

Name Description

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

SUPPRESS Values above the MAXIMUM value and below the MINIMUM value are excluded from
the command output.
optional

COLUMNS number The length of the x-axis in the textual representation of the bar chart if you output his-
togram results to a text file.
optional
The number value is the number of character spaces (text columns) to use for the x-axis
(and the y-axis labels). If you omit COLUMNS, the default of 78 character spaces is
used.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Basic histogram for hourly salary

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 230 of 934

Commands

You use HISTOGRAM to create a graph showing the distribution of wages between 0 and 100 dollars per
hour:

HISTOGRAM ON Rate MINIMUM 0 MAXIMUM 100 TO GRAPH

Histogram with defined intervals for hourly salary

Continuing from the previous example, you use HISTOGRAM to specify the ranges in the graph in a more
meaningful way.
Most of the wages fall between 20 and 50 dollars per hour, so the graph includes the following number of
intervals:
l three in the 20 to 50 range
l one for 0-20
l one for 50-100
l one for > 100

HISTOGRAM ON Rate MINIMUM 0 MAXIMUM 100 FREE 20,30,40,50,100 TO GRAPH

Remarks
Note
For more information about how this command works, see the Analytics Help.

Populating low and high values

You can run the STATISTICS or PROFILE commands on a numeric field before running the HISTOGRAM
command to automatically populate the MINIMUM and MAXIMUM parameter values with the lowest and
highest values in the field.

Related commands
Creating a histogram using a character field is similar to classifying. Creating a histogram using a numeric
field is similar to stratifying.
Unlike the other grouping operations in Analytics, histograms do not support subtotaling numeric fields.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 231 of 934

Commands

IF command
Specifies a condition that must evaluate to true in order to execute a command.

Syntax
IF test command

Parameters
Name Description

test The condition that must be met for command to be run.

command Any valid ACLScript command to run if test evaluates to true.

Examples
Running a command conditionally
You want to use CLASSIFY on a table, but only if the v_counter variable is greater than ten:

IF v_counter > 10 CLASSIFY ON Location TO "Count_by_Location.fil" OPEN

Running a command based on a user decision

You want to allow the script user to decide whether to classify a table.
In your script, you include a dialog box with a check box that if selected allows the CLASSIFY command to
run. The check box stores a True or False input value in the logical variable v_classify_checkbox.
You use an IF test to determine the value of v_classify_checkbox, and if the value is True, CLASSIFY
executes:

IF v_classify_checkbox=T CLASSIFY ON Location TO "Count_by_Location.fil" OPEN

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 232 of 934

Commands

Remarks
IF command versus IF parameter
The logic of the IF command differs from the IF parameter that is supported by most commands:
l IF command – determines whether the associated command runs or not, based on the value of the
test expression
l IF parameter – determines whether the command runs against each record in an Analytics table
based on the value of the test expression

Decision making in scripts

In a script, you can enter a series of IF command tests and run different commands based on the results.
The IF command can be also be used to test the value of a variable to determine if further processing should
occur.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 233 of 934

Commands

IMPORT ACCESS command

Creates an Analytics table by defining and importing a Microsoft Access database file.

Syntax
IMPORT ACCESS TO table <PASSWORD num> import_filename FROM source_filename TABLE
input_tablename CHARMAX max_field_length MEMOMAX max_field_length

Parameters
Name Description

TO table The name of the Analytics table to import the data into.
Note
Table names are limited to 64 alphanumeric characters. The name can
include the underscore character ( _ ), but no other special characters, or
any spaces. The name cannot start with a number.

PASSWORD num Used only with password-protected Access files.

optional The password definition to use.
You do not use PASSWORD num to prompt for, or specify, an actual password. The
password definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2
specifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag

import_filename The name of the Analytics data file to create.

Specify import_filename as a quoted string with a .FIL file extension. For example,
"Invoices.FIL".
By default, the data file (.FIL) is saved to the folder containing the Analytics project.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 234 of 934

Commands

Name Description

Use either an absolute or relative file path to save the data file to a different, existing
folder:
o "C:\data\Invoices.FIL"
o "data\Invoices.FIL"

FROM source_filename The name of the source data file. source_filename must be a quoted string.
If the source data file is not located in the same directory as the Analytics project, you
must use an absolute path or a relative path to specify the file location:
o "C:\data\source_filename"
o "data\source_filename"

TABLE input_tablename The name of the table in the Microsoft Access database file to import.

CHARMAX max_field_ The maximum length in characters for any field in the Analytics table that originates as
length character data in the source from which you are importing.
You can specify from 1 to 255 characters.

MEMOMAX max_field_ The maximum length in characters for text, note, or memo fields you are importing.
length
You can specify from 1 to 32767 characters (non-Unicode Analytics), or 16383 char-
acters (Unicode Analytics).

Examples
Note
For more information about how this command works, see the Analytics Help.

Importing into a table

You have a Microsoft Access file called Acceptable_Codes.mdb. You need to import the [Acceptable_
Codes] table from the file into Analytics. To do this, you use the following command and create a table called
acc_codes in Analytics.
The length of imported character or memo fields is set to the length of the longest value in the field, or to the
specified maximum number of characters, whichever is shorter:

SET ECHO NONE

SET PASSWORD 1 TO "qr347wx"
SET ECHO ON
IMPORT ACCESS TO acc_codes PASSWORD 1 "C:\ACL DATA\Sample Data Files\acc_codes.fil"
FROM "Acceptable_Codes.mdb" TABLE "[Acceptable_Codes]" CHARMAX 60 MEMOMAX 70

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 235 of 934

Commands

IMPORT DELIMITED command

Creates an Analytics table by defining and importing a delimited text file.

Syntax
IMPORT DELIMITED TO table import_filename FROM source_filename <SERVER profile_name>
source_char_encoding SEPARATOR {char|TAB|SPACE} QUALIFIER {char|NONE}
<CONSECUTIVE> STARTLINE line_number <KEEPTITLE> <CRCLEAR> <LFCLEAR>
<REPLACENULL> <ALLCHAR> {ALLFIELDS|[field_syntax] <...n> <IGNORE field_num> <...n>}

field_syntax ::=
FIELD name type AT start_position DEC value WID bytes PIC format AS display_name

Parameters
Name Description

import_filename The name of the Analytics data file to create.

Specify import_filename as a quoted string with a .FIL file extension. For example,
"Invoices.FIL".
By default, the data file (.FIL) is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
o "C:\data\Invoices.FIL"
o "data\Invoices.FIL"

SERVER profile_name The server profile name for the AX Server where the data you want to import is located.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 236 of 934

Commands

Name Description

optional

source_char_encoding The character set and encoding of the source data.

Depending on which edition of Analytics you are using, and the encoding of the source
data, specify the appropriate code:

Analytics edi-
Code tion Source data encoding

Non-Unicode all data

0 edition

0 Unicode edition ASCII data

2 Unicode edition Unicode data, UTF-16 LE encoding

Unicode edition Unicode data that does not use UTF-16 LE encoding
To determine the numeric code that matches the source
data encoding, perform an import using the Data Defin-
ition Wizard, select the Encoded Text option, and
find the matching encoding in the accompanying drop-
down list.
3 numeric_ To specify the code, specify 3 , followed by a space, and
code then the numeric code.

SEPARATOR char The separator character (delimiter) used between fields in the source data. You must
| TAB | SPACE specify the character as a quoted string.
You can specify a tab or a space separator by typing the character between double quo-
tation marks, or by using a keyword:
o SEPARATOR " " or SEPARATOR TAB
o SEPARATOR " " or SEPARATOR SPACE

QUALIFIER char | NONE The text qualifier character used in the source data to wrap and identify field values.
You must specify the character as a quoted string.
To specify the double quotation mark character as the text qualifier, enclose the char-
acter in single quotation marks: QUALIFIER '"'.
You can specify that there are no text qualifiers using either of these methods:
o QUALIFIER ""
o QUALIFIER NONE

CONSECUTIVE Consecutive text qualifiers are treated as a single qualifier.

optional

STARTLINE line_number The line the data begins on.

For example, if the first four lines of data contain header information that you do not
want, specify 5 for line_number.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 237 of 934

Commands

Name Description

KEEPTITLE Treat the line number specified by STARTLINE as field names instead of data. If you
omit KEEPTITLE, generic field names are used.
optional
If you specify FIELD syntax individually, FIELD name takes precedence over the values
in the first row in the delimited file. In this situation, KEEPTITLE prevents the first row val-
ues from being imported.

CRCLEAR Replaces any CR characters (carriage return) that occur between text qualifiers with
space characters. You must specify QUALIFIER with a char value to use CRCLEAR.
optional
If you use both CRCLEAR and LFCLEAR, CRCLEAR must come first.

LFCLEAR Replaces any LF characters (line feed) that occur between text qualifiers with space
characters. You must specify QUALIFIER with a char value to use LFCLEAR.
optional
If you use both CRCLEAR and LFCLEAR, CRCLEAR must come first.

REPLACENULL Replaces any NUL characters that occur in the delimited file with space characters. The
number of any replaced NUL characters is recorded in the log.
optional

ALLCHAR The Character data type is automatically assigned to all the imported fields.
optional Tip
Assigning the Character data type to all the imported fields simplifies the
process of importing delimited text files. Once the data is in Analytics,
you can assign different data types, such as Numeric or Datetime, to the
fields, and specify format details.
ALLCHAR is useful if you are importing a table with identifier fields auto-
matically assigned the Numeric data type by Analytics when in fact they
should use the Character data type.

ALLFIELDS All fields in the source data file are imported.

For information about how Analytics assigns data types when you use ALLFIELDS, see
"Remarks" on page 241.
Note
If you specify ALLFIELDS, do not specify any individual FIELD syntax, or
IGNORE.

FIELD name type The individual fields to import from the source data file, including the name and data
type of the field. To exclude a field from being imported, do not specify it.
For information about type, see "Identifiers for field data types" on page 242.
Note
type is ignored if you specify ALLCHAR.

AT start_position The starting byte position of the field in the Analytics data file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 238 of 934

Commands

Name Description

Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, typically you should specify an odd-numbered start-

ing byte position. Specifying an even-numbered starting position can
cause characters to display incorrectly.

DEC value The number of decimals for numeric fields.

Note
DEC is ignored if you specify ALLCHAR.

WID bytes The length in bytes of the field in the Analytics table layout.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, specify an even number of bytes only. Specifying

an odd number of bytes can cause characters to display incorrectly.

PIC format Note

Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in
the source data. For example, if the source data is 12/31/2014, you
must enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.
Note
PIC is ignored if you specify ALLCHAR.

AS display_name The display name (alternate column title) for the field in the view in the new Analytics
table.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title.
AS is required when you are defining FIELD. To make the display name the same as
the field name, enter a blank display_name value using the following syntax: AS "".
Make sure there is no space between the two double quotation marks.

IGNORE field_num <...n> Excludes the field from the table layout.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 239 of 934

Commands

Name Description

optional field_num specifies the position of the field in the source data. For example, IGNORE 5
excludes the fifth field in the source data from the Analytics table layout.
Note
The data in the field is still imported, but it is undefined, and does not
appear in the new Analytics table. The data can be defined later, if
necessary, and added to the table.
To completely exclude a field from being imported, do not specify it when
you specify fields individually.

Examples
Importing all fields
You import all fields from a comma delimited file to an Analytics table named Employees . The file uses
double quotation marks as the text qualifiers. Data types are automatically assigned based on the set of
rules outlined in "Remarks" on the facing page:

IMPORT DELIMITED TO Employees "Employees.fil" FROM "Employees.csv" 0 SEPARATOR ","

QUALIFIER '"' CONSECUTIVE STARTLINE 1 KEEPTITLE ALLFIELDS

Importing all fields, automatically assign a Character data type

You import all fields from a comma delimited file to an Analytics table named Employees . The file uses
double quotation marks as the text qualifiers. The Character data type is automatically assigned to all
imported fields:

IMPORT DELIMITED TO Employees "Employees.fil" FROM "Employees.csv" 0 SEPARATOR ","

QUALIFIER '"' CONSECUTIVE STARTLINE 1 KEEPTITLE ALLCHAR ALLFIELDS

Importing specified fields, automatically assign a Character data type

You import specified fields from a tab delimited file to an Analytics table named Employees . The file uses
double quotation marks as the text qualifiers. The Character data type is automatically assigned to all
imported fields:

IMPORT DELIMITED TO Employees "Employees.fil" FROM "Employees.csv" 0 SEPARATOR TAB

QUALIFIER '"' CONSECUTIVE STARTLINE 1 KEEPTITLE ALLCHAR FIELD "First_Name" C AT 1
DEC 0 WID 25 PIC "" AS "First Name" FIELD "Last_Name" C AT 26 DEC 0 WID 25 PIC "" AS "Last
Name" FIELD "CardNum" C AT 51 DEC 0 WID 16 PIC "" AS "Card Num" FIELD "EmpNo" C AT 67
DEC 0 WID 6 PIC "" AS "Emp Num" FIELD "HireDate" C AT 73 DEC 0 WID 10 PIC "" AS "Hire Date"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 240 of 934

Commands

FIELD "Salary" C AT 83 DEC 0 WID 5 PIC "" AS "" FIELD "Bonus_2016" C AT 88 DEC 0 WID 10 PIC
"" AS "Bonus 2016"

Importing specified fields, assign data types individually

You import specified fields from a semi-colon delimited file to an Analytics table named Employees . The file
does not use text qualifiers. You specify the data type of each imported field:

IMPORT DELIMITED TO Employees "Employees.fil" FROM "Employees.csv" 0 SEPARATOR ";"

QUALIFIER "" CONSECUTIVE STARTLINE 1 KEEPTITLE FIELD "First_Name" C AT 1 DEC 0 WID
25 PIC "" AS "First Name" FIELD "Last_Name" C AT 26 DEC 0 WID 25 PIC "" AS "Last Name" FIELD
"CardNum" C AT 51 DEC 0 WID 16 PIC "" AS "Card Num" FIELD "EmpNo" C AT 67 DEC 0 WID 6 PIC
"" AS "Emp Num" FIELD "HireDate" D AT 73 DEC 0 WID 10 PIC "MM/DD/YYYY" AS "Hire Date"
FIELD "Salary" N AT 83 DEC 0 WID 5 PIC "" AS "" FIELD "Bonus_2016" N AT 88 DEC 2 WID 10 PIC
"" AS "Bonus 2016"

Remarks
Note
For more information about how this command works, see the Analytics Help.

How Analytics assigns data types when you use

ALLFIELDS
When you use the ALLFIELDS parameter, instead of individually defining fields, Analytics examines a sub-
set of records at the beginning of the delimited file and assigns data types based on the set of rules outlined
below.
Once the data is in Analytics, you can assign different data types, such as Numeric or Datetime, to the fields,
and specify format details.

Description of field values in the delimited file Examples Data type assigned

Values enclosed by text qualifiers "ABC Suppliers" Character

"6,990.75"

Values include a non-numeric character anywhere in the field, with the $995 Character
exception of commas and periods used as numeric separators, and
(995)
the negative sign (-)

Values include only numbers, numeric separators, or the negative 6,990.75 Numeric
sign
-6,990.75
995

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 241 of 934

Commands

Description of field values in the delimited file Examples Data type assigned

One or more blank values occur in a field Character

Datetime values with separators, or alpha months 2016/12/31 Character

31 Dec 2016

Datetime values that are all numbers 20161231 Numeric

Identifiers for field data types

The table below lists the letters that you must use when specifying type for FIELD. Each letter corresponds
to a data type.
For example, if you are defining a Last Name field, which uses a character data type, you would specify
"C": FIELD "Last_Name" C.
Note
When you use the Data Definition Wizard to define a table that includes EBCDIC,
Unicode, or ASCII fields, the fields are automatically assigned the letter "C" (for the
CHARACTER type).
When you enter an IMPORT statement manually, or edit an existing IMPORT statement,
you can substitute the more specific letters "E" or "U" for EBCDIC or Unicode fields.

Letter Data type

A ACL

B BINARY

C CHARACTER

D DATETIME

E EBCDIC

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

L LOGICAL

N PRINT

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 242 of 934

Commands

Letter Data type

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Y UNISYS

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 243 of 934

Commands

IMPORT EXCEL command

Creates an Analytics table by defining and importing a Microsoft Excel worksheet or named range.

Syntax
IMPORT EXCEL TO table import_filename FROM source_filename TABLE input_worksheet_or_
named_range <KEEPTITLE> {ALLFIELDS|CHARMAX max_field_length|[field_syntax] <...n>
<IGNORE field_num> <...n>} <OPEN>

field_syntax ::=
FIELD name type {PIC format|WID characters DEC value} AS display_name

Parameters
Name Description

import_filename The name of the Analytics data file to create.

TABLE worksheet_or_ The Microsoft Excel worksheet or the named range in the source data file to import:
named_range o you must enter a "$" sign at the end of a worksheet name

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 244 of 934

Commands

Name Description

o worksheet_or_named_range must be specified as a quoted string

KEEPTITLE Treat the first row of data as field names instead of data. If omitted, generic field names
are used.
optional
If you are defining fields individually, KEEPTITLE must appear before the first FIELD.

ALLFIELDS All fields in the source data file are imported.

Note
If you specify ALLFIELDS, do not specify any individual FIELD syntax,
CHARMAX, or IGNORE.

CHARMAX max_field_ Only applies when you are not defining fields individually.
length
The maximum length in characters for any field in the Analytics table that originates as
character data in the source data file.

PIC format Note

WID characters The length in characters of the field in the Analytics table layout.

DEC value The number of decimals for numeric fields.

IGNORE field_num <...n> Excludes the field from the table layout.

optional field_num specifies the position of the field in the source data. For example, IGNORE 5
excludes the fifth field in the source data from the Analytics table layout.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 245 of 934

Commands

Name Description

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Importing specified fields
You perform an import that defines a new Analytics table called Credit_Cards . It uses the first row of Excel
data as the field names.
The Analytics table defines and includes three fields from the source table, but excludes the remaining
fields:

IMPORT EXCEL TO Credit_Cards "Credit Cards.fil" FROM "Credit_Cards_Metaphor.xls" TABLE

"Corp_Credit_Cards$" KEEPTITLE FIELD "CARDNUM" N WID 16 DEC 0 AS "Card Number"
FIELD "EXPDT" D WID 10 PIC "YYYY-MM-DD" AS "Expiry Date" FIELD "PASTDUEAMT" N WID 6
DEC 2 AS "Past Due" IGNORE 2 IGNORE 3 IGNORE 5 IGNORE 6 IGNORE 7 IGNORE 9 IGNORE
10 IGNORE 11 IGNORE 12

Importing all fields

You perform an import that defines a new Analytics table called May_Transactions . It uses the first row of
Excel data as the field names.
The Analytics table includes all fields from the source table and uses default field definitions.

Field length set to longest value

In the first example, fields that originate as character data in the source data file are set to the length of the
longest value in the field:

IMPORT EXCEL TO May_Transactions "May_Transactions.fil" FROM "Trans_May.xls" TABLE

"Trans1_May$" KEEPTITLE ALLFIELDS

Field length constrained

In the second example, fields that originate as character data in the source data file are set to the length of
the longest value in the field, or to the CHARMAX value of 100 characters, whichever is shorter:

IMPORT EXCEL TO May_Transactions "May_Transactions.fil" FROM "Trans_May.xls" TABLE

"Trans1_May$" KEEPTITLE CHARMAX 100

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 246 of 934

Commands

Remarks
Note
For more information about how this command works, see the Analytics Help.

Define fields individually, or import all fields using a default

definition
When you import an Excel file to an Analytics table you can use FIELD parameters to define each field indi-
vidually, or you can use the ALLFIELDS parameter, or the CHARMAX parameter, to import all fields using
default Analytics field definitions.

Maximum size of data import

File format .xlsx or .xlsm
The maximum number of Excel columns, and the maximum number of characters in a field, that you can
import from .xlsx or .xlsm files is not limited to a specific number.
Importing from these Excel file types is governed by the record length limit in Analytics data files (.fil) of
32 KB. If any record in the source Excel file would create an Analytics record longer than 32 KB, the import
fails.

File format .xls

The import of .xls (Excel 97 - 2003) files uses a different type of processing, and is subject to maximums of:
l 255 columns
l 255 characters per field
l 32 KB per record
l 65,000 rows

Identifiers for field data types

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 247 of 934

Commands

Note
When you use the Data Definition Wizard to define a table that includes EBCDIC,
Unicode, or ASCII fields, the fields are automatically assigned the letter "C" (for the
CHARACTER type).
When you enter an IMPORT statement manually, or edit an existing IMPORT statement,
you can substitute the more specific letters "E" or "U" for EBCDIC or Unicode fields.

Letter Data type

A ACL

B BINARY

C CHARACTER

D DATETIME

E EBCDIC

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

L LOGICAL

N PRINT

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Y UNISYS

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 248 of 934

Commands

Letter Data type

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 249 of 934

Commands

IMPORT GRCPROJECT command

Creates an Analytics table by importing a HighBond Projects table.

Syntax
IMPORT GRCPROJECT TO table import_filename PASSWORD num FROM org_id/type_id
<FIELD name AS display_name <...n>>

Parameters
Name Description

import_filename The name of the Analytics data file to create.

PASSWORD num The password definition to use.

You do not use PASSWORD num to prompt for, or specify, an actual password. The
password definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2
specifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 250 of 934

Commands

Name Description

l PASSWORD command
l SET command
l PASSWORD analytic tag
Note
PASSWORD may or may not be required, depending on the envir-
onment in which the script runs:

Analytics PASSWORD is not required.

(online activation) The current user's HighBond
access token is automatically
used.

Analytics PASSWORD is required.

(offline activation)

Robots

Analytics Exchange

Analysis App window

FROM org_id/type_id The organization and type of information that defines the data being imported:
o org_id – the Projects organization you are importing data from
o type_id – the type of information you are importing
The org_id value and the type_id value must be separated by a slash, with no inter-
vening spaces: FROM "125@eu/audits".
The entire string must be enclosed in quotation marks.

Organization ID
org_id must include the organization ID number, and if you are importing from a data
center other than North America, the data center code. The organization ID number and
the data center code must be separated by the at sign (@): FROM "125@eu".
The data center code specifies which regional HighBond server you are importing the
data from:
o ap – Asia Pacific
o au – Australia
o ca – Canada
o eu – Europe
o us – North America
You can use only the data center code or codes authorized for your organization's
installation of HighBond. The North America data center is the default, so specifying
"@us" is optional.
If you do not know the organization ID number, use the Analytics user interface to import
a table from Projects. The organization ID number is contained in the command in the
log. For more information, see Defining ACL GRC data.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 251 of 934

Commands

Name Description

Type ID
type_id specifies the type of information you are importing. Information in Projects is con-
tained in a series of related tables.
For type_id, use one of the values listed below. Enter the value exactly as it appears
and include underscores, if applicable:
o audits - Projects
o control_test_plans - Control Test Plans
o control_tests - Control Test
o controls - Controls
o finding_actions - Actions
o findings - Issues
o mitigations - Risk Control Associations
o narratives - Narratives
o objectives- Objectives
o risks - Risks
o walkthroughs - Walkthroughs
Tip
For information about how the tables in Projects are related, and the key
fields that you can use to join the tables once you have imported them to
Analytics, see Defining ACL GRC data.

FIELD name AS display_ Individual fields in the source data to import. Specify the name.
name <...n>
If you omit FIELD, all fields are imported.
optional o name must exactly match the physical field name in the Projects table, including
matching the case
o display_name (alternate column title) is the display name for the field in the view in
the new Analytics table. You must specify a display name for each FIELD name. Spe-
cify display_name as a quoted string.
Use a semi-colon (;) between words if you want a line break in the column title.
Unlike some other IMPORT commands in Analytics, you cannot specify a blank dis-
play_name as a way of using the FIELD name as the display name.
Tip
To get the physical field names, use the Analytics user interface to import
the appropriate table from Projects. The physical field names are con-
tained in the command in the log.
Subsequent imports can be scripted.

Examples
Importing all fields from the Projects table
You import all fields from the Projects table for all active projects belonging to organization 286 to an Ana-
lytics table named All_Projects . You include a numbered password definition to authenticate the

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 252 of 934

Commands

connection:

IMPORT GRCPROJECT TO All_Projects "C:\ACL GRC Project Data\All_Projects.fil" PASSWORD 1

FROM "286@us/audits"

Importing specified fields from the Projects table

You import specified fields from the Projects table for all active projects belonging to organization 286 to an
Analytics table named All_Projects :

IMPORT GRCPROJECT TO All_Projects "C:\ACL GRC Project Data\All_Projects.fil" FROM

"286@us/audits" FIELD "id" AS "Id" FIELD "description" AS "Description" FIELD "name" AS "Name"
FIELD "start_date" AS "Start date" FIELD "status" AS "Status" FIELD "created_at" AS "Created at"

Importing all fields from the Issues table

You import all fields from the Issues table for all active projects belonging to organization 286 to an Ana-
lytics table named All_Issues :

IMPORT GRCPROJECT TO All_Issues "C:\ACL GRC Project Data\All_Issues.fil" FROM

"286@us/findings"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Creating a password definition and specifying a password

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 253 of 934

Commands

Regardless of which method you use to create the password definition, the required password value is a
HighBond access token:
l PASSWORD method – Users can acquire an access token by selecting Tools > HighBond
Access Token, and then signing in to HighBond. An access token is returned, which users can
copy and paste into the password prompt.
l SET PASSWORD method – To insert an access token into the SET PASSWORD command syn-
tax in an Analytics script, right-click in the Script Editor, select Insert > HighBond Token, and sign
in to HighBond. An access token is inserted into the script at the cursor position.
Caution
The returned access token matches the account used to sign in to HighBond. As a
scriptwriter, using your own access token may not be appropriate if you are writing a script
to be used by other people.

Import debug capability

A simple debug capability exists for imports from HighBond.
The imported data is temporarily stored in a JSON intermediary file in the folder containing the target
Analytics project. In any folder containing an Analytics project you can create a text file that causes the
JSON file to be retained, instead of being deleting after the data is imported into Analytics.
l JSON file is present – If the import from HighBond is failing, but the JSON file is present on your
computer, you know that the problem is on the Analytics side, not on the HighBond side.
l JSON file is not present – If the import from HighBond is failing, and the JSON file is not present on
your computer, you know that the problem is on the HighBond side.
This information can help with troubleshooting.

Configure retention of the JSON intermediary file

In the folder containing the target Analytics project, create an empty text file with exactly this name: _grc_
import_debug.txt
When you import from either Results or Projects in HighBond, the JSON intermediary file is retained with
the name results.json. The file is overwritten with each subsequent import from HighBond.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 254 of 934

Commands

IMPORT GRCRESULTS command

Creates an Analytics table by importing a HighBond Results table or interpretation.

Syntax
IMPORT GRCRESULTS TO table import_filename PASSWORD num FROM Results_resource_path
<FIELD name AS display_name <...n>>

Parameters
Name Description

import_filename The name of the Analytics data file to create.

PASSWORD num The password definition to use.

You do not use PASSWORD num to prompt for, or specify, an actual password. The pass-
word definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2 spe-
cifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 255 of 934

Commands

Name Description

l PASSWORD command
l SET command
l PASSWORD analytic tag
Note
PASSWORD may or may not be required, depending on the environment
in which the script runs:

Analytics PASSWORD is not required.

(online activation) The current user's HighBond
access token is automatically used.

Analytics PASSWORD is required.

(offline activation)

Robots

Analytics Exchange

Analysis App window

FROM Results_resource_ The path to the data you are importing.

path
The form of the path varies depending on the data you are importing. For details about
the form of the path, see "Results path" on page 258.
Note
The form of the Results path is supplied by an API, and is subject to
change. The easiest and most reliable way to acquire the correct and cur-
rent syntax for the path is to perform a manual import of the target data,
and copy the path from the command log.

FIELD name AS display_ Individual fields in the source data to import. Specify the name.
name <...n>
If you omit FIELD, all fields are imported.
optional
Name
name must exactly match the physical field name in the Results table, including matching
the case. To view the physical field name, do one of the following:
o In Results, click a column header in the Table View. The physical field name appears
after Field Name.
o In Analytics, when you import a Results table, the physical field name appears in par-
entheses after the display name in the dialog box that allows you to select fields.
Note
The Results physical field name is not the display name used for column
headers in the Table View.
Also see "Field name considerations when importing and exporting Results data" on
page 259.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 256 of 934

Commands

Name Description

Display name
display_name (alternate column title) is the display name for the field in the view in the
new Analytics table. You must specify a display name for each FIELD name. Specify dis-
play_name as a quoted string.
Use a semi-colon (;) between words if you want a line break in the column title.
Unlike some other IMPORT commands in Analytics, you cannot specify a blank display_
name as a way of using the FIELD name as the display name.

Examples
Importing specified fields from a table in Results
You import specified fields from a table in Results to an Analytics table named T and E exceptions :

IMPORT GRCRESULTS TO T_and_E_exceptions "C:\Secondary Analysis\T_and_E_exceptions.fil"

PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" FIELD
"metadata.status" AS "Status" FIELD "EmpNo" AS "Employee Number" FIELD "DATE" AS "Date"
FIELD "CARDNUM" AS "Card Number" FIELD "CODES" AS "MC Codes" FIELD "AMOUNT" AS
"Amount" FIELD "DESCRIPTION" AS "Description"

Importing all fields from a table in Results

You import all fields from a table in Results to an Analytics table named T and E exceptions :

IMPORT GRCRESULTS TO T_and_E_exceptions "C:\Secondary Analysis\T_and_E_exceptions.fil"

PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions"

Importing data from an interpretation in Results

You import an interpretation in Results to an Analytics table named T and E exceptions filtered:

IMPORT GRCRESULTS TO T_and_E_exceptions_filtered "C:\Secondary Analysis\T_and_E_excep-

tions_filtered.fil" FROM "results/api/orgs/11594/control_test-
s/185699/interpretations/22699/exceptions"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 257 of 934

Commands

Preserving sort order and filters

When you import data from Results, any data customization, such as sorting or filter, is retained or ignored
in the resulting Analytics table depending on how you import the data:
l import a table – data customization is ignored. All the data in the table is imported, with the excep-
tion of any fields you choose to omit.
l import an interpretation – data customization is retained

Results path
Note
The form of the Results path is supplied by an API, and is subject to change. The easiest
and most reliable way to acquire the correct and current syntax for the path is to perform a
manual import of the target data, and copy the path from the command log.
The Results path in the FROM parameter takes the following general form:
FROM "results <-region code>/api/orgs/<org ID>/control_tests/<control test ID>/exceptions
For example: FROM "results/api/orgs/11594/control_tests/4356/exceptions"
The org ID is displayed in the browser address bar when you log in to Launchpad. The control test ID, and
the interpretation ID, are displayed in the address bar when you are viewing those tables in Results.
The table below provides all the variations of the Results path.

To import: Use this form of Results path:

Control test (table) data FROM "results/api/orgs/11594/control_tests/4356/exceptions"

Control test (table) audit FROM "results/api/orgs/11594/control_tests/4356/audit_trail"

trail

Control test (table) com- FROM "results/api/orgs/11594/control_tests/4356/comments"

ments

Interpretation FROM "results/api/orgs/11594/control_tests/4356/interpretations/1192/exceptions"

Data from a HighBond o Asia Pacific – FROM "results-ap/api/orgs/11594/control_tests/4356/exceptions"

region other than the o Australia – FROM "results-au/api/orgs/11594/control_tests/4356/exceptions"
default region (us) o Canada – FROM "results-ca/api/orgs/11594/control_tests/4356/exceptions"
o Europe – FROM "results-eu/api/orgs/11594/control_tests/4356/exceptions"

System-generated information columns

When you import data from Results, you have the option of also importing one or more of the system-gen-
erated information columns listed below.
The system-generated columns are either:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 258 of 934

Commands

l part of Results tables, and contain processing information related to individual records
l additional information – collection name, table name, or record ID number
You must specify the field names of the system-generated columns exactly as they appear below. The
default display names apply when you import from Results through the Analytics user interface. You are
free to change the display names if you are scripting the import process.

Field name Default display name

metadata.priority Priority

metadata.status Status

metadata.publish_date Published

metadata.publisher Publisher Name

metadata.assignee Assignee

metadata.group Group

metadata.updated_at Updated

metadata.closed_at Closed

extras.collection Collection

extras.results_table Results Table

extras.record_id Record ID

Field name considerations when importing and exporting

Results data
If you are round-tripping data between Results and Analytics, you need to ensure that all field names in the
Results table meet the more stringent Analytics field name requirements. If you do not, you risk misaligning
your Analytics and Results data.
For example, any special characters in Results field names are automatically converted to underscores
when they are imported into Analytics, which means the field names no longer match the original names in
Results. If you then export the Analytics data back to the original table in Results, fields are no longer cor-
rectly matched.
To avoid this problem with data that you intend to round-trip, make sure that before you upload the data to
Results from CSV or Excel files it meets these Analytics field name requirements:
l no special characters or spaces
l does not start with a number
l contains only alphanumeric characters, or the underscore character ( _ )

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 259 of 934

Commands

Creating a password definition and specifying a password

value
PASSWORD command
If you use the PASSWORD command to create the numbered password definition for connecting to
HighBond, no password value is specified, so a password prompt is displayed when the script attempts to
connect.
For more information, see "PASSWORD command" on page 350.
SET PASSWORD command
If you use the SET PASSWORD command to create the numbered password definition for connecting to
HighBond, a password value is specified, so no password prompt is displayed, which is appropriate for
scripts designed to run unattended.
For more information, see SET PASSWORD command.
HighBond access token
Regardless of which method you use to create the password definition, the required password value is a
HighBond access token:
l PASSWORD method – Users can acquire an access token by selecting Tools > HighBond
Access Token, and then signing in to HighBond. An access token is returned, which users can
copy and paste into the password prompt.
l SET PASSWORD method – To insert an access token into the SET PASSWORD command syn-
tax in an Analytics script, right-click in the Script Editor, select Insert > HighBond Token, and sign
in to HighBond. An access token is inserted into the script at the cursor position.
Caution
The returned access token matches the account used to sign in to HighBond. As a
scriptwriter, using your own access token may not be appropriate if you are writing a script
to be used by other people.

Import debug capability

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 260 of 934

Commands

Configure retention of the JSON intermediary file

In the folder containing the target Analytics project, create an empty text file with exactly this name: _grc_
import_debug.txt
When you import from either Results or Projects in HighBond, the JSON intermediary file is retained with the
name results.json. The file is overwritten with each subsequent import from HighBond.

Importing large tables

Tables that have a large number of fields may not successfully import using a single
IMPORT GRCRESULTS command. If you need to work with a single table containing a large number of
fields outside of Results, use one of the following approaches:
l Split the table – use two or more IMPORT GRCRESULTS commands to import a subset of fields and
then join the resulting tables in Analytics using the JOIN command
l Export the table to file – use the export to CSV format and then import the resulting file into Analytics
using the IMPORT DELIMITED command

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 261 of 934

Commands

IMPORT LAYOUT command

Imports an external table layout file (.layout) to an Analytics project.
Note:
Prior to version 11 of Analytics, external table layout files used an .fmt file extension. You
can still import a table layout file with an .fmt extension by manually specifying the exten-
sion.

Syntax
IMPORT LAYOUT external_layout_file TO table_layout_name

Parameters
Name Description

external_layout_file The name of the external table layout file. If the file name or path includes any spaces it
must be enclosed in quotation marks – for example, "Ap Trans.layout".
The .layout file extension is used by default and does not need to be specified. If
required, you can use another file extension, such as .fmt.
If the layout file is not located in the same folder as the Analytics project, you must use
an absolute path or a relative path to specify the file location – for example,
"C:\Saved layouts\Ap_Trans.layout" or "Saved layouts\Ap_Trans.layout".

TO table_layout_name The name of the imported table layout in the Analytics project – for example,
"Ap Trans May". You must specify the table_layout_name as a quoted string if it con-
tains any spaces. You can specify a table_layout_name that is different from the name
of the external_layout_file.

Example
Importing an external table layout file
You import an external table layout file called Ap_Trans.layout and create a new table layout called Ap_
Trans _May in the Analytics project:

IMPORT LAYOUT "C:\Saved layouts\Ap_Trans.layout" TO "Ap_Trans_May"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 262 of 934

Commands

Remarks
When to use IMPORT LAYOUT
Importing an external table layout file and associating it with a data file can save you the labor of creating a
new table layout from scratch:
l If the imported table layout specifies an association with a particular Analytics data file (.fil), and a data
file of the same name exists in the folder containing the project, the imported table layout is auto-
matically associated with the data file in the folder.
l If there is no data file with the same name in the project folder, you need to link the imported table lay-
out to a new data source.

Table layouts and source data files must match

The imported table layout and the data file it is associated with must match. The structure of the data in the
data file must match the field definitions specified by the table layout metadata.
Data structure refers to the data elements (fields) contained in a data file, the number and order of the fields,
and the data type and length of the fields. If the table layout and the data file do not match, jumbled or miss-
ing data results.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 263 of 934

Commands

IMPORT MULTIDELIMITED com-

mand
Creates multiple Analytics tables by defining and importing multiple delimited files.

Syntax
IMPORT MULTIDELIMITED <TO import_folder> FROM {source_filename|source_folder} source_
char_encoding SEPARATOR {char|TAB|SPACE} QUALIFIER {char|NONE} <CONSECUTIVE>
STARTLINE line_number <KEEPTITLE> <CRCLEAR> <LFCLEAR> <REPLACENULL>
<ALLCHAR>

Note
You must specify the IMPORT MULTIDELIMITED parameters in exactly the same order
as above, and in the table below.
To import multiple delimited files cleanly, the structure of all the files must be consistent
before importing.
For more information, see "Consistent file structure required" on page 269.

Parameters
Name Description

TO import_folder The folder to import the data into.

optional To specify the folder, use an absolute file path, or a file path relative to the folder con-
taining the Analytics project. Specify import_folder as a quoted string.

Example

TO "C:\Point of sale audit\Data\Transaction working data"

TO "Data\Transaction working data"

If you omit TO , the data is imported to the folder containing the Analytics project.

FROM source_filename | The name of the source data files, or the folder containing the source data files.
source_folder
Specify source_filename or source_folder as a quoted string.
The command supports importing four types of delimited file:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 264 of 934

Commands

Name Description

o *.csv
o *.dat
o *.del
o *.txt
Source data files in the root Analytics project folder
To specify multiple files, use a wildcard character (*) in place of unique characters in file
names. The wildcard character stands for zero (0) or more occurrences of any letter,
number, or special character.

Example

FROM "Transactions_FY*.csv"

selects:
Transactions_FY18.csv
Transactions_FY17.csv
You can use a wildcard in more than one location in a file name, and in a file extension.

Example

FROM "Transactions_FY*.*"

selects:
Transactions_FY18.txt
Transactions_FY17.csv
Source data files not in the root Analytics project folder
If the source data files are not located in the same folder as the Analytics project, you
must use an absolute file path, or a file path relative to the folder containing the project,
to specify the location of the files.

Example

FROM "C:\Point of sale audit\Data\Transaction master files\Transactions_FY*.csv"

FROM "Data\Transaction master files\Transactions_FY*.csv"

Folder containing source data files

Instead of specifying file names, you can just specify the name of the folder containing
source data files. All supported delimited files in the folder are imported (*.csv, *.dat,
*.del, *.txt).
To specify a source data folder, use an absolute file path, or a file path relative to the
folder containing the Analytics project.

Example

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 265 of 934

Commands

Name Description

FROM "C:\Point of sale audit\Data\Transaction master files"

FROM "Data\Transaction master files"

source_char_encoding The character set and encoding of the source data.

Depending on which edition of Analytics you are using, and the encoding of the source
data, specify the appropriate code:

Analytics edi-
Code tion Source data encoding

Non-Unicode all data

0 edition

0 Unicode edition ASCII data

2 Unicode edition Unicode data, UTF-16 LE encoding

Note
If you do not specify a code, Non-Unicode Analytics automatically uses 0
, and Unicode Analytics automatically uses 2 .

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 266 of 934

Commands

Name Description

CONSECUTIVE Consecutive text qualifiers are treated as a single qualifier.

optional

STARTLINE line_number The line the data begins on.

For example, if the first four lines of data contain header information that you do not
want, specify 5 for line_number.
Note
Ideally, the start line of the data should be the same in all the delimited
files that you import with a single execution of
IMPORT MULTIDELIMITED.
If start lines are different, see "Consistent file structure required" on
page 269.

KEEPTITLE Treat the line number specified by STARTLINE as field names instead of data. If you
omit KEEPTITLE, generic field names are used.
optional
Note
The field names must be on the same line number in all the delimited
files that you import with a single execution of
IMPORT MULTIDELIMITED.
If field names are on different line numbers, see "Consistent file structure
required" on page 269.

REPLACENULL Replaces any NUL characters that occur in the delimited file with space characters. The
number of any replaced NUL characters is recorded in the log.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 267 of 934

Commands

Examples
The examples below assume that you have monthly transaction data stored in 12 delimited files:
l Transactions_Jan.csv to Transactions_Dec.csv
Note
A separate Analytics table is created for each delimited file that you import.

Import all the delimited files

You want to import all 12 delimited files. You use the wildcard symbol (*) where the month occurs in each
file name.
Analytics attempts to assign the appropriate data type to each field.

IMPORT MULTIDELIMITED FROM "Transactions_*.csv" 0 SEPARATOR "," QUALIFIER '"'

CONSECUTIVE STARTLINE 1 KEEPTITLE

Import all the delimited files as character data

This example is the same as the one above, except Analytics automatically assigns the Character data
type to all the imported fields.

IMPORT MULTIDELIMITED FROM "Transactions_*.csv" 0 SEPARATOR "," QUALIFIER '"'

CONSECUTIVE STARTLINE 1 KEEPTITLE ALLCHAR

Import all the delimited files from the specified folder

You want to import all the delimited files in the C:\Point of sale audit\Data\Transaction
master files folder.

IMPORT MULTIDELIMITED FROM "C:\Point of sale audit\Data\Transaction master files" 0

SEPARATOR "," QUALIFIER '"' CONSECUTIVE STARTLINE 1 KEEPTITLE

Import all the delimited files from the specified folder, and save the Analytics
tables to another folder
This example is the same as the one above, but instead of saving the Analytics tables in the root project
folder, you want to save them in the C:\Point of sale audit\Data\Transaction working
data folder.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 268 of 934

Commands

IMPORT MULTIDELIMITED TO "C:\Point of sale audit\Data\Transaction working data" FROM

"C:\Point of sale audit\Data\Transaction master files" 0 SEPARATOR "," QUALIFIER '"'
CONSECUTIVE STARTLINE 1 KEEPTITLE

Remarks
Consistent file structure required
To import a group of delimited files cleanly using IMPORT MULTIDELIMITED, the structure of all the files in
the group must be consistent.
You can import inconsistently structured delimited files, and subsequently perform data cleansing and stand-
ardizing in Analytics. However, this approach can be labor intensive. In many cases, it is easier to make the
delimited files consistent before importing.
To import multiple delimited files cleanly, the following items need to be consistent across all files:

ACLScript
Item keyword Problem Solution

The character numeric code (Unicode edition of Analytics only) Group source files by encoding type,
set and encod- and do a separate import for each
Source delimited files use different
ing of the group.
character encodings. For example,
source data
some files have ASCII encoding and
some files have Unicode encoding.

Delimiter char- SEPARATOR Source delimited files use a different Do one of the following:
acter separator character (delimiter) o Standardize the separator character
between fields.
in the source files before importing
them.
o Group source files by separator char-
acter, and do a separate import for
each group.

Text qualifier QUALIFIER Source delimited files use a different Do one of the following:
character text qualifier character to wrap and o Standardize the qualifier character in
identify field values.
the source files before importing
them.
o Group source files by qualifier char-
acter, and do a separate import for
each group.

Start line of the STARTLINE Source delimited files have different Do one of the following:
data start lines for the data. o Standardize the start line in the
source files before importing them.
o Group source files that have the
same start line, and do a separate
import for each group.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 269 of 934

Commands

ACLScript
Item keyword Problem Solution

o Make line_number equal to the low-

est start line across all the files. Once
the files have been imported to Ana-
lytics tables, you can use the
"EXTRACT command" on page 197
to extract only the records from any
table with unwanted header inform-
ation.

Field names KEEPTITLE Source delimited files have field Do one of the following:
names on different line numbers. o Standardize the line number with the
field names in the source files before
importing them.
o Group source files that have field
names on the same line number,
and do a separate import for each
group.

Field names KEEPTITLE Some source delimited files have Do one of the following:
field names and some do not. o Add field names to the source files
that require them before importing all
files.
o Group source files that have field
names, and files that do not have
field names, and do a separate
import for each group.
o Omit KEEPTITLE to import all files
using generic field names. Once the
files have been imported to Analytics
tables, you can use the "EXTRACT
command" on page 197 to extract
only the data you want from any
table.

Multiple IMPORT DELIMITED commands

The IMPORT MULTIDELIMITED command actually performs multiple individual
IMPORT DELIMITED commands – one for each file imported. If you double-click the
IMPORT MULTIDELIMITED entry in the log, the individual IMPORT DELIMITED commands are dis-
played in the display area.

Combining multiple delimited files after importing them

After you import multiple delimited files into individual Analytics tables you might want to combine them into
a single Analytics table. For example, you could combine the data from twelve monthly tables into a single
annual table containing all the data.
For information about combining multiple Analytics tables, see "APPEND command" on page 72.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 270 of 934

Commands

IMPORT MULTIEXCEL command

Creates multiple Analytics tables by defining and importing multiple Microsoft Excel worksheets or named
ranges.

Syntax
IMPORT MULTIEXCEL <TO import_folder> FROM {source_filename|source_folder} TABLE input_
worksheets_or_named_ranges <PREFIX> <KEEPTITLE> <CHARMAX max_field_length>

Note
You must specify the IMPORT MULTIEXCEL parameters in exactly the same order as
above, and in the table below.

Parameters
Name Description

TO import_folder The folder to import the data into.

optional To specify the folder, use an absolute file path, or a file path relative to the folder con-
taining the Analytics project. Specify import_folder as a quoted string.

Example

TO "C:\Point of sale audit\Data\Transaction working data"

TO "Data\Transaction working data"

If you omit TO, the data is imported to the folder containing the Analytics project.

FROM source_filename | The name of the source data file or files, or the folder containing the source data file or
source_folder files.
Specify source_filename or source_folder as a quoted string.

Source data file or files in the root Analytics project folder

o single Excel file
Specify the compete file name and extension.

Example

FROM "Transactions_FY18.xlsx"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 271 of 934

Commands

Name Description

o multiple Excel files

To specify multiple files, use a wildcard character (*) in place of unique characters in
file names. The wildcard character stands for zero (0) or more occurrences of any let-
ter, number, or special character.

Example

FROM "Transactions_FY*.xlsx"

selects:
Transactions_FY18.xlsx
Transactions_FY17.xlsx
You can use a wildcard in more than one location in a file name, and in a file exten-
sion.

Example

FROM "Transactions_FY*.*"

selects:
Transactions_FY18.xlsx
Transactions_FY17.xls

Source data file or files not in the root Analytics project folder
If the source data file or files are not located in the same folder as the Analytics project,
you must use an absolute file path, or a file path relative to the folder containing the pro-
ject, to specify the file location.

Example

FROM "C:\Point of sale audit\Data\Transaction master files\Transactions_FY18.xlsx"

FROM "Data\Transaction master files\Transactions_FY*.xlsx"

Folder containing source data file or files

Instead of specifying a file name, you can just specify the name of the folder containing a
source data file or files.
To specify a source data folder, use an absolute file path, or a file path relative to the
folder containing the Analytics project.

Example

FROM "C:\Point of sale audit\Data\Transaction master files"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 272 of 934

Commands

Name Description

FROM "Data\Transaction master files"

Note
When you specify a folder, any worksheet in any Excel file in the folder is
imported if the worksheet name matches the TABLE value.

TABLE input_worksheets_ The name of the worksheets or named ranges to import. A separate Analytics table is cre-
or_named_ranges ated for each imported worksheet or named range.
Specify input_worksheets_or_named_ranges as a quoted string.
Use a wildcard (*) in place of unique characters in the names of worksheets or ranges.
For example, "Trans_*$" selects the following worksheets:
o Trans_Jan
o Trans_Feb
o Trans_Mar
o and so on
Note
The wildcard character (*) stands for zero (0) or more occurrences of any
letter, number, or special character.
You can use a wildcard in more than one location. For example, *Trans*$
selects:
l Trans_Jan
l Jan_Trans

The meaning of the dollar sign ($)

In an Excel file, worksheets are identified with a dollar sign ($) appended to the work-
sheet name (Trans_Jan$). The dollar sign is not visible in Excel.
Named ranges are identified by the absence of a dollar sign (Trans_Jan_commercial).
Specifying the dollar sign is not required when using IMPORT MULTIEXCEL. However,
you should include it, or exclude it, in the following situations:
o Include "$" – if you want to import only worksheets, and no named ranges, include the
dollar sign at the end of the worksheet name
o Exclude "$" – if you want to import named ranges, or worksheets and named ranges in
a single import operation, do not include the dollar sign

PREFIX Prepend the Excel file name to the name of the Analytics tables.
optional Tip
If worksheets in different files have the same name, prepending the Excel
file name allows you to avoid table name conflicts.

KEEPTITLE Treat the first row of data as field names instead of data. If omitted, generic field names
are used.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 273 of 934

Commands

Name Description

Note
All first rows in the worksheets and named ranges that you import should
use a consistent approach. First rows should be either field names, or
data, across all data sets. Avoid mixing the two approaches in a single
import operation.
If the data sets have an inconsistent approach to first rows, use two sep-
arate import operations.

CHARMAX max_field_ The maximum length in characters for any field in an Analytics table that originates as
length character data in a source data file.
optional

Examples
The examples below assume that you have monthly transaction data for three years stored in three Excel
files:
l Transactions_FY18.xlsx
l Transactions_FY17.xlsx
l Transactions_FY16.xlsx
Each Excel file has 12 worksheets – one for each month of the year. The worksheets also include some
named ranges identifying various subsets of transactions.
Note
A separate Analytics table is created for each worksheet or named range that you import.

Import worksheets
Import all FY18 worksheets
You want to import all 12 monthly worksheets from the FY18 Excel file, and ignore any named ranges.
l you use the wildcard symbol (*) where the month occurs in each worksheet name
l you include the dollar sign ($) at the end of the worksheet name so that only worksheets are selec-
ted, and no named ranges

IMPORT MULTIEXCEL FROM "Transactions_FY18.xlsx" TABLE "Trans_*$"

Import all FY18 worksheets, keep field names, and specify maximum char-
acter field length
This example is the same as the one above, but you want to keep the field names from the Excel files, and

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 274 of 934

Commands

also limit the length of character fields.

l you include KEEPTITLE to use the first row of Excel data as the field names
l you include CHARMAX 50 so that fields that originate as character data in the Excel file are limited to
50 characters in the resulting Analytics table

IMPORT MULTIEXCEL FROM "Transactions_FY18.xlsx" TABLE "Trans_*$" KEEPTITLE

CHARMAX 50

Import all worksheets from all three files

You want to import all 36 monthly worksheets from the three Excel files, and ignore any named ranges.
l you use the wildcard symbol (*) where the month occurs in each worksheet name
l you include the dollar sign ($) at the end of the worksheet name so that only worksheets are selected,
and no named ranges
l you use the wildcard symbol (*) where the year occurs in each Excel file name
l as a way of reducing the chance of naming conflicts, you use PREFIX to prepend the name of the
source Excel file to each Analytics table name

IMPORT MULTIEXCEL FROM "Transactions_FY.xlsx" TABLE "Trans_$" PREFIX

Import named ranges

Import all FY18 "Commercial_transaction" named ranges
You want to import all "Commercial_transaction" named ranges from the FY18 Excel file, and ignore work-
sheets, and other named ranges.
l you use the wildcard symbol (*) where a unique identifier occurs in the names of the different ranges
l you exclude the dollar sign ($) so that named ranges can be selected

IMPORT MULTIEXCEL FROM "Transactions_FY18.xlsx" TABLE "Commercial_transaction_*"

Import worksheets and named ranges

Import all FY18 worksheets and named ranges
You want to import all 12 monthly worksheets, and all named ranges, from the FY18 Excel file.
l with TABLE, you use only the wildcard symbol (*) so that all worksheets and named ranges in the file
are selected
l you exclude the dollar sign ($) so that named ranges can be selected

IMPORT MULTIEXCEL FROM "Transactions_FY18.xlsx" TABLE "*"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 275 of 934

Commands

Manage directories
Import all worksheets from all Excel files in the specified folder
You want to import all worksheets from all Excel files in the C:\Point of sale
audit\Data\Transaction master files folder.
l with TABLE, you use only the wildcard symbol (*) so that all worksheets in each file are selected,
and the dollar sign ($) so that only worksheets are selected, and no named ranges
l as a way of reducing the chance of naming conflicts, you use PREFIX to prepend the name of the
source Excel file to each Analytics table name

IMPORT MULTIEXCEL FROM "C:\Point of sale audit\Data\Transaction master files" TABLE "*$"
PREFIX

Import all worksheets from all Excel files in the specified folder, and save
the Analytics tables to another folder
This example is the same as the one above, but instead of saving the Analytics tables in the root project
folder, you want to save them in the C:\Point of sale audit\Data\Transaction working
data folder.

IMPORT MULTIEXCEL TO "C:\Point of sale audit\Data\Transaction working data" FROM "C:\Point

of sale audit\Data\Transaction master files" TABLE "*$" PREFIX

Remarks
Multiple IMPORT EXCEL commands
The IMPORT MULTIEXCEL command actually performs multiple individual IMPORT EXCEL commands –
one for each worksheet imported. If you double-click the IMPORT MULTIEXCEL entry in the log, the indi-
vidual IMPORT EXCEL commands are displayed in the display area.

Last table imported is automatically opened

IMPORT MULTIEXCEL does not support the OPEN keyword. However, after the command executes, the
last table imported is automatically opened.

Combining multiple worksheets after importing them

After you import multiple worksheets into individual Analytics tables you might want to combine them into a
single Analytics table. For example, you could combine the data from twelve monthly tables into a single
annual table containing all the data.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 276 of 934

Commands

For information about combining multiple Analytics tables, see "APPEND command" on page 72.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 277 of 934

Commands

IMPORT ODBC command

Creates an Analytics table by defining and importing data from an ODBC data source.
ODBC stands for Open Database Connectivity, a standard method for accessing databases.

Syntax
IMPORT ODBC SOURCE source_name TABLE table_name <QUALIFIER data_qualifier>
<OWNER user_name> <USERID user_id> <PASSWORD num> <WHERE where_clause>
<TO table_name> <WIDTH max_field_length> <MAXIMUM max_field_length> <FIELDS field
<,...n>>

Parameters
Name Description

SOURCE source_name The data source name (DSN) of the ODBC data source to connect to. The DSN must
already exist and be correctly configured.
Note
You are limited to data sources that use the Windows ODBC drivers that
are installed on your computer. The Analytics native data connectors that
can be used with the ACCESSDATA command may not be available
with IMPORT ODBC.

TABLE table_name The table name in the ODBC data source to import data from.
table_name usually refers to a database table in the source data, but it can refer to any-
thing Analytics imports as a table. For example, if you use the Microsoft Text Driver,
table_name refers to the text file you want to import data from.

QUALIFIER data_qualifier The character to use as the text qualifier to wrap and identify field values. You must spe-
cify the character as a quoted string.
optional
Use single quotation marks to specify the double quotation character: '"'.

OWNER user_name The name of the database user account that owns the table you are connecting to.
optional

USERID user_id The username to access the data source.

optional

PASSWORD num The password definition to use.

optional You do not use PASSWORD num to prompt for, or specify, an actual password. The

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 278 of 934

Commands

Name Description

password definition refers to a password previously supplied or set using the

PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2
specifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag

WHERE where_clause An SQL WHERE clause that limits the records returned based on a criteria you specify.
Must be a valid SQL statement and must be entered as a quoted string:
optional

WHERE "SALARY > 50000".

TO table_name The name of the Analytics data file to create.

optional Specify table_name as a quoted string with a .FIL file extension. For example, TO
"Invoices.FIL".
By default, the data file (.FIL) is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
o TO "C:\data\Invoices.FIL"
o TO "data\Invoices.FIL".

WIDTH max_field_length The maximum length in characters for any field in the Analytics table that originates as
character data in the source from which you are importing.
optional
You can enter any value between 1 and 254. The default value is 50. Data that exceeds
the maximum field length is truncated when imported to Analytics.

MAXIMUM max_field_ The maximum length in characters for text, note, or memo fields you are importing.
length
You can enter any value between 1 and 1100. The default value is 100. Data that
optional exceeds the maximum field length is truncated when imported to Analytics.

FIELDS field <,...n> Individual fields in the source data to import. Specify the name.
optional If you specify multiple fields, each field must be separated by a comma. If you omit
FIELDS, all fields are imported.
Enclosing the field names in quotation marks makes them case-sensitive. If you use quo-
tation marks, the case of field names must exactly match between FIELDS and the
ODBC data source. If you use quotation marks and the case of the field names does not
match, the fields are not imported.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 279 of 934

Commands

Name Description

Note
FIELDS must be positioned last among the IMPORT ODBC parameters.
If FIELDS is not positioned last, the command fails.

Examples
Importing data from SQL Server
You import data from a SQL Server database to an Analytics table named Trans_Dec11:

IMPORT ODBC SOURCE "SQLServerAudit" TABLE "Transactions" OWNER "audit" TO "C:\ACL

DATA\Trans_Dec11.FIL" WIDTH 100 MAXIMUM 200 FIELDS
"CARDNUM","CREDLIM","CUSTNO","PASTDUEAMT"

Remarks
Older method of connecting to ODBC data sources
The IMPORT ODBC command is the older method of connecting to ODBC-compliant data sources from
Analytics. The new method of connecting to ODBC data sources uses the Data Access window and the
ACCESSDATA command.
You can continue to use IMPORT ODBC in Analytics. However, this method of connecting is now available
only in scripts and from the Analytics command line. You can no longer access this connection method in
the Data Definition Wizard.

Suppress the time portion of datetime values

When using the IMPORT ODBC command to define an Analytics table you can suppress the time portion
of datetime values by prefacing the command with the SET SUPPRESSTIME ON command.
This capability allows retrofitting Analytics scripts written prior to version 10.0 of Analytics, when the time
portion of datetime values was automatically truncated. If SET SUPPRESSTIME ON is not added to these
scripts, they do not run in the datetime-enabled version of Analytics.
For more information, see the "SET SUPPRESSTIME" section in "SET command" on page 408.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 280 of 934

Commands

IMPORT PDF command

Creates an Analytics table by defining and importing an Adobe PDF file.

Syntax
IMPORT PDF TO table <PASSWORD num> import_filename FROM source_filename <SERVER pro-
file_name> skip_length <PARSER "VPDF"> <PAGES page_range> {[record_syntax] [field_syntax]
<...n>} <...n>

record_syntax ::=
RECORD record_name record_type lines_in_record transparent [test_syntax] <...n>

test_syntax ::=
TEST include_exclude match_type AT start_line,start_position,range logic text

field_syntax ::=
FIELD name type AT start_line,start_position SIZE length,lines_in_field DEC value WID bytes PIC
format AS display_name

Parameters
General parameters
Name Description

PASSWORD num Used for password-protected PDF files.

optional The password definition to use.
You do not use PASSWORD num to prompt for, or specify, an actual password. The pass-
word definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 281 of 934

Commands

Name Description

num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2 spe-
cifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag

import_filename The name of the Analytics data file to create.

SERVER profile_name The profile name for the server that contains the data that you want to import.
optional

skip_length The number of bytes to skip at the start of the file.

optional For example, if the first 32 bytes contains header information, specify a skip length value
of 32 to omit this information.
Note
For Unicode data, specify an even number of bytes only. Specifying an
odd number of bytes can cause problems with subsequent processing of
the imported data.

PARSER "VPDF" Use the VeryPDF parser to parse the PDF file during the file definition process.
optional If you omit PARSER, the default Xpdf parser is used.
If you are importing the PDF file for the first time, and you have no reason to do otherwise,
use the default Xpdf parser. If you have already encountered data alignment issues when
using Xpdf, use the VeryPDF parser to see if the parsing results are better.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 282 of 934

Commands

Name Description

PAGES page_range The pages to include if you do not want to import all of the pages in the PDF file. page_
range must be specified as a quoted string.
optional
You can specify:
o individual pages separated by commas (1,3,5)
o page ranges (2-7)
o a combination of pages and ranges (1, 3, 5-7, 11)
If you omit PAGES, all pages in the PDF file are imported.

RECORD parameter
General record definition information.
Note
Some of the record definition information is specified using numeric codes that map to
options in the Data Definition Wizard.
In scripts, specify the numeric code, not the option name.

Name Description

RECORD record_name The name of the record in the Data Definition Wizard.
Specifying record_name is required in the IMPORT PDF command, but the record_name
value does not appear in the resulting Analytics table.
In the Data Definition Wizard, Analytics provides default names based on the type of
record:
o Detail
o Headern
o Footern
You can use the default names, or specify different names.

record_type The three possible record types when defining a PDF file:

o 0 – detail
o 1 – header
o 2 – footer
Note
You can define multiple sets of header and footer records in a single exe-
cution of IMPORT PDF, but only one set of detail records.

lines_in_record The number of lines occupied by a record in the PDF file.

You can define single-line or multiline records to match the data in the PDF file.

transparent The transparency setting for a header record.

Note
Applies to header records only.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 283 of 934

Commands

Name Description

o 0 – not transparent
o 1 – transparent
Transparent header records do not split multiline detail records.
If a header record splits a multiline detail record in the source PDF file, which can happen
at a page break, specifying 1 (transparent) unifies the detail record in the resulting Ana-
lytics table.

TEST parameter
The criteria for defining a set of records in the PDF file. You can have one or more occurrences of TEST
(up to 8) for each occurrence of RECORD.
Note
Some of the criteria are specified using numeric codes that map to options in the Data
Definition Wizard (option names are shown in parentheses below).
In scripts, specify the numeric code, not the option name.

Name Description

TEST include_exclude How to treat matching data:

o 0 – (Include) data meeting the criteria is included in the set of records
o 1 – (Exclude) data meeting the criteria is excluded from the set of records

match_type The type of matching to perform:

o 0 – (Exact Match) matching records must contain the specified character, or string of
characters, in the specified start line, starting at the specified position
o 2 – (Alpha) matching records must contain one or more alpha characters, in the spe-
cified start line, at the specified start position, or in all positions of the specified range
o 3 – (Numeric) matching records must contain one or more numeric characters, in the
specified start line, at the specified start position, or in all positions of the specified
range
o 4 – (Blank) matching records must contain one or more blank spaces, in the specified
start line, at the specified start position, or in all positions of the specified range
o 5 – (Non-Blank) matching records must contain one or more non-blank characters
(includes special characters), in the specified start line, at the specified start position,
or in all positions of the specified range
o 7 – (Find in Line) matching records must contain the specified character, or string of
characters, anywhere in the specified start line
o 8 – (Find in Range) matching records must contain the specified character, or string
of characters, in the specified start line, anywhere in the specified range
o 10 – (Custom Map) matching records must contain characters that match the spe-
cified character pattern, in the specified start line, starting at the specified position

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 284 of 934

Commands

Name Description

Note
For single-line records, the start_line value is always 1.
o start_position – the starting byte position in the PDF file for the comparison against
the criteria
o range – the number of bytes from the starting byte position in the PDF file to use in
the comparison against the criteria
If you are using starting byte position only, without a range, specify 0 for range.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

logic The logical relations between criteria:

o 0 – (And) the current and the next criteria are related with a logical AND
o 1 – (Or) the current and the next criteria are related with a logical OR
o 4 – (New Group > And) the current criterion is the last in a group of logical criteria,
and the current group and the next group are related with a logical AND
o 5 – (New Group > Or) the current criterion is the last in a group of logical criteria, and
the current group and the next group are related with a logical OR
o 7 – (End) the current criterion is the last in a group of logical criteria

text Literal or wildcard characters to match against:

o For Exact Match, Find in Line, or Find in Range – specifies the character, or string of
characters, that uniquely identifies the set of records in the PDF file
o For Custom Map – specifies the character pattern that uniquely identifies the set of
records in the PDF file
The Custom Map option uses the same syntax as the "MAP( ) function" on page 630.
For other match types, text is an empty string "".

FIELD parameters
Field definition information.

Name Description

FIELD name type The individual fields to import from the source data file, including the name and data type
of the field. To exclude a field from being imported, do not specify it.
For information about type, see "Identifiers for field data types" on page 287.

AT start_line, start_position o start_line – the start line of the field in the record in the PDF file
For multiline records in a PDF file, start_line allows you to start a field at any line of the
record. start_line is always 1 if lines_in_record is 1.
o start_position – the starting byte position of the field in the PDF file

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 285 of 934

Commands

Name Description

Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, typically you should specify an odd-numbered

starting byte position. Specifying an even-numbered starting position
can cause characters to display incorrectly.

SIZE length, lines_in_field o length – the length in bytes of the field in the Analytics table layout
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, specify an even number of bytes only. Specifying

an odd number of bytes can cause characters to display incorrectly.
o lines_in_field – the number of lines occupied by a single field value in the PDF file
You can define single-line or multiline fields to match the data in the file.
Note
The number of lines specified for a field cannot exceed the number of
lines specified for the record containing the field.

DEC value The number of decimals for numeric fields.

WID bytes The display width of the field in bytes.

The specified value controls the display width of the field in Analytics views and reports.
The display width never alters data, however it can hide data if it is shorter than the field
length.

PIC format Note

Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in the
source data. For example, if the source data is 12/31/2014, you must
enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.

AS display_name The display name (alternate column title) for the field in the view in the new Analytics
table.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you want

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 286 of 934

Commands

Name Description

a line break in the column title.

AS is required when you are defining FIELD. To make the display name the same as the
field name, enter a blank display_name value using the following syntax: AS "". Make
sure there is no space between the two double quotation marks.

Examples
Importing data from a specific page of a PDF file
You import data from page 1 of the password-protected PDF file, Vendors.pdf.
One set of detail records, with three fields, is created in the resulting Analytics table, Vendor_List:

IMPORT PDF TO Vendor_List PASSWORD 1 "Vendor_List.FIL" FROM "Vendors.pdf" 2 PAGES "1"

RECORD "Detail" 0 1 0 TEST 0 3 AT 1,1,0 7 "" FIELD "Vendor_Number" C AT 1,1 SIZE 10,1 DEC 0
WID 10 PIC "" AS "" FIELD "Vendor_Name" C AT 1,33 SIZE 58,1 DEC 0 WID 58 PIC "" AS "" FIELD
"Last_Active_Date" D AT 1,277 SIZE 20,1 DEC 0 WID 20 PIC "DD/MM/YYYY" AS ""

Remarks
Note
For more information about how this command works, see the Analytics Help.

Troubleshooting PDF imports in the Unicode edition of Ana-

lytics
If you encounter issues when you import a PDF file using the Unicode edition of Analytics, the problem may
be related to length specifications:
l If foreign language characters are appearing unexpectedly, or the layout in the resulting
Analytics table is skewed, check that SIZE length is set to an even number.
Specifying an odd number of bytes for SIZE length can cause problems with processing of the impor-
ted data.
l If the Analytics table is created, but contains zero records, trying setting skip_length to 2, or some
other even number if there is header data at the beginning of the file that you want to skip.

Identifiers for field data types

The table below lists the letters that you must use when specifying type for FIELD. Each letter corresponds
to a data type.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 287 of 934

Commands

For example, if you are defining a Last Name field, which uses a character data type, you would specify
"C": FIELD "Last_Name" C.
Note
When you use the Data Definition Wizard to define a table that includes EBCDIC,
Unicode, or ASCII fields, the fields are automatically assigned the letter "C" (for the
CHARACTER type).
When you enter an IMPORT statement manually, or edit an existing IMPORT statement,
you can substitute the more specific letters "E" or "U" for EBCDIC or Unicode fields.

Letter Data type

A ACL

B BINARY

C CHARACTER

D DATETIME

E EBCDIC

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

L LOGICAL

N PRINT

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 288 of 934

Commands

Letter Data type

Y UNISYS

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 289 of 934

Commands

IMPORT PRINT command

Creates an Analytics table by defining and importing a Print Image (Report) file.

Syntax
IMPORT PRINT TO table import_filename FROM source_filename <SERVER profile_name> char-
acter_set_value <code_page_number> {[record_syntax] [field_syntax] <...n>} <...n>

record_syntax ::=
RECORD record_name record_type lines_in_record transparent [test_syntax] <...n>

test_syntax ::=
TEST include_exclude match_type AT start_line,start_position,range logic text

field_syntax ::=
FIELD name type AT start_line,start_position SIZE length,lines_in_field DEC value WID bytes PIC
format AS display_name

Parameters
General parameters
Name Description

import_filename The name of the Analytics data file to create.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 290 of 934

Commands

Name Description

o "C:\data\Invoices.FIL"
o "data\Invoices.FIL"

SERVER profile_name The profile name for the server that contains the data that you want to import.
optional

character_set_value The character set used to encode the Print Image (Report) file. The following values are
supported:
o 0 – ASCII
o 1 – EBCDIC
o 2 – Unicode
o 3 – Encoded text

code_page_number If you specified 3 (Encoded text) for character_set_value, you must also enter a code
page number.
optional

Name Description

RECORD record_name The name of the record in the Data Definition Wizard.
Specifying record_name is required in the IMPORT PRINT command, but the record_
name value does not appear in the resulting Analytics table.
In the Data Definition Wizard, Analytics provides default names based on the type of
record:
o Detail
o Headern
o Footern
You can use the default names, or specify different names.

record_type The three possible record types when defining a Print Image file:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 291 of 934

Commands

Name Description

o 0 – detail
o 1 – header
o 2 – footer
Note
You can define multiple sets of header and footer records in a single exe-
cution of IMPORT PRINT, but only one set of detail records.

lines_in_record The number of lines occupied by a record in the Print Image file.
You can define single-line or multiline records to match the data in the file.

transparent The transparency setting for a header record.

Note
Applies to header records only.
o 0 – not transparent
o 1 – transparent
Transparent header records do not split multiline detail records.
If a header record splits a multiline detail record in the source Print Image file, which can
happen at a page break, specifying 1 (transparent) unifies the detail record in the res-
ulting Analytics table.

TEST parameter
The criteria for defining a set of records in the Print Image file. You can have one or more occurrences of
TEST (up to 8) for each occurrence of RECORD.
Note
Some of the criteria are specified using numeric codes that map to options in the Data
Definition Wizard (option names are shown in parentheses below).
In scripts, specify the numeric code, not the option name.

Name Description

TEST include_exclude How to treat matching data:

o 0 – (Include) data meeting the criteria is included in the set of records
o 1 – (Exclude) data meeting the criteria is excluded from the set of records

match_type The type of matching to perform:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 292 of 934

Commands

Name Description

o 4 – (Blank) matching records must contain one or more blank spaces, in the specified
start line, at the specified start position, or in all positions of the specified range
o 5 – (Non-Blank) matching records must contain one or more non-blank characters
(includes special characters), in the specified start line, at the specified start position,
or in all positions of the specified range
o 7 – (Find in Line) matching records must contain the specified character, or string of
characters, anywhere in the specified start line
o 8 – (Find in Range) matching records must contain the specified character, or string
of characters, in the specified start line, anywhere in the specified range
o 10 – (Custom Map) matching records must contain characters that match the spe-
cified character pattern, in the specified start line, starting at the specified position

AT start_line, start_pos- o start_line – the line of a record that the criteria apply to
ition, range
For example, if you create a custom map to match zip codes, and the zip codes
appear on the third line of a three-line address record, you must specify 3 in start_
line.
Note
For single-line records, the start_line value is always 1.
o start_position – the starting byte position in the Print Image file for the comparison
against the criteria
o range – the number of bytes from the starting byte position in the Print Image file to
use in the comparison against the criteria
If you are using starting byte position only, without a range, specify 0 for range.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) 1 byte = 1 character

data

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, range must be an even number of bytes. For

example, 50,59 (10 bytes). Specifying an odd number of bytes can
prevent correct matching against criteria.

logic The logical relations between criteria:

text Literal or wildcard characters to match against:

o For Exact Match, Find in Line, or Find in Range – specifies the character, or string of
characters, that uniquely identifies the set of records in the Print Image file
o For Custom Map – specifies the character pattern that uniquely identifies the set of

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 293 of 934

Commands

Name Description

records in the Print Image file

The Custom Map option uses the same syntax as the "MAP( ) function" on page 630.
For other match types, text is an empty string "".

FIELD parameters
Field definition information.

Name Description

AT start_line, start_pos- o start_line – the start line of the field in the record in the Print Image file
ition
For multiline records in a Print Image file, start_line allows you to start a field at any
line of the record. start_line is always 1 if lines_in_record is 1.
o start_position – the starting byte position of the field in the Print Image file
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) 1 byte = 1 character

data

Unicode Analytics, Unicode data 2 bytes = 1 character

SIZE length, lines_in_field o length – the length in bytes of the field in the Analytics table layout
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) 1 byte = 1 character

data

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, specify an even number of bytes only. Specifying

an odd number of bytes can cause characters to display incorrectly.
o lines_in_field – the number of lines occupied by a single field value in the Print
Image file
You can define single-line or multiline fields to match the data in the file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 294 of 934

Commands

Name Description

Note
The number of lines specified for a field cannot exceed the number of
lines specified for the record containing the field.

DEC value The number of decimals for numeric fields.

WID bytes The display width of the field in bytes.

The specified value controls the display width of the field in Analytics views and reports.
The display width never alters data, however it can hide data if it is shorter than the field
length.

PIC format Note

Examples
Importing data from a Print Image (Report) file
You import data from the Print Image (Report) file, Report.txt.
One header record, and one set of detail records, with five fields, is created in the resulting Analytics table,
Inventory_report:

IMPORT PRINT TO Inventory_report "Inventory_report.FIL" FROM "Report.txt" 0 RECORD

"Header1" 1 1 0 TEST 0 0 AT 1,17,0 7 ":" FIELD "Field_1" C AT 1,19 SIZE 2,1 DEC 0 WID 2 PIC "" AS
"Prod Class" FIELD "Field_2" C AT 1,24 SIZE 31,1 DEC 0 WID 31 PIC "" AS "Prod Description"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 295 of 934

Commands

RECORD "Detail" 0 1 0 TEST 0 0 AT 1,59,59 7 "." FIELD "Field_3" X AT 1,6 SIZE 9,1 DEC 0 WID 9
PIC "" AS "Item ID" FIELD "Field_4" C AT 1,16 SIZE 24,1 DEC 0 WID 24 PIC "" AS "Item Desc."
FIELD "Field_5" N AT 1,40 SIZE 10,1 DEC 0 WID 10 PIC "" AS "On Hand" FIELD "Field_6" N AT
1,50 SIZE 12,1 DEC 2 WID 12 PIC "" AS "Cost" FIELD "Field_7" N AT 1,62 SIZE 12,1 DEC 2 WID 12
PIC "" AS "Total"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Identifiers for field data types

Letter Data type

A ACL

B BINARY

C CHARACTER

D DATETIME

E EBCDIC

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 296 of 934

Commands

Letter Data type

L LOGICAL

N PRINT

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Y UNISYS

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 297 of 934

Commands

IMPORT SAP command

Creates an Analytics table by importing data from an SAP system using Direct Link.

Syntax
IMPORT SAP PASSWORD num TO table_name SAP SOURCE "SAP AGENT" import_details

Parameters
Name Description

PASSWORD num The password definition to use.

TO table_name The name of the Analytics table to import the data into.
Note
Table names are limited to 64 alphanumeric characters. The name can
include the underscore character ( _ ), but no other special characters, or
any spaces. The name cannot start with a number.

SAP SOURCE Required for importing SAP data. "SAP AGENT" is the only available option.
"SAP AGENT"

import_details The details of the query. Must be enclosed by the <q></q> tags, and uses the tags listed
in "Direct Link query tags" on page 301 to define the query.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 298 of 934

Commands

Name Description

The physical size of this value can be up to 16 KB.

Examples
Performing a multi-table query
This example performs a multi-table query using the IMPORT SAP command.
Correct order and nesting of the tags is necessary to create a valid query string. The tags in the example are
ordered and nested correctly. Use this example to determine the required order and nesting of
IMPORT SAP query tags.
Note
To assist readability, this example is formatted using multiple lines. In your script, the com-
mand and the query string must be entered without any line breaks.
Tip
The syntax of an IMPORT SAP query string is typically complex. The best way to add
IMPORT SAP commands with query strings to your scripts is to copy an existing IMPORT
SAP command from the Log tab in Analytics, then edit the query tags as necessary.

IMPORT SAP PASSWORD 1 TO Purchasing_doc SAP SOURCE "SAP AGENT"

<q version="6.0">
  <s>0</s>
  <d>IDES</d>
  <u>mzunini</u>
  <c>800</c>
  <lg>en</lg>
  <cf>C:\ACL Data\Purchasing_doc.fil</cf>
  <sf>E:\Data\DL_JSMITH111107.DAT</sf>
  <jcount>11110701</jcount>
  <jname>DL_JSMITH111107.DAT</jname>
  <dl>75</dl>
  <m>2</m>
  <dt>20140321</dt>
  <tm>033000</tm>
  <r>500</r>
  <ar>0</ar>
  <e>500</e>
  <ts>
    <t>
      <n>EKKO</n>

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 299 of 934

Commands

      <a>T00001</a>
      <td>Purchasing Document Header</td>
      <fs>
        <f>EBELN</f>
        <f>BUKRS</f>
        <f>BSTYP</f>
        <f>BSART</f>
        <f>STATU</f>
        <f>WKURS</f>
      </fs>
      <wc>
        <w>
           <f>BUKRS</f>
           <o>0</o>
           <l>1000</l>
           <h></h>
        </w>
      </wc>
    </t>
    <t>
      <n>EKPO</n>
      <a>T00002</a>
      <td>Purchasing Document Item</td>
      <fs>
        <f>EBELP</f>
        <f>WERKS</f>
        <f>MENGE</f>
        <f>BRTWR</f>
      </fs>
      <wc></wc>
    </t>
  </ts>
  <js>
    <jc>
      <pt>
        <pa>T00001</pa>
        <pf>EBELN</pf>
      </pt>
      <ct>
        <ca>T00002</ca>
        <cf>EBELN</cf>
      </ct>
    </jc>
  </js>

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 300 of 934

Commands

</q>

Remarks
The IMPORT SAP command is only supported if Direct Link is installed and configured.
The table in "Direct Link query tags" below lists the tags that can be included in the import_details para-
meter. The Required column uses the following values to indicate when tags must be present:
l Y – Required
l N – Optional
l M – Required for multi-table queries only
l B – Required, but no value should be passed
l W – Optional when filters are used
l S – Required when scheduled mode is specified

Direct Link query tags

Name Tag Required Description

Table Alias <a> M The alias that uniquely identifies the table within the query. This allows
the same table to be used more than once.
The maximum length is 6 characters.

All Rows <ar> Y Indicates that all matching rows should be returned as part of the
query's result set.
Valid values are:
1 – Overrides the number of records specified in the <r> tag (Maximum
Rows)
0 – Returns the number of records specified in the <r> tag (Maximum
Rows)
This tag always appears after the <r></r> tag.

Client <c> N The client within the SAP system.

Child Table Alias <ca> M The alias of the child table.

Child Table Field <cf> M The field in the child table that the join condition is based on.

Client Filename <cf> Y Identifies the target file on the client system where the results of the
query will be stored.

Child Table <ct> M The child table in the join condition.

Destination <d> N Identifies a destination in the SAP RFC library file (sapnwrfc.ini) that
is used to locate an SAP system.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 301 of 934

Commands

Name Tag Required Description

Data Length <dl> B The number of characters in each row, including carriage return and
line feed characters indicating the end of the record (CR+LF, or the
hexadecimal characters 0D+0A).

Date <dt> S Required when using scheduled mode. Specifies the time to run the
SAP job.
Must be formatted as YYYYMMDD. For example, December 31, 2014
must be specified as 20141231.

Expected Rows <e> B The expected number of rows the query will return.

Field Name <f> Y The native field name.

Filter Field <f> W The native field name that the filter applies to.

Fields <fs> Y The list of fields in the table that will be returned as part of the query res-
ults.

High Value <h> W Contains the high value when using the Between operator. Ignored
when using any other operator.

Join Condition <jc> M The join condition.

Job Count <jcount> B Used internally by SAP to identify a Background mode query.

Job Name <jname> B Used internally by SAP to identify a Background mode query.

Join Relationships <js> Y The list of join conditions that link tables within the query.

Join Switch <jw> N Numeric equivalent of the join switch enumerated type.
Valid values are:
0 – Inner Join
1 – Left Outer Join

Low Value <l> W Contains either the lowest value when using the Between operator or
the value when using any other operator.

Language <lg> Y Language identifier used to determine the locale of fields in the SAP
database.

Mode <m> Y Numeric equivalent of the submission mode enumerated type.

Valid values are:
0 – Extract Now
1 – Background
2 – Scheduled

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 302 of 934

Commands

Name Tag Required Description

Table Name <n> Y The native table name.

Operator <o> W Numeric equivalent of the operator enumerated type.

Valid values are:
0 – Equal to (=)
1 – Not equal to (<>)
2 – Less than (<)
3 – Less than or equal to (<=)
4 – Greater than (>)
5 – Greater than or equal to (>=)
6 – Between
7 – Contains

Parent Table Alias <pa> M The alias of the parent table.

Parent Table Field <pf> M The field in the parent table the join condition is based on.

Parent Table <pt> M The parent table in the join condition.

Query <q> Y Encloses a query.

Maximum Rows <r> Y The maximum number of rows the query should return.

Selected <s> Y If the <s> tag appears below the <f> tag, it indicates whether the field
will be returned as part of the query's result set.

System <s> Y If the <s> tag appears below the <q> tag, it identifies the type of system
this query is used against (currently only SAP is supported).

Server Filename <sf> B Identifies the file on the server that holds the results of a Background
mode query.

Server Group <sg> N The name of the server group. Maximum 20 characters.
Name

Server Name <sn> N The name of the server. Maximum 20 characters.

Table <t> Y The table.

Table Description <td> Y The table description from the SAP data dictionary. It should always
appear below the <a> tag.

Time <tm> S Required when using scheduled mode. Specifies the time to run the
SAP job.
Must be formatted as hhmmss. For example, 2:30 pm must be specified

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 303 of 934

Commands

Name Tag Required Description

as 143000.

Tables <ts> Y The list of tables from which the query will extract data.

Table Type <tt> Y The type of SAP table.

Valid values are:
0 – clustered
1 – transparent
2 – pooled
3 – view

Username <u> N The user's logon name.

Filter <w> W The filter applied to the table's data.

Filters <wc> W The list of filters that will be applied to the data contained within the
table.

Filter Switch <ws> N Numeric equivalent of the filter switch enumerated type.
Valid values are:
0 – (Or) And (Or)
1 – (And) Or (And)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 304 of 934

Commands

IMPORT XBRL command

Creates an Analytics table by defining and importing an XBRL file.

Syntax
IMPORT XBRL TO table import_filename FROM source_filename CONTEXT context_name <...n>
[field_syntax] <...n> <IGNORE field_num> <...n>

field_syntax ::=
FIELD name type AT start_position DEC value WID bytes PIC format AS display_name

Parameters
Name Description

import_filename The name of the Analytics data file to create.

CONTEXT context_name The XBRL context to define the table from. If you specify more than one context, all con-
texts must be of the same type (instant, period, or forever).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 305 of 934

Commands

Name Description

FIELD name type The individual fields to import from the source data file, including the name and data type
of the field. To exclude a field from being imported, do not specify it.
For information about type, see "Identifiers for field data types" on the facing page.

AT start_position The starting byte position of the field in the Analytics data file.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, typically you should specify an odd-numbered start-

ing byte position. Specifying an even-numbered starting position can
cause characters to display incorrectly.

DEC value The number of decimals for numeric fields.

WID bytes The length in bytes of the field in the Analytics table layout.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, specify an even number of bytes only. Specifying an

odd number of bytes can cause characters to display incorrectly.

PIC format Note

Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in the
source data. For example, if the source data is 12/31/2014, you must
enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.

AS display_name The display name (alternate column title) for the field in the view in the new Analytics
table.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you want
a line break in the column title.
AS is required when you are defining FIELD. To make the display name the same as the
field name, enter a blank display_name value using the following syntax: AS "". Make
sure there is no space between the two double quotation marks.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 306 of 934

Commands

Name Description

IGNORE field_num Excludes a field from the table layout.

optional field_num specifies the position of the field in the source data. For example, IGNORE 5
excludes the fifth field in the source data from the Analytics table layout.

Examples
Importing an XBRL file to an Analytics table
You import data from the Current_AsOf context in an XBRL file to an Analytics table called Financials :

IMPORT XBRL TO Financials "Financials.fil" FROM "FinancialStatemenXBRL.xml" CONTEXT "Cur-

rent_AsOf" FIELD "Item" C AT 1 DEC 0 WID 57 PIC "" AS "" FIELD "Value" X AT 58 DEC 0 WID 7 PIC
"" AS "" IGNORE 1 IGNORE 3

Remarks
Note
For more information about how this command works, see the Analytics Help.

Identifiers for field data types

The table below lists the letters that you must use when specifying type for FIELD. Each letter corresponds
to a data type.
For example, if you are defining a Last Name field, which uses a character data type, you would specify "C":
FIELD "Last_Name" C.
Note
When you use the Data Definition Wizard to define a table that includes EBCDIC,
Unicode, or ASCII fields, the fields are automatically assigned the letter "C" (for the
CHARACTER type).
When you enter an IMPORT statement manually, or edit an existing IMPORT statement,
you can substitute the more specific letters "E" or "U" for EBCDIC or Unicode fields.

Letter Data type

A ACL

B BINARY

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 307 of 934

Commands

Letter Data type

C CHARACTER

D DATETIME

E EBCDIC

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

L LOGICAL

N PRINT

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Y UNISYS

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 308 of 934

Commands

IMPORT XML command

Creates an Analytics table by defining and importing an XML file.

Syntax
IMPORT XML TO table import_filename FROM source_filename [field_syntax] <...n>

field_syntax ::=
FIELD name type AT start_position DEC value WID bytes PIC format AS display_name RULE xpath_
expression

Parameters
Name Description

import_filename The name of the Analytics data file to create.

FIELD name type The individual fields to import from the source data file, including the name and data type
of the field. To exclude a field from being imported, do not specify it.
For information about type, see "Identifiers for field data types" on page 311.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 309 of 934

Commands

Name Description

AT start_position The starting byte position of the field in the Analytics data file.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, typically you should specify an odd-numbered start-

ing byte position. Specifying an even-numbered starting position can
cause characters to display incorrectly.

DEC value The number of decimals for numeric fields.

WID bytes The length in bytes of the field in the Analytics table layout.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics 2 bytes = 1 character

In Unicode Analytics, specify an even number of bytes only. Specifying an

odd number of bytes can cause characters to display incorrectly.

PIC format Note

Applies to numeric or datetime fields only.
o numeric fields – the display format of numeric values in Analytics views and reports
o datetime fields – the physical format of datetime values in the source data (order of
date and time characters, separators, and so on)
Note
For datetime fields, format must exactly match the physical format in the
source data. For example, if the source data is 12/31/2014, you must
enter the format as "MM/DD/YYYY".
format must be enclosed in quotation marks.

AS display_name The display name (alternate column title) for the field in the view in the new Analytics
table.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you want
a line break in the column title.
AS is required when you are defining FIELD. To make the display name the same as the
field name, enter a blank display_name value using the following syntax: AS "". Make
sure there is no space between the two double quotation marks.

RULE xpath_expression The XPath expression used to select the field contents from the XML file.
XPath is a standard way of accessing data from XML files. For example, acct/title/text()
retrieves the text within the <title> tag in the XML file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 310 of 934

Commands

Examples
Importing data from an XML file to an Analytics table
You import data from an XML file to an Analytics table named Employees :

IMPORT XML TO Employees "Employees.fil" FROM "emp.XML" FIELD "Empno" C AT 1 DEC 0 WID 6
PIC "" AS "" RULE "/RECORDS/RECORD/Empno/text()" FIELD "First" C AT 7 DEC 0 WID 13 PIC ""
AS "" RULE "/RECORDS/RECORD/First/text()" FIELD "Last" C AT 20 DEC 0 WID 20 PIC "" AS ""
RULE "/RECORDS/RECORD/Last/text()" FIELD "HireDate" D AT 40 DEC 0 WID 10 PIC "YYYY-MM-
DD" AS "" RULE "/RECORDS/RECORD/HireDate/text()" FIELD "Salary" N AT 50 DEC 2 WID 8 PIC
"" AS "" RULE "/RECORDS/RECORD/Salary/text()"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Identifiers for field data types

The table below lists the letters that you must use when specifying type for FIELD. Each letter corresponds
to a data type.
For example, if you are defining a Last Name field, which uses a character data type, you would specify "C":
FIELD "Last_Name" C.
Note
When you use the Data Definition Wizard to define a table that includes EBCDIC,
Unicode, or ASCII fields, the fields are automatically assigned the letter "C" (for the
CHARACTER type).
When you enter an IMPORT statement manually, or edit an existing IMPORT statement,
you can substitute the more specific letters "E" or "U" for EBCDIC or Unicode fields.

Letter Data type

A ACL

B BINARY

C CHARACTER

D DATETIME

E EBCDIC

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 311 of 934

Commands

Letter Data type

F FLOAT

G ACCPAC

I IBMFLOAT

K UNSIGNED

L LOGICAL

N PRINT

P PACKED

Q BASIC

R MICRO

S CUSTOM

T PCASCII

U UNICODE

V VAXFLOAT

X NUMERIC

Y UNISYS

Z ZONED

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 312 of 934

Commands

INDEX command
Creates an index for an Analytics table that allows access to the records in a sequential order rather than a
physical order.

Syntax
INDEX <ON> {key_field <D> <...n>|ALL} TO file_name <IF test> <WHILE test> <FIRST range|NEXT
range> <OPEN> <ISOLOCALE locale_code>

Parameters
Name Description

ON key_field D <...n> | ALL The key field or fields, or the expression, to use for indexing.
You can index by any type of field, including computed fields and ad hoc expressions,
regardless of data type.
o key_field – use the specified field or fields
If you index by more than one field, you create nested indexing in the table. The order
of nesting follows the order in which you specify the fields.
Include D to index the key field in descending order. The default index order is ascend-
ing.
o ALL – use all fields in the table
If you index by all the fields in a table you create nested indexing. The order of nesting
follows the order in which the fields appear in the table layout.
An ascending index order is the only option for ALL.

TO file_name The name of the index and the associated index file. The index file is created with an .INX
extension.
Note
In the Analytics user interface, index names are limited to 64 alpha-
numeric characters. The name can include the underscore character ( _ ),
but no other special characters, or any spaces. The name cannot start
with a number.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 313 of 934

Commands

Name Description

FIRST range | NEXT range The number of records to process:

OPEN Open the table and apply the index to the table.
optional

ISOLOCALE locale_code Note

Examples
Note
For more information about how this command works, see the Analytics Help.

Create an index and open the table

In the Vendor table, you create an index on the Vendor City field and open the table:

OPEN Vendor
INDEX ON Vendor_City to "CityIndex" OPEN

Create an index and apply it to a table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 314 of 934

Commands

In the Vendor table, you create an index on the Vendor City field. Later, you apply the index to the table:

OPEN Vendor
INDEX ON Vendor_City to "CityIndex"
.
.
.
SET INDEX TO "CityIndex"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 315 of 934

Commands

JOIN command
Combines fields from two Analytics tables into a new, single Analytics table.
Note
To use fuzzy matching to join tables, see "FUZZYJOIN command" on page 211.

Syntax
JOIN {PKEY primary_key_fields|PKEY ALL} {FIELDS primary_fields|FIELDS ALL} {SKEY sec-
ondary_key_fields|SKEY ALL} <WITH secondary_fields|WITH ALL> {no_
keyword|MANY|UNMATCHED|PRIMARY|SECONDARY|PRIMARY SECONDARY} <IF test> TO
table_name <LOCAL> <OPEN> <WHILE test> <FIRST range|NEXT range> <APPEND>
<PRESORT> <SECSORT> <ISOLOCALE locale_code>

Parameters
Name Description

PKEY primary_key_fields | The key field or fields, or expression, in the primary table.
PKEY ALL o primary_key_fields – use the specified field or fields
o ALL – use all fields in the table

FIELDS primary_fields | The fields or expressions from the primary table to include in the joined output table.
FIELDS ALL o primary_fields – include the specified field or fields
o ALL – include all fields from the table
Note
You must explicitly specify the primary key field or fields if you want to
include them in the joined table. Specifying ALL also includes them.

SKEY secondary_key_ The key field or fields, or expression, in the secondary table.
fields | SKEY ALL o secondary_key_fields – use the specified field or fields
o ALL – use all fields in the table

WITH secondary_fields | The fields or expressions from the secondary table to include in the joined output table.
WITH ALL o secondary_fields – include the specified field or fields
optional o ALL – include all fields from the table
Note
You must explicitly specify the secondary key field or fields if you want to
include them in the joined table. Specifying ALL also includes them.
You cannot specify WITH if you are using the UNMATCHED join type.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 316 of 934

Commands

Name Description

no_keyword | MANY | The type of join to perform.

UNMATCHED | PRIMARY
| SECONDARY | no_keyword (omit all join-type keywords)
PRIMARY SECONDARY

Corresponding option in the Join dialog

The joined output table contains: box

o all matched primary records and the first Matched primary and secondary
matched secondary record
(1st secondary match)

MANY

Corresponding option in the Join dialog

The joined output table contains: box

o all matched primary records and all Matched primary and secondary
matched secondary records
o one record for each match between the (all secondary matches)
primary and secondary tables

UNMATCHED

Corresponding option in the Join dialog

The joined output table contains: box

o unmatched primary records Unmatched primary

PRIMARY

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 317 of 934

Commands

Name Description

Corresponding option in the Join dialog

The joined output table contains: box

o all primary records (matched and All primary and matched secondary
unmatched) and the first matched sec-
ondary record

Note
The keyword BOTH is the same as specifying PRIMARY.

SECONDARY

Corresponding option in the Join dialog

The joined output table contains: box

o all secondary records (matched and All secondary and matched primary
unmatched) and all matched primary
records
Only the first instance of any duplicate sec-
ondary matches is joined to a primary
record.

PRIMARY SECONDARY

Corresponding option in the Join dialog

The joined output table contains: box

o all primary and all secondary records, All primary and secondary
matched and unmatched
Only the first instance of any duplicate sec-
ondary matches is joined to a primary
record.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 318 of 934

Commands

Name Description

Note
For most join types, an IF condition applies only to the primary table.
The one exception is a many-to-many join, in which the IF condition can
also reference the secondary table.

TO table_name The location to send the results of the command to:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

FIRST range | NEXT range The number of records to process:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 319 of 934

Commands

Name Description

PRESORT Sorts the primary table on the primary key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.

Indexing instead of sorting

The primary table can be indexed instead of sorted. With large tables, indexing instead
of sorting may reduce the time required to join the tables.
If you are joining two tables using an indexed common key field, omit PRESORT and
SECSORT.

SECSORT Sorts the secondary table on the secondary key field before executing the command.
optional Note
You cannot use SECSORT inside the GROUP command.

Indexing instead of sorting

The secondary table can be indexed instead of sorted. With large tables, indexing
instead of sorting may reduce the time required to join the tables.
If you are joining two tables using an indexed common key field, omit PRESORT and
SECSORT.

ISOLOCALE locale_code Note

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 320 of 934

Commands

Examples
Join two tables as a way of discovering employees who may also be vendors
The example below joins the Empmast and Vendor tables using address as the common key field (the
Address and Vendor_Street fields).
The JOIN command creates a new table with matched primary and secondary records, which results in a list
of any employees and vendors with the same address.

OPEN Empmast PRIMARY

OPEN Vendor SECONDARY
JOIN PKEY Address FIELDS Empno First Last Address SKEY Vendor_Street WITH Vendor_No
Vendor_Name Vendor_Street TO "Employee_Vendor_Match" OPEN PRESORT SECSORT

This version of the JOIN command includes all fields from the primary and secondary tables in the joined out-
put table.

OPEN Empmast PRIMARY

OPEN Vendor SECONDARY
JOIN PKEY Address FIELDS ALL SKEY Vendor_Street WITH ALL TO "Employee_Vendor_Match"
OPEN PRESORT SECSORT

Join two tables as a way of discovering accounts receivable records with no

matching customer
The example below joins the Ar and Customer tables using Customer Number (CustNo) as the common key
field.
The JOIN command uses the UNMATCHED join type to create a new table with unmatched primary
records, which results in a list of Ar records that are not associated with any Customer record.

OPEN Ar PRIMARY
OPEN Customer SECONDARY
JOIN PKEY CustNo FIELDS CustNo Due Amount SKEY CustNo UNMATCHED TO "Cus-
tomerNotFound.fil" OPEN PRESORT SECSORT

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 321 of 934

Commands

LIST command
Outputs the data in one or more fields in an Analytics table to a display formatted in columns.

Syntax
LIST {FIELDS field_name <AS display_name> <...n>|FIELDS ALL} <LINE number field_list> <TO
{SCREEN|filename|PRINT}> <UNFORMATTED> <IF test> <WHILE test> <FIRST range|NEXT
range> <HEADER header_text> <FOOTER footer_text> <SKIP lines> <EOF> <APPEND>

Parameters
Name Description

FIELDS field_name <...n> | The fields to include in the output:

FIELDS ALL o FIELDS field_name – use the specified fields
o FIELDS ALL – use all fields in the table

AS display_name Only used when listing data using FIELDS field_name.

optional The display name (alternate column title) for the field in the output. If you want the dis-
play name to be the same as the field name, or an existing display name in the source
table, do not use AS.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title.

LINE number field_list More than one line is used in the output for each record:
optional o number – the line number, must be between 2 and 60 inclusive
o field_list – the fields to include on that line

TO SCREEN | The location to send the results of the command to:

filename | PRINT o SCREEN – displays the results in the Analytics display area
optional o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o PRINT – sends the results to the default printer

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 322 of 934

Commands

Name Description

UNFORMATTED The output is displayed as unformatted text. Output is identical to that created by the
EXPORT ASCII command. Unformatted data can be output to a file for further pro-
optional
cessing by other software programs.

FIRST range | NEXT range The number of records to process:

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.

optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

SKIP lines Inserts the specified number of blank lines between each record in the list. For example,
LIST ALL SKIP 1 produces a double spaced list (one blank line between each record).
optional

APPEND Appends the command output to the end of an existing file instead of overwriting it.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 323 of 934

Commands

Examples
Listing exceptions and saving to a text file
You use LIST to create a report listing exceptions identified in an inventory table. The report is saved as a
text file:

LIST Product_number Description Quantity Unit_cost Value IF Quantity < 0 OR Unit_cost < 0
HEADER "Negative Values" TO "Exceptions.txt"

Remarks
When to use LIST
Use LIST to print data, display data on screen, to export it to a text file.

Formatting and totals

Unless you specify UNFORMATTED, the following information is included automatically:
l page numbers
l date
l time
l user identification
l column headings
Numeric columns are also automatically totaled.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 324 of 934

Commands

LOCATE command
Searches for the first record that matches the specified value or condition, or moves to the specified record
number.

Syntax
LOCATE {IF test <WHILE test> <FIRST range|NEXT range>|RECORD num}

Parameters
Name Description

IF test The value or condition to search for. You must enclose character literal values in quo-
tation marks, and datetime values in backquotes.

FIRST range | NEXT range The number of records to process:

RECORD num The record number to locate.

Examples
Locate the first record that matches a specified value
The following examples illustrate using LOCATE to find the first occurrence of a specific value in a table:

LOCATE IF Vendor_Name = "United Equipment"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 325 of 934

Commands

LOCATE IF Vendor_Name = "Uni"

LOCATE IF Invoice_Amount > 1000

LOCATE IF Invoice_Date = `20141231`

Locate the first record that matches a specified condition or expression

The following examples illustrate using LOCATE to find the first occurrence of a specific condition or
expression in a table:

LOCATE IF Vendor_Name = "United Equipment" AND Invoice_Amount > 1000 AND Invoice_Date >
`20140930`

LOCATE IF Vendor_City = v_city

Locate a record by record number

The following example illustrates using LOCATE to move to a particular record in a table:

LOCATE RECORD 50

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
Use the LOCATE command to move directly to the first record in a table matching the specified value or
condition.
If the specified value or condition is found, the first matching record in the table is selected. If the specified
value or condition is not found, the table is positioned at the first record.
You can also use LOCATE to move directly to a specific record number

LOCATE compared to FIND and SEEK

Unlike the FIND and SEEK commands, the LOCATE command is not restricted to searching an indexed
table, or a single character field. Using LOCATE, you can search for any type of literal, or for an expression

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 326 of 934

Commands

that uses any data type, or mix of data types.

When used to search an unindexed table, the LOCATE command may be significantly slower than FIND or
SEEK because it must process each record in the table sequentially. The required processing time depends
on the size of the table, the location of a matching record, and whether you reduce the scope of the search
by using WHILE, FIRST, or NEXT.

Partial matching supported

Partial matching is supported for character searches. The search value can be contained by a longer value
in the field or fields being searched. However, search values must appear at the start of fields to constitute a
match.

Enabling or disabling partial matching

You can enable or disable partial matching using either the SET command, or a setting in the Options dia-
log box:

Enable partial matching Disable partial matching

Specify: SET EXACT OFF Specify: SET EXACT ON

or or
Deselect: Exact Character Comparisons in the Options Select: Exact Character Comparisons in the Options dia-
dialog box (Tools > Options > Table) log box (Tools > Options > Table)
Result: The search value can be contained by a longer Result: The search value must exactly match a value in a
value in the field or fields being searched. The search field to constitute a match.
value must appear at the start of a field to constitute a
match.

For more information about SET EXACT, see "SET command" on page 408.
For more information about the Exact Character Comparisons option, see Table tab (Options dialog box).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 327 of 934

Commands

LOOP command
Executes a series of ACLScript commands repeatedly on a record while a specified condition evaluates to
true.
Note
The LOOP command must be enclosed inside the GROUP command.

Syntax
LOOP WHILE test
command
<...n>
END

Parameters
Name Description

WHILE test The test that must evaluate to true for the commands inside the LOOP command to be
executed. If the test evaluates to true the commands are executed repeatedly until the
test evaluates to false.

command <...n> One or more commands to execute.

You can enter multiple commands inside the LOOP command. Each command must
start on a new line.

END The end of the LOOP command.

Examples
Splitting a comma-delimited field
You have a table containing invoice data and you need to isolate specific information for invoice amounts
per department. One invoice may be related to more than one department, and department codes are
stored in comma-delimited format in the table.
To extract the invoice amounts per department, you:
1. Use a GROUP command to process the table record by record.
2. Calculate the number of departments (n) associated with each record.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 328 of 934

Commands

3. Use the LOOP command to iterate n times over the record to extract data for each department asso-
ciated with the record.

Remarks
Tip
For a detailed tutorial covering the LOOP and GROUP commands, see "Grouping and loop-
ing" on page 33.

When to use LOOP

Loops are frequently used when a record contains repeated segments of data that you want to process.

How it works
Each LOOP command must specify a WHILE condition to test, and be closed with an END statement. The
commands between LOOP and END are executed repeatedly for the current record as long as the specified
test is true.
If the test is initially false, the commands are not executed.

Avoiding infinite loops

To avoid creating an infinite loop, make sure that the test you specify eventually returns false. You can also
use the SET LOOP command to prevent infinite looping.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 329 of 934

Commands

MERGE command
Combines records from two sorted Analytics tables with an identical structure into a new Analytics table
that uses the same sort order as the original tables.

Syntax
MERGE {ON key_fields|PKEY primary_key_fields SKEY secondary_key_fields} <IF test> TO table_
name <LOCAL> <OPEN> <WHILE test> <FIRST range|NEXT range> <APPEND> <PRESORT>
<ISOLOCALE locale_code>

Parameters
Name Description

ON key_fields | PKEY Note

primary_key_fields SKEY
Only character fields, or character computed fields, can be used as key
secondary_key_fields
fields in MERGE.
o ON key_fields – the key field or fields to merge on if the corresponding key fields in
the primary and secondary tables have the same name
If the corresponding fields have different names, or if they are expressions rather
than actual physical fields, you must use PKEY and SKEY.
o PKEY primary_key_fields – the key field or fields, or expression, in the primary table
o SKEY primary_key_fields – the key field or fields, or expression, in the secondary
table

Sorting requirement
The key fields in the primary and secondary tables must both be sorted in ascending
order. If one or both key fields are unsorted, or sorted in descending order, the MERGE
command fails.
You can use PRESORT to sort the primary key field. If the secondary key field is unsor-
ted, you must first sort it in a separate sort operation before performing the merge.

Indexing instead of sorting

The primary and secondary tables can be indexed instead of sorted. With large tables,
indexing instead of sorting may reduce the time required to merge the tables.

IF test A conditional expression that must be true in order to process each record. The com-
mand is executed on only those records that satisfy the condition.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 330 of 934

Commands

Name Description

Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).

TO table_name The location to send the results of the command to:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

FIRST range | NEXT range The number of records to process:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 331 of 934

Commands

Name Description

PRESORT Sorts the primary table on the primary key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.
Omit PRESORT:
o If the primary key field is already sorted
o If you are merging two tables using an indexed common key field

ISOLOCALE locale_code Note

Examples
Merge tables with identical key field names
The following example merges two tables with identical key field names:

OPEN Employees_Location_1 PRIMARY

OPEN Employees_Location_2 SECONDARY
MERGE ON Last_Name TO "AllEmployees" PRESORT

Merge tables with different key field names

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 332 of 934

Commands

The following example merges two tables with different key field names:

OPEN Employees_Location_1 PRIMARY

OPEN Employees_Location_2 SECONDARY
MERGE PKEY Last_Name SKEY Surname TO "AllEmployees" PRESORT

Remarks
Note
For more information about how this command works, see the Analytics Help.

Alternatives to merging
Merging can be tricky to perform correctly. You can get the same result by appending, or by extracting and
appending, and then sorting.
For more information, see "APPEND command" on page 72, and "EXTRACT command" on page 197.
If the two source tables are already sorted, merging is more efficient and can execute more quickly.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 333 of 934

Commands

NOTES command
Creates, modifies, or removes a note associated with an individual record in an Analytics table.

Syntax
NOTES <IF test> <TEXT note_text> <APPEND> <CLEAR>

Parameters
Name Description

IF test A conditional expression that must be true in order to process each record. The com-
mand is executed on only those records that satisfy the condition.
optional
Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).
o If you do not specify an IF test, the note text is added to each record in the table
o If you specify an IF test and CLEAR, the notes for those records that meet the con-
dition are deleted

TEXT note_text The text to add as a note. note_text must be either a string enclosed in quotation marks,
or a character expression.
optional

APPEND The note text is added to the end of any existing notes. If omitted, any existing notes are
overwritten.
optional

CLEAR Notes are deleted. Even if all record notes in a table are deleted, the auto-generated
RecordNote field is not deleted from the table layout.
optional

Examples
Adding the same note to multiple records
Any existing notes for the specified records are overwritten:

NOTES IF MATCH(RECNO(),1,3,5,7) TEXT "note text"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 334 of 934

Commands

Adding or append the same note to multiple records

Any existing notes for the specified records have the new note text appended:

NOTES IF MATCH(RECNO(),1,3,5,7) TEXT "note text" APPEND

Deleting notes from multiple records

All record notes in the table are deleted:

NOTES CLEAR

Notes for the specified records are deleted:

NOTES IF MATCH(RECNO(),1,3,5,7) CLEAR

Notes for records 1-100 are deleted:

NOTES IF RECNO() <= 100 CLEAR

Remarks
Deleting the RecordNote field
To delete the RecordNote field from the table layout, and all notes in the table, use the DELETE NOTES
command without any of the options specified.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 335 of 934

Commands

NOTIFY command
Sends an email notification message.

Syntax
NOTIFY USER username <PASSWORD pwd> MAILBOX pathname ADDRESS recipient <CC cc_
recipient> <BCC bcc_recipient> <SUBJECT subject> MESSAGE message <ATTACHMENT path-
name>

Parameters
Name Description

USER username The email address of the sender.

PASSWORD pwd The password for the mail server.

optional

MAILBOX pathname The SMTP server name to use to send the email message. For example:

MAILBOX "mailserver.example.com"

ADDRESS recipient The email address of one or more recipients. Separate multiple email addresses with a
comma.
Enter a maximum of 1020 characters.

CC cc_recipient The email address of one or more carbon copy recipients. Separate multiple email
addresses with a comma.
optional
Enter a maximum of 1000 characters.

BCC bcc_recipient The email address of one or more blind carbon copy recipients. Separate multiple email
addresses with a comma.
optional

SUBJECT subject The subject line of the email message.

optional

MESSAGE message The body text of the email message. The message is plain text and does not support
HTML.
If you want to insert a line break in your message, use two carat characters: ^^.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 336 of 934

Commands

Name Description

ATTACHMENT pathname The path and filename of one or more attachments. Must be a quoted string.
optional Specify multiple attachments by entering a comma separated list of files for pathname:

ATTACHMENT "result1,result2"

Examples
Sending an error report email
You are running a script, and you want to send a notification email if the script fails. Using NOTIFY, you
define the email message and include two attachments:
l the log file
l a .fil file containing recorded errors

NOTIFY USER "support@company.com" MAILBOX "mail.company.com" ADDRESS "script_

admin@example.com" SUBJECT "Error Report" MESSAGE "Failed to process script. Details
attached." ATTACHMENT "Errors.fil,ACL_Demo.log"

Remarks
Recipients and attachments
You can use the NOTIFY command to send email notification messages to one or more recipients. Mes-
sages can include attached data files and Analytics projects.
The NOTIFY command can be used to notify the appropriate personnel when a script fails unexpectedly.

Protocols and ports

The command can be used with any mail server that supports SMTP (Simple Mail Transfer Protocol), which
is used by Microsoft Exchange and many other mail servers. The NOTIFY command can also be used with
older email applications, from Microsoft and others, that send mail locally.
NOTIFY uses port 25, so this port must be open or the command fails.

Error handling
If Analytics is unable to connect with the mail server, it makes five additional attempts to connect, with a 10-
second pause between each attempt. If all connection attempts are unsuccessful, the NOTIFY command is
canceled, with a message written to the log, but the script continues processing.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 337 of 934

Commands

You can use the SET command to change this default behavior. You can specify a different number of con-
nection attempts and a different amount of time between attempts, or you can turn off additional con-
nection attempts. You can also specify that Analytics stops processing a script if the NOTIFY command is
canceled. For more information, see "SET command" on page 408.
An invalid email recipient is not considered a failure of the NOTIFY command and does not cause a script
to stop regardless of the associated setting.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 338 of 934

Commands

OPEN command
Opens an Analytics table and the associated data file.

Syntax
OPEN {table_name|data_file <FORMAT layout_name>} <BUFFERLENGTH length> <CRLF>
<DBASE> <INDEX index_file> <PRIMARY|SECONDARY> <SKIP bytes> <RELATION key_field>

Parameters
Name Description

table_name The name of the Analytics table to open.

data_file The data file to associate with the table specified by FORMAT layout_name.
Analytics assumes a file extension of .fil if no extension is specified. To open a file with no
extension, insert a period (.) at the end of the file name.

FORMAT layout_name The Analytics table layout to apply to the data file that you open as a table.
optional

BUFFERLENGTH n The length in bytes of the input buffer area to be allocated to the table. The default value
is 33,000 bytes.
optional
Larger buffer areas may improve processing speed at the expense of RAM available for
storing Analytics commands.
If any IBM variable length blocks are read which exceed the buffer length, Analytics dis-
plays an error message and stops processing. The default value is set in the Buffer Size
field in the Table tab in the Options dialog box.
You will seldom need to change BUFFERLENGTH n, because the default is sufficient to
handle almost all situations.

CRLF Specifies that a variable length ASCII file is to be read. Analytics automatically adjusts for
the varying record lengths.
optional
By default, files are assumed to be fixed-length files.

DBASE Specifies that the data source is a dBASE file. Analytics recognizes the type of dBASE file
and automatically creates a table from the file description. Can be omitted for dBASE files
optional
with a .dbf extension.

INDEX index_file The index file to apply to the table when it is opened.
optional The file extension for the index file name is assumed to be .inx when none is specified.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 339 of 934

Commands

Name Description

You can specify INDEX with either primary or secondary tables.

PRIMARY | SECONDARY Specifies that a table is opened as either a primary table or a secondary table. If omitted,
the table is opened as a primary table.
optional

SKIP bytes The number of bytes to bypass at the physical start of the table.
optional SKIP can be used to ignore table header records or leading portions of the table that do
not follow the layout of the remainder of the table. If omitted, the table is read starting at
the first byte.
Note

non-Unicode Analytics 1 byte = 1 character

Unicode Analytics, extended ASCII (ANSI) data 1 byte = 1 character

Unicode Analytics, Unicode data 2 bytes = 1 character

For Unicode data, specify an even number of bytes only. Specifying an

odd number of bytes can cause characters to display incorrectly.

RELATION key_field Specifies that the table is to be opened as an ad hoc related table. Analytics does not
retain this relation when the table is closed.
optional
You must also specify the INDEX parameter when you use RELATION. key_field is the
key field or expression used to create the relation between two tables.

Examples
Opening a table while specifying a table layout
You open the April_2012 table using the March_2012 table layout:

OPEN April_2012 FORMAT March_2012

Opening a dBASE file

You open a dBASE file named Inventory.dbf for which there is no existing table:

OPEN Inventory

Opening a table and apply a pre-existing index

To open either a primary or a secondary table, and apply an index that already exists for the table, use the
following syntax:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 340 of 934

Commands

OPEN Accounts_receivable INDEX Customer_number_AR

OPEN Customer SECONDARY INDEX Customer_number

Opening a table and establish an ad hoc relation to another table

You need to establish a temporary relation between an open table named Customers (the primary table)
and a table named Accounts_receivable (the secondary table).
You use an index named Customer_index and a key field in the primary table named Last_name:

OPEN Accounts_receivable INDEX Customer_index RELATION Last_name

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 341 of 934

Commands

OUTLIERS command
Identifies statistical outliers in a numeric field. Outliers can be identified for the field as a whole, or for sep-
arate groups based on identical values in one or more character, numeric, or datetime key fields.

Syntax
OUTLIERS {AVERAGE|MEDIAN} {PKEY key_field <...n>|NOKEY} ON numeric_field <OTHER field
<...n>> NUMSTDEV number_of_std_devs <IF test> <TO {SCREEN|table_name}> <PRESORT>
<WHILE test> <FIRST range|NEXT range> <OPEN>

Note
You cannot run the OUTLIERS command locally against a server table.
You must specify the OUTLIERS command name in full. You cannot abbreviate it.

Parameters
Name Description

AVERAGE | MEDIAN The method for calculating the center point of the values in numeric_field (the outlier
field).
o AVERAGE – calculate the average (mean) of the values
o MEDIAN – calculate the median of the values
The center point is calculated for either:
o the numeric field as a whole
o the numeric values for each key field group
The center point is subsequently used in calculating the standard deviation of the
numeric field, or of each group.
Note
If you specify MEDIAN, numeric_field must be sorted. Use PRESORT if
numeric_field is not already sorted.
Tip
If the data you are examining for outliers is significantly skewed,
MEDIAN might produce results that are more representative of the bulk
of the data.

PKEY key_field <...n> If you specify PKEY, outliers are identified at the group level. If you specify NOKEY, out-
| NOKEY liers are identified at the field level.
o PKEY key_field – the field or fields to use for grouping the data in the table
Key fields can be character, numeric, or datetime. Multiple fields must be separated

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 342 of 934

Commands

Name Description

by spaces, and can be different data types.

If you specify more than one field, you created nested groups. The nesting follows
the order in which you specify the fields.
For each key field group, a standard deviation is calculated for the group's numeric
values in numeric_field. The group standard deviation is used as the basis for identi-
fying group outliers.
Note
The key field or fields must be sorted. Use PRESORT if one or more
fields are not already sorted.
o NOKEY – do not group the data in the table
A standard deviation is calculated for numeric_field as a whole. The field standard
deviation is used as the basis for identifying field outliers.

ON numeric_field The numeric field to examine for outliers. You can examine only one field at a time.
Outliers are values that fall outside the upper and lower boundaries established by the
field or group standard deviation, or by a specified multiple of the standard deviation.

OTHER field <...n> One or more additional fields to include in the output.
optional Note
Key fields and the outlier field are automatically included in the output
table, and do not need to be specified using OTHER.

NUMSTDEV number_of_ In numeric_field, the number of standard deviations from the mean or the median to the
std_devs upper and lower outlier boundaries. You can specify any positive integer or decimal
numeral (0.5, 1, 1.5, 2 . . . )
The formula for creating outlier boundaries is:
mean/median ± (number_of_std_devs * standard deviation)
Note
Standard deviation is a measure of the dispersion of a data set – that is,
how spread out the values are. The outliers calculation uses population
standard deviation.

Example of outlier boundaries

NUMSTDEV 2

establishes, for numeric_field as a whole, or for each key field group:

l an upper outlier boundary 2 standard deviations greater than the mean or the
median
mean/median + (2 * SD)
l a lower outlier boundary 2 standard deviations less than the mean or the
median
mean/median – (2 * SD)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 343 of 934

Commands

Name Description

Any value greater than the upper boundary, or less than the lower boundary, is included
as an outlier in the output results.
Note
For the same set of data, as you increase the value in number_of_std_
devs you potentially decrease the number of outliers returned.

TO SCREEN | table_name The location to send the results of the command to:
optional o SCREEN – displays the results in the Analytics display area
o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Output.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.

PRESORT Performs a sorting operation before executing the command.

optional
If you specify PRESORT and: Sorts by:

PKEY, AVERAGE o key field or fields

o key field or fields, then by numeric_field (if
numeric_field is computed)
Note
Sorting a computed
numeric_field is an internal,
technical requirement of Ana-
lytics.

PKEY, MEDIAN key field or fields, then by numeric_field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 344 of 934

Commands

Name Description

If you specify PRESORT and: Sorts by:

NOKEY, AVERAGE no sorting

NOKEY, MEDIAN numeric_field

Tip
If the appropriate field or fields in the input table are already sorted, you
can save processing time by not specifying PRESORT.
Note
You cannot use PRESORT inside the GROUP command.

FIRST range | NEXT range The number of records to process:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Identifying transaction amounts that are out of the ordinary
You want to identify transaction amounts that are out of the ordinary across the entire Ar table in Sample
Project.acl.
You decide to set the outlier boundaries at 3 times the standard deviation of the Amount field. The test
returns 16 outliers in the table of 772 records.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 345 of 934

Commands

OPEN Ar
OUTLIERS AVERAGE NOKEY ON Amount NUMSTDEV 3 PRESORT TO "Outliers_AR.fil" OPEN

You repeat the test, but increase the standard deviation multiple to 3.5. The test now returns only 6 outliers
because the outlier boundaries are farther away from the center point of the values in the Amount field.

OPEN Ar
OUTLIERS AVERAGE NOKEY ON Amount NUMSTDEV 3.5 PRESORT TO "Outliers_AR.fil"
OPEN

Identifying transaction amounts that are out of the ordinary for each cus-
tomer
For each customer in the Ar table in Sample Project.acl, you want to identify any transaction
amounts that are out of the ordinary.
You decide to set the outlier boundaries at 3 times the standard deviation of each customer's group of
transactions.

OPEN Ar
OUTLIERS AVERAGE PKEY No ON Amount NUMSTDEV 3 PRESORT TO "Outliers_Customer_
AR.fil" OPEN

The test returns 7 outliers. The standard deviation and the average are reported for each customer's
group of transactions:

Cust Number (No) Trans Amount STDEV AVERAGE Group Number

1 065003 4,954.64 1015.58 833.83 1

2 262001 3,567.34 772.44 438.81 2

3 262001 (2,044.82) 772.44 438.81 2

4 376005 (931.55) 411.18 484.57 3

5 501657 5,549.19 1332.80 441.14 4

6 811002 3,409.82 634.20 672.10 5

7 925007 3,393.87 736.48 906.16 6

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 346 of 934

Commands

How outliers are identified for customer 262001

Customer 262001 has 101 transactions in the Ar table, and two of them are reported as outliers because
they exceed the outlier boundaries for that customer:

Outlier Lower boundary Upper boundary Outlier

(2,044.82) (1,878.51) 2,756.13 3,567.34

How outlier boundaries are calculated for customer 262001

The outlier boundaries are the average of all customer 262001 transactions, plus or minus the specified mul-
tiple of the standard deviation of the transactions:

Average of all customer 262001 transactions 438.81

Specified multiple of the standard deviation 3

Standard deviation of the transactions 772.44

438.81 ± (3 * 772.44)
= 438.81 ± 2,317.32
= (1,878.51) (lower boundary)
= 2,756.13 (upper boundary)

Using MEDIAN to identify transaction amounts that are out of the ordinary for
each customer
You use MEDIAN, instead of AVERAGE, to perform the same outlier test that you performed in the
example above.

OPEN Ar
OUTLIERS MEDIAN PKEY No ON Amount NUMSTDEV 3 PRESORT TO "Outliers_Customer_AR_
Median.fil" OPEN

The test returns 10 outliers instead of the 7 that are returned in the previous test. Depending on the nature
of the data, MEDIAN and AVERAGE can return somewhat different results:

Cust Number (No) Trans Amount STDEV MEDIAN Group Number

1 065003 4,954.64 1015.58 663.68 1

2 262001 (2,044.82) 772.44 450.67 2

3 262001 3,567.34 772.44 450.67 2

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 347 of 934

Commands

Cust Number (No) Trans Amount STDEV MEDIAN Group Number

4 376005 (931.55) 411.18 517.16 3

5 501657 4,426.14 1332.80 146.80 4

6 501657 5,549.19 1332.80 146.80 4

7 811002 3,409.82 634.20 624.53 5

8 925007 2,972.78 736.48 717.88 6

9 925007 3,030.71 736.48 717.88 6

10 925007 3,393.87 736.48 717.88 6

How outlier boundaries are calculated for each customer

The outlier boundaries are the median value of each customer's transactions, plus or minus the specified
multiple of the standard deviation of the transactions.
For example, for customer 262001: 450.67 ± (3 * 772.44)

Remarks
Note
For more information about how this command works, see the Analytics Help.

Add outlier boundary fields to the results table

Analytics automatically adds the STDEV and AVERAGE or MEDIAN calculated fields to the outliers res-
ults table. You may find it useful to also add two computed fields that show the outliers boundaries used to
identify the outliers in the results table.
1. Open the outliers results table.
2. Paste this expression into the Analytics command line, edit it as required, and press Enter:

DEFINE FIELD Lower_Boundary COMPUTED AVERAGE - (number_of_std_devs * STDEV)

l For number_of_std_devs, substitute the actual standard deviation multiple you used.
l If you used median as a center point rather than average, substitute MEDIAN for AVERAGE.
3. Paste this expression into the Analytics command line, edit it as required, and press Enter:

DEFINE FIELD Upper_Boundary COMPUTED AVERAGE + (number_of_std_devs * STDEV)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 348 of 934

Commands

l For number_of_std_devs, substitute the actual standard deviation multiple you used.
l If you used median as a center point rather than average, substitute MEDIAN for AVERAGE.

4. Right-click the view and select Add Columns .

5. From the Available Fields list, double-click Lower_Boundary and Upper_Boundary to add them to
the Selected Fields list.
6. Click OK.
7. Optional. Reposition the added fields by dragging the column headers.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 349 of 934

Commands

PASSWORD command
Creates a password definition, without a password value, that prompts users for a password while a script
is running.

Syntax
PASSWORD num < prompt>

Parameters
Name Description

num A value from 1 to 10 that uniquely identifies the password definition.

prompt A valid character expression to display in the dialog box used to prompt for the pass-
word. Enclose literal strings in quotation marks.
optional
If prompt is omitted, a default dialog box with no message is displayed.

Examples
Prompting for password information
You use the PASSWORD command to prompt the user for the three passwords required in a script. Once
the user enters the required passwords, the script can complete the remaining processing without inter-
ruption:

PASSWORD 1 "Enter the password for the Receivables database"

PASSWORD 2 "Enter the password for the Payables database"
PASSWORD 3 "Enter the password for the Customer database"

Specifying a password when refreshing an Analytics table

You combine the PASSWORD command with the REFRESH command to update a password-protected
data file:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 350 of 934

Commands

PASSWORD 1 "Password:"
REFRESH Abc PASSWORD 1

Specifying a password to define a server table

You use the PASSWORD command with the DEFINE TABLE DB command to define a server table via AX
Connector, which requires one password for the database profile, and another for the associated server pro-
file:

DEFINE TABLE DB SOURCE Inventory_DBProfile PASSWORD 9 PASSWORD 3

Remarks
When to use PASSWORD
Use the PASSWORD command to prompt a user to enter password information before a script accesses,
imports, or refreshes password-protected data.
You can create up to ten different password definitions in a script .
PASSWORD is useful if:
l you want to avoid typing an actual password in a script, which the SET PASSWORD command
requires
l individual users need to enter distinct passwords

How passwords are stored

User-entered passwords are temporarily and securely stored in memory.
When a user types a password into the prompt dialog box, the characters are masked using asterisks (*).
The password does not appear in either the script or the log.

Storing passwords for server-based analytics

The PASSWORD command is not supported in analytics run in Robots or on AX Server, or in legacy server
scripts.
You can use the PASSWORD tag to prompt for a password when a user schedules an analytic in Robots or
on AX Server.
You can use the SET PASSWORD command to specify passwords in legacy server scripts.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 351 of 934

Commands

PAUSE command
Pauses a script, and displays information in a dialog box for users.

Syntax
PAUSE message <IF test>

Parameters
Name Description

message A message to display in the dialog box. The maximum length is 199 characters.
message must be enclosed in quotation marks. If the message contains double quo-
tation marks, enclose it in single quotation marks.

Examples
Displaying an error message
You require user input to meet specific requirements. When you detect that the input does not meet those
requirements, you use the PAUSE command and display an error message in a dialog box:

PAUSE "The product class must be a 2-digit value."

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 352 of 934

Commands

Remarks
When to use PAUSE
Use PAUSE to display read-only messages on screen in the course of running a script. You can display
error messages or information such as the result of an analytic operation.

How it works
While the message dialog box is displayed, execution of the script is halted and only resumes once the user
clicks OK to close the message dialog box. For this reason, you cannot use PAUSE in scripts or analytics
that must run unattended.

Limitations
PAUSE has the following limitations:
l cannot be included inside the GROUP command
l cannot be used in analytics run in Robots, or on AX Server

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 353 of 934

Commands

PREDICT command
Applies a predictive model to an unlabeled data set to predict classes or numeric values associated with
individual records.

Syntax
PREDICT MODEL model_name TO table_name <IF test> <WHILE test> <FIRST range|NEXT
range>

Parameters
Name Description

MODEL model_name The name of the model file to use for predicting classes or values. You use a model file
previously generated by the TRAIN command.
You must specify the *.model file extension. For example:

MODEL "Loan_default_prediction.model"

Note
The model file must have been trained on a data set with the same fields
as the unlabeled data set – or substantially the same fields.

TO table_name The name of the Analytics table output by the prediction process.

The table contains the key fields you specified during the training process, and either
one or two fields generated by the prediction process:
o Predicted – the predicted classes or numeric values associated with each record in
the unlabeled data set
o Probability – (classification only) the probability that a predicted class is accurate
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Loan_applicants_default_predicted.FIL"
By default, the table data file (.FIL) is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
o TO "C:\Loan_applicants_default_predicted.FIL"
o TO "ML Predict output\Loan_applicants_default_predicted.FIL"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 354 of 934

Commands

Name Description

FIRST range | NEXT range The number of records to process:

Examples
Use a classification model to make predictions
You input a classification model to the PREDICT command to make predictions about which current loan
applicants will default if given a loan.
You previously produced the classification model using the TRAIN command with a set of historical loan
data, including loan default information.

OPEN "Loan_applicants_current"
PREDICT MODEL "Loan_default_prediction.model" TO "Loan_applicants_default_predicted.FIL"

Use a regression model to make predictions

You input a regression model to the PREDICT command to make predictions about the future sale price of

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 355 of 934

Commands

houses.
You previously produced the regression model using the TRAIN command with a set of recent house
sales data, including the sale price.

OPEN "House_price_evaluation"
PREDICT MODEL "House_price_prediction.model" TO "House_prices_predicted.FIL"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 356 of 934

Commands

PRINT command
Prints a text file, an Analytics log file, or an Analytics project item that has been exported as an external file –
a script (.aclscript), a table layout (.layout), or a workspace (.wsp). You can also print a graph that has been
generated by a command.

Syntax
PRINT {file_name|GRAPH}

Parameters
Name Description

file_name | GRAPH The item to print:

o file_name – the relative or absolute path and file name of the file to print
For example, "C:\ACL Data\Sample Data Files\ACL_Demo.log" or "Sample Data
Files\ACL_Demo.log".
If the path or file name includes spaces you must enclose file_name in quotation
marks.
o GRAPH – the graph previously output as the result of a command

Examples
Printing a log file
To print the log file for the ACL_Demo.acl project, specify the following command:

PRINT "C:\ACL Data\Sample Data Files\ACL_Demo.log"

Printing a graph
To print the graph produced from the BENFORD command, specify the following commands:

OPEN Metaphor_APTrans_2002
BENFORD ON Invoice_Amount LEADING 1 TO GRAPH
PRINT GRAPH

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 357 of 934

Commands

Remarks
Selecting a printer
The printer used is the default printer configured in Microsoft Windows. To change the printer you need to
change the default printer in Windows.

Related commands
To print the contents of an Analytics table in a project, use the DO REPORT command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 358 of 934

Commands

PROFILE command
Generates summary statistics for one or more numeric fields, or numeric expressions, in an Analytics table.

Syntax
PROFILE {<FIELDS> numeric_field <...n>|<FIELDS> ALL} <IF test> <WHILE test> <FIRST
range|NEXT range>

Parameters
Name Description

FIELDS numeric_field Specify individual fields to profile, or specify ALL to profile all numeric fields in the
<...n> | FIELDS ALL Analytics table.

FIRST range | NEXT range The number of records to process:

Examples
Profiling a single field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 359 of 934

Commands

You profile the Salary field:

OPEN Employee_Payroll
PROFILE FIELDS Salary

The command generates the following output:

Field Name Total Value Absolute Value Minimum Maximum

SALARY 1,152,525 1,152,525 15,340 52,750

Remarks
Statistics displayed in output
The following statistics are displayed for each numeric field or numeric expression specified for the com-
mand:
l total value
l absolute value
l minimum value
l maximum value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 360 of 934

Commands

QUIT command
Ends the current session and closes Analytics.

Syntax
QUIT

Examples
Check if a file exists and close Analytics if it does not
You have created a script for others to run, but if a required file does not exist, you want to close Analytics.
The example below checks if the required Inventory.csv file exists, and closes Analytics if it does not:

IF FILESIZE("Inventory.csv") = -1 QUIT

Automatically close Analytics after a script completes

The script below summarizes the Inventory table, and produces output results, then automatically closes
Analytics:

OPEN Inventory
SUMMARIZE ON Location ProdCls SUBTOTAL Value TO "Inventory_value_by_location_class.FIL"
PRESORT CPERCENT
QUIT

Remarks
Changes are saved
When QUIT executes, any Analytics tables that are open are saved and closed before quitting.
If you modified the active view or a script and did not save the changes, Analytics prompts you to save the
changes before quitting.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 361 of 934

Commands

RANDOM command
Generates a set of random numbers.

Syntax
RANDOM NUMBER n <SEED seed_value> MINIMUM min_value MAXIMUM max_value
<COLUMNS n> <UNIQUE> <SORTED> <TO {SCREEN|filename}> <APPEND>

Parameters
Name Description

NUMBER n The size of the set of random numbers to be generated.

A maximum of 32767 numbers can be generated.

SEED seed_value The value used to initialize the random number generator.
optional If you specify a seed value, it can be any number. Each unique seed value results in a
different set of random numbers. If you respecify the same seed value, the same set of
random numbers is generated. Regenerating the same set of random numbers can be
required if you need to replicate analysis.
o Seed value – explicitly specify a seed value, and save the value, if you want the
option of replicating a particular set of random numbers.
o No seed value – enter a seed value of ‘0’, or leave the seed value blank, if you want
Analytics to randomly select a seed value.

MINIMUM min_value The smallest possible number in the set of random numbers. Any valid numeric value or
expression is allowed.

MAXIMUM max_value The greatest possible number in the set of random numbers. Any valid numeric value or
expression is allowed.

COLUMNS n The number of columns used to display the set of random numbers.
optional If you omit COLUMNS, the default is 6 columns.

UNIQUE Include only unique numbers in the set of random numbers.

optional If you omit UNIQUE, duplicate values are allowed in the set of random numbers.
Note
Do not specify UNIQUE when the specified size of the set of random
numbers exceeds 75 percent of the range between MINIMUM and
MAXIMUM. Doing so can result in too many random number selections
being discarded.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 362 of 934

Commands

Name Description

SORTED Displays the set of random numbers in ascending order.

optional If you omit SORTED, the numbers are displayed in the order in which they are randomly
selected.

TO SCREEN | filename The location to send the results of the command to:
optional o SCREEN – displays the results in the Analytics display area
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
If you omit TO, the set of random numbers is output to screen.

Examples
Generate a text file with 100 random numbers
You want to pull 100 hard copy files at random from a set of files with numbering that ranges from 10,000 to
20,000.
You can use the RANDOM command to generate a text file with 100 random numbers between 10,000 and
20,000. You then pull the hard copy files that match the random numbers. The numbers are arranged in 10
columns, are unique, and are sorted in ascending order:

RANDOM NUMBER 100 SEED 45387 MINIMUM 10000 MAXIMUM 20000 COLUMNS 10 UNIQUE
SORTED TO "Random_Numbers.txt"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 363 of 934

Commands

Remarks
Note
For more information about how this command works, see the Analytics Help.

Random number algorithm

The RANDOM command uses the default Analytics random number algorithm. Unlike the SAMPLE com-
mand, the RANDOM command does not have the option of using the Mersenne-Twister random number
algorithm.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 364 of 934

Commands

RCOMMAND command
Passes an Analytics table to an external R script as a data frame and creates a new table in the
Analytics project using output from the external R script.

Syntax
RCOMMAND FIELDS field <...n> RSCRIPT path_to_script TO table_name <IF test> <WHILE test>
<FIRST range|NEXT range> <KEEPTITLE> <SEPARATOR character> <QUALIFIER character>
<OPEN>

Parameters
Name Description

FIELDS field_name <...n> The fields from the source Analytics table, or the expressions, to include in the data frame
that is sent to the R script.
Depending on the edition of Analytics that you are using, you may encounter errors when
sending data containing some special characters to R:
o non-Unicode – "\"
o Unicode – "ÿ" or "Ŝ"
o Both – box drawing characters such as blocks, black squares, and vertical broken bars
Note
Mixed language data is also not supported, for example a table con-
taining both Japanese and Chinese characters.

RSCRIPT path_to_script The full or relative path to the R script on the file system. Enclose path_to_script in quo-
tation marks.

TO table_name The location to send the results of the command to:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 365 of 934

Commands

Name Description

IF test A condition that must be met to process the current record. The data frame passed to the
R script contains only those records that meet the condition.
optional

FIRST range | NEXT range The number of records to process:

optional o FIRST – start processing from the first record until the specified number of records is
reached
o NEXT – start processing from the currently selected record until the specified number
of records is reached
Use range to specify the number of records to process.
If you omit FIRST and NEXT, all records are processed by default.
Caution
There is a known issue in the current version with NEXT when running the
RCOMMAND. Avoid using this option as the record reference may reset to
the first record regardless of which record is selected.

KEEPTITLE Treat the first row of data as field names instead of data. If omitted, generic field names
are used.
optional
This option is required if you want to retrieve data using column names in the R script.

SEPARATOR character The character to use as the separator between fields. You must specify the character as a
quoted string.
optional
The default character is a comma.
Note
Avoid using any characters that appear in the input fields. If the
SEPARATOR character appears in the input data, the results may be
affected.

QUALIFIER character The character to use as the text qualifier to wrap and identify field values. You must spe-
cify the character as a quoted string.
optional
The default character is a double quotation mark.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 366 of 934

Commands

Name Description

Note
Avoid using any characters that appear in the input fields. If the
QUALIFIER character appears in the input data, the results may be
affected.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Examples
Getting R up and running (Hello world)
You create a hello world script to test your connection between Analytics and R:

Analytics command

RCOMMAND FIELDS "Hello", ", world!" TO "r_result" RSCRIPT "C:\scripts\r_scripts\analysis.r"

R script (analysis.r)

srcTable<-acl.readData()

# create table to send back to ACL

output<-data.frame(
c(srcTable[1,1]),
c(srcTable[1,2])
)

# add column names and send table back to ACL

colnames(output) <- c("Greeting","Subject")
acl.output<-output

Accessing field data using row and column coordinates

You send a number of invoice fields to an R script for analysis outside Analytics:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 367 of 934

Commands

Analytics command

RCOMMAND FIELDS Department_Code Invoice_Amount Invoice_Date Invoice_Number Vendor_

Number TO "r_result" RSCRIPT "C:\scripts\r_scripts\analysis.r"

R script (analysis.r)

# Retrieves invoice number from second row of data frame in R script

srcTable<-acl.readData()
srcTable[2,4]

Accessing field data using column names

You send a number of invoice fields to an R script for analysis outside Analytics. You use the KEEPTITLE
option so that columns can be referenced by name in R:

Analytics command

RCOMMAND FIELDS Department_Code Invoice_Amount Invoice_Number TO "r_result" RSCRIPT

"C:\scripts\r_scripts\analysis.r" KEEPTITLE

R script (analysis.r)

# Retrieves invoice number from second row of data frame in R script

srcTable<-acl.readData()
srcTable["2","Invoice_Number"]

Sending invoice records that exceed 1000.00 value to R script

You send a number of invoice fields to an R script for analysis outside Analytics. You use IF to limit the
records sent to R. Only those records with an invoice amount exceeding 1000.00 are sent:

Analytics command

RCOMMAND FIELDS Department_Code Invoice_Amount Invoice_Number TO "r_result" IF Invoice_

Amount > 1000.00 RSCRIPT "C:\scripts\r_scripts\analysis.r" KEEPTITLE

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 368 of 934

Commands

R script (analysis.r)

# Retrieves invoice number from second row of data frame in R script

srcTable<-acl.readData()
srcTable["2","Invoice_Number"]

Sending invoice records and returns multiplied invoice amounts

You send a number of invoice fields to an R script for analysis outside Analytics. The R script performs a
single action against every cell in the named column:

Analytics command

RCOMMAND FIELDS Department_Code Invoice_Amount Invoice_Number TO "r_result" RSCRIPT

"C:\scripts\r_scripts\analysis.r" KEEPTITLE

R script (analysis.r)

# Returns slice of ACL table with value doubled

srcTable<-acl.readData()
acl.output<-srcTable["Invoice_Amount"] * 2

Remarks
Note
For more information about how this command works, see the Analytics Help.

Referencing Analytics data in the R script

The Analytics table is passed to the script as an R data frame. Data frames are tabular data objects that
may contain columns of different modes, or types, of data.
To work with the data frame created by Analytics in an R script, invoke the acl.readData() function and store
the returned data frame in a variable:

# stores the Analytics table in a data frame called myTable that can be referenced throughout the script
myTable<-acl.readData()

To retrieve data from a cell in the data frame, you can use one of the following approaches:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 369 of 934

Commands

l Using row and column coordinates:

# Retrieves the value in the first row and second column of the data frame
myTable[1,2]

Note
Coordinates are based on the order of fields specified in the command, not the table
layout or view that is currently open.
l Using row and column names:

# Retrieves the value in the first row and "myColumnTitle" column of the data frame
myTable["1","myColumnTitle"]

You must specify the KEEPTITLE option of the command to use column names.
Rows are named "1", "2", "3", and increment accordingly. You may also use a combination of names
and coordinates.

Passing data back to Analytics

To return a data frame or matrix back to Analytics and create a new table, use the following syntax:

# Passes myNewTable data frame back to Analytics to create a new table

acl.output<-myNewTable

Note
You must return a data frame or a matrix to Analytics when the R script terminates.
Ensure the columns in the data frame or matrix contain only atomic values and not lists,
matrices, arrays, or non-atomic objects. If the values cannot be translated into
Analytics data types, the command fails.

Data type mappings

Analytics data types are translated into R data types using a translation process between the Analytics pro-
ject and the R script:

Analytics data type R data type(s)

Logical Logical

Numeric Numeric

Character Character

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 370 of 934

Commands

Analytics data type R data type(s)

Datetime Date, POSIXct, POSIXlt

Performance and file size limits

The time it takes to run your R script and process the data that is returned increases for input data exceed-
ing 1 GB. R does not support input files of 2 GB or higher.
The number of records sent to R also affects performance. For two tables with the same file size but a dif-
fering record count, processing the table with fewer records is faster.

Handling multi-byte character data

If you are sending data to R in a multi-byte character set, such as Chinese, you must set the system locale
appropriately in your R script. To successfully send a table of multi-byte data to R, the first line of the R script
must contain the following function:

# Example that sets locale to Chinese

Sys.setlocale("LC_ALL","Chinese")

For more information about Sys.setlocale( ), see the R documentation.

R log file
Analytics logs R language messages to an aclrlang.log file in the project folder. Use this log file for
debugging R errors.
Tip
The log file is available in the Results folder of Analytics Exchange analytic jobs.

Running R scripts on AX Server

If you are writing an analysis app to run on AX Server and you want to work with external R scripts:
1. Upload the file as a related file with the analysis app.
2. Use the FILE analytic tag to identify the file(s).
3. Reference the file(s) using the relative path ./filename.r.
Note
Using a related file ensures that the TomEE application server account has sufficient per-
missions to access the file when running R with Analytics Exchange.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 371 of 934

Commands

REFRESH command
Updates the data in an Analytics table from its associated data source.

Syntax
REFRESH < table_name> <PASSWORD num>

Parameters
Name Description

table_name The name of the Analytics table to refresh. If you do not specify a table_name, the open
table is refreshed.
optional

PASSWORD num The password definition to use.

optional You do not use PASSWORD num to prompt for, or specify, an actual password. The
password definition refers to a password previously supplied or set using the
PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic
tag.
num is the number of the password definition. For example, if two passwords have been
previously supplied or set in a script, or when scheduling an analytic, PASSWORD 2
specifies that password #2 is used.
For more information about supplying or setting passwords, see:
l "PASSWORD command" on page 350
l "SET command" on page 408
l PASSWORD analytic tag
For more information about supplying or setting passwords, see:
l PASSWORD command
l SET command
l PASSWORD analytic tag
Note
The password is used to access the original source data system.
You cannot use REFRESH with a password for file-based data sources,
with the exception of PDFs.

Examples
Refreshing a table with no password required

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 372 of 934

Commands

If a password is not required for the data source, just specify the REFRESH command and the name of the
Analytics table to refresh.

REFRESH Invoices

Refreshing a table with a password in an interactive script

If you are creating an interactive script, you can prompt the user for the password:

PASSWORD 1 "Enter your password:"

REFRESH Invoices PASSWORD 1

If you are refreshing a table originally imported from a password-protected data source using the
ACCESSDATA command, the password prompt is automatic and does not need to be separately specified:

REFRESH Invoices

Refreshing a table with a password in a non-interactive script

You can set the password in a script if you do not want to prompt the user for the value:

SET PASSWORD 1 TO "password"

REFRESH Invoices PASSWORD 1

The disadvantage of this method is that the password appears as clear text in the script.

Refreshing a table with a password in an AX Server analytic

If you are creating an AX Server analytic, you can prompt the user for the password when the analytic is
scheduled, or run ad-hoc:

COMMENT
//ANALYTIC Refresh Table
//PASSWORD 1 "Enter your password:"
END
REFRESH Invoices PASSWORD 1

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 373 of 934

Commands

How it works
The REFRESH command updates the contents of a table by re-running the IMPORT command, or the
ACCESSDATA command, initially used to define and import the table.

REFRESH updates table content only

The REFRESH command updates only the content of existing fields in an Analytics table. It cannot update
an Analytics table layout.
You cannot use REFRESH if the structure of the source data has changed – for example, if fields have
been added or removed. You must re-import the data.

Data sources that support refreshing

You can use the REFRESH command to update the content of an Analytics table created using any of the
following commands:
l IMPORT ACCESS
l IMPORT DELIMITED
l IMPORT EXCEL
l IMPORT ODBC (legacy ODBC command)
l IMPORT PDF
l IMPORT PRINT
l IMPORT SAP
l IMPORT XBRL
l IMPORT XML
l ACCESSDATA (ODBC data sources)

REFRESH and ACCESSDATA
The following guidelines apply when refreshing a table imported from an ODBC data source using the
ACCESSDATA command.
l Open table – If the table is open when you refresh it, you temporarily need disk space equal to twice
the size of the table. If you have limited disk space, close the table first before refreshing it.
l Analytics 12 – Tables that were imported using the ACCESSDATA command in version 12 of
Analytics are not refreshable, even if you are using a more recent version of Analytics.
If you want to be able to refresh these tables, re-import them using Analytics 12.5 or later.

REFRESH and passwords
You can use the REFRESH command with password-protected data sources that exist in a database, or
in a cloud data service.
You cannot use the REFRESH command with password-protected file-based data sources, such as Excel
files. The one exception is password-protected PDFs.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 374 of 934

Commands

REFRESH and the Analysis App window

Do not use the REFRESH command in scripts that you intend to run in the Analysis App window.
Depending on how a table is imported, refreshing the data in the table is either not supported, or produces
unpredictable results, if attempted in the Analysis App window.
If you want to refresh data as part of a script run in the Analysis App window, use either an
IMPORT command, or the ACCESSDATA command, and overwrite the table.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 375 of 934

Commands

RENAME command
Renames an Analytics project item or a file.

Syntax
RENAME item_type name <AS|TO> new_name <OK>

Parameters
Name Description

item_type name The type and name of the project item or file that you want to rename.
Note
In most cases, you cannot rename an item or file if it is active, open, or in
use.
Specify one of the following valid types:
o FIELD – physical data field, computed field, or variable
l The table containing the field must be open. However, the active view cannot
include the field.
l You cannot rename a field that is referenced by a computed field.
o FORMAT – Analytics table
o INDEX – index
o REPORT – report or view
o WORKSPACE – workspace
o SCRIPT (or BATCH) – script
o DATA – Analytics data file (.fil)
o FILE – data file in the file system
o LOG – Analytics log file (.log)
o TEXT – text file

AS | TO new_name The new name for the project item or file.

Note
Length limitations apply to most Analytics project item names. For more
information, see Character and size limits in Analytics.

OK Deletes or overwrites items without asking you to confirm the action.

optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 376 of 934

Commands

Examples
Renaming a field
You need to rename the ProdNo field to ProdNum . You use OK to perform the action without additional con-
firmation:

OPEN Inventory
RENAME FIELD ProdNo AS ProdNum OK

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 377 of 934

Commands

REPORT command
Formats and generates a report based on the open Analytics table.

Syntax
REPORT <ON break_field <PAGE> <NODUPS> <WIDTH characters> <AS display_name>>
<...n> FIELD other_fields <WIDTH characters> <AS display_name> <...n> <SUPPRESS>
<NOZEROS> <LINE n other_fields> <PRESORT < sort_field>> <...n> <SUMMARIZED> <SKIP n>
<EOF> <TO {SCREEN|PRINT|filename <HTML>}> <IF test> <WHILE test> <FIRST range|NEXT
range> <HEADER header_text> <FOOTER footer_text> <APPEND>

Parameters
Name Description

ON break_field PAGE The character field or fields used to break the report into sections.
NODUPS WIDTH char-
A new report section and subtotal is created each time the value in break_field
acters AS display_name
changes. Breaking reports into sections can make them easier to scan.
<...n>
o break_field – the field to use as a break field
optional
To run a report based on a view (DO REPORT), the break field must be the leftmost
character field in the view.
o PAGE – inserts a page break when the break field value changes
o NODUPS – suppresses duplicate display values in the break field
For example, if the customer name is listed for each invoice record, you can make
the report more readable by listing only the first instance of each customer name.
o WIDTH characters – the output length of the field in characters
o AS display_name – the display name (alternate column title) for the field in the report
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title. If you want the display name to be the same as
the field name, or an existing display name in the source table, do not use AS.
Note
You must specify ON to use break_field , PAGE, NODUPS, or
PRESORT.

FIELD other_fields WIDTH The fields to be included in the report.

characters AS display_ o WIDTH characters – the output length of the field in characters
name <...n> o AS display_name – the display name (alternate column title) for the field in the report
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title. If you want the display name to be the same as
the field name, or an existing display name in the source table, do not use AS.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 378 of 934

Commands

Name Description

The SUBTOTAL and ACCUMULATE keywords are synonyms for FIELD, and have been
deprecated. All numeric fields are automatically subtotaled.
Note
Break fields are automatically included in the report and do not need to
be specified as other_fields.

SUPPRESS Excludes blank detail lines from the report.

optional

NOZEROS Substitutes blank values for zero values in the field.

optional For example, if a report includes a large number of zero values in a field, the report is
easier to read if it only displays non-zero values.

LINE n other_fields Specifies the number of output lines in the column and the fields to appear on the line
number n.
optional
If no value is specified, the column defaults to a single line. The value of n must be
between 2 and 60 inclusive.
Column headings on the report are determined solely by the fields on the first line.
other_fields specifies appropriate fields or expressions for the report.

PRESORT sort_field <...n> o Sorts break_field , if one or more break fields are specified.
o Sorts sort_field, if one or more sort fields are specified.
optional
PRESORT does not sort the fields listed as other_fields unless they are also listed as
sort_field.

SUMMARIZED Produces a report with subtotals and totals only, and no detail lines.
optional Subtotals are generated for the unique break field values. If SUMMARIZED is not spe-
cified, Analytics produces a report that includes detail lines, as well as subtotals for
each of the specified key break fields.

SKIP n Inserts blank lines between detail lines in the report.

optional n must be an integer specifying the number of lines to insert. For example, SKIP 1 pro-
duces a double-spaced report.

TO SCREEN | PRINT| file- The location to send the results of the command to:
name <HTML> o SCREEN – displays the results in the Analytics display area
optional o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 379 of 934

Commands

Name Description

folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o PRINT – sends the results to the default printer
By default, reports output to a file are saved as ASCII text files. Specify HTML if you want
to output the report as an HTML file (.htm).
If you omit TO, the report is output to screen.

FIRST range | NEXT range The number of records to process:

HEADER header_text The text to insert at the top of each page of a report.
optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

APPEND Appends the command output to the end of an existing file instead of overwriting it.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 380 of 934

Commands

Name Description

Examples
Generating an HTML report
You generate a report from the Ar table and output the report to a formatted HTML file:

OPEN Ar
REPORT ON No FIELD Due Type Amount TO "C:\Reports\AR.htm" HTML

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 381 of 934

Commands

RETRIEVE command
Retrieves the result of a Direct Link query submitted for background processing.

Syntax
RETRIEVE table_name PASSWORD num

Parameters
Name Description

table_name The name of the table originally created in Analytics by the Direct Link query.
The table must already exist before you use RETRIEVE.

PASSWORD num The password definition to use.

Examples
Retrieving the Background mode query result
You set the password and then retrieve the Background mode query result for an Analytics table named

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 382 of 934

Commands

DD02T_Data:

SET PASSWORD 1 TO "pwd"

RETRIEVE DD02T_Data PASSWORD 1

Remarks
Before you begin
This command is only supported if Direct Link is installed and configured.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 383 of 934

Commands

SAMPLE command
Draws a sample of records using either the record sampling or monetary unit sampling method.
Record samplingMonetary unit sampling

Syntax
Note
The syntax does not include filtering (IF statements) or scope parameters because apply-
ing these options compromises the validity of a sample.

Fixed interval selection method

SAMPLE <ON> RECORD INTERVAL interval_value <FIXED initial_value> {RECORD|FIELDS
field_name <...n>} TO table_name <OPEN> <APPEND> <LOCAL>

Cell selection method

SAMPLE <ON> RECORD CELL INTERVAL interval_value <RANDOM seed_value>
{RECORD|FIELDS field_name < ...n>} TO table_name <OPEN> <APPEND> <MERSENNE_
TWISTER> <LOCAL>

Random selection method

SAMPLE <ON> RECORD NUMBER sample_size <RANDOM seed_value> <ORDER>
{RECORD|FIELDS field_name < ...n>} TO table_name <OPEN> <APPEND> <MERSENNE_
TWISTER> <LOCAL>

Parameters
Note
Do not include thousands separators when you specify values.

Name Description

ON RECORD Use record sampling.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 384 of 934

Commands

Name Description

INTERVAL interval_value INTERVAL interval_value FIXED initial_value

FIXED initial_value | CELL
INTERVAL interval_value | Use the fixed interval selection method.
NUMBER sample_size
An initial record is selected and all subsequent selections are a fixed interval or dis-
tance apart – for example, every 20th record after the initial selection.
o INTERVAL interval_value – specify the interval value that was generated by cal-
culating the sample size
o FIXED initial_value – specify the initial record number selected
If you specify an initial_value of zero ('0'), or omit FIXED, Analytics randomly selects
the initial record.

CELL INTERVAL interval_value

Use the cell selection method.
The data set is divided into multiple equal-sized cells or groups, and one record is ran-
domly selected from each cell.
The interval_value dictates the size of each cell. Specify the interval value that was gen-
erated by calculating the sample size.

NUMBER sample_size
Use the random selection method.
All records are randomly selected from the entire data set.
Specify the sample size that was generated by calculating the sample size.

RANDOM seed_value Note

optional Cell and random selection methods only.
The seed value to use to initialize the random number generator in Analytics.
If you specify a value of zero ('0'), or omit RANDOM, Analytics randomly selects the seed
value.

ORDER Note
optional Random selection method only.
You can only use ORDER when specify FIELDS.
Adds the ORDER field to the output results.
This field displays the order in which each record is randomly selected.

RECORD | FIELDS field_ o RECORD – the entire record is included in the output table
name <...n> o FIELDS – individual fields, rather than the entire record, are included in the output
table
Specify the field(s) or expressions to include. If you specify multiple fields, they must
be separated by spaces.

TO table_name The location to send the results of the command to:

o table_name – saves the results to an Analytics table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 385 of 934

Commands

Name Description

Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Output.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

MERSENNE_TWISTER Note
optional Cell and random selection methods only.
The random number generator in Analytics uses the Mersenne-Twister algorithm.
If you omit MERSENNE_TWISTER, the default Analytics algorithm is used.
Note
You should only use the default Analytics algorithm if you require back-
ward compatibility with Analytics scripts or sampling results created prior
to Analytics version 12.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 386 of 934

Commands

Examples
Draw a record sample
You are going to use record sampling to estimate the rate of deviation from a prescribed control in an
account containing invoices.
After calculating a statistically valid sample size, you are ready to draw the sample. You are going to use the
random selection method.
The example below:
l Samples the open Analytics table
l Uses the random selection method with a seed value of 123456
l Specifies a sample size of 95 records
l Includes only specified fields in the output table
l Specifies that the random number generator in Analytics uses the Mersenne-Twister algorithm

SAMPLE ON RECORD RANDOM 123456 NUMBER 95 FIELDS RefNum CustNum Amount Date
Type TO "Ar_record_sample" OPEN MERSENNE_TWISTER

Remarks
Note
For more information about how this command works, see the Analytics Help.

Syntax
Note
The syntax does not include filtering (IF statements) or scope parameters because apply-
ing these options compromises the validity of a sample.

Fixed interval selection method

SAMPLE <ON> mus_numeric_field INTERVAL interval_value <FIXED initial_value> <CUTOFF top_
stratum_cutoff_value> <SUBSAMPLE> <NOREPLACEMENT> {RECORD|FIELDS field_name
< ...n>} TO table_name <OPEN> <APPEND> <LOCAL>

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 387 of 934

Commands

Cell selection method

SAMPLE <ON> mus_numeric_field CELL INTERVAL interval_value <CUTOFF top_stratum_cutoff_
value> <RANDOM seed_value> <SUBSAMPLE> <NOREPLACEMENT> {RECORD|FIELDS
field_name <...n>} TO table_name <OPEN> <APPEND> <MERSENNE_TWISTER> <LOCAL>

Random selection method

SAMPLE <ON> mus_numeric_field NUMBER sample_size POPULATION absolute_value
<RANDOM seed_value> <SUBSAMPLE> <NOREPLACEMENT> <ORDER> {RECORD|FIELDS
field_name <...n>} TO table_name <OPEN> <APPEND> <MERSENNE_TWISTER> <LOCAL>

Parameters
Note
Do not include thousands separators when you specify values.

Name Description

ON mus_numeric_field Use monetary unit sampling (MUS).

mus_numeric_field is the numeric field or expression to use as the basis for the
sampling.

INTERVAL interval_value INTERVAL interval_value FIXED initial_value

FIXED initial_value | CELL
INTERVAL interval_value | Use the fixed interval selection method.
NUMBER sample_size
An initial monetary unit is selected and all subsequent selections are a fixed interval or
POPULATION absolute_
distance apart – for example, every 5000th monetary unit after the initial selection.
value
o INTERVAL interval_value – specify the interval value that was generated by cal-
culating the sample size
o FIXED initial_value – specify the initial monetary unit selected
If you specify an initial_value of zero ('0'), or omit FIXED, Analytics randomly selects
the initial monetary unit.

CELL INTERVAL interval_value

Use the cell selection method.
The data set is divided into multiple equal-sized cells or groups, and one monetary unit
is randomly selected from each cell.
The interval_value dictates the size of each cell. Specify the interval value that was gen-
erated by calculating the sample size.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 388 of 934

Commands

Name Description

NUMBER sample_size POPULATION absolute_value

Use the random selection method.
All monetary units are randomly selected from the entire data set.
o NUMBER sample_size – specify the sample size that was generated by calculating
the sample size
o POPULATION absolute_value – specify the total absolute value of mus_numeric_
field, which is the population from which the sample will be selected

CUTOFF top_stratum_ Note

cutoff_value
Fixed interval and cell selection methods only.
optional
A top stratum cutoff value.
Amounts in the mus_numeric_field greater than or equal to the cutoff value are auto-
matically selected and included in the sample.
If you omit CUTOFF, a default cutoff value equal to the interval_value is used.

RANDOM seed_value Note

SUBSAMPLE Note
optional You can only use SUBSAMPLE when specify FIELDS.
Adds the SUBSAMPLE field to the output results.
If each amount in a sample field represents a total of several separate transactions, and
you want to perform audit procedures on only one transaction from each sampled total
amount, you can use the values in the SUBSAMPLE field to randomly select the indi-
vidual transactions.
For more information, see Performing monetary unit sampling.

NOREPLACEMENT The same record is not selected more than once. As a result, the sample may contain
fewer records than calculated by the SIZE command.
optional
If NOREPLACEMENT is omitted, or if you specify REPLACEMENT, records can be
selected more than once.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 389 of 934

Commands

Name Description

TO table_name The location to send the results of the command to:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 390 of 934

Commands

Name Description

Note
You should only use the default Analytics algorithm if you require back-
ward compatibility with Analytics scripts or sampling results created prior
to Analytics version 12.

Examples
Draw a monetary unit sample
You are going to use monetary unit sampling to estimate the total amount of monetary misstatement in an
account containing invoices.
After calculating a statistically valid sample size, you are ready to draw the sample. You are going to use the
fixed interval selection method.
The example below:
l Samples the open Analytics table based on a transaction amount field
l Uses the fixed interval selection method with an interval value of $6,283.33
l Specifies that the first record selected contains the 100,000th monetary unit (the number of cents in
$1,000)
l Uses a top stratum cutoff of $5,000
l Includes the entire record in the output table

SAMPLE ON Amount INTERVAL 6283.33 FIXED 1000.00 CUTOFF 5000.00 RECORD TO "Ar_mon-
etary_unit_sample" OPEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 391 of 934

Commands

SAVE command
Copies an Analytics table and saves it with a different name, or saves an Analytics project.

Syntax
To create a copy of an Analytics table and save it with a different name:

SAVE new_table FORMAT ACL_table

To save changes to the current project:

SAVE

Parameters
Name Description

new_table The name of the new Analytics table to create and save.
Note
Table names are limited to 64 alphanumeric characters. The name can
include the underscore character ( _ ), but no other special characters, or
any spaces. The name cannot start with a number.

FORMAT ACL_table The name of the existing Analytics table. Use the name of the table layout, not the name
of an associated data file.

Examples
Creating a new table based on an existing one
You create a new table called Payables_March based on the existing table Payables_master. Pay-
ables_March can then be linked to the March payables data file:

SAVE Payables_March FORMAT Payables_master

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 392 of 934

Commands

Remarks
How it works
SAVE FORMAT produces a result similar to copying and pasting an Analytics table in the Overview tab in
the Navigator. A new Analytics table is created and associated to the same data file or data source as the
original table.
If required, you can link the newly created table to a different data source.

Using SAVE to avoid prompts

At certain points, Analytics prompts you to save changes to the current project. To avoid interruptions in the
execution of scripts, you can use the SAVE command to save changes before Analytics prompts you.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 393 of 934

Commands

SAVE LAYOUT command

Saves an Analytics table layout to an external table layout file (.layout), or saves table layout metadata to
an Analytics table.
Note
Prior to version 11 of Analytics, external table layout files used an .fmt file extension. You
can still save a table layout file with an .fmt extension by manually specifying the exten-
sion.

Syntax
SAVE LAYOUT {FILE|TABLE} TO {file_name|table_name}

Parameters
Name Description

FILE | TABLE o FILE – save an Analytics table layout to an external table layout file (.layout)
o TABLE – save table layout metadata to an Analytics table (.fil)

TO file_name | table_ The name of the output file, and the output location:
name o filename – the name of the .layout file
Specify the filename as a quoted string. For example: TO "Ap_Trans.layout".
The .layout file extension is used by default, so specifying it is optional.
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Ap_Trans.layout"
l TO "Table Layouts\Ap_Trans.layout"
Note
Limit the table layout name to 64 alphanumeric characters, not includ-
ing the .layout extension, to ensure that the name is not truncated
when the table layout is imported back into Analytics.
The name can include the underscore character ( _ ), but no other
special characters, or any spaces. The name cannot start with a num-
ber.
o table_name –the name of the Analytics table and .fil file
Specify the table_name as a quoted string. For example: TO "Ap_Trans_layout_
metadata.fil".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 394 of 934

Commands

Name Description

The .fil file extension is used by default, so specifying it is optional.

By default, the table data file (.fil) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Ap_Trans_layout_metadata.fil"
l TO "Layout Metadata\Ap_Trans_layout_metadata.fil"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character (
_ ), but no other special characters, or any spaces. The name cannot
start with a number.

Examples
Saving a table layout to an external table layout file (.layout)
The following examples save the table layout used by the open table to an external table layout file called
Ap_Trans.layout:
Here, the table layout file is saved in the Analytics project folder:

SAVE LAYOUT FILE TO Ap_Trans.layout

Here, the table layout file is saved in the specified folder:

SAVE LAYOUT FILE TO "C:\ACL_DATA\AP Audit 2013\Ap_Trans.layout"

Saving a copy of table layout metadata to a new Analytics table

The following examples save a copy of the metadata in the table layout used by the open table to a new Ana-
lytics table called Ap_Trans_layout_metadata.
Here, the new Analytics table is saved in the Analytics project folder:

SAVE LAYOUT TABLE TO Ap_Trans_layout_metadata

Here, the new Analytics table is saved in the specified folder:

SAVE LAYOUT TABLE TO "C:\ACL_DATA\AP Audit 2013\Ap_Trans_layout_metadata"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 395 of 934

Commands

Remarks
SAVE LAYOUT file vs table
The SAVE LAYOUT command is used for two different purposes:
l FILE – saves the table layout of the open Analytics table to an external table layout file with a .lay-
out extension
l TABLE – extracts the metadata from the table layout of the open Analytics table and saves it to a
new Analytics table

SAVE LAYOUT FILE

How it works
SAVE LAYOUT FILE saves the table layout of the open Analytics table to an external table layout file with
a .layout extension.
A table layout contains metadata that provides a structured interpretation of the raw data in an associated
source data file. A table layout does not contain any source data itself.

When to use SAVE LAYOUT FILE

Saving a table layout as a .layout file makes the table layout and its metadata portable and reusable.
The .layout file can be imported into any Analytics project and associated with a matching source data file.
The data elements in the source data file must match the field definitions specified by the table layout
metadata.
For example, you could save the table layout of a transactions file from March, and associate it with a
source data file containing transactions from April, assuming the structure of the data in the March and
April source data files is identical. Used in this manner, .layout files can save you the labor of creating a
new table layout from scratch.
For more information about the structure of Analytics tables, see the Analytics Help.

SAVE LAYOUT TABLE

How it works
SAVE LAYOUT TABLE extracts the metadata from the table layout of the open Analytics table and saves
it to a new Analytics table.
The new table is not the table layout itself, but rather a regular Analytics table that contains a summary of
the table layout metadata for the original table. Having access to this summary in an Analytics script can
allow you to make decisions in the script based on the information.
For each field in the original table, the following pieces of table layout metadata are extracted into the new
table.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 396 of 934

Commands

Note
The field names in the new table are always generated in English regardless of which loc-
alized version of Analytics you are using.

Field name in new table Table layout metadata

field_name The name of the field

data_type The data type of the field

category The data category of the field

start_position The start position of the field

field_length The length of the field

decimals The number of decimal places in the field (numeric fields only)

format The format of the field (datetime and numeric fields only)

alternate_title The alternate column title of the field

column_width The width of the column in the view

Additional details

Computed fields are included in the extracted metadata, but the expression used by the
computed field, and any conditions, are not recorded. Start position, field length, and
Computed fields decimal places are also not recorded for computed fields.

Related fields Related fields are not included because they are not part of the table layout.

Field-level filters Field-level filters and field notes are not included.
Field notes

Alternate column title The values recorded for alternate column title and column width are the ones specified in
the table layout, not the view-level values that can be specified for columns.
Column width

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 397 of 934

Commands

SAVE LOG command

Saves the entire command log, or the log entries for the current Analytics session, to an external file.

Syntax
SAVE LOG <SESSION> AS filename {<ASCII>|HTML} <OK>

Parameters
Name Description

SESSION Only log entries for the current Analytics session are saved.
optional

AS filename The name of the output file.

Specify the filename as a quoted string. For example: AS "Command Log". You can spe-
cify a file extension (.txt, or .htm or .html), but it is not required.
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
o AS "C:\Command Log.TXT"
o AS "Results\Command Log.TXT"

ASCII | HTML The format of the output file:

o ASCII (or no keyword) – a plain text ASCII file.
o HTML – an HTML file.

OK If a file with the same name as filename already exists, it is overwritten without con-
firmation.
optional

Examples
Save the command log from payables analysis
You have performed data analysis on the March payables file and you want to save the associated com-
mand log as part of your working papers.
The following example saves the entries from the current Analytics session to an HTML file. If a file with the
same name already exists it is overwritten without confirmation:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 398 of 934

Commands

SAVE LOG SESSION AS "C:\Payables_March_Log.htm" HTML OK

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 399 of 934

Commands

SAVE TABLELIST command

Saves a list of all tables in an Analytics project to an Analytics table or a CSV file.

Syntax
SAVE TABLELIST {FILE|TABLE} TO {table_name|file_name}

Parameters
Name Description

FILE | TABLE o FILE – saves the table list to a CSV file (.csv)

o TABLE – saves the table list to an Analytics table

TO table_name | file_ The location to save the table list:

name o table_name – the name of the output Analytics table and the associated .fil file when
using TABLE
The .fil file extension is used by default and does not need to be specified. The table
is saved in the same folder as the Analytics project, and cannot be saved in any
other folder.
Note
Analytics table names are limited to 64 alphanumeric characters. The
name can include the underscore character ( _ ), but no other special
characters, or any spaces. The name cannot start with a number.
o file_name – the name of the .csv file when using FILE
The .csv file extension is used by default and does not need to be specified. You can
specify an absolute or relative path to save the CSV file in an existing folder other
than the folder containing the Analytics project. If you specify a relative path, it is rel-
ative to the Analytics working directory.
You must specify values as quoted strings if they contain any spaces.

Examples
Creating a new table
You create a new table in the Analytics project called Table_list_complete:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 400 of 934

Commands

SAVE TABLELIST TABLE TO Table_list_complete

Creating a CSV file

You create a new CSV file in the C:\ACL Data folder called Table_list_complete.csv:

SAVE TABLELIST FILE TO "C:\ACL Data\Table_list_complete"

Remarks
Output columns
The output Analytics table or CSV file contains three columns:
l table_name – the name of the Analytics table layout
l type – an indication whether the Analytics table is a local table or a server table
l Data_file_Path – the full path to the source data file

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 401 of 934

Commands

SAVE WORKSPACE command

Creates and saves a workspace.

Syntax
SAVE WORKSPACE workspace_name {field_name <...n>}

Parameters
Name Description

workspace_name The name of the workspace to create and add to the current Analytics project.

field_name <...n> The name of the field to add to the workspace. You can include multiple field names sep-
arated by spaces.

Example
Activating a workspace
You create a workspace called Inventory_margin with two computed fields from the Metaphor_Invent-
ory_2002 table. Then you activate the workspace so that the fields are available in the Inventory table:

OPEN Metaphor_Inventory_2002
SAVE WORKSPACE Inventory_margin Gross_unit_margin Percent_unit_margin
OPEN Inventory
ACTIVATE WORKSPACE Inventory_margin OK

Remarks
Field names used to create computed fields must match
The names of any fields used in expressions that create a computed field that is saved in a workspace
must match the names of the fields in the table that uses the workspace.
For example, if a workspace contains the computed field Value=Sale_price*Quantity, the active table
must also contain fields called Sale_price and Quantity .

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 402 of 934

Commands

SEEK command
Searches an indexed character field for the first value that matches the specified character expression or
character string.

Syntax
SEEK search_expression

Parameters
Name Description

search_expression The character expression to search for.

You can use any valid character expression, character variable, or quoted string. search_
expression is case-sensitive, and can include leading spaces, which are treated like char-
acters.

Examples
Locate the first value in a field that matches a character variable
The Card_Number field has been defined as a character field and is indexed in ascending order.
The example below locates the first value in the field that exactly matches, or starts with, the value contained
in the v_card_num variable.

INDEX ON Card_Number TO "CardNum" OPEN

SET INDEX TO "CardNum"
SEEK v_card_num

Locate the first value in a field that matches a character string

The Card_Number field has been defined as a character field and is indexed in ascending order.
The example below locates the first value in the field that exactly matches, or starts with, the character literal
"AB-123":

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 403 of 934

Commands

INDEX ON Card_Number TO "CardNum" OPEN

SET INDEX TO "CardNum"
SEEK "AB-123"

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
Use the SEEK command to move directly to the first record in a table containing the specified search_
expression in the indexed character field.
l If the search_expression is found – the first matching record in the table is selected.
l If the search expression is not found – the message "No index matched key" is displayed, and the
table is positioned at the first record with a greater value than the search expression.
If there are no values in the indexed field greater than the search expression, the table is positioned
at the first record.

Index required
To use SEEK to search a character field, you must first index the field in ascending order. If multiple char-
acter fields are indexed in ascending order, only the first field specified in the index is searched.
SEEK cannot be used to search non-character index fields, or character fields indexed in descending
order.

Partial matching supported

Partial matching is supported. The search expression can be contained by a longer value in the indexed
field. However, the search expression must appear at the start of the field to constitute a match.
The SEEK command is not affected by the Exact Character Comparisons option (SET EXACT
ON/OFF).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 404 of 934

Commands

SEQUENCE command
Determines if one or more fields in an Analytics table are in sequential order, and identifies out-of-sequence
items.

Syntax
SEQUENCE <ON> {<FIELDS> field <D> <...n>|<FIELDS> ALL} <UNFORMATTED>
<ERRORLIMIT n> <IF test> <WHILE test> <FIRST range|NEXT range> <TO
{SCREEN|filename|PRINT}> <APPEND> <HEADER header_text> <FOOTER footer_text>
<PRESORT> <LOCAL> <ISOLOCALE locale_code>

Parameters
Name Description

ON FIELDS field D <...n> The fields or expressions to check for sequential order. Specify ALL to check all fields in
| FIELDS ALL the Analytics table.
Include D to sort the key field in descending order. The default sort order is ascending.

UNFORMATTED Suppresses page headings and page breaks when the results are output to a file.
optional

ERRORLIMIT n The number of errors allowed before the command is terminated. The default value is 10.
optional

FIRST range | NEXT range The number of records to process:

optional o FIRST – start processing from the first record until the specified number of records is

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 405 of 934

Commands

Name Description

TO SCREEN | filename | The location to send the results of the command to:
PRINT o SCREEN – displays the results in the Analytics display area
optional o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"
o PRINT – sends the results to the default printer

HEADER header_text The text to insert at the top of each page of a report.
optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

PRESORT Sorts the table on the key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.

LOCAL Saves the output file in the same location as the Analytics project.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 406 of 934

Commands

Name Description

Note
Applicable only when running the command against a server table with
an output file that is an Analytics table.

ISOLOCALE locale_code Note

Analytics output variables

Name Contains

WRITEn The total number of sequence errors identified by the command.

Examples
Testing for out of sequence employee IDs and hire dates
You write any sequence errors identified in the EmployeeID and HireDate fields to a text file:

SEQUENCE ON EmployeeID HireDate ERRORLIMIT 10 TO "SequenceErrors.txt"

Remarks
Using SEQUENCE inside a GROUP
If you use SEQUENCE inside a GROUP command, the command executes to avoid interfering with the pro-
cessing of the group, but no further data sequence errors are reported.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 407 of 934

Commands

SET command
Sets a configurable Analytics option.
Note
The SET command sets an Analytics option for the duration of the Analytics session only.
This behavior applies whether you use the SET command in the Analytics command line
or in an Analytics script.
To set Analytics options so that they persist between Analytics sessions, you must use the
Options dialog box. For more information, see Configuring ACL options.

Syntax
Syntax Examples and remarks

SET BEEP value

SET BEEP 2

Specifies the number of beeps to sound when command processing is completed.

The value parameter must be between 1 and 255.

SET CENTURY value

SET CENTURY 40

Specifies the start-of-century year for two-digit years.

The value parameter must be from 0 to 99.
Setting the start-of-century value to 40 means that two-digit years 40 to 99 are inter-
preted as 1940 to 1999, and two-digit years 00 to 39 are interpreted as 2000 to 2039.

SET CLEAN {ON | OFF}

SET CLEAN ON

When this option is turned on, Analytics replaces invalid character data with blanks and
invalid numeric data with zeros.

SET DATE <TO> {0 | 1 | 2 |

string} SET DATE "YYYY/MM/DD"

Specifies how Analytics displays dates, and the date portion of datetimes, in views,
reports, and exported files.
o SET DATE 0 sets the date to MM/DD/YYYY format
o SET DATE 1 sets the date to MM/DD/YY format
o SET DATE 2 sets the date to DD/MM/YY format
o SET DATE "<string>" sets the date to the custom format you specify

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 408 of 934

Commands

Syntax Examples and remarks

When using the SET DATE command to specify custom date formats, you must use
'D' for Day, 'M' for Month, and 'Y' for Year, even if you have specified different date
format characters in the Options dialog box. For example:

SET DATE "DD MMM YYYY"

SET DELETE_FILE {ON |

OFF} SET DELETE_FILE ON

Default setting: OFF
Specify ON to automatically delete the associated data file when you delete a table lay-
out.
Specify OFF to prevent the associated data file from being deleted when you delete a
table layout.
You must include the underscore ( _ ) in DELETE_FILE.
Specifying SET DELETE_FILE, without any parameter, in the command line displays
whether DELETE_FILE is currently on or off.
Caution
Use caution when turning this option on. It may be an original data file
that is deleted along with the table.
Data files are deleted outright. They are not sent to the Windows
Recycle Bin.

SET DESIGNATION value

SET DESIGNATION "Produced by ABC Corporation"

The value parameter is a quoted string that specifies the label to display at the top of
each printed page.

SET ECHO {ON | NONE}

SET ECHO NONE
COM Commands and results in scripts excluded from log.
SET ECHO ON

Specify NONE to stop writing commands and results in scripts to the Analytics com-
mand log. Specify ON to resume logging.
The SET ECHO command applies only to the logging of commands and results in
scripts. Commands performed through the user interface or issued from the command
line, and any results they produce, are always logged, regardless of how ECHO is set.
You can issue the SET ECHO NONE/ON command in a script or from the command
line, but regardless of where you issue the command, it affects only the logging of com-
mands and results in scripts.
Specifying SET ECHO, without any parameter, in the command line displays whether
the logging of commands and results in scripts is currently on or off.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 409 of 934

Commands

Syntax Examples and remarks

SET EXACT {ON | OFF}

SET EXACT ON

Default setting: OFF
Controls how Analytics compares character fields, expressions, or literal values.
Note
Blank spaces are treated like characters.
o SET EXACT is OFF – Analytics uses the shorter string when comparing two strings
of unequal length. The comparison starts with the leftmost characters and moves to
the right.
For example, "AB" is equal to "AB", and it is also considered equal to "ABC".
o SET EXACT is ON – comparison strings must be exactly identical to be a match.
When comparing two strings of unequal length, Analytics pads the shorter string with
trailing blank spaces to match the length of the longer string.
For example, "AB" is equal to "AB", but it is not considered equal to "ABC".
For more examples illustrating SET EXACT, see "Exact Character Comparisons" in
Table tab (Options dialog box).
You can use the ALLTRIM( ) function to remove leading and trailing blank spaces and
ensure that only text characters and internal spaces are compared.
For example: ALLTRIM(" AB") = ALLTRIM("AB") is True when the values are wrapped
with ALLTRIM( ), but False otherwise.
Some Analytics commands and functions are affected by SET EXACT and some are
not:

Affected Not affected

o LOCATE command o JOIN command

o MATCH( ) function o DEFINE RELATION command
o BETWEEN( ) function o FIND( ) function
o FINDMULTI( ) function

SET FILTER <TO> {test | fil-

ter_name} SET FILTER TO ProdNo = "070104347"

SET FILTER TO ProdNoFilter

Creates a global filter (view filter) on the open table, and specifies either a logical test,
or the name of an existing saved filter.
Specifying SET FILTER, without any parameter, removes any filter from the open table.

SET FOLDER folder path Specifies the Analytics project folder in the Overview tab for command output. The
default output folder is the folder containing the active table.
This a DOS-style path using the format /foldername/subfoldername, in which the initial
slash (/) indicates the root level in the Overview tab. You must specify a full file path.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 410 of 934

Commands

Syntax Examples and remarks

o SET FOLDER /Tables/Results sets the output folder to the Results subfolder. If the
Results subfolder does not exist, it is created.
o SET FOLDER / sets the output folder to the root level in the Overview tab
o SET FOLDER sets the output folder to the default (the folder containing the active
table)
The output folder remains as whatever you set it – until you reset it, or close the project.
Upon opening the project, the output folder reverts to the default of the active table
folder.

SET FORMAT {ON | OFF}

SET FORMAT ON

Default setting: OFF
If you use the ON parameter, Analytics automatically displays the current table layout
and computed field definitions when you open a new table. The results appear in the
command log.

SET FUZZYGROUPSIZE
<TO> num SET FUZZYGROUPSIZE TO 10

Specifies the maximum number of items that can appear in a fuzzy duplicate group in
the output results. The num parameter cannot be less than 2 or greater than 100. The
default size is 20. The specified size remains in effect for the duration of the Analytics
session.

SET GRAPH type

SET GRAPH LINE

Specifies the graph type to use for all subsequently generated graphs. The commands
run must be compatible with the specified graph type. For example, the BENFORD com-
mand cannot produce a PIE2D or PIE3D chart. If an incompatible graph type is spe-
cified the default graph type is used (BAR3D).
The type parameter must be one of the following:
o PIE2D
o PIE3D
o BAR2D
o BAR3D – This is the default graph type.
o STACKED2D
o STACKED3D
o LAYERED
o LINE
o BENFORD – Combines 2D bar graph and 2D line graph.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 411 of 934

Commands

Syntax Examples and remarks

SET HISTORY <TO> value

SET HISTORY TO 50

Specifies the maximum number of table history entries to retain. The value parameter
must be between 1 and 100.

SET INDEX <TO> value

SET INDEX TO "CustomerCode.INX"

Specifies the index to apply to the active table.

SET LEARN <TO> script

SET LEARN TO InventoryRec

Specifies the name of the script file that the Script Recorder uses to record commands.

SET LOG <TO> {file | OFF}

SET LOG TO "analysis.log"

SET LOG OFF

The first command switches logging to the specified log. If the specified log does not
exist, it is created.
The second command restores logging to the original Analytics command log.
Note
The maximum length of an Analytics project path and log name is 259
characters, which includes the file path, the log name, and the file exten-
sion (.log).

SET LOOP <TO> num

SET LOOP TO 20

Specifies the maximum number of loops that can be executed by the LOOP command
before the command is terminated.
The num range is 0 to 32767, where 0 turns off loop testing.

SET MARGIN side <TO>

value SET MARGIN TOP TO 100

Specify LEFT, RIGHT, TOP, or BOTTOM for the side parameter. If you want to change
the margin on all sides, you need to specify each margin with a separate SET MARGIN
command. Specifying a value of 100 creates a margin of 1 inch.

SET MATH <TO> {FIRST |

LAST | MIN | MAX} SET MATH TO MIN

Default setting: MAX

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 412 of 934

Commands

Syntax Examples and remarks

Specifies how decimal precision works when two operands are evaluated in a numeric
expression.
o FIRST – use the number of decimal places of the first operand in a pair of operands
o LAST – use the number of decimal places of the last operand in a pair of operands
o MIN – use the minimum number of decimal places in a pair of operands
o MAX – use the maximum number of decimal places in a pair of operands
In multi-operand expressions, the SET MATH setting works on a pairwise basis, apply-
ing the specified setting to each pair of operands, rounding as necessary, as they are
evaluated in the standard mathematical order (BOMDAS).
If the SET MATH setting reduces the number of decimal places in a result, the result is
rounded, not truncated.
For more information, see Controlling rounding and decimal precision in numeric
expressions.
Note
You cannot use SET MATH while an Analytics table is open.

SET MONTHS <TO> string Specifies the default three-character abbreviations for month names. The string para-
meter is the list of month abbreviations separated by commas.

SET NOTIFYFAILSTOP
{ON | OFF} SET NOTIFYFAILSTOP ON

Default setting: OFF
o NOTIFYFAILSTOP is OFF – Analytics allows a script to continue even if a NOTIFY
command in the script fails.
o NOTIFYFAILSTOP is ON – Analytics stops processing a script, and writes a mes-
sage to the log, if a NOTIFY command in the script fails. The script stops after the ini-
tial failure, or after the specified number of NOTIFYRETRYATTEMPTS, if none of the
attempts are successful.

SET
NOTIFYRETRYATTEMPTS SET NOTIFYRETRYATTEMPTS TO 10
<TO> num
Specifies the number of times the NOTIFY command will attempt to send an email if the
initial attempt is unsuccessful. Enter a number from 0 to 255. If you enter 0, no addi-
tional attempts are made after an initial failure. The default is 5.
One possible reason for the NOTIFY command failing to send an email is that the email
server is unavailable.

SET
NOTIFYRETRYINTERVAL SET NOTIFYRETRYINTERVAL TO 30
<TO> seconds
Specifies the amount of time in seconds between NOTIFYRETRYATTEMPTS. Enter a
number from 1 to 255. The default is 10 seconds.

SET ORDER <TO> values Specifies the sort sequence for character fields. The values parameter lists all of the
character for the selected sort order.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 413 of 934

Commands

Syntax Examples and remarks

SET OVERFLOW {ON |

OFF} SET OVERFLOW OFF

Default setting: ON
If OFF is specified Analytics does not stop processing when an overflow error occurs.

SET PASSWORD num

<TO> string SET PASSWORD 1 TO "password123"

Used to create a password definition, and specify a password value, for unattended
script execution.
The num parameter uniquely identifies the password definition and must be a value
from 1 to 10. Specify the password value as a quoted string.

SET PERIODS <TO> value

<,...n> SET PERIODS TO "0,30,90,180,10000"

Specifies the default aging periods used by the AGE command.

SET PICTURE format

SET PICTURE "(9,999,999.99)"

Specifies the default formatting for numeric values.

SET READAHEAD <TO> Specifies the size of the data block read. You should only change this setting if you are
size advised to do so by Support.

SET RETRY <TO> num

SET RETRY TO 50
SET RETRYIMPORT <TO>
num
Specifies the number of times Analytics attempts to import or export data if the initial
attempt is unsuccessful. Enter a number from 0 to 255. If you enter 0, no additional
attempts are made after an initial failure. The default is 0.
There is no waiting period between retry attempts. Each successive attempt is made
immediately after a preceding failure.
The ability to specify retry attempts is useful when connecting to databases or cloud
data services, which can be temporarily unavailable.
Applies to the following commands:
o ACCESSDATA
o IMPORT GRCPROJECT
o IMPORT GRCRESULTS
o IMPORT SAP
o RETRIEVE
o REFRESH
(for tables initially created using ACCESSDATA or IMPORT SAP only)
o EXPORT . . . ACLGRC
(export to HighBond Results)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 414 of 934

Commands

Syntax Examples and remarks

Note
SET RETRYIMPORT is retained for backward compatibility.
SET RETRYIMPORT and SET RETRY perform identical actions.

SET SAFETY {ON | OFF}

SET SAFETY OFF

Specify ON to display a confirmation dialog box when overwriting any of the following:
o fields in table layouts
o Analytics tables
o files, including Analytics data files (.fil)
Specify OFF to prevent the dialog box from being displayed.
Specifying SET SAFETY, without any parameter, in the command line displays whether
SAFETY is currently on or off.

SET SEPARATORS <TO>

values SET SEPARATORS TO ".,,"

Specifies the default decimal, thousands, and list separators used by Analytics. The
SET SEPARATORS values must be three valid separator characters in the following
order:
o decimal (period, comma, or space)
o thousands (period, comma, or space)
o list (semi-colon, comma, or space)
Among the three separators, the decimal separator must be unique. You must specify
all three separators when you use the command. The list separator is used primarily to
separate function parameters.

SET SESSION <session_

name> SET SESSION

SET SESSION "Analysis"

Creates a new session in the Analytics command log. The session is identified by the
current timestamp.
The optional session_name allows you to add up to 30 characters of additional identi-
fying information. Quotation marks are permitted but not required.

SET SORTMEMORY num

SET SORTMEMORY 800

Specifies the maximum amount of memory allocated for sorting and indexing pro-
cesses. The num parameter must be a value from 0 to 2000 megabytes (MB), to be
entered in 20MB increments. If the sort memory is set to 0, Analytics uses the memory
currently available.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 415 of 934

Commands

Syntax Examples and remarks

SET SUPPRESSTIME {ON

| OFF} SET SUPPRESSTIME ON

Default setting: OFF
Only for use when defining an Analytics table that uses an ODBC data source (IMPORT
ODBC command), or direct database access (DEFINE TABLE DB command).
If you use the ON parameter, when defining the table Analytics suppresses the time por-
tion of datetime values. For example, 20141231 235959 is read, displayed in views,
and subsequently processed as 20141231.
Including this command in a pre-datetime Analytics script (pre v.10.0) that assumes the
time portion of datetime data will be truncated allows the script to run in the datetime-
enabled version of Analytics.
Analytics suppresses the time portion by using only the date portion of the datetime
format. The time data is still present in the .fil file or the database table. If required, you
can redefine the field or define a new field to include the time portion of the data.
If SET SUPPRESSTIME = OFF, Analytics tables defined using ODBC or direct database
access include full datetime values.
You can issue the SET SUPPRESSTIME ON/OFF command in a script or from the com-
mand line.
Specifying SET SUPPRESSTIME, without any parameter, in the command line displays
whether the suppression of the time portion of datetime data is currently on or off.

SET SUPPRESSXML {ON

| OFF} SET SUPPRESSXML ON

Default setting: OFF
Specifies that command output is in plain text rather than formatted text.

SET TEST {ON | OFF}

SET TEST ON

Specifies whether the results of IF, WHILE, FOR, and NEXT tests associated with
GROUP commands should be recorded in the log.

SET TIME <TO> string

SET TIME "hh:mm:ss PM"

Specifies how Analytics displays the time portion of datetimes, and standalone time val-
ues, in views, reports, and exported files.
When using the SET TIME command to specify time formats, you must use 'h' for Hour,
'm' for Minute, and 's' for Second, even if you have specified different time format char-
acters in the Options dialog box. For example:

SET TIME TO "hh:mm"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 416 of 934

Commands

Syntax Examples and remarks

SET UTCZONE {ON | OFF}

SET UTCZONE OFF

Default setting: ON
o UTCZONE is ON – Analytics changes the display of local times with a UTC offset to
the UTC equivalent of the local time. (UTC is Coordinated Universal Time, the time
at zero degrees longitude.)
o UTCZONE is OFF – Analytics displays local times with a UTC offset without con-
verting them to UTC.
For example:
o 01 Jan 2015 04:59:59 (SET UTCZONE ON)
o 31 Dec 2014 23:59:59-05:00 (SET UTCZONE OFF)
Conversion of local time to UTC is for display purposes only, and does not affect the
source data. You can change back and forth between the two different display modes
whenever you want to.

SET VERIFY {ON | OFF |

BLANK} SET VERIFY ON

When ON is specified, Analytics automatically checks whether the contents of a data

field correspond to the field's data type in the table layout whenever a table is opened.
When BLANK is specified, Analytics replaces invalid character data with blanks and
invalid numeric data with zeros, in addition to the verification described for the ON para-
meter.

SET WIDTH <TO> char-

acters SET WIDTH TO 20

Specifies the default display width in characters for numeric computed fields or ad hoc
numeric expressions when Analytics cannot determine the maximum width.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 417 of 934

Commands

SIZE command
Calculates a statistically valid sample size, and sample interval, for record sampling or monetary unit
sampling.
Record samplingMonetary unit sampling

Syntax
SIZE RECORD CONFIDENCE confidence_level POPULATION population_size PRECISION tol-
erable_rate <ERRORLIMIT expected_rate> <TO {SCREEN|filename}>

Parameters
Note
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

RECORD Calculate sample size for a record sample.

ATTRIBUTE is a deprecated parameter that does the same thing as RECORD.

CONFIDENCE con- The desired confidence level that the resulting sample is representative of the entire
fidence_level population.
For example, specifying 95 means that you want to be confident that 95% of the time the
sample will in fact be representative. Confidence is the complement of "sampling risk". A
95% confidence level is the same as a 5% sampling risk.

POPULATION population_ The number of records in the table you are sampling.
size

PRECISION tolerable_rate The tolerable deviation rate, which is the maximum rate of deviation from a prescribed
control that can occur and you still consider the control effective.
For example, specifying 5 means that the deviation rate must be greater than 5% for you
to consider the control not effective.

ERRORLIMIT expected_ The expected population deviation rate. This is the rate of deviation from a prescribed
rate control that you expect to find.
optional For example, specifying 1 means that you expect the deviation rate to be 1%.
If you omit this parameter, an expected population deviation rate of 0% is used.

TO SCREEN | filename The location to send the results of the command to:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 418 of 934

Commands

Name Description

o SCREEN – displays the results in the Analytics display area

o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing
folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"

Analytics output variables

Name Contains

SAMPINTn The required sample interval calculated by the command.

SAMPSIZEn The required sample size calculated by the command.

Examples
Calculate the required size and interval for a record sample
You have decided to use record sampling to estimate the rate of deviation from a prescribed control in an
account containing invoices.
Before drawing the sample, you must first calculate the statistically valid sample size and sample interval.
You want to be confident that 95% of the time the sample drawn by Analytics will be representative of the
population as a whole.
Using your specified confidence level, the example below calculates a sample size of 95, and a sample inter-
val value of 8.12, to use when drawing a record sample:

SIZE RECORD CONFIDENCE 95 POPULATION 772 PRECISION 5 ERRORLIMIT 1 TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 419 of 934

Commands

Syntax
SIZE MONETARY CONFIDENCE confidence_level POPULATION population_size MATERIALITY
tolerable_misstatement <ERRORLIMIT expected_misstatement> <TO {SCREEN|filename}>

Parameters
Note
Do not include thousands separators, or percentage signs, when you specify values.

Name Description

MONETARY Calculate sample size for a monetary unit sample.

POPULATION population_ The total absolute value of the numeric sample field.
size

MATERIALITY tolerable_ The tolerable misstatement, which is the maximum total amount of misstatement that
misstatement can occur in the sample field without being considered a material misstatement.
For example, specifying 29000 means that the total amount of misstatement must be
greater than $29,000 to be considered a material misstatement.

ERRORLIMIT expected_ The expected misstatement. This is the total amount of misstatement that you expect the
misstatement sample field to contain.
optional For example, specifying 5800 means that you expect the total amount of misstatement
to be $5,800.
If you omit this parameter, an expected misstatement of $0.00 is used.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 420 of 934

Commands

Name Description

l TO "C:\Output.TXT"
l TO "Results\Output.TXT"

Analytics output variables

Name Contains

SAMPINTn The required sample interval calculated by the command.

SAMPSIZEn The required sample size calculated by the command.

Examples
Calculate the required size and interval for a monetary unit sample
You have decided to use monetary unit sampling to estimate the total amount of monetary misstatement in
an account containing invoices.
Before drawing the sample, you must first calculate the statistically valid sample size and sample interval.
You want to be confident that 95% of the time the sample drawn by Analytics will be representative of the
population as a whole.
Using your specified confidence level, the example below calculates a sample size of 93, and a sample inter-
val value of 6,283.33, to use when drawing a monetary unit sample:

SIZE MONETARY CONFIDENCE 95 POPULATION 585674.41 MATERIALITY 29000 ERRORLIMIT

5800 TO SCREEN

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 421 of 934

Commands

SORT command
Sorts records in an Analytics table into an ascending or descending sequential order, based on a specified
key field or fields. The results are output to a new, physically reordered Analytics table.

Syntax
SORT ON {key_field <D> <...n>|ALL} <FIELDS field_name <AS display_name> <...n>|FIELDS
ALL> TO tablename <IF test> <WHILE test> <FIRST range|NEXT range> <APPEND> <OPEN>
<ISOLOCALE locale_code>

Parameters
Name Description

ON key_field D <...n> The key field or fields, or the expression, to use for sorting.
| ALL
You can sort by any type of field, including computed fields and ad hoc expressions,
regardless of data type.
o key_field – use the specified field or fields
If you sort by more than one field, you create a nested sort in the output table. The
order of nesting follows the order in which you specify the fields.
Include D to sort the key field in descending order. The default sort order is ascend-
ing.
o ALL – use all fields in the table
If you sort by all the fields in a table you create a nested sort in the output table. The
order of nesting follows the order in which the fields appear in the table layout.
An ascending sort order is the only option for ALL.

FIELDS field_name <...n> | Note

FIELDS ALL
Key fields are automatically included in the output table, and do not
optional need to be specified using FIELDS.
The fields to include in the output:
o FIELDS field_name – use the specified fields
Fields are used in the order that you list them.
Converts computed fields to physical fields of the appropriate data type in the des-
tination table – ASCII or Unicode (depending on the edition of Analytics), ACL (the
native numeric data type), Datetime, or Logical. Populates the physical fields with the
actual computed values.
o FIELDS ALL – use all fields in the table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 422 of 934

Commands

Name Description

Fields are used in the order that they appear in the table layout.
Converts computed fields to physical fields of the appropriate data type in the des-
tination table – ASCII or Unicode (depending on the edition of Analytics), ACL (the
native numeric data type), Datetime, or Logical. Populates the physical fields with the
actual computed values.
o omit FIELDS – the entire record is included in the sorted output table: all fields, and
any undefined portions of the record
Fields are used in the order that they appear in the table layout.
Computed fields are preserved.
Tip
If you need only a portion of the data contained in a record, do not
include all fields, or the entire record, in the sorted output table. Select
only the fields you need, which in most cases speeds up the sorting pro-
cess.

AS display_name Only used when sorting using FIELDS.

optional The display name (alternate column title) for the field in the view in the new Analytics
table. If you want the display name to be the same as the field name, or an existing dis-
play name in the source table, do not use AS.
Specify display_name as a quoted string. Use a semi-colon (;) between words if you
want a line break in the column title.
Note
AS works only when outputting to a new table. If you are appending to
an existing table, the alternate column titles in the existing table take pre-
cedence.

TO table_name The location to send the results of the command to:

IF test A conditional expression that must be true in order to process each record. The com-
mand is executed on only those records that satisfy the condition.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 423 of 934

Commands

Name Description

Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).

FIRST range | NEXT range The number of records to process:

OPEN Open the table and apply the index to the table.
optional

ISOLOCALE locale_code Note

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 424 of 934

Commands

Examples
Sort on a single field, output entire records
You want to sort the records in the sample Inventory table by product number. The sorted records are
extracted to a new Analytics table called Inventory_Product_Number.
Entire records are included in the output table:

SORT ON ProdNo TO "Inventory_Product_Number"

To switch from the default ascending sort order to a descending sort order, you add D after the key field
name:

SORT ON ProdNo D TO "Inventory_Product_Number"

Sort on a single field, output a subset of fields

You want to sort the records in the sample Inventory table by product number. Only the key field and the spe-
cified non-key fields are extracted to a new Analytics table called Inventory_Quantity_on_Hand.
The third non-key field, QtyOH, is given the display name Qty on Hand in the output table:

SORT ON ProdNo FIELDS ProdDesc ProdStat QtyOH AS "Qty on Hand" TO "Inventory_Quantity_on_

Hand"

Sort on a single field, output all fields

You want to sort the records in the sample Inventory table by product number. All fields are extracted to a
new Analytics table called Inventory_Product_Number.
The difference between using FIELDS ALL and outputting the entire record is that FIELDS ALL converts
any computed fields in the source table to physical fields in the output table, and populates the fields with the
actual computed values:

SORT ON ProdNo FIELDS ALL TO "Inventory_Product_Number"

Sort on multiple fields (nested sort)

You want to sort the records in the sample Inventory table by location, then by product class, and then by
product number. The sorted records are extracted to a new Analytics table called Inventory_Location_
Class_Number.

SORT ON Location ProdCls ProdNo TO "Inventory_Location_Class_Number"

Sort using related fields

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 425 of 934

Commands

You want to sort the records in the sample Ap_Trans table by the following fields:
l vendor state (related Vendor table)
l vendor city (related Vendor table)
l vendor number (Ap_Trans table)
All three key fields and the specified non-key fields, including the related field Vendor.Vendor_Name, are
extracted to a new Analytics table called Ap_Trans_State_City :

SORT ON Vendor.Vendor_State Vendor.Vendor_City Vendor_No FIELDS Vendor.Vendor_Name

Invoice_No Invoice_Date Invoice_Amount Prodno Quantity Unit_Cost TO "Ap_Trans_State_City"

Remarks
Note
For more information about how this command works, see the Analytics Help.

Sorting on related fields

You can sort on related fields, and include related fields as non-key fields in a sorted output table. To ref-
erence a related field in the SORT command specify child table name.field name.

Fixed-length vs variable-length data files

The SORT command works on both fixed-length and variable-length data files.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 426 of 934

Commands

STATISTICS command
Calculates statistics for one or more numeric or datetime fields in an Analytics table.

Syntax
STATISTICS <ON> {field <...n>|ALL} <STD> <MODMEDQ> <NUMBER n> <TO
{SCREEN|filename|PRINT}> <IF test> <WHILE test> <FIRST range|NEXT range> <APPEND>

Parameters
Name Description

ON field <...n> | ALL Specify one or more numeric or datetime fields to generate statistics for, or specify ALL to
generate statistics for all numeric and datetime fields in the Analytics table.

STD Calculates the standard deviation of the fields specified, in addition to the other statistics.
optional

MODMEDQ Calculates the mode, median, first quartile, and third quartile values of the fields spe-
cified, in addition to the other statistics.
optional

NUMBER n The number of high and low values to retain during processing. The default value is 5.
optional

IF test A conditional expression that must be true in order to process each record. The command
is executed on only those records that satisfy the condition.
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 427 of 934

Commands

Name Description

Note
The IF parameter is evaluated against only the records remaining in a
table after any scope parameters have been applied (WHILE, FIRST,
NEXT).

FIRST range | NEXT range The number of records to process:

Analytics output variables

Note
If you generate statistics for more than one field in a table, the system-generated output
variables contain values for the first listed field only.

Name Contains

ABSn The absolute value calculated by the command.

AVERAGEn The mean value calculated by the command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 428 of 934

Commands

Name Contains

COUNTn The record count calculated by the command.

HIGHn The 5th highest value identified by the command.

The 5th highest is the default setting. The setting can be changed using the NUMBER
parameter. For example, NUMBER 3 specifies that the 3rd highest value is stored.
Note
When Analytics identifies the highest value, duplicate values are not
factored out. For example, if values in descending order are 100, 100,
99, 98, the 3rd highest value is 99, not 98.

LOWn The 5th lowest value identified by the command.

The 5th lowest is the default setting. The setting can be changed using the
NUMBER parameter. For example, NUMBER 3 specifies that the 3rd lowest value is
stored.
Note
When Analytics identifies the lowest value, duplicate values are not
factored out. For example, if values in ascending order are 1, 1, 2, 3, the
3rd lowest value is 2, not 3.

MAXn The maximum value identified by the command.

MEDIANn The median value identified by the command.

MINn The minimum value identified by the command.

MODEn The most frequently occurring value identified by the command.

Q25n The first quartile value (lower quartile value) calculated by the command.

Q75n The third quartile value (upper quartile value) calculated by the command.

RANGEn The difference between the maximum and minimum values calculated by the command.

STDDEVn The standard deviation value calculated by the command.

TOTALn The total value calculated by the command.

The value of n is 1 unless the TOTAL command is inside a GROUP command, in which
case the value of n corresponds to the line number of the TOTAL command in the

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 429 of 934

Commands

Name Contains

GROUP command.
For more information, see "GROUP command" on page 221.

Examples
Generating conditional statistics
You generate statistics for the Quantity field in records where the product class ID is 01:

STATISTICS ON Quantity IF ProdCls = "01"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 430 of 934

Commands

STRATIFY command
Groups records into numeric intervals based on values in a numeric field. Counts the number of records in
each interval, and also subtotals specified numeric fields for each interval.

Syntax
STRATIFY <ON> numeric_field MINIMUM value MAXIMUM value {<INTERVALS number>|FREE
interval_value <...n> last_interval} <SUPPRESS> <SUBTOTAL numeric_field <...n>|SUBTOTAL
ALL> <KEY break_field> <TO {SCREEN|table_name|filename|GRAPH|PRINT}> <IF test> <FIRST
range|NEXT range> <WHILE test> <APPEND> <OPEN> <HEADER header_text> <FOOTER
footer_text> <LOCAL> <STATISTICS>

Parameters
Name Description

ON numeric_field The numeric field or expression to be stratified.

MINIMUM value Applies to numeric fields only. The minimum value of the first numeric interval.
MINIMUM is optional if you are using FREE, otherwise it is required.

MAXIMUM value Applies to numeric fields only. The maximum value of the last numeric interval.
MAXIMUM is optional if you are using FREE, otherwise it is required.

INTERVALS number Applies to numeric fields only.

FREE interval_value <...n> Applies to numeric fields only.

last_interval
Creates custom-sized intervals by specifying the start point of each interval and the end
optional point of the last interval.
If you specify MINIMUM and MAXIMUM values, those values are the start point of the first
interval and the end point of the last interval, and each interval_value creates an addi-
tional interval within the range. The interval values you specify must be greater than the
MINIMUM value, and equal to or less than the MAXIMUM value.
Interval values must be in numeric sequence and cannot contain duplicate values:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 431 of 934

Commands

Name Description

FREE -1000, 0, 1000, 2000, 3000

If you specify both FREE and INTERVALS, then INTERVALS is ignored.

SUPPRESS Values above the MAXIMUM value and below the MINIMUM value are excluded from the
command output.
optional

SUBTOTAL numeric_field One or more numeric fields or expressions to subtotal for each group.
<...n> | SUBTOTAL ALL
Multiple fields must be separated by spaces. Specify ALL to subtotal all the numeric fields
optional in the table.
If you do not select a subtotal field, the field you are stratifying on is automatically sub-
totaled.
You must explicitly specify the stratify field if you want to subtotal it along with one or more
other fields, or if you want to include statistics for the subtotaled stratify field.

TO SCREEN table_name | The location to send the results of the command to:
filename | GRAPH | PRINT o SCREEN – displays the results in the Analytics display area
o table_name – saves the results to an Analytics table
Specify table_name as a quoted string with a .FIL file extension. For example: TO "Out-
put.FIL"
By default, the table data file (.FIL) is saved to the folder containing the
Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
l TO "C:\Output.FIL"
l TO "Results\Output.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _
), but no other special characters, or any spaces. The name cannot
start with a number.
o filename – saves the results to a file
Specify filename as a quoted string with the appropriate file extension. For example:
TO "Output.TXT"
By default, the file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the file to a different, existing folder:
l TO "C:\Output.TXT"
l TO "Results\Output.TXT"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 432 of 934

Commands

Name Description

o GRAPH – displays the results in a graph in the Analytics display area

o PRINT – sends the results to the default printer

FIRST range | NEXT range The number of records to process:

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 433 of 934

Commands

Name Description

FOOTER system variable.

STATISTICS Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates average, minimum, and maximum values for all SUBTOTAL fields.

Examples
Stratifying on invoice amount
You need to stratify an accounts receivable table on the Invoice_Amount field. The invoice amount is also
automatically subtotaled.
The output is grouped into $1000 intervals:
l from $0 to $999.99
l from $1,000 to $1,999.99
l so on
The total invoice amount is included for each interval.

OPEN Ar
STRATIFY ON Invoice_Amount MINIMUM 0 MAXIMUM 10000 INTERVALS 10 TO "Stratified_
invoices.FIL"

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
STRATIFY groups records into equal-sized, or custom-sized, numeric intervals based on values in a
numeric field.
The output contains a single record for each interval, with a count of the number of records in the source
table that fall into each interval.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 434 of 934

Commands

Automatically populate the MINIMUM and MAXIMUM val-

ues
You can run the STATISTICS or PROFILE commands on the stratify field before running the STRATIFY
command to automatically populate the MINIMUM and MAXIMUM parameter values with the lowest and
highest values in the field.

Names of auto-generated subtotal and statistics fields

Description of auto-gen- Alternate column title (display name) in output

erated field Field name in output table table

Subtotal field subtotaled field name in source Total + subtotaled alternate column title in source
table table

Average field a_ subtotaled field name in Average + subtotaled alternate column title in
source table source table

Minimum field m_ subtotaled field name in Minimum + subtotaled alternate column title in
source table source table

Maximum field x_ subtotaled field name in Maximum + subtotaled alternate column title in
source table source table

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 435 of 934

Commands

SUMMARIZE command
Groups records based on identical values in one or more character, numeric, or datetime fields. Counts
the number of records in each group, and also subtotals specified numeric fields for each group.

Syntax
SUMMARIZE ON key_field <...n> <SUBTOTAL numeric_field <...n> |SUBTOTAL ALL> <OTHER
field <...n>|OTHER ALL> <TO {SCREEN|table_name|PRINT}> <IF test> <WHILE test> <FIRST
range|NEXT range> <PRESORT> <APPEND> <OPEN> <LOCAL> <HEADER header_text>
<FOOTER footer_text> <STATISTICS> <MODMEDQ> <STDEV> <CPERCENT> <ISOLOCALE
locale_code>

Parameters
Name Description

ON key_field <...n> One or more character, numeric, or datetime fields to summarize. Multiple fields must be
separated by spaces, and can be different data types.

OTHER field <...n> | One or more additional fields to include in the output.
OTHER ALL o field <...n> – include the specified field or fields
optional o ALL – include all fields in the table that are not specified as key fields or subtotal
fields
Use OTHER only with fields that contain the same value for all records in each sum-
marized group. If you specify a field that contains values that are different for a sum-
marized group, only the value for the first record in the group is displayed, which is not
meaningful.
For example:
o summarize a table on customer number – an appropriate "other field" is Customer
Name. Typically, the customer name is identical for all records with the same cus-
tomer number.
o summarize a vendor table by state – an inappropriate "other field" is City. Only the
first city listed for each state appears in the output. In this instance, the better
approach is to summarize using both state and city as key fields, in that order.

TO SCREEN table_name | The location to send the results of the command to:
PRINT o SCREEN – displays the results in the Analytics display area

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 436 of 934

Commands

Name Description

o table_name – saves the results to an Analytics table

FIRST range | NEXT range The number of records to process:

PRESORT Sorts the table on the key field before executing the command.
optional Note
You cannot use PRESORT inside the GROUP command.

If you use PRESORT

If you use PRESORT, the output is sorted and contains a single, unique group for each

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 437 of 934

Commands

Name Description

set of identical values, or identical combination of values, in the key field or fields.
Tip
If the input table is already sorted, you can save processing time by not
specifying PRESORT.

If you do not use PRESORT

If you do not use PRESORT, the output results use the sort order of the input table.
If the key field or fields contain non-sequential identical values, the output results con-
tain more than one group for each set of identical values, or identical combination of val-
ues.
Note
Depending on the context, more than one group for each set of identical
values, or identical combination of values, can defeat the purpose of
summarizing.

OPEN Opens the table created by the command after the command executes. Only valid if the
command creates an output table.
optional

HEADER header_text The text to insert at the top of each page of a report.

optional header_text must be specified as a quoted string. The value overrides the Analytics
HEADER system variable.

FOOTER footer_text The text to insert at the bottom of each page of a report.
optional footer_text must be specified as a quoted string. The value overrides the Analytics
FOOTER system variable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 438 of 934

Commands

Name Description

STATISTICS Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates average, minimum, and maximum values for all SUBTOTAL fields.

MODMEDQ Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates mode, median, first quartile, and third quartile values for all SUBTOTAL
fields.

STDEV Note
optional Cannot be used unless SUBTOTAL is also specified.
Calculates standard deviation and percentage of total for all SUBTOTAL fields.

CPERCENT Calculates percentage of record count for each group.

optional

ISOLOCALE Note
optional Applicable in the Unicode edition of Analytics only.
The system locale in the format language_ country. For example, to use Canadian
French, enter fr_ca.
Use the following codes:
o language – ISO 639 standard language code
o country – ISO 3166 standard country code
If you do not specify a country code, the default country for the language is used.
If you do not use ISOLOCALE, the default system locale is used.

Examples
Total transaction amount per customer
You summarize an accounts receivable table on the Customer_Number field, and subtotals the Trans_
Amount field. The output is grouped by customer and includes the total transaction amount for each cus-
tomer:

OPEN Ar
SUMMARIZE ON Customer_Number SUBTOTAL Trans_Amount TO "Customer_total.FIL"
PRESORT

Total transaction amount per customer per transaction date

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 439 of 934

Commands

You summarize an accounts receivable table on the Customer_Number and Trans_Date fields. You sub-
total the Trans_Amount field.
The output is grouped by customer, and within customer by date, and includes the total transaction
amount for each customer for each date the customer had transactions.

OPEN Ar
SUMMARIZE ON Customer_Number Trans_Date SUBTOTAL Trans_Amount TO "Customer_total_
by_date.FIL" PRESORT

Total, average, minimum, and maximum transaction amounts per customer

per transaction date
You add STATISTICS to the previous example.
In addition to the subtotaled transaction amount for each customer for each date the customer had trans-
actions, you also calculate the average, minimum, and maximum transaction amounts for each customer
for each date:

OPEN Ar
SUMMARIZE ON Customer_Number Trans_Date SUBTOTAL Trans_Amount TO "Customer_
stats_by_date.FIL" PRESORT STATISTICS

Identical transaction amounts, same date

You summarize a credit card transactions table on the Trans_Date and Trans_Amount fields.
The output is grouped by date, and within date by amount. You can use the associated count to identify
transactions with identical amounts and identical dates:

OPEN CC_Trans
SUMMARIZE ON Trans_Date Trans_Amount TO "Transactions_by_date_amount.FIL" OPEN
PRESORT
SET FILTER TO COUNT > 1

Remarks
Note
For more information about how this command works, see the Analytics Help.

How it works
SUMMARIZE groups records that have the same value, or the same combination of values, in one or
more character, numeric, or datetime fields. The output contains a single record for each group, with a
count of the number of records in the source table that belong to the group.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 440 of 934

Commands

Subtotal and statistics: calculations and field names in the

output results
You can use one or more optional parameters to perform statistical calculations on any SUBTOTAL field
you specify. The statistical calculations are broken down by group in the output:

Alternate column title (dis- Calculation performed on

Optional Parameter play name) in output table Field name in output table subtotaled field

Total + subtotaled altern- subtotaled field name Subtotaled values for each
SUBTOTAL ate column title group

Average + subtotaled a_ subtotaled field name The average value for

alternate column title each group

Minimum + subtotaled m_ subtotaled field name The minimum value for

alternate column title each group

Maximum + subtotaled x_ subtotaled field name The maximum value for

STATISTICS alternate column title each group

Median + subtotaled altern- c_ subtotaled field name The median value for each
ate column title group
o Odd-numbered sets of
values: the middle
value
o Even-numbered sets of
values: the average of
the two values at the
middle

Mode + subtotaled altern- o_ subtotaled field name The most frequently occur-
ate column title ring value for each group
o Displays "N/A" if no
value occurs more than
once
o In the event of a tie, dis-
plays the lowest value

Q25 + subtotaled alternate q_ subtotaled field name The first quartile value for
column title each group (lower quartile
value)
o The result is an inter-
polated value based on
an Analytics algorithm
o Produces the same res-
ult as the QUARTILE
and QUARTILE.INC
functions in Microsoft
MODMEDQ Excel

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 441 of 934

Commands

Alternate column title (dis- Calculation performed on

Optional Parameter play name) in output table Field name in output table subtotaled field

Q75 + subtotaled alternate p_ subtotaled field name The third quartile value for
column title each group (upper quartile
value)
o The result is an inter-
polated value based on
an Analytics algorithm
o Produces the same res-
ult as the QUARTILE
and QUARTILE.INC
functions in Microsoft
Excel

STDDEV + subtotaled d_ subtotaled field name The standard deviation for

alternate column title each group

% Field + subtotaled altern- f_ subtotaled field name Each group's subtotal

ate column title expressed as a percentage
STDEV of the field total

Percent of Count COUNT_PERCENTAGE The percentage of source

table records belonging to
each group
Note
Does not
require a sub-
CPERCENT total field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 442 of 934

Commands

TOP command
Moves to the first record in an Analytics table.

Syntax
TOP

Parameters
This command does not have any parameters.

Remarks
When to use TOP
Use TOP to move to the first record in a table if a previous command, such as FIND, selected another record
in the table.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 443 of 934

Commands

TOTAL command
Calculates the total value of one or more fields in an Analytics table.

Syntax
TOTAL {<FIELDS> numeric_field <...n>|<FIELDS> ALL} <IF test> <WHILE test> <FIRST
range|NEXT range>

Parameters
Name Description

FIELDS numeric_ The numeric fields to total. Specify ALL to total each of the numeric fields in the table.
field <...n> | FIELDS ALL

FIRST range | NEXT range The number of records to process:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 444 of 934

Commands

Analytics output variables

Note
If you total more than one field in a table, the system-generated output variable contains the
total for the first listed field only.

Name Contains

TOTALn The total value calculated by the command.

The value of n is 1 unless the TOTAL command is inside a GROUP command, in which
case the value of n corresponds to the line number of the TOTAL command in the
GROUP command.
For more information, see "GROUP command" on page 221.

Examples
Totaling the first 25 records
You calculate the total amount of the MKTVAL field for the first 25 records in the table:

TOTAL FIELDS MKTVAL FIRST 25

Remarks
When to use TOTAL
Use TOTAL to verify the completeness and accuracy of the source data and to produce control totals. The
command calculates the arithmetic sum of the specified fields or expressions.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 445 of 934

Commands

TRAIN command
Uses automated machine learning to create an optimum predictive model using a training data set.

Syntax
TRAIN {CLASSIFIER|REGRESSOR} <ON> key_field <...n> TARGET labeled_field SCORER
{ACCURACY|AUC|F1|LOGLOSS|PRECISION|RECALL|MAE|MSE|R2} SEARCHTIME minutes
MAXEVALTIME minutes MODEL model_name TO table_name <IF test> <WHILE test> <FIRST
range|NEXT range> FOLDS number_of_folds <SEED seed_value> <LINEAR> <NOFP>

Note
The maximum supported size of the data set used with the TRAIN command is 1 GB.

Parameters
Name Description

CLASSIFIER | The prediction type to use when training a predictive model:

REGRESSOR o CLASSIFIER – use classification algorithms to train a model
Use classification if you want to predict which class or category records belong to.
o REGRESSOR – use regression algorithms to train a model
Use regression if you want to predict numeric values associated with records.

ON key_field <...n> One or more training input fields.

Fields can be character, numeric, or logical. Multiple fields must be separated by
spaces.
Note
Character fields must be "categorical". That is, they must identify cat-
egories or classes, and contain a maximum number of unique values.
The maximum is specified by the Maximum Categories option (Tools
> Options > Command).

TARGET labeled_field The field that the model is being trained to predict based on the training input fields.
The different prediction types (classification or regression) work with different field data
types:

Valid with CLASSIFIER a character or logical target field

Valid with REGRESSOR a numeric target field

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 446 of 934

Commands

Name Description

Valid with CLASSIFIER ACCURACY | AUC | F1 | LOGLOSS | PRECISION | RECALL

Valid with REGRESSOR MAE | MSE | R2

SEARCHTIME minutes The total time in minutes to spend training and optimizing a predictive model.
Training and optimizing involves searching across different pipeline configurations (dif-
ferent model, preprocessor, and hyperparameter combinations).
Note
Total runtime of the TRAIN command is SEARCHTIME plus up to twice
MAXEVALTIME.
Tip
Specify a SEARCHTIME that is 10x the MAXEVALTIME.
This time allotment strikes a reasonable balance between processing
time and allowing a variety of model types to be evaluated.

MAXEVALTIME minutes Maximum runtime in minutes per model evaluation.

Tip
Allot 45 minutes for every 100 MB of training data.
This time allotment strikes a reasonable balance between processing
time and allowing a variety of model types to be evaluated.

MODEL model_name The name of the model file output by the training process.
The model file contains the model best fitted to the training data set. You will input the
model to the PREDICT command to generate predictions about a new, unseen data set.
Specify model_name as a quoted string. For example: TO "Loan_default_prediction"
You can specify the *.model file extension, or let Analytics automatically specify it.
By default, the model file is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the model file to a different, existing
folder:
o TO "C:\Loan_default_prediction"
o TO "ML Train output\Loan_default_prediction.model"

TO table_name The name of the model evaluation table output by the training process.
The model evaluation table contains two distinct types of information:
o Scorer/Metric – for the classification or regression metrics, quantitative estimates of
the predictive performance of the model file output by the training process

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 447 of 934

Commands

Name Description

Different metrics provide different types of estimates. Scorer identifies the metric you
specified with SCORER. Metric identifies the metrics you did not specify.
o Importance/Coefficient – in descending order, values indicating how much each fea-
ture (predictor) contributes to the predictions made by the model
Specify table_name as a quoted string with a .FIL file extension. For example: TO
"Model_evaluation.FIL"
By default, the table data file (.FIL) is saved to the folder containing the Analytics project.
Use either an absolute or relative file path to save the data file to a different, existing
folder:
o TO "C:\Model_evaluation.FIL"
o TO "ML Train output\Model_evaluation.FIL"
Note
Table names are limited to 64 alphanumeric characters, not including
the .FIL extension. The name can include the underscore character ( _ ),
but no other special characters, or any spaces. The name cannot start
with a number.

FIRST range | NEXT range The number of records to process:

FOLDS number_of_folds The number of cross-validation folds to use when evaluating and optimizing the model.
Folds are subdivisions of the training data set, and are used in a cross-validation pro-
cess.
Typically, using from 5 to 10 folds yields good results when training a model. The min-
imum number of folds allowed is 2, and the maximum number is 10.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 448 of 934

Commands

Name Description

Tip
With smaller training data sets, increasing the number of folds can pro-
duce a better estimate of the predictive performance of a model, but it
also increases overall runtime.

SEED seed_value The seed value to use to initialize the random number generator in Analytics.
optional If you omit SEED, Analytics randomly selects the seed value.
Explicitly specify a seed value, and record it, if you want to replicate the training process
with the same data set in the future.

LINEAR Train and score only linear models.

optional Including only linear models in the training process guarantees coefficients in the out-
put.
If LINEAR is omitted, all model types relevant to classification or regression are eval-
uated.

NOFP Exclude feature selection and data preprocessing from the training process.
optional Feature selection is the automated selection of the fields in the training data set that are
the most useful in optimizing the predictive model. Automated selection can improve pre-
dictive performance, and reduce the amount of data involved in model optimization.
Data preprocessing performs transformations such as scaling and standardizing on the
training data set to make it better suited for the training algorithms.
Caution
You should only exclude feature selection and data preprocessing if you
have a reason for doing so.

Examples
Train a classification model
You want to train a classification model that you can use in a subsequent process to predict which loan
applicants will default.
You train the model using a set of historical loan data with a known outcome for each loan, including whether
the client defaulted.
In the subsequent prediction process, you will use the model produced by the TRAIN command to process
current loan applicant data.

OPEN "Loan_applicants_historical"
TRAIN CLASSIFIER ON Age Job_Category Salary Account_Balance Loan_Amount Loan_Period

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 449 of 934

Commands

Refinanced Credit_Score TARGET Default SCORER LOGLOSS SEARCHTIME 960

MAXEVALTIME 90 MODEL "Loan_default_prediction.model" TO "Model_evaluation.FIL" FOLDS 5

Train a regression model

You want to train a regression model that you can use in a subsequent process to predict the future sale
price of houses.
You train the model using a set of recent house sales data, including the sale price.
In the subsequent prediction process, you will use the model produced by the TRAIN command to gen-
erate house price evaluations.

OPEN "House_sales"
TRAIN REGRESSOR ON Lot_Size Bedrooms Bathrooms Stories Driveway Recroom Full_Base-
ment Gas_HW Air_conditioning Garage_Places Preferred_Area TARGET Price SCORER MSE
SEARCHTIME 960 MAXEVALTIME 90 MODEL "House_price_prediction.model" TO "Model_eval-
uation.FIL" FOLDS 5

Remarks
Note
For more information about how this command works, see the Analytics Help.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 450 of 934

Commands

VERIFY command
Checks for data validity errors in one or more fields in an Analytics table by verifying that the data is con-
sistent with the field definitions in the table layout.

Syntax
VERIFY {<FIELDS> field <...n>|<FIELDS> ALL} <IF test> <WHILE test> <FIRST
range|NEXT range> <ERRORLIMIT n> <TO {SCREEN|filename|PRINT}> <APPEND>

Parameters
Name Description

FIELDS field <...n> | The fields or expressions to verify. Specify ALL to verify all fields in the table.
FIELDS ALL
Note
By definition, computed fields, ad hoc expressions, and binary fields are
always valid.

FIRST range | NEXT range The number of records to process:

ERRORLIMIT n The number of errors allowed before the command is terminated. The default value is 10.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 451 of 934

Commands

Name Description

optional

Analytics output variables

Name Contains

WRITEn The total number of data validity errors identified by the command.

Examples
Verifying data and specifying an error limit
You verify all of the columns in a table and set the error limit to 10. The command stops processing if 10
data validity errors are detected:

VERIFY ALL ERRORLIMIT 10 TO "ImportErrors.txt"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 452 of 934

Commands

Remarks
How it works
VERIFY compares the values in one or more fields to the data type specified for each of the fields in the
table layout and reports any errors. The command ensures the following:
l character fields – contain only valid characters, and that no unprintable characters are present
l numeric fields – contain only valid numeric data. In addition to numbers, numeric fields can contain
one preceding plus sign or minus sign and one decimal point
l datetime fields – contain valid dates, datetimes, or times
For each error that is identified, the record number and field name are output, along with the invalid value in
hexadecimal format.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 453 of 934

Commands

Functions

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 454 of 934

Commands

ABS( ) function
Returns the absolute value of a numeric expression. The absolute value of a number is the number without
its sign.

Syntax
ABS(number)

Parameters
Name Type Description

number numeric The value to find the absolute value for.

Output
Numeric.

Examples
Basic examples
Returns 7.2:

ABS(7.2)

Returns 7.2:

ABS(-7.2)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 455 of 934

Commands

AGE( ) function
Returns the age, in days, of a specified date compared to a specified cutoff date, or the current operating
system date.

Syntax
AGE(date/datetime/string <,cutoff_date>)

Parameters
Name Type Description

date/datetime/string character The field, expression, or literal value to age.

datetime

cutoff_date character The field, expression, or literal value to which date/datetime/string is

compared. If omitted, the current operating system date is used as the
optional datetime
cutoff date.

Note
date/datetime/string and cutoff_date can both accept a datetime value, but the time por-
tion of the value is ignored. You cannot use AGE( ) with time values alone.

Output
Numeric.

Examples
Basic examples
No cutoff date
Returns the number of days between 31 Dec 2014 and the current date:
l If a positive value is returned, it is equal to the number of days in the past December 31, 2014
occurred

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 456 of 934

Commands

l If a negative value is returned, it is equal to the number of days in the future December 31, 2014
occurs
l If 0 is returned, December 31, 2014 is the current date

AGE(`20141231`)

Returns the number of days between each date in the Due_date field and the current date:

AGE(Due_date)

Mixing data types

Returns 518, the number of days between the two specified dates:

AGE(`20130731`,`20141231`)

AGE("20130731","20141231")

AGE(`20130731`,"20141231")

AGE(`20130731 235959`,`20141231`)

Using cutoff dates and fields

Returns the number of days between each date in the Due_date field and the cutoff date of December 31,
2014:
l Dates prior to the cutoff date return a positive value equal to the number of days before the cutoff day
they occur
l Dates after the cutoff date return a negative value equal to the number of days after the cutoff day
they occur

AGE(Due_date, `20141231`)

Returns the number of days between December 31, 2014 and each date in the Due_date field. Results are
the same as the example immediately above, but the sign of the returned values (positive or negative) is
reversed:

AGE(`20141231`, Due_date)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 457 of 934

Commands

Comparing dates in fields

Returns the number of days between each date in the Payment_date field and a corresponding date in the
Due_date field:
l Payment dates prior to due dates return a positive value, indicating timely payment
l Payment dates after due dates return a negative value, indicating late payment

AGE(Payment_date, Due_date)

Returns the number of days between each date in the Payment_date field and a corresponding date in the
Due_date field plus a grace period of 15 days.
l Payment dates prior to due dates, or up to 15 days after due dates, return a positive value
l Payment dates more than 15 days after due dates return a negative value, indicating late payment
outside the grace period

AGE(Payment_date, Due_date+15)

Advanced examples
Extracting overdue payments
Extract the name, amount, and invoice date for each record where the age of the invoice is greater than
180 days, based on a cutoff date of December 31, 2014:

EXTRACT FIELDS Name Amount Invoice_Date TO "Overdue" IF AGE(Invoice_Date,`20141231`) >

180

Remarks
How it works
The AGE( ) function calculates the number of days between two dates.

When to use AGE( )

Use AGE( ) to compare two dates to determine overdue accounts, to perform aged analyses of balances,
or to perform any task that requires the number of elapsed days between two dates.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 458 of 934

Commands

Negative return values

A negative value is returned if the date specified for date/datetime/string is more recent than the date spe-
cified as the cutoff_date, or the operating system date if no cutoff_date is specified.

Using a field for the cutoff date

Unlike the AGE command, which requires a literal date value for the cutoff date, the AGE( ) function allows
you to use a field for the cutoff date.
For example:

AGE(Payment_date, Due_date)

Using the AGE( ) function in this manner is equivalent to calculating the difference between two date fields
by subtracting them in an expression.
For example:

Due_date – Payment_date

Parameter details
A datetime field specified for date/datetime/string or cutoff_date can use any date or datetime format, as
long as the field definition correctly defines the format.

Specifying a literal date or datetime value

When specifying a literal date or datetime value for date/datetime/string or cutoff_date, you are restricted to
the formats in the table below, and you must enclose the value in backquotes, or single or double quotation
marks – for example, `20141231` or "20141231"
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times. Colons are permitted in character time values.
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.

Example formats Example literal values

YYYYMMDD `20141231`
"20141231"

YYMMDD `141231`
"141231"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 459 of 934

Commands

Example formats Example literal values

YYYYMMDD hhmmss `20141231 235959`
"20141231 235959"

YYMMDDthhmm `141231t2359`
"141231t2359"

YYYYMMDDThh `20141231T23`
"20141231T23"

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset) "20141231 235959-0500"

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset) "141231 2359+01"

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 460 of 934

Commands

ALLTRIM( ) function
Returns a string with leading and trailing spaces removed from the input string.

Syntax
ALLTRIM(string)

Parameters
Name Type Description

string character The value to remove leading and trailing spaces from.

Output
Character.

Examples
Basic examples
Returns "Vancouver":

ALLTRIM(" Vancouver ")

Returns "New York":

ALLTRIM(" New York ")

Advanced examples
Concatenating character fields
Use ALLTRIM( ) to eliminate spaces when you concatenate character fields, such as first name and last
name fields, so that the resulting field does not contain multiple blank spaces between the concatenated

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 461 of 934

Commands

values.

DEFINE FIELD Full_Name COMPUTED ALLTRIM(First_Name) + " " + ALLTRIM(Last_Name)

Removing non-breaking spaces

Non-breaking spaces are not removed by the ALLTRIM( ) function.
If you need to remove leading or trailing non-breaking spaces, create a computed field using the following
expression:

DEFINE FIELD Description_cleaned COMPUTED ALLTRIM(REPLACE(Description, CHR(160),

CHR(32)))

The REPLACE( ) function replaces any non-breaking spaces with regular spaces, and then ALLTRIM( )
removes any leading or trailing regular spaces.

Remarks
How it works
The ALLTRIM( ) function removes the leading and trailing spaces from a string. Spaces inside the string
are not removed.

Related functions
Use the LTRIM( ) function if you want to remove only leading spaces from a string, or the TRIM( ) function if
you want to remove only trailing spaces.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 462 of 934

Commands

ASCII( ) function
Returns the ASCII code for a specified character.

Syntax
ASCII(character)

Parameters
Name Type Description

character character The character to identify the ASCII code for.

You can specify a quoted character, or a multi-character string, field, or
expression. If you specify multiple characters, only the first character is
evaluated.

Output
Numeric.

Examples
Basic examples
Returns 65:

ASCII("A")

Returns 49:

ASCII("1")

Advanced examples
Extracting a record that starts with a tab character

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 463 of 934

Commands

Extract records that have a tab character at the beginning of a field called "Description". The ASCII code
for a tab character is "9".

EXTRACT RECORD TO "Tab_Entries.acl" IF ASCII(Description) = 9

Remarks
Testing for non-printable characters
You can use ASCII( ) to test for non-printable characters such as:
l Nul – ASCII "0"
l Tab – ASCII "9"
l Line Feed (LF) – ASCII "10"
l Carriage Return (CR) – ASCII "13"

Related functions
ASCII( ) is the inverse of the CHR( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 464 of 934

Commands

AT( ) function
Returns a number specifying the starting location of a particular occurrence of a substring within a character
value.

Syntax
AT(occurrence_num, search_for_string, within_text)

Parameters
Name Type Description

occurance_num numeric The occurrence (instance) of search_for_string to return the location

of.
For example, specify 1 to return the starting location of the first occur-
rence of search_for_string.

search_for_string character The substring to search for in within_text. This value is case-sensitive.
If search_for_string includes double quotation marks, you need to
enclose the value in single quotation marks:

AT(1,'"test"', Description)

within_text character The value to search in.

You can concatenate two or more fields in the within_text parameter if
you want to search in more than one field in a table:

AT(1,'"test"', Description+Summary)

Output
Numeric. Returns the starting byte position of the specified occurrence of the search_for_string value, or 0 if
no matches are found.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 465 of 934

Commands

Examples
Basic examples
Occurrences found
Returns 4:

AT(1, "-", "604-669-4225")

Returns 8:

AT(2, "-", "604-669-4225")

Occurrences not found

Returns 0, because there is not a third hyphen in the value:

AT(3, "-", "604-669-4225")

Returns 0, because there is not a fourth lowercase "a" in the value:

AT(4, "a", "Alabama")

Groups of characters
Returns 5:

AT(2, "iss", "Mississippi")

Searching a field
Returns the byte position of the first hyphen in each value in the Invoice_Number field:

AT(1, "-", Invoice_Number)

Advanced examples
Finding invoice numbers in which the second hyphen occurs after the tenth
byte position

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 466 of 934

Commands

You can analyze the consistency of invoice numbers in a table by using the AT( ) function to create a filter
like the one below. This filter isolates all records in which the invoice number contains two or more hyphens,
and the second hyphen occurs after the tenth byte position:

SET FILTER TO AT(2, "-", Invoice_Number) > 10

Remarks
When to use AT( )
Use this function to retrieve the following starting positions within a character value:
l the starting position of a substring
l the starting position of a subsequent occurrence of the substring
If you only want to confirm multiple occurrences of the same substring in a field, the OCCURS( ) function is a
better alternative. For more information, see "OCCURS( ) function" on page 666.

Return value when occurrence_num exceeds the number

of occurrences
If occurrence_num is greater than the actual number of substring occurrences in within_text, the function
returns 0 because it cannot find that occurrence of the substring.

Concatenated fields and return values

When you search in more than one field, the value returned for the instance is the starting location of
search_for_string across all fields that you specify. The concatenated fields are treated like a single field that
includes leading and trailing spaces from the individual fields, unless you use the ALLTRIM( ) function to
remove spaces.
For example, if you search for the first occurrence of a string in two fields with a width of eight characters
each, and the string is found at the beginning of the second field, the return value is 9.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 467 of 934

Commands

BETWEEN( ) function
Returns a logical value indicating whether the specified value falls within a range.

Syntax
BETWEEN(value, min, max)

Parameters
Name Type Description

value character The field, expression, or literal value to test.

numeric
datetime

min character The minimum value of the range.

numeric
datetime

max character The maximum value of the range.

numeric
datetime

Note
The range evaluating to T (true) includes the min and max values.
For information regarding character ranges, see "SET EXACT behavior" on the facing
page.

Output
Logical. Returns T (true) if value is greater than or equal to the min value, and less than or equal to the max
value. Returns F (false) otherwise.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 468 of 934

Commands

Examples
Basic examples
Numeric input
Returns T:

BETWEEN(500,400,700)

Returns F:

BETWEEN(100,400,700)

Character input
Returns T:

BETWEEN("B","A","C")

Returns F, because the character comparison is case-sensitive, and lowercase "b" does not fall between
uppercase "A" and "C":

BETWEEN("b","A","C")

Datetime input
Returns T:

BETWEEN(`141230`,`141229`,`141231`)

Returns T for all values in the Login_time field from 07:00:00 AM to 09:00:00 AM, inclusive, and F oth-
erwise:

BETWEEN(Login_time,`t070000`,`t090000`)

SET EXACT behavior

Returns T for all values in the Last_Name field that begin with the letters from "C" to "K", inclusive, and F oth-
erwise (SET EXACT must be OFF):

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 469 of 934

Commands

BETWEEN(Last_Name, "C", "K")

Returns T for all values in the Last_Name field that begin with the letters from "C" to "J", inclusive, and F
otherwise (SET EXACT must be ON). Also returns T for the single letter "K":

BETWEEN(Last_Name, "C", "K")

Field input
Returns T for all values in the Invoice_Date field from 30 Sep 2014 to 30 Oct 2014, inclusive, and F oth-
erwise:

BETWEEN(Invoice_Date, `20140930`, `20141030`)

Returns T for all records in which the invoice date does not fall between the PO date and the paid date,
inclusive, and F otherwise:

NOT BETWEEN(Invoice_Date, PO_Date, Paid_Date)

Returns T for all values in the Invoice_Amount field from $1000 to $5000, inclusive, and F otherwise:

BETWEEN(Invoice_Amount, 1000, 5000)

Advanced examples
Creating a filter to view a salary range
The following example opens the Employee_List sample table and applies a filter that limits the records
displayed to include only employees that earn a salary greater than or equal to $40,000.00, and less than
or equal to $50,000.00.

OPEN Employee_List
SET FILTER TO BETWEEN(Salary, 40000.00, 50000.00)

Remarks
Supported data types
Inputs to the BETWEEN( ) function can be numeric, character, or datetime data. You cannot mix data
types. All three inputs must belong to the same data category.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 470 of 934

Commands

Use BETWEEN( ) instead of the AND operator

You can use the BETWEEN( ) function instead of expressions that use the AND operator.
For example:

BETWEEN(Invoice_Amount, 1000, 5000)

is equivalent to

Invoice_Amount >= 1000 AND Invoice_Amount <= 5000

The order of min and max

The order of min and max in the BETWEEN( ) function does not matter because Analytics automatically
identifies which value is the minimum and which value is the maximum.
Both of the examples below return T:

BETWEEN(2500, 1000, 5000)

BETWEEN(2500, 5000, 1000)

Decimal precision of numeric inputs

When the numeric inputs being compared have a different decimal precision, the comparison uses the
higher level of precision.
Returns T, because 1.23 is equal to 1.23:

BETWEEN(1.23, 1.23, 1.25)

Returns F, because 1.23 is less than 1.234 once the third decimal place is considered:

BETWEEN(1.23, 1.234, 1.25)

Character data
Case sensitivity
The BETWEEN( ) function is case-sensitive when used with character data. When it compares characters,
"a" is not equivalent to "A".
Returns F:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 471 of 934

Commands

BETWEEN("B","a","C")

If you are working with data that includes inconsistent case, you can use the UPPER( ) function to convert
the values to consistent case before using BETWEEN( ).
Returns T:

BETWEEN(UPPER("B"), UPPER("a"), UPPER("C"))

Partial matching
Partial matching is supported for character comparisons.
value can be contained by min.
Returns T, even though value "AB" appears to be less than min "ABC":

BETWEEN("AB", "ABC", "Z")

max can be contained by value.

Returns T, even though value "ZZ" appears to be greater than max "Z":

BETWEEN("ZZ", "ABC", "Z")

Note
The shorter value in the character comparison must appear at the start of the longer value
to constitute a match.

Partial matching and SET EXACT

Partial matching is enabled when SET EXACT = OFF, which is the Analytics default setting. If SET
EXACT = ON, partial matching is disabled and the comparison values must exactly match to constitute a
match.
Both examples above are False when SET EXACT is ON.
For more information about SET EXACT (the Exact Character Comparisons option), see "SET com-
mand" on page 408.

Turning SET EXACT off or on

If you want to ensure that the Exact Character Comparisons option is not used with the BETWEEN( )
function, check that the option is deselected in the Table tab in the Options dialog box (Tools > Options ).
If you are using a script, you can add the SET EXACT OFF command before the BETWEEN( ) function
appears. If required, you can restore the previous state with the SET EXACT ON command.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 472 of 934

Commands

Datetime parameters
A date, datetime, or time field specified as a function input can use any date, datetime, or time format, as
long as the field definition correctly defines the format.

Mixing date, datetime, and time inputs

You are not prevented from mixing date, datetime, and time values in the BETWEEN( ) function's three
inputs, but mixing these Datetime subtypes can give results that are not meaningful.
Analytics uses serial number equivalents to process datetime calculations, so even if you are interested in
only the date portion of a datetime value, the time portion still forms part of the calculation.
Consider the following examples:
Returns T, because 31 December 2014 falls within the range specified by min and max:

BETWEEN(`20141231`,`20141229`,`20141231`)

Returns F, even though 12:00 PM on 31 December 2014 appears to fall within the range specified by min
and max:

BETWEEN(`20141231 120000`,`20141229`,`20141231`)

If we look at the serial number equivalent of these two expressions, we can see why the second one eval-
uates to false.
Returns T, because the serial number value is equal to the serial number max:

BETWEEN(42003.000000, 42001.000000, 42003.000000)

Returns F, because the serial number value is greater than the serial number max:

BETWEEN(42003.500000, 42001.000000, 42003.000000)

The serial number 42003.500000 is greater than 42003.000000 and therefore is out of range, even though
the two dates are identical. 0.500000 is the serial number equivalent of 12:00 PM.

Harmonize Datetime subtypes

To avoid the problems that can be caused by mixing Datetime subtypes, you can use functions to harmonize
the subtypes.
For example, this expression, which uses the same initial values as the second example above, returns T
rather than F:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 473 of 934

Commands

BETWEEN(CTOD(DATE(`20141231
120000`,"YYYYMMDD"),"YYYYMMDD"),`20141229`,`20141231`)

Specifying a literal date, datetime, or time value

When specifying a literal date, datetime, or time value for any of the function inputs, you are restricted to
the formats in the table below, and you must enclose the value in backquotes – for example, `20141231`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

thhmmss `t235959`

Thhmm `T2359`

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 474 of 934

Commands

BINTOSTR( ) function
Returns Unicode character data converted from ZONED or EBCDIC character data. Abbreviation for "Bin-
ary to String".
Note:
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.

Syntax
BINTOSTR(string, string_type)

Parameters
Name Type Description

string character The ZONED or EBCDIC value that you want to convert to Unicode char-
acter encoding.

string_type character The format to convert from. You must specify one of the following val-
ues:
o "A" – convert from ZONED (ASCII) data
o "E" – convert from EBCDIC data

Output
Character.

Examples
Basic examples
The expression ZONED(-6448,4) converts the value -6448 to the character format "644Q", however the
Unicode edition of Analytics requires that you convert the output of ZONED( ) to Unicode characters using
BINTOSTR( ).
Returns "644Q" in Unicode format:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 475 of 934

Commands

BINTOSTR(ZONED(-6448,4), "A")

Remarks
When to use BINTOSTR( )
Use this function to convert return values from the ZONED( ) and EBCDIC( ) functions to a Unicode value.
Note
If this function is not applied to the return values of ZONED( ) and EBCDIC( ) in Unicode
editions of Analytics, then they are displayed incorrectly because the encoding is not inter-
preted correctly.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 476 of 934

Commands

BIT( ) function
Returns the binary representation for the specified byte position in the current record as an eight character
string.

Syntax
BIT(byte_location)

Parameters
Name Type Description

byte_location numeric The byte position to return as a binary value.

Output
Character.

Examples
Basic examples
Returns "00110001" if the eighth byte contains "1":

BIT(8)

Returns "01000001" if the ninth byte contains "A":

BIT(9)

Returns "01100001" if the seventeenth byte contains "a":

BIT(17)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 477 of 934

Commands

Advanced examples
Using BIT ( ) and SUBSTRING ( ) to extract a value
Assume that byte position 17 contains a set of 8 credit flags.
To extract all customer records that have the third bit set to one (meaning "do not ship"), specify:

EXTRACT IF SUBSTRING(BIT(17), 3, 1) = "1"

In this example, the SUBSTRING( ) function is used to extract the value of the third bit.

Remarks
How it works
BIT( ) converts the byte at the specified byte position into an eight character string of ones and zeros.

When to use BIT( )

Use BIT( ) to examine the individual bits in a byte.

Related functions
If you want to retrieve the character at the specified byte location, use the BYTE( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 478 of 934

Commands

BLANKS( ) function
Returns a string containing a specified number of blank spaces.

Syntax
BLANKS(count)

Parameters
Name Type Description

count numeric The number of blank spaces to insert.

Output
Character.

Examples
Basic examples
Returns " ":

BLANKS(5)

Returns "ABC Corporation":

"ABC" + BLANKS(1) + "Corporation"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 479 of 934

Commands

Remarks
When to use BLANKS( )
Use the BLANKS( ) function to harmonize fields, to initialize variables in scripts, or to insert blank spaces
when formatting fields or concatenating strings.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 480 of 934

Commands

BYTE( ) function
Returns the character stored in the specified byte position in the current record.

Syntax
BYTE(byte_location)

Parameters
Name Type Description

byte_location numeric The byte position to return as a character value.

The value refers to a position in the record (counting from 1), irre-
spective of any field definitions.

Output
Character.

Examples
Basic examples
Returns "1" from a record that begins with an ID field containing "1":

byte(112)

Advanced examples
Identify records in print files or PDFs based on consistent formatting
Use BYTE( ) to identify records in a data file where a particular character is present in a particular byte pos-
ition. This is typically the case in Print Image (Report) files or Adobe Acrobat (PDF) files where data is
formatted in a consistent way throughout the document.
For example, to locate and extract records that include a period at byte position 113:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 481 of 934

Commands

EXTRACT RECORD IF BYTE(113) = "." TO "Output.fil"

Remarks
When to use BYTE( )
Use BYTE( ) to examine the contents of a position in a record, without having to define a field for the pur-
pose.

Using BYTE( ) on EBCDIC data

If you use this function on EBCDIC data, the value returned will also be EBCDIC. You may not be able to
compare this to character values.

Related functions
If you want to retrieve the binary representation for specified byte location, use the BIT( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 482 of 934

Commands

CDOW( ) function
Returns the name of the day of the week for a specified date or datetime. Abbreviation for "Character Day of
Week".

Syntax
CDOW(date/datetime, length)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to return the day name for.

length numeric A value between 1 and 9 that specifies the length of the output string.
To display abbreviated day names, specify a smaller value.

Output
Character.

Examples
Basic examples
Returns "Wednesday" because December 31, 2014 falls on a Wednesday, and length is 9:

CDOW(`20141231`, 9)

Returns "Wed" because December 31, 2014 falls on a Wednesday, and length is 3:

CDOW(`20141231 235959`, 3)

Returns the full day name for each value in the Invoice_date field:

CDOW(Invoice_date, 9)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 483 of 934

Commands

Returns the abbreviated day name for each value in the Receipt_timestamp field:

CDOW(Receipt_timestamp, 3)

Advanced examples
Adding a field that identifies the days of the week for dates
Use the CDOW( ) function to create a computed field that identifies the days of the week for all the dates in
a date field. Once you have created the computed field, you can add it to the view beside the date column:

DEFINE FIELD Name_of_Day COMPUTED CDOW(Trans_Date, 3)

Creating a filter to test for transactions that occurred on a weekend

Use the CDOW( ) function to create a filter that isolates transactions that occurred on a weekend:

SET FILTER TO CDOW(Trans_Date, 3) = "Sat" OR CDOW(Trans_Date, 3) = "Sun"

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.
If the length parameter is shorter than the day name, the day name is truncated to the specified length. If
the length parameter is longer than the day name, the day name is padded with blank spaces.

Specifying a literal date or datetime value

When specifying a literal date or datetime value for date/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 484 of 934

Commands

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Related functions
If you need to return the day of the week as a number (1 to 7), use DOW( ) instead of CDOW( ).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 485 of 934

Commands

CHR( ) function
Returns the character associated with the specified ASCII code.

Syntax
CHR(number)

Parameters
Name Type Description

number numeric A valid numeric expression between 1 and 255.

Output
Character.

Examples
Basic examples
Returns "A":

CHR(65)

Returns "1":

CHR(49)

Advanced examples
Adding the UK pound symbol (£) to each of the values in a currency field
Create a computed field that adds the pound symbol (ASCII code 163) before amounts in the Invoice_

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 486 of 934

Commands

Amount field. The numeric Invoice_Amount field is first converted to a character field, and leading and trail-
ing blank spaces are trimmed.

DEFINE FIELD Currency_UK COMPUTED CHR(163)+ALLTRIM(STRING(Invoice_Amount, 12))

Remarks
When to use CHR( )
Use the CHR( ) function to return the character associated with any ASCII code, including those characters
that cannot be entered directly from a keyboard or displayed on screen. With CHR( ), you can search fields
or records for the existence of these specific characters.

Referencing NUL
Referencing the ASCII NUL (null) character, CHR(0), may produce unpredictable results because it is used
by Analytics as a text qualifier, and should be avoided if possible.

Related functions
CHR( ) is the inverse of the ASCII( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 487 of 934

Commands

CLEAN( ) function
Replaces the first invalid character in a string, and all subsequent characters, with blanks.

Syntax
CLEAN(string <,extra_invalid_characters>)

Parameters
Name Type Description

string character The value from which to remove default and any extra invalid char-
acters.

extra_invalid_char- character Invalid characters you want to remove from string in addition to the
acters default invalid characters. You may specify more than one extra
invalid character:
optional

" ,;\"

Tab characters, null characters, and carriage return and line feed
characters are default invalid characters that are automatically
removed and do not need to be specified.
To specify the double quotation mark as an extra invalid character,
enclose extra_invalid_characters in single quotation marks:

'"'

Output
Character.

Examples
Basic examples
Returns "ABC " ("ABC" followed by four blank spaces):

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 488 of 934

Commands

CLEAN("ABC%DEF","%")

Returns "1234.56 " ("1234.56" followed by six blank spaces):

CLEAN("1234.56,111,2", ",")

Remarks
When to use CLEAN( )
Use this function to ensure that fields containing invalid data are printed correctly. You can also use this func-
tion to isolate parts of a field, such as the last name in a customer field that includes both the first and last
name of the customer.

Specifying invalid single and double quotation marks

If you need to specify both single and double quotation marks as invalid characters, you must nest the
CLEAN( ) function within itself:

CLEAN(CLEAN(string, '"'), "'")

Automatic CLEAN( )
In an Analytics script, you can apply the CLEAN( ) function automatically to all character fields by adding
SET CLEAN ON to the script. You cannot specify extra individual characters using this option.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 489 of 934

Commands

CMOY( ) function
Returns the name of the month of the year for a specified date or datetime. Abbreviation for "Character
Month of Year".

Syntax
CMOY(date/datetime, length)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to return the month name for.

length numeric A value between 1 and 9 that specifies the length of the output string.
To display abbreviated month names, specify a smaller value.

Output
Character.

Examples
Basic examples
Returns "December":

CMOY(`20141231`, 9)

Returns "Dec":

CMOY(`20141231 235959`, 3)

Returns the abbreviated month name for each value in the Receipt_timestamp field:

CMOY(Receipt_timestamp, 3)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 490 of 934

Commands

Returns the full month name for each value in the Invoice_date field:

CMOY(Invoice_date, 9)

Returns the full name of the month 15 days after each value in the Invoice_date field:

CMOY(Invoice_date + 15, 9)

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.
If the length parameter is shorter than the month name, the month name is truncated to the specified length.
If the length parameter is longer than the month name, the month name is padded with blank spaces.

Specifying a literal date or datetime value

When specifying a literal date or datetime value for date/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 491 of 934

Commands

Example formats Example literal values

(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Related functions
If you need to return the month of the year as a number (1 to 12), use MONTH( ) instead of CMOY( ).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 492 of 934

Commands

COS( ) function
Returns the cosine of an angle expressed in radians, with a precision of 15 decimal places.

Syntax
COS(radians)

Parameters
Name Type Description

radians numeric The measurement of the angle in radians.

Output
Numeric.

Examples
Basic examples
Returns 0.500000000000000 (the specified number of radians):

COS(1.047197551196598)

Advanced examples
Using degrees as input
Returns 0.500000000000000 (the cosine of 60 degrees):

COS(60 * PI( )/180)

Rounding to 3 decimal places

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 493 of 934

Commands

Returns 0.500 (the cosine of 60 degrees, rounded to 3 decimal places):

DEC(COS(60 * PI( )/180),3)

Remarks
Performing the Mantissa Arc Test
The three trigonometric functions in Analytics – SIN( ), COS( ), and TAN( ) – support performing the Man-
tissa Arc Test associated with Benford's Law.

Converting degrees to radians

If your input is in degrees you can use the PI( ) function to convert the input to radians: (degrees * PI
( )/180) = radians. If required, you can round or truncate the return value using the DEC( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 494 of 934

Commands

CTOD( ) function
Converts a character or numeric date value to a date. Can also extract the date from a character or numeric
datetime value and return it as a date. Abbreviation for "Character to Date".

Syntax
CTOD(string/number <,format>)

Parameters
Name Type Description

string/number character The field, expression, or literal value to convert to a date, or from which
to extract the date.
numeric

format character The date format of string/number. The format is required for values that
use any date format other than YYYYMMDD or YYMMDD, for example
optional
"DD/MM/YYYY".
Note
If you use the CTOD function with a datetime value that
requires the format parameter, specify only the date por-
tion of the format, and not the time portion. For example:

CTOD("31/12/2014 23:59:59", "DD/MM/YYYY")

Specifying the time portion prevents the results from

appearing.

Output
Datetime. The date value is output using the current Analytics date display format.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 495 of 934

Commands

Examples
Basic examples
Character literal input
Returns `20141231` displayed as 31 Dec 2014 assuming a current Analytics date display format of DD
MMM YYYY:

CTOD("20141231")

CTOD("31/12/2014", "DD/MM/YYYY")

CTOD("20141231 235959")

Numeric literal input

Returns `20141231` displayed as 31 Dec 2014 assuming a current Analytics date display format of DD
MMM YYYY:

CTOD(20141231)

CTOD(31122014, "DDMMYYYY")

CTOD(20141231.235959)

Character field input

Returns each value in the specified character field as a date, using the current Analytics date display
format:

CTOD(Invoice_date, "DD/MM/YYYY")

CTOD(Receipt_timestamp)

Numeric field input

Returns each value in the specified numeric field as a date, using the current Analytics date display format:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 496 of 934

Commands

CTOD(Due_date, "DDMMYYYY")

CTOD(Payment_timestamp)

Advanced examples
Compare a character or numeric field to a date
Use the CTOD( ) function to compare a date against character or numeric fields that contain values rep-
resenting dates.
The filter below compares two values:
l the numeric Due_date field that stores dates as numbers in the format DDMMYYYY
l the literal date value July 1, 2014

SET FILTER TO CTOD(Due_date, "DDMMYYYY") < `20140701`

Remarks
Required date formats
Character and numeric fields containing date or datetime values must match the formats in the table below.
Datetime values can use any combination of the date, separator, and time formats valid for their data type.
The date must precede the time, and there must be a separator between the two.
Dates, or the date portion of datetime values, can use any date format supported by Analytics, and valid for
the data type, as long as formats other than YYYYMMDD or YYMMDD are correctly defined by format.

Date formats Separator formats Time formats

Character fields

YYYYMMDD single blank space hhmmss

hh:mm:ss

YYMMDD the letter 't' hhmm

hh:mm

any Analytics-supported date format, valid for the data type, if defined by format the letter 'T' hh

+/-hhmm
+/-hh:mm
(UTC offset)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 497 of 934

Commands

Date formats Separator formats Time formats

+/-hh
(UTC offset)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 498 of 934

Commands

Date formats Separator formats Time formats

N-
ot-
e
D-
o
n-
ot
us-
e
hh
al-
o-
ne
in
th-
e
m-
ai-
n
ti-
m-
e
fo-
r-
m-
at
wi-
th
d-
at-
a
th-
at
h-
as
a
U-
T-
C
off-
se-
t.
F-
or
ex-
a-
m-
pl-
e,
av-
oi-
d:
h-
h-
+-
h-
h-
Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize m-
m.
Page 499 of 934
R-
Commands

Date formats Separator formats Time formats

Numeric fields

YYYYMMDD decimal point hhmmss

YYMMDD hhmm

any Analytics-supported date format, valid for the data type, if defined by format hh

Other datetime conversion functions

Character or Numeric to Datetime conversion
Function Description

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can
also return the current operating system time.

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional por-
tion of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 500 of 934

Commands

Function Description

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 501 of 934

Commands

CTODT( ) function
Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to Datetime".

Syntax
CTODT(string/number <,format>)

Parameters
Name Type Description

string/number character The field, expression, or literal value to convert to a datetime.

numeric

format character The date format of string/number. The format is required for values
that use any date format other than YYYYMMDD or YYMMDD for the
optional
date portion of the value, for example "DD/MM/YYYY".

Output
Datetime. The datetime value is output using the current Analytics date and time display formats.

Examples
Basic examples
Character literal input
Returns `20141231t235959` displayed as 31 Dec 2014 23:59:59 assuming a current Analytics date and
time display formats of DD MMM YYYY and hh:mm:ss:

CTODT("20141231 235959")

CTODT("31/12/2014 23:59:59", "DD/MM/YYYY hh:mm:ss")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 502 of 934

Commands

Numeric literal input

Returns `20141231t235959` displayed as 31 Dec 2014 23:59:59 assuming a current Analytics date and
time display formats of DD MMM YYYY and hh:mm:ss:

CTODT(20141231.235959)

CTODT(31122014.235959, "DDMMYYYY.hhmmss")

Character field input

Returns each value in the Receipt_timestamp character field as a datetime, using the current Analytics
date display format:

CTODT(Receipt_timestamp, "DD/MM/YYYY hh:mm:ss")

Numeric field input

Returns each value in the Payment_timestamp numeric field as a datetime, using the current Analytics
date display format:

CTODT(Payment_timestamp, "DD/MM/YYYY hh:mm:ss")

Advanced examples
Compare a character or numeric field to a datetime
Use the CTODT( ) function to compare a datetime against character or numeric fields that contain values
representing datetimes.
The filter below compares two values:
l the character Receipt_timestamp field that stores datetimes as character data in the format
DD/MM/YYYY hh:mm:ss
l the literal datetime value July 1, 2014 13:30:00

SET FILTER TO CTODT(Receipt_timestamp, "DD/MM/YYYY hh:mm:ss") < `20140701t133000`

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 503 of 934

Commands

Remarks
Required datetime formats
Character and numeric fields containing datetime values must match the formats in the table below. The
datetime values can use any combination of the date, separator, and time formats valid for their data type.
The date must precede the time, and there must be a separator between the two.
The date portion of values can use any date format supported by Analytics, and valid for the data type, as
long as formats other than YYYYMMDD or YYMMDD are correctly defined by format. If you use format,
you must also specify the time format, which must be one of the time formats that appear in the table
below.
Analytics automatically recognizes the separator between the date and time portions of datetime values,
so there is no need to specify the separator in format. You can specify the separator if you want to.

Date formats Separator formats Time formats

Character fields

YYYYMMDD single blank space hhmmss

hh:mm:ss

YYMMDD the letter 't' hhmm

hh:mm

any Analytics-supported date format, valid for the data type, if defined by format the letter 'T' hh

+/-hhmm
+/-hh:mm
(UTC offset)

+/-hh
(UTC offset)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 504 of 934

Commands

Date formats Separator formats Time formats

N-
ot-
e
D-
o
n-
ot
u-
se
h-
h
al-
o-
n-
e
in
th-
e
m-
ai-
n
ti-
m-
e
fo-
r-
m-
at
wi-
th
d-
at-
a
th-
at
h-
as
a
U-
T-
C
off-
s-
et.
F-
or
e-
x-
a-
m-
pl-
e,
a-
v-
oi-
d:
h-
Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize h-
+-
Pageh-505 of 934
h-
Commands

Date formats Separator formats Time formats

Numeric fields

YYYYMMDD decimal point hhmmss

YYMMDD hhmm

any Analytics-supported date format, valid for the data type, if defined by format hh

Other datetime conversion functions

Character or Numeric to Datetime conversion
Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a char-
acter or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can
also return the current operating system time.

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional por-
tion of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 506 of 934

Commands

Function Description

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 507 of 934

Commands

CTOT( ) function
Converts a character or numeric time value to a time. Can also extract the time from a character or
numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Syntax
CTOT(string/number)

Parameters
Name Type Description

string/number character The field, expression, or literal value to convert to a time, or from
which to extract the time.
numeric

Output
Datetime. The time value is output using the current Analytics time display format.

Examples
Basic examples
Character literal input
Returns `t235959` displayed as 23:59:59 assuming a current Analytics time display format of hh:mm:ss:

CTOT("t235959")

CTOT("23:59:59")

CTOT("20141231 235959")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 508 of 934

Commands

Numeric literal input

Returns `t235959` displayed as 23:59:59 assuming a current Analytics time display format of hh:mm:ss:

CTOT(.235959)

CTOT(0.235959)

CTOT(20141231.235959)

Character field input

Returns each value in the Login_time character field as a time, using the current Analytics time display
format:

CTOT(Login_time)

Numeric field input

Returns each value in the Payment_datetime numeric field as a time, without any date portion, using the
current Analytics time display format:

CTOT(Payment_datetime)

Advanced examples
Compare a character or numeric field to a time
Use the CTOT( ) function to compare a time against character or numeric fields that contain values rep-
resenting times.
The filter below compares two values:
l the numeric Login_time field that stores times as numeric data
l the literal time value 09:30:00

SET FILTER TO CTOT(Login_time) > `t093000`

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 509 of 934

Commands

Remarks
Required datetime formats
Character and numeric fields containing time or datetime values must match the formats in the table
below.
Time values can use any combination of separator and time format. There must be a separator before the
time value, or colons between the time components, for the function to operate correctly.
Datetime values can use any combination of the date, separator, and time formats valid for their data type.
The date must precede the time, and there must be a separator between the two.
Use the CTOD( ) function if you want to convert a character or numeric date value to a date, or extract the
date from a character or numeric datetime value and return it as a date.
Use the CTODT( ) function if you want to convert a character or numeric datetime value to a datetime.

Date formats Separator formats Time formats

Character fields

YYYYMMDD single blank space hhmmss

hh:mm:ss

YYMMDD the letter 't' hhmm

hh:mm

the letter 'T' hh

+/-hhmm
+/-hh:mm
(UTC offset)

+/-hh
(UTC offset)

Note:
Do not use hh alone
in the main time
format with data that
has a UTC offset. For
example, avoid: hh+h-
hmm. Results can be
unreliable.)

Numeric fields

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 510 of 934

Commands

Date formats Separator formats Time formats

YYYYMMDD decimal point hhmmss

YYMMDD hhmm

Other datetime conversion functions

Character or Numeric to Datetime conversion
Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a character
or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can also
return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can also
return the current operating system time.

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional portion
of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 511 of 934

Commands

Function Description

hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 512 of 934

Commands

CUMIPMT( ) function
Returns the cumulative interest paid on a loan during a range of periods.

Syntax
CUMIPMT(rate, periods, amount, start_period, end_period <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of payment periods.

amount numeric The principal amount of the loan.

start_period numeric The first period in the calculation.

start_period cannot be 0.

end_period numeric The last period in the calculation.

end_period cannot be greater than the total number of payment peri-
ods.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Note
You must use consistent time periods when specifying rate and periods to ensure that you
are specifying interest rate per period.
For example:
l for monthly payments on a two-year loan or investment with interest of 5% per
annum, specify 0.05/12 for rate and 2 * 12 for periods
l for annual payments on the same loan or investment, specify 0.05 for rate and 2 for
periods

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 513 of 934

Commands

Output
Numeric.

Examples
Basic examples
Returns 17437.23, the total amount of interest paid in the second year of a twenty-five year, $275,000 loan
at 6.5% per annum, with payments due at the end of the month:

CUMIPMT(0.065/12, 12*25, 275000, 13, 24, 0)

Returns 17741.31, the total amount of interest paid on the same loan in the first year of the loan:

CUMIPMT(0.065/12, 12*25, 275000, 1, 12, 0)

Remarks
Related functions
The CUMPRINC( ) function is the complement of the CUMIPMT( ) function.
The IPMT( ) function calculates interest paid for a single period.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 514 of 934

Commands

CUMPRINC( ) function
Returns the cumulative principal paid on a loan during a range of periods.

Syntax
CUMPRINC(rate, periods, amount, start_period, end_period <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of payment periods.

amount numeric The principal amount of the loan.

start_period numeric The first period in the calculation.

start_period cannot be 0.

end_period numeric The last period in the calculation.

end_period cannot be greater than the total number of payment peri-
ods.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 515 of 934

Commands

Output
Numeric.

Examples
Basic examples
Returns 4844.61, the total amount of principal paid in the second year of a twenty-five year, $275,000 loan
at 6.5% per annum, with payments due at the end of the month:

CUMPRINC(0.065/12, 12*25, 275000, 13, 24, 0)

Returns 367.24, the amount of principal paid on the same loan in the first month of the loan:

CUMPRINC(0.065/12, 12*25, 275000, 1, 1, 0)

Remarks
Related functions
The CUMIPMT( ) function is the complement of the CUMPRINC( ) function.
The PPMT( ) function calculates principal paid for a single period.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 516 of 934

Commands

DATE( ) function
Extracts the date from a specified date or datetime and returns it as a character string. Can also return the
current operating system date.

Syntax
DATE(< date/datetime> <,format>)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to extract the date from. If omitted,
the current operating system date is returned.
optional

format character The format to apply to the output string, for example "DD/MM/YYYY". If
omitted, the current Analytics date display format is used. You cannot
optional
specify a format if you have omitted date/datetime.

Output
Character.

Examples
Basic examples
Returns "20141231" in the current Analytics date display format:

DATE(`20141231 235959`)

Returns "31-Dec-2014":

DATE(`20141231 235959`, "DD-MMM-YYYY")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 517 of 934

Commands

Returns the current operating system date as a character string, using the current Analytics date display
format:

DATE()

Returns each value in the Receipt_timestamp field as a character string using the current Analytics date
display format:

DATE(Receipt_timestamp)

Returns each value in the Receipt_timestamp field as a character string using the specified date display
format:

DATE(Receipt_timestamp, "DD/MM/YYYY")

Remarks
Output string length
The length of the output string is always 12 characters. If the specified output format, or the Analytics date
display format, is less than 12 characters, the output string is padded with trailing blank spaces.

Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.
If you use format to control how the output string is displayed, you can use any supported Analytics date
display format. For example:
l DD/MM/YYYY
l MM-DD-YY
l DD MMM YYYY
format must be specified using single or double quotation marks – for example, "DD MMM YYYY".

Specifying a literal date or datetime value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 518 of 934

Commands

l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Related functions
If you need to return the current operating system date as a datetime value, use TODAY( ) instead of DATE(
).

Other datetime conversion functions

Datetime to Character conversion
Function Description

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can also

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 519 of 934

Commands

Function Description

return the current operating system time.

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a char-
acter or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional por-
tion of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 520 of 934

Commands

DATETIME( ) function
Converts a datetime to a character string. Can also return the current operating system datetime.

Syntax
DATETIME(< datetime> <,format>)

Parameters
Name Type Description

datetime datetime The field, expression, or literal value to convert. If omitted, the current
operating system date is returned.
optional

Output
Character.

Examples
Basic examples
Literal datetime input
Returns "20141231 235959" in the current Analytics date and time display formats:

DATETIME(`20141231 235959`)

Returns "31-Dec-2014 11:59 P":

DATETIME(`20141231 235959`, "DD-MMM-YYYY hh:mm A")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 521 of 934

Commands

Returns the current operating system date and time as a character string, using the current Analytics date
and time display formats:

DATETIME()

Field input
Returns each value in the Receipt_timestamp field as a character string using the current Analytics date
and time display formats:

DATETIME(Receipt_timestamp)

Returns each value in the Receipt_timestamp field as a character string using the specified date and time
display formats:

DATETIME(Receipt_timestamp, "DD/MM/YYYY hh:mm:ss")

Remarks
Output string length
The length of the output string is always 27 characters. If the specified output format, or the Analytics date
and time display formats, are less than 27 characters, the output string is padded with trailing blank
spaces.

Parameter details
A field specified for datetime can use any datetime format, as long as the field definition correctly defines
the format.
If you use format to control how the output string is displayed, you are restricted to the formats in the table
below.
l You can use any combination of date, time, and AM/PM formats.
l The date must precede the time. Placing a separator between the two is not required as Analytics
automatically uses a single space as a separator in the output string.
l The AM/PM format is optional, and is placed last.
l format must be specified using single or double quotation marks.
For example: "DD-MMM-YYYY hh:mm:ss AM"

Date formats Time formats AM/PM formats Examples

all supported Analytics date display formats hh:mm:ss none "DD/MM/YYYY hh:mm:ss"
24-hour clock

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 522 of 934

Commands

Date formats Time formats AM/PM formats Examples

hhmmss AM, or PM "MMDDYY hhmmss PM"

12-hour clock

hh:mm A, or P "DD-MMM-YYYY hh:mm A"

12-hour clock

hhmm

Specifying a literal datetime value

When specifying a literal datetime value for datetime, you are restricted to the formats in the table below,
and you must enclose the value in backquotes – for example, `20141231 235959`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 523 of 934

Commands

Other datetime conversion functions

Datetime to Character conversion
Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can
also return the current operating system time.

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a char-
acter or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional por-
tion of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 524 of 934

Commands

DAY( ) function
Extracts the day of the month from a specified date or datetime and returns it as a numeric value (1 to 31).

Syntax
DAY(date/datetime)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to extract the day from.

Output
Numeric.

Examples
Basic examples
Returns 31:

DAY(`20141231`)

DAY(`20141231 235959`)

Returns the day of the month for each value in the Invoice_date field:

DAY(Invoice_date)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 525 of 934

Commands

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.

Specifying a literal date or datetime value

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 526 of 934

Commands

Related functions
If you need to return:
l the day of the week as a number (1 to 7), use DOW( ) instead of DAY( )
l the name of the day of the week, use CDOW( ) instead of DAY( )

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 527 of 934

Commands

DBYTE( ) function
Returns the Unicode character located at the specified byte position in a record.
Note
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.

Syntax
DBYTE(byte_location)

Parameters
Name Type Description

byte_location numeric The byte position to return as a character value.

To return a meaningful value, you must specify the starting point of
the double-byte character, which means that you should only specify
odd numbers in the byte_location parameter.

Output
Character.

Examples
Basic examples
The examples illustrate the behavior of the function when applied to the following Unicode value, which
contains 11 characters (22 bytes) 美丽 10072DOE:
Returns "丽 ":

DBYTE(3)

Returns "D":

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 528 of 934

Commands

DBYTE(17)

Returns "E":

DBYTE(21)

Remarks
When to use DBYTE( )
Use DBYTE( ) to examine the contents of a position in a record, without having to define a field for this pur-
pose.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 529 of 934

Commands

DEC( ) function
Returns a value, or the result of a numeric expression, with the specified number of decimal places.

Syntax
DEC(number, decimals)

Parameters
Name Type Description

number numeric The value or result to adjust the number of decimal places for.
o integers – decimal places are added to the end of number as trail-
ing zeros.
o fractional numbers – If the number of decimal places is reduced,
number is rounded, not truncated. If the number of decimal places
is increased, trailing zeros are added to the end of number.

decimals numeric The number of decimal places to use in the return value.
Note
You cannot use DEC( ) to increase the decimal pre-
cision of results.
For information about how to increase decimal pre-
cision, see Controlling rounding and decimal precision
in numeric expressions.

Output
Numeric.

Examples
Basic examples
Returns 7.00:

DEC(7, 2)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 530 of 934

Commands

Returns 7.565:

DEC(7.5647, 3)

Returns 7.56470:

DEC(7.5647, 5)

Advanced examples
Calculating daily interest
Calculates the daily interest to six decimal places for a field called Annual_rate:

DEC(Annual_rate, 6) / 365

Remarks
When to use DEC( )
Use this function to adjust the number of decimal places in a field, or when you want to round a value or a res-
ult to a specified number of decimal places.

DEC( ) cannot reverse fixed-point rounding

You cannot use the DEC( ) function to reverse the standard rounding that fixed-point arithmetic performs in
numeric expressions.

Example
Consider the following series of expressions in Analytics:

1.1 * 1.1 = 1.2

1.1 * 1.10 = 1.21
DEC(1.1 * 1.1, 2) = 1.20

Fixed-point rounding means that the result of 1.1 * 1.1 is 1.2, not 1.21, which is the unrounded result. Using
DEC( ) to specify a two-decimal-place result does not create two-decimal-place precision. Instead, it adds a
trailing zero to create the specified number of decimal places, without increasing precision.
For information about how to increase decimal precision, see Controlling rounding and decimal precision in
numeric expressions.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 531 of 934

Commands

Related functions
If you want to round a value to the nearest whole number, use the "ROUND( ) function" on page 756.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 532 of 934

Commands

DHEX( ) function
Converts a Unicode string to a hexadecimal string.
Note:
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.

Syntax
DHEX(field)

Parameters
Name Type Description

field character The Unicode string to convert to a hexadecimal string.

Output
Character.

Examples
Basic examples
Returns "004100420043003100320033":

DHEX("ABC123")

Remarks
How it works
DHEX( ) displays each double-byte character using big-endian format, with the most significant double-byte
stored first.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 533 of 934

Commands

Each character is represented by a four-character code. The output string is four times as long as the field
value, and includes the digits between 0 and 9 and letters between A and F that make up the hexadecimal
values.

Related functions
DHEX( ) is the inverse of the HTOU( ) function, which converts a hexadecimal string to a Unicode string.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 534 of 934

Commands

DICECOEFFICIENT( ) function
Returns the Dice's coefficient of two specified strings, which is a measurement of how similar the two strings
are.

Syntax
DICECOEFFICIENT(string1, string2 <,ngram>)

Parameters
Name Type Description

string1 character The first string in the comparison.

string2 character The second string in the comparison.

ngram numeric The n-gram length to use.

optional Specify a whole number, 1 or greater. Increasing the ngram length
makes the criterion for similarity between two strings stricter.
If you do not specify a length, the default length of 2 is used.
N-grams are overlapping substrings (character blocks) into which the
comparison strings are divided as part of the Dice's coefficient cal-
culation.
For detailed information, see "Remarks" on page 537.

Output
Numeric. The value is the Dice's coefficient of the two strings, which represents the percentage of the total
number of n-grams in the two strings that are identical. The range is 0.0000 to 1.0000, inclusive.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 535 of 934

Commands

Examples
Basic examples
How the n -gram length affects the result
The three examples below compare the same two strings. The degree of similarity returned varies depend-
ing on the specified n-gram length.
Returns 0.9167 (using the default n-gram length (2), the n-grams in the two strings are 92% identical):

DICECOEFFICIENT("125 SW 39TH ST, Suite 100","Suite 100, 125 SW 39TH ST")

Returns 1.0000 (using an n-gram length of 1, the n-grams in the two strings are 100% identical):

DICECOEFFICIENT("125 SW 39TH ST, Suite 100","Suite 100, 125 SW 39TH ST", 1)

Returns 0.8261 (using an n-gram length of 3, the n-grams in the two strings are 83% identical):

DICECOEFFICIENT("125 SW 39TH ST, Suite 100","Suite 100, 125 SW 39TH ST", 3)

Field input
Returns the Dice's coefficient of each value in the Address field when compared to the string "125 SW
39TH ST, Suite 100" (based on the default n-gram length of 2):

DICECOEFFICIENT(Address,"125 SW 39TH ST, Suite 100")

Advanced examples
Working with transposed elements
By reducing the n-gram length, and removing non-essential characters, you can optimize
DICECOEFFICIENT( ) when searching for transposed elements.
Returns 0.7368 (using the default n-gram length (2), the n-grams in the two strings are 74% identical):

DICECOEFFICIENT("John Smith","Smith, John")

Returns 1.0000 (by excluding the comma between last name and first name, and by using an n-gram
length of 1, the n-grams in the two strings are 100% identical):

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 536 of 934

Commands

DICECOEFFICIENT("John Smith", EXCLUDE("Smith, John", ","), 1)

Ranking values against "125 SW 39TH ST, Suite 100"

Create the computed field Dice_Co to display the Dice's coefficient between "125 SW 39TH ST, Suite 100"
and each value in the Address field:

DEFINE FIELD Dice_Co COMPUTED DICECOEFFICIENT(Address,"125 SW 39TH ST, Suite 100")

Add the computed field Dice_Co to the view, and then quick sort it in descending order, to rank all values in
the Address field based on their similarity to "125 SW 39TH ST, Suite 100".

Isolating fuzzy duplicates for "125 SW 39TH ST, Suite 100"

Create a filter that isolates all values in the Address field that are within a specified degree of similarity to
"125 SW 39TH ST, Suite 100":

SET FILTER TO DICECOEFFICIENT(Address,"125 SW 39TH ST, Suite 100") > 0.5

Changing the number in the expression allows you to adjust the degree of similarity in the filtered values.

Remarks
When to use DICECOEFFICIENT( )
Use the DICECOEFFICIENT( ) function to find nearly identical values (fuzzy duplicates). You can also use
DICECOEFFICIENT( ) to find values with identical or near-identical content, but transposed elements. For
example:
l telephone numbers, or social security numbers, with transposed digits
l versions of the same address, formatted differently

How it works
DICECOEFFICIENT( ) returns the Dice's coefficient of the two evaluated strings, which is a measurement of
the degree of similarity between the strings, on a scale from 0.0000 to 1.0000. The greater the returned
value the more similar the two strings:
l 1.0000 – means that each string is composed of an identical set of characters, although the characters
may be in a different order, and may use different case.
l 0.7500 – means the n-grams in the two strings are 75% identical.
l 0.0000 – means the two strings have no shared n-grams (explained below), or the specified length of
the n-gram used in the calculation is longer than the shorter of the two strings being compared.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 537 of 934

Commands

Usage tips
l Filtering or sorting – Filtering or sorting the values in a field based on their Dice's coefficient iden-
tifies those values that are most similar to the comparison string.
l Case-sensitivity – The function is not case-sensitive, so "SMITH" is equivalent to "smith."
l Leading and trailing blanks – The function automatically trims leading and trailing blanks in fields,
so there is no need to use the TRIM( ) or ALLTRIM( ) functions when specifying a field as a para-
meter.
l Removing generic elements – The OMIT( ) and EXCLUDE( ) functions can improve the effect-
iveness of the DICECOEFFICIENT( ) function by removing generic elements such as "Corporation"
or "Inc.", or characters such as commas, periods, and ampersands (&), from field values.
Removal of generic elements and punctuation focuses the DICECOEFFICIENT( ) string com-
parison on just the portion of the strings where a meaningful difference may occur.

How Dice's coefficient is calculated

Dice's coefficient represents the percentage of the total number of n-grams in two strings that are identical.
Dice's coefficient is calculated by first dividing the strings being compared into n-grams. N-grams (also
referred to as q-grams) are overlapping substrings, or overlapping character blocks, with a length of n.
You can specify the length of n using the ngram parameter, or accept the default length of 2.

Two names divided into n -grams

Here are the names "John Smith" and "Smith, John D." divided into n-grams with a length of 2, and n-
grams with a length of 3. Underscores indicate spaces. Internal spaces and punctuation are counted as
characters.

n-gram
length "John Smith" n-grams "Smith, John D." n-grams

2 Jo | oh | hn | n_ | _S | Sm | mi | it | th Sm | mi | it | th | h, | ,_ | _J | Jo | oh | hn | n_ | _D | D.

3 Joh | ohn | hn_ | n_S | _Sm | Smi | mit | Smi | mit | ith | th, | h,_ | ,_J | _Jo | Joh | ohn | hn_ | n_D | _
ith D.

The Dice's coefficient formula

Once the n-grams have been established for two strings being compared, the calculation is completed
using the following formula:
l 2 x the number of shared n-grams / the total number of n-grams in both strings
Shared n-grams are n-grams that appear in both strings. For example, "ABC" and "BCD" share the n-
gram "BC", assuming an n-gram length of 2 (AB | BC and BC | CD).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 538 of 934

Commands

Examples of calculating the Dice's coefficient

The table below illustrates calculating the Dice's coefficient for the two strings, "John Smith" and "Smith,
John D.", using different n-gram lengths.
Note that as the n-gram length increases for the same pair of strings, the Dice's coefficient value decreases,
indicating less similarity. Although the strings remain the same, the criterion for similarity becomes stricter
because dividing the strings into longer n-grams means that longer sequences of characters must match for
an n-gram to qualify as shared.
Another way of thinking about this point is that the relative position of characters is weighted more heavily as
you increase the n-gram length. By contrast, the relative position of characters is not considered when using
an n-gram length of 1. Relative position refers to the position of characters in relation to one another, rather
than to their absolute position within a string.
Tip
If you are specifically looking for transposition, use an n-gram length of 1.

n-gram Shared Dice's coef-

length "John Smith" n-grams "Smith, John D." n-grams n-grams ficient

1 J|o|h|n|_|S|m|i|t|h S|m|i|t|h|,|_|J|o|h|n|_|D|. 10 2x10 / (10+14)

= 0.8333
(10 n-grams) (14 n-grams)

2 Jo | oh | hn | n_ | _S | Sm | mi Sm | mi | it | th | h, | ,_ | _J | Jo | oh | hn | n_ | 8 2x8 / (9+13) =
| it | th _D | D. 0.7273
(default)
(9 n-grams) (13 n-grams)

3 Joh | ohn | hn_ | n_S | _Sm | Smi | mit | ith | th, | h,_ | ,_J | _Jo | Joh | ohn 6 2x6 / (8+12) =
Smi | mit | ith | hn_ | n_D | _D. 0.6000
(8 n-grams) (12 n-grams)

4 John | ohn_ | hn_S | n_Sm | _ Smit | mith | ith, | th,_ | h,_J | ,_Jo | _Joh | 4 2x4 / (7+11) =
Smi | Smit | mith John | ohn_ | hn_D | n_D. 0.4444
(7 n-grams) (11 n-grams)

DICECOEFFICIENT( ) compared to ISFUZZYDUP( ) and

LEVDIST( )
One of the key differences between the DICECOEFFICIENT( ) function and the ISFUZZYDUP( ) and
LEVDIST( ) functions, which use Levenshtein distance, is that DICECOEFFICIENT( ) de-emphasizes or
completely ignores the relative position of characters or character blocks in the two strings being compared.
Relative position is significant in the functions based on Levenshtein distance.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 539 of 934

Commands

Comparison values with transposition

If you are comparing strings such as addresses, in which entire elements might be transposed,
DICECOEFFICIENT( ) might be a better choice. For example, the same address with the "Suite" element
transposed is identified as highly similar by DICECOEFFICIENT( ), but highly different by LEVDIST( ):

Dice's coefficient
Address pair (default n-gram of 2) Levenshtein distance

o 125 SW 39TH ST, Suite 100 0.9167 22

o Suite 100, 125 SW 39TH ST (the greater the Levenshtein dis-
tance, the more two strings differ)

Comparison values without transposition

If transposition is not an issue, LEVDIST( ) may give more useful results. For example, the same cor-
poration name with different punctuation is identified as highly different by DICECOEFFICIENT( ), but
highly similar by LEVDIST( ):

Dice's coefficient
Corporation name pair (default n-gram of 2) Levenshtein distance

o AVS, Inc 0.3750 3

o A.V.S. Inc

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 540 of 934

Commands

DIGIT( ) function
Returns the upper or lower digit of a specified Packed data type byte.

Syntax
DIGIT(byte_location, position)

Parameters
Name Type Description

byte_location numeric The byte position in the record.

position numeric The digit to return:

o specify 1 to return the upper half of the byte
o specify 2 to return the lower half of the byte

Output
Numeric.

Examples
Basic examples
A packed field with the value 123.45 (00 12 34 5C), containing two decimals, and starting in byte position 10,
appears in the data record in the following format:

Byte 10 Byte 11 Byte 12 Byte 13

UPPER(1) 0 1 3 5

LOWER(2) 0 2 4 C

Returns 3 (finds the digit that appears in the 12th position in the upper half of the byte):

DIGIT(12, 1)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 541 of 934

Commands

Returns 4 (finds digit that appears in the 12th position in the lower half of the byte):

DIGIT(12, 2)

Remarks
How it works
DIGIT( ) separates individual halves of a byte, and returns the value of the byte specified in the position
parameter as a digit between 0 and 15.

When to use DIGIT( )

Use DIGIT( ) to access individual half-bytes. This is required if you work with applications that use half-
byte-aligned packed fields, such as Unisys applications.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 542 of 934

Commands

DOW( ) function
Returns a numeric value (1 to 7) representing the day of the week for a specified date or datetime. Abbre-
viation for "Day of Week".

Syntax
DOW(date/datetime)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to extract the numeric day of the
week from.

Output
Numeric.

Examples
Basic examples
Returns 4, because December 31, 2014 falls on a Wednesday, the 4th day of the week:

DOW(`20141231`)

DOW(`20141231 235959`)

Returns the numeric day of the week for each value in the Invoice_date field:

DOW(Invoice_date)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 543 of 934

Commands

Advanced examples
Identifying transactions occurring on a weekend
Use the DOW( ) function to identify transactions that occur on a weekend. The filter below isolates dates in
the Trans_Date field that occur on a Saturday or a Sunday:

SET FILTER TO DOW(Trans_Date) = 7 OR DOW(Trans_Date) = 1

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.

Specifying a literal date or datetime value

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 544 of 934

Commands

Example formats Example literal values

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Related functions
If you need to return:
l the name of the day of the week, use CDOW( ) instead of DOW( )
l the day of the month as a number (1 to 31), use DAY( ) instead of DOW( )

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 545 of 934

Commands

DTOU( ) function
Converts an Analytics date value to a Unicode string in the specified language and locale format. Abbre-
viation for "Date to Unicode".
Note
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.

Syntax
DTOU(< date> <,locale> <,style>)

Parameters
Name Type Description

date datetime The field, expression, or literal value to convert to a Unicode string. If
omitted, the current operating system date is used.
optional
The date can contain a datetime value, but the time portion of the
value is ignored. Standalone time values are not supported.
You can specify a field or a literal date value:
o Field – can use any date format, as long as the field definition cor-
rectly defines the format
o Literal – must use one of the YYYYMMDD or YYMMDD formats, for
example `20141231`
The minimum supported date value is 31 December 1969.

locale character The locale code that specifies the language of the output string, and
optionally the version of the language associated with a particular
optional
country or region.
For example, "zh" specifies Chinese, and "pt_BR" specifies Brazilian
Portuguese.
If omitted, the default locale for your computer is used. If a language
is specified, but no country is specified, the default country for the lan-
guage is used.
You cannot specify locale if you have not specified date.
For information about locale codes, see www.unicode.org.

style numeric The date format style to use for the Unicode string. The format style
matches the standard for the locale you specify:
optional

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 546 of 934

Commands

Name Type Description

o 0 – full specification format, such as "Sunday, September 18, 2016"

o 1 – long format, such as "September 18, 2016"
o 2 – medium format, such as "Sep 18, 2016"
o 3 – short, numeric format such as "9/18/16"
If omitted, the default value of 2 is used. You cannot specify style if
you have not specified date and locale.

Output
Character.

Examples
Basic examples
Literal input values
Returns "31 de dezembro de 2014":

DTOU(`20141231`, "pt_BR", 1)

Returns "31 grudnia 2014":

DTOU(`20141231`, "pl", 1)

Field input values

Returns each numeric date in the Invoice_date field as a Unicode string:

DTOU(Invoice_date, "zh", 1)

Output uses full date style

Returns "星期三 , 2014 十二月 31" (no region identifier specified):

DTOU(`20141231`, "zh", 0)

Returns "2014年 12月 31日星期三 " (region identifier specified):

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 547 of 934

Commands

DTOU(`20141231`, "zh_CN", 0)

Output uses long date style

Returns "2014 十二月 31" (no region identifier specified):

DTOU(`20141231`, "zh", 1)

Returns "2014年 12月 31日 " (region identifier specified):

DTOU(`20141231`, "zh_CN", 1)

Remarks
Related functions
DTOU( ) is the inverse of the UTOD( ) function, which converts a Unicode string to a date.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 548 of 934

Commands

EBCDIC( ) function
Returns a string that has been converted to EBCDIC character encoding.

Syntax
EBCDIC(string)

Parameters
Name Type Description

string character The value to convert to EBCDIC.

Output
Character.

Examples
Basic examples
Returns "ñòó@Æ '…@â£K":

EBCDIC("123 Fake St.")

Advanced examples
Creating an EBCDIC-encoded field to export
To create a field containing the EBCDIC encoded value of a Name field for export to an application that
requires EBCDIC encoding, specify the following:

DEFINE FIELD Name_Exp COMPUTED EBCDIC(Name)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 549 of 934

Commands

Remarks
When to use EBCDIC( )
Use this function to convert data to the Extended Binary Coded Decimal Interchange Code (EBCDIC) char-
acter encoding. EBCDIC character encoding is used primarily on IBM mainframe operating systems, such
as z/OS.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 550 of 934

Commands

EFFECTIVE( ) function
Returns the effective annual interest rate on a loan.

Syntax
EFFECTIVE(nominal_rate, periods)

Parameters
Name Type Description

nominal_rate numeric The nominal annual interest rate.

periods numeric The number of compounding periods per year.

Note
Specify an integer. If you specified a decimal portion, it is
truncated.

Output
Numeric. The rate is calculated to eight decimals places.

Examples
Basic examples
Returns 0.19561817 (19.56%), the effective annual rate of interest on the unpaid balance of a credit card
that charges 18% per annum, compounded monthly:

EFFECTIVE(0.18, 12)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 551 of 934

Commands

Remarks
What is the effective annual interest rate?
The effective annual interest rate on a loan is the actual annual rate of interest paid, taking into account
interest on the remaining balance, compounded monthly or daily.

Related functions
The NOMINAL( ) function is the inverse of the EFFECTIVE( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 552 of 934

Commands

EOMONTH( ) function
Returns the date of the last day of the month that is the specified number of months before or after a spe-
cified date.

Syntax
EOMONTH(< date/datetime> <,months>)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value from which to calculate the end-
of-month date. If omitted, the end-of-month date is calculated from the
optional
current operating system date.
Note
You can specify a datetime value for date/datetime but
the time portion of the value is ignored.

months numeric The number of months before or after date/datetime. If omitted, the
default of 0 (zero) is used.
optional
You cannot specify months if you have omitted date/datetime.

Output
Datetime. The date value is output using the current Analytics date display format.

Examples
Basic examples
No input
Returns the last day of the month for the current operating system date:

EOMONTH()

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 553 of 934

Commands

Literal input values

Returns `20140131` displayed as 31 Jan 2014 assuming a current Analytics date display format of
DD MMM YYYY:

EOMONTH(`20140115`)

Returns `20140430` displayed as 30 Apr 2014 assuming a current Analytics date display format of
DD MMM YYYY:

EOMONTH(`20140115`, 3)

Returns `20131031` displayed as 31 Oct 2013 assuming a current Analytics date display format of
DD MMM YYYY:

EOMONTH(`20140115`, -3)

Field input values

Returns the last day of the month that falls three months after each date in the Invoice_date field:

EOMONTH(Invoice_date, 3)

Returns the last day of the month that falls three months after each date in the Invoice_date field plus a
grace period of 15 days:

EOMONTH(Invoice_date + 15, 3)

Returns the first day of the month in which the invoice date falls:

EOMONTH(Invoice_date, -1) + 1

Remarks
Datetime formats
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.
A literal date value must use one of the following formats:
l YYYYMMDD
l YYMMDD

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 554 of 934

Commands

You must enclose literal date values in backquotes. For example: `20141231`

How the months value works

l Positive value – the output date is more recent than the specified date/datetime
l Negative value – the output date is prior to the specified date/datetime
l Value omitted, or '0' (zero) – the output date is the last day of the month in which the date/datetime
occurs

Return the date of the first day of a month

Add 1 day to the result of the EOMONTH( ) function to return the date of the first day of a month.
Returns `20140201` displayed as 01 Feb 2014 assuming a current Analytics date display format of
DD MMM YYYY:

EOMONTH(`20140115`) + 1

Related functions
Use the GOMONTH( ) function if you want to return the exact date, rather than the date of the last day of the
month, that is the specified number of months before or after a specified date.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 555 of 934

Commands

EXCLUDE( ) function
Returns a string that excludes the specified characters.

Syntax
EXCLUDE(string, characters_to_exclude)

Parameters
Name Type Description

string character The value from which to exclude characters.

characters_to_ character The list of characters to exclude.

exclude
If you specify double quotation marks in characters_to_exclude, you
must enclose the list of characters in single quotation marks.
For example: '"-/'

Output
Character.

Examples
Basic examples
Returns " Alberni Street", which is the input string with all numbers excluded:

EXCLUDE("1550 Alberni Street", "0123456789")

Returns all the values in the Product_Number field with the forward slash and number sign excluded:

EXCLUDE(Product_Number, "/#")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 556 of 934

Commands

Remarks
How it works
The EXCLUDE( ) function compares each character in string with the characters listed in characters_to_
exclude. If a match occurs, the character is excluded from the output string.
For example, the output for EXCLUDE("123-45-4536", "-") is "123454536".

No matching characters
If there are no matches between string and characters_to_exclude, then string and the output of the func-
tion are the same.
For example, the output for EXCLUDE("ABC", "D") is "ABC".

Case sensitivity
The EXCLUDE( ) function is case-sensitive. If you specify "ID" in characters_to_exclude, these characters
are not excluded from "id#94022". If there is a chance the case may be mixed, use the UPPER( ) function to
convert string to uppercase.
For example:

EXCLUDE(UPPER("id#94022"), "ID#")

Usage tip
Use EXCLUDE( ) if the set of characters you want to exclude is small, and the set you want to include is
large.

Excluding both single and double quotation marks

Quotation marks are used as string delimiters, therefore to exclude both single and double quotation marks
you must nest EXCLUDE( ) so that there is a single function for each type of quotation mark:

EXCLUDE(EXCLUDE(field_to_process, "'"), '"')

Related functions
The EXCLUDE( ) function is the opposite of the INCLUDE( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 557 of 934

Commands

EXP( ) function
Returns the exponential value (base 10) of a numeric expression with a specified number of decimal
places.

Syntax
EXP(number, decimals)

Parameters
Name Type Description

number numeric The numeric field, expression, or value to return the exponential
value of.

decimals numeric The number of decimals to include in the return value.

Output
Numeric.

Examples
Basic examples
Returns 1000.00:

EXP(3, 2)

Returns 72443.596007:

EXP(4.86, 6)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 558 of 934

Commands

Advanced examples
Finding the cube root
Creates a field that is the cube root of the field X to two decimal places:

DEFINE FIELD cube_root COMPUTED EXP(LOG(X, 6) / 3, 2)

Tip
You can determine the nth root by dividing the log of the value by n and taking the expo-
nential of the result.

Remarks
How it works
This function returns the exponential value (base 10) of a numeric expression, which is defined as 10 raised
to the nth power. For example, the exponential value of 3 is 103, or 1000.

When to use EXP( )

Use EXP( ) for financial applications requiring complex mathematical calculations. EXP( ) performs the
same operation as the exponentiation operator (^), but can be useful in applications that also use the LOG( )
function.

Related functions
The inverse of an exponent is its logarithm, so EXP( ) is the opposite of the LOG( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 559 of 934

Commands

FILESIZE( ) function
Returns the size of the specified file in bytes or -1 if the file does not exist.

Syntax
FILESIZE(filename)

Parameters
Name Type Description

filename character The name of the file.

If the file is in the same folder as the Analytics project, you do not
need to specify the file path.
For files in other folders, specify either a relative path or an absolute
path. For example:
o "results\test_output.fil"
o "c:\results\test_output.fil"
Note
You need to specify the physical data file name (.fil) for
Analytics tables, not the table name.

Output
Numeric.

Examples
Basic examples
Returns 14744:

FILESIZE("Inventory.fil")

If the file you are checking is not in the same folder as the Analytics project, you must specify either the rel-
ative path or absolute path to the file.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 560 of 934

Commands

Returns 6018:

FILESIZE("C:\ACL Data\Sample Data Files\Backup\Ap_Trans.fil")

Advanced examples
Executing a script if a file does not exist
Only executes the script import_data if the file Metaphor_Inventory_2002.fil does not exist:

DO SCRIPT import_data IF FILESIZE("Metaphor_Inventory_2002.fil") = -1

Recording a file's size in the Analytics command log

Use the CALCULATE command to record the size of Metaphor_Inventory_2002.fil in the Ana-
lytics command log:

CALCULATE FILESIZE("Metaphor_Inventory_2002.fil")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 561 of 934

Commands

FIND( ) function
Returns a logical value indicating whether the specified string is present in a particular field, or anywhere in
an entire record.
Note
The FIND( ) function and the "FIND command" on page 204 are two separate Analytics
features with significant differences.

Syntax
FIND(string <,field_to_search_in>)

Parameters
Name Type Description

string character The character string to search for. This search is not case-sensitive.

field_to_search_in character The field, or variable, to search in. If omitted, the entire record is
searched, including any undefined portion of the record.
optional

Output
Logical. Returns T (true) if the specified string value is found, and F (false) otherwise.

Examples
Basic examples
Searching an entire record
Returns T for all records that contain the string "New York" in any field, across any field boundaries, and in
any undefined portion of the record. Returns F otherwise:

FIND("New York")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 562 of 934

Commands

Searching a single field

Returns T for all records that contain the string "New York" in the City field. Returns F otherwise.

FIND("New York", City)

Returns T for all records that contain the string "Ne" in the City field. Returns F otherwise:

FIND("Ne", City)

Returns T for all records that contain the string "New York" preceded by one or more spaces in the City field.
Returns F otherwise:

FIND(" New York", City)

Returns T for all records that have a value in the Description field that matches, or contains, the value in the
v_search_term variable. Returns F otherwise:

FIND(v_search_term, Description)

Searching multiple fields

Returns T for all records that contain the string "New York" in either the City or the City_2 fields. Returns F
otherwise:

FIND("New York", City+City_2)

Returns T for all records that contain the string "New York" in either the City or the City_2 fields. Returns F
otherwise:

FIND("New York", City) OR FIND("New York", City_2)

Combining with other functions

Returns T for all records that have a value in the Last_Name_2 field that matches, or contains, the trimmed
value from the Last_Name field. Returns F otherwise:

FIND(ALLTRIM(Last_Name), Last_Name_2)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 563 of 934

Commands

Remarks
When to use FIND( )
Use the FIND( ) function to test for the presence of the specified string in a field, two or more fields, or an
entire record.

How matching works

The string value can be exactly matched or it can be contained within a longer string. Leading spaces in
fields do not affect the search unless you include one or more leading spaces in the string value.

Search an entire record

If the optional field_to_search_in is not specified, the entire record is searched, including any undefined
portion of the record. Field boundaries are ignored when the entire record is searched, and trailing spaces
in fields are treated as characters.
Note
When you search an entire record, the physical record is searched. Any computed fields
or related fields are not searched.

Search a subset of fields

You can concatenate two or more fields in the field_to_search_in if you want to search in a subset of the
fields in a table. For example, to search both the City and City_2 fields for the string "New York":

FIND("New York", City+City_2)

The concatenated fields are treated like a single field that includes leading and trailing spaces from the indi-
vidual fields, unless you use the ALLTRIM( ) function to remove spaces.
You can also build an expression that searches each field individually:

FIND("New York", City) OR FIND("New York", City_2)

If string includes a leading space, search results from the two approaches can differ.

Case sensitivity and Exact Character Comparisons

The FIND( ) function is not case-sensitive, and finds both ASCII and EBCDIC characters. The function is
not affected by the Exact Character Comparisons option (SET EXACT ON/OFF).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 564 of 934

Commands

Search in a computed field

To search in a computed field you must specify the name of the field in field_to_search_in. For example, if
Vendor_City is a computed field that isolates the city in an address:

FIND("New York", Vendor_City)

Search in a related field

To search in a related field you must specify the fully qualified name of the field (that is, table.field name) in
the field_to_search_in value:

FIND("New York", Vendor.Vendor_City)

Search datetime or numeric data

It is possible to use the FIND( ) function to search datetime or numeric data at the record level. Specifying
the field_to_search_in is not supported for datetime or numeric searching.
The numeric or datetime string must be enclosed in quotation marks, and needs to exactly match the source
data formatting rather than the formatting in the view.
Using the FIND( ) function to search datetime or numeric data in computed or related fields is not supported.
Note
Using the FIND( ) function to search datetime or numeric data is not recommended
because it can be difficult to do successfully.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 565 of 934

Commands

FINDMULTI( ) function
Returns a logical value indicating whether any string in a set of one or more specified strings is present in a
particular field, or anywhere in an entire record.

Syntax
FINDMULTI({search_in|RECORD}, string_1 <,...n>)

Parameters
Name Type Description

search_in | character The field, or variable, to search in.

RECORD
Specify the keyword RECORD to search the entire record, including
any undefined portion of the record.
You can also specify a list of fields by concatenating field names:

Field_1+Field_2+Field_3

string_1 <,...n> character One or more character strings to search for. Separate multiple search
strings with commas:

FINDMULTI(RECORD, "Joa", "Jim", "Joh")

The search is not case-sensitive.

Output
Logical. Returns T (true) if any of the specified string values are found, and F (false) otherwise.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 566 of 934

Commands

Examples
Basic examples
Searching an entire record
Returns T for all records that contain "New York" or "Chicago" in any field, across any field boundaries, and
in any undefined portion of the record. Returns F otherwise:

FINDMULTI(RECORD, "New York", "Chicago")

Searching a single field

Returns T for all records that contain "New York" or "Chicago" in the City field. Returns F otherwise:

FINDMULTI(City, "New York", "Chicago")

Returns T for all records that contain the string "Ne" or "Chi" in the City field. Returns F otherwise:

FINDMULTI(City, "Ne", "Chi")

Returns T for all records that contain "New York" or "Chicago" preceded by one or more spaces in the City
field. Returns F otherwise:

FINDMULTI(City, " New York", " Chicago")

Returns T for all records that have a value in the Description field that matches, or contains, any of the val-
ues in the v_search_term variables . Returns F otherwise:

FINDMULTI(Description, v_search_term_1, v_search_term_2, v_search_term_3)

Searching multiple fields

Returns T for all records that contain the string "New York" or "Chicago" in either the City or the City_2
fields. Returns F otherwise:

FINDMULTI(City+City_2, "New York", "Chicago")

Returns T for all records that contain the string "New York" or "Chicago" in either the City or the City_2
fields. Returns F otherwise:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 567 of 934

Commands

FINDMULTI(City, "New York", "Chicago") OR FINDMULTI(City_2, "New York", "Chicago")

Combining with other functions

Returns T for all records that have a value in the Last_Name_1 field that matches, or contains, the
trimmed value from the Last_Name_2 or Last_Name_3 fields. Returns F otherwise:

FINDMULTI(Last_Name_1, ALLTRIM(Last_Name_2), ALLTRIM(Last_Name_3))

Remarks
When to use FINDMULTI( )
Use the FINDMULTI( ) function to test for the presence of any of the specified strings in a field, two or more
fields, or an entire record.

How matching works

Search an entire record

If you specify RECORD instead of a search_in field, the entire record is searched, including any undefined
portion of the record. Field boundaries are ignored when the entire record is searched, and trailing spaces
in fields are treated as characters.
Note
When you search an entire record, the physical record is searched. Any computed fields
or related fields are not searched.

Search a subset of fields

You can concatenate two or more fields in the search_in parameter if you want to search in a subset of the
fields in a table. For example, to search both the City and the City_2 fields for the strings "New York" or
"Chicago":

FINDMULTI(City+City_2, "New York", "Chicago")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 568 of 934

Commands

FINDMULTI(City, "New York", "Chicago") OR FINDMULTI(City_2, "New York", "Chicago")

If a string value includes a leading space, search results from the two approaches can differ.

Case sensitivity and Exact Character Comparisons

The FINDMULTI( ) function is not case-sensitive, and finds both ASCII and EBCDIC characters. The func-
tion is not affected by the Exact Character Comparisons option (SET EXACT ON/OFF).

Search in a computed field

To search in a computed field you must specify the name of the field in search_in. For example, if Vendor_
City is a computed field that isolates the city in an address:

FINDMULTI(Vendor_City, "New York", "Chicago")

Search in a related field

To search in a related field you must specify the fully qualified name of the field (that is, table.field name) in
the search_in value:

FINDMULTI(Vendor.Vendor_City, "New York", "Chicago")

Search datetime or numeric data

It is possible to use the FINDMULTI( ) function to search datetime or numeric data at the record level, when
specifying RECORD. Specifying a search_in field is not supported for datetime or numeric searching.
The numeric or datetime string values must be enclosed in quotation marks, and need to exactly match the
source data formatting rather than the formatting in the view.
Using the FINDMULTI( ) function to search datetime or numeric data in computed or related fields is not sup-
ported.
Note
Using the FINDMULTI( ) function to search datetime or numeric data is not recommended
because it can be difficult to do successfully.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 569 of 934

Commands

FREQUENCY( ) function
Returns the expected Benford frequency for sequential leading positive numeric digits to a precision of
eight decimal places.

Syntax
FREQUENCY(digit_string)

Parameters
Name Type Description

digit_string character A character string containing digits (0-9) to identify the frequency for.
digit_string must be a positive number, and leading zeros are
ignored.

Output
Numeric.

Examples
Basic examples
Returns 0.00998422:

FREQUENCY("43")

Returns 0.00000000:

FREQUENCY("87654321")

Note
The result is 0.00000000495, but because Analytics computes to a precision of eight
decimal places, a zero value is returned.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 570 of 934

Commands

Remarks
How it works
FREQUENCY( ) returns the expected Benford frequency for sequential leading positive numeric digits to a
precision of eight digits. It lets you perform limited Benford tests for specific situations.

Using this function for specific digit combinations

You can use this function instead of the BENFORD command if you want to focus on specific digit com-
binations. For example, when auditing insurance claims that have approval limits at specified claim
amounts, you could use the FREQUENCY( ) function to investigate amounts just under an approval
threshold.
To investigate claims valued close to an approval limit of $5,000, you could select the range from $4,900
through $4,999. First, count the total number of records, then use a filter to count the records for which
LEADING( ) returns 49, and compare the ratio of the two counts to the value you get for FREQUENCY
("49").
This is faster than running a complete analysis on a table of a million records, and it does not generate a
large table or lengthy entries in the command log.

Specifying strings longer than six digits

Specifying strings longer than six digits can result in zero values. Calculations for strings longer than six
digits may require greater precision than Analytics's limit of eight decimal places.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 571 of 934

Commands

FTYPE( ) function
Returns a character identifying the data category of a field or variable, or the type of an Analytics project
item.

Syntax
FTYPE(field_name_string)

Parameters
Name Type Description

field_name_string character A field name, variable name, or Analytics project item name.
Enclose field_name_string in quotation marks:

FTYPE("Amount")

Output
Character. This function returns one of the following characters, which indicates the field, variable, or Ana-
lytics project item type:
l "C" – Character field
l "N" – Numeric field
l "D" – Datetime field
l "L" – Logical field
l "c" – Character variable
l "n" – Numeric variable
l "d" – Datetime variable
l "l" – Logical variable
l "b" – Analytics script
l "y" – Analytics table layout
l "w" – Analytics workspace
l "i" – Analytics index
l "r" – Analytics report
l "a" – Analytics log file
l "U" – Undefined

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 572 of 934

Commands

Examples
Basic examples
The following example assigns a value of 4 to the num variable and then checks the type.
Returns "n":

ASSIGN num = 4
FTYPE("num")

Advanced examples
Testing for the data type of a field
You have a script or analytic that requires a numeric Amount field, and you need to test that the field is the
correct type before running the script.
The following command only runs Script_1 if Amount is a numeric field:

OPEN Invoices
DO Script_1 IF FTYPE("Amount") = "N"

Testing if a table or Analytics project item exists

The following command only runs Script_1 if a table named Invoices is present in the project:

DO Script_1 IF FTYPE("Invoices") <> "U"

Testing the runtime environment

You can use FTYPE to determine if an analytic is running in Analytics, or on Analytics Exchange or in the
Analysis App window.
If an analytic is running on Analytics Exchange, or in the Analysis App window, 'ax_main' is equal to 'b':

IF FTYPE('ax_main') = 'b' v_running_in_ax_or_analysis_app = T

If an analytic is running in Analytics, 'ax_main' is not equal to 'b':

IF FTYPE('ax_main') <> 'b' v_running_in_ax_or_analysis_app = F

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 573 of 934

Commands

The ability to detect the runtime environment allows you to design a single script that executes different
blocks of codes depending on which application it is running in.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 574 of 934

Commands

FVANNUITY( ) function
Returns the future value of a series of payments calculated using a constant interest rate. Future value is the
sum of the payments plus the accumulated compound interest.

Syntax
FVANNUITY(rate, periods, payment <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of payment periods.

payment numeric The payment per period.

The payment amount must remain constant over the term of the annu-
ity.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Note
You must use consistent time periods when specifying rate, periods, and payment to
ensure that you are specifying interest rate per period.
For example:
l for a monthly payment on a two-year loan or investment with interest of 5% per
annum, specify 0.05/12 for rate and 2 * 12 for periods
l for an annual payment on the same loan or investment, specify 0.05 for rate and 2 for
periods

Output
Numeric. The result is calculated to two decimal places.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 575 of 934

Commands

Examples
Basic examples
Monthly payments
Returns 27243.20, the future value of $1,000 paid at the beginning of each month for 2 years at 1% per
month, compounded monthly:

FVANNUITY(0.01, 2*12, 1000, 1)

Returns 12809.33, the future value of the same annuity after the first year:

FVANNUITY(0.01, 12, 1000, 1)

Annual payments
Returns 25440.00, the future value of $12,000 paid at the end of each year for 2 years at 12% per annum,
compounded annually:

FVANNUITY(0.12, 2, 12000, 0)

Advanced examples
Annuity calculations
Annuity calculations involve four variables:
l present value, or future value – $21,243.39 and $ 26,973.46 in the examples below
l payment amount per period – $1,000.00 in the examples below
l interest rate per period – 1% per month in the examples below
l number of periods – 24 months in the examples below
If you know the value of three of the variables, you can use an Analytics function to calculate the fourth.

I want to find: Analytics function to use:

PVANNUITY( )
Returns 21243.39:

PVANNUITY(0.01, 24, 1000)

Present value

Future value FVANNUITY( )

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 576 of 934

Commands

I want to find: Analytics function to use:

Returns 26973.46:

FVANNUITY(0.01, 24, 1000)

PMT( )
Returns 1000:

PMT(0.01, 24, 21243.39)

Payment amount per period

RATE( )
Returns 0.00999999 (1%):

RATE(24, 1000, 21243.39)

Interest rate per period

NPER( )
Returns 24.00:

NPER(0.01, 1000, 21243.39)

Number of periods

Annuity formulas
The formula for calculating the present value of an ordinary annuity (payment at the end of a period):

The formula for calculating the future value of an ordinary annuity (payment at the end of a period):

Remarks
Related functions
The PVANNUITY( ) function is the inverse of the FVANNUITY( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 577 of 934

Commands

FVLUMPSUM( ) function
Returns the future value of a current lump sum calculated using a constant interest rate.

Syntax
FVLUMPSUM(rate, periods, amount)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of periods.

amount numeric The investment made at the start of the first period.

Output
Numeric. The result is calculated to two decimal places.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 578 of 934

Commands

Examples
Basic examples
Interest compounded monthly
Returns 1269.73, the future value of a lump sum of $1,000 invested for 2 years at 1% per month, com-
pounded monthly:

FVLUMPSUM(0.01, 2*12, 1000)

Returns 1126.83, the future value of the same investment after the first year:

FVLUMPSUM(0.01, 12, 1000)

Returns 27243.20, the future value of $21,455.82 invested for 2 years at 1% per month, compounded
monthly:

FVLUMPSUM(0.01, 2*12, 21455.82)

Interest compounded semi-annually

Returns 1262.48, the future value of a lump sum of $1,000 invested for 2 years at 12% per annum, com-
pounded semi-annually:

FVLUMPSUM(0.12/2, 2*2, 1000)

Interest compounded annually

Returns 1254.40, the future value of a lump sum of $1,000 invested for 2 years at 12% per annum, com-
pounded annually:

FVLUMPSUM(0.12, 2, 1000)

Remarks
What is future value?
The future value of an invested lump sum is the initial investment principal plus the accumulated compound
interest.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 579 of 934

Commands

Related functions
The PVLUMPSUM( ) function is the inverse of the FVLUMPSUM( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 580 of 934

Commands

FVSCHEDULE( ) function
Returns the future value of a current lump sum calculated using a series of interest rates.

Syntax
FVSCHEDULE(principal, rate1 <,rate2...>)

Parameters
Name Type Description

principal numeric The amount of the initial investment.

rate1, rate2... numeric A series of interest rates for equal-length periods.

Note
The periods can represent months or years, or some
other time period, as long as the type of time period is
consistent.
You must specify the interest rates per period. So, if one
of the interest rates is 5% per annum and the periods are
months, specify 0.05/12.

Output
Numeric. The result is calculated to two decimal places.

Examples
Basic examples
Returns 1282.93, the future value of a lump sum of $1000 invested for 3 years at 10% for the first year, 9%
for the second year, and 7% for the third year, compounded annually:

FVSCHEDULE(1000, 0.1, 0.09, 0.07)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 581 of 934

Commands

Remarks
The future value of an invested lump sum is the initial investment principal plus the accumulated com-
pound interest.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 582 of 934

Commands

GETOPTIONS( ) function
Returns the current setting for the specified Analytics option (Options dialog box setting).

Syntax
GETOPTIONS(option)

Parameters
Name Type Description

option character The Analytics option to return a setting for.

The name of the option must be specified exactly as it appears in the
list below, and it must be enclosed in quotation marks:
o separators – returns the current settings for the three Analytics sep-
arator characters, in the following order:
l decimal place symbol
l thousands separator
l list separator
Note
Currently, "separators" is the only option that can be spe-
cified for the GETOPTIONS( ) function.

Output
Character.

Examples
Basic examples
Returns the current settings for the three Analytics separator characters. For example, ".,,":

GETOPTIONS("separators")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 583 of 934

Commands

Advanced examples
Using GETOPTIONS( ) in a script
If a script needs to change one or more of the Analytics separator characters, the GETOPTIONS( ) func-
tion provides a method for discovering the current settings. The current settings can be stored in a variable
and then reinstated at the end of the script.

ASSIGN v_SeparatorsSetting = GETOPTIONS("separators")
SET SEPARATORS ",.;"
< script content>
SET SEPARATORS "%v_SeparatorsSetting%"

Remarks
The three Analytics separator characters are specified in the following options in the Options dialog box:
l Decimal Place Symbol
l Thousands Separator
l List Separator

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 584 of 934

Commands

GOMONTH( ) function
Returns the date that is the specified number of months before or after a specified date.

Syntax
GOMONTH(date/datetime, months)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value from which to calculate the output
date.

months numeric The number of months before or after date/datetime.

Note
You can specify a datetime value for date/datetime but
the time portion of the value is ignored.

Output
Datetime. The date value is output using the current Analytics date display format.

Examples
Basic examples
Literal input values
Returns `20140415` displayed as 15 Apr 2014 assuming a current Analytics date display format of
DD MMM YYYY:

GOMONTH(`20140115`, 3)

Returns `20131015` displayed as 15 Oct 2013 assuming a current Analytics date display format of
DD MMM YYYY:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 585 of 934

Commands

GOMONTH(`20140115`, -3)

Returns `20140430` displayed as 30 Apr 2014 assuming a current Analytics date display format of
DD MMM YYYY (date rounding prevents returning 31 Apr 2014, which is an invalid date):

GOMONTH(`20140330`, 1)

GOMONTH(`20140331`, 1)

Returns `20140501` displayed as 01 May 2014 assuming a current Analytics date display format of
DD MMM YYYY:

GOMONTH(`20140401`, 1)

Field input values

Returns the date three months after each date in the Invoice_date field:

GOMONTH(Invoice_date, 3)

Returns the date three months after each date in the Invoice_date field plus a grace period of 15 days:

GOMONTH(Invoice_date + 15, 3)

How the months value works

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 586 of 934

Commands

Date rounding to avoid non-existent dates

If the combination of date/datetime and months would produce a non-existent date, the GOMONTH( ) func-
tion uses 'date rounding' to return the closest valid date within the same month.
Returns `20140430` (30 Apr 2014) because 31 Apr 2014 is an invalid date:

GOMONTH(`20140331`,1)

Related functions
Use the EOMONTH( ) function if you want to return the date of the last day of the month, rather than the
exact date, that is the specified number of months before or after a specified date.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 587 of 934

Commands

HASH( ) function
Returns a salted cryptographic hash value based on the input value.

Syntax
HASH(field <,salt_value>)

Parameters
Name Type Description

field character The value to hash.

numeric
datetime
logical

salt_value character The salt value to use. You can specify a PASSWORD identifier num-
ber from 1 to 10, or a character string.
optional numeric
If omitted, the Analytics default salt value is used.
The salt value is limited to 128 characters, and is automatically trun-
cated to 128 characters if you specify a longer salt value.
For more information, see "The salt value" on page 591.

Output
Character.

Examples
Basic examples
With the Analytics default salt value
Returns "819A974BB91215D58E7753FD5A42226150100A0763087CA7DECD93F3C3090405":

HASH("555-44-3322")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 588 of 934

Commands

Returns the hash value for each number in the Credit_card_num field:

HASH(Credit_card_num)

With a user-specified salt value

Returns "AD1E7D9B97B6F6B5345AB13471A74C31EBE6630CA2622BB7E8C280E9FBEE1F17":

HASH("555-44-3322", "my salt value 123")

Advanced examples
Ensuring hash values are identical
Use other functions in conjunction with HASH( ) to standardize clear text values that should produce
identical hash values.
Consider the following set of examples. Note how the case of the clear text values completely alters the out-
put hash value in the first two examples.
Returns "DF6789E1EC65055CD9CA17DD5B0BEA5892504DFE7661D258737AF7CB9DC46462":

HASH("John Smith")

Returns "3E12EABB5940B7A2AD90A6B0710237B935FAB68E629907927A65B3AA7BE6781D":

HASH("JOHN SMITH")

By using the UPPER( ) function to standardize case, an identical hash value results.
Returns "3E12EABB5940B7A2AD90A6B0710237B935FAB68E629907927A65B3AA7BE6781D":

HASH(UPPER("John Smith"))

Using HASH( ) to compare large blocks of text

Use HASH( ) to test if blocks of text in two comment fields are identical.
To perform this test, create two computed fields similar to the ones shown below, and then create a filter to
find any text blocks that are not identical.

DEFINE FIELD Hash_1 COMPUTED HASH(Comment_Field_1)

DEFINE FIELD Hash_2 COMPUTED HASH(Comment_Field_2)
SET FILTER TO Hash_1 <> Hash_2

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 589 of 934

Commands

If the comment fields are in separate tables, create a computed HASH( ) field in each table and then use
the computed fields as a common key field to do an unmatched join of the two tables. The records in the
joined output table represent text blocks that are not identical.

Remarks
When to use HASH( )
Use the HASH( ) function to protect sensitive data, such as credit card numbers, salary information, or
social security numbers.

How it works
HASH( ) provides one-way encoding. Data in clear text can be used to produce a hash value, however the
hash value cannot subsequently be unencoded or decrypted.
A specific clear text value always produces the same hash value, so you can search a field of hashed
credit card numbers for duplicates, or join two fields of hashed credit card numbers, and the results are the
same as if you had performed the operation on the equivalent clear text fields.

Protecting sensitive data

To avoid storing sensitive data on a server, you can create a computed field locally using the HASH( ) func-
tion, and then create a new table by extracting the hashed field and any other required fields, while exclud-
ing the clear text field. You can use the new table on the server for your analysis, and once you have the
results, refer back to the original table if you need to see the clear text version of any of the hashed data.
If storing sensitive data locally, beyond initial use, is prohibited, you can delete the original table after you
have created the new table with the hashed values, and refer to the original source system for the clear
text values.

Clear text values must be exactly identical

In order to produce identical hash values, two clear text values must be exactly identical. For example, dif-
ferent hash values result from the same credit card number with or without hyphens, or the same name in
title case or all upper case.
You may need to incorporate functions such as INCLUDE( ), EXCLUDE( ), or UPPER( ) in the HASH( )
function to standardize clear text values.
Leading and trailing blanks are automatically trimmed by the HASH( ) function, so there is no need to use
the TRIM( ) or ALLTRIM( ) functions.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 590 of 934

Commands

What if leading or trailing blanks are meaningful?

If you have data in which leading or trailing blanks represent meaningful differences between values you
need to replace the blanks with another character before hashing the values.
Replaces blanks in the field values with the underscore character (_) before hashing:

HASH(REPLACE(field_name, " ", "_"))

The cryptographic algorithm used by HASH( )

HASH( ) uses an SHA-2 cryptographic hash algorithm that produces a fixed-length hashed output of 64
bytes, regardless of the length of the input value. The clear text input value can be longer than 64 bytes.

The salt value

How it works
The protection offered by the HASH( ) function is strengthened by the automatic addition of a salt value prior
to hashing. The salt value is an alphanumeric string that is concatenated with the source data value. The
entire concatenated string is then used to produce the salted, hashed value. This approach makes the
hashed values more resistant to decoding techniques.

Optionally specify your own salt value

A fixed, default salt value is automatically used unless you specify a salt value. You can use either of the fol-
lowing methods to specify a salt value:
l Salt value as clear text string
Specify an alphanumeric string. For example:

HASH(Credit_card_num, "my salt value")

l Salt value as password

Use the PASSWORD command in conjunction with the HASH( ) function and specify a PASSWORD
identifier number from 1 to 10. For example:

PASSWORD 3 "Enter a salt value"

EXTRACT FIELDS HASH(Credit_card_num, 3) TO "Protected_table"

Note
The PASSWORD salt value must be entered before the field in the HASH( ) function
can be extracted.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 591 of 934

Commands

The benefit of using a PASSWORD identifier number with HASH( ) is that you do not have to
expose a clear text salt value.
For more information, see "PASSWORD command" on page 350.

Password method guidelines

The password method is intended for use in scripts that prompt for the password at the beginning of the
script, or prior to the HASH( ) function appearing in the script.
The password method is not suitable for use in computed fields because PASSWORD assignments are
deleted when you close Analytics.
In addition, computed fields that use a password-based salt value are automatically removed from views
when you reopen Analytics. This removal is necessary to avoid the recalculation of hash values using the
default salt value. The recalculated values would differ from the original hash values calculated with a
user-supplied salt value.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 592 of 934

Commands

HEX( ) function
Converts an ASCII string to a hexadecimal string.

Syntax
HEX(field)

Parameters
Name Type Description

field character The ASCII string to convert to a hexadecimal string.

Output
Character.

Examples
Basic examples
Returns "3132333435":

HEX("12345")

Returns the values in the Count field as hexadecimal strings:

HEX(Count)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 593 of 934

Commands

Remarks
How it works
This function returns the hexadecimal string that is equivalent to the field value or expression you specify.
You can use the function when you need to identify the exact contents of a field, including characters that
cannot be displayed on screen, such as CR (carriage return), LF (line feed), and NUL (null).

Return value length

The return value is a string that is double the length of the field value. The digits 0 to 9 and the letters A to F
(for the digits 10 to 15) represent the 16 hexadecimal values.

Use fields as input rather than expressions

In general, you should apply this function to fields rather than expressions because it displays a rep-
resentation of the internal storage format of expressions, which is not meaningful in most instances.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 594 of 934

Commands

HOUR( ) function
Extracts the hour from a specified time or datetime and returns it as a numeric value using the 24-hour
clock.

Syntax
HOUR(time/datetime)

Parameters
Name Type Description

time/datetime datetime The field, expression, or literal value to extract the hour from.

Output
Numeric.

Examples
Basic examples
Returns 23:

HOUR(`t235959`)

HOUR(`20141231 235959`)

Returns the hour for each value in the Call_start_time field:

HOUR(Call_start_time)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 595 of 934

Commands

Remarks
Parameter details
A field specified for time/datetime can use any time or datetime format, as long as the field definition cor-
rectly defines the format.
Specifying a literal time or datetime value
When specifying a literal time or datetime value for time/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231 235959`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Time values – you can use any of the time formats listed in the table below. You must use a sep-
arator before a standalone time value for the function to operate correctly. Valid separators are the
letter 't', or the letter 'T'. You must specify times using the 24-hour clock. Offsets from Coordinated
Universal Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).
l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.

Example formats Example literal values

thhmmss `t235959`

Thhmm `T2359`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 596 of 934

Commands

HTOU( ) function
Converts a hexadecimal string to a Unicode string. Abbreviation for "Hexadecimal to Unicode".
Note
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.

Syntax
HTOU(hex_string)

Parameters
Name Type Description

hex_string character The hexadecimal string to convert to a Unicode string. The string can
only contain hexadecimal values, for example "20AC".

Output
Character.

Examples
Basic examples
Returns "ABC123":

HTOU("004100420043003100320033")

Advanced examples
Adding a currency symbol to a value
You need to extract a monetary field to a new table. The field should display the numeric Amount field's

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 597 of 934

Commands

value and prepend it with a Euro currency symbol (€):

EXTRACT HTOU("20AC") + STRING(Amount, 10) AS "Currency_Amount" TO Display_Table

When the EXTRACT command runs, HTOU( ) returns the Euro symbol "€" and concatenates it with the
Amount value that STRING( ) converts to a character. If the original value of Amount was 2000, then the
value in Currency_Amount is "€2000".

Remarks
Related functions
HTOU( ) is the inverse of the DHEX( ) function, which converts a Unicode string to a hexadecimal string.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 598 of 934

Commands

INCLUDE( ) function
Returns a string that includes only the specified characters.

Syntax
INCLUDE(string, characters_to_include)

Parameters
Name Type Description

string character The value to restrict to included characters.

characters_to_ character The list of characters to include.

include
If you specify double quotation marks in characters_to_include, you
must enclose the list of characters in single quotation marks.
For example: '"-/'
Note
If a character you specify to include does not appear in
string, it is not included in the return value.

Output
Character.

Examples
Basic examples
Returns "123", which is the input string with only numbers included:

INCLUDE("123 Main St.", "0123456789")

Returns "1231234", which is the input string with only numbers included:

INCLUDE("123-123-4", "1243")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 599 of 934

Commands

Returns "" (nothing), because the input string does not contain "D":

INCLUDE("ABC", "D")

Remarks
How it works
The INCLUDE( ) function compares each character in string with the characters listed in characters_to_
include. If a match occurs, the character is included in the output string.

No matching characters
If there are no matches between string and characters_to_include the output of the function is blank.

Case sensitivity
The INCLUDE( ) function is case-sensitive. If you specify "ID" in characters_to_include, these characters
are not included in "id#94022". If there is a chance the case may be mixed, use the UPPER( ) function to
convert string to uppercase.
For example:

INCLUDE(UPPER("id#94022"), "ID0123456789")

Usage tip
Use INCLUDE( ) if the set of characters you want to include is small, and the set you want to exclude is
large.

Related functions
The INCLUDE( ) function is the opposite of the EXCLUDE( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 600 of 934

Commands

INSERT( ) function
Returns the original string with specified text inserted at a specific byte location.

Syntax
INSERT(string, insert_text, location)

Parameters
Name Type Description

string character The value to insert the text into.

insert_text character The text to insert.

location numeric The character position at which to insert insert_text into the string.

Output
Character.

Examples
Basic examples
Returns "aXXXbcde":

INSERT("abcde", "XXX", 2)

Returns "XXXabcde":

INSERT("abcde", "XXX", 0)

Returns "abcdeXXX", with "XXX" inserted at byte position 6 instead of 8, because "abcde" is only 5 bytes
long::

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 601 of 934

Commands

INSERT("abcde", "XXX", 8)

Remarks
How it works
The INSERT( ) function inserts specified characters or spaces into a character string, beginning at a spe-
cified position in the string.

When to use INSERT( )

Use INSERT( ) to normalize data for formatting, for duplicate matching, and for the JOIN and DEFINE
RELATION commands, which require identical fields.
For example, part numbers in one file may be in the format "12345", and in another file, "12-345." In the
first file, you can use INSERT( ) to insert a hyphen (-) in position 3.

Location guidelines
l If the location value is greater than the length of string, the insert_text value is inserted at the end of
the string.
l If location is 0 or 1, insert_text is inserted at the beginning of the string.

Inserting double quotation marks

If you specify double quotation marks in insert_text, you must enclose them in single quotation marks.
For example: '"'

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 602 of 934

Commands

INT( ) function
Returns the integer value of a numeric expression or field value.

Syntax
INT(number)

Parameters
Name Type Description

number numeric The field or numeric expression to convert to an integer. If the value
specified includes decimals, the decimals are truncated without round-
ing.

Output
Numeric.

Examples
Basic examples
Returns 7:

INT(7.9)

Returns -7:

INT(-7.9)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 603 of 934

Commands

IPMT( ) function
Returns the interest paid on a loan for a single period.

Syntax
IPMT(rate, specified_period, periods, amount <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

specified_period numeric The period for which you want to find the interest payment.

periods numeric The total number of payment periods.

amount numeric The principal amount of the loan.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Output
Numeric.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 604 of 934

Commands

Examples
Basic examples
Returns 1489.58, the interest paid in the first month of a twenty-five year, $275,000 loan at 6.5% per annum,
with payments due at the end of the month:

IPMT(0.065/12, 1, 12*25, 275000, 0)

Returns 10.00, the interest paid on the same loan in the last month of the loan:

IPMT(0.065/12, 300, 12*25, 275000, 0)

Remarks
Related functions
The PPMT( ) function is the complement of the IPMT( ) function.
The CUMIPMT( ) function calculates interest paid during a range of periods.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 605 of 934

Commands

ISBLANK( ) function
Returns a logical value indicating whether the input value is blank.

Syntax
ISBLANK(string)

Parameters
Name Type Description

string character The value to test for blank data.

Output
Logical. Returns T (true) if the string parameter value is blank, and F (false) otherwise.

Examples
Basic examples
Returns F:

ISBLANK(" A")

Returns T:

ISBLANK(" ")

ISBLANK("")

Returns T for all values in the Address field that are blank, and F otherwise:

ISBLANK(Address)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 606 of 934

Commands

Remarks
When to use ISBLANK( )
Use ISBLANK( ) during the data integrity phase of an analysis project to identify fields with missing data,
which may indicate issues with the source data.

What is blank input?

For the function to evaluate to true, the input value must be one of the following:
l entirely blank (that is, contain only spaces)
l a zero-length string
The function only identifies true blanks in source data, not invalid characters that appear as blanks in a view.

Null characters
ISBLANK( ) may not return useful results when used with character fields that contain null characters. Ana-
lytics uses the null character to indicate the end of a string, and for this reason the ISBLANK( ) function will
not read any character data that follows a null character, including blanks.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 607 of 934

Commands

ISDEFINED( ) function
Returns T (true) if the specified field or variable is defined, and F (false) otherwise.

Syntax
ISDEFINED(string)

Parameters
Name Type Description

string character The name of the field or variable to check for the existence of. The
value must be entered as a quoted string:

ISDEFINED("v_numeric_limit")

Output
Logical.

Examples
Basic examples
Returns T if v_numeric_limit is defined as a variable or field, otherwise returns F:

ISDEFINED("v_numeric_limit")

Advanced examples
Using ISDEFINED( ) to test a field
The following example uses the ISDEFINED( ) function to test if the Limit field is defined in the table before
extracting records based on the value in the field:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 608 of 934

Commands

OPEN Metaphor_Employees_US
IF ISDEFINED("Limit") EXTRACT RECORD IF Limit > 50000 TO "HighLimit.fil"

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 609 of 934

Commands

ISFUZZYDUP( ) function
Returns a logical value indicating whether a string is a fuzzy duplicate of a comparison string.

Syntax
ISFUZZYDUP(string1, string2, levdist <,diffpct>)

Parameters
Name Type Description

string1 character The first string in the comparison.

string2 character The second string in the comparison.

levdist numeric The maximum allowable Levenshtein distance between the two
strings for them to be identified as fuzzy duplicates.
The levdist value cannot be less than 1 or greater than 10.
Increasing the levdist value increases the number of results by includ-
ing values with a greater degree of fuzziness – that is, values that are
more different from each another.

diffpct numeric The upper threshold for the 'difference percentage'.

optional Difference percentage is explained in "How it works" on page 612.
The diffpct value cannot be less than 1 or greater than 99.
Increasing the diffpct value increases the number of results by includ-
ing values with a greater proportion of difference relative to their
length.
If omitted, difference percentage is not considered during processing
of the ISFUZZYDUP( ) function.

Output
Logical. Returns T (true) if string values are fuzzy duplicates, and F (false) otherwise.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 610 of 934

Commands

Examples
Basic examples
Returns F, because two edits are required to transform "Smith" into "Smythe", but the levdist value is only 1:

ISFUZZYDUP("Smith","Smythe", 1, 99)

Returns T, because two edits are required to transform "Smith" into "Smythe", and the levdist value is 2:

ISFUZZYDUP("Smith","Smythe", 2, 99)

Returns T, because zero edits are required to transform "SMITH" into "smith", and the levdist value is 1 (the
ISFUZZYDUP( ) function is not case-sensitive):

ISFUZZYDUP("SMITH","smith", 1, 99)

Returns a logical value (T or F) indicating whether individual values in the Last_Name field are fuzzy duplic-
ates for the string "Smith":

ISFUZZYDUP(Last_Name,"Smith", 3, 99)

Advanced examples
Working with difference percentage
The difference percentage gives you a tool for reducing the number of false positives returned by
ISFUZZYDUP( ).
No diffpct specified
Returns T, because five edits are required to transform "abc" into "Smith", and the levdist value is 5:

ISFUZZYDUP("abc", "Smith", 5)

diffpct specified
Returns F, even though "abc" is within the specified Levenshtein distance of "Smith", because 5 edits/a
string length of 3 results in a difference percentage of 167%, which exceeds the specified diffpct of 99%:

ISFUZZYDUP("abc", "Smith", 5, 99)

Difference percentage is fully explained in "How it works" on the next page.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 611 of 934

Commands

Isolating fuzzy duplicates for "Smith"

Create a filter that isolates all values in the Last_Name field that are fuzzy duplicates for "Smith":

SET FILTER TO ISFUZZYDUP(Last_Name, "Smith", 3, 99)

Changing the levdist or diffpct values allows you to adjust the amount of difference in the filtered values.

Remarks
When to use ISFUZZYDUP( )
Use the ISFUZZYDUP( ) function to find nearly identical values (fuzzy duplicates) or locate inconsistent
spelling in manually entered data.

How it works
The ISFUZZYDUP( ) function calculates the Levenshtein distance between two strings, and calculates the
difference percentage.
ISFUZZYDUP( ) evaluates to T (true) if:
l The Levenshtein distance is less than or equal to the levdist value.
l The difference percentage is less than or equal to the diffpct value (if specified).

Levenshtein distance
The Levenshtein distance is a value representing the minimum number of single character edits required
to make one string identical to the other string.
For more information, see "LEVDIST( ) function" on page 620.

Difference percentage
The difference percentage is the percentage of the shorter of the two evaluated strings that is different.
The difference percentage is the result of the following internal Analytics calculation, which uses the Leven-
shtein distance between the two strings:
Levenshtein distance / number of characters in the shorter string × 100 = difference percentage
Using the optional difference percentage helps reduce the number of false positives returned by
ISFUZZYDUP( ):
l The upper threshold for diffpct is 99%, which prevents the entire replacement of a string in order to
make it identical.
l Strings that require a large number of edits in relation to their length are excluded.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 612 of 934

Commands

Usage tips
l Case-sensitivity – The function is not case-sensitive, so "SMITH" is equivalent to "smith."
l Trailing blanks – The function automatically trims trailing blanks in fields, so there is no need to use
the TRIM( ) function when specifying a field as a parameter.
l Removing generic elements – The OMIT( ) function can improve the effectiveness of the
ISFUZZYDUP( ) function by removing generic elements such as "Corporation" or "Inc." from field val-
ues.
Removal of generic elements focuses the ISFUZZYDUP( ) string comparison on just the portion of
the strings where a meaningful difference may occur.

How the FUZZYDUP command and the ISFUZZYDUP( )

function differ
The FUZZYDUP command identifies all fuzzy duplicates in a field, organizes them in groups, and outputs
non-exhaustive results.
The ISFUZZYDUP( ) function identifies an exhaustive list of fuzzy duplicates for a single character value.
The command and the function both identify exact duplicates. Unlike the command, you cannot exclude
exact duplicates when using the function.

What exhaustive means

Exhaustive means that all values within the specified degree of difference of the test value are returned,
regardless of their position in the test field relative to the test value.
The ISFUZZYDUP( ) function is useful if the non-exhaustive results produced by the FUZZYDUP command
are not sufficient for the purposes of your analysis, and you need to directly scrutinize every fuzzy duplicate
for a specific character value.

Related functions
l LEVDIST( ) – provides an alternate method for comparing strings based on Levenshtein distance.
Unlike ISFUZZYDUP( ), LEVDIST( ) is case-sensitive by default.
l DICECOEFFICIENT( ) – de-emphasizes or completely ignores the relative position of characters or
character blocks when comparing strings.
l SOUNDSLIKE( ) and SOUNDEX( ) – compare strings based on a phonetic comparison (sound)
rather than on an orthographic comparison (spelling).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 613 of 934

Commands

LAST( ) function
Returns a specified number of characters from the end of a string.

Syntax
LAST(string, length)

Parameters
Name Type Description

string character The value to return the characters from.

length numeric The number of characters to return.

Output
Character.

Examples
Basic examples
Returns "Savings":

LAST("Account Type: Savings", 7)

Returns "efghi":

LAST("abcdefghi", 5)

Returns "fghi ":

LAST("abcdefghi ", 5)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 614 of 934

Commands

Returns " abc", because the string value is shorter than the specified length of 6, so leading spaces are
added to the output:

LAST("abc", 6)

Remarks
Blank results caused by trailing spaces
Trailing spaces in string can cause the results produced by the LAST( ) function to be blank.
For example, the output for LAST("6483-30384 ", 3) is " ".
You can use the ALLTRIM( ) function in conjunction with LAST( ) to remove any trailing spaces in string.
For example, LAST(ALLTRIM("6483-30384 "), 3) returns "384".

Returning characters from the start of a string

If you want to return a specified number of characters from the start of a string, use the SUBSTR( ) function.
For more information, see "SUBSTR( ) function" on page 796.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 615 of 934

Commands

LEADING( ) function
Returns a string containing a specified number of leading digits.

Syntax
LEADING(number, leading_digits)

Parameters
Name Type Description

number numeric The value to return the leading digits from.

leading_digits numeric The number of leading digits to be returned.

Output
Character.

Examples
Basic examples
Literal numeric input
Returns 623:

LEADING(6234.56, 3)

Returns 62345:

LEADING(-6234.56, 5)

Padding with trailing zeros

Returns 000:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 616 of 934

Commands

LEADING(0.00, 3)

Returns 00000:

LEADING(0.00, 5)

Returns 35500:

LEADING(3.55, 5)

Remarks
Use LEADING( ) to extract digits from a numeric field as a string, and filter out non-digit elements such as
decimals or dollar signs.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 617 of 934

Commands

LENGTH( ) function
Returns the number of characters in a string.

Syntax
LENGTH(string)

Parameters
Name Type Description

string character The value to find the length of.

Output
Numeric.

Examples
Basic examples
Returns 15:

LENGTH("ABC Corporation")

Returns the length in characters of the Description field in the table layout:

LENGTH(Description)

Advanced examples
Displaying the length of each address in an address field
Create a computed field that displays the length in characters of each address in the Vendor_Street field.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 618 of 934

Commands

Leading and trailing blank spaces are first trimmed from the address values so they are not counted in the
length.

DEFINE FIELD Address_Length COMPUTED LENGTH(ALLTRIM(Vendor_Street))

Remarks
How it works
The LENGTH( ) function counts the number of characters in string, including any spaces, and returns the
number.

Trailing spaces
Trailing spaces are counted as characters. If you do not want trailing spaces to be counted, use the TRIM( )
or ALLTRIM( ) functions to remove them. For example:

LENGTH(TRIM(Vendor_Street))

If you create a computed field to display the length of the values in a field, and you do not remove trailing
spaces, the maximum length of the field is displayed for each value.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 619 of 934

Commands

LEVDIST( ) function
Returns the Levenshtein distance between two specified strings, which is a measurement of how much the
two strings differ.

Syntax
LEVDIST(string1, string2 <,case_sensitive>)

Parameters
Name Type Description

string1 character The first string in the comparison.

string2 character The second string in the comparison.

case_sensitive logical Specify T for a case-sensitive comparison of strings, or F to ignore

case.
optional
If omitted, the default value of T is used.

Output
Numeric. The value is the Levenshtein distance between two strings.

Examples
Basic examples
Returns 3, because two substitutions and one insertion are required to transform "smith" into "Smythe":

LEVDIST("smith","Smythe")

Returns 2, because case is ignored, so only two substitutions are required to transform "smith's" into
"Smythes":

LEVDIST("smith's","Smythes",F)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 620 of 934

Commands

Returns the Levenshtein distance between each value in the Last_Name field and the string "Smith":

LEVDIST(TRIM(Last_Name),"Smith")

Advanced examples
Ranking values against "Smith"
Create the computed field Lev_Dist to display the Levenshtein distance between "Smith" and each value in
the Last_Name field:

DEFINE FIELD Lev_Dist COMPUTED LEVDIST(TRIM(Last_Name),"Smith", F)

Add the computed field Lev_Dist to the view, and then quick sort it in ascending order, to rank all values in
the Last_Name field by their amount of difference from "Smith".

Isolating fuzzy duplicates for "Smith"

Create a filter that isolates all values in the Last_Name field that are within a specified Levenshtein distance
of "Smith":

SET FILTER TO LEVDIST(TRIM(Last_Name),"Smith", F) < 3

Changing the number in the expression allows you to adjust the amount of Levenshtein distance in the
filtered values.

Remarks
When to use LEVDIST( )
Use the LEVDIST( ) function to find nearly identical values (fuzzy duplicates) or locate inconsistent spelling
in manually entered data. LEVDIST( ) also identifies exact duplicates.

How it works
The LEVDIST( ) function returns the Levenshtein distance between the two evaluated strings, which is a
value representing the minimum number of single character edits required to make one string identical to
the other string.
Each required edit increments the value of the Levenshtein distance by 1. The greater the Levenshtein dis-
tance, the greater the difference between the two strings. A distance of zero (0) means the strings are
identical.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 621 of 934

Commands

Types of edits
The edits can be of three types:
l insertion
l deletion
l substitution
Transpositions (two adjacent letters reversed) are not recognized by the Levenshtein algorithm, and count
as two edits – specifically, two substitutions.

Non-alphanumeric characters
Punctuation marks, special characters, and blanks are treated as single characters, just like letters and
numbers.

The case of characters

Changing the case of a character counts as one substitution, unless you turn off case sensitivity using the
case_sensitive setting.

The position of characters

Levenshtein distance takes the position of characters into account. The same characters ordered dif-
ferently may result in a different Levenshtein distance.
Returns 2:

LEVDIST("abc", "dec")

Returns 3:

LEVDIST("abc", "cde")

Using TRIM( ) with LEVDIST( )

To ensure accurate results when using LEVDIST( ) to compare a literal string such as "Smith" with a char-
acter field, you must use the TRIM( ) function to remove trailing blanks from the field.
If you are comparing two fields, you must use the TRIM( ) function with each field.
The Levenshtein algorithm counts blanks as characters, so any trailing blanks are included in the cal-
culation of the number of edits required to make two strings identical.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 622 of 934

Commands

Using OMIT( ) with LEVDIST( )

The OMIT( ) function can improve the effectiveness of the LEVDIST( ) function by removing generic ele-
ments such as "Corporation" or "Inc." from field values. Removal of generic elements focuses the LEVDIST
( ) string comparison on just the portion of the strings where a meaningful difference may occur.

Related functions
l ISFUZZYDUP( ) – provides an alternate method for comparing strings based on Levenshtein dis-
tance.
Unlike the default behavior of LEVDIST( ), ISFUZZYDUP( ) is not case-sensitive.
l DICECOEFFICIENT( ) – de-emphasizes or completely ignores the relative position of characters or
character blocks when comparing strings.
l SOUNDSLIKE( ) and SOUNDEX( ) – compare strings based on a phonetic comparison (sound)
rather than on an orthographic comparison (spelling).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 623 of 934

Commands

LOG( ) function
Returns the logarithm (base 10) of a numeric expression or field value with a specified number of decimal
places.

Syntax
LOG(number, decimals)

Parameters
Name Type Description

number numeric The value to find the logarithm for.

decimals numeric The number of decimal places for the return value.

Output
Numeric.

Examples
Basic examples
Returns 3.0000:

LOG(1000, 4)

Returns 4.86:

LOG(72443, 2)

Advanced examples
Finding the cube root

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 624 of 934

Commands

Creates a field that is the cube root of the field X to two decimal places:

DEFINE FIELD Cube_root COMPUTED EXP(LOG(X, 6) / 3, 2)

Note
You determine the nth root by dividing the log of the value by n and taking the exponential
value of the result.

Remarks
How it works
The logarithm of a number is the exponent (or power) of 10 needed to generate that number. Therefore, the
logarithm of 1000 is 3.

Related functions
The LOG( ) function is the inverse of the EXP( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 625 of 934

Commands

LOWER( ) function
Returns a string with alphabetic characters converted to lowercase.

Syntax
LOWER(string)

Parameters
Name Type Description

string character The value to convert to lowercase.

Output
Character.

Examples
Basic examples
Returns "abc":

LOWER("ABC")

Returns "abc 123 def":

LOWER("abc 123 DEF")

Returns "abcd 12":

LOWER("AbCd 12")

Returns all the values in the Last_Name field converted to lowercase:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 626 of 934

Commands

LOWER(Last_Name)

Remarks
How it works
The LOWER( ) function converts all alphabetic characters in string to lowercase. All non-alphabetic char-
acters are left unchanged.

When to use LOWER( )

Use LOWER( ) when you search for data that is in mixed or unknown case, or when you want data formatted
as lowercase text.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 627 of 934

Commands

LTRIM( ) function
Returns a string with leading spaces removed from the input string.

Syntax
LTRIM(string)

Parameters
Name Type Description

string character The value to remove leading spaces from.

Output
Character.

Examples
Basic examples
Note that in both examples the trailing spaces are not removed by the LTRIM( ) function.
Returns "Vancouver ":

LTRIM(" Vancouver ")

Returns "New York ":

LTRIM(" New York ")

Advanced examples
Removing non-breaking spaces
Non-breaking spaces are not removed by the LTRIM( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 628 of 934

Commands

If you need to remove leading non-breaking spaces, create a computed field using the following expression:

DEFINE FIELD Description_cleaned COMPUTED LTRIM(REPLACE(Description, CHR(160), CHR

(32)))

The REPLACE( ) function replaces any non-breaking spaces with regular spaces, and then LTRIM( )
removes any leading regular spaces.

Remarks
How it works
The LTRIM( ) function removes leading spaces only. Spaces inside the string, and trailing spaces, are not
removed.

Related functions
LTRIM( ) is related to the TRIM( ) function, which removes any trailing spaces from a string, and to the
ALLTRIM( ) function, which removes both leading and trailing spaces.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 629 of 934

Commands

MAP( ) function
Returns a logical value indicating if a character string matches a specified format string containing wildcard
characters, literal characters, or both.

Syntax
MAP(string, format)

Parameters
Name Type Description

string character The field, expression, or literal value to test for matches.

format character The data pattern, or character string, you want to compare with string.
format can contain wildcard characters, literal characters, or a com-
bination of the two:

"\9\9\9-999-9999"

The following wildcard characters are supported:

o "X" – matches any alphabetic character (a-z, A-Z, European char-
acters). This wildcard character is not case-sensitive. You can use
"X" or "x"
o "9" – matches any number (0-9)
o "!" – matches any non-blank character
o "?" – matches any character, including blanks
o "\" – escape character that specifies that the character immediately
following is a literal. Use the escape character if you want to lit-
erally match any of the wildcard characters (X, x, 9, !, ?)
o "\\" – specifies a literal backslash

Output
Logical. Returns T (true) if a match is found, and F (false) otherwise.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 630 of 934

Commands

Examples
Basic examples
Simple search patterns
Returns T:

MAP("ABC Plumbing", "xxx")

Returns F (string has only 3 numbers where a minimum of 4 are required):

MAP("045", "9999")

Escaping a wildcard
If the goal is to return T for only those values that start with the literal character "X", followed by any second
letter, the format parameter "\XX" ensures that the first "X" in the parameter is interpreted literally and not as
a wildcard.
Returns T:

MAP("XA-123", "XX")

MAP("GC-123", "XX")

MAP("XA-123", "\XX")

Returns F:

MAP("GC-123", "\XX")

Fields and patterns

Returns T for all records with invoice numbers that consist of, or that start with, two letters followed by five
numbers. Returns F otherwise:

MAP(Invoice_Number, "XX99999")

Returns T for all records with invoice numbers that are exactly "AB12345", or that start with "AB12345".
Returns F otherwise:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 631 of 934

Commands

MAP(Invoice_Number, "AB12345")

Returns T for all records with invoice numbers that consist of, or that start with, "AB" followed by five num-
bers. Returns F otherwise:

MAP(Invoice_Number, "AB99999")

Returns T for all records that do not match the standard format of social security numbers in the SSN field.
Returns F otherwise:

NOT MAP(SSN, "999-99-9999")

Advanced examples
Extracting records with 10-character product codes and with the leading
characters "859-"
Use an IF statement and the MAP( ) function to extract only those records that have product codes at least
10 characters long, and the leading characters "859-":

EXTRACT RECORD IF MAP(Product_Code, "85\9-999999") TO "Long_Codes_859"

Remarks
When to use MAP( )
Use the MAP( ) function to search for patterns or particular formats in alpha-numeric data. The patterns or
formats can be made up of wildcard characters, literal characters, or a combination of both.

Case sensitivity
The MAP( ) function is case-sensitive when comparing two literal characters. For example, "a" is not equi-
valent to "A".
If string includes character data with inconsistent case, you can use the UPPER( ) function to convert the
values to consistent case before using MAP( ).
For example:

MAP(UPPER(Invoice_Number), "AB99999")

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 632 of 934

Commands

Partial matching
MAP( ) supports partial matching in one situation but not in the other.
Partial matching in MAP( ) is not affected by the Exact Character Comparisons option (SET EXACT
ON/OFF).

Partial matching supported

Partial matching is supported if the format value is shorter than the string value.
Returns T, because format is 7 characters and string is 9 characters:

MAP("AB1234567", "AB99999")

Note
To return True, the format value must appear at the start of the string value.

Partial matching not supported

Partial matching is not supported if the format value is longer than the string value.
Returns F, because format is 7 characters and string is 6 characters:

MAP("AB1234", "AB99999")

If format is longer than string, the result is always False.

Accounting for blank spaces

Blank spaces are treated as characters, and can be accounted for in either of two ways:
l match blanks literally, by including blanks in the format value at the appropriate position
l use the wildcard "?" , which matches any character, including blanks
If required, you can use the TRIM( ), LTRIM( ), or ALLTRIM( ) functions to remove leading or trailing blanks
from string, which ensures that only text characters and any internal blanks are compared.

Concatenating fields
You can concatenate two or more fields in string if you want to search in more than one field in a table. The
concatenated fields are treated like a single field that includes leading and trailing blanks from the individual
fields, unless you use the ALLTRIM( ) function to remove them.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 633 of 934

Commands

MASK( ) function
Performs a bitwise AND operation on the first bytes of two character strings.

Syntax
MASK(character_value, character_mask)

Parameters
Name Type Description

character_value character The string with the byte to test.

character_mask character The string with the byte to test against (the mask value).

Output
Character. The output is the character representation of the binary result of the bitwise AND operation.

Examples
Basic examples
Returns "2" (00110010), the result of a bitwise AND of 3 (00110011) and 6 (00110110):

MASK("3", "6")

Remarks
When to use MASK( )
Use MASK( ) to identify specific bit patterns in a byte of data, including whether or not a particular bit is set
to 1.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 634 of 934

Commands

How it works
The MASK( ) function performs a bitwise AND operation on the binary representations of the first characters
of character_value and character_mask. The two comparison bytes are compared one bit at a time, res-
ulting in a third binary value.
The result of each comparison of corresponding bits is either 1 or 0:

character_value bit character_mask bit Result

0 0 0

0 1 0

1 0 0

1 1 1

Comparison strings longer than one byte

If either comparison string is longer than one byte, subsequent characters are ignored.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 635 of 934

Commands

MATCH( ) function
Returns a logical value indicating whether the specified value matches any of the values it is compared
against.

Syntax
MATCH(comparison_value, test <,...n>)

Parameters
Name Type Description

comparison_value character The field, expression, or literal value to test for matches.
numeric
datetime

test <,...n> character Any field, expression, or literal value you want to compare with com-
parison_value.
numeric
You can specify as many test values as necessary, but all specified
datetime
values must be of the same data type:

MATCH(comparison_value, `20140930`, `20141030`)

Note
Inputs to the MATCH( ) function can be character, numeric, or datetime data. You cannot
mix data types. All inputs must belong to the same data category.

Output
Logical. Returns T (true) if at least one match is found, and F (false) otherwise.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 636 of 934

Commands

Examples
Basic examples
Note
Return values for character comparisons assume that SET EXACT is OFF (the default set-
ting), except where noted.

Testing literal values

Returns T:

MATCH("ABC", "BCD", "CDE", "AB")

Returns F:

MATCH(98, 99, 100, 101)

Testing a field
Returns T for all records that contain "Phoenix", "Austin", or "Los Angeles" in the Vendor_City field. Returns
F otherwise:

MATCH(Vendor_City, "Phoenix", "Austin", "Los Angeles")

Returns T for all records that do not contain "Phoenix", "Austin", or "Los Angeles" in the Vendor_City field.
Returns F otherwise:

NOT MATCH(Vendor_City, "Phoenix", "Austin", "Los Angeles")

Returns T for all records that contain "PHOENIX", "AUSTIN", or "LOS ANGELES" in the Vendor_City field,
regardless of the case of any of the characters in the field. Returns F otherwise:
Values in the Vendor_City field are converted to uppercase before being compared with the uppercase city
names.

MATCH(UPPER(Vendor_City), "PHOENIX", "AUSTIN", "LOS ANGELES")

Testing multiple fields

Returns T for all records that contain "Phoenix" in the Vendor_City , City , or City_2 fields. Returns F oth-
erwise:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 637 of 934

Commands

MATCH("Phoenix", Vendor_City, City, City_2)

SET EXACT behavior
Returns T for all records that have product codes "A", "D", or "F", or product codes beginning with "A", "D",
or "F", in the Product_Code field. Returns F otherwise:

MATCH(Product_Code, "A", "D", "F")

Returns T for all records that have one-character product codes "A", "D", or "F" in the Product_Code field.
Returns F otherwise (SET EXACT must be ON):

MATCH(Product_Code, "A", "D", "F")

Comparing two fields

Returns T for all records that contain identical vendor and employee addresses. Returns F otherwise:
You may need to use additional functions to standardize the format of vendor and employee addresses.

MATCH(Vendor_Address, Employee_Address)

Comparing dates
Returns T for all records with an invoice date of 30 Sep 2014 or 30 Oct 2014. Returns F otherwise:

MATCH(Invoice_Date, `20140930`, `20141030`)

Advanced examples
Extracting anomalous inventory records
Use an IF statement and the MATCH( ) function to extract records that contain different amounts in the
Inventory_Value_at_Cost field and the computed Cost_x_Quantity field:

EXTRACT RECORD IF NOT MATCH(Inventory_Value_at_Cost, Cost_x_Quantity) TO "Non_match-

ing_amounts"

Extracting records for departments 101, 103, and 107

Use an IF statement and the MATCH( ) function to extract only records associated with departments 101,
103, or 107:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 638 of 934

Commands

EXTRACT RECORD IF MATCH(Dept, "101", "103", "107") TO "Three_Departments"

Remarks
Use MATCH( ) instead of the OR operator
You can use the MATCH( ) function instead of expressions that use the OR operator.
For example:

MATCH(City, "Phoenix", "Austin", "Los Angeles")

is equivalent to

City="Phoenix" OR City="Austin" OR City="Los Angeles"

Decimal precision of numeric inputs

When the numeric inputs being compared have a different decimal precision, the comparison uses the
higher level of precision.
Returns T, because 1.23 is equal to 1.23:

MATCH(1.23, 1.23, 1.25)

Returns F, because 1.23 does not equal 1.234 once the third decimal place is considered:

MATCH(1.23, 1.234, 1.25)

Character parameters
Case sensitivity
The MATCH( ) function is case-sensitive when used with character data. When it compares characters, "a"
is not equivalent to "A".
Returns F:

MATCH("a","A","B","C")

If you are working with data that includes inconsistent case, you can use the UPPER( ) function to convert
the values to consistent case before using MATCH( ).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 639 of 934

Commands

Returns T:

MATCH(UPPER("a"), UPPER("A"), UPPER("B"), UPPER("C"))

Partial matching
Partial matching is supported for character comparisons. Either value being compared can be contained
by the other value and be considered a match.
Both of these examples return T:

MATCH("AB", "ABC")

MATCH("ABC", "AB")

Note
The shorter value must appear at the start of the longer value to constitute a match.

Partial matching and SET EXACT

Turning SET EXACT off or on

If you want to ensure that the Exact Character Comparisons option is not used with the MATCH( ) func-
tion, check that the option is deselected in the Table tab in the Options dialog box (Tools > Options ).
If you are using a script, you can add the SET EXACT OFF command before the MATCH( ) function
appears. If required, you can restore the previous state with the SET EXACT ON command.

Datetime parameters
A date, datetime, or time field specified as a function input can use any date, datetime, or time format, as
long as the field definition correctly defines the format.

Mixing date, datetime, and time inputs

You are not prevented from mixing date, datetime, and time values in the MATCH( ) function's inputs, but
mixing these Datetime subtypes can give results that are not meaningful.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 640 of 934

Commands

Analytics uses serial number equivalents to process datetime calculations, so even if you are interested in
only the date portion of a datetime value, the time portion still forms part of the calculation.
Consider the following examples:
Returns T, because 31 December 2014 matches the second test value:

MATCH(`20141231`,`20141229`,`20141231`)

Returns F, even though the comparison_value and the second test value have an identical date of 31
December 2014:

MATCH(`20141231 120000`,`20141229`,`20141231`)

If we look at the serial number equivalent of these two expressions, we can see why the second one eval-
uates to false.
Returns T, because the serial number comparison_value is equal to the second serial number test:

MATCH(42003.000000, 42001.000000, 42003.000000)

Returns F, because the serial number comparison_value does not equal any of the test values:

MATCH(42003.500000, 42001.000000, 42003.000000)

The date portion of the serial numbers 42003.500000 and 42003.000000 match, but the time portions do
not. 0.500000 is the serial number equivalent of 12:00 PM.

Harmonize Datetime subtypes

MATCH(CTOD(DATE(`20141231 120000`,"YYYYMMDD"),"YYYYMMDD"),`20141229`,
`20141231`)

Specifying a literal date, datetime, or time value

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 641 of 934

Commands

l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

thhmmss `t235959`

Thhmm `T2359`

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 642 of 934

Commands

MAXIMUM( ) function
Returns the maximum value in a set of numeric values, or the most recent value in a set of datetime values.

Syntax
MAXIMUM(value_1, value_2 <,...n>)

Parameters
Name Type Description

value_1, value_2 <, numeric The values to compare, separated by commas.

...n>
datetime All values must be of the same data type.
Additionally, datetime values must be of the same subtype. You cannot
mix date, datetime, or time values in a single execution of the function.

Output
Numeric or Datetime.

Examples
Basic examples
Literal numeric input
Returns 7:

MAXIMUM(4, 7)

Returns 8:

MAXIMUM(4, 7, 3, 8)

Returns 8.00:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 643 of 934

Commands

MAXIMUM(4, 7.25, 3, 8)

Literal datetime input

Returns `20161231`:

MAXIMUM(`20161231`, `20161229`, `20161230`)

Returns `20161231 23:59:59`:

MAXIMUM(`20161231 235959`, `20161229 235959`)

Returns `23:59:59`:

MAXIMUM(`.235957`, `.235959`, `.235958`)

Field input
Returns the most recent date among the three fields for each record:

MAXIMUM(PO_Date, Invoice_Date, Payment_Date)

Advanced examples
Creating a computed field with a minimum default value
If you have a table of overdue accounts, create an Interest_Due computed field with a minimum default
value of $1.00:

DEFINE FIELD Interest_Due COMPUTED MAXIMUM(BALANCE * ANNUAL_RATE, 1)

If the balance multiplied by the interest rate is less than one dollar, MAXIMUM( ) returns 1. Otherwise,
MAXIMUM( ) returns the calculated interest amount.

Discovering dates past the end of a quarter

To discover if any dates across multiple fields are past the end of a quarter, create a computed field with an
expression like the one below:

DEFINE FIELD Past_Qtr COMPUTED MAXIMUM(PO_Date, Invoice_Date, Payment_Date,

`20160331`)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 644 of 934

Commands

l Records with all dates on or before 31 Mar 2016 return `20160331`.

l Records with one or more dates after 31 Mar 2016 return the most recent date among the three
fields.

Remarks
How decimal places work in sets of numeric values
If the numeric values being compared do not have the same number of decimal places, the result is adjusted
to the largest number of decimal places.
Returns 20.400:

MAXIMUM(3.682, 10.88, 20.4)

You can use the DECIMALS( ) function to adjust the number of decimals for value parameters.
Returns 20.40:

MAXIMUM(DECIMALS(3.682, 2), 10.88, 20.4)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 645 of 934

Commands

MINIMUM( ) function
Returns the minimum value in a set of numeric values, or the oldest value in a set of datetime values.

Syntax
MINIMUM(value_1, value_2 <,...n>)

Parameters
Name Type Description

value_1, value_2<, numeric The values to compare, separated by commas.

...n>
datetime All values must be of the same data type.
Additionally, datetime values must be of the same subtype. You can-
not mix date, datetime, or time values in a single execution of the func-
tion.

Output
Numeric or Datetime.

Examples
Basic examples
Literal numeric input
Returns 4:

MINIMUM(4, 7)

Returns 3:

MINIMUM(4, 7, 3, 8)

Returns 3.00:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 646 of 934

Commands

MINIMUM(4, 7.25, 3, 8)

Literal datetime input

Returns `20161229`:

MINIMUM(`20161231`, `20161229`, `20161230`)

Returns `20161229 23:59:59`:

MINIMUM(`20161231 235959`, `20161229 235959`)

Returns `23:59:57`:

MINIMUM(`.235957`, `.235959`, `.235958`)

Field input
Returns the oldest date among the three fields for each record:

MINIMUM(PO_Date, Invoice_Date, Payment_Date)

Advanced examples
Identifying the lowest value among multiple fields
Create a computed field to identify the lowest value among the Cost, Sale_Price, and Discount_Price
fields:

DEFINE FIELD Low_Value COMPUTED MINIMUM(Cost, Sale_Price, Discount_Price)

Discovering dates before the beginning of a quarter

To discover if any dates across multiple fields are before the beginning of a quarter, create a computed field
with an expression like the one below:

DEFINE FIELD Pre_Qtr COMPUTED MINIMUM(PO_Date, Invoice_Date, Payment_Date,

`20160101`)

l Records with all dates on or after 01 Jan 2016 return `20160101`.

l Records with one or more dates before 01 Jan 2016 return the oldest date among the three fields.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 647 of 934

Commands

Remarks
How decimal places work in sets of numeric values
If the numeric values being compared do not have the same number of decimal places, the result is adjus-
ted to the largest number of decimal places.
Returns 3.600:

MINIMUM(3.6,10.88, 20.482)

You can use the DECIMALS( ) function to adjust the number of decimals for value parameters.
Returns 3.60:

MINIMUM(3.6,10.88, DECIMALS(20.482, 2))

The MIN( ) abbreviation

In ACLScript, you can use the abbreviation MIN( ) for the MINIMUM( ) function even though it does not
uniquely identify the function, which is the normal requirement when abbreviating function names.
MIN( ) could also be an abbreviation for MINUTE( ), however Analytics reserves the abbreviation MIN( )
for the MINIMUM( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 648 of 934

Commands

MINUTE( ) function
Extracts the minutes from a specified time or datetime and returns it as a numeric value.

Syntax
MINUTE(time/datetime)

Parameters
Name Type Description

time/datetime datetime The field, expression, or literal value to extract the minutes from.

Output
Numeric.

Examples
Basic examples
Returns 59:

MINUTE(`t235930`)

MINUTE(`20141231 235930`)

Returns the minutes for each value in the Call_start_time field:

MINUTE(Call_start_time)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 649 of 934

Commands

Remarks
Abbreviating MINUTE( ) in scripts
In ACLScript, if you abbreviate the MINUTE( ) function, you must use at least the first four letters ( MINU ).
Analytics reserves the abbreviation MIN for the MINIMUM( ) function.

Parameter details
A field specified for time/datetime can use any time or datetime format, as long as the field definition cor-
rectly defines the format.
Specifying a literal time or datetime value
When specifying a literal time or datetime value for time/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231 235959`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Time values – you can use any of the time formats listed in the table below. You must use a sep-
arator before a standalone time value for the function to operate correctly. Valid separators are the
letter 't', or the letter 'T'. You must specify times using the 24-hour clock. Offsets from Coordinated
Universal Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).
l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.

Example formats Example literal values

thhmmss `t235959`

Thhmm `T2359`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 650 of 934

Commands

Example formats Example literal values

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 651 of 934

Commands

MOD( ) function
Returns the remainder from dividing two numbers.

Syntax
MOD(number, divisor_number)

Parameters
Name Type Description

number numeric The number to divide.

divisor_number numeric The number to divide number by.

If number or divisor_number, or both, include decimals, the output
has the same decimal precision as the input value with the higher
number of decimal places. For example, the output for MOD(45.35,
5.3) is "2.95".

Output
Numeric.

Examples
Basic examples
Returns 3:

MOD(93, 10)

Returns 2.0:

MOD(66, 16.00)

Returns 3.45:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 652 of 934

Commands

MOD(53.45, 10)

Advanced examples
Calculating an anniversary date
Defines a field that shows the number of months since the last anniversary:

DEFINE FIELD Months_since_last_anniversary COMPUTED MOD(Months_of_service, 12)

Remarks
When to use MOD( )
Use the MOD( ) function to test whether two numbers divide evenly, or to isolate the remainder of a division
calculation. This function divides one number by another and returns the remainder.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 653 of 934

Commands

MONTH( ) function
Extracts the month from a specified date or datetime and returns it as a numeric value (1 to 12).

Syntax
MONTH(date/datetime)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to extract the month from.

Output
Numeric.

Examples
Basic examples
Returns 12:

MONTH(`20141231`)

MONTH(`20141231 235959`)

Returns the month for each value in the Invoice_date field:

MONTH(Invoice_date)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 654 of 934

Commands

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.

Specifying a literal date or datetime value

When specifying a literal date or datetime value for date/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 655 of 934

Commands

Related functions
If you need to return the name of the month of the year, use CMOY( ) instead of MONTH( ).

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 656 of 934

Commands

NOMINAL( ) function
Returns the nominal annual interest rate on a loan.

Syntax
NOMINAL(effective_rate, periods)

Parameters
Name Type Description

effective_rate numeric The effective annual interest rate.

periods numeric The number of compounding periods per year.

Note
Specify an integer. If you specified a decimal portion, it is
truncated.

Output
Numeric. The rate is calculated to eight decimals places.

Examples
Basic examples
Returns 0.17998457 (18%), the nominal annual rate of interest on the unpaid balance of a credit card that
charges an effective annual rate of 19.56%:

NOMINAL(0.1956, 12)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 657 of 934

Commands

Remarks
What is the nominal interest rate?
The nominal annual interest rate on a loan is the stated or posted rate of interest, without taking into
account interest on the remaining balance, compounded monthly or daily.

Related functions
The EFFECTIVE( ) function is the inverse of the NOMINAL( ) function.

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 658 of 934

Commands

NORMDIST( ) function
Returns the probability that a random variable from a normally distributed data set is less than or equal to a
specified value, or exactly equal to a specified value.

Syntax
NORMDIST(x, mean, standard_deviation, cumulative)

Parameters
Name Type Description

x numeric The value for which you want to calculate the probability.

mean numeric The mean value of the data set.

standard_deviation numeric The standard deviation of the data set. The standard_deviation value
must be greater than 0.

cumulative logical Specify T to calculate the probability that a random variable is less
than or equal to x (cumulative probability), or F to calculate the prob-
ability that a random variable is exactly equal to x (simple probability).

Output
Numeric.

Examples
Basic examples
Returns 0.908788780274132:

NORMDIST(42, 40, 1.5, T)

Returns 0.109340049783996:

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 659 of 934

Commands

NORMDIST(42, 40, 1.5, F)

Published 6/19/2019 © 2019 ACL Services Ltd. dba Galvanize

Page 660 of 934

Commands

NORMSINV( ) function
Returns the z-score associated with a specified probability in a standard normal distribution. The z-score is
the number of standard deviations a value is from the mean of a standard normal distribution.

Syntax
NORMSINV(probability)

Parameters
Name Type Description

probability numeric The probability for which you want to calculate the z-score.

Output
Numeric.

Examples
Basic examples
Returns 1.333401745213610:

NORMSINV(0.9088)

Page 661 of 934

Commands

NOW( ) function
Returns the current operating system time as a Datetime data type.

Syntax
NOW()

Parameters
This function does not have any parameters.

Output
Datetime.

Examples
Basic examples
Returns the current operating system time as a datetime value, for example, `t235959`, displayed using
the current Analytics time display format:

NOW()

Remarks
Related functions
If you need to return the current operating system time as a character string, use TIME( ) instead of NOW(
).

Page 662 of 934

Commands

NPER( ) function
Returns the number of periods required to pay off a loan.

Syntax
NPER(rate, payment, amount <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

payment numeric The payment per period.

amount numeric The principal amount of the loan.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Output
Numeric.

Examples
Basic examples
Returns 300.00, the number of months required to pay off a $275,000 loan at 6.5% per annum, with pay-
ments of $1,856.82 due at the end of each month:

NPER(0.065/12, 1856.82, 275000, 0)

Returns 252.81, the number of months required to pay off the same loan, with payments of $2,000 due at
the end of each month:

Page 663 of 934

Commands

NPER(0.065/12, 2000, 275000, 0)

Returns 249.92, the number of months required to pay off the same loan, with payments of $2,000 due at
the beginning of each month:

NPER(0.065/12, 2000, 275000, 1)

I want to find: Analytics function to use:

PVANNUITY( )
Returns 21243.39:

PVANNUITY(0.01, 24, 1000)

Present value

FVANNUITY( )
Returns 26973.46:

FVANNUITY(0.01, 24, 1000)

Future value

PMT( )
Returns 1000:

PMT(0.01, 24, 21243.39)

Payment amount per period

RATE( )
Returns 0.00999999 (1%):

RATE(24, 1000, 21243.39)

Interest rate per period

Number of periods NPER( )

Page 664 of 934

Commands

I want to find: Analytics function to use:

Returns 24.00:

NPER(0.01, 1000, 21243.39)

Annuity formulas
The formula for calculating the present value of an ordinary annuity (payment at the end of a period):

The formula for calculating the future value of an ordinary annuity (payment at the end of a period):

Page 665 of 934

Commands

OCCURS( ) function
Returns a count of the number of times a substring occurs in a specified character value.

Syntax
OCCURS(string, search_for)

Parameters
Name Type Description

string character The value to search in.

You can concatenate two or more fields if you want to search in more
than one field in a table:

OCCURS(First_Name+Last_Name,"John")

search_for character The value to search for. The search is case-sensitive.

Output
Numeric.

Examples
Basic examples
Returns 2:

OCCURS("abc/abc/a","ab")

Returns 3:

OCCURS("abc/abc/a","a")

Returns the number of times a hyphen occurs in each value in the Invoice_Number field:

Page 666 of 934

Commands

OCCURS(Invoice_Number, "-")

Advanced examples
Finding invoice numbers with more than one hyphen
If invoice numbers in a table should have only one hyphen, use the OCCURS( ) function to create a filter that
isolates invoice numbers that have two or more hyphens:

SET FILTER TO OCCURS(Invoice_Number, "-") > 1

Finding occurrences of one field's value in another field

Use OCCURS( ) to find occurrences of one field's value in another field. For example, you could create a fil-
ter that isolates records in which Last_Name values occur in the Full_Name field:

SET FILTER TO OCCURS(Full_Name, ALLTRIM(Last_Name)) = 1

Including the ALLTRIM( ) function in the expression removes any leading or trailing spaces from the Last_
Name field, ensuring that only text values are compared.

Performing case-sensitive searches

Unlike the FIND( ) function, the OCCURS( ) function is case sensitive, which allows you to perform case-
sensitive searches.
The following expression isolates all records that contain the name "UNITED EQUIPMENT", in uppercase,
in the Vendor_Name field, while ignoring occurrences of "United Equipment".

SET FILTER TO OCCURS(Vendor_Name, "UNITED EQUIPMENT") > 0

If you want to find all occurrences of "United Equipment" regardless of casing, use the UPPER( ) function to
convert the search field values to uppercase:

SET FILTER TO OCCURS(UPPER(Vendor_Name), "UNITED EQUIPMENT") > 0

Page 667 of 934

Commands

OFFSET( ) function
Returns the value of a field with the starting position offset by a specified number of bytes.

Syntax
OFFSET(field, number_of_bytes)

Parameters
Name Type Description

field character A field name.

numeric
datetime

number_of_bytes numeric Any positive numeric expression.

Output
The return value is the same data type as the input field parameter.

Examples
Basic examples
If you have a field called "Number" that contains the value "1234567890" and you define an overlapping
field called "Offset_Number" that has a starting position of 1, a length of 3, and no decimals places, you
can use the OFFSET( ) function to shift the numbers in the field.
Returns 123:

OFFSET(Offset_Number,0)

Returns 234:

OFFSET(Offset_Number,1)

Page 668 of 934

Commands

Returns 789:

OFFSET(Offset_Number,6)

Remarks
You can use this function to temporarily offset the starting position of a field. This is useful when you are pro-
cessing data where the field starting position is variable.
If you use the OFFSET( ) function with conditional computed fields, any fields referenced in the IF test will
also be offset.

Page 669 of 934

Commands

OMIT( ) function
Returns a string with one or more specified substrings removed.

Syntax
OMIT(string1, string2 <,case_sensitive>)

Parameters
Name Type Description

string1 character The string to remove one or more substrings from.

string2 character One or more substrings to remove.

o Use commas to separate multiple substrings.
o Use a space after a comma only if it is part of the substring you
want to remove.
o If the double quotation mark character occurs in any of the sub-
strings, enclose the entire string2 parameter in single quotation
marks (' ') rather than double quotation marks.
o To omit a comma, place a single comma last in the list of sub-
strings, followed immediately by the closing quotation mark (see
the final example below).

case_sensitive logical Specify T to make the substrings case-sensitive, or F to ignore case.

optional If case_sensitive is omitted, the default value of T is used.

Output
Character.

Examples
Basic examples
Literal character input
Returns "Intercity Couriers":

Page 670 of 934

Commands

OMIT("Intercity Couriers Corporation", " Corporation, Corp.")

Returns "Inter-city Couriers":

OMIT("Inter-city Couriers Corp.", " Corporation, Corp.")

Note
The Levenshtein distance between the returned values in the first two examples is 1. If the
generic elements are not removed, the distance between the two examples is 8, which
could allow the values to escape detection as fuzzy duplicates.

Field input
Returns all the values in the Vendor_Name field with generic elements such as "Corporation" and "Inc."
removed:

OMIT(Vendor_Name," Corporation, Corp., Corp, Inc., Inc, Ltd., Ltd")

Returns all the values in the Vendor_Name field with generic elements such as "Corporation" and "Inc."
removed:

OMIT(Vendor_Name," ,.,Corporation,Corp,Inc,Ltd")

Note
The two preceding examples both return the same results but the syntax for the second
example is more efficient.
Returns all the values in the Vendor_Name field with "Corporation" and "Corp" removed, and all commas
removed:

OMIT(Vendor_Name," Corporation, Corp,")

Remarks
OMIT( ) can remove substrings as units
The OMIT( ) function removes one or more substrings from a string. It differs from functions such as CLEAN
( ), EXCLUDE( ), INCLUDE( ), and REMOVE( ) because it matches and removes characters on a substring
basis rather than on a character-by-character basis. Substring removal allows you to remove specific
words, abbreviations, or repeated sequences of characters from a string without affecting the remainder of
the string.

Page 671 of 934

Commands

A helper function for fuzzy comparisons

OMIT( ) can improve the effectiveness of the LEVDIST( ) or ISFUZZYDUP( ) functions, or the FUZZYDUP
or FUZZYJOIN commands, by removing generic elements such as "Corporation" or "Inc." from field val-
ues. Removal of generic elements focuses the string comparisons performed by these functions and com-
mands on just the portion of the strings where a meaningful difference may occur.

How the order of substrings affects results

If you specify multiple substrings for removal, the order in which you list them in string2 can affect the out-
put results.
When the OMIT( ) function is processed, the first substring is removed from all values that contain it, the
second substring is then removed from all values that contain it, and so on. If one substring forms part of
another substring – for example, "Corp" and "Corporation" – removing the shorter substring first also alters
values containing the longer substring ("Corporation" becomes "oration") and prevents the longer sub-
string from being found.
To avoid this situation, specify longer substrings before any shorter substrings they contain. For example:

OMIT(Vendor_Name," Corporation, Corp., Corp")

Try removing special characters first

You can specify single-character substrings, such as punctuation marks, special characters, and a blank
space, which further reduces the generic material in strings. It may be more efficient to remove a single
character first, such as a period or a blank, which reduces the number of substring variations you sub-
sequently need to specify. Compare the third and fourth examples above. They both return the same res-
ults, but the fourth example is more efficient.

Dealing with blanks or spaces

Blanks or spaces in substrings are treated like any other character. You must explicitly specify each blank
you want removed as part of a substring. For example, if you specify an ampersand without any blanks
("&"), "Ricoh Sales & Service" becomes "Ricoh Sales Service". If you include blanks (" & "), "Ricoh Sales
& Service" becomes "Ricoh SalesService".
If you specify a blank that is not part of the substring, the substring will not be found. For example, if you
specify an ampersand with blanks (" & "), "Ricoh Sales&Service" remains unchanged.
When using commas to separate multiple substrings, follow the comma with a space only if it corresponds
with the actual substring you want to remove.
One approach to dealing with blanks is to remove all blanks from a field first, by specifying a blank as a
single-character substring prior to specifying any other substrings.

Page 672 of 934

Commands

Review the results of using OMIT( )

After using OMIT( ) to created a computed field, review the contents of the field to confirm that you have not
inadvertently omitted meaningful portions of strings. For example, omitting "Co" gets rid of a common abbre-
viation for "Company", but it also removes the letters "Co" from two locations in "Coca-Cola".

Page 673 of 934

Commands

PACKED( ) function
Returns numeric data converted to the Packed data type.

Syntax
PACKED(number, length_of_result)

Parameters
Name Type Description

number numeric The numeric value or field to convert.

length_of_result numeric The number of bytes to use in the output string.

Output
Numeric.

Examples
Basic examples
Integer and decimal input
Returns 00075C:

PACKED(75, 3)

PACKED(7.5, 3)

Truncated digits in output

Returns 00000012456D:

Page 674 of 934

Commands

PACKED(-12.456, 6)

Returns 456D:

PACKED(-12.456, 2)

Advanced examples
Creating an 8-byte field to update a mainframe
You need to create an 8-byte field containing each employee's salary as a PACKED number for uploading
to a mainframe:

EXTRACT PACKED(SALARY, 8) AS "Salary_Export" TO "export"

Remarks
What is Packed data?
The Packed data type is used by mainframe operating systems to store numeric values in a format that uses
minimal storage space. The Packed data type stores two digits in each byte, and the last byte indicates
whether the value is positive or negative.

When to use PACKED( )

Use the PACKED( ) function to convert numeric data to the Packed format for export to mainframe systems.

Truncated return values

If the length_of_result value is shorter than the length of the number value, the additional digits are trun-
cated.

Page 675 of 934

Commands

PI( ) function
Returns the value of pi to 15 decimal places.

Syntax
PI( )

Parameters
This function does not have any parameters.

Output
Numeric.

Examples
Basic examples
Returns 3.141592653589793 (the value of pi to 15 decimal places):

PI( )

Returns 1.047197551196598 (the equivalent in radians of 60 degrees):

60 * PI( )/180

Advanced examples
Using degrees as input
Returns 0.866025403784439 (the sine of 60 degrees):

SIN(60 * PI( )/180)

Page 676 of 934

Commands

Remarks
When to use PI( )
Use PI( ) to convert degrees to radians: (degrees * PI( )/180) = radians. Radians are the required input for
three of Analytics's math functions: SIN( ), COS( ), and TAN( ).

Page 677 of 934

Commands

PMT( ) function
Returns the amount of the periodic payment (principal + interest) required to pay off a loan.

Syntax
PMT(rate, periods, amount <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of payment periods.

amount numeric The principal amount of the loan.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Output
Numeric.

Page 678 of 934

Commands

Examples
Basic examples
Returns 1856.82, the monthly payment (principal + interest) required to pay off a twenty-five year, $275,000
loan at 6.5% per annum, with payments due at the end of the month:

PMT(0.065/12, 12*25, 275000, 0)

Returns 1846.82, the monthly payment (principal + interest) required to pay off the same loan, with pay-
ments due at the beginning of the month:

PMT(0.065/12, 12*25, 275000, 1)

I want to find: Analytics function to use:

PVANNUITY( )
Returns 21243.39:

PVANNUITY(0.01, 24, 1000)

Present value

FVANNUITY( )
Returns 26973.46:

FVANNUITY(0.01, 24, 1000)

Future value

PMT( )
Payment amount per period Returns 1000:

Page 679 of 934

Commands

I want to find: Analytics function to use:

PMT(0.01, 24, 21243.39)

RATE( )
Returns 0.00999999 (1%):

RATE(24, 1000, 21243.39)

Interest rate per period

NPER( )
Returns 24.00:

NPER(0.01, 1000, 21243.39)

Number of periods

Annuity formulas
The formula for calculating the present value of an ordinary annuity (payment at the end of a period):

The formula for calculating the future value of an ordinary annuity (payment at the end of a period):

Page 680 of 934

Commands

PPMT( ) function
Returns the principal paid on a loan for a single period.

Syntax
PPMT(rate, specified_period, periods, amount <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

specified_period numeric The period for which you want to find the principal payment.

periods numeric The total number of payment periods.

amount numeric The principal amount of the loan.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Output
Numeric.

Page 681 of 934

Commands

Examples
Basic examples
Returns 367.24, the principal paid in the first month of a twenty-five year, $275,000 loan at 6.5% per
annum, with payments due at the end of the month:

PPMT(0.065/12, 1, 12*25, 275000, 0)

Returns 1846.82, the principal paid on the same loan in the last month of the loan:

PPMT(0.065/12, 300, 12*25, 275000, 0)

Remarks
Related functions
The IPMT( ) function is the complement of the PPMT( ) function.
The CUMPRINC( ) function calculates principal paid during a range of periods.

Page 682 of 934

Commands

PROPER( ) function
Returns a string with the first character of each word set to uppercase and the remaining characters set to
lowercase.

Syntax
PROPER(string)

Parameters
Name Type Description

string character The value to convert to proper case.

Output
Character.

Examples
Basic examples
Returns "John Doe":

PROPER("JOHN DOE")

Returns "John Doe":

PROPER("john doe")

Returns "1550 Alberni St.":

PROPER("1550 ALBERNI st.")

Returns "Bill O'Hara":

Page 683 of 934

Commands

PROPER("BILL O'HARA")

Returns all the values in the Company_Name field converted to proper case:

PROPER(Company_Name)

Remarks
How it works
The PROPER( ) function converts the first character in string, and any subsequent character preceded by
a blank, to uppercase.
Subsequent characters preceded by a hyphen, an apostrophe, an ampersand (&), and several other punc-
tuation marks and special characters are also converted to uppercase. All other alphabetic characters are
converted to lowercase.

When to use PROPER( )

The most common use for PROPER( ) is to convert names stored as all uppercase or all lowercase in
source data into proper case format, so the name is displayed correctly in a form letter or report.

Page 684 of 934

Commands

PROPERTIES( ) function
Returns properties information for the specified Analytics project item.

Syntax
PROPERTIES(name, obj_type, info_type)

Parameters
Name Type Description

name character The name of the Analytics project item you want information about.
name is not case-sensitive.
If the project item is an Analytics table, specify the table layout name,
not the data file name. For example: "Invoices", not "january_invoices.-
fil"
If you are using the PROPERTIES( ) function to return the name of the
active table, specify the name "activetable"

obj_type character The type of Analytics project item referred to by name.

Note
Currently, "table" is the only type of project item sup-
ported.

info_type character The type of information you want about the Analytics project item.
For more information, see "Types of properties information" on
page 687.

Output
Character. The maximum length of the output string is 260 characters. If properties information cannot be
found, an empty string is returned.

Page 685 of 934

Commands

Examples
Basic examples
Information about the Analytics data file (.fil)
Returns "Ap_Trans.fil":

PROPERTIES("Ap_Trans", "table", "filename")

Returns "C:\ACL DATA\Sample Data Files":

PROPERTIES("Ap_Trans", "table", "filepath")

Information about the open Analytics table

Returns "Ap_Trans":

PROPERTIES("activetable", "table", "open")

Information about an external data source

Returns "Trans_May.xls":

PROPERTIES("Trans_May", "table", "sourcename")

Returns "C:\Project Data\Monthly Invoices_Excel":

PROPERTIES("Trans_May", "table", "sourcepath")

Returns "EXCEL":

PROPERTIES("Trans_May", "table", "sourcetype")

Remarks
File information
Information types starting with "file" provide information about the Analytics data file (.fil) associated with
an Analytics table.

Page 686 of 934

Commands

Source information
Information types starting with "source" provide information about external data sources that can be asso-
ciated with an Analytics table. Only those external data sources that support refreshing an Analytics table
can be reported on using the PROPERTIES( ) function:
l Microsoft Excel
l Microsoft Access
l Delimited text
l Adobe Acrobat (PDF)
l Print Image (Report)
l SAP private file format/DART
l XML
l XBRL
l ODBC data sources

Types of properties information

The table below lists the types of properties information that can be returned by the PROPERTIES( ) func-
tion. Analytics tables are the only Analytics project items that can currently be used with the PROPERTIES
( ) function:

Page 687 of 934

Commands

obj_
type info_type Returns:

"table" "filename" The name of the data file associated with the Analytics table.

"filepath" The path of the data file associated with the Analytics table.

"filesize" The size, in KB, of the data file associated with the Analytics table.

"filemodifiedat" The time and date that the data file associated with the Analytics table was last mod-
ified.

"sourcename" The name of the data source associated with the Analytics table.
Data sources can be external files such as Excel, Access, PDF, XML, or delimited text
files, or ODBC data sources.

"sourcepath" The path of the data source associated with the Analytics table.
Not supported for ODBC data sources.

"sourcetype" The type of the data source associated with the Analytics table.

"sourcesize" The size, in KB, of the data source associated with the Analytics table.
Not supported for ODBC data sources.

"sourcemodifiedat" The time and date that the data source associated with the Analytics table was last
modified.
Not supported for ODBC data sources.

"open" The name of the currently active Analytics table.

Note
Multiple Analytics tables can be open at the same time, but in the user
interface only one table at a time can be active.

Page 688 of 934

Commands

PVANNUITY( ) function
Returns the present value of a series of future payments calculated using a constant interest rate. Present
value is the current, lump-sum value.

Syntax
PVANNUITY(rate, periods, payment <,type>)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of payment periods.

payment numeric The payment per period.

The payment amount must remain constant over the term of the annu-
ity.

type numeric The timing of payments:

optional o 0 – payment at the end of a period
o 1 – payment at the beginning of a period
If omitted, the default value of 0 is used.

Output
Numeric. The result is calculated to two decimal places.

Page 689 of 934

Commands

Examples
Basic examples
Monthly payments
Returns 21455.82, the present value of $1,000 paid at the beginning of each month for 2 years at 1% per
month, compounded monthly:

PVANNUITY(0.01, 2*12, 1000, 1)

Annual payments
Returns 20280.61, the present value of $12,000 paid at the end of each year for 2 years at 12% per
annum, compounded annually:

PVANNUITY(0.12, 2, 12000, 0)

I want to find: Analytics function to use:

PVANNUITY( )
Returns 21243.39:

PVANNUITY(0.01, 24, 1000)

Present value

FVANNUITY( )
Returns 26973.46:

FVANNUITY(0.01, 24, 1000)

Future value

Page 690 of 934

Commands

I want to find: Analytics function to use:

PMT( )
Returns 1000:

PMT(0.01, 24, 21243.39)

Payment amount per period

RATE( )
Returns 0.00999999 (1%):

RATE(24, 1000, 21243.39)

Interest rate per period

NPER( )
Returns 24.00:

NPER(0.01, 1000, 21243.39)

Number of periods

Annuity formulas
The formula for calculating the present value of an ordinary annuity (payment at the end of a period):

The formula for calculating the future value of an ordinary annuity (payment at the end of a period):

Remarks
Related functions
The FVANNUITY( ) function is the inverse of the PVANNUITY( ) function.

Page 691 of 934

Commands

PVLUMPSUM( ) function
Returns the present value required to generate a specific future lump sum calculated using a constant
interest rate. Present value is the current, lump-sum value.

Syntax
PVLUMPSUM(rate, periods, amount)

Parameters
Name Type Description

rate numeric The interest rate per period.

periods numeric The total number of periods.

amount numeric The value of the future lump sum at the end of the last period.

Output
Numeric. The result is calculated to two decimal places.

Page 692 of 934

Commands

Examples
Basic examples
Interest compounded monthly
Returns 1000.00, the initial investment principal required to generate a future lump sum of $1,269.73, when
invested for 2 years at 1% per month, compounded monthly:

PVLUMPSUM(0.01, 2*12, 1269.73)

Returns 787.57, the initial investment principal required to generate a future lump sum of $1,000, when
invested for 2 years at 1% per month, compounded monthly:

PVLUMPSUM(0.01, 2*12, 1000)

Returns 21455.82, the initial investment principal required to generate a future lump sum of $27,243.20,
when invested for 2 years at 1% per month, compounded monthly:

PVLUMPSUM(0.01, 2*12, 27243.20)

Interest compounded semi-annually

Returns 792.09, the initial investment principal required to generate a future lump sum of $1,000, when
invested for 2 years at 12% per annum, compounded semi-annually:

PVLUMPSUM(0.12/2, 2*2, 1000)

Interest compounded annually

Returns 797.19, the initial investment principal required to generate a future lump sum of $1,000, when
invested for 2 years at 12% per annum, compounded annually:

PVLUMPSUM(0.12, 2, 1000)

Page 693 of 934

Commands

Remarks
What is present value?
The present value of an invested lump sum is the initial principal required to generate a specific future
lump sum, within a particular time frame. The future value is the principal plus the accumulated compound
interest.

Related functions
The FVLUMPSUM( ) function is the inverse of the PVLUMPSUM( ) function.

Page 694 of 934

Commands

PYDATE( ) function
Returns a date value calculated by a function in a external Python script. Data processing in Python is
external to Analytics.

Syntax
PYDATE("PyFile,PyFunction" <, field|value <,...n>>)

Parameters
Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

When specifying the Python script, omit the file extension. The function
you call may call other functions within the script or within other scripts,
however all scripts that run must be placed inside a folder in the
PYTHONPATH system environment variable prior to running.
For more information, see "Configuring Python for use with Analytics"
on page 905.
Note
Your PyFunction must return a Python datetime.date
object.

field |value <,...n> character This list of fields, expressions, or literal values to use as arguments for
the Python function. The values are passed into the function you call in
optional numeric
the order you specify them.
datetime
You may include as many arguments as necessary to satisfy the func-
logical tion definition in the Python script.
Note
Use the ALLTRIM() function to remove any leading or
trailing spaces from character input: ALLTRIM(str). For
more information, see "ALLTRIM( ) function" on
page 461.

Page 695 of 934

Commands

Output
Datetime.

Examples
Basic examples
Returns `20160630`:

PYDATE('hello,due_date', `20160531`, 30)

External Python script that accepts a date and a grace period as a number of days and calculates the date
the invoice is due. For an invoice date of 2016-05-31 and a period of 30 days: "2016-06-30":

#! python
from datetime import timedelta

def due_date(inv_date, period):

return(inv_date + timedelta(period))

Advanced examples
Defining a computed field
Defines a computed field in the Ap_Trans table using the Python script that calculates due date:

OPEN Ap_Trans
DEFINE FIELD due_date COMPUTED
WIDTH 27
PYDATE( "hello,due_date" ,Invoice_Date, Pay_Period)

Page 696 of 934

Commands

PYDATETIME( ) function
Returns a datetime value calculated by a function in an external Python script. Data processing in Python is
external to Analytics.

Syntax
PYDATETIME("PyFile,PyFunction" <, field|value <,...n>>)

Parameters
Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

Page 697 of 934

Commands

Output
Datetime.

Examples
Basic examples
Returns `20170101t0500`:

PYDATETIME("hello, combine_date_time", `20170101`, `t0500`)

External Python script that accepts a date argument and a time argument and returns a combined Dat-
etime object:

# hello.py content
from datetime import datetime

def combine_date_time(d,t):
return datetime.combine(d,t)

Advanced examples
Adding time to a datetime
Returns `20160101t2230`:

PYDATETIME("hello,add_time", `20160101 150000`, `t073000`)

External Python script that accepts a datetime and a time and adds the time to the datetime: 2016-01-01
15:00:00 + 7 hours, 30 minutes, 00 seconds = 2016-01-01 22:30:00.

# hello.py content
from datetime import timedelta
from datetime import datetime
from datetime import time
def add_time(start, time_to_add):
return start + timedelta(hours=time_to_add.hour, minutes=time_to_add.minute, seconds=time_to_
add.second)

Page 698 of 934

Commands

PYLOGICAL( ) function
Returns a logical value calculated by a function in an external Python script. Data processing in Python is
external to Analytics.

Syntax
PYLOGICAL("PyFile,PyFunction" <, field|value <,...n>>)

Parameters
Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

Page 699 of 934

Commands

Output
Logical.

Examples
Basic examples
Returns F:

PYLOGICAL( "hello,str_compare", "basketball", "baseball", "b" )

External Python script that compares str1 and str2 using the count of the character that is passed in as
char:

# hello.py content
def str_compare(str1, str2, char):
return str1.count(char) > str2.count(char)

Advanced examples
Using fields
Returns a truth value when comparing Vendor_Name and Vendor_City:

PYLOGICAL( "hello,str_compare", Vendor_Name, Vendor_City, "b" )

External Python script that compares str1 and str2 using the count of the character that is passed in as
char:

# hello.py content
def str_compare(str1, str2, char):
return str1.count(char) > str2.count(char)

Page 700 of 934

Commands

PYNUMERIC( ) function
Returns a numeric value calculated by a function in an external Python script. Data processing in Python is
external to Analytics.

Syntax
PYNUMERIC(PyFile,PyFunction, decimal <, field|value <,...n>>)

Parameters
Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

decimal numeric The number of decimal places to include in the return value. Must be a
positive integer.

Page 701 of 934

Commands

Output
Numeric.

Examples
Basic examples
Returns 35.00:

PYNUMERIC("hello,get_nth_percent", 2, 80, 120, 30, 45, 30, 100, 35, 45)

External Python script that returns the value at the requested percentile from a dynamically sized list of val-
ues:

# hello.py content
from math import ceil
def get_nth_percent(percentage, *values):
input_length = len(values)
position = ceil((percentage/100.00) * input_length)
return values[position-1]

Page 702 of 934

Commands

PYSTRING( ) function
Returns a character value calculated by a function in an external Python script. Data processing in Python is
external to Analytics.

Syntax
PYSTRING("PyFile,PyFunction", length <,field|value <,...n>>)

Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

length numeric The length to allocate for the return string.

Output
Character.

Page 703 of 934

Commands

Examples
Basic examples
Returns "my test":

PYSTRING('hello,main', 20, "my")

External Python script that accepts a string and concatenates " test" to the string:

#! python
# hello.py content
def main(str):
str2 = str + ' test'
return(str2)

Advanced examples
Returning a substring
This example removes the last two characters from the Vendor Name field and returns the substring:

PYSTRING( "hello,sub_set", LENGTH(Vendor_Name), ALLTRIM(Vendor_Name), LENGTH

(ALLTRIM(Vendor_Name)), 0, LENGTH(ALLTRIM(Vendor_Name)) - 2)

External Python script that accepts a string, a string length, and two character positions. The function
returns a substring between position one and position two:

#hello.py content
def sub_set(str, length, p1, p2):
if p1 >= 0 and p2 < length and p1 < p2:
str2 = str[p1:p2]
else:
str2 = str
return str2

Page 704 of 934

Commands

PYTIME( ) function
Returns a time value calculated by a function in an external Python script. Data processing in Python is
external to Analytics.

Syntax
PYTIME("PyFile,PyFunction" <, field|value <,...n>>)

Parameters
Name Type Description

PyFile,PyFunction character The name of the Python script to run followed by a comma and then
the name of the function that returns the value:

"myScript,myFunction"

Page 705 of 934

Commands

Output
Datetime.

Examples
Basic examples
Returns `t2122`:

ASSIGN v_time_part = PYTIME("hello,get_time", `20160101 212223`)

External Python script:

# hello.py content
from datetime import time
from datetime import date

def get_time(timestamp):
return timestamp.time();

Page 706 of 934

Commands

RAND( ) function
Returns a random number that falls within a specified boundary.

Syntax
RAND(number)

Parameters
Name Type Description

number numeric The numeric boundary for the random number.

If you specify a number with decimal places the random number gen-
erated has the same number of decimal places.
o If you enter a positive number – the random number returned is
greater than or equal to zero, and less than the number you spe-
cified.
Returns a number from 0 to 99:

RAND(100)

o If you enter a negative number – the random number returned is

less than zero, and greater than or equal to the number you spe-
cified.
Returns a number from -1 to -100:

RAND(-100)

Output
Numeric.

Examples
Basic examples
Returns 278.61:

Page 707 of 934

Commands

RAND(1000.00)

Returns 3781:

RAND(10000)

Note
The return value will differ with each execution of the function.

Remarks
RAND( ) cannot replicate results
If you use the RAND( ) function consecutively with the same number value, it produces different results.
Unlike the RANDOM command, the RAND( ) function has no seed value.

Duplicate random numbers possible

If you use RAND( ) to create a computed field that assigns a random number to every record in a table, it is
possible that duplicate random numbers are generated. There is no guarantee that the random numbers
will be unique.
The larger the number value in relation to the number of records in the table, the greater the chance that
the generated numbers will be unique.

Random numbers dynamically update

A computed field with the RAND( ) function generates a new set of random numbers every time you per-
form actions such as quick sorting, applying a filter, rearranging columns, or scrolling through the view.
If you want to fix a set of random numbers, extract the data to a new table using the View or Fields option
in the Extract dialog box.

Page 708 of 934

Commands

RATE( ) function
Returns the interest rate per period.

Syntax
RATE(periods, payment, amount)

Parameters
Name Type Description

periods numeric The total number of payment periods.

payment numeric The payment per period.

amount numeric The principal amount of the loan.

Note
The RATE( ) function assumes that payments are made at the end of each period.

Output
Numeric. The rate is calculated to eight decimals places.

Examples
Basic examples
Returns 0.00541667 (0.54%), the monthly interest rate implied by a twenty-five year, $275,000 loan with
monthly payments of $1,856.82:

RATE(12*25, 1856.82, 275000)

Returns 0.06500004 (6.5%), the annual interest rate implied by the same loan:

RATE(1225, 1856.82, 275000)12

Page 709 of 934

Commands

Advanced examples
Converting the nominal rate to the effective rate
The RATE( ) function calculates the nominal interest rate. You can use the EFFECTIVE( ) function to con-
vert the result of RATE( ) to the effective interest rate.
Returns 0.06715155 (6.7%), the effective annual interest rate implied by the loan in the examples above:

EFFECTIVE((RATE(1225, 1856.82, 275000)12), 12*25)

Annuity calculations
Annuity calculations involve four variables:
l present value, or future value – $21,243.39 and $ 26,973.46 in the examples below
l payment amount per period – $1,000.00 in the examples below
l interest rate per period – 1% per month in the examples below
l number of periods – 24 months in the examples below
If you know the value of three of the variables, you can use an Analytics function to calculate the fourth.

I want to find: Analytics function to use:

PVANNUITY( )
Returns 21243.39:

PVANNUITY(0.01, 24, 1000)

Present value

FVANNUITY( )
Returns 26973.46:

FVANNUITY(0.01, 24, 1000)

Future value

PMT( )
Returns 1000:

PMT(0.01, 24, 21243.39)

Payment amount per period

RATE( )
Returns 0.00999999 (1%):

RATE(24, 1000, 21243.39)

Interest rate per period

Number of periods NPER( )

Page 710 of 934

Commands

I want to find: Analytics function to use:

Returns 24.00:

NPER(0.01, 1000, 21243.39)

Annuity formulas
The formula for calculating the present value of an ordinary annuity (payment at the end of a period):

The formula for calculating the future value of an ordinary annuity (payment at the end of a period):

Page 711 of 934

Commands

RDATE( ) function
Returns a date value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RDATE(rScript|rCode <,field|value <,...n>>)

Parameters
Name Type Description

rScript | rCode character The full or relative path to the R script, or a snippet of R code to run.
If you enter R code directly rather than use an external file, you can-
not use the enclosing quotation character in your code, even if you
escape it:
o valid – 'var <- "\"test\"" '
o invalid – 'var <- "\'test\'" '

field | value <,...n> character The list of fields, expressions, or literal values to use as arguments for
the R script or code snippet.
optional numeric
The values are passed into the function you call in the order you spe-
datetime
cify them, and you reference them using value1, value2 ... valueN in
logical the R code.
You may include as many arguments as necessary to satisfy the func-
tion definition in the R code.
Note
Use the ALLTRIM() function to remove any leading or
trailing spaces from character input: ALLTRIM(str). For
more information, see "ALLTRIM( ) function" on
page 461.

Output
Datetime.

Page 712 of 934

Commands

Examples
Basic examples
Returns `20160530`:

RDATE("as.Date(value1,'%m-%d-%Y')", "05-30-16")

Advanced examples
Using an external R script
Converts a string to a date and returns it:

RDATE("a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]", dateText)

External R script (sample.r):

dateForm <- function(dateText) {

return(as.Date(dateText,format='%y%m%d'))
}
dateForm(value1)

Remarks
Returning data from R
When calling R scripts, use the source function and assign the return object to a variable. You can then
access the value returned from your R function from the return object:

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

Page 713 of 934

Commands

Running external R scripts on AX Server

Page 714 of 934

Commands

RDATETIME( ) function
Returns a datetime value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RDATETIME(rScript|rCode <,field|value <,...n>>)

Parameters
Name Type Description

rScript | rCode character The full or relative path to the R script, or a snippet of R code to run.
If you enter R code directly rather than use an external file, you cannot
use the enclosing quotation character in your code, even if you escape
it:
o valid – 'var <- "\"test\"" '
o invalid – 'var <- "\'test\'" '

Output
Datetime.

Page 715 of 934

Commands

Examples
Basic examples
Adds 45 minutes to the current date and time:

RDATETIME("Sys.time() + value1",2700)

Advanced examples
Using an external R script
Adds 45 minutes to a datetime field by passing a field and a literal value to an external R function:

RDATETIME("a<-'c:\\scripts\\sample.r');a[[1]]", start_date, 2700)

External R script (sample.r):

add_time <- function(start, sec) {

return(start + sec)
}
add_time(value1, value2)

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

Page 716 of 934

Commands

Running external R scripts on AX Server

System time zone

Greenwich Mean Time (GMT) is the default current time zone in the R environment used by Analytics.

Page 717 of 934

Commands

RECLEN( ) function
Returns the length of the current record.

Syntax
RECLEN( )

Parameters
This function does not have any parameters.

Output
Numeric.

Examples
Basic examples
The following example extracts all records where the length is exactly 110:

EXTRACT RECORD IF RECLEN( ) = 110 TO "Extract.fil"

Remarks
You can use the RECLEN( ) function to identify to records of a particular length, or to test for shorter than
expected records. This function is useful if you are working with Print Image (Report) files because it
provides an easy way to examine the record lengths:
l For fixed-length records, the return value is a constant value (the record length).
l For variable-length records, the return value changes for each record.

Page 718 of 934

Commands

RECNO( ) function
Returns the current record number.

Syntax
RECNO( )

Parameters
This function does not have any parameters.

Output
Numeric.

Examples
Basic examples
The following example extracts records numbered 10 through 20 to a new Analytics table:

EXTRACT RECORD IF BETWEEN(RECNO( ),10,20) TO "Subset.fil"

Remarks
You can use the RECNO( ) function to output record numbers to a table, or to determine the relative location
of a particular record within a table.

Indexed tables vs Non-indexed tables

This function returns the current logical record number:
l If the table is not indexed, RECNO( ) starts with a value of 1 and increases by one for each record in
the table. The logical and physical record numbers are identical.
l If the table is indexed, RECNO( ) behaves similarly, but counts the records using the logical, not phys-
ical order.

Page 719 of 934

Commands

Using the SEEK or FIND command

If the SEEK or FIND commands are used, the record number is reset to 1 after you execute these com-
mands.

Reordering records
When you reorder the records in a table, the record numbers generated by RECNO( ) are not reordered.
To keep the record numbers with the records that they were originally associated with, extract the data to a
new table using the Fields option before you reorder the records.

Page 720 of 934

Commands

RECOFFSET( ) function
Returns a field value from a record that is a specified number of records from the current record.

Syntax
RECOFFSET(field, number_of_records)

Parameters
Name Type Description

field character The name of the field to retrieve the value from.
numeric
datetime

number_of_records numeric The number of records from the current record. A positive number spe-
cifies a record after the current record, and a negative number spe-
cifies a record before the current record.

Output
Character, Numeric, or Datetime. The return value belongs to the same data category as the input field para-
meter.

Examples
Basic examples
Returns an Amount value from the next record:

RECOFFSET(Amount,1)

Returns an Amount value from the previous record:

RECOFFSET(Amount, -1)

Page 721 of 934

Commands

Advanced examples
Using RECOFFSET in a computed field
The computed field Next_Amount shows the value of the Amount field in the next record only if the next
record has the same customer number.
To define this computed field in a script, use the following syntax:

DEFINE FIELD Next_Amount COMPUTED

RECOFFSET(Amount,1) IF RECOFFSET(Customer,1) = Customer
0

Next_Amount is the value of the next record's Amount field only if the customer number in the next record
is the same as the customer number in the current record. Otherwise, Next_Amount is assigned a value of
zero.

Remarks
The RECOFFSET( ) function returns a field value from a record that is a specified number of records
above or below the current record.

When to use RECOFFSET( )

This function is commonly used for advanced comparison testing.
You can use this function to compare values in a field in the current record with a field in another record.
For example, you can add a computed field that calculates the difference between an amount in the cur-
rent record and an amount in the previous record.

The beginning or end of a table

If the beginning or end of the table is encountered, the function returns zero for numeric fields, a blank
string for character fields, or 1900/01/01 for date fields. The function returns blank output in these
instances because there is no further record to compare the current record to.

Page 722 of 934

Commands

REGEXFIND( ) function
Returns a logical value indicating whether the pattern specified by a regular expression occurs in a string.

Syntax
REGEXFIND(string, pattern)

Parameters
Name Type Description

string character The field, expression, or literal value to test for a matching pattern.

pattern character The pattern string (regular expression) to search for.

pattern can contain literal characters, metacharacters, or a com-
bination of the two. Literal characters include all alphanumeric char-
acters, some punctuation characters, and blanks.
The search is case-sensitive, which means that uppercase and lower-
case alpha characters must be explicitly specified.

Output
Logical. Returns T (true) if the specified pattern value is found, and F (false) otherwise.

Examples
Basic examples
Alpha character patterns
Returns T for all records that contain "Phoenix", "Austin", or "Los Angeles" in the Vendor_City field. Returns
F otherwise:

REGEXFIND(Vendor_City, "Phoenix|Austin|Los Angeles")

Returns T for all last names that start with "John" or "Jon". For example: John, Jon, Johnson, Johnston, Jon-
son, Jonston, Jones, and so on. Returns F otherwise:

Page 723 of 934

Commands

REGEXFIND(Last_Name,"^Joh?n")

Returns T for only those last names that are "John" or "Jon". Returns F otherwise:

REGEXFIND(Last_Name,"^Joh?n\b")

Numeric character patterns

Returns T for all records with invoice numbers that contain "98". Returns F otherwise:

REGEXFIND(Invoice_Number, "98")

Returns T for all records with invoice numbers that begin with "98". Returns F otherwise:

REGEXFIND(Invoice_Number, "\b98")

Returns T for all records with invoice numbers that end with "98". Returns F otherwise:

REGEXFIND(Invoice_Number, "98\b")

Returns T for all records with invoice numbers that contain "98" in the 5th and 6th positions. Returns F oth-
erwise:

REGEXFIND(Invoice_Number, "\b\d\d\d\d98")

REGEXFIND(Invoice_Number, "\b\d{4}98")

Mixed character patterns

Returns T for all records with product codes that start with 3 numbers, followed by a hyphen and 6 letters.
Returns F otherwise:

REGEXFIND(Product_Code, "\b\d{3}-[a-zA-Z]{6}\b")

Returns T for all records with product codes that start with 3 or more numbers, followed by a hyphen and 6
or more letters. Returns F otherwise:

REGEXFIND(Product_Code, "\b\d{3,}-[a-zA-Z]{6}")

Returns T for all records with alphanumeric invoice identifiers that contain "98" in the 5th and 6th positions.
Returns F otherwise:

Page 724 of 934

Commands

REGEXFIND(Invoice_Number, "\b\w{4}98")

Returns T for all records with invoice identifiers that contain both of the following, otherwise returns F:
l any character in the first four positions
l "98" in the 5th and 6th positions

REGEXFIND(Invoice_Number, "\b.{4}98")

Returns T for all records with invoice identifiers that contain "98" preceded by 1 to 4 initial characters.
Returns F otherwise:

REGEXFIND(Invoice_Number, "\b.{1,4}98")

Returns 'T' for all records with invoice identifiers that contain all of the following, otherwise returns F:
l any character in the first three positions
l "5" or "6" in the 4th position
l "98" in the 5th and 6th positions

REGEXFIND(Invoice_Number, "\b.{3}[56]98")

Returns T for all records with invoice identifiers that contain all of the following, otherwise returns F:
l any character in the first two positions
l "55" or "56" in the 3rd and 4th positions
l "98" in the 5th and 6th positions

REGEXFIND(Invoice_Number, "\b.{2}(55|56)98")

Remarks
How it works
The REGEXFIND( ) function uses a regular expression to search data in Analytics.
Regular expressions are powerful and flexible search strings that combine literal characters and metachar-
acters, which are special characters that perform a wide variety of search operations.
For example:

REGEXFIND(Last_Name,"Sm(i|y)the{0,1}")

uses the group ( ) , alternation | , and quantifier { } metacharacters to create a regular expression that finds
"Smith", "Smyth", "Smithe", or "Smythe" in the Last_Name field.

Page 725 of 934

Commands

Matching performed sequentially

Matching between string and pattern values is performed sequentially. In the example above:
l "S" is matched against the first position in the Last_Name field
l "m" is matched against the second position
l "i" and "y" are matched against the third position
l "t" is matched against the fourth position
l "h" is matched against the fifth position
l "e" is matched against the sixth position, if a sixth position exists in the source value

When to use REGEXFIND( )

Use REGEXFIND( ) to search data using simple or complex pattern matching.
Constructing regular expressions can be tricky, especially if you are new to the syntax. You may be able to
achieve your search goals using simpler Analytics search functions such as FIND( ), MATCH( ), or MAP( ).
If your search requirements exceed the capabilities of these simpler functions, regular expressions give
you almost unlimited flexibility in constructing search strings.

How REGEXFIND( ) handles spaces

Spaces (blanks) are treated as characters in both string and pattern, so you should exercise care when
dealing with spaces.
In pattern, you can indicate a space either literally, by typing a space, or by using the metacharacter \s.
Using the metacharacter makes spaces easier to read in pattern, and therefore less likely to be over-
looked, especially when you construct more complex patterns.

Concatenating fields
You can concatenate two or more fields in string if you want to search across multiple fields sim-
ultaneously.
For example:

REGEXFIND(Vendor_Name+Vendor_Street,"Hardware.*Main")

searches both the Vendor_Name and the Vendor_Street fields for the words "Hardware" and "Main" sep-
arated by zero or more characters.
A business with the word "Hardware" in its name, located on a street called "Main", matches the regular
expression. So does a business called "Hardware on Main".
The concatenated fields are treated like a single field that includes leading and trailing spaces from the indi-
vidual fields, unless you use the ALLTRIM( ) function to remove spaces.

Page 726 of 934

Commands

Order of concatenated fields matters

Because REGEXFIND( ) searches for the characters in pattern in the order in which you specify them, the
order in which you concatenate the fields has an effect. If you reversed Vendor_Name and Vendor_Street
in the expression above, you would be less likely to get any results.

Regular expression metacharacters

The table below lists metacharacters you can use with REGEXFIND( ) and REGEXREPLACE( ) and
describes the operation that each one performs.
Additional regular expression syntax exists, and is supported by Analytics, but it is more complex. A full
explanation of additional syntax is beyond the scope of this guide. Numerous resources explaining regular
expressions are available on the Internet.
Analytics uses the ECMAScript implementation of regular expressions. Most implementations of regular
expressions use a common core syntax.
Note
The current implementation of regular expressions in Analytics does not fully support
searching languages other than English.

Metacharacter Description

. Matches any character (except a new line character)

? Matches 0 or 1 occurrences of the immediately preceding literal, metacharacter, or element

* Matches 0 or more occurrences of the immediately preceding literal, metacharacter, or element

+ Matches 1 or more occurrences of the immediately preceding literal, metacharacter, or element

{} Matches the specified number of occurrences of the immediately preceding literal, metacharacter, or
element. You can specify an exact number, a range, or an open-ended range.
For example:
o a{3} matches "aaa"
o X{0,2}L matches "L", "XL", and "XXL"
o AB-\d{2,}-YZ matches any alphanumeric identifier with the prefix "AB-", the suffix "-YZ", and two or
more numbers in the body of the identifier

[] Matches any single character inside the brackets

For example:
o [aeiou] matches a, or e, or i, or o, or u
o [^aeiou] matches any character that is not a, or e, or i, or o, or u
o [A-G] matches any uppercase letter from A to G
o [A-Ga-g] matches any uppercase letter from A to G, or any lowercase letter from a to g
o [5-9] matches any number from 5 to 9

Page 727 of 934

Commands

Metacharacter Description

() Creates a group that defines a sequence or block of characters, which can then be treated as a single
unit.
For example:
o S(ch)?mid?th? matches "Smith" or "Schmidt"
o (56A.*){2} matches any alphanumeric identifier in which the sequence "56A" occurs at least twice
o (56A).*-.*\1 matches any alphanumeric identifier in which the sequence "56A" occurs at least
twice, with a hyphen located between two of the occurrences

\ An escape character that specifies that the character immediately following is a literal. Use the escape
character if you want to literally match metacharacters. For example, \( finds a left parenthesis, and \\
finds a backslash.
Use the escape character if you want to literally match any of the following characters:
^ $ . * + ? = ! : | \ ( ) [ ] { }
Other punctuation characters such as the ampersand (&) or the 'at sign' (@) do not require the escape
character.

\ int Specifies that a group, previously defined with parentheses ( ), recurs. int is an integer that identifies
the sequential position of the previously defined group in relation to any other groups. This metachar-
acter can be used in the pattern parameter in both REGEXFIND( ) and REGEXREPLACE( ).
For example:
o (123).*\1 matches any identifier in which the group of digits "123" occurs at least twice
o ^(\d{3}).*\1 matches any identifier in which the first 3 digits recur
o ^(\d{3}).*\1.*\1 matches any identifier in which the first 3 digits recur at least twice
o ^(\D)(\d)-.*\2\1 matches any identifier in which the alphanumeric prefix recurs with the alpha and
numeric characters reversed

$int Specifies that a group found in a target string is used in a replacement string. int is an integer that iden-
tifies the sequential position of the group in the target string in relation to any other groups. This
metacharacter can only be used in the new_string parameter in REGEXREPLACE( ).
For example:
o If the pattern (\d{3})[ -]?(\d{3})[ -]?(\d{4}) is used to match a variety of different telephone number
formats, the new_string($1)-$2-$3 can be used to replace the numbers with themselves, and stand-
ardize the formatting. 999 123-4567 and 9991234567 both become (999)-123-4567.

Page 728 of 934

Commands

Metacharacter Description

\w Matches any word character (a to z, A to Z, 0 to 9, and the underscore character _ )

\W Matches any non-word character (not a to z, A to Z, 0 to 9, or the underscore character _ )

\d Matches any number (any decimal digit)

\D Matches any non-number (any character that is not a decimal digit)

\s Matches a space (a blank)

\S Matches any non-space (a non-blank character)

\b Matches a word boundary (between \w and \W characters)

Word boundaries consume no space themselves. For example:
o "United Equipment" contains 4 word boundaries – one either side of the space, and one at the start
and the end of the string. "United Equipment" is matched by the regular expression
\b\w*\b\W\b\w*\b
Tip
In addition to spaces, word boundaries can result from commas, periods, and other
non-word characters.
For example, the following expression evaluates to True:

REGEXFIND("jsmith@example.net", "\bexample\b")

^ Matches the start of a string

Inside brackets [ ], ^ negates the contents

$ Matches the end of a string

Related functions
If you want to find and replace matching patterns, use the "REGEXREPLACE( ) function" on the next page.

Page 729 of 934

Commands

REGEXREPLACE( ) function
Replaces all instances of strings matching a regular expression with a new string.

Syntax
REGEXREPLACE(string, pattern, new_string)

Parameters
Name Type Description

string character The field, expression, or literal value to test for a matching pattern.

pattern character The pattern string (regular expression) to search for.

new_string character The string to use to replace all values matching pattern.
The replacement string can contain literal characters, groups of char-
acters from the original string (using the $int element), or a com-
bination of the two.

Output
Character.

Examples
Basic examples
Working with spaces
Returns "AB CD EF", by replacing multiple spaces between text characters with a single space:

Page 730 of 934

Commands

REGEXREPLACE("AB CD EF", "\s+", " ")

Returns the character field data with the spacing between words standardized on a single space:

REGEXREPLACE(character_field, "\s+", " ")

Returns the character field data with the spacing between words standardized on a single space. Using the
BLANKS( ) function in new_string, rather than a literal space, makes spaces easier to read and less likely to
be overlooked:

REGEXREPLACE(character_field, "\s+", BLANKS(1))

Standardizing telephone numbers

Returns "(123) 456-7890". The formatting of the telephone number '1234567890' is standardized:

REGEXREPLACE(SUBSTR("1234567890",1,14), "(\d{3})[\s-](\d{3})[\s-](\d{4})","($1) $2-$3")

Returns the numbers in the Telephone_Number field and standardizes their formatting:

REGEXREPLACE(Telephone_Number, ".(\d{3})[\s-\.\)](\d{3})[\s-\.]*(\d{4})", "($1) $2-$3")

Extracts "123-456-7890" from the surrounding text:

REGEXREPLACE("Tel num: 123-456-7890 (office)", "(.)(\d{3}[\s-\)\.]\d{3}[\s-\.]\d{4})(.)", "$2")

Extracts telephone numbers from surrounding text in the Comment field and standardizes their formatting:

REGEXREPLACE(Comment, "(.)(\d{3})[\s-\)\.](\d{3})[\s-\.](\d{4})(.)","($2) $3-$4")

Identifying generic formats

Returns "9XXX-999xx", which represents the generic format of the value specified by string ("1ABC-
123aa"):

REGEXREPLACE(REGEXREPLACE(REGEXREPLACE("1ABC-123aa","\d","9"),"[a-z]","x"),"[A-Z]",
"X")

Returns the generic format of all identifiers in the Invoice_Number field:

Page 731 of 934

Commands

REGEXREPLACE(REGEXREPLACE(REGEXREPLACE(Invoice_Number,"\d","9"),"[a-z]","x"),"[A-
Z]", "X")

Standardizing name format

Returns "John David Smith":

REGEXREPLACE("Smith, John David", "^(\w+),(\s\w+)(\s\w+)?(\s\w+)?","$2$3$4 $1")

Returns the names in the Full_Name field in their regular order: First (Middle) (Middle) Last:

REGEXREPLACE(Full_Name, "^(\w+),(\s\w+)(\s\w+)?(\s\w+)?","$2$3$4 $1")

Note
Name data can present various complications, such as apostrophes in names. Account-
ing for variations in name data typically requires more complex regular expressions than
the one provided in the example above.

Remarks
How it works
The REGEXREPLACE( ) function uses a regular expression to find matching patterns in data, and
replaces any matching values with a new string.
For example:

REGEXREPLACE(character_field, "\s+", " ")

standardizes spacing in character data by replacing one or more spaces between text characters with a
single space.
The search portion of REGEXREPLACE( ) is identical to the REGEXFIND( ) function. For detailed inform-
ation about the search capability common to both functions, see "REGEXFIND( ) function" on page 723.

When to use REGEXREPLACE( )

Use REGEXREPLACE( ) any time you want to find and replace data in Analytics using simple or complex
pattern matching.

Page 732 of 934

Commands

Replacing characters with themselves

You can use the $int element to replace characters with themselves, which allows you to preserve the mean-
ingful parts of data, while standardizing or omitting surrounding or intermixed data.
Several examples using telephone numbers and names appear above.
To use the $int element you must first create groups by using parentheses ( ) in the pattern value. For more
information, see "REGEXFIND( ) function" on page 723.

Avoiding sequential character matching

You can avoid sequential character matching, and replace substrings regardless of their position in relation
to one another, by nesting REGEXREPLACE( ) functions.
The problem in the two examples below is to derive a generic format from alphanumeric source data in
which numbers and letters can appear in any order. Without knowing the order of numbers and letters, how
do you construct the pattern string?
The solution is to first find and replace numbers using the inner REGEXREPLACE( ) function, and then find
and replace letters using the outer REGEXREPLACE( ) function.
Returns "999XXX":

REGEXREPLACE(REGEXREPLACE("123ABC","\d","9"),"[A-Z]","X")

Returns "9X9X9X":

REGEXREPLACE(REGEXREPLACE("1A2B3C","\d","9"),"[A-Z]","X")

Replacement string length and truncation

When you use REGEXREPLACE( ) to create a computed field, the computed field length is identical to the
original field length.
If the replacement string length exceeds the target string length, overall string length increases, which res-
ults in truncation if the computed field length cannot accommodate the increased string length.
Characters that trail the target string are truncated first, followed by trailing replacement string characters.
The examples below illustrate truncation:

string pattern new_string Field length Result Truncated characters

x123x 123 A 5 "xAx" none

x123x 123 ABC 5 "xABCx" none

x123x 123 ABCD 5 "xABCD" "x"

Page 733 of 934

Commands

string pattern new_string Field length Result Truncated characters

x123x 123 ABCDE 5 "xABCD" "x", "E"

x123x 123 ABCDE 6 "xABCDE" "x"

x123x 123 ABCDE 7 "xABCDEx" none

How to avoid truncation

To avoid truncation, use the SUBSTR( ) function to increase field length, as demonstrated by the second
example below.
Returns "xABCD", which truncates the replacement character "E" and the existing character "x":

REGEXREPLACE("x123x","123","ABCDE")

Returns "xABCDEx", which includes all replacement characters and unreplaced existing characters:

REGEXREPLACE(SUBSTR("x123x",1,10),"123","ABCDE")

Regular expression metacharacters

Metacharacter Description

. Matches any character (except a new line character)

? Matches 0 or 1 occurrences of the immediately preceding literal, metacharacter, or element

* Matches 0 or more occurrences of the immediately preceding literal, metacharacter, or element

+ Matches 1 or more occurrences of the immediately preceding literal, metacharacter, or element

Page 734 of 934

Commands

Metacharacter Description

[] Matches any single character inside the brackets

() Creates a group that defines a sequence or block of characters, which can then be treated as a
single unit.
For example:
o S(ch)?mid?th? matches "Smith" or "Schmidt"
o (56A.*){2} matches any alphanumeric identifier in which the sequence "56A" occurs at least
twice
o (56A).*-.*\1 matches any alphanumeric identifier in which the sequence "56A" occurs at least
twice, with a hyphen located between two of the occurrences

\ An escape character that specifies that the character immediately following is a literal. Use the
escape character if you want to literally match metacharacters. For example, \( finds a left par-
enthesis, and \\ finds a backslash.
Use the escape character if you want to literally match any of the following characters:
^ $ . * + ? = ! : | \ ( ) [ ] { }
Other punctuation characters such as the ampersand (&) or the 'at sign' (@) do not require the
escape character.

\ int Specifies that a group, previously defined with parentheses ( ), recurs. int is an integer that identifies
the sequential position of the previously defined group in relation to any other groups. This
metacharacter can be used in the pattern parameter in both REGEXFIND( ) and REGEXREPLACE
( ).
For example:
o (123).*\1 matches any identifier in which the group of digits "123" occurs at least twice
o ^(\d{3}).*\1 matches any identifier in which the first 3 digits recur
o ^(\d{3}).*\1.*\1 matches any identifier in which the first 3 digits recur at least twice

Page 735 of 934

Commands

Metacharacter Description

o ^(\D)(\d)-.*\2\1 matches any identifier in which the alphanumeric prefix recurs with the alpha and
numeric characters reversed

$int Specifies that a group found in a target string is used in a replacement string. int is an integer that
identifies the sequential position of the group in the target string in relation to any other groups. This
metacharacter can only be used in the new_string parameter in REGEXREPLACE( ).
For example:
o If the pattern (\d{3})[ -]?(\d{3})[ -]?(\d{4}) is used to match a variety of different telephone number
formats, the new_string($1)-$2-$3 can be used to replace the numbers with themselves, and
standardize the formatting. 999 123-4567 and 9991234567 both become (999)-123-4567.

\w Matches any word character (a to z, A to Z, 0 to 9, and the underscore character _ )

\W Matches any non-word character (not a to z, A to Z, 0 to 9, or the underscore character _ )

\d Matches any number (any decimal digit)

\D Matches any non-number (any character that is not a decimal digit)

\s Matches a space (a blank)

\S Matches any non-space (a non-blank character)

\b Matches a word boundary (between \w and \W characters)

Word boundaries consume no space themselves. For example:
o "United Equipment" contains 4 word boundaries – one either side of the space, and one at the
start and the end of the string. "United Equipment" is matched by the regular expression
\b\w*\b\W\b\w*\b
Tip
In addition to spaces, word boundaries can result from commas, periods, and other
non-word characters.
For example, the following expression evaluates to True:

REGEXFIND("jsmith@example.net", "\bexample\b")

Page 736 of 934

Commands

Metacharacter Description

^ Matches the start of a string

Inside brackets [ ], ^ negates the contents

$ Matches the end of a string

Related functions
If you want to find matching patterns without replacing them, use the "REGEXFIND( ) function" on
page 723.

Page 737 of 934

Commands

REMOVE( ) function
Returns a string that includes only the specified characters.

Syntax
REMOVE(string, valid_characters)

Parameters
Name Type Description

string character The string to remove characters from.

valid_characters character The characters to retain in string.

If you specify double quotation marks in valid_characters, you must
enclose the list of characters in single quotation marks.
For example: '"-/'
Note
If a character you specify does not appear in string, it is
not included in the return value.

Output
Character.

Examples
Basic examples
Returns "ABC123 ":

REMOVE("ABC 123 XX4","ABC123")

Returns "ABC123XX ":

REMOVE("zABC 123 XX4","ABCX123")

Page 738 of 934

Commands

Returns "1234 ":

REMOVE("ABC 123 XX4", "1234567890")

Returns all the values in the Product_Number field with all non-numeric characters removed:

REMOVE(Product_Number,"0123456789")

Remarks
Note
The REMOVE( ) function has been superseded by the INCLUDE( ) and EXCLUDE( ) func-
tions.
REMOVE( ) is still available in the current version of Analytics for backwards compatibility
with earlier versions.

How it works
The REMOVE( ) function removes unwanted characters from character data and returns a fixed length
string.

When to use REMOVE( )

Use REMOVE( ) to normalize data fields that do not have a consistent format, such as address fields. You
can also use REMOVE( ) to remove punctuation or other invalid information from poorly edited fields.
You can also use the function to clean data in fields before using the SORT or JOIN commands, for duplic-
ate matching, or for report output.

Case sensitivity
The REMOVE( ) function is case-sensitive. If you specify "ID" in valid_characters, these characters are not
included in "id#94022". If there is a chance the case may be mixed, use the UPPER( ) function to convert
string to uppercase.
For example:

REMOVE(UPPER("id#94022"), "ID0123456789")

Related functions
REMOVE( ) is similar to the INCLUDE( ) function, with the following difference:

Page 739 of 934

Commands

l REMOVE( ) adds blanks to the end of the output to replace the characters that have been removed.
The original length of string is retained.
l INCLUDE( ) does not add any blanks.

Page 740 of 934

Commands

REPEAT( ) function
Returns a string that repeats a substring a specified number of times.

Syntax
REPEAT(string, count)

Parameters
Name Type Description

string character The string to repeat.

count numeric The number of times to repeat the value of string.

Output
Character.

Examples
Basic examples
Returns "ABCABCABC":

REPEAT("ABC",3)

Returns "000000000":

REPEAT("0",9)

Page 741 of 934

Commands

Remarks
When to use REPEAT( )
Use the REPEAT( ) function to initialize a variable with constant values or blanks, or to set a default value
for a computed field.

Page 742 of 934

Commands

REPLACE( ) function
Replaces all instances of a specified character string with a new character string.

Syntax
REPLACE(string, old_text, new_text)

Parameters
Name Type Description

string character The value to replace characters in.

old_text character The character string to replace. The search is case-sensitive.

new_text character The text to replace the value in old_text with.

Output
Character.

Examples
Basic examples
Returns "a12345efg":

REPLACE("abcdefg","bcd","12345")

Returns "Rd.":

REPLACE("Road","Road","Rd.")

Returns "ac":

REPLACE("abc","b","")

Page 743 of 934

Commands

Advanced examples
Removing specified characters
Use REPLACE( ) to remove a specified character string from a source string, by replacing it with an empty
character string ( "" ).
Returns "1234 Scott":

REPLACE("1234 Scott rd.", "rd.", "")

Field length adjustment

If new_text ("ABC") is longer than old_text ("X"), the field length of the resulting string is automatically
increased to accommodate the first replacement:
Returns "9ABC9", with a field length increased to 5 characters from 3 characters:

REPLACE("9X9", "X", "ABC")

The field length is not automatically increased for subsequent replacements, and truncation can result if
the field is not long enough to accommodate all the new characters.
Returns "9ABC9A":

REPLACE("9X9X", "X", "ABC")

To avoid truncation, you can increase the length of string using the BLANKS( ) function, or literal blank
spaces.
Returns "9ABC9ABC":

REPLACE("9X9X" + BLANKS(2), "X", "ABC")

REPLACE("9X9X" + " ", "X", "ABC")

If the resulting string is shorter than string, the resulting string is padded with blanks to maintain the same
field length.
Returns "9X9 ":

REPLACE("9ABC9", "ABC", "X")

Page 744 of 934

Commands

Remarks
How it works
The REPLACE( ) function replaces every instance of an existing string with a new string.
Returns "1234 Scott Road":

REPLACE("1234 Scott rd.", "rd.", "Road")

When to use REPLACE( )

Use REPLACE( ) for normalizing data fields with inconsistent formats, such as address fields, or for repla-
cing invalid information in poorly edited fields. To be performed accurately, operations such as duplicates
testing, or joining or relating tables, require data with a normalized or standardized format.

Case sensitivity
The REPLACE( ) function is case-sensitive. If you specify "RD." in old_text and the values in string are lower-
case, the new_text value will not be substituted because no matches will be found.
If there is a chance the case in string may be mixed, first use the UPPER( ) function to convert all characters
to uppercase.
Returns "1234 SCOTT ROAD":

REPLACE(UPPER("1234 Scott rd."), "RD.", "ROAD")

Protecting against inadvertent replacements

When building a REPLACE( ) expression you must be aware of every possible instance of old_text in string
so that you do not get inadvertent replacements.
Returns "645 RichaRoad Road", because the last two letters of "Richard" are "rd":

REPLACE("645 Richard rd ", "rd", "Road")

By adding both a leading space and a trailing space to the value in old_text ( " rd " ), you prevent the function
from replacing instances where "rd" occurs in a name, because in these instances there are no leading
spaces.
Returns "645 Richard Road":

REPLACE("645 Richard rd ", " rd ", " Road")

Page 745 of 934

Commands

REVERSE( ) function
Returns a string with the characters in reverse order.

Syntax
REVERSE(string)

Parameters
Name Type Description

string character The value to reverse the order of.

Output
Character.

Examples
Basic examples
Returns "E DCBA":

REVERSE("ABCD E")

Page 746 of 934

Commands

RJUSTIFY( ) function
Returns a right-justified string the same length as a specified string, with any trailing spaces moved to the left
of the string.

Syntax
RJUSTIFY(string)

Parameters
Name Type Description

string character The value to right-justify.

Output
Character.

Examples
Basic examples
Returns " ABC":

RJUSTIFY("ABC ")

Remarks
When to use RJUSTIFY( )
Use the RJUSTIFY( ) function to right-justify a character field.

Page 747 of 934

Commands

RLOGICAL( ) function
Returns a logical value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RLOGICAL(rScript|rCode <,field|value <,...n>>)

Parameters
Name Type Description

Output
Logical.

Page 748 of 934

Commands

Examples
Basic examples
Returns T:

RLOGICAL("(value1>0.6) & (value2>0.7) & (value3>0.5)", 0.8, 0.9, 0.55)

Advanced examples
Using an external R script
Accepts an amount, and an upper and lower threshold value. The function returns a truth value based on a
series of logical comparisons:

RLOGICAL("a<-'c:\\scripts\\sample.r');a[[1]]", expense_amt, threshold_low, threshold_hi)

External R script (sample.r):

test_truth <- function(amt, low, hi) {

return(((amt > low) & (amt < hi)) | ((amt==low) | (amt==hi)))
}
test_truth(value1, value2, value3)

Using R code stored in a variable

Performs a logical test of three fields using AND logic:

v_rcode = "(value1>0.6) & (value2>0.7) & (value3>0.5)"

RLOGICAL(v_rcode, PACKED, MICRO_LONG, ACCPAC)

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

Page 749 of 934

Commands

Running external R scripts on AX Server

Page 750 of 934

Commands

RNUMERIC( ) function
Returns a numeric value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RNUMERIC(rScript|rCode, decimals <,field|value <,...n>>)

Parameters
Name Type Description

decimals numeric The number of decimal places to include in the return value. Must be a
positive integer.

Output
Numeric.

Page 751 of 934

Commands

Examples
Basic examples
Returns 100 with 10 decimals (100.0000000000):

RNUMERIC("print(value1)", 10, 100)

Advanced examples
Storing R code as a variable
Returns 100 with 10 decimals (100.0000000000):

ASSIGN v_rcode = "print(value1)"
RNUMERIC(v_rcode, 10, 100)

Writing to an external file

Performs a simple addition and writes the comment attached to the function to file using the sink function in
R:

RNUMERIC("foo<-function(x,y){x+y};attr(foo, 'comment') <- 'foo performs simple addition';sink

('c:/temp/result.txt');attributes(foo);sink(NULL);foo(value1,value2)",0, amt, gross)

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

R log file
Analytics logs R language messages to an aclrlang.log file in the project folder. Use this log file for
debugging R errors.

Page 752 of 934

Commands

Tip
The log file is available in the Results folder of Analytics Exchange analytic jobs.

Running external R scripts on AX Server

Page 753 of 934

Commands

ROOT( ) function
Returns the square root of a numeric expression.

Syntax
ROOT(number, decimals)

Parameters
Name Type Description

number numeric The numeric expression to find the square root of.
This function returns zero if number is a negative number.

decimals numeric The number of decimals to use in the output.

Output
Numeric.

Examples
Basic examples
Returns 10.00:

ROOT(100, 2)

Returns 31.6228:

ROOT(1000, 4)

Page 754 of 934

Commands

Remarks
How it works
The ROOT( ) function returns the square root of the numeric expression or field value with the specified num-
ber of decimal places. The result is rounded appropriately.

When to use ROOT( )

Use LOG( ) to perform other root functions, such as cube root.

Page 755 of 934

Commands

ROUND( ) function
Returns a rounded whole number for a numeric value.

Syntax
ROUND(number)

Parameters
Name Type Description

number numeric The value to round to the nearest integer.

Output
Numeric.

Examples
Basic examples
Returns 7:

ROUND(7.2)

Returns 8:

ROUND(7.5)

Returns -8:

ROUND(-7.5)

Page 756 of 934

Commands

Advanced examples
Rounding monetary values
Creates a field that is equal to the balance rounded to the nearest dollar value:

DEFINE FIELD Nearest_dollar_value COMPUTED ROUND(Balance)

Remarks
How it works
ROUND( ) returns a number equal to the number value rounded to the nearest integer:

Positive values Negative values

Rounds up to the next integer >= 0.5 < 0.5

Rounds down to the next integer < 0.5 >= 0.5

Rounding to a particular number of decimal places

If you want to round a number to a particular number of decimal places, use the "DEC( ) function" on
page 530. The ROUND( ) function is the same as the DEC( ) function with zero decimal places specified.

ROUND(number)

is equivalent to:

DEC(number, 0)

Page 757 of 934

Commands

RSTRING( ) function
Returns a string value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RSTRING(rScript|rCode, length <,field|value <,...n>>)

Parameters
Name Type Description

length numeric The length to allocate for the return string.

Output
Character.

Page 758 of 934

Commands

Examples
Basic examples
Returns "abc123":

RSTRING("print(paste(value1,value2,sep=""))",6,"abc","123")

Advanced examples
Using an external R script
Concatenates x and y into a single string delimited by a space character:

RSTRING("a<-source('./sample.r');a[[1]]",50, FirstName, LastName)

External R script (sample.r):

conc <- function(x, y) {

paste(x, y, sep=" ")
}
print(conc(value1, value2))

Using R code stored in a variable

Concatenates x and y into a single string delimited by a space character:

ASSIGN v_script = "conc <- function(x, y){paste(x, y, sep=' ')};conc(value1, value2)"

RSTRING(v_script, 50, FirstName, LastName)

Using R to generate a UUID for a table

You are preparing a table of exceptions to upload to Results and you require a guaranteed unique identifier
for each record. To generate this field, you use the uuid package in R to create a unique primary key value
for each record:

EXTRACT RSTRING("uuid::UUIDgenerate()", 36) AS "id", first_name, last_name, birthdate TO

export_table

Page 759 of 934

Commands

Tip
To install the uuid package, open R.exe and execute the following command:

install.packages("uuid")

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

Running external R scripts on AX Server

Page 760 of 934

Commands

RTIME( ) function
Returns a time value calculated by an R function or script. Data processing in R is external to Analytics.

Syntax
RTIME(rScript|rCode <,field|value <,...n>>)

Parameters
Name Type Description

Output
Datetime.

Page 761 of 934

Commands

Examples
Basic examples
Returns `t0545`:

RTIME("value1+2700",`t0500`)

Advanced examples
Using an external R script
Adds 45 minutes to a time field by passing a field and a literal value to an external R function:

RTIME("a<-source('c:\\scripts\\sample.r');a[[1]]", end_time, 2700)

External R script (sample.r):

add_time <- function(start, sec) {

return(start + sec)
}
add_time(value1, value2)

# 'a' holds the response object and a[[1]] access the data value
"a<-source('c:\\scripts\\r_scripts\\sample.r');a[[1]]"

Page 762 of 934

Commands

Running external R scripts on AX Server

System time zone

Greenwich Mean Time (GMT) is the default current time zone in the R environment used by Analytics.

Page 763 of 934

Commands

SECOND( ) function
Extracts the seconds from a specified time or datetime and returns it as a numeric value.

Syntax
SECOND(time/datetime)

Parameters
Name Type Description

time/datetime datetime The field, expression, or literal value to extract the seconds from.

Output
Numeric.

Examples
Basic examples
Returns 30:

SECOND(`t235930`)

SECOND(`20141231 235930`)

Returns the seconds for each value in the Call_start_time field:

SECOND(Call_start_time)

Page 764 of 934

Commands

Remarks
Parameter details
A field specified for time/datetime can use any time or datetime format, as long as the field definition cor-
rectly defines the format.
Specifying a literal time or datetime value
When specifying a literal time or datetime value for time/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231 235959`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Time values – you can use any of the time formats listed in the table below. You must use a separator
before a standalone time value for the function to operate correctly. Valid separators are the letter 't',
or the letter 'T'. You must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.

Example formats Example literal values

thhmmss `t235959`

Thhmm `T2359`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Page 765 of 934

Commands

SHIFT( ) function
Returns a single character string with the bits in the first character of the input value shifted to the left or
right.

Syntax
SHIFT(character, number_of_bits_to_left)

Parameters
Name Type Description

character character The value to shift bits for.

number_of_bits_to_ numeric Specifies the number of bits to shift the character value.
left o If the value is positive – character is shifted to the left
o If the value is negative – character is shifted to the right
If the specified value is greater than 15 or less than -15 the result is
binary zero, CHR(0).

Output
Character.

Examples
Basic examples
Returns the letter "X", or CHR(88) (00010110 becomes 01011000):

SHIFT(CHR(22), 2)

Returns the backspace character, or CHR(8) (00010000 becomes 00001000):

SHIFT(CHR(16), -1)

Returns the grave accent character, or CHR(96) (10011011 becomes 01100000):

Page 766 of 934

Commands

SHIFT(CHR(155), 5)

Remarks
When to use SHIFT( )
Use the SHIFT( ) function in conjunction with the BYTE( ), CHR( ) and MASK( ) functions to isolate and
move individual bits in a record.

Page 767 of 934

Commands

SIN( ) function
Returns the sine of an angle expressed in radians, with a precision of 15 decimal places.

Syntax
SIN(radians)

Parameters
Name Type Description

radians numeric The measurement of the angle in radians.

Output
Numeric.

Examples
Basic examples
Returns 0.500000000000000 (the sine of the specified number of radians, equivalent to 30 degrees):

SIN(0.523598775598299)

Returns 0.500000000000000 (the sine value of 30 degrees):

SIN(30 * PI( )/180)

Advanced examples
Using degrees as input
Returns 0.500 (the sine of 30 degrees, rounded to 3 decimal places):

Page 768 of 934

Commands

DEC(SIN(30 * PI( )/180),3)

Remarks
Performing the Mantissa Arc Test
The three trigonometric functions in Analytics – SIN( ), COS( ), and TAN( ) – support performing the Mantissa
Arc Test associated with Benford's Law.

Converting degrees to radians

If your input is in degrees you can use the PI( ) function to convert the input to radians: (degrees * PI( )/180)
= radians. If required, you can round or truncate the return value using the DEC( ) function.

Page 769 of 934

Commands

SOUNDEX( ) function
Returns the soundex code for the specified string, which can be used for phonetic comparisons with other
strings.

Syntax
SOUNDEX(name)

Parameters
Name Type Description

name character The character expression to evaluate.

Output
Character. Returns a four-character soundex code.

Examples
Basic examples
Words that sound the same but are spelled differently
The two examples below return the same soundex code because they sound the same even though they
are spelled differently.
Returns F634:

SOUNDEX("Fairdale")

Returns F634:

SOUNDEX("Faredale")

Page 770 of 934

Commands

Words that sound similar

The two examples below return soundex codes that are different, but close to one another, because the two
words sound similar.
Returns J525:

SOUNDEX("Jonson")

Returns J523:

SOUNDEX("Jonston")

Words that sound different

The two examples below return soundex codes that are quite different, because the two words sound noth-
ing alike.
Returns S530:

SOUNDEX("Smith")

Returns M235:

SOUNDEX("MacDonald")

Field input
Returns the soundex code for each value in the Last_Name field:

SOUNDEX(Last_Name)

Advanced examples
Identifying matching soundex codes
Create the computed field Soundex_Code to display the soundex code for each value in the Last_Name
field:

DEFINE FIELD Soundex_Code COMPUTED SOUNDEX(Last_Name)

Add the computed field Soundex_Code to the view, and then perform a duplicates test on the computed
field to identify any matching soundex codes:

Page 771 of 934

Commands

DUPLICATES ON Soundex_Code OTHER Last_Name PRESORT OPEN TO "Possible_Dupes.fil"

Matching soundex codes indicate that the associated character values in the Last_Name field are pos-
sible duplicates.

Remarks
When to use SOUNDEX( )
Use the SOUNDEX( ) function to find values that sound similar. Phonetic similarity is one way of locating
possible duplicate values, or inconsistent spelling in manually entered data.

How it works
SOUNDEX( ) returns the American Soundex code for the evaluated string. All codes are one letter fol-
lowed by three numbers. For example: "F634".

How the soundex code is derived

l The first character in the code represents the first letter of the evaluated string.
l Each number in the code represents one of the six American Soundex groups. The groups are com-
posed of phonetically similar consonants.
Based on these groups, the soundex process encodes the first three consonants in the evaluated
string after the first letter.

What the soundex process ignores

The soundex process ignores:
l capitalization
l vowels
l the consonants "H", "W", and "Y"
l any consonants that appear after the three encoded consonants
One or more trailing zeros (0) in the returned code indicate an evaluated string with fewer than three con-
sonants after the first letter.

Limitations of the soundex process

Both the SOUNDEX( ) and SOUNDSLIKE( ) functions have certain limitations:
l The soundex algorithm is designed to work with words pronounced in English, and has varying
degrees of effectiveness when used with other languages.
l Although the soundex process performs a phonetic match, matching words must all begin with the
same letter, which means that some words that sound the same are not matched.

Page 772 of 934

Commands

For example, a word that begins with "F", and a word that begins with a "Ph", could sound the same
but they will never be matched.

Related functions
l SOUNDSLIKE( ) – an alternate method for phonetically comparing strings.
l ISFUZZYDUP( ) and LEVDIST – compare strings based on an orthographic comparison (spelling)
rather than on a phonetic comparison (sound).
l DICECOEFFICIENT( ) – de-emphasizes or completely ignores the relative position of characters or
character blocks when comparing strings.

Page 773 of 934

Commands

SOUNDSLIKE( ) function
Returns a logical value indicating whether a string phonetically matches a comparison string.

Syntax
SOUNDSLIKE(name, sounds_like_name)

Parameters
Name Type Description

name character The first string in the comparison.

sounds_like_name character The second string in the comparison.

Output
Logical. Returns T (true) if the values being compared phonetically match, and F (false) otherwise.

Examples
Basic examples
Returns T, because "Fairdale" and "Faredale" both have a soundex code of F634:

SOUNDSLIKE("Fairdale","Faredale")

Returns F, because "Jonson" has a soundex code of J525, and "Jonston" has a soundex code of J523:

SOUNDSLIKE("Jonson","Jonston")

Returns a logical value (T or F) indicating whether the soundex code for each value in the Last_Name field
matches the soundex code for the string "Smith":

SOUNDSLIKE(Last_Name,"Smith")

Page 774 of 934

Commands

Advanced examples
Isolating values that sound like "Smith"
Create a filter that isolates all values in the Last_Name field that sound like "Smith":

SET FILTER TO SOUNDSLIKE(Last_Name,"Smith")

Remarks
When to use SOUNDSLIKE( )
Use the SOUNDSLIKE( ) function to find values that sound similar. Phonetic similarity is one way of locating
possible duplicate values, or inconsistent spelling in manually entered data.

How it works
SOUNDSLIKE( ) converts the comparison strings to four-character American Soundex codes, which are
based on the first letter, and the first three consonants after the first letter, in each string.
The function then compares each string's code and returns a logical value indicating whether they match.
For more information about soundex codes, see "SOUNDEX( ) function" on page 770.

Case sensitivity
The function is not case-sensitive, so "SMITH" is equivalent to "smith."

Limitations of the soundex process

Both the SOUNDSLIKE( ) and SOUNDEX( ) functions have certain limitations:
l The soundex algorithm is designed to work with words pronounced in English, and has varying
degrees of effectiveness when used with other languages.
l Although the soundex process performs a phonetic match, matching words must all begin with the
same letter, which means that some words that sound the same are not matched.
For example, a word that begins with "F", and a word that begins with a "Ph", could sound the same
but they will never be matched.

Related functions
l SOUNDEX( ) – an alternate method for phonetically comparing strings.
l ISFUZZYDUP( ) and LEVDIST – compare strings based on an orthographic comparison (spelling)
rather than on a phonetic comparison (sound).

Page 775 of 934

Commands

l DICECOEFFICIENT( ) – de-emphasizes or completely ignores the relative position of characters or

character blocks when comparing strings.

Page 776 of 934

Commands

SPLIT( ) function
Returns a specified segment from a string.

Syntax
SPLIT(string, separator, segment <,text_qualifier>)

Parameters
Name Type Description

string character The value to extract the segment from.

separator character The character or characters that delimit segments.

For more information, see "How the separator character works" on
page 779.

segment numeric The segment to extract.

Use a number to specify which segment to extract. For example, to
extract the third segment, specify 3.

text_qualifier character The character or characters that indicate the start and end of segments
of text.
optional
If the separator character occurs inside a paired set of text qualifiers, it
is read as text and not as a separator.
You must enclose the text qualifier in quotation marks. A single quo-
tation mark text qualifier must be enclosed in double quotation marks,
and a double quotation mark text qualifier must be enclosed in single
quotation marks.
Tip
This optional parameter can be useful when working with
imported source data that retains separators and text
qualifiers.

Output
Character.

Page 777 of 934

Commands

Examples
Basic examples
Comma-delimited segments
Returns "seg1":

SPLIT("seg1,seg2,seg3", ",", 1)

Returns "seg3":

SPLIT("seg1,seg2,seg3", ",", 3)

Returns "" (the third segment is empty):

SPLIT("seg1,seg2,,seg4", ",", 3)

Multi-character and space delimiters

Returns "seg3":

SPLIT("seg1/*seg2/*seg3", "/*", 3)

Returns "Doe":

SPLIT("Jane Doe", " ", 2)

Escaping delimiters with a text qualifier

Returns "Doe, Jane", which includes a comma that is read as text rather than as a separator:

SPLIT('"Doe, Jane","Smith, John"', ",", 1, '"')

Advanced examples
Extracting digits from a credit card number
Use the SPLIT( ) command to remove dashes from a credit card number.

Page 778 of 934

Commands

Variables are used to capture each segment of the credit card number, and then the segments are con-
catenated together in an additional variable.

ASSIGN seg1 = SPLIT("4150-2222-3333-4444", "-", 1)

ASSIGN seg2 = SPLIT("4150-2222-3333-4444", "-", 2)
ASSIGN seg3 = SPLIT("4150-2222-3333-4444", "-", 3)
ASSIGN seg4 = SPLIT("4150-2222-3333-4444", "-", 4)
ASSIGN ccNum = seg1 + seg2 + seg3 + seg4

The value of ccNum is "4150222233334444".

The example illustrates the SPLIT( ) function, but note that the dashes can be removed more efficiently
using the EXCLUDE( ) function.

Remarks
How it works
The SPLIT( ) function breaks character data into segments based on separators such as spaces or com-
mas and returns a specified segment.

When to use SPLIT( )

Use the SPLIT( ) function to extract a particular segment of data from a record or field. The segment must
appear in the same position in each record or field.

How the separator character works

The separator character delimits, or indicates, the segments of data in a source string.
In a string with a number of segments, most of the segments appear between two separators. However, the
first segment may not have a separator character preceding it, and the last segment may not have a sep-
arator character following it.
For example:

SPLIT("seg1,seg2,seg3", ",", 1)

If the source string begins with a separator, the segment that follows the separator is treated as segment 2.
Returns "seg1":

SPLIT(",seg1,seg2,seg3", ",", 2)

Page 779 of 934

Commands

Case sensitivity
If separator or text_qualifier specify characters that have both an uppercase and a lowercase version, the
case used must match the case of the separator or text qualifier in the data.

Related functions
SPLIT( ) and SUBSTR( ) both return a segment of data from a longer source string.
l SPLIT( ) identifies the segment based on a separator character.
l SUBSTR( ) identifies the segment based on a numeric character position.

Page 780 of 934

Commands

STOD( ) function
Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation for "Serial to
Date".

Syntax
STOD(serial_date <,start_date>)

Parameters
Name Type Description

serial_date numeric The field, expression, or literal value to convert.

serial_date can be a serial date or a serial datetime. Only the date por-
tion of serial datetimes is considered. The time portion is ignored.

start_date datetime The start date from which serial dates are calculated. If omitted, the
default start date of 01 January 1900 is used.
optional

Output
Datetime. The date value is output using the current Analytics date display format.

Examples
Basic examples
Returns `20141231` displayed as 31 Dec 2014 assuming a current Analytics date display format of DD
MMM YYYY:

STOD(42003)

Returns `20181231` displayed as 31 Dec 2018 assuming a current Analytics date display format of DD
MMM YYYY:

STOD(42003, `19040101`)

Page 781 of 934

Commands

Returns the equivalent date for each serial date value in the Invoice_Date field:

STOD(Invoice_Date)

Advanced examples
Adjusting for a start date before 1900-01-01
Use date arithmetic to adjust the start date to a value that is earlier than the Analytics minimum date of
January 1, 1900:
1. Convert the serial date using the default start date.
2. Subtract the number of days before 1900-01-01 that the actual start date falls.
To use 1899-01-01 as the start date (evaluates to `20131231`):

STOD(42003) - 365

Remarks
How it works
The STOD( ) function allows you to convert serial dates to regular dates. Analytics serial dates represent
the number of days that have elapsed since 01 January 1900.

Serial date Regular date equivalent

1 02 January 1900

365 31 December 1900

42003 31 December 2014

0 not valid

For more information about serial dates, see Serial datetimes.

Analytics serial dates compared to Excel serial dates

Analytics serial dates are similar to Microsoft Excel serial dates. You should be aware of one key point of
similarity and one key point of difference. The two points are unrelated.

Page 782 of 934

Commands

Point of similarity
Both Analytics and Excel treat the year 1900 as a leap year, with 366 days. Although 1900 was not in fact a
leap year, Excel treated it as one in order to maintain compatibility with Lotus 1-2-3.

Point of difference
Analytics serial dates are offset from Excel serial dates by one day. In Excel, 01 January 1900 has a serial
date of '1'. In Analytics, 01 January 1900 is not counted, and 02 January 1900 has a serial date of '1'.

The start_date
Some source data files may use a start date other than 01 January 1900. The start_date allows you to
match the start date in a source data file. The start date is the date from which serial dates are calculated.

Start date in
source data
file Specify: Details

01 January STOD(date_field) You do not need to specify a start_date, because 01 January

1900 1900 is the default start date.

01 January STOD(date_field, `19010101`) You specify a start_date of `19010101` to match the start date of
1901 01 January 1901 used in the source data file.

01 January STOD(date_field) - 365 You cannot specify a start_date earlier than 01 January 1900. If
1899 a source data file uses a start date earlier than 01 January 1900,
you can create a datetime expression that subtracts an appro-
priate number of days from the output results of the STOD( ) func-
tion.

Other datetime conversion functions

Serial to Datetime conversion
Function Description

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional portion
of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Page 783 of 934

Commands

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a char-
acter or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can
also return the current operating system time.

Page 784 of 934

Commands

STODT( ) function
Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional portion of 24 hours –
to a datetime value. Abbreviation for "Serial to Datetime".

Syntax
STODT(serial_datetime <,start_date>)

Parameters
Name Type Description

serial_datetime numeric The field, expression, or literal value to convert.

Serial datetime values with the date and time portions separated by a
decimal point are required. For example, 42003.75000

start_date datetime The start date from which serial dates are calculated. If omitted, the
default start date of 01 January 1900 is used.
optional

Output
Datetime. The datetime value is output using the current Analytics date and time display formats.

Examples
Basic examples
Unadjusted start dates
Returns `20141231t060000` displayed as 31 Dec 2014 06:00:00 AM assuming current Analytics date and
time display formats of DD MMM YYYY and hh:mm:ss PM:

STODT(42003.25000)

Returns `20141231t191530` displayed as 31 Dec 2014 07:15:30 PM assuming current Analytics date and
time display formats of DD MMM YYYY and hh:mm:ss PM:

Page 785 of 934

Commands

STODT(42003.802431)

Adjusted start dates

Returns `20181231t120000` displayed as 31 Dec 2018 12:00:00 PM assuming current Analytics date and
time display formats of DD MMM YYYY and hh:mm:ss PM:

STODT(42003.50000, `19040101`)

Fields as input
Returns the equivalent datetime for each serial datetime value in the Receipt_datetime field:

STODT(Receipt_datetime)

Advanced examples
Adjusting for a start date before 1900-01-01
Use date arithmetic to adjust the start date to a value that is earlier than the Analytics minimum date of
January 1, 1900:
1. Convert the serial datetime using the default start date.
2. Subtract the number of days before 1900-01-01 that the actual start date falls.
To use 1899-01-01 as the start date (evaluates to `20131231t180000`):

STODT(42003.75000) - 365

Remarks
How it works
The STODT( ) function allows you to convert serial datetimes to regular datetimes. Analytics serial dat-
etimes represent the number of days that have elapsed since 01 January 1900, and following the decimal
point, represent a fractional portion of 24 hours, with 24 hours equaling 1.

Serial datetime Regular datetime equivalent

1.25 02 January 1900 06:00:00 AM

365.75000 31 December 1900 06:00:00 PM

Page 786 of 934

Commands

Serial datetime Regular datetime equivalent

42003.79167 31 December 2014 07:00:00 PM

42003.802431 31 December 2014 07:15:30 PM

42003.00000 31 December 2014 12:00:00 AM

42003.50000 31 December 2014 12:00:00 PM

0.0 not valid

For more information about serial datetimes, see Serial datetimes.

Analytics serial dates compared to Excel serial dates

Analytics serial dates are similar to Microsoft Excel serial dates. You should be aware of one key point of sim-
ilarity and one key point of difference. The two points are unrelated.

Start date in
source data
file Specify: Details

01 January STODT(datetime_field) You do not need to specify a start_date, because 01 January

1900 1900 is the default start date.

01 January STODT(datetime_field, You specify a start_date of `19010101` to match the start date of
1901 `19010101`) 01 January 1901 used in the source data file.

01 January STODT(datetime_field) - 365 You cannot specify a start_date earlier than 01 January 1900. If
1899 a source data file uses a start date earlier than 01 January 1900,
you can create a datetime expression that subtracts an appro-

Page 787 of 934

Commands

Start date in
source data
file Specify: Details

priate number of days from the output results of the STODT( )

function.

Other datetime conversion functions

Serial to Datetime conversion
Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a char-
acter or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a char-
acter or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can
also return the current operating system time.

Page 788 of 934

Commands

STOT( ) function
Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24 hours equaling 1
– to a time value. Abbreviation for "Serial to Time".

Syntax
STOT(serial_time)

Parameters
Name Type Description

serial_time numeric The field, expression, or literal value to convert.

serial_time can be a serial time or a serial datetime. Only the time por-
tion of serial datetimes is considered. The date portion is ignored.

Output
Datetime. The time value is output using the current Analytics time display format.

Examples
Basic examples
Returns `t060000` displayed as 06:00:00 AM assuming a current Analytics time display format of hh:mm:ss
PM:

STOT(0.25000)

Returns `t191530` displayed as 07:15:30 PM assuming a current Analytics time display format of hh:mm:ss
PM:

STOT(0.802431)

Returns the equivalent regular time for each serial time value in the Login_time field:

Page 789 of 934

Commands

STOT(Login_time)

Remarks
When to use STOT( )
Use the STOT( ) function to convert serial times to regular times.

What are serial times?

Analytics serial times represent a fractional portion of 24 hours, with 24 hours equaling 1.
For example:
l the serial time equivalent of 1 hour is 1/24, or 0.04167
l the serial time equivalent of 1 minute is 1/1440, or 0.0006945
Serial times can be prefaced with a '0' (zero) and a decimal point, or just a decimal point.

1.000000 is not a valid serial time

Although 24 hours equals 1 for the purposes of calculating serial times, 1.000000 is not a valid serial time.
Valid serial times are all decimal fractions less than 1. For example: 0.75000 (06:00:00 PM).
Analytics treats the serial number 1.000000 as the serial datetime equivalent to 02 Jan 1900 12:00:00 AM.
Because STOT( ) ignores the date portion of datetimes, STOT(1.000000) is equivalent to STOT
(0.000000) and both are equivalent to the regular time 12:00:00 AM.

Serial times and regular time equivalents

Serial time Regular time equivalent

0.00 12:00:00 AM

0.0006945 12:01:00 AM

0.04167 01:00:00 AM

0.0423645 01:01:00 AM

0.042998 01:01:55 AM

0.25 06:00:00 AM

0.50 12:00:00 PM

Page 790 of 934

Commands

Serial time Regular time equivalent

0.75 06:00:00 PM

0.79167 07:00:00 PM

0.802431 07:15:30 PM

1.00 12:00:00 AM

Other datetime conversion functions

Serial to Datetime conversion
Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional portion
of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a character
or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a character
or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Datetime to Character conversion

Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can also
return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

Page 791 of 934

Commands

Function Description

TIME( ) Extracts the time from a specified time or datetime and returns it as a character string. Can also
return the current operating system time.

Page 792 of 934

Commands

STRING( ) function
Converts a numeric value to a character string.

Syntax
STRING(number, length <,format>)

Parameters
Name Type Description

number numeric The numeric value to convert to a string.

length numeric The number of characters in the output string.

format character The formatting to apply to the output string. For example, "(9,999.99)"
optional

Output
Character.

Examples
Basic examples
Unformatted strings
Returns " 125.2":

STRING(125.2, 6)

Returns "25.2" (-1 is truncated because length is less than the number of digits and formatting characters in
number):

STRING(-125.2, 4)

Page 793 of 934

Commands

Returns " -125.2":

STRING(-125.2, 7)

Formatted strings
Returns " (125.20)":

STRING(-125.2, 10, "(9,999.99)")

Returns "25.20" (1 is truncated because length is less than the number of digits and formatting characters
in number):

STRING(125.2, 6, "(9,999.99)")

Field input
Returns numeric values in the Employee_number field as character strings with a length of 10 characters.
If required, the return value is padded or truncated:

STRING(Employee_number, 10)

Remarks
Padded and truncated return values
STRING( ) converts number into a character string of the length specified in length:
l If number is shorter than length, leading spaces are added to the return value
l If number is longer than length, the return value is truncated from the left side

Formatting the return value

The optional format parameter adds formatting to the return value such as dollar signs, percent symbols,
decimals, commas, negative indicators, or parentheses. The format must be enclosed in double quotation
marks.
The digit 9 acts as a placeholder for digits to format. Ensure that you have the correct number of 9s for
proper display. You also need to account for decimals and formatting characters, such as dollar signs and
brackets for negative numbers, when you specify the value for the length.

Page 794 of 934

Commands

Related functions
The STRING( ) function is the opposite of the VALUE( ) function, which converts character data to numeric
data.

Page 795 of 934

Commands

SUBSTR( ) function
Returns a specified substring from a string.

Syntax
SUBSTR(string, start, length)

Parameters
Name Type Description

string character The value to extract the substring from.

start numeric The starting character position of the substring.

length numeric The number of characters in the substring.

If length is 0, the output is blank.

Output
Character.

Examples
Basic examples
Literal character input
Returns "BCD":

SUBSTR("ABCDEF", 2, 3)

Returns "EF":

SUBSTR("ABCDEF", 5, 10)

Page 796 of 934

Commands

Parsing structured character data

Returns "189543":

SUBSTR("***189543***", 4, 6)

Returns the four-digit year out of a character field containing dates formatted as "MM/DD/YYYY":

SUBSTR(DATE, 7, 4)

Advanced examples
Increasing field length
Use SUBSTR( ) to increase the length of a character field. Increasing the length of a field is a common har-
monization task that you may need to perform before joining or appending two fields.
The example below pads the Product_Description field with blank spaces to create the computed field
Product_Description_Long with a length of 50 characters.

DEFINE FIELD Product_Description_Long COMPUTED SUBSTR(Product_Description, 1, 50)

Remarks
How it works
The SUBSTR( ) function returns characters from the string value starting at the character position specified
by start. The number of characters returned is specified by length.

How SUBSTR( ) handles spaces

Leading, trailing, or internal spaces in the string value are treated like characters. Spaces captured by start
and length are included in the output string.

How padding works

If the length value exceeds the number of characters, including trailing spaces, from the start position to the
end of string, the output string may or may not be padded on the right with spaces.

Padded with spaces

If you use SUBSTR( ) within a command that creates a field, the output is padded with spaces.

Padding when creating a computed field

Page 797 of 934

Commands

Creates the computed field Product_Description_Long, with a length of 50 characters, based on the phys-
ical field Product_Description, with a length of 24 characters:

DEFINE FIELD Product_Description_Long COMPUTED SUBSTR(Product_Description, 1, 50)

Padding when extracting a physical field

Extracts the field Product_Description_Long, with a length of 50 characters, to a new table, based on the
physical field Product_Description, with a length of 24 characters:

EXTRACT FIELDS SUBSTR(Product_Description, 1, 50) AS "Product_Description_Long" TO New_

Table

Not padded with spaces

If you use SUBSTR( ) in a variable definition or an expression, the output is not padded with spaces.

No padding when defining a variable

Creates the variable v_prod_desc, with a length of 24 characters, based on the field length of Product_
Description:

ASSIGN v_prod_desc = SUBSTR(Product_Description, 1, 50)

Note
Even though SUBSTR( ) specifies a length of 50 characters, the output is limited to the
field length of Product_Description.

Related functions
SUBSTR( ) and SPLIT( ) both return a segment of data from a longer source string.
l SUBSTR( ) identifies the segment based on a numeric character position.
l SPLIT( ) identifies the segment based on a separator character.

Page 798 of 934

Commands

TAN( ) function
Returns the tangent of an angle expressed in radians, with a precision of 15 decimal places.

Syntax
TAN(radians)

Parameters
Name Type Description

radians numeric The measurement of the angle in radians.

Output
Numeric.

Examples
Basic examples
Returns 0.999999999999999 (the tangent of the specified number of radians, equivalent to 45 degrees):

TAN(0.785398163397448)

Returns 0.999999999999999 (the tangent of 45 degrees):

TAN(45 * PI( )/180)

Advanced examples
Using degrees as input
Returns 1.000 (the tangent of 45 degrees, rounded to 3 decimal places):

Page 799 of 934

Commands

DEC(TAN(45 * PI( )/180),3)

Remarks
Performing the Mantissa Arc Test
The three trigonometric functions in Analytics – SIN( ), COS( ), and TAN( ) – support performing the Man-
tissa Arc Test associated with Benford's Law.

Converting degrees to radians

Page 800 of 934

Commands

TEST( ) function
Returns a logical value indicating whether a specified string occurs at a specific byte position in a record.

Syntax
TEST(byte_position, string)

Parameters
Name Type Description

byte_position numeric The sequential number from the left in the table layout that identifies
the location of the first character of string.
The function evaluates to F if the start of string is not identified at this
position, even if string appears at another position in the record.

string character The character string to search for.

The search is case-sensitive. If there is a chance the case may be
mixed, use the UPPER( ) function to convert all characters to upper-
case.

Output
Logical. Returns T (true) if the specified string starts at the specified byte location within a record, and F
(false) otherwise.

Examples
Basic examples
Given a record containing:

Department: Marketing
....|....|....|....|....|

Returns T:

Page 801 of 934

Commands

TEST(5, "Department")

Returns F, because in the record, "Department" starts at the fifth byte position, not the sixth:

TEST(6, "Department")

Returns F, because the function is case-sensitive:

TEST(5, "DEPARTMENT")

Advanced examples
Isolating records that are page headings
Use TEST( ) to create a filter that isolates all records that start with "Page:":

SET FILTER TO TEST(1, "Page:")

Page 802 of 934

Commands

TIME( ) function
Extracts the time from a specified time or datetime and returns it as a character string. Can also return the
current operating system time.

Syntax
TIME(< time/datetime> <,format>)

Parameters
Name Type Description

time/datetime datetime The field, expression, or literal value to extract the time from. If omitted,
the current operating system time is returned in the format hh:mm:ss.
optional

format character The format to apply to the output string, for example "hh:mm:ss". If omit-
ted, the current Analytics time display format is used. You cannot spe-
optional
cify format if you have omitted time/datetime.

Output
Character.

Examples
Basic examples
Literal input values
Returns "23:59:59" assuming an Analytics time display format of hh:mm:ss:

TIME(`20141231 235959`)

Returns "11:59 P":

TIME(`20141231 235959`, "hh:mm A")

Page 803 of 934

Commands

Returns the current operating system time returned as a character string in hh:mm:ss format (24-hour
clock):

TIME()

Field as input values

Returns a character string for each value in the Receipt_timestamp field, using the current Analytics time
display format:

TIME(Receipt_timestamp)

Returns a character string for each value in the Receipt_timestamp field, using the specified time display
format:

TIME(Receipt_timestamp, "hh:mm:ss")

Advanced examples
Calculating the elapsed time for a command or a script to execute
Use the TIME( ) function to help calculate the amount of time a particular Analytics command, or an entire
script, takes to execute.
Immediately before the command you want to time, or at the start of the script, specify this line to create a
variable that stores the current operating system time:

ASSIGN Time_started = TIME()

Immediately after the command, or at the end of the script, specify the two lines below.
The first line creates a variable that stores the operating system time after the command or script com-
pletes. The second line calculates the difference between the finish and start times, and converts the result
to an easily readable format.
Tip
You can double-click the CALCULATE log entry to see the elapsed time for the command
or the script.

ASSIGN Time_finished = TIME()

CALCULATE STOT(CTOT(Time_finished) - CTOT(Time_started))

If the command or script will run over the boundary of midnight, use this second line instead:

Page 804 of 934

Commands

CALCULATE `T000000` - (CTOT(Time_started) - CTOT(Time_finished))

Remarks
Output string length
The length of the output string is always 14 characters. If the specified output format, or the Analytics time
display format, is less than 14 characters, the output string is padded with trailing blank spaces.

Parameter details
A field specified for time/datetime can use any time or datetime format, as long as the field definition cor-
rectly defines the format.
If you use format to control how the output string is displayed, you are restricted to the formats in the table
below. You can use any combination of time and AM/PM formats. The AM/PM format is optional, and is
placed last.
Specify format using single or double quotation marks. For example: "hh:mm:ss AM".

Time formats AM/PM formats Examples

hh:mm:ss none "hh:mm:ss"

24-hour clock

hhmmss AM, or PM "hhmmss PM"

12-hour clock

hh:mm A, or P "hh:mm A"

12-hour clock

hhmm

Specifying a literal time or datetime value

When specifying a literal time or datetime value for time/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231 235959`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Time values – you can use any of the time formats listed in the table below. You must use a separator
before a standalone time value for the function to operate correctly. Valid separators are the letter 't',
or the letter 'T'. You must specify times using the 24-hour clock. Offsets from Coordinated Universal

Page 805 of 934

Commands

Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).
l Datetime values – you can use any combination of the date, separator, and time formats listed in
the table below. The date must precede the time, and you must use a separator between the two.
Valid separators are a single blank space, the letter 't', or the letter 'T'.

Example formats Example literal values

thhmmss `t235959`

Thhmm `T2359`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset.
For example, avoid: hh+hhmm. Results
can be unreliable.

Related functions
If you need to return the current operating system time as a datetime value, use NOW( ) instead of TIME(
).

Other datetime conversion functions

Datetime to Character conversion
Function Description

DATE( ) Extracts the date from a specified date or datetime and returns it as a character string. Can
also return the current operating system date.

DATETIME( ) Converts a datetime to a character string. Can also return the current operating system dat-
etime.

Page 806 of 934

Commands

Character or Numeric to Datetime conversion

Function Description

CTOD( ) Converts a character or numeric date value to a date. Can also extract the date from a character
or numeric datetime value and return it as a date. Abbreviation for "Character to Date".

CTODT( ) Converts a character or numeric datetime value to a datetime. Abbreviation for "Character to
Datetime".

CTOT( ) Converts a character or numeric time value to a time. Can also extract the time from a character
or numeric datetime value and return it as a time. Abbreviation for "Character to Time".

Serial to Datetime conversion

Function Description

STOD( ) Converts a serial date – that is, a date expressed as an integer – to a date value. Abbreviation
for "Serial to Date".

STODT( ) Converts a serial datetime – that is, a datetime expressed as an integer, and a fractional portion
of 24 hours – to a datetime value. Abbreviation for "Serial to Datetime".

STOT( ) Converts a serial time – that is, a time expressed as a fractional portion of 24 hours, with 24
hours equaling 1 – to a time value. Abbreviation for "Serial to Time".

Page 807 of 934

Commands

TODAY( ) function
Returns the current operating system date as a Datetime data type.

Syntax
TODAY()

Parameters
This function does not have any parameters.

Output
Datetime.

Examples
Basic examples
Returns the current operating system date as a datetime value, for example `20141231`, displayed using
the current Analytics date display format:

TODAY()

Remarks
Related functions
If you need to return the current operating system date as a character string, use DATE( ) instead of
TODAY( ).

Page 808 of 934

Commands

TRANSFORM( ) function
Reverses the display order of bi-directional text within a specified string.

Syntax
TRANSFORM(original_string)

Parameters
Name Type Description

original_string character The string containing bi-directional text.

Output
Character.

Examples
Basic examples
In the input string, the characters "XZQB" represent Hebrew/bidirectional characters in an input string that
otherwise contains regular characters.
In the output string, the direction of "XZQB" is reversed, and returns "BQZX". The other characters are
unmodified.
Returns "ABC BQZX 123":

TRANSFORM("ABC XZQB 123")

Page 809 of 934

Commands

Remarks
How it works
The TRANSFORMS( ) function identifies bi-directional data and displays it correctly in the view, from right
to left.
All other characters processed by the function are unmodified and continue to display from left to right.

When to use TRANSFORMS( )

Use TRANSFORMS( ) to adjust the display order of Arabic or Hebrew characters, so they display cor-
rectly.

Page 810 of 934

Commands

TRIM( ) function
Returns a string with trailing spaces removed from the input string.

Syntax
TRIM(string)

Parameters
Name Type Description

string character The value to remove trailing spaces from.

Output
Character.

Examples
Basic examples
Note that in both examples the leading spaces and spaces between words are not removed by the TRIM( )
function.
Returns " Vancouver":

TRIM(" Vancouver ")

Returns " New York":

TRIM(" New York")

Advanced examples
Removing non-breaking spaces

Page 811 of 934

Commands

Non-breaking spaces are not removed by the TRIM( ) function.

If you need to remove trailing non-breaking spaces, create a computed field using the following expres-
sion:

DEFINE FIELD Description_cleaned COMPUTED TRIM(REPLACE(Description, CHR(160), CHR

(32)))

The REPLACE( ) function replaces any non-breaking spaces with regular spaces, and then TRIM( )
removes any trailing regular spaces.

Remarks
How it works
The TRIM( ) function removes trailing spaces only. Spaces inside the string, and leading spaces, are not
removed.

Related functions
TRIM( ) is related to the LTRIM( ) function, which removes any leading spaces from a string, and to the
ALLTRIM( ) function, which removes both leading and trailing spaces.

Page 812 of 934

Commands

UNSIGNED( ) function
Returns numeric data converted to the Unsigned data type.

Syntax
UNSIGNED(number, length_of_result)

Parameters
Name Type Description

number numeric The value to convert.

length_of_result numeric The number of bytes to use in the output string.

Output
Numeric.

Examples
Basic examples
Returns 000075:

UNSIGNED(75, 3)

UNSIGNED(-75, 3)

UNSIGNED(7.5, 3)

Returns 2456 (1 is truncated because only 4 digits can be stored when the length_of_result is 2):

UNSIGNED(12456, 2)

Page 813 of 934

Commands

Returns 000000012456:

UNSIGNED(-12.456, 6)

Remarks
What is Unsigned data?
The Unsigned data type is used by mainframe operating systems to store numeric values in a format that
uses minimal space, storing two digits in each byte. The Unsigned data type is the same as the Packed
data type, but it does not use the last byte to specify whether the value is positive or negative.

When to use UNSIGNED( )

Use the UNSIGNED( ) function to convert numeric data to the Unsigned format for export to mainframe
systems.

Truncated return values

If the length_of_result value is shorter than the length of the number value, the additional digits are trun-
cated.

Page 814 of 934

Commands

UPPER( ) function
Returns a string with alphabetic characters converted to uppercase.

Syntax
UPPER(string)

Parameters
Name Type Description

string character The value to convert to uppercase.

Output
Character.

Examples
Basic examples
Returns "ABC":

UPPER("abc")

Returns "ABC 123 DEF":

UPPER("abc 123 DEF")

Returns "ABCD 12":

UPPER("AbCd 12")

Returns all the values in the Last_Name field converted to uppercase:

Page 815 of 934

Commands

UPPER(Last_Name)

Remarks
How it works
The UPPER( ) function converts all alphabetic characters in string to uppercase. All non-alphabetic char-
acters are left unchanged.

When to use UPPER( )

Use UPPER( ) when you need to ensure that all characters in a field, variable, or expression have con-
sistent casing. Consistent casing is particularly important when you are comparing values.
UPPER( ) can also be used for formatting values in reports as uppercase text.

Page 816 of 934

Commands

UTOD( ) function
Converts a Unicode string containing a formatted date to an Analytics date value. Abbreviation for "Unicode
to Date".
Note
This function is specific to the Unicode edition of Analytics. It is not a supported function in
the non-Unicode edition.
Use this function when working with dates in languages and formats that are different from
your default installation. If the string you want to convert is in your default language, use
CTOD( ) instead.

Syntax
UTOD(string <,locale> <,style>)

Parameters
Name Type Description

string character The Unicode string to convert to a date.

The Unicode string can contain a datetime value, but the time portion
of the value is ignored. Standalone time values are not supported.
string must match the input format required by the style value for the
date's locale.

locale character The code that specifies the language and locale of the output string,
and optionally the version of the language associated with a particular
optional
country or region.
For example, "zh" specifies Chinese, and "pt_BR" specifies Brazilian
Portuguese.
If omitted, the default locale for your computer is used. If a language is
specified, but no country is specified, the default country for the lan-
guage is used.
You cannot specify locale if you have not specified date.
For more information about locale codes, see www.unicode.org.

style numeric The date format style to use for the Unicode string. The format style
matches the standard for the locale you specify:
optional
o 0 – full specification format, such as "Sunday, September 18, 2016"
o 1 – long format, such as "September 18, 2016"

Page 817 of 934

Commands

Name Type Description

o 2 – medium format, such as "Sep 18, 2016"

o 3 – short, numeric format such as "9/18/16"
If omitted, the default value of 2 is used. You cannot specify style if you
have not specified locale.
Tip
For help determining the expected format of your input
string, do one of the following:
l Use the DTOU( ) function to generate an example
value using the style and locale.
In the command line, use the DISPLAY command
to print the value:

DISPLAY DTOU(`20160909`, "es_MX", 3)

l Consult an authoritative source on the standard

date format for the style in the specific locale.

Output
Datetime. The date value is output using the current Analytics date display format.

Examples
Basic examples
Note
All examples assume a current Analytics date display format of DD MMM YYYY.
In the examples below, the locale code for Chinese ( "zh" ) and Simplified Chinese ( "zh_
CN" ) match different input strings and are not interchangeable.
You must also specify the correct style. A long Unicode date string (that is, style is 1 ) does
not return an Analytics date if you specify a style of 2.

Literal input values

Returns `20141231` displayed as 31 Dec 2014:

UTOD("31 de dezembro de 2014", "pt_BR", 1)

Returns `20141231` displayed as 31 Dec 2014:

Page 818 of 934

Commands

UTOD("31 grudnia 2014", "pl", 1)

Field input values

Returns the date equivalent for each Unicode string in the Invoice_date field:

UTOD(Invoice_date, "zh", 1)

Input uses full date style

Returns `20141231` displayed as 31 Dec 2014 (no region identifier specified):

UTOD("星期三, 2014 十二月 31", "zh", 0)

Returns `20141231` displayed as 31 Dec 2014 (region identifier specified):

UTOD("2014年12月31日星期三", "zh_CN", 0)

Input uses long date style

Returns `20141231` displayed as 31 Dec 2014 (no region identifier specified):

UTOD("2014 十二月 31", "zh", 1)

Returns `20141231` displayed as 31 Dec 2014 (region identifier specified):

UTOD("2014年12月31日", "zh_CN", 1)

Remarks
Converting Unicode strings successfully
To successfully convert Unicode strings containing dates into Analytics dates you must specify locale and
style parameters that match the language country/region (if applicable), and style of the date in the Unicode
string.

Related functions
UTOD( ) is the inverse of DTOU( ), which converts a date to a Unicode string. If you are uncertain which
country/region and style to specify for UTOD( ), you can use DTOU( ) and experiment with different para-

Page 819 of 934

Commands

meters to produce an output Unicode string that matches the form of the input Unicode strings you want to
convert with UTOD( ).

Page 820 of 934

Commands

VALUE( ) function
Converts a character string to a numeric value.

Syntax
VALUE(string, decimals)

Parameters
Name Type Description

string character The field, literal, or expression to convert.

decimals numeric The number of decimal places to include in the output.

Output
Numeric.

Examples
Basic examples
Returns -123.400:

VALUE("123.4-", 3)

Returns 123456.00:

VALUE("$123,456", 2)

Returns -77.45:

VALUE("77.45CR", 2)

Returns -123457:

Page 821 of 934

Commands

VALUE(" (123,456.78)", 0)

Field input
Returns character values in the Salary field as numbers without any decimal places:

VALUE(Salary, 0)

Remarks
How it works
This function converts character data to numeric data. You can use the VALUE( ) function if you need to
convert character expressions or field values to numeric values for use in Analytics commands.

Numeric input formatting

VALUE( ) accepts numbers in any format. You can use any numeric formatting accepted by the Print data
type such as punctuation, leading or trailing signs, and parentheses as input.

Negative values
The VALUE( ) function can interpret different indicators of negative values such as parentheses and the
minus sign. It can also interpret CR (credit) and DR (debit). For example:
Returns -1000.00:

VALUE("(1000)", 2)

VALUE("1000CR", 2)

Decimal vs integer values

If the string value does not include decimals, Analytics treats the number as an integer. For example:
Returns 123.00:

VALUE("123", 2)

If the number of decimals specified by decimals is less than the number in the field or expression, the result
is rounded. For example:

Page 822 of 934

Commands

Returns "10.6":

VALUE("10.56", 1)

Related functions
The VALUE( ) function is the opposite of the STRING( ) function, which converts numeric data to character
data.

Page 823 of 934

Commands

VERIFY( ) function
Returns a logical value indicating whether the data in a physical data field is valid.

Syntax
VERIFY(field)

Parameters
Name Type Description

field character Must be a physical data field.

numeric
datetime

Output
Logical. Returns T (true) if data in the field is valid, and F (false) otherwise.

Examples
Basic examples
Extracts any records where the VERIFY( ) function evaluates to false to a new Analytics table:

EXTRACT RECORD IF NOT VERIFY(Address) TO "InvalidEntries.fil"

Remarks
The VERIFY( ) function determines whether the data in a field is consistent with the specified data type for
the field.

Page 824 of 934

Commands

When to use VERIFY( )

The function provides more precise control over the fields you want to verify than either the VERIFY com-
mand or the Verify Data option in the Numeric tab in the Options dialog box (Tools > Options ). You can
use the function to detect errors in individual fields and proceed in a situation-specific manner.

When the function evaluates to true

For the function to evaluate to true:
l character fields must contain only valid, printable characters, such as letters, numbers, and symbols
l numeric fields must contain only valid numeric characters, such as numbers, decimals, and currency
symbols
l datetime fields must contain only valid dates, datetimes, or times

Computed fields and expressions

Computed fields and expressions always evaluate to T (true), so this function cannot be used with computed
fields or expressions unless they are first converted to physical fields. Using the Fields option in the Extract
dialog box to extract computed fields or expressions converts them to physical fields.

Page 825 of 934

Commands

WORKDAY( ) function
Returns the number of workdays between two dates.

Syntax
WORKDAY(start_date, end_date <,nonworkdays>)

Parameters
Name Type Description

start_date datetime The start date of the period for which workdays are calculated. The
start date is included in the period.

end_date datetime The end date of the period for which workdays are calculated. The
end date is included in the period.

nonworkdays character The days of the week that are weekend days, or non workdays, and
excluded from the calculation. If nonworkdays is omitted, Saturday
optional
and Sunday are used as the default non workdays.
Enter nonworkdays using the following abbreviations, separated by a
space or a comma:
o Mon
o Tue
o Wed
o Thu
o Fri
o Sat
o Sun
nonworkdays is not case-sensitive. The abbreviations must be
entered in English even if you are using a non-English version of Ana-
lytics:

"Fri, Sat, Sun"

Note
You can specify a datetime value for start_date or end_date but the time portion of the
value is ignored.
If start_date is more recent than end_date, a negative value is returned.

Page 826 of 934

Commands

Output
Numeric. The number of workdays in the period for which workdays are calculated.

Examples
Basic examples
Literal input values
Returns 5 (the number of workdays between Monday, March 02, 2015 and Sunday, March 08, 2015 inclus-
ive):

WORKDAY(`20150302`, `20150308`)

Returns 6 (the number of workdays between Monday, March 02, 2015 and Sunday, March 08, 2015 inclus-
ive, when Sunday is the only non workday):

WORKDAY(`20150302`, `20150308`, "Sun")

Returns 5 (the number of workdays between Sunday, March 01, 2015 and Saturday, March 07, 2015 inclus-
ive, when Friday and Saturday are the non workdays):

WORKDAY(`20150301`, `20150307`, "Fri, Sat")

Field input values

Returns the number of workdays between each date in the Start_date field and December 31, 2015 inclus-
ive:

WORKDAY(Start_date, `20151231`)

Returns the number of workdays between each date in the Start_date field and a corresponding date in the
End_date field inclusive:
l Statutory holidays are included in the workdays total and may need to be factored out using a sep-
arate calculation
l A negative return value indicates a start date that is more recent than an end date

WORKDAY(Start_date, End_date)

Page 827 of 934

Commands

Remarks
Date formats
A field specified for start_date or end_date can use any date format, as long as the field definition correctly
defines the format.
When specifying a literal date value for start_date or end_date, you are restricted to the formats
YYYYMMDD and YYMMDD, and you must enclose the value in backquotes – for example, `20141231`.

Non workdays other than Saturday and Sunday

The ability to specify non workdays other than Saturday and Sunday allows you to use the WORKDAY( )
function with data that is not based on a Monday-to-Friday work week, or on a five-day work week.
For example, if you specify "Sun" by itself as a non workday, you create a six-day work week from Monday
to Saturday.

Accounting for statutory holidays

The WORKDAY( ) function does not take into account statutory holidays, which means that the return
value may not reflect the actual number of workdays in a period if the period contains one or more stat-
utory holidays.

"Calculate Working Days" script in ScriptHub

If you need to account for statutory holidays, one option is to use the Calculate Working Days script in
ScriptHub, which accepts a list of user-defined holidays.
For data that covers longer time periods and includes a number of holidays, using the script is probably the
easier approach. For more information, see "Importing scripts from ScriptHub" in the Analytics Help.
For shorter time periods with only three or four holidays, such as a quarter, you may find creating the con-
ditional computed field described below is not too laborious.

Conditional computed field for deducting statutory holidays

If required, you can create a conditional computed field to deduct statutory holidays from the value
returned by the WORKDAY( ) function.
For example, for first-quarter data for 2015, you could decrement the WORKDAY( ) return value by 1 for
each of these holidays that falls into a specified period:
l 01 January 2015
l 19 January 2015
l 16 February 2015
The example that follows accommodates periods that have any start date and end date during the quarter.

Page 828 of 934

Commands

You first create a computed field, for example Workdays , that calculates the workdays for a specified period
during the quarter:

DEFINE FIELD Workdays COMPUTED WORKDAY(Start_date, End_date)

You then create a conditional computed field, for example Workdays_no_holidays , that adjusts the value
returned by the first computed field (Workdays ):

DEFINE FIELD Workdays_no_holidays COMPUTED

Workdays-1 IF Start_date = `20150101` AND End_date < `20150119`

Workdays-2 IF Start_date = `20150101` AND End_date < `20150216`
Workdays-3 IF Start_date = `20150101` AND End_date <= `20150331`
Workdays   IF Start_date < `20150119` AND End_date < `20150119`
Workdays-1 IF Start_date < `20150119` AND End_date < `20150216`
Workdays-2 IF Start_date < `20150119` AND End_date <= `20150331`
Workdays-1 IF Start_date = `20150119` AND End_date < `20150216`
Workdays-2 IF Start_date = `20150119` AND End_date <= `20150331`
Workdays   IF Start_date < `20150216` AND End_date < `20150216`
Workdays-1 IF Start_date < `20150216` AND End_date <= `20150331`
Workdays-1 IF Start_date = `20150216` AND End_date <= `20150331`
Workdays   IF Start_date < `20150331` AND End_date <= `20150331`
Workdays

Note
The order of the conditions in the conditional computed field is important.
Analytics evaluates multiple conditions starting at the top. The first condition that evaluates
to true for a record assigns the value of the conditional computed field for that record. A sub-
sequent condition that evaluates to true does not change the assigned value.

Page 829 of 934

Commands

YEAR( ) function
Extracts the year from a specified date or datetime and returns it as a numeric value using the YYYY
format.

Syntax
YEAR(date/datetime)

Parameters
Name Type Description

date/datetime datetime The field, expression, or literal value to extract the year from.

Output
Numeric.

Examples
Basic examples
Returns 2014:

YEAR(`20141231`)

YEAR(`141231 235959`)

Returns the year for each value in the Invoice_date field:

YEAR(Invoice_date)

Page 830 of 934

Commands

Remarks
Parameter details
A field specified for date/datetime can use any date or datetime format, as long as the field definition cor-
rectly defines the format.

Specifying a literal date or datetime value

When specifying a literal date or datetime value for date/datetime, you are restricted to the formats in the
table below, and you must enclose the value in backquotes – for example, `20141231`.
Do not use any separators such as slashes (/) or colons (:) between the individual components of dates or
times.
l Datetime values – you can use any combination of the date, separator, and time formats listed in the
table below. The date must precede the time, and you must use a separator between the two. Valid
separators are a single blank space, the letter 't', or the letter 'T'.
l Time values – you must specify times using the 24-hour clock. Offsets from Coordinated Universal
Time (UTC) must be prefaced by a plus sign (+) or a minus sign (-).

Example formats Example literal values

YYYYMMDD `20141231`

YYMMDD `141231`

YYYYMMDD hhmmss `20141231 235959`

YYMMDDthhmm `141231t2359`

YYYYMMDDThh `20141231T23`

YYYYMMDD hhmmss+/-hhmm `20141231 235959-0500`
(UTC offset)

YYMMDD hhmm+/-hh `141231 2359+01`
(UTC offset)

Note
Do not use hh alone in the main time
format with data that has a UTC offset. For
example, avoid: hh+hhmm. Results can be
unreliable.

Page 831 of 934

Commands

ZONED( ) function
Converts numeric data to character data and adds leading zeros to the output.

Syntax
ZONED(number, length)

Parameters
Name Type Description

number numeric The numeric value to convert to a string.

Note
If you want to add leading zeros to a character value
that contains a numeric string, you must use the VALUE
( ) function to convert the character to the numeric data
type before using the value as input for ZONED( ). For
more information, see "VALUE( ) function" on page 821.

length numeric The length of the output string.

Output
Character.

Examples
Basic examples
Integer input
Returns "235":

ZONED(235, 3)

Returns "00235", because length is greater than the number of digits in number so two leading zeros are
added to the result:

Page 832 of 934

Commands

ZONED(235, 5)

Returns "35", because length is less than the number of digits in number so the leftmost digit is truncated
from the result:

ZONED(235, 2)

Decimal input
Returns "23585", because the zoned data format does not support a decimal point:

ZONED(235.85, 5)

Negative input
Returns "64489M", because the number is negative and "M" represents the final digit 4:

ZONED(-6448.94, 6)

Returns "489J", because length is less than the number of digits in number so the two leftmost digits are trun-
cated from the result, and the number is negative and "J" represents the final digit 1:

ZONED(-6448.91, 4)

Advanced examples
Adding leading zeros to a character field containing numbers
The Employee_Number field contains the value "254879". You need to convert the value to a 10-digit string
with leading zeros.
Tip
You must use the VALUE( ) function to convert the character to numeric data before using
the numeric as input for ZONED( ).

COMMENT returns "0000254879"

ASSIGN v_str_length = 10
ASSIGN v_num_decimals = 0
ZONED(VALUE(Employee_Number, v_num_decimals), v_str_length)

Harmonizing a key field when joining tables

You have two tables, Ar and Customer, and you need to join them on the CustNo field for further analysis.

Page 833 of 934

Commands

The two tables each have a CustNo field, but the data format is different:
l Ar – numeric field (for example, 235)
l Customer – 5 character field that pads numbers with leading zeros (for example, "00235")
To harmonize the fields when joining so that the data types and lengths are equal, you use the ZONED( )
function to convert the Ar key field CustNo to a character field of length 5 so that it matches the format of
the key field in Customer:

OPEN Ar PRIMARY
OPEN Customer SECONDARY
JOIN PKEY ZONED(CustNo,5) FIELDS CustNo Due Amount SKEY CustNo UNMATCHED TO Ar_
Cust OPEN PRESORT SECSORT

Remarks
How it works
This function converts numeric data to character data and adds leading zeros to the output. The function is
commonly used to harmonize fields that require leading zeros, for example, check number, purchase
order number, and invoice number fields.

When to use ZONED( )

Use the function to convert a positive numeric value to a character value containing leading zeros. This is
useful for normalizing data in fields to be used as key fields.
For example, if one table contains invoice numbers in the form 100 in a numeric field, and another table
contains invoice numbers in the form "00100" in a character field, you can use ZONED( ) to convert the
numeric value 100 to the character value "00100". This allows you to compare like invoice numbers.

String length and return values

Leading zeros are added to the output value when the length value is more than the number of digits in
number. When length is less than the number of digits in number, the output is truncated from the left side.
If the number value is the same length as length, then no zeros are added.

Decimal numbers
The zoned data format does not include an explicit decimal point.

Negative numbers
If the input number is negative, the rightmost digit is displayed as a character in the result:

Page 834 of 934

Commands

l "}" for 0
l a letter between "J" and "R" for the digits 1 to 9

ZONED( ) and the Unicode edition of Analytics

If you are working with the Unicode edition of Analytics, you need to use the BINTOSTR( ) function to cor-
rectly display the return value of the ZONED( ) function. You also need to use the BINTOSTR( ) function if
you want to use the return value of the ZONED( ) function as a parameter in another function.

Page 835 of 934

Commands

ZSTAT( ) function
Returns the standard Z-statistic.

Syntax
ZSTAT(actual, expected, population)

Parameters
Name Type Description

actual numeric o When specifying parameters as numbers – represents the actual

count, such as a leading digit or a leading digit combination.
o When specifying parameters as proportions – represents the
expected proportion of the value being tested and must be
between 0 and 1 inclusive (i.e., greater than or equal to 0 and less
than or equal to 1).

expected numeric o When specifying parameters as numbers – represents the expec-

ted count, such as a leading digit or a leading digit combination.
o When specifying parameters as proportions – represents the
expected proportion of the value being tested and must be
between 0 and 1 exclusive (i.e., greater than 0 and less than 1).

population numeric The total number of items being tested. This parameter must be a pos-
itive whole number greater than 0.

Output
Numeric.

Examples
Advanced examples
Parameters expressed as numbers
Based on 10 years of previous data, you know that the distribution of worker disability claims per month is

Page 836 of 934

Commands

normally highly uniform. In April, May, and June of this year, claims were higher by about 10 percent, aver-
aging 220 per month instead of 200. Claims in July and August were slightly low, at 193 and 197. The total
claims for the year were 2,450. To test whether these high and low results were significant, use the Z-stat-
istic.
The actual number of claims for April to June is higher than expected at 660. The expected number of
claims for this period is 25 percent of the 2,450 annual claims, or 612.5. The Z-statistic for these counts is cal-
culated as 2.193:

ZSTAT(660, 612.5, 2450)

A Z-statistic of 1.96 has a significance of 0.05, and 2.57 has a significance of 0.01. Thus, the probability that
the higher rates of claims are due to chance is between 1:20 and 1:100.
The actual number of claims for July and August is lower than expected at 390. The expected number of
claims for this period is one sixth of the 2,450 annual claims, or 408.33. The Z-statistic for these proportions
is calculated as 0.967:

ZSTAT(390, 408.33, 2450)

This is not a very significant result. Z-statistics of 1.000 and less are very common and can typically be
ignored.

Parameters expressed as proportions

Based on 10 years of previous data, you know that the distribution of worker disability claims per month is
normally highly uniform. In April, May, and June of this year, claims were higher by about 10 percent, aver-
aging 220 per month instead of 200. Claims in July and August were slightly low, at 193 and 197. The total
claims for the year were 2,450. To test whether these high and low results were significant, use the Z-stat-
istic.
The actual number of claims for April to June is represented by the proportion 660/2450, which is higher
than expected. The expected number of claims for this period should be 25 percent of the 2,450 annual
claims. The Z-statistic for these proportions is 2.193:

ZSTAT((1.00000000 * 660 / 2450), 0.25, 2450)

A Z-statistic of 1.96 has a significance of 0.05, and 2.57 has a significance of 0.01. Thus, the probability that
the higher rates of claims are due to chance is between 1:20 and 1:100.
The actual number of claims for July and August is low at 390. The expected number of claims for this period
should be one sixth, or 16.6667 percent of the 2,450 annual claims. The Z-statistic for these proportions is
0.967:

ZSTAT((1.00000000 * 390 / 2450), 0.16667, 2450)

Page 837 of 934

Commands

This is not a very significant result. Z-statistics of 1.000 and less are very common and can typically be
ignored.

Remarks
How it works
The ZSTAT( ) function calculates the standard Z-statistic for use in many problem-solving tasks, including
digital analysis. It outputs the result with a precision of three decimal places.

Using ZSTAT( )
Use ZSTAT( ) to evaluate the likely frequency of occurrence of a given result in a specified period or cat-
egory. The larger the resulting Z-statistic, the more unlikely the occurrence.
For example, a Z-statistic of 1.96 has a significance of 0.05, representing the likelihood of a one time in 20
occurrence, whereas a Z-statistic of 2.57 has a significance of 0.01, representing the likelihood of a one
time in 100 occurrence. For information on the Z-statistic, consult a statistics textbook.

Specifying input for ZSTAT( )

You can specify the parameters for ZSTAT( ) as either numbers or proportions:
l When you specify both input values as numbers, the function computes the Z-statistic using float-
ing-point arithmetic
l When you specify both input values as proportions, the function computes the Z-statistic using
fixed-point arithmetic, and you need to use a decimal multiplier to control rounding
l When using an expression within an expression to calculate the actual or expected value, you must
specify the level of precision you want in the result by using a decimal multiplier. Analytics has a pre-
cision of 8 digits, therefore a multiplier of 1.00000000 will return the greatest precision attainable

Page 838 of 934

Commands

Analytics

Page 839 of 934

Commands

Analytic scripts
Scripts are not limited to running in Analytics only. By converting regular scripts to analytic scripts , you
can schedule and run scripts in the Robots module of HighBond, or in Analytics Exchange. You can also
run analytic scripts in the Analysis App window, a freestanding component of Analytics.

What are analytic scripts?

An analytic script, or "an analytic", is a regular script with an analytic header. The analytic header is a
series of declarative tags that allow the script to run in Robots, on AX Server, or in the Analysis App win-
dow. The analytic header includes input parameters that a user populates in advance, which allows the
analytic script to run unattended, either immediately, or at a scheduled time.
Tip
Analytic scripts are almost exclusively developed and tested in Analytics, which supports
easier development. Use AX Client to make simple updates to existing analytic scripts that
are stored on AX Server.

What are analysis apps?

An analysis app is an Analytics project that is packaged for use in Analytics Exchange or the Analysis App
window. Analysis apps contain one or more analytic scripts, and can also contain data tables and inter-
pretations.
Note
Analysis apps are typically created or developed by an organization's in-house scripting
experts, or by arrangement with Galvanize consultants.

Turning regular scripts into analytic scripts

Analytic scripts begin as regular scripts. To run a regular script in Robots, on AX Server, or in the Analysis
App window, you must convert the regular script into an analytic script:
1. Create and test a script in Analytics.
2. Add the appropriate analytic header tags to make the script an analytic script.
3. Package the analytic script to run on AX Server or in the Analysis App window. You do not package
analytic scripts run in Robots.

Adding analytic headers

Analytic headers are defined in a comment block on the first line of the script. At a minimum, an analytic
header declares the script is an analytic script:

Page 840 of 934

Commands

COMMENT
//ANALYTIC Identify missing checks
This analytic script identifies missing check numbers
END

For more information, see "Adding analytic headers" on page 882.

Distributing and running analytic scripts

There are several options for distributing and running analytic scripts, depending on which
Galvanize products and components your organization uses.

Product/component Method for distributing and running an analytic script

Robots module of o commit one or more analytic scripts as a version to development mode in Robots, and
HighBond schedule and run an activated version in production mode

AX Server Either of these methods:

o import the Analytics project (.acl file) directly into AX Server, and schedule and run
an analytic script using AX Client
o package the project into a compressed analysis app file (.aclapp file), import it into
AX Server, and run an analytic script using AX Web Client
For more information, see "Packaging analysis apps" on page 891.

Analysis App window o package the project into a compressed analysis app file (.aclapp file), open the pro-
ject as an analysis app (.aclx file), and run the analytic script in the Analysis App win-
dow
For more information, see "Packaging analysis apps" on page 891.

Determining the environment where an analytic script is run-

ning
If you want to create an analytic script that can run in Analytics, Analytics Exchange, or the Analysis App win-
dow, you can determine the runtime environment during script execution. You can use this information to
make decisions about which commands to run based on where the script is running.
Use the FTYPE( ) function to determine where the script is running:

FTYPE("ax_main") = "b"

If the script is running in either Analytics Exchange or the Analysis App window, the expression evaluates to
true (T). For scripts running in Analytics, the expression evaluates to false (F). For more information, see
"FTYPE( ) function" on page 572.

Page 841 of 934

Commands

Identifying the user running the script on AX Server

For analytic scripts run on AX Server, you can use the system variable AXRunByUser to identify the name
of the user who is currently running the script, in the format domain\username:

EXTRACT FIELDS TIME() AS "Time", DATE() AS "Date", AXRunByUser AS "Current User" TO R_

RunRecord APPEND

Note
AXRunByUser is only available when running analytic scripts on AX Server. The variable
is unrecognized when running scripts in Analytics.

Page 842 of 934

Commands

Analytic headers and tags

An analytic header is a series of tags enclosed in a comment block at the start of an Analytics script. The ana-
lytic tags specify input parameters that a user populates in advance of scheduling or running an analytic,
and output parameters.
An analytic header is required for any analytic script that you intend to run in Robots, on AX Server, or in the
Analysis App window.

Defining analytic headers

Analytic headers must be defined in a comment block that starts on the first line of the script. Tags can be in
any order in the analytic header, except for:
l the ANALYTIC tag, which must be first
l FIELD tags, which must immediately follow their associated TABLE tag

Example
This analytic header identifies a table and field to use in the script, as well as a start date parameter:

Tag format
Each tag in the header uses the following format:

//tagName attributes descriptiveText

The // tag indicator must be the first non-whitespace character on the script line. The tag must immediately
follow the tag indicator, without any space or characters in between.

Page 843 of 934

Commands

Tag conventions
Component Convention

Tag names Tag names are not case-sensitive.

Unlike Analytics command and function names, tag names cannot be abbreviated.

Tag attributes When specifying attribute values for a tag, you may include spaces and optionally enclose the
value in quotation marks.

Tag descriptions Descriptions are optional. If a description is specified it can be multi-line, but line breaks are
not preserved in client applications.

Specifying test input values in Analytics

You can use a special assignment operator ( := ) to specify test input values for any analytic tag that
requires definition:
l FILE
l TABLE
l FIELD
l PARAM
Use this syntax to test analytic scripts in Analytics:

//TABLE v_AnalysisTable "Table to classify" := "Trans_May"

When the script runs in Analytics, the parameter takes the value specified in the assignment. When the
analytic runs in a client application, the test value is ignored and the user-defined input parameters are
used.
You must leave a space between the assignment operator and the tag syntax preceding it. Assignment val-
ues must use the correct qualifier for the data type as required throughout Analytics. For more information,
see "Data types" on page 21.

Full list of available analytic tags

Tag Description

"ANALYTIC" on Designates an Analytics script as an analytic that can run in Robots, on AX Server, or in the
page 846 Analysis App window.

Input tags

Page 844 of 934

Commands

Tag Description

"FILE" on page 848 Specifies a non-Analytics file, such as an Excel file, or a delimited file, that provides input for
an analytic running in Robots, or on AX Server.
o Robots – the file must be located in the Input/Output tab in the same robot as the analytic
o AX Server – the file must be located in the Related Files subfolder in the folder where the
analytic is located

"TABLE" on Defines an Analytics table that the user selects as input for an analytic.
page 850
The TABLE tag can be followed by zero or more FIELD tags entered on sequential lines.

"FIELD" on Defines a field that the user selects as input for the analytic.
page 852
The field must be part of the table defined in the preceding TABLE tag. The first FIELD tag
must immediately follow a TABLE tag, and can be followed by additional FIELD tags entered
on sequential lines.

"PARAM" on Creates an input parameter for an analytic, and defines the requirements for the input value.
page 854
An input parameter is a placeholder that allows the user to specify the actual value when
scheduling or running an analytic.

"PASSWORD" on Creates a password input parameter for an analytic. The parameter provides encrypted stor-
page 866 age of a password for subsequent use in an ACLScript command.
The user is prompted to specify the required password value when they schedule or start an
analytic so that user intervention is not required as the analytic is running.

Output tags

"DATA" on page 869 Specifies that an Analytics table output by an analytic is copied to a data subfolder (a storage
location) in the deployment environment.
Typically, you store Analytics tables so that they can be used as input tables for subsequent
analytics.

"RESULT" on Specifies the analytic output results that you want to make available to end users in client
page 873 applications.
Output results, even if they exist, are not automatically made available. You must use a sep-
arate RESULT tag for each result item that you want to make available.

"PUBLISH" on Specifies a file that contains metadata defining which Analytics tables to publish to AX Excep-
page 877 tion when an analytic is finished processing.

Page 845 of 934

Commands

ANALYTIC
Designates an Analytics script as an analytic that can run in Robots, on AX Server, or in the Analysis App
window.

Syntax
//ANALYTIC <TYPE IMPORT|PREPARE|ANALYSIS> name
< description>

Parameters
Name Description

TYPE Identifies the kind of analytic script as one of the following three types:
optional o IMPORT – retrieves data from a data source. The output of an import analytic is a raw
data table.
o PREPARE – transforms raw data in whatever way is necessary to make it suitable for
analysis. The output of a preparation analytic is an analysis table.
o ANALYSIS – performs tests on data in analysis tables. The output of an analysis ana-
lytic is one or more results tables.
Analytics with a specified TYPE are organized in the corresponding Import,
Preparation, or Analysis areas in Robots, AX Web Client, and the Analysis App window.
This placement guides the user in the appropriate sequence for running the analytics.
The sequence is not enforced, nor is the type of functionality within the analytic.
If you omit TYPE, the analytic appears in the Analysis section.

name The name of the analytic.

The name identifies the analytic in client applications. The analytic name is separate
from the script name that you specify in Analytics when you initially create the script.
Note
Analytics in the same project or analysis app must be uniquely named. If
the same name is used in two or more analytics, an error occurs when
you try to commit the analytic scripts, or import or open the analysis app.
Characters that cannot be used in Windows filenames (< > : " / \ | ? *) should not be
used in analytic names, because they will cause an error that prevents the export of ana-
lytic results. Do not use the value TYPE as the name.
In client applications, names are listed in alphanumeric order. To guide users in the cor-
rect sequence for running multiple analytics in a single robot or analysis app, you can
add a prefix to order the analytic names within each area. For example: 01_analyze_
POs, 02_analyze_invoices, and so on. The sequence implied by the order of the names
is not enforced.

Page 846 of 934

Commands

Name Description

description A description of the analytic or other information that the user might need to run the ana-
lytic successfully.
optional
The description appears with the analytic in client applications. The description can be
multiline, but it cannot skip lines. The description must be entered on the line below the
associated ANALYTIC tag.

Examples
Basic analytic header
The following analytic header contains a name and a description of the analytic:

COMMENT
//ANALYTIC Identify missing checks
This analytic identifies missing check numbers.
END

Analytic header with type

The following analytic header specifies a preparation analytic with a description of what the script does:

COMMENT
//ANALYTIC TYPE PREPARE Standardize address data
This analytic cleans and standardizes the address field in preparation for duplicates analysis.
END

Remarks
An ACLScript COMMENT command must be entered on the first line in the script, followed by the
ANALYTIC tag on the second line. If the ANALYTIC tag is used in any other location it is ignored.
One or more scripts in an Analytics project can include an ANALYTIC tag.

Page 847 of 934

Commands

FILE
Specifies a non-Analytics file, such as an Excel file, or a delimited file, that provides input for an analytic
running in Robots, or on AX Server.
l Robots – the file must be located in the Input/Output tab in the same robot as the analytic
l AX Server – the file must be located in the Related Files subfolder in the folder where the analytic is
located
Note
To specify a non-Analytics input file for an analytic run in the Analysis App window, see
"PARAM" on page 854.

Syntax
//FILE filename

Parameters
Name Description

filename The name of the item in the robot, or in the Related Files subfolder, to use as an input
file for an analytic. filename cannot include a path.
Wildcards are supported when specifying the file name. Use a single asterisk ( * ) to sub-
stitute for zero or more characters.
For example:
o Inv12* matches all of the following: Inv12, Inv123, and Inv1234
o *.* matches all files of all extensions in the robot or the Related Files folder
o Inv_*.* matches Inv_Jan.pdf and Inv_Feb.xls
Tip
You can use the //FILE tag to reference a .prf Analytics preferences file.
When you do this, the preferences file in the Related Files subfolder is
used to set the runtime environment settings rather than the global pref-
erences file on AX Server. The preferences file must be from the latest
version of Analytics that is compatible with your Analytics Exchange
installation.

Page 848 of 934

Commands

Examples
Basic examples
Specifies a specific file:

//FILE FlaggedAccounts.csv

Specifies all CSV files starting with "Flagged":

//FILE Flagged*.csv

Specifies all files:

//FILE *.*

Advanced examples
Import data from an included file
You run a monthly analysis of employee data on AX Server. One of the analytics in the analysis app imports
the data to analyze from a delimited file that is placed in the Related Files folder on monthly basis:

COMMENT
//ANALYTIC TYPE IMPORT employee_import
Imports employee records from delimited file stored in Related Files folder.
//FILE Employees.csv
END
IMPORT DELIMITED TO Employees "Employees.fil" FROM "Employees.csv" 0 SEPARATOR ","
QUALIFIER '"' CONSECUTIVE STARTLINE 1 KEEPTITLE FIELD "First_Name" C AT 1 DEC 0 WID
11 PIC "" AS "First Name" FIELD "Last_Name" C AT 12 DEC 0 WID 12 PIC "" AS "Last Name"

Remarks
The FILE tag is not supported for use in analytics run in the Analysis App window. To specify an input file for
analytics run in the Analysis App window, use the PARAM tag. For more information, see "PARAM" on
page 854.

Page 849 of 934

Commands

TABLE
Defines an Analytics table that the user selects as input for an analytic.
The TABLE tag can be followed by zero or more FIELD tags entered on sequential lines.
Note
The TABLE tag requires that a table pre-exists in the storage location in order to be avail-
able to be selected. For more information, see "DATA" on page 869.

Syntax
//TABLE id name
<description>

Parameters
Name Description

id The variable that stores the input table name selected by the user. Use this value in the
analytic script to reference the table.

name The name to associate with the table.

The value is displayed in client applications when the user who runs the analytic is
prompted to select the table.

description Descriptive text that specifies the purpose of the table. The description can be multiline,
but it cannot skip lines.
optional
The value is displayed in client applications when the user is prompted to select the
table. The description can prompt the user to select the correct table. For example,
"Select the table that includes payroll information".
The description must be entered on the line below the associated TABLE tag.

Examples
Basic examples
TABLE tag with description to help user select the correct input table:

Page 850 of 934

Commands

//TABLE v_table_payments Payments Table

Select a table that lists payments and includes a check number column.

Advanced examples
Using a table defined in a TABLE tag in the script
The following script runs an AGE command on a table that is selected by the user from the data tables in the
project:

COMMENT
//ANALYTIC example_script
//TABLE v_table_payments Payments Table
Select a table that lists payments and includes a check number column.
END

OPEN %v_table_payments%
AGE ON payment_date CUTOFF 20141231 INTERVAL 0,30,60,90,120,10000 SUBTOTAL Pay-
ment_Amount TO r_output
CLOSE %v_table_payments%

Page 851 of 934

Commands

FIELD
Defines a field that the user selects as input for the analytic.
The field must be part of the table defined in the preceding TABLE tag. The first FIELD tag must imme-
diately follow a TABLE tag, and can be followed by additional FIELD tags entered on sequential lines.
Note
The TABLE tag requires that a table pre-exists in the storage location in order to be avail-
able to be selected. For more information, see "DATA" on page 869.

Syntax
//FIELD id type name
<description>

Parameters
Name Description

id The variable that stores the input field name selected by the user. Use this value in the
analytic script to reference the field.

type The types of fields that can be selected. Any type, or combination of types, from the fol-
lowing list can be selected:
o C – character data
o N – numeric data
o D – date, datetime, or time subtype of datetime data
o L – logical data
Any computed fields in a table can be selected regardless of the type specified.

name The name to associate with the field.

The value is displayed in client applications when the user is prompted to select the
field.

description Descriptive text that specifies the purpose of the field. The description can be multiline,
but it cannot skip lines.
optional
The value is displayed in client applications when the user is prompted to select the
field. The description can prompt the user to select the correct field. For example,
"Select the field that includes payment amount".
The description must be entered on the line below the associated FIELD tag.

Page 852 of 934

Commands

Examples
Basic examples
Specifies a character field:

//FIELD v_name C Name Field

Specifies a character or numeric field:

//FIELD v_inv_num CN Invoice Number

Advanced Examples
TABLE with two accompanying FIELD tags
The following analytic header allows the user to specify two input fields from the v_table_payments table
when the script runs:

COMMENT
//ANALYTIC test analytic
//TABLE v_table_payments Payments Table
Select a table that lists payments and includes a check number column.
//FIELD v_check_num CN Check Number Field
//FIELD v_payment_date D Payment Date Field
Select the column that contains the check payment date.
END

OPEN %v_table_payments%
EXTRACT FIELDS %v_check_num%, %v_payment_date% TO t_analyze

Page 853 of 934

Commands

PARAM
Creates an input parameter for an analytic, and defines the requirements for the input value.
An input parameter is a placeholder that allows the user to specify the actual value when scheduling or run-
ning an analytic.

Syntax
//PARAM id type <OPTIONAL> <MULTI> <SEPARATOR value> <QUALIFIER value>
<VALUES value_list> label
<description>

Parameters
Name Description

id The variable that stores the analytic input value(s) selected or specified by the user.
For example:
o v_start_date
o v_regions
o v_input_file
Also serves as the unique identifier for the parameter.
Note
When an analytic is run, the variable is created only if the user provides
an input value. If a parameter is optional, and the user skips it, the vari-
able is not created.
If subsequent logic in the analytic requires the variable to exist, you can
test for its existence, and if it does not exist, create it and initialize it. For
more information, see "Designing optional input parameters" on
page 860.

type The data type of the parameter, which controls what sort of input values can be entered.
The following types can be specified using uppercase letters:
o C – character data
o N – numeric data
o D – date subtype of datetime data
o DT – datetime subtype of datetime data
o T – time subtype of datetime data
o L – logical data

Page 854 of 934

Commands

Name Description

Note
Qualifying character input values is required for an analytic to run suc-
cessfully.
How PARAM... F works
You can also specify that a file upload utility, or a Windows file browser, opens:
o F – opens a file upload utility, or a Windows file browser, and allows a user to select a
non-Analytics input file for the analytic when running in AX Web Client or the Ana-
lysis App window
Upon selection, the file name is automatically entered as a Character input value.
Specify F only. Do not specify F C.
For example:

//PARAM v_input_file F...

For more information, see "Specifying or selecting a non-Analytics input file for an ana-
lytic" on page 864.
Note
A type of F is not supported for use in analytics run in Robots or AX Cli-
ent. To specify an input file for these environments, use the FILE tag. For
more information, see "FILE" on page 848.

OPTIONAL Specifies that the parameter is optional and the user does not need to enter a value.
optional For more information, see "Designing optional input parameters" on page 860.

MULTI Specifies that the parameter accepts multiple input values.

optional MULTI can be used with or without the VALUES option:

MULTI The user can select one or more values from a list of values.

VALUES

MULTI The user can manually enter one or more values.

VALUES

For more information, see "Summary of the MULTI and VALUES options" on page 861.
MULTI cannot be used if type is L (Logical).
Multiple character input values
If you specify MULTI , and type is C (Character), you can also specify the SEPARATOR
and QUALIFIER options to automatically insert separators (delimiters) and text qualifiers
in a string of input values.
Note
Delimiting and qualifying multiple character input values is required for
an analytic to run successfully. The separators and qualifiers can be
inserted automatically, or manually by the user.

Page 855 of 934

Commands

Name Description

SEPARATOR value SEPARATOR can be used only when MULTI is specified, and type is C (Character).
optional Specifies that a separator character is automatically inserted between multiple char-
acter input values, creating a delimited list that is passed to the analytic for processing.
value specifies the separator character to use. A commonly used separator, or delimiter,
is the comma , .
If SEPARATOR is omitted, a single space is used as the separator by default. The space
character cannot be specified as value.
For more information, see "Delimiting and qualifying character input values" on
page 862.

QUALIFIER value QUALIFIER can be used only when MULTI is specified, and type is C (Character).
optional Specifies that a text qualifier character is automatically inserted at the start and end of
each character input value in a delimited list that is passed to the analytic for pro-
cessing. Any text enclosed within the qualifier characters is treated as plain text.
value specifies the qualifier character to use. A commonly used qualifier is the single
quotation mark ' .
If QUALIFIER is omitted, there is no default qualifier used. You cannot specify a space
character as value.
For more information, see "Delimiting and qualifying character input values" on
page 862.
Note
Analytic input parameters currently do not support the use of the double
quotation mark (") as a text qualifier. You can use the single quotation
mark (') instead. Specifying a double quotation mark qualifier will cause
the PARAM tag to malfunction.

VALUES value_list A list of values that the user can select from when running the analytic.
optional Use the following syntax to specify the values:

VALUES |Value 1|Value 2|Value 3|Value n|

VALUES can be used with or without the MULTI option:

VALUES The user can select one or more values from the list of values.

MULTI

VALUES The user can select a single value from the list of values.

MULTI

For more information, see "Summary of the MULTI and VALUES options" on page 861.
Format of values in value_list

Character val- o can contain spaces and punctuation

Page 856 of 934

Commands

Name Description

ues

o can be positive or negative

o must be specified using decimal notation, and without a thousands sep-
arator
Numeric val-
ues For example, 1500.00 or -1500.00

o Date – must be specified using the format MM/DD/YYYY

For example, 12/31/2014
o Datetime – must be specified using the format MM/DD/YYYY hh:mm:ss
For example, 12/31/2014 23:59:59
o Time – must be specified using the format hh:mm:ss
Datetime val-
ues For example, 23:59:59

Logical val- VALUES cannot be used if type is L (Logical)

ues

label The user interface label for the parameter.

In client applications, label is displayed with the input field.

description Descriptive text that provides additional information about the parameter.
optional In client applications, description is displayed with the input field.
description can provide instructions that assist the user. For example, "Enter the cutoff
date for the payroll period".
description must be entered on the next line after the associated PARAM tag. The text
can be multiline, but it cannot skip lines. Line breaks are not preserved when displayed
in client applications.

Examples
Basic examples
Allows the user to optionally specify a date range:

//PARAM v_start_date D OPTIONAL Start Date (Optional)

Enter the start date for the analysis
//PARAM v_end_date D OPTIONAL End Date (Optional)
Enter the end date for the analysis

Requires the user to select a maximum number of transactions to process:

Page 857 of 934

Commands

//PARAM v_maxTrans N VALUES |250|500|750|1000| Maximum transactions to process

Requires the user to specify one or more merchant category codes:

//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' MC Codes to include

Specify one or more merchant category codes. Press "Enter" after each code, so that each code is on
a separate line. Do not enclose codes in quotation marks.

Requires the user to select one or more merchant category codes:

//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' VALUES |4121 Taxis/Limousines|5812

Restaurants|5813 Drinking Places - Alcoholic Beverages|5814 Fast food restaurants| MC Codes to
include
Select one or more merchant category codes.

Advanced examples
Require a user to specify an amount range
You need to classify the records in a table that fall between a minimum and maximum amount range. This
range changes occasionally, so you provide input parameters that allow the user who runs the analytic to
define the range when scheduling or running the script:

COMMENT
//ANALYTIC test_analytic
//PARAM v_min_amount N Minimum Amount
Enter a minimum amount
//PARAM v_max_amount N Maximum Amount
Enter a maximum amount
END

CLASSIFY ON %v_FieldA% IF BETWEEN(AMOUNT, v_min_amount, v_max_amount) SUBTOTAL

AMOUNT TO "Classified_%v_AnalysisTable%.FIL"

Allow the user to optionally exclude one or more customer numbers

You need to classify the records in a table but you want to give the user the option to exclude some cus-
tomers from the analysis.
To do this, you provide an optional character parameter. Your script tests whether or not the value is
provided, and if so, those customer numbers are excluded from the classify command:

Page 858 of 934

Commands

COMMENT
//ANALYTIC test_analytic
//PARAM v_cust_no C OPTIONAL MULTI SEPARATOR , QUALIFIER ' Customer Number(s) to
exclude (optional)
Specify one or more customer numbers. Press "Enter" after each number, so that each number is on a
separate line. Do not enclose numbers in quotation marks.
END

IF FTYPE("v_cust_no") = "U" v_cust_no = ""

GROUP IF v_cust_no = ""
CLASSIFY ON %v_FieldA% SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL"
ELSE
CLASSIFY ON %v_FieldA% IF NOT MATCH(CUSTNO, %v_cust_no%) SUBTOTAL AMOUNT TO
"Classified_%v_AnalysisTable%.FIL"
END

Allow the user to select an input file (AX Web Client or the Analysis App win-
dow only)
You are distributing an analysis app to colleagues who will run it in the Analysis App window. When they run
the analytic script in the app, you want to provide them with a Windows file browser to select a Microsoft
Excel file to import data from:

COMMENT
//ANALYTIC test_analytic
//PARAM v_input_file F Input File
Select an input file
END

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "%v_input_file%" TABLE "Trans2_

May$" CHARMAX 100 KEEPTITLE

Require the user to specify an input file path and file name (the Analysis App
window only)
You are distributing an analysis app to colleagues who will run it in the Analysis App window. When they run
the analytic script in the app, you want them to specify a filepath and filename to use as an import file:

COMMENT
//ANALYTIC test_analytic
//PARAM v_input_file C Input File Path and Name
Enter an absolute file path and a file name, for example: C:\Users\username\Documents\ACL
Data\Sample Data Files\ Trans_May.xls

Page 859 of 934

Commands

END

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "%v_input_file%" TABLE "Trans2_

May$" CHARMAX 100 KEEPTITLE

Using default values for optional parameters

You are creating an analytic that extracts transaction records to a results table. You want to give the user
who runs the script the option of providing a date range as well as a list of entities for filtering the records to
extract.
To do this, you create three optional parameters:
l v_start_date
l v_end_date
l v_entity_list
In the opening lines of the script, you test if these values are set. If they are not set, you set default values
of the minimum and maximum dates as well as a default flag to test for with v_entity_list.
In your EXTRACT command, you use the values to filter the records:

COMMENT
//ANALYTIC test
This analytic tests the PARAM
//RESULT TABLE t_results
//PARAM v_start_date D OPTIONAL Enter Start Date
//PARAM v_end_date D OPTIONAL Enter End Date
//PARAM v_entity_list C MULTI OPTIONAL |entity1|entity2|
END

IF NOT ISDEFINED("v_start_date") v_start_date = `19000101`

IF NOT ISDEFINED("v_end_date") v_end_date = `99991231`
IF NOT ISDEFINED("v_entity_list") v_entity_list = "'all'"

EXTRACT FIELDS ALL TO t_results IF BETWEEN(transaction_date v_start_date v_end_date)

AND (MATCH(entity_field %v_entity_list%) OR v_entity_list = "'all'")

Remarks
Designing optional input parameters
If you use OPTIONAL with the PARAM tag, the variable associated with the analytic input parameter may
or may not be created when the analytic runs:
l variable automatically created – if the user specifies an input value
l variable not created – if the user skips the optional parameter and does not specify an input value

Page 860 of 934

Commands

Test for the existence of the parameter variable

If subsequent logic in the analytic depends on being able to evaluate the contents of the parameter variable,
including evaluating an empty or null state, you need to test for the existence of the parameter variable. If
the parameter variable does not exist, you need to create it and initialize it to null.
Use the IF command with the FTYPE( ) function, or the ISDEFINED( ) function, to perform the test and cre-
ate the variable if it does not exist:

IF FTYPE("var_name") = "U" var_name = ""

IF NOT ISDEFINED("var_name") var_name = ""

When to perform the test

Perform the test after the analytic header and before any Analyticsscript logic that depends on the existence
of the parameter variable.

Summary of the MULTI and VALUES options

The table below summarizes the effect of the MULTI and VALUES options on the user input control in the
user interface.

User input control (Robots) Parameter design MULTI VALUES

A single input value

manually entered
in a field

One or more input

values manually
entered in a field

A single input value

selected from a
drop-down list of
values

Page 861 of 934

Commands

User input control (Robots) Parameter design MULTI VALUES

One or more input

values selected
from a checklist of
values

Delimiting and qualifying character input values

For an analytic to run successfully, character input values must be delimited by a separator if there is more
than one value, and values must be qualified.

Avoid nested text qualifiers

When you create character input parameters, and when you instruct users of the analytic how to enter
character input values, you need to be careful to avoid creating redundant or nested text qualifiers (qual-
ifiers within qualifiers). Redundant text qualifiers will cause the input parameter to malfunction.

Methods for inserting text qualifiers

There are four different methods available for inserting text qualifiers around character input values.
Depending on the method, a separator is also inserted between the input values.
As you develop an analytic, you may need to experiment with different methods to find what works best for
the character values that users will input.
Note
One or more of the methods may not be applicable, depending on how you are using the
MULTI and VALUES options.
Each input parameter must use only one of these methods.

Use SEPARATOR and Include the SEPARATOR and QUALIFIER options in the PARAM tag.
QUALIFIER
For example:

//PARAM v_regions C MULTI SEPARATOR , QUALIFIER '

Not applicable if you use VALUES without MULTI.

Tip
Use this method whenever possible. It is the least labor-intensive
1 and the least error-prone.

Page 862 of 934

Commands

Manually specify sep- Require the user of the analytic to manually specify separators and qualifiers in
arators and qualifiers addition to the actual input values.
For example:

'North America','Europe','Asia'

2 Not applicable if you use VALUES with or without MULTI.

Include qualifiers in the Include qualifiers with each value in the value_list specified with the VALUES
value_list option.
For example:

VALUES |'Asia'|'Europe'|'Middle East'|'North America'|

3 Not applicable if you use MULTI without VALUES.

Enclose the parameter vari- In the syntax of the Analytics script, enclose the parameter variable in text qual-
able in qualifiers ifiers.
For example:

IF MATCH(REGIONS, "%v_regions%")

4 Use this method only if you are using VALUES without MULTI.

Note
Analytic input parameters currently do not support the use of the double quotation mark (") as a
text qualifier. You can use the single quotation mark (') instead with the QUALIFIER option, in
the value_list, or when manually specifying qualifiers around input values. Double quotation
marks can be used as text qualifiers in the body of an Analytics script.

When to use the different methods

The table below summarizes when to use the different methods for inserting text qualifiers.

MULTI MULTI MULTI

VALUES VALUES VALUES

Method 1 If used, do not use Not applicable If used, do not use

Method 2 Method 3
Use the SEPARATOR and QUALIFIER
options

Method 2 If used, do not use Not applicable Not applicable

Method 1
Manually specify separators and qual-
ifiers

Method 3 Not applicable If used, do not use If used, do not use

Method 4 Method 1
Include qualifiers in the value_list

Page 863 of 934

Commands

MULTI MULTI MULTI

VALUES VALUES VALUES

Method 4 Do not use If used, do not use Do not use

Method 3
Enclose the parameter variable in qual-
ifiers

Specifying or selecting a non-Analytics input file for an ana-

lytic
The table below summarizes the different methods for specifying or selecting a non-Analytics input file for
an analytic. The method you choose is partly dependent on which client application will be used to run the
analytic.

The
Analysis
AX Cli- AX Web App win-
Method Details Robots ent Client dow

PARAM tag o AX Web Client – user selects the input file using a
with type of file upload utility
'F'
The file name is automatically specified as the ana-
lytic input value. The file is automatically uploaded
to the appropriate Related Files subfolder on AX
Server.
o Analysis App window – user selects the input file
using the Windows file browser
The file path and the file name are automatically
specified as the analytic input value.
This method is the best option because it combines
flexibility, ease of use, and precision.

PARAM tag The user manually specifies an input file path and file
with type of name as an analytic input value.
'C'
This method provides flexibility because the file path
and the file name are not specified in advance.
However, it is laborious and error prone because it
requires the user to manually enter these values.

FILE tag o Robots – the input file must be located in the

Input/Output tab in the robot
(For more o AX Client, AX Web Client – the input file must be
information,
located in the appropriate Related Files subfolder
see "FILE"
on AX Server
on
page 848)

Page 864 of 934

Commands

The
Analysis
AX Cli- AX Web App win-
Method Details Robots ent Client dow

Input file This method avoids use of the PARAM tag, however it
path and is the least flexible. On every computer where the ana-
file name lytic is run, the user must ensure that the input file has
hard-coded a file path and a file name identical to those specified
in the ana- in the analytic.
lytic

Page 865 of 934

Commands

PASSWORD
Creates a password input parameter for an analytic. The parameter provides encrypted storage of a pass-
word for subsequent use in an ACLScript command.
The user is prompted to specify the required password value when they schedule or start an analytic so
that user intervention is not required as the analytic is running.

Syntax
//PASSWORD index name
< description>

Parameters
Name Description

index The numerical identifier associated with the password. The value must be from 1 to 10.

name The label for the password prompt. name is displayed in the client application when the
application prompts the user to enter a password.

description Descriptive text about the required password or other information.

optional The description can be multiline, but it cannot skip lines. The description must be
entered on the line below the associated PASSWORD tag.

Examples
Create a password input parameter for a Direct Link SAP query
The analytic header specifies a password input parameter that prompts the user to enter an
SAP password. The stored password is used in the subsequent RETRIEVE command in the body of the
script.

COMMENT
//ANALYTIC SAP Password Example
//PASSWORD 1 SAP Password:
//DATA RSADMIN
END

Page 866 of 934

Commands

SET SAFETY OFF

RETRIEVE RSADMIN PASSWORD 1
OPEN RSADMIN
SET SAFETY ON

Note
The password input parameter and the password parameter in the RETRIEVE command
are linked by using the same numerical identifier:

//PASSWORD 1 SAP Password:

.
.
.
RETRIEVE RSADMIN PASSWORD 1

Create a password input parameter for an export to Results

The analytic header specifies a password input parameter that prompts the user to enter an HighBond pass-
word. The stored password is used in the subsequent EXPORT command in the body of the script.

COMMENT
//ANALYTIC HighBond Password Example
//PASSWORD 3 HighBond Password:
END
SET SAFETY OFF
OPEN AR_Exceptions
EXPORT FIELDS No Due Date Ref Amount Type ACLGRC PASSWORD 3 TO "10926@us"
SET SAFETY ON

Remarks
Password storage and encryption
Password values are associated with individual users, and are encrypted at rest. Passwords remain secure
throughout analytic processing, and are encrypted in any temporary files created in the deployment envir-
onment.

Testing in Analytics
If you test an analytic that has one or more PASSWORD tags in Analytics, Analytics automatically gen-
erates a PASSWORD command and prompts you to enter the appropriate password. This auto-generated

Page 867 of 934

Commands

command saves you the labor of inserting PASSWORD commands in the script portion of an analytic for
the purposes of testing, and then removing them again before delivering the analytic to users.
The auto-generated PASSWORD command is saved in the log, without the password value.
Password values are not saved when you run an analytic in Analytics, so you must specify the password or
passwords each time you run the analytic, including running or stepping through the analytic from the
cursor position.

Page 868 of 934

Commands

DATA
Specifies that an Analytics table output by an analytic is copied to a data subfolder (a storage location) in the
deployment environment.
Typically, you store Analytics tables so that they can be used as input tables for subsequent analytics.
Note
ACL Robotics with a cloud-based Robots Agent does not include a storage location for Ana-
lytics tables. The //DATA tag is ignored in analytics run with a cloud-based agent.

Syntax
//DATA name

Parameters
Name Description

name The name of the Analytics table to be stored. The value of name cannot contain any
spaces.
Note
The value of name must exactly match the name of the Analytics output
table in the analytic script. You are not naming a table with name, you are
matching a name specified in the script.
You must specify the table name, not the source data file name.
Correct:

//DATA Missing_Checks

Incorrect:

//DATA Missing_Checks.fil

Note
Any existing Analytics table with the same name as the value you specify
is overwritten.

Wildcard characters
You can use wildcard characters in name if part of the table name may change. For
example, if the table name depends on the month (invoices-jan, invoices-feb, and so on),
specifying invoices-* ensures that the table is copied to the data subfolder regardless of

Page 869 of 934

Commands

Name Description

the month suffix.

You can specify a single wildcard character to copy all Analytics output tables in the ana-
lytic script to the data subfolder:

//DATA *

Caution
Be careful when using wildcards characters. You may unintentionally
overwrite existing data tables if the wildcard pattern that you specify
matches unintended tables.
As a best practice, make the value of name as specific as possible. Use
wildcard characters only where they are required.

Uploads to Robots
For information about uploads to Robots, see "Uploads to the cloud-based Robots mod-
ule" on page 872.

Examples
Copying an Analytics table to the storage location
The following analytic header specifies that the Invoices table, which is output in the associated script, is
copied to the storage location:

COMMENT
//ANALYTIC Import Table
//DATA Invoices
END
IMPORT DELIMITED TO Invoices "Invoices.fil" FROM "Invoices.csv" 0 SEPARATOR "," QUALIFIER
'"' CONSECUTIVE STARTLINE 1 KEEPTITLE ALLCHAR ALLFIELDS

Remarks
Storing output tables
Output tables are not automatically copied to the storage location. You must use a DATA tag for each
table that you want to store. You can include multiple DATA tags in an analytic header if necessary.

When should I use the DATA tag?

Two situations require use of the DATA tag and storing Analytics tables:

Page 870 of 934

Commands

l output tables are used as input for subsequent analytic scripts

l users can select input tables or fields when scheduling an analytic, or running it ad hoc
Note
If an entire data analysis process is completed using a single analytic script, use of the
DATA tag is not required.
The DATA tag is not intended to be used for specifying result tables. Use the RESULT tag
instead. For more information, see "RESULT" on page 873.

Output tables are used as input for subsequent analytic scripts

Depending on the deployment environment, and the structure of associated scripts, you may need to use
the DATA tag to store an Analytics output table that you want to use in a subsequent analytic.
During analytic processing, Robots and AX Server use a temporary directory to store and access
Analytics output tables, so you may not need to use the DATA tag.
The table below provides guidance.

Deployment envir-
onment Use the DATA tag if... Do not need the DATA tag if...

Robots o an Analytics table output in one robot task o an Analytics table is output and sub-
is required as input in another robot task sequently input during a sequence of ana-
(Enterprise Edition
lytic scripts run in a single robot task
only) o an entire data analysis process is com-
pleted using a single analytic script

AX Server o an Analytics table output by one analytic o an entire data analysis process is com-
script is required as input for another ana- pleted using a single analytic script
lytic script

Analysis App win- o an Analytics table output by one analytic o an entire data analysis process is com-
dow script is required as input for another ana- pleted using a single analytic script
lytic script

Users can select input tables or fields

The TABLE and FIELD analytic tags create input parameters that allow a user to select an Analytics table,
and to select fields from the table, for use as input to an analytic script. However, a table must pre-exist in the
storage location in order to be available to be selected.
If you are developing an analytic that allows a user to choose one or more input tables and fields, a prior ana-
lytic with the DATA tag must run and save the appropriate table or tables to the storage location.

Locate output tables in the Source tables section in Robots

You can optionally add the src_ prefix to an output table name to locate the output table in the Source
tables section of the Input/Output tab in Robots.

Page 871 of 934

Commands

//DATA src_Invoices

You must add the prefix to the table name in both the //DATA tag and in the accompanying script.
The Source tables section allows you to visually separate tables that provide input for subsequent scripts.
If no output table names have the src_ prefix, the Source tables section does not appear in the Input/Out-
put tab and all tables are located by default in the Other tables section.

Uploads to the cloud-based Robots module

With analytic scripts run in Robots installations, specifying DATA uploads the table layout only (field name,
data type, field length) from the on-premise Robots Agent to the cloud-based Robots module in HighBond.
Table data remains on your organization's network, within the Robots Agent directory.
All information is encrypted in transit.

Overwriting linked or shared tables in AX Server

If an output table overwrites a linked or shared table in AX Server, the table is changed to a standalone
table.

Page 872 of 934

Commands

RESULT
Specifies the analytic output results that you want to make available to end users in client applications.
Output results, even if they exist, are not automatically made available. You must use a separate RESULT
tag for each result item that you want to make available.

Syntax
//RESULT type name
<description>

Parameters
Name Description

type The type of result item:

o TABLE – an Analytics table and associated data file (.fil)
o LOG – an analytic log file
o FILE – a non-Analytics file
For information about uploads to Robots, see "Uploads to the cloud-based Robots mod-
ule" on page 875.

name The name of the result item. The name value cannot contain any spaces.
Note
The name value must exactly match the name of the result item in the ana-
lytic script. You are not naming an item with name, you are matching a
name specified in the script.

Table name
The name value specifies an Analytics table name. You must specify the table name, not
the source data file name.
Correct:

//RESULT TABLE Missing_Checks

Incorrect:

//RESULT TABLE Missing_Checks.fil

Wildcard characters

Page 873 of 934

Commands

Name Description

You can use wildcard characters in name if part of the table name may change. For
example, if the table name depends on the month (invoices-jan, invoices-feb, and so on),
specifying invoices-* ensures that the table is made available in the results regardless of
the month suffix.

Log name
Optional. The name value specifies an analytic log file name. If you do not specify name,
the default log name is used: analytic_name.log.
Note
If you specify a log name, SET LOG TO log_name must appear in the
script.

File name
The name value specifies a non-Analytics file name.
You must specify the appropriate file extension for the type of non-Analytics file being out-
put.
Correct:

//RESULT FILE Missing_Checks.xlsx

Incorrect:

//RESULT FILE Missing_Checks

Wildcard characters
You can use wildcard characters for all or part of the name value to specify all files with a
specific extension ( *.xlsx ), or to specify files where part of the file name may change.
For example, if the file name depends on the month (invoices-jan.xlsx, invoices-feb.xlsx,
and so on), specifying invoices-*.xlsx ensures that the file is made available in the results
regardless of the month suffix.

description Descriptive text about the result or other information. The description can be multiline, but
it cannot skip lines.
optional

Examples
RESULT tag for an Analytics table:

//RESULT TABLE Missing_Checks

RESULT tag for an analytic log with the default name:

Page 874 of 934

Commands

//RESULT LOG

RESULT tag for an analytic log with a specified name:

//RESULT LOG My_log_name

.
.
.
SET LOG TO My_log_name

RESULT tag for a specific Excel file:

//RESULT FILE Missing_Checks.xlsx

RESULT tag for all Excel files:

//RESULT FILE *.xlsx

Remarks
Uploads to the cloud-based Robots module
With analytic scripts run in Robots installations, specifying RESULT LOG or RESULT FILE uploads analytic
log files or non-Analytics files from the on-premise Robots Agent to the cloud-based Robots module in
HighBond.
For more information about logs, see "How log files are output" below.
Specifying RESULT TABLE uploads the table layout only (field name, data type, field length). Result table
data remains on your organization's network, within the Robots Agent directory.
All information is encrypted in transit.

How log files are output

How log files for analytic scripts are output depends on whether a script succeeded or failed, and on which
environment the script is running in.

Analytic
script Robots Agent AX Server Analysis App window

o RESULT LOG specified o RESULT LOG specified o RESULT LOG specified

log file uploaded to cloud- log file output to AX Server log file output to Results tab
based Robots module (available in client applic-
Succeeded o RESULT LOG not specified

Page 875 of 934

Commands

Analytic
script Robots Agent AX Server Analysis App window

o RESULT LOG not specified ations) no log file

no log file o RESULT LOG not specified
no log file

o RESULT LOG tag not con- o RESULT LOG tag not con- o RESULT LOG tag not con-
sidered sidered sidered
l log file automatically out-
log file automatically output log file automatically output to
put to Robots Agent base
to AX Server (available in cli- Results tab
data folder
ent applications)
(configuration setting =
"false")
l log file automatically
uploaded to cloud-based
Robots module
(configuration setting =
"true" (default))
See configuration setting
UploadLogsWhenFailed in
Failed Configuring a Robots Agent.

Result file size limitation on AX Server

Result files are limited to a maximum of 2 GB for analytic scripts running on AX Server. If the file exceeds
this size, results are not saved.

Result file storage and availability during script execution

on AX Server
When you use the //RESULT FILE tag, the file that is created is available for download from AX Web Cli-
ent and AX Client once your script completes. This file is stored in the AX database and is not available on
the file system of AX Server when the script is not running.
During the execution of your script, the file is available temporarily on the file system of AX Server and you
can work with it using external processes, such as those you invoke using the EXECUTE command. While
your script is running, external processes can access the file from the analytic job subfolder.
Note
By default, analytic job subfolders are located inside ACL\Data\jobs. Once the script
completes, the analytic job subfolder is removed and the file is stored in the database.

Page 876 of 934

Commands

PUBLISH
Specifies a file that contains metadata defining which Analytics tables to publish to AX Exception when an
analytic is finished processing.

Syntax
//PUBLISH filename

Parameters
Name Description

filename The name of the file containing publishing metadata for AX Exception.

Examples
The analytic definition and the text file that specifies the publishing details for
the analytic
The FILE tag is required if the publish file is stored in the AX folder, so that the file is retrieved when the ana-
lytic is processed.

COMMENT
//ANALYTIC Publish Results
//RESULT TABLE Results
//FILE ex_publish.txt
//PUBLISH ex_publish.txt
END
EXTRACT RECORD TO Results

The ex_publish.txt file uploaded to the Related Files subfolder in the collection contains the following
line of text. The values must be quoted, and must use the following syntax: "table name","entity name","ana-
lytic name"

"Results","MyEntity","MyAnalytic"

Page 877 of 934

Commands

Developing analytics
To facilitate debugging and to isolate errors, develop the script body before adding the analytic header.
Once you add the analytic header, use the log file and temporary test values to test how the analytic
executes. Finally, deploy the analytic to the target environment.
Note
The following workflow is a suggested approach for developing analytics, however you are
free to develop analytics in whatever manner best suits you.

Workflow for creating and testing an analytic

script
Create the Analytics script
Create a script in Analytics without using any custom dialog boxes for user input, or any other features that
require user interaction during the running of the script. Analytics allow user input prior to running an ana-
lytic, but unlike scripts do not support user interaction during the running of the analytic.
To store test input values in the Analytics script, temporarily create variables at the top of the script:

ASSIGN v_AnalysisTable = "Trans_May"

Test and debug the script until it executes without errors.

Add the analytic header and tags

Add an analytic header to the script. Copy the variable names from the top of the script to the cor-
responding tags in the analytic header:

//TABLE v_AnalysisTable "Table to classify"

For more information, see "Adding analytic headers" on page 882.

Include the log in the analytic results

The log is a crucial tool for diagnosing the cause of analytic failures, but can also be important when ana-
lytics succeed but give unexpected results. The log is automatically output when an analytic fails, but it is
only output when an analytic succeeds if you specify the RESULT analytic tag.
Include the following line in the analytic header to ensure that a log is available every time the analytic is
run:

Page 878 of 934

Commands

//RESULT LOG

Validate the analytic header

Validate the analytic header. You can validate the analytic header as frequently as you want.
For more information, see "Validating analytic headers" on page 883.

Assign temporary test values to the analytic tags

Using the special assignment operator ( := ), assign temporary test values to all analytic tags that require
user input. You can copy the test values from the temporary variable assignments at the top of the script:

//TABLE v_AnalysisTable "Table to classify" := "Trans_May"

For more information about assigning temporary test values, see "Specifying test input values in Analytics"
on page 844.

Delete the temporary variables

Delete the temporary variables from the top of the script, or comment them out if you think you might want to
use them again.

Step through the analytic

Step through the analytic by clicking Step , or by pressing F10 repeatedly. Review the contents of the
Variables tab in the Navigator to ensure that all variables in the analytic header are being created correctly,
with the correct assignment of test values.
Test and debug the analytic until it executes without errors.
When you are finished testing, delete the temporary test values and the special assignment operator from
all analytic tags.
Note
If you want to exit the analytic before it completes, press Esc and click Yes in the con-
firmation prompt.
Tip
You can delete all stored variables and variable assignments from the Analytics project by
entering DELETE ALL OK in the command line. Clearing the Variables tab prior to step-
ping through an analytic gives you a clean start.

Page 879 of 934

Commands

Workflow for testing an analysis app

For analytics that will be run in AX Web Client, or the Analysis App window, you also need to test the ana-
lysis app.

Delete redundant table layouts

Once all analytics and any subscripts in the analysis app are tested, debugged, and executing correctly,
delete any table layouts from the Analytics project that you are not going to include in the analysis app.
Redundant table layouts will clutter the analysis app in AX Client, AX Web Client, and the Analysis App win-
dow, and could be confusing to end users.

Open the analysis app in the Analysis App window

Open the completed analysis app in the Analysis App window by right-clicking the Analytics project entry in
the Overview tab and selecting Open as Analysis App.
Note
If the analysis app fails to open and you get an error message stating that analytics have
identical names, check the name value in the ANALYTIC tag for each analytic specified in
the error message. The analytic name values must be unique in an Analytics project.

Run the analytics

Run all the analytics in the analysis app to confirm that they are functioning correctly.
Observe the correct order for running the analytics if you are using the TYPE option with the ANALYTIC
tag and creating import, preparation, and analysis analytics.

Check the log

If an analytic fails, open and review the log file (analytic_name.log). The log should include an entry,
marked with a red X, that indicates why the analytic failed:
l for incorrectly entered input values, immediately re-run the analytic with a correctly entered input
value
l for syntax or logical errors in the script body, correct the error in Analytics, and then reopen the ana-
lysis app in the Analysis App window
An analytic may succeed but the result table may not contain the results you were expecting. In this situ-
ation, review the log entries in sequence, and check the input values that have been passed to the analytic,
to ensure that the analytic is functioning in the manner you intended.

Page 880 of 934

Commands

Packaging and validating an analysis app

Package or import the analysis app
Once you are satisfied the analysis app is working as intended, package it for distribution and use in the Ana-
lysis App window, or import it to AX Server for use in AX Client or AX Web Client. For more information, see
"Packaging analysis apps" on page 891.

Run AX Server analysis apps

If you are developing analytics for use in AX Server, run all analytics using both AX Client and AX Web Cli-
ent to ensure they work as intended.

Page 881 of 934

Commands

Adding analytic headers

An analytic header is a series of declarative tags enclosed in a comment at the beginning of a script. The
header includes input parameters that a user populates in advance, which allows the analytic to run unat-
tended, either immediately, or at a scheduled time.
After you develop scripts in an Analytics project, you must add an analytic header before you can commit
the scripts to Robots, or use the project as an analysis app on AX Server or in the Analysis App window.

Analytic header requirements

An analytic header must conform to certain requirements. If it does not conform, the analytic script fails
when run.
For detailed information about analytic header syntax, and a full list of analytic tags, see "Analytic headers
and tags" on page 843.

Enclose analytic headers in a comment block

Analytic headers must be completely defined in a comment block that starts on the first line of the script.

COMMENT
Analytic tags go here.
END

Declare inputs and outputs

In the analytic header, you must declare any inputs required by the analytic, and any outputs that are
copied to Robots or AX Server, or written out as results in the Analysis App window:

Inputs Outputs

o tables o data files

o fields o results tables
o parameters o log files
o input files
o password prompts

Declare input values

Analytic headers must also declare any input values that users will specify when they run or schedule the
analytic.

Page 882 of 934

Commands

Use the PARAM tag to add input parameters that accept user-specified input values and store them in vari-
ables. For example, if you want an analytic to select data based on a date range, you need to add Start Date
and End Date input parameters that allow users to specify these dates.

Validating analytic headers

After you add an analytic header to one or more scripts, use tools in Analytics to validate the header syntax
to ensure that it is correct. Perform the validation before committing scripts to Robots, or packaging analysis
apps, so that the analytics do not fail when they run.
One tool validates individual analytic headers at the script level. The other tool validates all the analytic head-
ers in a project at once. The two types of validation focus on different things.

Validate an individual analytic header

Script-level validation of an analytic header focuses on the syntax of individual analytic tags and reports
errors with accompanying line numbers.
1. Open the script containing the analytic header.
2. On the Script Editor toolbar, click Validate Analytic Header .
A message appears telling you that the analytic header is valid, or specifying an error and the line
number where the error occurs.

3. If the analytic header contains an error, correct the error and click Validate Analytic Header
again to ensure that there are no further errors.
Tip
If the nature of the error is not apparent based on the error message, review the Help
topic for the associated analytic tag. Carefully compare the syntax in the topic with the
syntax in the line of the analytic header. Errors can be caused by minor discrepancies
in the analytic header syntax.

Validate all the analytic headers in a project

Project-level validation of the analytic headers checks two things:
l at least one analytic header exists in the project
l names of multiple analytics are unique
Note
Refers to the name specified in the ANALYTIC tag, not the script name in the Over-
view tab in the Navigator.
Project-level validation is performed automatically when you commit scripts to Robots. You can also per-

form the validation manually if you add the Check Scripts button to the Analytics toolbar.

Page 883 of 934

Commands

1. If necessary, add the Check Scripts button to the Analytics toolbar:

a. Double-click an empty spot on the toolbar to open the Customize Toolbar dialog box.
b. In the Available toolbar buttons list, select the Check Scripts button and click Add.
c. In the Current toolbar buttons list, select the Check Scripts button and click Move Up or Move
Down to change the location of the button.
The order of the buttons from top to bottom corresponds to their location from left to right on the
toolbar.
d. Click Close to save your changes.

2. On the toolbar, click Check Scripts .

A message appears telling you that the analytic headers in the project are valid, or specifying one or
more errors.

3. If the analytic headers contain an error, correct the error and click Check Scripts again to
ensure there are no further errors.

Example analytic header

COMMENT
//ANALYTIC Identify missing checks
  This analytic identifies missing check numbers
//TABLE v_table_payments Payments Table
  Select a table that lists payments and includes a check number column
//FIELD v_check_num CN Check Number
  Select the field that contains the check numbers
//PARAM v_start_date D OPTIONAL Start Date (Optional)
  Enter the start date for the analysis
//PARAM v_end_date D OPTIONAL End Date (Optional)
  Enter the end date for the analysis
//PARAM v_region C MULTI SEPARATOR , QUALIFIER ' Region(s)
  Enter one or more regions to include in the analysis
//RESULT LOG
//RESULT TABLE MissingChecks
//RESULT FILE MissingCheckDetails.xls
END

Page 884 of 934

Commands

Analytic development best practices

Analytics support most of the commands that you can use in a regular Analytics script. However, you must
ensure that analytics run without user interaction, and that they do not include commands not supported by
the engine that processes the analytics in the deployment environment.
Analytics support all Analytics functions.

General best practices

Use one Analytics project per robot or analysis app
Create a new Analytics project in Analytics for each robot or analysis app. The project must contain all the
analytics that make up the robot or the analysis app, and any required subscripts. For an analysis app, the
project must also contain any data files required by any of the analytics.

Test locally
Test all analytics locally before deploying them to the target environment. Ensure that analytics run as expec-
ted, and that they do not require user interaction.
For more information, see "Developing analytics" on page 878.

Use consistent data connections for testing

To test an analytic locally if it uses an ODBC data source, you must configure an ODBC connection on your
local computer that is identical to the connection in the environment where the analytic will run.
For analytics distributed for use in the Analysis App window, end users must configure an identical ODBC
connection on their computers.

Avoid absolute file paths

Avoid using absolute file paths in analytics (for example, C:\results) unless you are certain that identical
file paths exist in the environment where the analytic will run.
Using relative file paths such as \results allows you to develop and test analytics locally and then deploy
them in another environment without requiring that the other environment has an identical directory struc-
ture.

Use SET for preference settings

Use the SET command to specify any preference settings required by the analytic. If you do not specify pref-
erences in the analytic, the default Analytics preferences are used. Position the SET command after the

Page 885 of 934

Commands

analytic header but before any of the analytic logic.

Do not use computed fields in results or data tables

Do not use computed fields in any tables you intend to keep beyond the session in which the analytic script
runs.
Results and data tables that are kept for use in interpretations or as input for subsequent scripts may dis-
play unexpected values if they contain computed fields. Computed values are dependent on settings
defined in the preference file (.prf), or by the SET command, and therefore different environments may
produce different values.
If you need to retain the values in a computed field, use the EXTRACT command with the FIELDS or ALL
option to convert the field to a physical field in a result or data table. For more information, see "EXTRACT
command" on page 197.

Encrypt data connection passwords

To avoid having a data source password in plain text in an analytic, use the PASSWORD analytic tag. This
tag prompts the user for a password before running the analytic, and encrypts the entered value.

Use a password when importing from or exporting to

HighBond
The PASSWORD parameter is required in any command that imports from or exports to HighBond:
l IMPORT GRCRESULTS
l IMPORT GRCPROJECT
l EXPORT... ACLGRC
Without the PASSWORD parameter, the commands fail in Robots, Analytics Exchange, or the Analysis
App window.
When you use the PASSWORD parameter in an analytic script, you must also specify an associated pass-
word input parameter in the analytic header. For more information, see "PASSWORD" on page 866.
Note
The PASSWORD parameter is not required when running the import and export com-
mands in Analytics because the current user's HighBond access token is automatically
used.

Avoiding user interaction

Analytics must be able to run without user interaction. If a command in an analytic tries to create a dialog
box, the engine in the deployment environment stops processing the analytic, and an error is entered in
the log.

Page 886 of 934

Commands

Replace user interaction commands with analytic tags

Do not use Analytics commands that require user interaction. Replace them with equivalent analytic tags in
the analytic header. Analytic tags allow users to provide input values before the analytic runs.

Do not use Replace with

DIALOG //TABLE, //FIELD, //PARAM

ACCEPT //TABLE, //FIELD, //PARAM

PASSWORD //PASSWORD

PAUSE no equivalent

Guidelines
l to prevent analytic processing failures, remove all interactive commands
l to ensure files can be overwritten as necessary without displaying a confirmation dialog box, add the
SET SAFETY OFF command at the beginning of an analytic and then add the SET SAFETY ON
command at the end of the analytic to restore the default behavior
l to prevent confirmation dialogs from crashing the analytic, add the OK parameter after any com-
mands that normally display a confirmation dialog box:
l RENAME

l DELETE

Checking script syntax

Analytics provides a tool for detecting script syntax that causes analytics to fail, or that requires alignment
between your local environment and the environment where the analytics are deployed. The tool provides a
warning only, and you are still free to commit or import analytic scripts that have warnings.

What the tool checks

The tool checks all scripts in a project and detects three things:
l any command that requires user interaction
l any absolute file path
l any call of an external script
The tool checks all scripts in a project for the following items:
l any command that requires user interaction
l any absolute file path
l any call of an external script
l any command that imports from or exports to HighBond, and that does not have the
PASSWORD parameter

Page 887 of 934

Commands

When the check is performed

Script syntax checking is performed automatically when you commit scripts to Robots.
Automatic syntax checking is enabled by default. If you want to turn it off, select Disable Script Syntax
Check Before Commit Scripts in the Options dialog box (Tools > Options > Interface).

Perform checking manually

You can perform script syntax checking manually. You may need to first add the Check Scripts but-
ton to the Analytics toolbar.
1. If necessary, add the Check Scripts button to the Analytics toolbar:
a. Double-click an empty spot on the toolbar to open the Customize Toolbar dialog box.
b. In the Available toolbar buttons list, select the Check Scripts button and click Add.
c. In the Current toolbar buttons list, select the Check Scripts button and click Move Up or Move
Down to change the location of the button.
The order of the buttons from top to bottom corresponds to their location from left to right on the
toolbar.
d. Click Close to save your changes.

2. On the toolbar, click Check Scripts .

A message appears telling you that the script syntax in the project is valid, or specifying one or more
warnings.
3. Do one of the following:

l Correct any script syntax that generates a warning, and click Check Scripts again to ensure
that the warnings no longer appear.
l Ensure that the deployment environment contains a directory structure, or external scripts, that
align with the paths or external scripts specified in the analytic.

Best practices for analytics run on AX Server

Develop in Analytics
Develop analytics and their supporting scripts primarily in Analytics before importing them to AX Server.
As a convenience feature, the AX Client script editor does allow you to add new analytics or subscripts or
edit existing analytics or subscripts. This feature is useful for fine-tuning the behavior of an analytic without
having to export it to Analytics and then reimport it to AX Server. However, analytic development work bey-
ond minor adjustments is easier to accomplish in Analytics.

Page 888 of 934

Commands

Store related files with the Analytics project

Related files such as database profile files should be stored in the same folder as the Analytics project, but
must be imported to AX Server separately.

Avoid commands not supported on AX Server

l direct database server tables linked to Analytics Server Edition for z/OS
l the NOTIFY command supports only SMTP messaging. The MAPI and VIM mail protocols are not
supported
l to use the PRINT or TO PRINT command, a default printer must be configured on the server
l the SAVE GRAPH and PRINT GRAPH commands are not supported
l do not use the SET LEARN command in analytics

Minimize AX Server table transactions

Optimize the performance of analytics by minimizing the number of times tables on AX Server are
accessed:
1. Use the FILTER command to select the records you need.
2. Use the EXTRACT command to extract only the required fields.
The reduced data set will be processed locally on the server where the analytic is being run by the AX
Engine.
Optimizing analytics in this way is important when the data files are not located on the same server as AX
Server or the AX Engine Node processing the analytic, and the Copy analytic data option is not selected in
the AX Server Configuration web application.

Inefficient analytic example

OPEN LargeTable
SET FILTER TO trans_date >= `20091201` AND trans_date < `20100101`
COUNT
TOTAL amount
CLASSIFY ON account ACCUMULATE amount TO TransClassAccount

Efficient analytic example

OPEN LargeTable
SET FILTER TO trans_date >= `20091201` AND trans_date < `20100101`
EXTRACT FIELDS trans_date desc account type amount TO AnalysisTable
OPEN AnalysisTable
COUNT

Page 889 of 934

Commands

TOTAL amount
CLASSIFY ON account ACCUMULATE amount TO TransClassAccount

Access SAP data in background mode

Use Background mode to access data from SAP ERP systems using Direct Link.

Page 890 of 934

Commands

Packaging analysis apps

To run analytic scripts in the Analysis App window or on AX Server, create a packaged analysis app
(.aclapp file). You can package an Analytics project into a new .aclapp file, or merge an Analytics pro-
ject with an existing analysis app (.aclx file) to include existing interpretations.
Note
If at least one script in an Analytics project contains an analytic header, the project can be
packaged as an analysis app. Before packaging an analysis app make sure you validate
the analytic headers of each analytic in the analysis app.

Why use a packaged analysis app?

Distributing to Analysis App window users
Use packaged analysis apps to distribute a project to users who can extract the .aclx file and open the con-
tents in the Analysis App window.
In the Analysis App window, you can run the analytic scripts and create interpretations based on tables and
analytic results.

Importing into AX Server

Use packaged analysis apps to prepare an Analytics project for import into AX Server. You can choose
which tables and data files to import along with the analytic scripts in the project.
You can also use a packaged analysis app (.aclapp) to import existing interpretations. To include the inter-
pretations from an existing analysis app (.aclx) you must repackage your Analytics project and merge this
packaged analysis app (.aclapp) with the existing .aclx file in your project folder.
Note
When you use an existing analysis app (.aclx file), the contents of the Analytics project
take precedence, so if there are scripts or tables in the .aclx that no longer exist in the
.acl file, they are not included in the resulting packaged analysis app (.aclapp file).

File size limitation

To use a packaged analysis app successfully, you must ensure that the sum of all file sizes included in the
package does not exceed 800 MB before packaging the analysis app. If your prepackaged files exceed this
combined size, data files may be corrupted when unpacking the analysis app.

Page 891 of 934

Commands

Package a new analysis app

1. In Analytics, right-click the project entry in the Overview tab of the Navigator and select Package
Analysis App.
The Analytics project is the top-level folder in the tree view.
2. In the Select Tables dialog box, do the following:
a. If you want to include one or more of the project tables and associated data files in the analysis
app, select the table(s) and the data file(s) to include.
Note
Generally you should include only static tables and data files that are required by
one or more of the analytics in the analysis app, such as a master vendor table, or
a list of merchant category codes.
b. Click To and navigate to the location where you want to save the packaged analysis app.
c. In the Save As dialog box, enter a File name with the .aclapp file extension and click Save.
d. Click OK.
Result – the packaged analysis app is saved to the location you specified. Other users can retrieve the
packaged analysis app from this location, or you can distribute it by email, or by other appropriate method.
You can also import this file into AX Server.

Package an analysis app with interpretations

1. Ensure that the analysis app (.aclx file) that contains the interpretations you want to import exists
in the Analytics project folder on your computer and uses the same file name as the
Analytics project (.acl file).

2. In Analytics, right-click the project entry in the Overview tab of the Navigator and select Package
Analysis App.
The Analytics project is the top-level folder in the tree view.
3. In the Select Tables dialog box, do the following:
a. If you want to include one or more of the project tables and associated data files in the analysis
app, select the table(s) and the data file(s) to include.
Note
Generally you should include only static tables and data files that are required by
one or more of the analytics in the analysis app, such as a master vendor table, or
a list of merchant category codes.
b. Optional. To include the interpretations from the existing analysis app, select Include Inter-
pretations .

Page 892 of 934

Commands

Interpretations that are associated with tables or scripts that do not exist in the new package are not
included.
c. Click To and navigate to the location where you want to save the packaged analysis app.
d. In the Save As dialog box, enter a File name with the .aclapp file extension and click Save.
e. Click OK.
Result – the packaged analysis app is saved to the location you specified. Other users can retrieve the pack-
aged analysis app from this location, or you can distribute it by email, or by other appropriate method. You
can also import this file into AX Server.

Page 893 of 934

Commands

Sample analytic scripts (analysis app)

The sample analytic scripts contain one import analytic (two versions), one preparation analytic, and one
analysis analytic. The analytic scripts can be run in any of the following environments or client applications:
l Robots
l AX Server:
l AX Client

l AX Web Client

l the Analysis App window

Sequence of the analytic scripts

The three analytics are designed to work in conjunction, and need to be run in the following sequence:

Sequence ANALYTIC TYPE Analytic name

IMPORT Sample Import analytic Robots_AX

or
1 Sample Import analytic Web_AA_Window

2 PREPARE Sample Preparation analytic

3 ANALYSIS Sample Analysis analytic

Sample import analytic

Imports data from the sample Excel file Trans_May.xls and saves it to the new Analytics table Trans_
May_raw (the raw data table).
Two versions of this analytic are provided.

Analytic name Use in Import file requirement

o Robots o Robots –Trans_May.xls must be located in the

o AX Client Input/Output tab in the same robot as the analytic
o AX Client –Trans_May.xls must be located in the
Sample Import analytic Related Files subfolder in the AX folder where the
Robots_AX analytic is located

Sample Import analytic o AX Web Client

Web_AA_Window o Analysis App window

Page 894 of 934

Commands

Sample import analytic for use in Robots or AX Client

COMMENT
//ANALYTIC TYPE IMPORT Sample Import analytic Robots_AX
This analytic imports data from the sample Excel file Trans_May.xls and saves it to the new Analytics
table "Trans_May_raw" (the raw data table).
//FILE Trans_May.xls
//DATA Trans_May_raw
//RESULT LOG
END

SET SAFETY OFF

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "Trans_May.xls" TABLE "Trans2_
May$" KEEPTITLE FIELD "CARDNUM" C WID 22 AS "" FIELD "CODES" C WID 4 AS "" FIELD
"DATE" D WID 10 PIC "YYYY-MM-DD" AS "" FIELD "CUSTNO" C WID 6 AS "" FIELD
"DESCRIPTION" C WID 95 AS "" FIELD "AMOUNT" N WID 9 DEC 2 AS ""
SET SAFETY ON

Sample import analytic for use in AX Web Client or the Ana-

lysis App window
COMMENT
//ANALYTIC TYPE IMPORT Sample Import analytic Web_AA_Window
This analytic imports data from the sample Excel file Trans_May.xls and saves it to the new Analytics
table "Trans_May_raw" (the raw data table).
//PARAM v_input_file F Input File
Select an input file
//DATA Trans_May_raw
//RESULT LOG
END

SET SAFETY OFF

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "%v_input_file%" TABLE "Trans2_
May$" KEEPTITLE FIELD "CARDNUM" C WID 22 AS "" FIELD "CODES" C WID 4 AS "" FIELD
"DATE" D WID 10 PIC "YYYY-MM-DD" AS "" FIELD "CUSTNO" C WID 6 AS "" FIELD
"DESCRIPTION" C WID 95 AS "" FIELD "AMOUNT" N WID 9 DEC 2 AS ""
SET SAFETY ON

Page 895 of 934

Commands

Sample preparation analytic

Prepares the raw data table for analysis and saves it to the new Analytics table Trans_May_prepared
(the analysis table). The analytic defines a shorter version of the "Description" field because classifying
only supports field lengths up to 64 characters.

COMMENT
//ANALYTIC TYPE PREPARE Sample Preparation analytic
This analytic prepares the raw data table for analysis and saves it to the new Analytics table "Trans_
May_prepared" (the analysis table). The analytic defines a shorter version of the "Description" field
because classifying only supports field lengths up to 64 characters.
//TABLE v_RawTable Table to prepare
Select the raw data table you want to prepare
//RESULT TABLE Trans_*_prepared
//DATA Trans_*_prepared
//RESULT LOG
END

SET SAFETY OFF

OPEN %v_RawTable%
DEFINE FIELD DESC_SHORT ASCII 43 64
EXTRACT RECORD TO "Trans_May_prepared"
SET SAFETY ON

Sample analysis analytic

Classifies the analysis table and outputs the results to the new Analytics table Classified_Trans_
May_prepared (the results table). Users can specify which field to use for classifying the table, and can
specify merchant category codes, customer numbers, and date and transaction amount ranges to restrict
which records are processed.

COMMENT
//ANALYTIC TYPE ANALYSIS Sample Analysis analytic
This analytic classifies the analysis table and outputs the results to the new Analytics table "Clas-
sified_Trans_May_prepared" (the results table). You can specify merchant category codes, customer
numbers, and date and transaction amount ranges, to restrict which records are processed.
//TABLE v_AnalysisTable Table to classify
Select the analysis table you want to classify
//FIELD v_FieldA C Field to classify on
Select the field you want to classify on
//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' VALUES |4112 Passenger Railways|4121
Taxis/Limousines|4131 Bus travel|4215 Courier Services - Air or Ground|4411 Cruise Lines|4457

Page 896 of 934

Commands

Boat Leases and Boat Rentals|4722 Travel Agencies and Tour Operations|4814 Local/long-distance
calls|5812 Restaurants|5813 Drinking Places (Alcoholic Beverages)|5814 Fast food restaurants|5921
Package Stores, Beer, Wine, Liquor|5993 Cigar Stores & Stands|5994 Newsstand|7216 Dry cleaners|
MC code(s) to include
Specify one or more merchant category codes to include
//PARAM v_cust_no C OPTIONAL MULTI SEPARATOR , QUALIFIER ' Customer Number(s) to
exclude (optional)
Specify one or more customer numbers to exclude. Press "Enter" after each number, so that each num-
ber is on a separate line. Do not enclose numbers in quotation marks.
//PARAM v_start_date D VALUES
|05/01/2003|05/02/2003|05/03/2003|05/04/2003|05/05/2003|05/06/2003|05/07/2003|05/08/2003|05/0-
9/2003|05/10/2003|05/11/2003|05/12/2003|05/13/2003|05/14/2003|05/15/2003|05/16/2003|05/17/200-
3|05/18/2003|05/19/2003|05/20/2003|05/21/2003|05/22/2003|05/23/2003|05/24/2003|05/25/2003|05/-
26/2003|05/27/2003|05/28/2003|05/29/2003|05/30/2003|05/31/2003|Start Date
Select a start date
//PARAM v_end_date D End Date
Enter an end date or pick one from the calendar
//PARAM v_min_amount N Minimum Amount
Enter a minimum amount
//PARAM v_max_amount N Maximum Amount
Enter a maximum amount
//RESULT TABLE Classified_*
//RESULT LOG
END

SET SAFETY OFF

OPEN %v_AnalysisTable%
IF NOT ISDEFINED("v_cust_no") v_cust_no = ""
GROUP IF v_cust_no = ""
CLASSIFY ON %v_FieldA% IF MATCH(CODES, %v_codes%) AND BETWEEN(DATE, v_start_
date, v_end_date) AND BETWEEN(AMOUNT, v_min_amount, v_max_amount) SUBTOTAL
AMOUNT TO "Classified_%v_AnalysisTable%.FIL" OPEN
ELSE
CLASSIFY ON %v_FieldA% IF MATCH(CODES, %v_codes%) AND NOT MATCH(CUSTNO, %v_
cust_no%) AND BETWEEN(DATE, v_start_date, v_end_date) AND BETWEEN(AMOUNT, v_min_
amount, v_max_amount) SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL" OPEN
END
SET SAFETY ON

Page 897 of 934

Appendix

Page 899 of 934

Appendix

System requirements
Before installing Analytics, ensure that your computer meets the minimum software and hardware require-
ments.

Software requirements
Note
Some software prerequisites are automatically installed if not already present on your
computer. For a complete list of automatically installed prerequisites, see the online doc-
umentation.

Requirement Additional information

One of the following operating ACL for Windows is a 32-bit application that can run on the 64-bit versions of Win-
systems: dows.
o Microsoft Windows 10 (64-bit) Note
o Microsoft Windows 8.1 (64-
To install ACL for Windows on Windows 7, you must have Service
bit)
o Microsoft Windows 7 Service Pack 1 installed. ACL for Windows requires Microsoft .NET 4.6.x,
Pack 1 (SP1) (32-bit/64-bit) which cannot be installed on versions of Windows 7 prior to SP1.
Windows XP is no longer a supported operating system.

For Microsoft Windows 8.1 Important

users:
Windows 8.1 Update KB2919355 is required by Microsoft .NET
Windows 8.1 Update Framework 4.6.x, which in turn is required by ACL for Windows 14.
KB2919355
If you are using Windows 8.1, and .NET 4.6.x is not installed, and
you have not run Update KB2919355, the ACL for Windows
installer terminates with an error message during the .NET 4.6.2
prerequisite installation.
You need to download and install Update KB2919355 before you
can continue with the ACL for Windows installation.
Alternatively, you can install Update KB2919355 before you begin
the ACL for Windows installation and avoid the error message.
Caution
If you are prompted to restart your computer at any point during the
installation process, do so right away. Do not ignore messages to
restart your computer.
If you do not restart your computer when you are prompted, you
may cause problems with the installation of .NET, other pre-
requisites, or ACL for Windows.

To use Analytics functions that The bitness of the installed version of R must match the bitness of the operating
integrate with the system.
R programming language, you

Page 900 of 934

Appendix

Requirement Additional information

must install and configure R (32- If you are using one of the CRAN R packages, you may need to add the path to
bit/64-bit). the R binary folder to the PATH environment variable on your computer.
The following versions of R have For example:
been tested and work with Ana- o C:\Program Files\R\R-<version>\bin\i386 (32-bit)
lytics: o C:\Program Files\R\R-<version>\bin\x64 (64-bit)
o 3.3.2 Note
o 3.3.1
o 3.2.5 You do not need to install R if you do not intend to use the
o 3.2.3 Analytics functions integrated with this language.
You can use either CRAN R (32-
bit/64-bit) or Microsoft R (64-bit
only).
Note
Other versions of R
may work as well.
However, they are
not guaranteed to
work.
Currently, R 3.5.0
and later are not sup-
ported for use with
Analytics.

To use Analytics functions that Python version 3.5.x is fully tested and supported. You may use a different version
integrate with the Python pro- such as 3.3.x or 3.6.x, however these versions do not offer the same guarantee of
gramming language, you must testing and support with Analytics as 3.5.x.
install and configure:
When installing Python, you must also configure it to run on your system. For
o Python version 3.3.x or later more information, see "Configuring Python for use with Analytics" on page 905.
(32-bit)
Note
o PYTHONPATH environment
variable You do not need to install Python if you do not intend to use the
o ACLPYTHONDLL envir- Analytics functions integrated with this language.
onment variable
The local copy of the Python Engine contained in the Analytics
installation directory is not intended for use with the Analytics
Python functions, or for general Python use. You must install a sep-
arate instance of Python for these purposes.

To use the ACL Connector for o You do not need to install Oracle Instant Client if you do not intend to use the
Oracle, you must install: ACL Connector for Oracle.
o The bitness of Oracle Instant Client must match your operating system's bit-
o Oracle Instant Client 11g or
ness. If the 32-bit Instant Client is installed on a 64-bit machine, the connection
12c
fails.
o If you are using the connector with Analytics Exchange and you install the
Oracle Instant Client after AX Server, you must restart the Analytics Exchange
Service before you can use the connector.

Page 901 of 934

Appendix

Hardware requirements
Note
The best Analytics performance in a production environment may require greater
resources than the minimum specification.

Component Minimum Recommendation

Processor 1.8 GHz

2 GB o 64-bit operating systems: 8 GB or more, especially if sorting large

Memory
files
(RAM) o 32-bit operating systems: 4 GB, especially if sorting large files

Hard disk space 1.1 GB

(Analytics application files)

Hard disk space 8 GB

(software prerequisites)

100 GB or more

In addition to the hard disk space required to install
Analytics application files and prerequisites, significant additional
Hard disk space
space is required if a computer will be used to store data extracts, flat
(data storage) files, and results.

Page 902 of 934

Appendix

Installing ACL for Windows

Follow the ACL for Windows installation instructions to install or upgrade your copy of Analytics. Once the
installation completes, you must activate your license.
Note
When you install or upgrade Analytics, any existing Analytics sample data files are over-
written if they are in the Analytics working directory you specify during the installation or
upgrade.
If you have made changes to any of the sample projects or data files that you want to keep,
save the files elsewhere before installing or upgrading, or rename the folder containing
them. Do the same with the associated command log files if you want to preserve them.

Obtain the installer

Obtain your installer from your organization's primary contact with Galvanize. If you are the primary contact:
l Internet access – obtain the installer from the downloads page in Launchpad (http://www.high-
bond.com/)
l No Internet access – ask your Galvanize representative to help you obtain the installer from Launch-
pad

Extract the installer

1. Double-click the ACL for Windows installation package (ACLforWindows141.exe).
2. If a security warning dialog box appears, verify the information listed, and click Yes .
3. Select the language you want to use for your installation and click OK.
4. In the Setup Extraction Location page, click Extract.
After the files are extracted the installer starts automatically.

Install any prerequisites

If you are prompted to install prerequisites, click Install .
After the prerequisites are installed, the installer automatically proceeds.

Install ACL for Windows

Follow the onscreen instructions to perform the ACL for Windows installation.
In the ACL Edition Selection page, select the edition you want to install:

Page 903 of 934

Appendix

l Non-Unicode
l Unicode
For more information about Unicode and non-Unicode editions, see "Unicode versus non-Unicode edi-
tions" on page 908.

Activate your license

If you have access to the Internet, you can activate the first time you start ACL for Windows and sign in to
your organization. To activate your license offline, contact Galvanize Support.

Start Analytics
To start Analytics, do one of the following:

To create a new, empty Analytics project Under Create, click Analytic Project

To open an existing Analytics project Under Open, click Analytic Project

To open a recent or a sample Analytics project (.acl) Under Recent Analytics Files, or Sample Files, click the
name of a project

Page 904 of 934

Appendix

Configuring Python for use with Ana-

lytics
To configure Python to work with Analytics, you must install the correct version of Python and add the
executable to your system PATH environment variable. You must also set the ACLPYTHONDLL and
PYTHONPATH system environment variables.

How it works
To run Python scripts, Analytics must be able to call the Python executable and find the scripts it is instruc-
ted to run. Analytics uses the PATH environment variable to locate Python and the
PYTHONPATH environment variable to locate scripts.

Install Python version 3.3.x or later (32-bit)

1. From the Python downloads page, download the latest version of Python 3.5 to your machine.
2. On your machine, double-click the installer.
3. In the installer, select Add Python versionNumber to PATH.
4. Click Install and follow the on-screen instructions.
5. Reboot the machine before running any Python scripts from Analytics.

Set the ACLPYTHONDLL and PYTHONPATH

environment variables
1. In your Windows operating system, create one or more folders to house your Python scripts.
Example –C:\python_scripts.
2. From your Windows operating system, open the System Properties dialog box and click Envir-
onment Variables .

Page 905 of 934

Appendix

3. In the System variables section, click New and enter the following variables:
Variable name Variable value Example

PYTHONPATH The full path to the folder(s) you C:\python_scripts;C:\dev;C:\tmp

created to house the Python
scripts. Separate multiple folder
paths with a semi-colon.

ACLPYTHONDLL The full path and filename of the c:\python_install\python33.dll

Python DLL file in the Python
installation folder that you want to
use with Analytics.
If you are using Python 3.3.x, the
following restrictions apply:
o Unicode characters are not sup-
ported in the path for European
platforms
o Extended characters are not
supported in the path for Asian
platforms
Note
Python adds the DLL to
the system folder (c:\w-
indows\system32\py-
thon33.dll) rather tha-
n the installation folder.
You must copy the DLL -
from the system folder t-
o the installation folder,
and use this as the vari-
able value so that Analy-
tics can access the DLL-
.
You may also need to r-
emove any read only se-
ttings from the installati-
on folder.
If you do not set this value, Ana-
lytics attempts to use the default
supported version 3.5.x
DLL python35.dll.

4. To save the variable, click OK and then in the System Properties dialog box, click OK.

Use Python in Analytics Python functions

From Analytics, use the Analytics Python functions to call functions in scripts that exist in your
PYTHONPATH.

Page 906 of 934

Appendix

Note
If you make any edits to a Python script, you must refresh the view in your Analytics project
to use the latest version of the Python script. The simplest way to refresh the view is to close
the table you are working with and then re-open it.

Page 907 of 934

Appendix

Unicode versus non-Unicode editions

Unicode editions of Analytics products allow you to view and work with files that contain Unicode data.
Unicode is an industry-standard method of character encoding that supports most of the world's lan-
guages.

Should I install the non-Unicode or the

Unicode edition?
Analytics is available in non-Unicode and Unicode editions. Both editions are contained in the same install-
ation package, and during the installation you specify which edition to install.
You should install the non-Unicode edition, unless you have a requirement to view or analyze Unicode
data. Unicode data can only be opened in the Unicode edition of Analytics.
You are more likely to encounter Unicode data if you work in an environment with global information sys-
tems, or you analyze data that contains multiple languages.

When the Unicode edition is required

You need to install the Unicode edition to view or analyze data with:
l Asian characters
l a combination of non-Unicode, or traditional, character encodings
For example, some combination of languages from at least two of these character encodings:
l Latin 1 (English and Western European)
l Latin 2 (Central European)
l Cyrillic
l Greek
l Arabic
Note
If you want to use the Chinese, Japanese, or Polish Analytics user interface the only
option is to install the Unicode edition. This requirement is related to the language of the
user interface, not to the language of the data.

Page 908 of 934

Appendix

Converting analytics to Unicode

If you are migrating from the non-Unicode edition of Analytics to the Unicode edition, existing analytics and
scripts are automatically converted to Unicode. However, you must verify that the logic of the scripts remains
the same when applied to double-byte Unicode data.

What is Unicode?
Unicode is a standard for encoding text that uses two or more bytes to represent each character, and char-
acters for all languages are contained in a single character set. The Unicode editions of Galvanize products
allow you to view and work with files and databases that contain Unicode-encoded data in all modern lan-
guages.
Note
Analytics and the AX Engine support little-endian (LE) encoded Unicode data. These
products cannot be used to analyze big-endian (BE) encoded data.

Migrating to Unicode Analytics Exchange

l encryption of Unicode scripts is not currently supported
l Analytics project files and log files are encoded as Unicode data (UTF-16 LE) and cannot be used
with the non-Unicode edition of Analytics
l when you use Analytics to define print image and delimited files that contain ASCII or EBCDIC-
encoded text, the fields in the Analytics table containing this data are assigned the Unicode data type
by default

Required analytics changes

Update any parameters that specify a value in bytes
Characters in the non-Unicode edition of Analytics are one byte in length. Characters in the Unicode edition,
if they are Unicode data, are two bytes in length. When you specify field length or starting position in bytes in
the non-Unicode edition of Analytics, the number of bytes is equal to the number of characters. This is not
true for Unicode data in the Unicode edition of Analytics.
To convert analytics for use in Unicode Analytics, you must adjust the numeric value of any parameters that
specify field length or starting position in bytes. For example, for an IMPORT DELIMITED command that
specifies a WID value of 7 in non-Unicode Analytics, you must double the WID value to 14 to produce the
same result in Unicode Analytics.
In addition, for Unicode data, specify an odd-numbered starting byte position for fields, and an even number
of bytes for field lengths. Specifying an even-numbered starting position, or an odd-numbered length, can
cause characters to display incorrectly.

Page 909 of 934

Appendix

Recreate all instances of IMPORT PRINT and

IMPORT DELIMITED
You need to recreate all instances of the IMPORT PRINT and IMPORT DELIMITED commands by
importing the source data file using the Data Definition Wizard in the Unicode version of Analytics and reim-
porting the projects into AX Server. Using the Data Definition Wizard ensures that all syntax is valid.

Change all instances of the ZONED( ) and EBCDIC( ) func-

tions
You need to change all instances of the ZONED() and EBCDIC() functions as follows so that the ASCII
values returned by the functions are correctly converted to Unicode data:
l Computed fields – wrap the BINTOSTR() function around ZONED() or EBCDIC() instances
l Static expressions – wrap the BINTOSTR() function around ZONED() instances

BINTOSTR(ZONED(%result%, 5), 'A')

Change all instances of the OPEN FORMAT command

You need to modify all instances of the OPEN FORMAT command. You need to use the SKIP parameter
to skip the first two bytes of the Unicode file you are opening. This is required because the first two bytes of
UTF-16 encoded files are reserved as byte order marks and are separate from the text in the file.

Non-Unicode

OPEN "ascii_test.txt" FORMAT template_table CRLF

DEFINE FIELD full_rec ASCII 1 10

Unicode

OPEN "utf-16_test.txt" FORMAT template_table CRLF SKIP 2

DEFINE FIELD full_rec UNICODE 1 20

Verifying converted analytics

Verify that the Unicode versions of the analytics produce results that are identical to the results produced
by the non-Unicode analytics. The best way to do this is to use a Diff tool to compare the log files produced
in the analysis. The Diff tool identifies any differences between the files.

Page 910 of 934

Appendix

What if the results are not the same?

If you cannot produce the same results with the Unicode version of an analytic as the non-Unicode version,
you may be able to isolate the problem by comparing the log outputs of the scripts at each step of the ana-
lysis.

Page 911 of 934

Appendix

Checking for Unicode compatibility

When upgrading to a Unicode edition, you need to verify that any custom logic you have added to scripts
will produce the same results when run against Unicode data. There are predictable areas where scripts
may be affected when they are run against Unicode data.

Bit and Character functions

Each of the functions listed below returns values based on byte locations or byte counts. You need to
check to ensure that these functions are still being used correctly when you move from the single-byte rep-
resentation of characters used in the non-Unicode edition to the double-byte character encoding used for
Unicode data:
l ASCII( )
l BIT( )
l BYTE( )
l CHR( )
l DIGIT( )
l HEX( )
l MASK( )
l SHIFT( )

Byte length does not equal character length

You need to check the way the following functions are used in your scripts to ensure that they do not
assume a one-to-one correspondence between the number of characters in data and the number of
bytes.
If you find any instances where the logic assumes a one-to-one correspondence between characters and
bytes, you must adjust the logic to work correctly with Unicode data, which uses two bytes to represent
each character. Numbers specified as string function parameters, such as 4 in STRING(1000, 4) refer to
the number of characters, so standard usage of these functions will not cause problems.

Conversion Functions
l PACKED( )
l STRING( )
l UNSIGNED( )

Page 912 of 934

Appendix

l VALUE( )
l ZONED( )

String functions
l AT( )
l BLANKS( )
l INSERT( )
l LAST( )
l LENGTH( )
l REPEAT( )
l SUBSTRING( )

Miscellaneous functions
l FILESIZE( )
l LEADING( )
l OFFSET( )
l RECLEN( )

Substituting Unicode-specific functions

Galvanize Unicode products support six Unicode-specific functions that support conversions between non-
Unicode and Unicode data. The following functions are available in Galvanize Unicode products:
l BINTOSTR() – converts ZONED or EBCDIC data to its corresponding Unicode string. This ensures
that values encoded as ZONED or EBCDIC data can be displayed correctly
l DHEX( ) – returns the hexadecimal equivalent of a specified Unicode field value. This function is the
inverse of HTOU( )
l DBYTE( ) – returns the Unicode character interpretation of a double-byte character at a specified pos-
ition in a record
l DTOU( ) – converts a date value to the correct Unicode string display based on the specified locale
setting
l HTOU( ) – returns the Unicode equivalent of a specified hexadecimal string. This function is the
inverse of DHEX( )
l UTOD( ) – converts a locale-specific Unicode string to an Analytics date value

Page 913 of 934

Appendix

Running R scripts on AX Server

Import external R scripts as related files along with an analysis app and then call the R scripts from your
analytics to leverage the statistical analysis capabilities of the R scripting language on the server. To pre-
pare the AX Server environment to run R scripts, you must first install R and then add the .r extension to
the file extension whitelist.

Prerequisites
To run R scripts on AX Server, you must:
1. Install a supported version of the R scripting language on your AX Server computer.
2. Add the .r extension to the file extension whitelist on AX Server.
3. In Analytics, create a project to work with and import into AX Server.
Note
For help completing these prerequisites, contact your Analytics Exchange administrator
and see:
l AX Server requirements
l Whitelisting file extensions

Add R scripts to the Analytics project directory

After you create your Analytics project in Analytics, copy the R scripts you intend to use and paste them
into the project folder so that you can test your script locally in Analytics before importing it to Analytics
Exchange.

Example R files
The following example R files contain trivial scripts that concatenate two strings and return a single string
joined by a space character. These examples are intended to show how R scripts run on AX Server, not
how to analyze data with R.

analysis_a.r

conc<-function(x, y) {
paste(x, y, sep=" ")
}
print(conc(value1, value2))

Page 914 of 934

Appendix

analysis_b.r

conc<-function(x, y) {
paste(y, x, sep=" ")
}
print(conc(value1, value2))

Create an Analytics script

In your Analytics project, create a new script to use as the analytic you run on AX Server. This script does
the following:
1. Opens a temporary table called t_tmp with one record.
You must open a table to execute the EXTRACT command in Analytics, here the t_tmp table is used
only for this purpose.
2. Uses the EXTRACT command to run each R script and writes the results to a table.

Add the analytic header

Add the appropriate analytic header tags at the beginning of the script so that the Analytics script can run on
AX Server after you import your analysis app. You must add a FILE tag for any R script you intend to run
from the analytic:

COMMENT
//ANALYTIC R integration test
verify R integration on AX Server
//DATA t_tmp
//FILE analysis_a.r
//FILE analysis_b.r
//RESULT TABLE results
END

Add the script logic

SET SAFETY OFF
DEL ALL OK
CLOSE PRIMARY SECONDARY

OPEN t_tmp

COM **** execute R scripts and write results to table

Page 915 of 934

Appendix

EXTRACT FIELDS RSTRING("a<-source('./analysis_a.r');a[[1]]",50,"test","value") AS "value" TO

"results.fil"
EXTRACT FIELDS RSTRING("a<-source('./analysis_b.r');a[[1]]",50,"test","value") AS "value" TO
"results.fil" APPEND

CLOSE t_tmp

The complete analytic script

The complete analytic that you run on AX Server looks as follows:

COMMENT
//ANALYTIC R integration test
verify R integration on AX Server
//DATA t_tmp
//FILE analysis_a.r
//FILE analysis_b.r
//RESULT TABLE results
END

SET SAFETY OFF

DEL ALL OK
CLOSE PRIMARY SECONDARY

OPEN t_tmp

COM **** execute R scripts and write results to table

EXTRACT FIELDS RSTRING("a<-source('./analysis_a.r');a[[1]]",50,"test","value") AS "value" TO
"results.fil"
EXTRACT FIELDS RSTRING("a<-source('./analysis_b.r');a[[1]]",50,"test","value") AS "value" TO
"results.fil" APPEND

CLOSE t_tmp

Import the Analytics project and related R files

Once you have authored the analytic script:
1. In AX Client, create a collection and folder to house the Analytics project.
2. To import the project and R files:
a. Right-click the folder you created and select Import.
b. Navigate to your Analytics project on your local computer and select the .acl project file and the
.r R scripts.

Page 916 of 934

Appendix

Note
Make sure you select the R files in the project folder as well as the Analytics project
using Ctrl+click so that they are imported into AX Server. You must also import the
source data files for the t_tmp table.
c. Click Open.

Server explorer after import

l collectionName
l folderName

l Analysis Apps

l ACLProjectName

l analyticScriptName

l Data

l t_tmp

l Related Files

l analysis_a.r

l analysis_b.r

Run the analytic

From the Server Explorer of AX Client, right-click the analytic and select Run. The R scripts are executed
as part of the analytic and you can access the results results table from AX Web Client.

Results
Server explorer after running the analytic
l collectionName
l folderName

l Analysis Apps

l ACLProjectName

l analyticScriptName

l Data

l results

l Related Files

l analysis_a.r

l analysis_b.r

Results table
l value
l test value
l value test

Page 917 of 934

Appendix

Running Python scripts on AX Server

Have an Analytics Exchange administrator upload external Python scripts to the PYTHONPATH directory
of AX Server and then call the scripts from your analytics to leverage the object-oriented features of the
Python programming language on the server. To prepare the AX Server environment to run Python
scripts, you must first install Python, and then set the PYTHONPATH environment variable.

Prerequisites
To run Python scripts on AX Server, you must:
1. Install a supported version of the Python scripting language on your AX Server computer.
2. Set the PYTHONPATH environment variable on AX Server.
3. In Analytics, create a project to work with and import into AX Server.
Note
For help completing these prerequisites, contact your Analytics Exchange administrator
and see:
l AX Server requirements
l Configuring Python for use with AX Server

Create a Python script

After you create your Analytics project in Analytics, create a Python script that you can call from an ana-
lytic.
Then, give your Analytics Exchange administrator this script file to upload to the PYTHONPATH directory
of the machine hosting AX Server before you call the script from an analytic. When the analytic runs on AX
Server, the Python executable looks for the script in the PYTHONPATH directory, so it must be present.

Example Python file

The following example Python file contains a trivial script that uses a lambda expression to raise a number
to the power of itself. This example is intended to show how Python scripts run on AX Server, not how to
analyze data with Python.

Filename: lambda_example.py

# myFunc squares value1 and returns the value

myFunc = lambda value1: value1**2

Page 918 of 934

Appendix

Create an Analytics script

In your Analytics project, create a new script to use as the analytic you run on AX Server. This script does
the following:
1. Opens a simple table called py with one record.
You must open a table to execute the GROUP command in Analytics, here the py table is used only
for this purpose.
2. Loops 10 times and in each loop, executes the Python script by passing the incrementing counter as
an argument and extracting the output to a results table.

Add the analytic header

Add the appropriate analytic header tags at the beginning of the script so that the Analytics script can run on
AX Server after you import your analysis app:

COMMENT
//ANALYTIC Python integration test
verify Python integration on AX Server
//DATA py
//DATA results
//RESULT TABLE results
END

Add the script logic

SET SAFETY OFF
DEL ALL OK
CLOSE

OPEN py

GROUP
ASSIGN v_max = 11
ASSIGN v_counter = 1
LOOP WHILE v_counter < v_max
EXTRACT PYNUMERIC("lambda_example,myFunc",0,v_counter) AS "Results value" TO "res-
ults.fil"
v_counter = v_counter + 1
END
END
CLOSE py

Page 919 of 934

Appendix

The complete analytic script

The complete analytic that you run on AX Server looks as follows:

COMMENT
//ANALYTIC Python integration test
verify Python integration on AX Server
//DATA py
//DATA results
//RESULT TABLE results
END

SET SAFETY OFF

DEL ALL OK
CLOSE

OPEN py

Import the Analytics project

Once you have authored the analytic script:
1. In AX Client, create a collection and folder to house the Analytics project.
2. To import the project:
a. Right-click the folder you created and select Import.
b. Navigate to your Analytics project on your local computer, select the .acl project file, and then
click Open.
Note
Make sure you import the source data files to import the py table with your Ana-
lytics project.

Server explorer after import

Page 920 of 934

Appendix

l collectionName
l folderName

l Analysis Apps

l ACLProjectName

l analyticScriptName

l Data

l py

l Related Files

Run the analytic

From the Server Explorer of AX Client, right-click the analytic and select Run. The Python script is
executed as part of the analytic and you can access the results results table from AX Web Client.
Note
When the script runs, the Python executable looks for the script file in the PYTHONPATH
directory of the machine hosting AX Server. If your Analytics Exchange administrator has
not uploaded the file to this directory, the analytic fails.

Results
Server explorer after running the analytic
l collectionName
l folderName

l Analysis Apps

l ACLProjectName

l analyticScriptName

l Data

l py

l results

l Related Files

Results table
l Results value
l 1
l 4
l 9
l 16
l 25
l 36
l 49
l 64
l 81
l 100

Page 921 of 934

Appendix

Analytic engine error codes

The following table lists the error codes that you may encounter when running analytics.

Analytic engine startup errors

Error Code Description

202 System error.

203 The evaluation period has expired.

204 The evaluation period has expired.

205 Activation failed.

206 Maximum number of sessions reached.

207 Memory initialization problem(s).

209 Unknown script error.

210 Database profile password is missing.

211 Server connection failure.

212 An unsupported command was encountered.

213 A dialog box was generated by the script.

256 The AX Engine failed to start.

Analytic engine error codes

Error
Code Description

1000 No preference file was specified. A new default preference file was created.

1001 There is a problem with the preference file. A new default preference file was created.

1002 The project has been upgraded from an earlier version. A copy was saved with a .old extension.

Page 922 of 934

Appendix

Error
Code Description

1003 The project file could not be processed. The last saved project was used.

1004 No project file specified.

1005 The specified project file does not exist.

1006 The specified project file is read-only.

1007 The specified project is currently being used by another application.

1008 The specified .old project file cannot be used. You must specify a project file with the .ACL extension.

1009 The specified project file is not an Analytics project file.

1011 The specified project file cannot be saved as an earlier version.

1012 Unable to open the log file for writing.

1013 No script was specified.

1014 The specified script does not exist.

1015 The Analytics license was not found or is invalid.

1016 A required library file (.dll) was not found.

1017 An unknown error occurred.

Command errors
The following table lists the error codes that are returned when an analytic fails because of an invalid
ACLScript command. The error code number returned identifies the command that failed.

Error
Code Command

1 SAMPLE

2 EXTRACT

3 LIST

4 TOTAL

Page 923 of 934

Appendix

Error
Code Command

5 DEFINE

6 COMMENT

7 QUIT

8 STOP

9 BYE

10 USE

11 OPEN

12 SAVE

13 DISPLAY

14 ACTIVATE

15 CLOSE

16 HELP

17 COUNT

18 STATISTICS

19 HISTOGRAM

20 STRATIFY

21 SUMMARIZE

22 EXPLAIN

23 GROUP

24 ELSE

25 END

26 CANCEL

27 SUBMIT

Page 924 of 934

Appendix

Error
Code Command

28 DELETE

29 RANDOM

30 SORT

31 FIND

32 DIRECTORY

33 TYPE

34 DUMP

35 INDEX

37 SET

40 DO

41 TOP

42 EXPORT

43 VERIFY

44 SEEK

45 JOIN

46 MERGE

47 SEQUENCE

48 CALCULATE

49 PRINT

50 LOCATE

51 RENAME

54 COPY

55 REPORT

Page 925 of 934

Appendix

Error
Code Command

56 EJECT

58 LET

59 ACCUMULATE

63 ACCEPT

64 ASSIGN

65 AGE

66 CLASSIFY

67 PROFILE

68 DO REPORT

69 LOOP

70 PAUSE

71 SIZE

72 EVALUATE

73 DIALOG

74 IF

75 GAPS

76 DUPS

77 SQLOPEN

78 PASSWORD

79 IMPORT

80 REFRESH

81 NOTIFY

82 CONNECT

Page 926 of 934

Appendix

Error
Code Command

83 RETRIEVE

84 FIELDSHIFT

85 BENFORD

86 CROSSTAB

87 (not used)

88 ESCAPE

89 NOTES

90 FUZZY DUPLICATE

91 EXECUTE

Analytic job processing errors

Error
Code Error message

-10 The analytic results could not be saved because the destination results folder was deleted after the analytic
started running.

-11 Job was stopped.

-12 Stopped due to server shut down.

-13 Failed to create results.

-16 Could not run due to server properties configuration error.

-17 Unable to create uniquely named results directory.

-19 Job was skipped.

-20 Could not prepare publish result tables.

-21 Could not publish results to AX Exception.

-22 Publish failed. Invalid table name.

Page 927 of 934

Appendix

Error
Code Error message

-23 Publish failed. One or more of the table's column names are too long.

-24 Publish failed. Invalid values within data cells within an Analytics table.

-25 Publish failed. Not supported data types within table fields.

-26 Publish failed. Could not connect to AX Exception server.

-27 Job did not run. The user was removed or does not have permission.

-28 Job did not run. Unexpected error. See the server log and Analytics log for details.

-29 Could not copy data files. The analytic failed because the required data files could not be copied to the jobs
directory.

-30 Job did not run. The analytic link is broken.

-31 Publish failed. The exception mapping file could not be located.

-32 Publish failed. Failed to parse the exception mapping file.

-34 Failed to store job results. Check that there is sufficient space on the drive storing the jobs folder and that no
data files are locked.

Page 928 of 934

Appendix

Variables created by Analytics com-

mands
When you execute certain commands, either by entering information in dialog boxes in Analytics or by run-
ning scripts, system variables are automatically created by Analytics. You can use these variables, and the
values they contain, when processing subsequent Analytics commands.
The value in a system variable is replaced with an updated value if you execute the same command again.
"Analytics system variables" on the next page lists the system variables created by Analytics.
Note
System variables, and the values they contain, are retained for the duration of the current
Analytics session only.

Displaying the current value of variables

You can use any of the following methods to display the current values of all system-defined and user-
defined variables in an Analytics project:
l Select the Variables tab in the Navigator
l Enter DISPLAY VARIABLES in the command line

l Click Display Variables on the toolbar (requires that you first add the button to the toolbar)
The second and third methods also display the remaining memory available to store variables.

Incrementally numbered system variables

For system variable names that include n in "Analytics system variables" on the next page, n is always 1 if
commands are executed outside a group – for example, TOTAL1.
If you use a group to execute multiple commands, any system variables that result are numbered based on
the line number of the command that creates the variable. The first command in a group is considered to be
on line number 2.
For example:
l If the Total command is the third command in a group, the results are contained in the variable
TOTAL4.
l If a second Total command is the fifth command in the group, the results are contained in the variable
TOTAL6.

Page 929 of 934

Appendix

Analytics system variables

The following table lists the system variables created by Analytics, the commands that generate them, and
the values the variables contain.
Note
If you run the Statistics command on more than one field simultaneously, the system vari-
ables contain values for the first field you specify.

System variable Command Value

o Any command that out- o The number of records in the output table
puts a table o The number of data validity errors (Verify)
o Verify o The number of sequence errors (Sequence)
WRITEn o Sequence

o Any command that out- The path to the Analytics project folder in the Navigator that
puts an Analytics table contains the output table.
This a DOS-style path that uses the format /folder-
name/subfoldername, in which the initial slash (/) indicates the
root level in the Overview tab.
Tip
Use the SET FOLDER command to specify a dif-
ferent output folder or to create a new output
OUTPUTFOLDER folder.

o Count The number of records tallied.

COUNT n o Statistics

ACL_Ver_Major o Display Version The major version of Analytics that is currently running.
(Analytics version num-
ACL_Ver_Minor bers are in the format The minor version of Analytics that is currently running.
major.minor.patch)
ACL_Ver_Patch The patch version of Analytics that is currently running.

The edition of Analytics that is currently running:

o A value of '0' indicates the non-Unicode edition
ACL_Ver_Type o A value of '1' indicates the Unicode edition

o Evaluate Monetary unit sampling

Most Likely Error amount (projected misstatement)
Record sampling
Upper error limit frequency rate (computed upper deviation
MLEn rate)

Monetary unit sampling

UELn Upper Error Limit amount (upper misstatement limit)

Page 930 of 934

Appendix

System variable Command Value

o Execute The code returned by an external application or process run

using the Execute command.
Return codes are numbers generated by the external applic-
ation or process and sent back to Analytics to indicate the out-
come of the external process. Analytics does not generate the
return code.
Typical return codes are integer values that map to specific
notifications or error messages. For example, the return code
"0" could mean "The operation completed successfully". The
return code "2" could mean "The system cannot find the file
specified".
Specific return codes and their meanings vary depending on
the external application or process. Lists of return codes, also
called 'error codes' or 'exit codes', and their meanings, can
often be found in the documentation for the associated
external application. Lists of return codes can also be found on
the Internet.
The RETURN_CODE variable is created when the Execute
command is used synchronously, but not when the command
RETURN_CODE is used asynchronously.

o Gaps The total number of gaps, duplicates, or fuzzy duplicate

o Duplicates groups.
GAPDUPn o Fuzzy Duplicates

SAMPINT n o Size The required sample interval.

SAMPSIZEn The required sample size.

ABSn o Statistics The absolute value of the first specified field.

AVERAGEn The mean value of the first specified field.

The 5th highest value in the first specified field.

The 5th highest is the default setting. The setting can be
changed using the # of High/Low option in the Statistics dia-
log box.
Note
When Analytics identifies the highest value, duplic-
ate values are not factored out. For example, if val-
ues in descending order are 100, 100, 99, 98, the
HIGHn 3rd highest value is 99, not 98.

The 5th lowest value in the first specified field.

The 5th lowest is the default setting. The setting can be
changed using the # of High/Low option in the Statistics dia-
LOW n log box.

Page 931 of 934

Appendix

System variable Command Value

Note
When Analytics identifies the lowest value, duplic-
ate values are not factored out. For example, if val-
ues in ascending order are 1, 1, 2, 3, the 3rd
lowest value is 2, not 3.

MAXn The maximum value in the first specified field.

MEDIANn The median value in the first specified field.

MINn The minimum value in the first specified field.

MODEn The most frequently occurring value in the first specified field.

The first quartile value (lower quartile value) in the first spe-
Q25n cified field.

The third quartile value (upper quartile value) in the first spe-
Q75n cified field.

The difference between the maximum and minimum values in

RANGEn the first specified field.

STDDEVn The standard deviation of the first specified field.

o Total The sum total of the values in the first specified field.
TOTALn o Statistics

Other system variables

The following variables are system-generated but not created by commands:
l AXRunByUser – available in scripts running on AX Server, this variable stores the username of the
user running the analytic in the format "domain\username"
l OUTPUTFOLDER – the current Analytics project output folder

Page 932 of 934

Appendix

Reserved keywords
Analytics reserves certain keywords for special purposes. You cannot name fields or variables with these
reserved keyword values.
If you add a suffix to a reserved keyword, then you can use it as a field or variable name. For example, the
name "Field" is not permitted, but "Field_1" or "Field_2" are permitted.
Note
In some cases, you are also prevented from using abbreviations of the reserved keywords,
such as "Can" (CANCEL), "Form" (FORMAT), or "Rec" (RECORD).

Reserved Keyword Purpose in Analytics

ALL Refers to all previously defined fields.

AND The logical AND operator.

AS Assigns a display name to the output field or expression.

AXRunByUser A system variable that stores the username of the user running an analytic script on AX Server
in the format "domain\username".

CANCEL Cancels the current command.

D Specifies a descending sort order for the preceding expression or field name.

END Concludes the input stream and acts like a null line.

EXPR The prefix for the name of a default output field.

F Refers to the false value of a logical expression.

FIELD/FIELDS Part of the EXPORT, EXTRACT, JOIN, and SAMPLE commands.

FORMAT An older name for an Analytics table layout.

Cannot be used as a name for an Analytics table.

IF Specifies a condition.

LINE Used by the DEFINE COLUMN command to specify whether a field breaks over a specified
number of lines.

NODUPS Suppresses duplicate display values in the break field in an Analytics report.

NOT The logical NOT operator.

NOZEROS Displays or prints zero values in a numeric field or report as blank.

Page 933 of 934

Appendix

Reserved Keyword Purpose in Analytics

ON Precedes a field list.

OR The logical OR operator.

OTHER Indicates which fields or expressions to include, but not subtotal, in the output of the
SUMMARIZE command.

PAGE Used by the REPORT command to create page breaks.

PICTURE Specifies a format for a numeric field.

PRIMARY Specifies a certain type of join.

RECORD Refers to the entire input record as it exists.

RECORD_LENGTH Stores record-length values for use in record-processing operations.

SECONDARY Specifies a certain type of join.

SUPPRESS Suppresses the output of numeric totals.

T Refers to the true value of a logical expression.

TAPE Refers to an older method of accessing data with Analytics.

Cannot be used as a name for an Analytics table.

TO Designates an output file for any command.

WIDTH Changes the default print width of a specified field or expression.

Page 934 of 934

You Completed This Test On 25/03/2021, 06:36: ACDA Level 1
67% (3)
You Completed This Test On 25/03/2021, 06:36: ACDA Level 1
9 pages
Access Archived Data From ABAP
No ratings yet
Access Archived Data From ABAP
3 pages
Robot Programming: A Practical Guide to Behavior-Based Robotics
From Everand
Robot Programming: A Practical Guide to Behavior-Based Robotics
Joe Jones
4.5/5 (1)
Wrist Watch
100% (1)
Wrist Watch
54 pages
ACL101 Foundations 21-10-2022 - Trainer's
No ratings yet
ACL101 Foundations 21-10-2022 - Trainer's
119 pages
Fortianalyzer: SQL and Datasets (Supplementary Material)
No ratings yet
Fortianalyzer: SQL and Datasets (Supplementary Material)
34 pages
Airbus vs. Boeing Notes
No ratings yet
Airbus vs. Boeing Notes
4 pages
Of Mice Men Character Quotes
No ratings yet
Of Mice Men Character Quotes
1 page
Scripting Guide PDF
No ratings yet
Scripting Guide PDF
952 pages
Analytics Scripting PDF
No ratings yet
Analytics Scripting PDF
2,757 pages
Using ACL - Quick Guide
No ratings yet
Using ACL - Quick Guide
4 pages
ACL9 Getting Started Guide PDF PDF
No ratings yet
ACL9 Getting Started Guide PDF PDF
84 pages
ACL9 Getting Started Guide PDF
No ratings yet
ACL9 Getting Started Guide PDF
84 pages
Acl Exercises
50% (2)
Acl Exercises
50 pages
Acl Scripts 4 Beginners
No ratings yet
Acl Scripts 4 Beginners
10 pages
ACL Commands User Guide
No ratings yet
ACL Commands User Guide
62 pages
ChandraLearns To ACL
No ratings yet
ChandraLearns To ACL
25 pages
ChandraLearns To ACL
100% (2)
ChandraLearns To ACL
26 pages
ABAP Statements - Overview
No ratings yet
ABAP Statements - Overview
29 pages
Commonly Used ACL Commands
No ratings yet
Commonly Used ACL Commands
6 pages
Sort - Ice1cg50
No ratings yet
Sort - Ice1cg50
220 pages
This Study Resource Was: Tutorial 4
No ratings yet
This Study Resource Was: Tutorial 4
6 pages
01 WKBK PDF
No ratings yet
01 WKBK PDF
422 pages
Tutorial 01ACL
No ratings yet
Tutorial 01ACL
2 pages
ABAP All Statement
No ratings yet
ABAP All Statement
11 pages
Examine The Employee List: Points To Remember
No ratings yet
Examine The Employee List: Points To Remember
14 pages
PeopleSoft Application Engine Program PDF
No ratings yet
PeopleSoft Application Engine Program PDF
17 pages
Sap Abap On Hana
No ratings yet
Sap Abap On Hana
12 pages
Cdbflite
No ratings yet
Cdbflite
10 pages
QlikView Advanced Data Visualization Discover Deeper Insights with Qlikview by Building Your Own Rich Analytical Applications from Scratch 1st Edition Miguel Ángel García - Read the ebook now with the complete version and no limits
100% (2)
QlikView Advanced Data Visualization Discover Deeper Insights with Qlikview by Building Your Own Rich Analytical Applications from Scratch 1st Edition Miguel Ángel García - Read the ebook now with the complete version and no limits
71 pages
Tutorial 4
No ratings yet
Tutorial 4
6 pages
Analytics Scripting PDF
No ratings yet
Analytics Scripting PDF
2,765 pages
Introduction To Scripting Presentation
No ratings yet
Introduction To Scripting Presentation
20 pages
Fdocuments - in - Confidential Acl Functions Corporate Audit Services Technology Solutions Team
No ratings yet
Fdocuments - in - Confidential Acl Functions Corporate Audit Services Technology Solutions Team
28 pages
Sort
No ratings yet
Sort
204 pages
PDF QlikView Advanced Data Visualization Discover Deeper Insights with Qlikview by Building Your Own Rich Analytical Applications from Scratch 1st Edition Miguel Ángel García download
100% (2)
PDF QlikView Advanced Data Visualization Discover Deeper Insights with Qlikview by Building Your Own Rich Analytical Applications from Scratch 1st Edition Miguel Ángel García download
25 pages
ACL
No ratings yet
ACL
413 pages
Interview
No ratings yet
Interview
48 pages
WhoIsMrjQL - Copy (2)
No ratings yet
WhoIsMrjQL - Copy (2)
72 pages
DQL CheatSheet
No ratings yet
DQL CheatSheet
4 pages
4. SQL - 1688813695672
No ratings yet
4. SQL - 1688813695672
33 pages
Car Stereo Speaker Projects Illustrated
From Everand
Car Stereo Speaker Projects Illustrated
Daniel Ferguson
No ratings yet
rajni_ip_file_final
No ratings yet
rajni_ip_file_final
42 pages
QMF Document PDF
No ratings yet
QMF Document PDF
157 pages
DEFAULT Values: Chapter 1: Creating
No ratings yet
DEFAULT Values: Chapter 1: Creating
1 page
Quick Guide ACL
No ratings yet
Quick Guide ACL
19 pages
Tutorial No.: 4 Activity No.: 1 Topic: Computer-Aided Audit Tools - ACL 9 Table Name: Inventory
No ratings yet
Tutorial No.: 4 Activity No.: 1 Topic: Computer-Aided Audit Tools - ACL 9 Table Name: Inventory
9 pages
ACLExercises1 2015 Complete
No ratings yet
ACLExercises1 2015 Complete
14 pages
Portfolio - Ramadhan Khansa Akbari
No ratings yet
Portfolio - Ramadhan Khansa Akbari
39 pages
Item Description Prefix Example: Filter
No ratings yet
Item Description Prefix Example: Filter
2 pages
Commands and Function
No ratings yet
Commands and Function
31 pages
Important Topics Summary
No ratings yet
Important Topics Summary
39 pages
Lecture 04- Xii -Data Farme
No ratings yet
Lecture 04- Xii -Data Farme
9 pages
Cognos 8 Bi - Data Manager - Function and Scripting Reference Guide
100% (1)
Cognos 8 Bi - Data Manager - Function and Scripting Reference Guide
134 pages
I 4 Glbyeg
100% (2)
I 4 Glbyeg
734 pages
Focus Funda11
No ratings yet
Focus Funda11
100 pages
Excel Formulasx
No ratings yet
Excel Formulasx
201 pages
List of ABAP Keywords
No ratings yet
List of ABAP Keywords
14 pages
08_Prajwal_Dikshit_ADBMS_RUBRICS
No ratings yet
08_Prajwal_Dikshit_ADBMS_RUBRICS
63 pages
SQLDEV320A WEEK4-1
No ratings yet
SQLDEV320A WEEK4-1
30 pages
Build Your Own Printed Circuit Board
From Everand
Build Your Own Printed Circuit Board
Al Williams
2/5 (2)
Anatomy of a Robot
From Everand
Anatomy of a Robot
Charles Bergren
2.5/5 (1)
The Complete Rigger's Apprentice: Tools and Techniques for Modern and Traditional Rigging
From Everand
The Complete Rigger's Apprentice: Tools and Techniques for Modern and Traditional Rigging
Brion Toss
No ratings yet
Mahindra Parts Catalog
71% (7)
Mahindra Parts Catalog
909 pages
Projective Techniques FGI
No ratings yet
Projective Techniques FGI
73 pages
Lactic Acid MSDS
No ratings yet
Lactic Acid MSDS
14 pages
111111
No ratings yet
111111
4 pages
Advanced Administration Guide: General Parallel File System
No ratings yet
Advanced Administration Guide: General Parallel File System
164 pages
Junior Assistant in Telangana State Road Transport Corporation
No ratings yet
Junior Assistant in Telangana State Road Transport Corporation
23 pages
On Characterizations of NANO RGB-Closed Sets in NANO Topological Spaces
No ratings yet
On Characterizations of NANO RGB-Closed Sets in NANO Topological Spaces
9 pages
Proof: Euler S Theorem
No ratings yet
Proof: Euler S Theorem
20 pages
Wireless Energy Meter Reading Using RF Technology
100% (1)
Wireless Energy Meter Reading Using RF Technology
26 pages
SDN PDF
No ratings yet
SDN PDF
2 pages
AF2602 Course Outline Sem 1 2021-2022
No ratings yet
AF2602 Course Outline Sem 1 2021-2022
12 pages
1.3 Patients Assessment Policy
0% (1)
1.3 Patients Assessment Policy
6 pages
Teenage Pregnancy Factors On Completion Rate of Female Students in Public Secondary Schools in Nyamasheke District Rwanda
No ratings yet
Teenage Pregnancy Factors On Completion Rate of Female Students in Public Secondary Schools in Nyamasheke District Rwanda
18 pages
CED Assignment 2&3
No ratings yet
CED Assignment 2&3
4 pages
New Disney
No ratings yet
New Disney
3 pages
Autolab Manual
100% (1)
Autolab Manual
327 pages
Decision Making Swallow-Hard Decisions
No ratings yet
Decision Making Swallow-Hard Decisions
5 pages
Biomass - A Renewable Energy Source
No ratings yet
Biomass - A Renewable Energy Source
311 pages
Positive and Negative Feedback PDF
No ratings yet
Positive and Negative Feedback PDF
3 pages
Abdullah Infrared Radiation
No ratings yet
Abdullah Infrared Radiation
24 pages
Mobile Email Database of Doctors Sample
No ratings yet
Mobile Email Database of Doctors Sample
11 pages
Mime Summative Scene
No ratings yet
Mime Summative Scene
2 pages
CLIMDEX: Climate Extremes Indices
No ratings yet
CLIMDEX: Climate Extremes Indices
5 pages
Active Voice
No ratings yet
Active Voice
9 pages
New Method Four Point Bending Matlab
No ratings yet
New Method Four Point Bending Matlab
4 pages
0.1 Differential Operator: D DX D DX 2
No ratings yet
0.1 Differential Operator: D DX D DX 2
16 pages
On Indian Railway Gorakhpur
No ratings yet
On Indian Railway Gorakhpur
20 pages