Automation Engine Script Guide > Ordered by Function > Activate Objects > :READ

:READ

Script Statement: Queries the user in a dialog

Syntax

:REA[D] InVariable, [Input Check], [Message Text], [Default Value], [Input Handling]

Syntax	Description/Format
InVariable	User input is stored here Format: script variable
Input Check	Term that determines how the user input should be checked Format: cript literal or script variable The following characters are possible: "00" No input check (default value) "01" to "99" The maximal number of characters of the entered value has to correspond to this number (e.g. "10"). "min. number - max. number" The entered number must be within this specified range (e.g."10-20"). Date Format The indicated value has to correspond to the specified date format (e.g. YYYYMMDD). Value, Value1 - Value2 The entered value has to be equal to a defined value or be in a certain range of values. Values and ranges of values can be freely combined (separated through commas).
Message Text	Text that is displayed and requests the user to make an entry Format: script literal or script variable. Default value: "Please enter value for variable Variable name"
Default Value	Suggested default value that is displayed in the input field Format: script literal or script variable. Maximum 1024 characters You cannot pass an empty string for the default value. You must enclose a space character in quotes.
Input Handling	Options for specifying input handling. You can supply multiple options in any order (e.g. "MN"). Format: script literal or script variable. The following options are valid: "C" If the READ statement is used within a :BEGINREAD... :ENDREADblock, the cursor is placed in this input field. "D" Secured input. Characters are displayed as asterisks (). "I" (only for jobs) :READ statements and user inputs are generally documented in the generated Job object in the form of REMARK Lines. By specifying the option "I", this documentation will be suppressed. "K" The input can be written in lower-case letters. If this option is not used, the input is automatically written in upper-case letters. The "K" option is only available for user interface inputs and does not affect the read buffer. "M" The field must not be left blank. "N" Only numerical characters can be entered. "O" The user can select an entry from the list selection or make individual entries. "D" and "N" cannot be used together. Use the parameter Input Check for protected entries that should only contain numbers. Example: :READ &PASS#,"1-99999999","Enter password (numerical)",,"DM" Note that you must set a comma if you use Input Check* without indicating a Default Value. See example above.

Comments

The :READ statement displays a dialog whose appearance and function depend on the given parameters. The object name is displayed in the headline. The user input can be specified in an entry field and memorized in a script variable.

This dialog is only displayed when the script runs in dialog mode. Otherwise, the default values are used.

When using this script element, make sure that the specified value is compatible with the data type of the "InVariable" (target variable).

The parameters Input Check, Message Text, Default Value and Input Handling are optional. The relevant commas must always be inserted, regardless of the parameters Input Check and Message Text in the :READ statement.

Field	Description
Number field	If you use a continuous numerical range of values (e.g. "0-255") with the entry format "N" in the Input Check, a number field with arrows (up/down) is displayed.
List selection	If the parameter Input Check contains a fixed set of values, i.e. A,B,C, these values are then displayed in a list box.
Text field	If the parameter contains ranges (i.e. A, 5-9) an input field is created.

Specify commas and hyphens with single quotations if they should not be read as separators. Example: Either value '1-5' or value '8,9' can be selected.

:READ &OPTION#,"'1-5','8,9'",'Please select','1-5'

You can either use letters, numbers or a combination of both for the input check. In a combination of letters and numbers, the number of characters are checked. Inputs must then be structured as shown below. The example permits the entries "A" to "F" and "1" to "999":

:READ &INPUT#, "A-F,1-9,01-99,001-999","Please select"

A blank (" ") is stored in the script variable if the user does not enter or select a value!

The report automatically logs the values that were entered in the dialog boxes. This function can also be deactivated for job reports with the parameter "I". Note that protected entries (usually passwords) that were defined with the parameter "D" appear encrypted in the report.

With a :READ statement, values that have been put to the input buffer can be read (see:PUT_READ_BUFFER).

The script statement causes all open transactions of the script to be written to the AE databaseA database is an organized collection of data including relevant data structures..

The following particularity appears when :PUT_VAR is used before a :READ statement:
If the script generation of :READ is canceled manually via the "Cancel" button or due to invalid default values (see "Generate at runtime"), the variable object still contains the values that were set with :PUT_VAR.

Examples

In querying the user for a headline - the input is not checked. It is also possible to leave the field blank. The characters are immediately converted to upper-case letters.

:READ &HEADLINE#,"00","Please enter headline"

In querying the user for a headline: a default value is not specified, the input is not checked, however, entering lower-case letters is possible.

:READ &HEADLINE#,,,,"K"

In querying a number: In this case, the parameter "N" generates a number field with arrows. Only numbers ranging from 0 - 5 are accepted.

:READ &NUMBER#,"0-5","Please enter number",,"N"

In querying the user for a date: The input has to be a valid date in the format "YYMMDD". You cannot leave the field blank.

:READ &DATE1#,"YYMMDD","Please specify a date (YYMMDD)",,"M"

In querying the user for a signature. The entry field obtains the default value "A". The input value will be checked as it can only contain "A", "X", "5", "6", "7", "8" or "9".

:READ &LKZ#,"A,X,5-9","Please enter List Signature","A"

Requests the user to enter a passwordA secret combination of characters for a Automation Engine user. with a maximum of 8 characters. The parameter Input Handling defines the input as "secured" so that it is not converted to upper case and cannot be left blank.

:READ &PASS#,"08","Please enter password (max. 8 characters)",,"DMK"

In the example, the email address is requested. The user can select from a range of three email addresses. In order to avoid the hyphens being interpreted as a range of values, one address is set in single quotations.

:READ &USER#,"brown@automic.us,johnson@automic.us,'smith@late-night.com'", "Please select user"

The following example shows that the user can select from among three email addresses and that he can also enter a new one.

:READ &USER#,"brown@automic.us,johnson@automic.us,'smith@late-night.com'", "Please select user",,"O"

Script element	Description
:BEGINREAD... :ENDREAD	They are used to define the beginning and end of a dialog box for user queries
:PRINT	This is used to write text to a dialog for user queries or to the activation protocol of an object
:PUT_READ_BUFFER	Puts the name and content of a script variable in the input buffer