Scripting Examples

This page contains examples that illustrate how to use the Automation Engine scripting language:

Create Variable, Assign Values and Print Them

This script creates two script variables, assigns them values and writes them to the Activation report.

:DEFINE &number#,signed

:SET &number# = -1

:SET &string# = "test"

:PRINT "&&number# = &number#, &&string# = &string#"

Description:

  1. This line creates the first script variable.

    When you create a variable, you have to define its data type. Once defined, you cannot change the data type. In this case, the data type is signed because the variable should store a negative number.

  2. This line assigns a value to the variable.

  3. This line creates the second variable and sets its value to test. In this case, you can change the variable to any other value later on.

  4. Finally, this line writes the values of both variables to the Activation report. Note that you must use the & character twice here to be able to print the variable name. This is the result:

Screenshot of the Activation report displaying the following information: 2021-04-06 14:48:17 - U0020408 &number# = -0000000000000001, &string# = test

Arithmetic Operation

This script executes an arithmetic operation using a script function.

:DEFINE &result#, float

:SET &result# = DIV(1,4)

:PRINT "Result: 1/4 = &result#"

Description:

  1. This line creates a script variable with data type float.

  2. The DIV script function performs a division. This function has two parameters, number 1 is divided by number 2. The return code is the result of the division. The result is stored in a script variable (&result#).

  3. The result is printed to the Activation report. This is the result:

Screenshot showing the Activation report

Formatting

This script executes the same arithmetic operation and removes leading and trailing zeros from the result of the division.

:DEFINE &result#, float

:SET &result# = DIV(1,4)

:SET &format# = FORMAT(&result#,"0.00")

:PRINT "Formatted result: &format#"

This is the resulting Activation report:

For details and examples of script functions, see Script Functions.

See also:

Creating Requests

These scripts create a request. The first one simply prints text to the request. The second script creates a form that the user must populate.

Print Text to Request

For this purpose, you use the :BEGINREAD... :ENDREAD script statements. These statements define the beginning and the end of the request content. You combine them with the :PRINT statement to specify the text that will be written to the request.

:BEGINREAD

:PRINT "HELLO WORLD"

:ENDREAD

As a result, the Requests window displays the text HELLO WORLD:

Screenshot showing the requests view, where HELLO WORLD is displayed.

Create Form

This example combines the output that results from the :PRINT statement with the :READ statement, which stores variables to make their values available for further processing. The second :PRINT statements writes the variable to the Activation report

:BEGINREAD

:PRINT "HELLO WORLD"

:READ &INPUT#,"00","Please enter a text."

:ENDREAD

:PRINT "User text: &INPUT#"

This is the result:

Screenshot showing the requests view, where the input mask is displayed  

For more information, see:

IF Conditions

The following scripts show how to define conditions. You use the :IF... :ELSE... :ENDIF script elements to create conditions.

This simple example creates a condition that compares two numbers and writes a text to the Activation report:

:IF 1<2

:PRINT "Condition is met"

:ENDIF

The following example combines an :IF and a :READ statement to create a form in which the user can select YES or NO. If the user selects YES, the script function retrieves the current date and time and prints it to the Activation report. If the condition defined in IF is not met, a message is written to the Activation report:

:READ &VAR#,"'YES','NO'", "Retrieve current date and time?","YES"

:IF &VAR# = "YES"

:SET &TIME# = SYS_TIMESTAMP_PHYSICAL()

:PRINT &TIME#

:ELSE

:PRINT "Date and time have not been retrieved."

:ENDIF

This is the request with the form and both options:

Screensbhot of the Request showing a dropdown with the YES and NO options

If you select YES, the Activation report shows the current date and time:

Screenshot of the Activation report displaying the date and time

If you select NO, the Activation report shows the text specified in the :PRINT statement:

Screenshot of the Activation report displaying the text defined for the NO option

For more information, see:

Loops

Loops process code blocks until a condition is met and the iteration ends when the condition does not apply anymore. To avoid infinite loops, the Automation Engine has an internal mechanism that caps iterations at a specific number.

Check Agent Availability

The following script checks whether an Agent is available. If so, a Job (JOBTEST) should start on this Agent (VVIEAWATS02). We use a Script object to write the script. The script uses the :WHILE script statement to process loops.

:SET &AGENT# = VVIEAWATS02

:WHILE &ALIVE# NE "Y"

:PRINT "Waiting for agent &AGENT#..."

:WAIT 60

: SET &ALIVE# = SYS_HOST_ALIVE(&AGENT#)

:ENDWHILE

:SET &ACT# = ACTIVATE_UC_OBJECT(TESTJOB)

Description:

  1. This line defines the Agent.

  2. The :WHILE script statement defines the loop. The condition is &ALIVE# NE "Y" (where NE corresponds to "does not equal"). This means that the loop will end when the Agent is active.

  3. As long as the Agent is not active, the text defined here is written to the Activation report.

  4. To avoid too many loop cycles, a delay of 60 seconds is defined.

  5. When the Agent is alive, the SYS_HOST_ALIVE script function returns Y.

  6. The loop ends.

  7. The ACTIVATE_UC_OBJECT triggers the execution of the Job.

For more information, see

Get File List and Write to Activation Report

This script retrieves a file list from a computer and writes this list to the Activation report. The script uses the PREP_PROCESS_FILENAME script function to retrieve the list. The loop is defined by the :PROCESS script statement. In this example, we retrieve all text files available in C:\AUTOMIC\Agents\VVIEAWATS02\temp\, which includes the Agent log files.

:SET &HND# = PREP_PROCESS_FILENAME("VVIEAWATS02", "C:\AUTOMIC\Agents\VVIEAWATS02\temp\*.txt","Y",,)

:PROCESS &HND#

:SET &LINE#=GET_PROCESS_LINE(&HND#)

:PRINT &LINE#

:ENDPROCESS

Description:

  1. The PREP_PROCESS_FILENAME script function retrieves the list of files from the computer where the VVIEAWATS02 Agent is installed.

    In this example, the script variable name (&HND#) stands for HANDLE.

  2. The :PROCESS script statement creates the data sequence; it processes the data line by line and returns the output as internal list.

  3. The GET_PROCESS_LINE script function retrieves the current line content of the data sequence. In this example, the result is the path and name of the file.

  4. The result is written to the Activation report.

For more information, see:

See also:

The Reference guide in this documentation provides detailed descriptions and examples of all script elements. The guide is designed to help you find information as easily as possible. It is structured as follows:

You write scripts in the script editor available in the Process pages of executable objects, in SCRIPT (SCRI) and Include (JOBI) objects. See Working with the Script Editor for information about its features and functions.

The Using section in this documentation describes how to write scripts using the Automation Engine scripting language in more detail: