Script Elements and Syntax

The elements and syntax of the Automation Engine scripting language are consistent with other scripting languages that you will be familiar with. Write statements with commands, functions and variables, and include comments. You can combine Automation Engine scripting language with commands of your target operating systems and applications. See Working with the Script Editor for information on syntax highlighting and completion.

This page includes the following:

Script Statements

Statements are the basic unit of work in scripts, and usually contain a command.

Properly formatted statements are displayed in blue in the script editor.

Example

The script statement below displays the text “Automation Engine” in the activation report when the object is processed:

:PRINT "Automation Engine"

If you need to continue a statement in the next line, write an underscore at the end of the line and start the next line with a colon.

Example

The statement below is interpreted as a single script statement:

:SCRIPT LINE SCRIPT LINE SCRIPT LINE SCRIPT LINE SCRIPT LINE_

:CONTINUED SCRIPT LINE

Script Functions

Functions allow you to manipulate data in the system. Script functions supply return codes, which distinguishes them from script statements.

Follow these rules when using script functions:

Properly formatted functions are displayed in red in the script editor.

Syntax

The statement below defines the value of a variable as the sum of two numbers.

:SET &SUM# = ADD(2,2)

Parameters

Many script functions work on their own, but there are also functions that only work or make sense when used in combination with other script elements.

Example

The script function PREP_PROCESS_FILE generates a data sequence from the content of a text file. The return code is a handle. The GET_PROCESS_LINE function reads the individual lines of the text file, but requires the handle that is retrieved with PREP_PROCESS_FILE.

Return Codes of Functions

Return codes can be individual characters, strings or numbers. Numbers are always supplied in 16 digits with leading zeros. The zeros do not affect the further processing of the number, such as arithmetic operations.

Syntax

The following script lines set a variable to a sum of two values, and display the resulting number.

:SET &SUM# = ADD(2,2)

:PRINT &SUM#

Parameters

This the result that is displayed:

0000000000000004

Tip: You can use a script function to remove leading zeros in the output. For more information, see FORMAT.

Return codes can also contain an error number. For more information about return codes, see the detailed descriptions of particular script elements in the Automation Engine Script Reference and Error Handling in Scripts.

Script Variables

Script variables let you define and pass values in scripts. Script variables can include numbers, strings, dates or times. The value of the variable is valid until the script has been processed. Properly formatted variables are displayed in purple in the script editor.

Defining and Setting Variables in Scripts

Use the following script statements to declare and assign values to variables in your scripts:

Note: The value you assign to a script variable is unlimited. Some script elements, such as :ADD_COMMENT, truncate the value because the target field has a limit.

More information: Script Elements for Variables and VARA Objects

Examples

The following statement declares a variable as a string.

:DEFINE &FILE#, string

The following script lines declare the variable as a string and define the text in that string.

:DEFINE &FILE#, string
:SET &FILE# = "temp.txt"

:DEFINE &STRING#, string

:DEFINE &SIGNED#, signed

:DEFINE &UNSIGNED#, unsigned

:DEFINE &FLOAT#, float

:SET &STRING#= "1234abc"
:SET &SIGNED#= -5
:SET &UNSIGNED#= 24
:SET &FLOAT#= -0.50

Script Variable Names

Follow the rules for naming variables when you define script variables. For more information, see Variable Names.

Variable names are context-specific, so you can define multiple variables in different objects that have the same name, as long as they are used in separate contexts. Variables cannot share the same initial characters within the same context.

Tip: End variable names with a hash character (#) to delimit the name and avoid problems with similar variable names. For example, the variables &VALUE# and &VALUES# can be used within the same context, while &VALUE and &VALUES cannot.

Arrays

Use arrays to store several different values in one variable. Declare a variable as an array by including array parameters in the :DEFINE statement. The individual values in the array can be accessed using an index.

Use the :ON_ERROR script statement to include error handling in the script if the array uses an invalid index. By default, if the script contains an invalid index, an error message is written both to the log and to the ACT report but processing is not stopped. For more information, see :ON_ERROR.

Example

The script below declares a variable as an array with 10 values, and specifies the value of index 5:

:DEFINE&ARR#, unsigned, 10

:SET&ARR#[5] = 20

Note: Array fields that have not yet been initialized display the default value "" if the data type is string, or 0 for numerical data types.

Tips:

Using Variables in Scripts

In addition to script variables, scripts let you call different types of variables used in the Automation Engine to retrieve and store values stored in the variables. Various script elements let you retrieve and modify different types of variables. For more information, see Script Elements for Variables and VARA Objects.

VARA Objects

Several script elements specifically let you work with VARA objects. Specify the name of the VARA object in the parameters of the script element.

Important! The script editor does not support the editing of VARA objects that contain arbitrary binary values (such as 0x00-0x08, 0x0b, 0x0c, 0x0e-0x19). When you try to save any of these values, the character ? (0x3f) is always saved instead.

Tip: You can define what should happen when the key that your script refers to is not available in the specified VARA object. For more information, see Script Access.

More Information: Variables and VARA Objects

Script Parameters

Write script element parameters in parentheses. Use commas to separate parameters. Script elements are evaluated in the order in which they are listed.

Example

In the script line below, the parameters for the function are enclosed in parentheses.

:SET &SUM# = ADD(2,2)

Notes:

Example

The function below creates an object and has two required parameters (Object Type and Object Name), and two optional parameters (Folder and Title).

CREATE_OBJECT (Object Type, Object Name, [Folder], [Title] )

If you do not want to specify a value for an optional parameter, write nothing or a space between the commas.

Example

The statement below does not specify a folder, as there is nothing between the second and third commas.

:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2018",,"Company calendar for 2018")

If you specify values for all required parameters but do not want to include values for any remaining optional parameters, you do not need to include commas for the remaining optional parameters.

Example

The statement below creates an object without specifying a folder or title, and you can simply close the parentheses after the last required parameter.

:SET &RET# = CREATE_OBJECT("CALE","FIRM.CALENDAR2018")

Keyword Parameters

You must write keyword parameters exactly as specified. In our documentation, keyword parameters are written in bold. As with parameters, optional keywords are enclosed in square brackets.

Example

In the function below, VERSION is a keyword.

SYS_INFO (component,VERSION, [ type ], [component name])

Optional keywords are enclosed in square brackets.

Example

In the script function below, FORCED is an optional keyword.

MODIFY_TASK (RunID, Status [, FORCED])

Some keyword parameters can be written in long or short forms. In this case, the keyword parameter is documented with the optional text for its long name in [ ] brackets.

Example

The keyword parameter STR_SUBSTITUTE_VAR is documented as STR_SUB[STITUTE]_VAR.You can write STR_SUBSTITUTE_VAR or STR_SUB_VAR, depending on your preference.

Script Literals

String literals are strings written within single (') or double (") quotation marks. You can write any string as a literal, for example to print a particular text.

A script literal can also contain script variables, which are replaced by their values when the script line containing the script literal is processed. The following scripts retrieves the system time, and prints the string Time followed by the system time:

:SET &TIME# = SYS_TIME("HH:MM:SS")

:PRINT "Time &TIME#"

Output:

Time 10:30:05

##<number> is a reserved combination. If you use this string in a script literal, the text is included in the message whose number is specified in <number>.

The following statement displays a message:

:PRINT "##1800" or :PRINT ##1800

This is the message displayed:

2011-06-15 13:01:51 - U0020408 ENDED_NOT_OK  - aborted.|

Important! The string <![[ ]]> results in an error when you use it in script literals, and you cannot save the object. If you need to be able to use this string, use one of the following approaches to avoid this error:

Object Names

AE names do not have to be enclosed in single or double quotation marks unless they start with a number. Write the following AE names without quotations marks if they do not start with a number:

Note: Use quotation marks if the AE name begins with a number.

Editing Strings by Script

The Automation Engine scripting language provides various script elements that let you edit strings. You can concatenate strings, retrieve or remove parts of strings, and replace all or parts of strings. For more information, see Script Elements for Editing Strings.

Comments

Any line starting with an exclamation point is interpreted as a comment and has no impact on processing. Use comments to inform other users about what different parts of your script do, and make later maintenance easier.

Example

!I can write anything I like here

Properly formatted comments are shown in green in the script editor.

Data Lines and Job Control Language

(Job objects only) Lines that start with neither an exclamation point (!) nor with a colon (:) are interpreted as data lines. Data lines contain commands in the Job Control Language (JCL) of the target system. When you include JCL, make sure that you use the commands and syntax of the JCL of the target system, because that is where it will be interpreted. When a script containing JCL is processed, the JCL is sent to the Agent and executed there.

You can use a script statement to explicitly declare a script line as a data line. For more information, see :DATA.

Jobs for enterprise business solutions (PeopleSoft, SAP and Siebel), include some special features, so the Automation Engine scripting language provides specific JCL elements for those systems. For more information, see Job Control Language Script Reference.

Example

The following data line uses a Windows command to copy a file to a directory.

copy test.txt c:\temp

If a data line starts with a colon (:), you must explicitly declare it as a data line by using the :DATA script statement.

Example

The following data line uses the same Windows command as in the example above, but is explicitly declared.

:DATA copy test.text c:\temp

Note: If you include a variable and your data line requires an ampersand before the variable, make sure you write both ampersands. When the script is processed, the script variable along with the ampersand in its name is replaced with the value that is assigned to the variable. If you use an ampersand without writing a valid variable name after it, the data line remains unchanged.

See also:

Related Script Elements

Process Pages

seealso

Scripting

Writing Scripts

Script Elements Ordered by Purpose

Alphabetical List of Script Statements and Functions