Variable Tab

String

Unlimited

If the setting "Text limiting" is selected ("Attributes"tab), this restriction only affects the first value column. 

Number

Between 0 and 2147483647.

Timestamp

Date and time value depending on the output format.

Executable Object

The name of the Automation Engine object.

The following object types are recommended for use with VARA.EXEC:

• Job, Script, FileTransfer Job, Event, Remote Task Manager, Workflow, Group, Notification

The following executable object types should not be used with VARA.EXEC: Schedule, Cockpit.

Note that at this stage in the executable object itself no check is performed, if the right object type has been selected. An error message will be displayed as soon as the object is executed.

The name of the script variable that is used for the return value of the executable object.

List of parameters and variables that are available in the executable object. Their values can be either

• Direct values, for example 5342
• Reference variables, for example &reftext#

You must treat these parameters as though they were PromptSet/read buffer values. When VARA object calls the executable object, it uses :PUT_PROMPT_BUFFER to set the specified parameters. This means that in order to read and use these values in the called executable object, you must do one of the following:

1. Create a PromptSet on the called executable object with variables with the same names as the parameters set in the calling EXEC Variable object.
2. Use the :READ command to read in the values of variables of the same names as the parameters set in the calling EXEC Variable object.

It is not sufficient merely to define the variables on the Variables & Prompts tab for the called executable object.

Database connection

Connection

The database-type Connection object that contains the connection parameters for the required database.

The Login object that stores the name of the database user and the corresponding passwordA secret combination of characters for a Automation Engine user..

The login data for accessing the database is retrieved from the Connection object if you neither specify a Login object nor set the option Apply User's default Login. An error occurs if the variable should be resolved and this object does not include any login information.

You can also select a Login object for SQL variables in User objects (default login). With the option Apply user's login activated, the Login object that has been assigned to the current user is applied. The Login object that is specified in the variable is ignored in this case. An error occurs if the variable is accessed and no login is defined in the User object.

Text field for specifying SQL statements. These SQL statements are used to select data records in the database and supply them as variable values.

For example: select * from col

Note that all SQL statements are allowed in this text field. You can even change or delete database entries.

AE does not verify whether these SQL commands include errors or are harmful. They are passed on to the database without being verified. This means that an execution error can only occur during database access, which is when the variables are being resolved.

Note that you must used the setting VAR_SECURITY_LEVEL(UC_SYSTEM_SETTINGS) in the SQL statements if you usepredefined variables or other Variable objects. Otherwise, no value replacement takes place (default) and a database error occurs.

Maximum length: 4096 characters

Definition of the result column's contents.

The first column that is displayed in the preview is the result column. The other columns include the individual values of the database columns that have been returned by the SQL query. The result column can show a combination of value columns and any characters. This is defined via the Result Format.

Column numbers that were specified using {} curly brackets in the Result Format field will be replaced by the value of the corresponding column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Return Format: {1}_{2}
Result column: JOB01_WIN01

The result column corresponds to the first value column if no Result format is specified.

The limitations for variables (min. value, max. value, limit text to) do not affect the result column but the first returned column. If the value of this column exceeds the allowed range, the line is skipped and is not available via the Variable object.

This executes the SQL statements and displays the result in a new window. In doing so, the SQL statements are checked and possible errors can be identified (for example, the data type of the Variable object and of the database do not match).

The database agent sends the preview data to the Automation Engine in the form of a message. An error occurs if this message exceeds the maximum message length that a server process accepts (see parameter MaxMsgSize= in the AutomationEngine's INI file, default value: 3145 728 Bytes). In this case, you can limit the result either by using a maximum number of lines or through SQL statements.

Database connection

Connection

The database-type Connection object that contains the connection parameters for the selected database.

The Login object that stores the name of the database user and the corresponding password.

The login data for accessing the database is retrieved from the Connection object if you neither specify a Login object nor set the option Apply user's default login. An error occurs if the variable is to be resolved and this object does not include any login information.

You can also select a Login object for SQL variables in User objects (default login). With the option Apply user's login activated, the Login object that has been assigned to the current user is applied. The Login object that is specified in the variable is ignored in this case. An error occurs if the variable is accessed and no login is defined in the User object.

The SQL statements used to select specific database entries that serve as variable values.

Variables that are directly specified in SQL will not be replaced. To include variables, use bind parameters.

Maximum length: 4096 characters

The table that contains the bind parameters.

Use bind parameters in order to insert variable values within SQL statements. You can use predefined variables, PromptSet variables, and placeholders for VARA objects for the entries of this table. Each line represents one bind parameter.

You use bind parameters in order to insert variable values within SQL statements. You can use script variables, object variables, predefined variables, and placeholders for VARA objects that you enter in this table. Each line represents one bind parameter.

The variable VAR_SECURITY_LEVEL (UC_SYSTEM_SETTINGS) does not impose any limitations.

In the SQL statements, you must use a "?" character at every location where the replaced value of a bind parameter is to be inserted. A bind parameter must exist for each "?". Make sure that you maintain the correct order (table). Note that you cannot use bind parameters multiple times.

No values will be replaced if a specified variable does not exist. In this case, the variable name is used, which can cause an error when the variable is to be resolved.

The parameters are automatically numbered and cannot be changed. To remove individual bind parameters, highlight them and press the DEL key.

You can use variable names as bind parameters, with any values of your choice.

The following field data types and input formats are supported for bind parameters:

• Date: yyyy-mm-dd
• Time: hh:mm:ss
• Timestamp: yyyy-mm-dd hh:mm:ss
• String: any string
• Boolean: possible values: 0 / 1 or true / false
• Number: no thousand separator, a decimal point as a decimal separator

Other field types of the database and other formats are not supported. Data types are not converted (no conversion from timestamp to date). Inserting an invalid value causes an error when the SQL commands are processed.

The definition of the result column's contents.

The first column that is displayed in the preview is the result column. The other columns include the individual values of the database columns that have been returned by the SQL query. The result column can show a combination of value columns and any characters. This is defined via the Result Format.

Column numbers that were specified using {} curly brackets in the Result Format field will be replaced by the value of the corresponding column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Return Format: {1}_{2}
Result column: JOB01_WIN01

The result column corresponds to the first value column if no Result format is specified.

The limitations for variables (min. value, max. value, limit text to) do not affect the result column but the first returned column. If the value of this column exceeds the allowed range, the line is skipped and is not available via the Variable object.

This executes the SQL statements and displays the result in a new window. In doing so, the SQL statements are checked and possible errors can be identified (for example, the data type of the Variable object and of the database do not match).

The database agent sends the preview data to the Automation Engine in the form of a message. An error occurs if this message exceeds the maximum message length that a server process accepts (see parameter MaxMsgSize= in the AutomationEngine's INI file, default value: 3145 728 Bytes). In this case, you can limit the result either by using a maximum number of lines or through SQL statements.

The text field for specifying SQL statements. These SQL statements are used to determine the AE database's data records that are used as variable values.

For example: select * from OH

Select the type of AE database you use in order to be able to execute SQL commands: MS SQL, Oracle or DB2. The SQL statements remain stored for each database type.

Note that SQL statements are not checked. You can even change or delete database entries.

AE does not verify whether these SQL commands include errors or are dangerous. They are passed on to the database without being verified. This means that an execution error will only occur during database access, which is when the variables are being resolved.

Note that usingpredefined variables or other Variable objects requires you to specify the setting VAR_SECURITY_LEVEL (UC_SYSTEM_SETTINGS) in the SQL statements accordingly. Otherwise, the variables are not replaced (standard) and a database error occurs.

Maximum length: 4096 characters

The definition of the result column's contents.

The first column that is displayed in the preview is the result column. The other columns include the individual values of the database columns which have been returned by the SQL query. The result column can show a combination of value columns and any characters. This is defined via the Result Format.

Column numbers that were specified by using { } curly brackets in the field Result Format will be replaced by the value of the corresponding column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Result Format: {1}_{2}
Result column: JOB01_WIN01

The result column corresponds to the first value column if no Result format is specified.

The limitations for variables (min. value, max. value, limit text to) do not affect the result column but the first returned column. If the values of this column exceed the maximum range, this line is skipped and is not available via the Variable object.

This executes the SQL statements and displays the result in a new window. In doing so, the SQL statements can be checked and other errors be identified (for example, the data type of the Variable object and of the database do not match).

The SQL statements used to select specific database entries that serve as variable values.

Variables that are directly specified in SQL will not be replaced. To include variables, use bind parameters.

Maximum length: 4096 characters

The table that contains the bind parameters.

You use bind parameters in order to insert variable values within SQL statements. You can use script variables, object variables, predefined variables, and placeholders for VARA objects that you enter in this table. Each line represents one bind parameter.

The variable VAR_SECURITY_LEVEL (UC_SYSTEM_SETTINGS) does not impose any limitations.

In the SQL statements, you must use a "?" character at every location where the replaced value of a bind parameter is to be inserted. A bind parameter must exist for each "?". Make sure that you maintain the correct order (table). Note that you cannot use bind parameters multiple times.

No values will be replaced if a specified variable does not exist. In this case, the variable name is used, which can cause an error when the variable is to be resolved.

The parameters are numbered automatically and cannot be changed. To remove individual bind parameters, highlight them and press the DEL key.

You can use variable names as bind parameters, with any values of your choice.

The following field data types and input formats are supported for bind parameters:

• Date: yyyy-mm-dd
• Time: hh:mm:ss
• Timestamp: yyyy-mm-dd hh:mm:ss
• String: any string
• Boolean: possible values: 0 / 1 or true / false
• Number: no thousand separator, a decimal point as a decimal separator

Other field types of the database and other formats are not supported. Data types are not converted (no conversion from timestamp to date). Inserting an invalid value causes an error when the SQL commands are processed.

The definition of the result column's contents.

The first column that is displayed in the preview is the result column. The other columns include the individual values of the database columns which have been returned by the SQL query. The result column can show a combination of value columns and any characters. This is defined via the Result Format.

Column numbers that were specified by using { } curly brackets in the field Result Format will be replaced by the value of the corresponding column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Result Format: {1}_{2}
Result column: JOB01_WIN01

The result column corresponds to the first value column if no Result format is specified.

The limitations for variables (min. value, max. value, limit text to) do not affect the result column but the first returned column. If the values of this column exceed the maximum range, this line is skipped and is not available via the Variable object.

This executes the SQL statements and displays the result in a new window. In doing so, the SQL statements are checked and possible errors can be identified (for example, the data type of the Variable object and of the database do not match).

Definition of the two Variable objects that serve as values sources.

Variable 1 determines the number of columns. The reference columns' values of both variables are combined depending on the operation that has been specified. The reference column depends on the variable source: Key column (in static variables), first value column (variable source: SQL, SQL-internally, Multi), or the Filelist column (variable source: Filelist). Columns that are not included in Variable 2 do not include a value for the corresponding entries.

The values of Variable 1 are used if two Variable objects contain entries of the same name.

Note that the data type of the source variable's reference column should match the Multi variable's data type. Otherwise, an error occurs or the values are not available.

Definition of the result column's contents.

The first column that is displayed in the preview is the result column. The result column can show a combination of value columns and any other characters. This is defined via the Result Format.

Column numbers that were specified using curly brackets {} in the Result Format field will be replaced by the value of the corresponding column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Result Format: {1}_{2}
Result column: JOB01_WIN01

Without a Result Format being specified, the value of the variable's Result or Key column is assumed.

The values of the result column have to comply with the variable's limitations (min. value, max. value, limit text to), the output format, or the data type. Otherwise, the result column does not include a value.

The directory whose file names should be returned as a value list when the Variable object is accessed. This directory must be available on the specified host.

Example for a Windows computer:


C:\temp

You can also limit the list to files with a particular name or suffix. To set such filters, use wildcard characters: * stands for several characters, ? for exactly one character.

For example:
C:\AUTOMIC\utility\temp\*.txt

The OS agent that is used to access the specified directory. You cannot select an agent group.
The system automatically uses the agent of the task that triggers the variable access (in file transfers: the source host) if no host has been selected.

A runtime error occurs if the variable is used in an object which no agent or login has been assigned to.

FileTransfer object as source: If you do not assign a host to the Variable, the host of the FileTransfer object's target system will be used.

With this option activated, the agent of the task that accesses the Variable object is used.

The agent on whose computer the command is to be executed.

This setting deploys the agent of the task accessing the Variable object.

The task's agent is preferred if this option is set. The variable's agent (see Host) is used if the task does not include an agent (such as in Script objects). An error occurs if the variable is to be resolved and neither the task nor the variable includes an agent.

This setting deploys the login of the task using the variable.

The task's Login object is preferred if this option is set. The variable's login (see "Login") is used if the task does not include a Login object (such as in Script objects). An error occurs if the variable is to be resolved and neither the task nor the variable includes a Login object.

Table for the definition of commands per operating system.

In Windows, these are not batch lines. This means that you must define a specific program to be executed. 

Examples:
Listing the directory: cmd /c dir C:\temp
Ping: ping localhost -n 10

You can store the commands for several operating systems within the same variable. They system automatically uses the OS commands of the relevant agent when the variables are resolved.

In the columns OS Name and Version, you can filter for the names (such as a particular UNIX derivative) and OS version. The suitable line for the specified agent is automatically used when the variable is executed.

The first entry that matches the OS, OS name, and version of the agent is used.

Note that Backend-type variables execute exactly one command.

UNIX: The user who is specified in the Login object must have the right to execute the corresponding command. Linux: Root rights are required for the chkconfig and runlevel commands.

Filters for the name of the operating system.

You can also use the wildcard character *. This serves as a placeholder for any number of characters.

The OS name refers to the agent's OS name that is shown in the System Overview -> Agents -> SW column.

Filters for the OS version.

Version refers to the agent's OS version that is shown in the System Overview -> Agents -> SW version column.

OS command.

Windows only supports PowerShell commands.

Definition of how the result should be split into columns.

Syntax:
column name:start position(length) [;column name:start position(length)  . . .] 

Column name: Name of the column, user-defined
Start position: Position of the character where the column starts.
Length: Number of characters that determines the column's size.

Semicolons (;) must only be used between several columns. They are not required at the end of the complete definition.

You must define at least one value column (minimum requirement).

For example:
process:1(20);pid:25(10)

The above example splits the command's output into two columns:
The process column starts with the first character and has a length of 20 characters. "pid" starts at character 25 and is 10 characters long.

Definition of the result column's contents.

The first column that is displayed in the preview is the result column. It can be composed of value columns and any characters (to be determined in the Result Format).

Column numbers that are specified in curly brackets { } in the Result Format field are replaced by the value of the relevant column.

For example:
Value column 1: JOB1
Value column 2: WIN01
Result format: {1}_{2}
Result column: JOB01_WIN01

The result column matches the first Value column if you do not specify a Result format.

The result column's values must be within the variable's limits (min. value, limit text to) or match the data type. Otherwise, the result column does not obtain a value.

Lists the active processes.

The maximum ProcessID length may differ depending on the UNIX system used. Adjust the column length in the Variable object if necessary.

Lists all OS users.

Windows: Active Directory for PowerShell must be installed on the relevant computer.