DIALOG command
Concept Information
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 instead.
The DIALOG command is not supported in AX Server analytics.
You can create a basic interactive dialog box with the ACCEPT command.
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_syntax]|[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>)
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 "&OK;&Cancel" |
The labels for the OK and Cancel buttons in the dialog box. 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:
|
| 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 optional |
Displays the values for the BUTTONSET control horizontally. Values are displayed vertically by default. |
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.
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 optional |
The alignment of the text in the control. 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 optional |
The default text string to display in the control. 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. |
| 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 optional |
Sets the control to checked by default. |
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 optional |
The numeric value that corresponds to the list item that you want to select as the default. For example, if value_list is "Red;Green;Blue", specify DEFAULT 2 to select Green by default. |
| HORZ optional |
Displays the values for the control horizontally. Values are displayed vertically by default. |
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 exist, it is created, and the specified value is assigned. |
| DEFAULT item_num optional |
The numeric value that corresponds to the list item that you want to select as the default. For example, if value_list is "Red;Green;Blue", specify DEFAULT 2 to select Green by default when the drop-down list is displayed. |
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_category |
The category of project item to include in the control. You can specify one or more categories. The user can select a single value from the project 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. 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 optional |
The exact name of the project item that you want to select as the default. 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:
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 "Metaphor_Inventory_2012" ) (TEXT TITLE "Script:" AT 230 50 ) (ITEM TITLE "b" TO "v_script" AT 230 70 )
Additional examples
For additional DIALOG examples, see Example script: filter records by date, and group filtered records by month.
Remarks
For more information about how this command works, see Creating custom dialog boxes.
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:
- text box
- project item list
For basic interactivity, ACCEPT may be all you need. For more information, see ACCEPT command.
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 |
|
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%))
In the example, the start and end dates for this filter are stored as character values. They must be converted 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 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.
