Working with the Script Editor

Use the script editor in the Process Pages to write scripts for executable objects. You can use the Automation Engine scripting language and Job Control Language to provide processing instructions.

This page includes the following:

Scripting Assistance

The script editor provides various features to help you write your scripts.

Tips:

  • The Automic Web Interface provides a number of shortcut keys to make your work with the script editor easier and faster. See Keyboard Shortcuts.
  • Adjust the font size of the script editor and other settings in the user settings. For more information, see Script Editor Settings.

Script Element Color

Script elements are displayed in different colors depending on their category to help you easily recognize them:

  • Green

    Comment lines

    Example: !####-STOP-####

  • Blue

    Script statements and predefined variables

    Example: :PRINT

  • Red

    Script functions

    Example: ACTIVATE_UC_OBJECT

  • Brown

    Job Control Language (JCL) lines

    Example: echo FileContent > c:\temp\FileName.txt

  • Grey

    Strings

    Example: "GENERIC.09.JOBS"

  • Purple

    Script variables

    Example: &RUNID#

For more information, see Script Elements and Syntax.

Tip: Select an element and right-click to open a context menu with the same functions as the Script Editor Toolbar.

Syntax Highlighting

To see all occurrences of a script element at a glance, click or select it. All instances of the selected element are highlighted in yellow. Occurrences of the element that are in Includes are also highlighted as long as the Includes are expanded.

This function is not case-sensitive.

Example: MODIFY_TASK

Tip: You can also use the search function in the script editor to find occurrences of script elements, object names, strings, and so on. For more information, see Searching and Replacing Strings.

Syntax Tooltips

The script editor displays tooltips with script elements and their syntax as you type. Tooltips suggest the correct syntax for the script statement, function and function argument. Tooltips also display successor arguments for statements (for example, IF condition ELSE). To display tooltips, do one of the following:

  • Click or double-click any element to display its syntax
  • Click or double-click a statement to display possible arguments
  • Start writing a script function or point your mouse to an adjacent script function to display the possible script variable syntax

If there are multiple syntax possibilities for your script function, the tooltip displays all of them.

Activate syntax tooltips in the user settings. For more information, see Script Editor Settings.

Autocomplete

Use the autocomplete feature to insert script elements as you type. This feature suggests Automation Engine scripting language statements and functions and lets you insert predefined variables and VARA objects.

Writing Script Elements

  1. Start typing the element.
  2. Press Ctrl+space.

  3. The autocomplete dropdown list displays a list of all function names that match your input. You have the following options to select the element you need:

    • Start typing its name
    • Use the mouse or your keyboard to select it

Tip: To resize the dropdown list, click its bottom right end and drag it to the desired size.

Inserting Predefined Variables and VARA Objects

You have to options to insert variables and VARA objects in your scripts:

  • Click the {&} Select Variable button on the toolbar
  • Press Ctrl+space to display the autocomplete dropdown list and select {&} Select Variable

Then, select the variable or VARA object from the Insert Variable dialog. For more information, see Inserting Variables/VARA Objects in Objects and Scripts.

Tip: The Automation Engine scripting language provides script elements that let you perform many operations with VARA objects. See Script Elements for Variables and VARA Objects.

Context-Sensitive Help for Script

Right-click an Automation Engine keyword in the script editor and select Search in help in the context menu. The online help opens displaying the topic that describes the selected script element.

Note: Search in help will not appear if the keyword is highlighted.

Script Editor Toolbar

Use the buttons in the script editor toolbar for the following actions when writing scripts. You find some of these options in the More dropdown menu:

  • Select Variable

    Opens the Select Variable dialog, from which you insert a variable or VARA object in the script.

  • Comment
    Adds an exclamation mark (!) at the beginning of the selected line or lines. You can also type the exclamation mark, but this button is useful for marking multiple lines as comments. Commented lines are ignored during execution.
  • Uncomment
    Removes the exclamation mark. The lines are no longer commented, so they are processed during execution. If a line contains multiple exclamation marks and one of them is at the beginning of the line, then only the first exclamation mark is removed.
  • Reformat All
    Applies consistent formatting to the entire script: indents nested blocks, removes unnecessary indent spacing and adds a space after a comment character (!).
    Example: after reformatting, the line : ..........PRINT"Start of processing" looks like :PRINT"Start of processing"

  • Undo (Ctrl+Z)

    Reverts your last change

  • Redo (Ctrl+Y)
    Restore your last undone action
  • Indent and Outdent
    Indents or outdents selected lines. Colons that identify script statement lines and exclamation marks that identify comment lines remain at the beginning of the line, while the rest of line is indented or outdented.
  • Import and Export
    Imports or exports a whole script. Place the cursor in the spot where you want to import the script lines. The export function generates a text file containing the script for you to download. For more information, see Reusing Script Components.

Searching and Replacing Strings

You can search and replace strings in the script editor if the object is in edit mode. Found strings are highlighted in yellow. The search function also finds and highlights strings in Includes if the Includes are expanded.

The search and replace function is not case-sensitive.

To Search for or Replace a String in the Script

  1. To activate the search function, click the Search button on the script editor toolbar or press Ctrl+F. To populate the search field with a string automatically, select the string in the editor before opening the search.
  2.  Enter the strings in the in the Search for or Replace with fields. Both fields remember the last 30 entered strings.
  3. Specify the search options:
    • Direction
      Search above or below the current location, or search for all occurrences of the string.
    • match case
      Select to make the search case-sensitive.
    • match whole words
      Select to search for strings separated from the rest of the text by the following characters:
      • Blanks ( )
      • Tabs (\t)
      • New lines (\r\n or \n)
      • Punctuation marks (, . ; : ? !)
      • Special characters (\ ^ $ | ( ) [ ] { } EOF)
      Note: this option is disabled if your search string contains any of the characters above.
  4. Do one of the following:
    • Press [Enter] or click Find Next to highlight the first occurrence of the string.
    • Click Find All to highlight all occurrences.
    • To replace one specific occurrence, click Find Next until the desired match is highlighted and then click Replace/Find.
    • To replace all occurrences, click Replace All.

The number of occurrences or replacements is displayed at the bottom of the search bar.

Converting to Uppercase or Lowercase Characters

Select one or more words, right-click and select Uppercase or Lowercase in the context menu. Special characters and numbers are not affected by case conversion.

Automatic Uppercase Conversion for OS/390 and AS/400 Jobs

The script editor recognizes scripts for OS/390 or AS/400 jobs and automatically converts those script lines to UPPERCASE. Numbers, other non-alphabetical characters, imported scripts and copy-pasted texts are not affected. If you need to write such scripts in lowercase, press shift and enter your text.

Example:

If you type wait100, the script editor automatically converts the text to WAIT100.

Handling Objects in the Script Editor

The script editor treats any string that meets the following criteria as a potential object name:

  • Contains alphanumeric characters without umlauts

  • Can contain the following special characters:

    . _ # @ - $

  • Starts or ends with any of the following:
    • Spaces, tabs, new lines
    • Umlauts or any other special characters
    • Punctuation marks other than dots

Opening and Editing an Object from the Script Editor

When you write scripts, you often refer to objects that are available in your system. If you need to change the settings of an object that you are referring to, you can do so directly from the script editor. Hover your cursor over the object name, right-click and select Open from the context-menu. This opens the object definition pages where you can edit settings if you have write permissions.

Opening the List of Executions of an Object

You can open lists of execution data of an object included in a script directly from the script editor. Right-click the object name and select Executions from the context menu. For more information about execution lists, see Execution Data.

Opening the Last Report of an Object

You can check the details of the object's last report without leaving the script editor. Right-click the object name and select Open Last Report from the context menu. For more information about object reports, see Reports.

Using Include Objects in Scripts

Include objects (JOBI) let you store and reuse common script blocks. Write an :INCLUDE statement in the line where you want to call an Include object. The included script lines are inserted in that position. You can nest Include objects within Include objects, without limit as to the level of nesting.

To expand the inserted script lines, click the + icon in the line of the :INCLUDE statement. The lines of the Include object are displayed inline in read-only mode. To edit them, open and modify the Include object. To do so, right-click the name of the Include objects, select Open and edit it. Your changes are reflected in the script editor after refreshing the view or collapsing and expanding the Include.

Right-click any empty space of the Include to open a context-menu with the same functions as the toolbar of the editor. It also provides the Collapse all expanded Includes option.

Notes:

  • To edit the included script lines, you need write permissions for the Include object. If you only have read permissions, you can view the included script lines but you cannot modify them.
    If you have neither read nor write permissions for the Include object, you cannot either expand or edit the included lines.
  • The script editor search considers the content of Include objects only if they are expanded.
  • Exporting a script also exports the first-level Includes. If they contain nested Includes, the nested ones are not exported.
  • Copying and pasting the content of a script copies the content of the Includes only if they are expanded
  • If an Include object is deleted, expanding the corresponding Include in the scripts displays a message indicating it.

For more information, see:

Using VARA Objects in Scripts

See Using Variables in Scripts.

Importing and Exporting Code Chunks

You can import and export chunks of code in the script editor. Exporting code lets you reuse scripts across installations quickly and easily. This function is available on all Process pages as well as in the Script object.

You can import the content of a file available on your machine to your script. You can also export the entire script to a file that you can then import on a different system.

Note: Exporting a script always applies to the entire script. You cannot export just the text that you have currently selected . If you want to export only a part of your script, copy and paste the text.

To Import Code from a File

  1. Put your cursor in the position where you want to insert the imported code.
  2. Right-click and select Import from the context menu.
  3. Click the upload icon in the Import dialog.
  4. Locate the file in your local file system and click Open.
  5. The selected file is uploaded and its contents are inserted at the current cursor position.

The maximum file size for uploads is defined by the MAX_IMPORT_SIZE key (see UC_CLIENT_SETTINGS - Various Client Settings). The hard limit is max. 30720 KB.

Tip: Import scripts that are not larger than 500kb to avoid potential performance issues.

To Export Code to a File

  1. Open the script.
  2. Click the Export button on the script editor toolbar.
  3. The entire script is downloaded in a text file with the name of the object followed by "_sheet.script". The download path depends on your browser settings.

See also:

seealso

Writing Scripts