Dialog - Input

Declaration

<AMSHOWDIALOG ACTIVITY="input" MESSAGE="text" DEFAULTVALUE="text" 
RESULTVARIABLE="text" WINDOWTITLE="text" MAXLENGTH="number" 
XPOS="number" YPOS="number" ICON="text options)" 
DEFAULTBUTTON="number (options)" ONCANCEL="text (options)" 
ONCANCELTASK="text" COUNTDOWNDELAY="number" 
MEASURE="text (options)" MASKINPUT="YES/NO" />

Description: Displays an input dialog allowing the user to enter a specific text value during runtime. The value is saved to the variable specified. Execution is paused while the task waits for a value to be entered. A default value can be specified in case no value is entered.

Practical Usage

Useful for asking a question that requires a text response at runtime. Can be used to make decisions during task execution. For example, if value 1 is entered, continue to the next step; if value 2 is entered, end the task.

General Parameters

Property	Type	Required	Default	Markup	Description
Message to display	Text	Yes	(Empty)	MESSAGETEXT="What's your answer to the question?"	The text message to be displayed in the input box during runtime. This is usually a question that the user should input an answer to.
Default value	Text	No	(Empty)	DEFAULTVALUE="theValue"	The default text value that should appear in the input box. This parameter is optional.
Maximum length of string	Number	No	Disabled	MAXLENGTH="30"	If enabled, specifies the maximum characters the user can enter in the input box. This prevents users from entering invalid data (such as entering more than 5 digits in a zip code field).
Populate variable with value entered	Text	No	(Empty)	RESULTVARIABLE="varname"	The name of an existing variable to be populated with the text that the user entered as a response to the message.
Mask input	Yes/No	No	No	MASKINPUT="YES"	If set to YES, allows the text being entered in the input box to be masked in real-time (e.g., ######). This is useful if the user is entering a password or other sensitive data. This parameter is set to NO by default.
Title of message box	Text	No	(Empty)	WINDOWTITLE="QUESTION"	The title that should appear in the title bar of the input box.
Bring dialog to front	Yes/No	No	Yes	WINDOWINFRONT="NO"	If set to YES, specifies that the input box will appear in front of all other open windows. This parameter is set to YES by default.

Buttons Parameters

Property	Type	Required	Default	Markup	Description
Button selected by default	Number	No	0	DEFAULTBUTTON="0" DEFAULTBUTTON="1"	The number associated with the button that should be automatically selected if no user interaction is applied within the time limit specified in the Automatically select the default button after parameter. The OK button correlates with "0" and the Cancel button correlates with "1". Setting a default button allows task execution to continue in case no user interaction occurs. The default value is "0".
On cancel	Text (Options)	No	Stop	ONCANCEL="continue" ONCANCEL="stop" ONCANCEL="fail" ONCANCEL="start_task" ONCANCEL="set_variable"	Specifies how this activity should react if the Cancel button is selected . The available options are: Continue - The task will continue to the next step. Stop (default) - The task will stop. No error is generated. Fail - The task will fail with an error. Start a task - Another task will start. Set a variable - The specified variable will be set to a particular value.
Task to start	Text	Yes if set to start a task on cancel	(Empty)	ONCANCELTASK="task_name"	The path and file name of the task (.aml) file to start if the Cancel button is selected. Click the folder icon to navigate to the desired task file or enter the path and file name manually in the provided text box. This parameter is available only if the On cancel parameter is set to Start a task.
Variable name	Text	Yes if set variable on cancel	(Empty)	ONCANCELVARNAME="var1"	The name of the variable whose value to set. This parameter is available only of the On cancel parameter is set to Set a variable.
Variable value	Text	Yes if set variable on cancel	(Empty)	ONCANCELVARVALUE="value"	The value to set the variable to. This parameter is available only of the On cancel parameter is set to Set a variable.
Automatically select the default button after	Number	No	Disabled	COUNTDOWNDELAY="10"	If enabled, specifies the amount (numeric value) of time that should elapse before the default button is selected as specified in the Button selected by default parameter. If this parameter is disabled, the input box is displayed indefinitely. This parameter is disabled by default.
Measure	Text (Options)	No	Seconds	MEASURE="milliseconds" MEASURE="seconds" MEASURE="minutes" MEASURE="hours"	Denotes the time measurement to associate with the value entered in the Automatically select the default button after parameter. The available options are: Milliseconds - Time measurement is set to milliseconds. Seconds (Default) - Time measurement is set to seconds. Minutes - Time measurement is set to minutes. Hours - Time measurement is set to hours.
Populate variable with value entered	Text	No	(Empty)	RESULTVARIABLE="varname"	The name of an existing variable to be populated with the text that the user entered as a response to the message.
Mask input	Yes/No	No	No	MASKINPUT="YES"	If set to YES, allows the text being entered in the input box to be masked in real-time. This is useful when the user is entering a password or other sensitive data.
Title of message box	Text	No	(Empty)	WINDOWTITLE="QUESTION"	The title that should appear in the title bar of the input box.
Bring dialog to front	Yes/No	No	Yes	WINDOWINFRONT="NO"	If set to YES, specifies that the input box will appear in front of all other open windows. This parameter is set to YES by default.

Advanced Parameters

Property	Type	Required	Default	Markup	Description
Position	Text (Options)	No	Center of screen	POSITION="center" POSITION="upper_left" POSITION="lower_left" POSITION="upper_right" POSITION="lower_left" POSITION="custom"	The screen position in which to display the input dialog. The available options are: Center of screen (default) - The input dialog will be displayed at the center of the screen. Upper left corner of screen - The input dialog will be displayed at the upper left of the screen. Lower left corner of screen - The input dialog will be displayed at the lower left of the screen. Upper right corner of screen - The input dialog will be displayed at the upper right of the screen. Lower right corner of screen - The input dialog will be displayed at the lower right of the screen. Custom location - The input dialog will be displayed at the specified X,Y coordinates.
Window coordinates (X)	Number	Yes if position is set to custom location	(Empty)	XPOS="55"	The X (horizontal) coordinates of the position that the upper left corner of the input dialog should be displayed on the screen. To capture X coordinates using your mouse, enable the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location.
Window coordinates (Y)	Number	Yes if position is set to custom location	(Empty)	YPOS="55"	The Y (vertical) coordinates of the position that the upper left corner of the input box should be displayed on the screen. To capture Y coordinates using your mouse, enable the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location.
Dialog title icon	Text (Options)	No	(Empty)	ICON="none" ICON="information" ICON="exclamation" ICON="question" ICON="stop"	Specifies the icon that should be displayed next to the title. This helps to determine what type of message is being displayed. The available options are: None (default) - No icon is displayed. Information - An information icon is displayed. Exclamation point: An exclamation point icon is displayed. Question : A question mark icon is displayed. Stop - A stop sign icon is displayed.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Examples

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Example 1: A simple task that saves the text entered in an input box to a variable and later displays it in a message box.

<AMVARIABLE NAME="textEntered"></AMVARIABLE>
<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="textEntered" 
WINDOWTITLE="ENTER TEXT">Please enter some text here.</AMSHOWDIALOG>
<AMSHOWDIALOG WINDOWTITLE="TEXT ENTERED">The 
text that was entered: %textEntered%</AMSHOWDIALOG>

Example 2: A more complex task that demonstrates use of the Input Dialog and Message Dialog. Also demonstrates use of variables, BASIC Script, IF/End if activities and expressions.

<AMVARIABLE NAME="theanswer" DESCRIPTION=""></AMVARIABLE>
<AMSCRIPT>Function SquareNumber(thenum)
SquareNumber = thenum * thenum
End Function</AMSCRIPT>
<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="theanswer">What 
number would you like to square?</AMSHOWDIALOG>
<AMIF EXPRESSION="IsNumeric(theanswer) = true">
<AMSHOWDIALOG>The number %theanswer% squared  is %SquareNumber(theanswer)%</AMSHOWDIALOG>
<AMELSE />
<AMSHOWDIALOG>The text "%theanswer%" is not a valid number. Please re-run 
and enter a valid number.</AMSHOWDIALOG>
</AMIF>

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
v10 | 202212080228 | December 2022