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

:READ

Script Statement: Queries the userIn the Automation Engine, a user is an instance of a User object, and generally the user is a specific person who works with Automic products. The User object is assigned a user ID and then a set of access rights to various parts of the Automation Engine system and product suite. These access rights come in the form of Automation Engine authorizations and privileges, Decision user roles and EventBase rights and ARA web application object rights. You can manage all these centrally in the ECC user management functions. See also, Unified user management. 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 variableA placeholder for a value within a script.

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: scriptA particular Automation Engine object type. literal or script variable.
Default value: "Please enter value for variableIt stores or retrieves values dynamically at runtime. An individual Automation Engine object type. 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 objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task 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 listShows entities in a grid view 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 functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,… 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 reportA report provides more detailed information about a task's execution or a component. automatically logs the values that were entered in the dialog boxes. This function can also be deactivated for jobAn Automation Engine object type for a process that runs on a target system. 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 runtimeThe duration of a task's execution. It refers to the period between a task's start and end. It does not include its activation period (see also: activation and start)."), 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"

See also:

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

Script Elements - Activate Objects

Sample Collection:
Database Maintenance with Options

About Scripts
Script Elements - Alphabetical Listing

Script Elements - Ordered by Function

 


Automic Documentation - Tutorials - Automic Blog - Resources - Training & Services - Automic YouTube Channel - Download Center - Support

Copyright © 2016 Automic Software GmbH