PARAM

The PARAM tag creates input parameters for an analytic, and defines the requirements for parameter values (analytic input values). Input parameters use variables to pass input values to the analytic so that users can specify different actual values when they run or schedule the analytic. For example, you could create Start Date and End Date input parameters to allow users to set a date range to limit the data the analytic is processing.

You can also use the PARAM tag to allow users to select a non-ACL input file for an analytic.

Syntax

//PARAM id type <OPTIONAL> <MULTI> <SEPARATOR value> <QUALIFIER value>
  <VALUES value_list> label
  <description>
id

Specifies the variable that stores the analytic input value(s) selected or specified by the user. For example, v_start_date, v_regions, or v_input_file. Also serves as the unique identifier for the parameter.

When an analytic is run, the parameter variable is created only if the user provides an input value. If a parameter is optional, and the user skips it, the variable is not created. If the subsequent logic of the analytic requires the variable to exist, you can test for its existence, and if it does not exist, create it and initialize it to null. For more information, see the “Remarks” and Example “f” below.

type

Specifies the data type of the parameter, which controls what sort of input values can be entered. Can also specify that a file upload utility, or a Windows file browser, opens. The following types can be specified using uppercase letters:

  • C – Values that use the Character data type can be entered.

  • N – Values that use the Numeric data type can be entered.

  • D – Values that use the Date subtype of the Datetime data type can be entered.

  • DT – Values that use the Datetime subtype of the Datetime data type can be entered.

  • T – Values that use the Time subtype of the Datetime data type can be entered.

  • L – Values that use the Logical data type can be entered.

  • F – (For analytics run in AX Web Client or the Analysis App window only.) Opens a file upload utility, or a Windows file browser, and allows a user to select a non-ACL input file for the analytic. Upon selection, the file name is automatically entered as a Character input value. Specify ‘F’ only. Do not specify ‘F C’. For more information, see the “Remarks” and Example “g” below.

Note

A type of ‘F’ is not supported for use in analytics run in AX Client. To specify an input file for analytics run in AX Client, use the FILE tag. For more information, see FILE.

OPTIONAL

Optional. Specifies that the parameter is optional and the user does not need to enter an input value.

MULTI

Optional. Specifies that the parameter accepts multiple input values. The MULTI option can be used with or without the VALUES option:

  • If you specify both MULTI and VALUES, the user can select one or more values from a checklist of values.

  • If you specify MULTI without VALUES, the user can manually enter one or more values. For example: 5812 5813 5814

MULTI can be specified for all data types and subtypes (C, N, D, DT, T) except the Logical (L) data type.

If you specify MULTI, and the 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. Delimiting and qualifying character input values is required for an analytic to run successfully.

SEPARATOR value

Optional. Specifies that a separator character is automatically inserted between multiple character input values, creating a delimited list that is passed to the analytic for processing. The value specifies the separator character to use. A commonly used separator, or delimiter, is the comma (,).

SEPARATOR can be used only when the type is ‘C’ (Character) and the MULTI option is specified, either with or without the VALUES option.

If SEPARATOR is not specified, a single space is used as the separator by default. The space character cannot be specified as the value for SEPARATOR in the command syntax, so if you want to use the space character as the separator omit the SEPARATOR parameter.

QUALIFIER value
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.

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 processing. Any text enclosed within the qualifier characters is treated as text. The value specifies the qualifier character to use. A commonly used qualifier is the single quotation mark (').

QUALIFIER can be used only when the type is ‘C’ (Character) and the MULTI option is specified, either with or without the VALUES option.

If QUALIFIER is not specified, there is no default value. The space character cannot be specified as the value for QUALIFIER in the command syntax.

VALUES value_list

Optional. Specifies a checklist of input values the user can select from when running the analytic. Use the following syntax to specify the values:

VALUES |Value1|Value2|Value3|Value n|

The VALUES option can be used with or without the MULTI option:

  • If you specify both VALUES and MULTI, the user can select one or more values from a checklist of values.

  • If you specify VALUES without MULTI, the user can select a single value from a drop-down list of values.

VALUES can be specified for all data types and subtypes (C, N, D, DT, T) except the Logical (L) data type.

Character values in a value_list can contain spaces and punctuation. A numeric, date, datetime, or time value_list must be specified using the following formats:

  • Numeric values can be positive or negative. They must be specified using decimal notation, and without a thousands separator. For example, 1500.00 or -1500.00

  • Date values must be specified using the format MM/DD/YYYY (for example, 12/31/2014)

  • Datetime values must be specified using the format MM/DD/YYYY hh:mm:ss (for example, 12/31/2014 23:59:59)

  • Time values must be specified using the format hh:mm:ss (for example, 23:59:59)

label

Specifies the user interface label to associate with the parameter. The label value is displayed in AX Client, AX Web Client, or the Analysis App window when the user is prompted to enter or select an input value for the parameter.

description

Optional. Descriptive text that specifies the purpose of the parameter. The description value is displayed in AX Client, AX Web Client, or the Analysis App window when the user is prompted to enter or select an input value for the parameter. The text can include instructions that assist the user. For example, “Enter the cutoff date for the payroll period”. The 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 in the AX Client, AX Web Client, or the Analysis App window user interfaces.

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. If the user specifies an input value, the parameter variable is automatically created. However, if the user skips the optional parameter and does not specify an input value, the parameter variable is not created.

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, and if it does not exist, create it and initialize it to null. You can use either the FTYPE( ) function or the ISDEFINED( ) function to perform the test:

Perform the test after the analytic header and before any ACLscript logic that depends on the existence of the parameter variable. See Example “f” below.

Summary of the MULTI and VALUES options

Table 1 summarizes the effect of the MULTI and VALUES options on the requirements and design of the input parameter.

Table 1. The effect of the MULTI and VALUES options

Input parameter requirements and design

uses MULTI

uses VALUES

A single input value manually entered in a field

No

No

A single input value selected from a drop-down list of values

No

Yes

One or more input values manually entered in a field

Yes

No

One or more input values selected from a checklist of values

Yes

Yes

Delimiting and qualifying character input values

Character input values must be delimited by a separator if there is more than one value, and values must be qualified, for an analytic to run successfully.

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 (qualifiers within qualifiers). Redundant text qualifiers will cause the input parameter to malfunction.

There are four different methods for inserting text qualifiers around character input values (listed below). You must ensure that the input parameter you design uses only one of these methods. Depending on the method, a separator is also inserted between the input values. One or more of the methods may not be applicable, depending on how you are using the MULTI and VALUES options.

Methods for inserting text qualifiers (use only one per parameter):

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 ACL script.

Table 2 summarizes when to use the different methods for inserting text qualifiers.

Table 2. Methods for inserting text qualifiers

MULTI without VALUES

VALUES without MULTI

Both MULTI and VALUES

Method 1

Use the SEPARATOR and QUALIFIER options

If used, do not use Method 2

Not applicable

If used, do not use Method 3

Method 2

Manually specify separators and qualifiers

If used, do not use Method 1

Not applicable

Not applicable

Method 3

Include qualifiers in the value_list

Not applicable

If used, do not use Method 4

If used, do not use Method 1

Method 4

Enclose the parameter variable in qualifiers

Do not use

If used, do not use Method 3

Do not use

Specifying or selecting a non-ACL input file for an analytic

Table 3 summarizes the different methods for specifying or selecting a non-ACL input file for an analytic. The method you choose is partly dependent on which application will be used to run the analytic: AX Client, AX Web Client, or the Analysis App window.

Table 3. Methods for specifying or selecting a non-ACL input file

Method

Details

AX Client

AX Web Client

The Analysis App window

PARAM tag with type of ‘F’

(example “g” below)

The user selects the input file using a file upload utility (AX Web Client), or the Windows file browser (the Analysis App window).

This method is the best option because it combines flexibility, ease of use, and precision. A value consisting of the file name (AX Web Client), or the file path and the file name (the Analysis App window), is automatically entered.

In AX Web Client this method also automatically uploads the selected file to the appropriate Related Files subfolder on AX Server.

not supported

supported

PARAM tag with type of ‘C’

(example “h” below)

The user manually specifies an input file path and file name as an analytic input value.

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.

not supported

supported

FILE tag

(For more information, see FILE.)

The input file must be located in the appropriate Related Files subfolder on the AX Server.

supported

not supported

Input file path and file name hard-coded in the analytic

(example “i” below)

This method avoids use of the PARAM tag, however it is the least flexible. On every computer where the analytic is run, the user must ensure that the input file has a file path and a file name identical to those specified in the analytic.

not supported

supported

Examples

The following examples show a variety of input parameter definitions.

Some of the examples include associated lines from an ACL analytic that demonstrate how the input values, contained in the parameter variable, can be used to control the behavior of the analytic.

a. Allow 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

b. Require the user to specify an amount range

//PARAM v_min_amount N Minimum Amount
  Enter a minimum amount
//PARAM v_max_amount N Maximum Amount
  Enter a maximum amount

Associated line in an analytic:

CLASSIFY ON %v_FieldA% IF BETWEEN(AMOUNT, v_min_amount, v_max_amount)
SUBTOTAL AMOUNT TO "Classified_%v_AnalysisTable%.FIL"

c. Require the user to select a maximum number of transactions to process

//PARAM v_maxTrans N VALUES |250|500|750|1000| Maximum transactions to process

d. Require the user to specify one or more merchant category codes

//PARAM v_codes C MULTI SEPARATOR , QUALIFIER ' MC Code(s) 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.

e. Require 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 Code(s) to include
  Select one or more merchant category codes.

f. Allow the user to optionally exclude one or more customer numbers

//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.

Associated lines in an analytic:

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

g. Allow the user to select an input file (AX Web Client or the Analysis App window only)

//PARAM v_input_file F Input File
  Select an input file

Associated lines in an analytic:

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "%v_input_file%" TABLE
"Trans2_May$" CHARMAX 100 KEEPTITLE

h. Require the user to specify an input file path and file name (the Analysis App window only)

//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

Associated lines in an analytic:

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM "%v_input_file%" TABLE
"Trans2_May$" CHARMAX 100 KEEPTITLE

i. Hard-code an input file path and file name (no user input required) (the Analysis App window only)

Associated lines in an analytic:

IMPORT EXCEL TO Trans_May_raw Trans_May_raw.fil FROM
"C:\Users\username\Documents\ACL Data\Sample Data Files\Trans_May.xls"
TABLE "Trans2_May$" CHARMAX 100 KEEPTITLE


(C) 2015 ACL Services Ltd. All Rights Reserved.