:READ

Use the :READ script statement when you want retrieve data from the read buffer. The read buffer stores variables to make the values available for further processing. The function of the :READ statement depends on the context in which you use this script statement.

Important! Do not use text values with line breaks in the read buffer. :READ ignores the characters after the first line break.

Reading Variables in the Read Buffer

Use the :READ statement to retrieve the following data from the read buffer:

• Values that are stored when you start an object with ACTIVATE_UC_OBJECT
  For more information, see :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER
• UC_CAUSE* variables that are stored in the read buffer
  For more information, see List of Predefined Read Buffer Variables.

To Read Data Stored in the Read Buffer

Store a script variable in the read buffer with a :PUT_READ_BUFFER statement. Activate an object with the ACTIVATE_UC_OBJECT function. Retrieve the value of the variable that you stored in the read buffer with a :READ statement. Each script variable in the buffer can only be read once. The variable is deleted from the buffer after reading..

Example

The following example stores the name of the agent of a Job in the read buffer, and activates a Notification object.

:SET &att_host# = GET_ATT(HOST)
:PUT_READ_BUFFER host# = '&att_host#'

:SET &ret# = ACTIVATE_UC_OBJECT('CALLOP')

In the Notification object, the following script retrieves the agent name stored by the previous script:

:READ &host#,,

:PRINT "Agent: &host#"

The following example is a script in a Notification object. The script reads UC_CAUSE* variables to retrieve the details of the task that activated the Notification. The script prints the details of task in the activation report:

:READ &UC_CAUSE_NAME,,
:READ &UC_CAUSE_NR,,
:READ &UC_CAUSE_STATE,,
:READ &UC_CAUSE_RETCODE,,

:PRINT "This notification was triggered by the following task:"
:PRINT "Name: &UC_CAUSE_NAME"
:PRINT "RunID: &UC_CAUSE_NR"
:PRINT "Status: &UC_CAUSE_STATE"
:PRINT "Return code: &UC_CAUSE_RETCODE"

:READ User Dialogs

Write the :READ statement between a :BEGINREAD and :ENDREAD statement to trigger a request and display it in the Requests view for user input. The data the user enters is stored in variables and can be used for further processing. For more information, see Requests.

:READ statements only trigger a request if one if the following is true:

• You have selected the Generate Task at: Activation time option on the Attributes page of the object. For more information, see Generating at Activation or at Runtime.
• You activate the task manually.

:READ statements do not trigger a request in the following situations, and the default values are used instead:

• You have selected the Generate Task at: Runtime option on the Attributes page of the object.
• You have selected the Generate Task at: Runtime option for the Workflow in which the object runs.
• The task runs in a Schedule.
• The task is activated using a script function such as ACTIVATE_UC_OBJECT.
• A CallAPI starts the task.
• The task is activated via an object setting (for example, in the Postcondition tab of a task in a Workflow).
• The task runs in a group which serves as a queue.

Tip: Use the GET_ATT script function with the DCMODUS attribute to determine whether a script is running in a mode that will permit the Requests view to be displayed. For more information, see GET_ATT.

The report automatically logs values that are entered in the request. You can deactivate this behavior for Job reports in the parameters of the script statement.

To Read User Input from the Read Buffer

Write the :READ statement in an enclosing :BEGINREAD...:ENDREAD block to query the user and store the values in the read buffer.

Syntax

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

Parameters

• :READ
  Queries for user input

• InVariable
  Variable to store user input in
  Important! The specified value must be compatible with the data type of the target variable (InVariable). For more information, see Script Variable Data Types.
  Format: script variable

• Input Check
  Validates user input
  Format: script literal or script variable
  Maximum length: 1024 characters, with a maximum of 127 characters per input parameter
  Example: each of the variables used for input parameters in the following script is limited to 127 characters.
  :READ &INPUT#,'&var1#,&var2#,&var3#','Select a value',&var3#
  Allowed values:

  • 00
    No validation (default)
  • 01 - 99
    Maximum number of characters that the user can enter for the value
  • N-M
    Minimum and maximum number of characters that the user can enter for the value, where N and M are integers
    Example: 10-20
  • Date format
    Specified format for dates and times
    Example: YYYYMMDD
    For more information, see Date, Time and Period Formats in Scripts.
  • Value, Value1 - Value2
    Value or range of values that the value that the user enters must match

• Message Text
  Text that is displayed to the user in the request
  Format: script literal or script variable
  Default: "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 length: 1024 characters
  Important! You cannot pass an empty string for the default value. You must enclose a space character in quotes.

• Input Handling
  Specifies option for how input is handled
  Format: script literal or script variable
  Allowed values:

  • C
    (If the READ statement is used within a :BEGINREAD... :ENDREAD block only) Places the cursor in this input field 
  • D
    Displays entered characters as asterisks (*)
    This setting is typically used for passwords.
    Note: Values that are entered in this protected manner are shown encrypted in the reports.
    
  • I
    (Jobs only) Suppresses documentation in the generated Job object report
    Note: Without this option, :READ statements and user input are documented in the generated Job object in the form of REMARK lines.
  • K
    Allows lowercase letters in the input
    Note: Without this option, input is automatically entered in uppercase letters. This option affects user interface input only, and not the read buffer.
  • M
    Field cannot be left blank
  • N
    Only numerical characters can be entered
    Note: This option affects user interface input only, and not the read buffer.
  • O
    User can select an entry from a list selection or make individual entries
  Note: You cannot use the D and N options together. To configure protected entries that must be numeric, use the Input Check parameter.
  Example:
  :READ &PASS#,"1-99999999","Enter password (numerical)",,"DM"

Important!

• Always include the relevant commas, regardless of the parameters Input Check and Message Text in the :READ statement.

• If you use several default values (for example in a dropdown box), each value must be at most 127 characters. Values that exceed 127 characters result in a runtime error.
  Tip: Use prompt sets to query users with more options. For more information, see PromptSets (PRPT).

• If :PUT_VAR is used before a :READ statement and the script generation of :READ is canceled manually (Cancel button) or due to invalid default values, the VARA object still contains the values that are set with the :PUT_VAR statement. For more information, see Generating at Activation or at Runtime.
  

Notes:

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

• The script statement writes all open transactions of the script to the AE database. For more information, see Script Processing.

• To freely combine values and ranges of values, separate them by commas.

• You can use letters, numbers or a combination of both for the input check. If you combine letters and numbers, the number of characters is checked.
  Example:Structure the parameter as follows to combine letters and numbers.
  :READ &INPUT#, "A-F,1-9,01-99,001-999","Please select"

• Specify commas and hyphens with single quotation marks if they should not be read as separators.
  Example: The user can select either the value 1-5 or the value 8,9.
  :READ &OPTION#,"'1-5','8,9'",'Please select','1-5'
  

The request displays the object name in the title bar. Use the script statement parameters to define the appearance and content of the request.

• Number field
  Define a continuous numerical range of values such as 0-255 with the Input Check option N to display a number field with up and down arrows in the request.
• List selection
  Define a fixed set of values such as A,B,C in the Input Check parameter to display the values in a list box.
• Text field
  Define a range such as A, 5-9 in the Input Check parameter to display an input field.
  

Examples

The script in the following example creates a request that queries the user for a headline. The input that the user enters is not validated, and the user can also leave the field blank. The characters are immediately converted to uppercase letters.

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

The following example also queries the user for a headline. The request does not suggest a default value, and does not validate input. Entering lowercase letters is possible.

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

The following example queries the user for a number. The Input Handling option is set to N, so the request contains a number field. Only numbers from 0 to 5 are accepted.

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

The following example queries the user for a date. The input has to be a valid date in the format YYMMDD, and cannot be blank.

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

The following example queries the user for a signature. The default value in the input field is A. The value entered in the field is validated to check whether it matches the allowed values of A, X and numbers between 5 and 9.

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

The following example requests the user to enter a password with a maximum of 8 characters. The Input Handling options D, M, and K determine that the field is secured, letters are not converted to uppercase, and the field cannot be left blank, respectively.

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

The following example requests the user for an email address. The user can pick from a selection of three email addresses. To avoid the hyphen being interpreted as a range of values, the last address is written in single quotation marks.

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

The following example requests the user to select an address, or enter a new one.

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

See also: