BACKEND Variables

BACKEND variable objects execute a command on an operating system and supply the result in the form of values that are shown in columns.

This topic provides information on the following:

Overview
Variables Page
Commands Page
Templates

Overview

BACKEND variable objects execute a command on an operating system and supply the result in the form of values that are shown in columns. The Variable object defines how the columns are split. You can enter several commands for various operating systems, system names, and versions in a variable. The correct command of the agent in question is automatically selected and executed when the variable is resolved.

The operating systems UNIX and Windows are supported. You can select the OS on the Commands window.

The privilege "Create and modify Backend variables" is required in order to create and modify BACKEND-type VARA objects.

The return code is automatically set to 1 if a Windows command results in an error. This means that when you use the VARA object within a script, the script will abort. In order to avoid this, you can append " & set ERRORLEVEL=0" at the end of the Windows command.

For example: cmd /c dir /b /o:d C:\temp\*.xml & set ERRORLEVEL=0

This command lists the files of a directory. The return code is always 0 regardless of whether files are found or not. In doing so, you can ensure that the tasks using this variable will not abort.

The settings VAR_TIMEOUT (UC_HOSTCHAR_) and BACKENDVAR_MAX_ROWS (UC_SYSTEM_SETTINGS) are also available for Backend variables.

PromptSet variables are supported in select fields for BACKEND, EXEC, FILELIST, SEC_SQLI, SEC_SQL, SQLI, SQL, and XML variable types. Using PromptSet variables are necessary when using the Dynamic Reload feature.

Variables Page

Specifying Variable Settings

Field	Description
Type	This read-only field shows "Backend" as the variable type. You determine the variable type when you create the object. It cannot be changed once the variable is defined.
Agent	The agent where the command will be executed. You can include PromptSet variables here when using the Dynamic Reload feature for Combobox prompts. When PromptSet variables are used in dynamic Variable objects, and you click Preview, you will get an error. This is because the PromptSet variables do not exist in the dynamic Variable object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed. The supplied Templates for Backend variable use the PromptSet variables &AGENT# for their specified agent and &LOGIN# for their login.
Apply Task Agent	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 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.
Login	The Login object for logging in to the agent computer. You can include PromptSet variables here when using the Dynamic Reload feature for Combobox prompts. When PromptSet variables are used in dynamic Variable objects, and you click Preview, you will get an error. This is because the PromptSet variables do not exist in the dynamic Variable object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed. The supplied Templates for Backend variable use the PromptSet variables &AGENT# for their specified agent and &LOGIN# for their login.
Apply Task Login	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 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.

Specifying Data & Formatting Settings

Field	Description
Data Type	The data type decides the format of the variable's values. Variable objects with the source "Backend" are always created with the data type "Text". This type cannot be changed. An alpha-numeric string. Blanks at the end of the string will be truncated. Leading blanks are retained. If the Limit Text Length checkbox is not checked, there will be no limit to the length of the character string.
Limit text length	Enforces a maximum character length. If this option is deactivated, there is no limit. The Key column of VARA objects has a maximum limit of 200 characters. This limit always exists and cannot be increased or deactivated. The result column of dynamic variables has no limit. The length depends on the value columns. In static and dynamic variables, this limit refers to the first value column. The Key or result column is not checked. Values that exceed the maximum length are excluded.
Force upper case	Lower case letters that are used in variable values are automatically converted to upper case. This only affects the first value column.
Result Format	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.

Specifying the Script Access Setting

You can specify what happens if a key is not found with the If key not found radio buttons.

To:	Choose:
Have an error message displayed if an object attempts to access an item that is not available at runtime via script	Return error
Not use the result of output format of when it is " "	Return initial values

Defining the Variable Usage in Other Clients

In client 0 you specify how the VARA object will behave in other clients.

When you define Variable objects in system Client 0, they can be used in other clients, either because they refer to the values set in the Variable in Client 0 or because you copy the original object from Client 0 to other clients and, if necessary, edit its values in the target clients.

With the Variable Usage in Other Clients options you define the behavior of this Variable object in clients other than 0:

Option	Description
Don't share but allow duplicates	If you select this option, this VARA object is available in clients other than 0 and you can use it there. You can modify all of its parameters in the non-0 clients, which can then be different per client. The name of the variable can be kept in non-0 clients. This means that if there is already a VARA object in the non-0 client with this name, two independent VARA objects with the same name will be available. You can modify all the parameters of both variables independently per client.
Share and allow read-only access	If you select this option, this VARA object is available in clients other than 0 and you can use it there but you cannot modify any of its parameters. Additionally, the name of this VARA object must be unique system-wide.
Share but keep attribute settings from system client	If you select this option, this VARA object can be copied to non-0 clients. If you do so, it keeps all the definitions made on the Attributes page but you can edit the Key and Value settings in the non-0 clients. Each client can have its own Key/Value definitions. Only available for STATIC variables.

Option

Description

Don't share but allow duplicates

If you select this option, this VARA object is available in clients other than 0 and you can use it there. You can modify all of its parameters in the non-0 clients, which can then be different per client.

The name of the variable can be kept in non-0 clients. This means that if there is already a VARA object in the non-0 client with this name, two independent VARA objects with the same name will be available.

You can modify all the parameters of both variables independently per client.

Share and allow read-only access

If you select this option, this VARA object is available in clients other than 0 and you can use it there but you cannot modify any of its parameters.

Additionally, the name of this VARA object must be unique system-wide.

Share but keep attribute settings from system client

If you select this option, this VARA object can be copied to non-0 clients. If you do so, it keeps all the definitions made on the Attributes page but you can edit the Key and Value settings in the non-0 clients. Each client can have its own Key/Value definitions.

Only available for STATIC variables.

Commands Page

Table for the definition of commands per operating system. The images below show Windows and Linux/UNIX commands.

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.

Column	Description
OS name	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 Administration perspective -> Agents -> SW column.
Version	Filters for the OS version. Version refers to the agent's OS version that is shown in the Administration perspective -> Agents -> SW version column.
Command	The OS command. You can include PromptSet variables here when using the Dynamic Reload feature for Combobox prompts. When PromptSet variables are used in dynamic Variable objects, and you click Preview, you will get an error. This is because the PromptSet variables do not exist in the dynamic Variable object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed. Windows only supports PowerShell commands.
Column format	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.

Working in the Command Tables

To:	Do this:
Add a row to the table	Click in the appropriate section. Click the cells in the table to edit their values.
Edit a cell in table row	Click the cell in the table and edit its value.
Delete one of more rows to the table	Check the checkbox for the row(s) and click .
Delete all rows to the table	Check the checkbox column header and click .
Cut one or more rows and them to the AWI clipboard	Check the checkbox for the row(s) and click .
Copy one or more rows and them to the AWI clipboard	Check the checkbox for the row(s) and click .
Paste row(s) from the AWI clipboard to the bottom of the table	Click .

Previewing Commands

To run the command, click Preview. The command is run on the defined computer and the results are displayed.

Templates

Predefined BACKEND-type Variable objects are supplied in client 0 (UC _RB_VARIABLES folder):

Object name	Operating System	Function	Columns
UC_RB_VARA_PROCESSLIST	Windows, Linux, AIX, SunOS, HP-UX	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.	ProcessID Process name
UC_RB_VARA_SERVICES_PAUSED	Windows, Linux, AIX, SunOS, HP-UX	Lists all paused services.	Service name
UC_RB_VARA_SERVICES_RUNNING	Windows, Linux, AIX, SunOS, HP-UX	Lists all started services.	Service name
UC_RB_VARA_SERVICES_STOPPED	Windows, Linux, AIX, SunOS, HP-UX	Lists all stopped services.	Service name
UC_RB_VARA_USERLIST	Windows, Linux, AIX, SunOS, HP-UX	Lists all OS users. Windows: Active Directory for PowerShell must be installed on the relevant computer.	User (account) name

These Variable objects can be used for the Dynamic Reload feature. Their specified agent is the variable name &AGENT#, and their login is &LOGIN#. Ensure that you use these names for the PromptSet variables of the required elements.

In PromptSet objects, you can select the predefined Variable objects directly as reference variables. It is not necessary to create them in their clients beforehand.

Variable objects include the options Apply Task Agent/Apply Task Login and use the agent/login of the task (if available) to which the PromptSet object is assigned.

The above table also shows the operating systems for which commands are specified in the variable. The correct command is executed depending on the agent and its OS.