:READ

Use the :READ script statement to retrieve data from the read buffer. The read buffer temporarily stores variables, making their values available for subsequent processing. The specific function and behavior of the :READ statement depend on the context in which you use it.

Important! Do not use text values containing line breaks within the read buffer. The :READ statement ignores any characters following the initial line break.

Reading Variables in the Read Buffer

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

• Values stored when starting an object via the ACTIVATE_UC_OBJECT function. For more information, see :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER.
• Predefined UC_CAUSE* variables stored in the read buffer. For more information, see List of Predefined Read Buffer Variables.

Retrieving Stored Data

First, store a script variable in the read buffer using the :PUT_READ_BUFFER statement, and then activate the target object with ACTIVATE_UC_OBJECT. Within that target object, use the :READ statement to fetch the stored variable's value. Each script variable in the buffer can only be read once, as the system automatically deletes it immediately after reading.

Triggering User Dialogs

Enclose the :READ statement within a :BEGINREAD...:ENDREAD block to trigger a user prompt in the Requests view. The system stores the user's input in variables for further processing. For more information, see Working with Requests .

Dialog Trigger Conditions

The :READ statement successfully triggers a request only if one of the following conditions is met:

• The task is activated manually.
• The Generate Task at: Activation time option is selected on the object's Attributes page. For more information, see Executing Objects: Generating Task at Activation Time vs Generating Task at Runtime.

Conversely, the request is suppressed and default values are used automatically in the following scenarios:

• The Generate Task at: Runtime option is selected for the object or its parent Workflow.
• The task runs within a Schedule or a queue group.
• The task is activated via a script function (e.g., ACTIVATE_UC_OBJECT), a CallAPI, or an object setting like a Workflow Postcondition.

Tip: Use the GET_ATT script function with the DCMODUS attribute to programmatically determine whether the current execution mode permits the Requests view to display. For more information, see GET_ATT.

Syntax

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

Parameters

Parameter	Description	Format	Allowed Values	Default Value
InVariable	Specifies the target script variable for storing the user's input. Important! This input must be compatible with the variable's defined data type. For more information, see Script Variable Data Types.	Script variable	n.a.	n.a.
Input Check	Validates the user input. You can combine values and ranges freely by separating them with commas.	Script literal or variable. Maximum 1024 total characters, and maximum 127 characters per individual parameter.	00: No validation (default). 01-99: Sets the absolute maximum character limit (e.g., 05 restricts input to 5 characters). Number Range: Defines an acceptable numerical range (e.g., 05-10). Date format: Specifies a date format string (e.g., YYYYMMDD). Specific Values: A strict value or range of values the input must match (e.g., A-F).	00
Message Text	Defines the descriptive text displayed to the user within the request dialog.	Script literal or script variable. Maximum 256 single-byte characters (fewer if multi-byte).	n.a.	"Please enter value for variable Variable name"
Default Value	Provides a suggested default value inside the input field. Important! You cannot pass a completely empty string; you must supply a quoted space character instead.	Script literal or script variable. Maximum 1024 characters.	n.a.	n.a.
Input Handling	Specifies behavior options for how the UI handles the entered data. Note: You cannot combine the D and N options.	Script literal or script variable	C: Places the cursor in this specific field (only within a :BEGINREAD block). D: Masks characters with asterisks for passwords, encrypting the output in reports. I: (Jobs only) Suppresses REMARK documentation of the input in the generated Job report. K: Permits lowercase letters in the UI, overriding the default uppercase conversion. M: Makes the field mandatory. N: Restricts UI input to numerical characters only. O: Allows users to either select an entry from a dropdown list or type a custom value.	n.a.

Important Considerations

Keep the following rules and formatting guidelines in mind when scripting with :READ:

• Always retain the appropriate positional commas in the syntax, even if you omit optional parameters like Input Check or Message Text.
• If the user skips the field without entering or selecting a value, the system stores a blank space (" ") in the target variable.
• The script statement automatically commits all open transactions to the AE database. For more information, see Script Processing.
• If you provide multiple default values (e.g., for a dropdown box), no single value can exceed 127 characters. Exceeding this limit triggers a runtime error. Tip: Use PromptSets for more robust query options. For more information, see PromptSets (PRPT).
• If a :PUT_VAR statement executes before :READ, and the script generation is subsequently canceled (manually or due to invalid defaults), the VARA object will still retain the values written by :PUT_VAR. For more information, see Executing Objects: Generating Task at Activation Time vs Generating Task at Runtime.
• To prevent commas and hyphens from being interpreted as range separators during input validation, enclose them in single quotation marks. For example, using '1-5','8,9' allows the literal selections "1-5" or "8,9".
• By default, reports automatically log the values entered into the request. You can disable this logging for Job reports using the I option in the Input Handling parameter.

Dialog UI Appearance

The resulting dialog displays the object's name in its title bar, while the input field itself adapts based on your script parameters:

• Number field: Defining a numerical range (e.g., 0-255) alongside the N handling option generates a numeric field featuring up and down arrows.
• List selection: Supplying a fixed set of comma-separated values (e.g., A,B,C) renders a dropdown list box.
• Text field: Defining alphanumeric ranges (e.g., A, 5-9) outputs a standard text input field.

Examples

Reading Buffer Variables

The following example stores the host agent's name in the read buffer, then activates a Notification object.

:SET &att_host# = GET_ATT(HOST)

:PUT_READ_BUFFER host# = '&att_host#'

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

Inside the target Notification object, the script retrieves and prints the stored agent name:

:READ &host#,,

:PRINT "Agent: &host#"

This script example retrieves system-generated UC_CAUSE* variables to output the details of the specific task that triggered the notification:

: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"

:RINT "Return code: &UC_CAUSE_RETCODE"

Requesting User Input

The following script generates a basic headline request. It skips validation, allows blank fields, and automatically converts characters to uppercase.

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

This request skips validation and default values but uses the K parameter to permit lowercase text entry:

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

The following script strictly queries for a number between 0 and 5, using the N handling option to render a numerical input field:

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

This example demands a mandatory (M) date entry conforming strictly to the YYMMDD format:

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

The following script requests a signature, suggesting "A" as the default. The validation requires the input to be exactly A, X, or a number from 5 to 9.

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

This script securely requests an 8-character maximum password. The DMK handling flags ensure the field masks input (D), is mandatory (M), and accepts lowercase characters (K).

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

The following script provides three distinct email options. Single quotation marks wrap the final email address to prevent the hyphen from acting as a range operator during validation.

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

By adding the O parameter, this script allows the user to either pick from the provided list or type an entirely new custom address:

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

See also: