Using Variables

Use variables to store values that can be referenced in multiple procedure steps. Variables are passed automatically to nested procedures.

• Three Methods for Creating Variables:
  • Procedure Variables - Use the getVariable() command within a procedure to create a new variable name without any special characters. Example: VariableName. In subsequent steps, including steps in nested procedures, reference the variable by bracketing the variable name with the # character. Example: #VariableName#.

    Note: Procedures variables cannot be referenced outside of the procedure or nested procedures that use them except for GLOBAL variables. A procedure variable is only visible to the section of the procedure it was created in and any child procedures. Once a procedure leaves the THEN clause or ELSE clause the variable was created in, the variable is out of scope and no longer valid. Use GLOBAL Variables, described below, to maintain visibility of a variable after leaving the THEN clause or ELSE clause the variable was created in.

  • Managed Variables - Use the Variable Manager to define variables that can be used repeatedly in different procedures. You can maintain multiple values for each managed variable, with each value applied to one or more group IDs. Managed variables cannot be re-assigned new values within a procedure. Within a procedure, reference a managed variable by bracketing the variable name with the < and > character. Example: <VariableName>.
  • GLOBAL Variables - Non-GLOBAL variables cannot return a changed value of a procedure variable defined by its parent procedure. Non-GLOBAL variables initialized in the child procedure also cannot be passed back to the parent. Variables named with the prefix GLOBAL: (case-insensitive followed by a colon) can pass changed values from the child to the parent, whether the variable is initialized in the parent or the child procedure. Subsequent child procedures can makes use of any GLOBAL variable initialized in any earlier step, regardless of whether that global variable is initialized in a parent procedure or another child procedure.
• Variable Names - Variable names cannot include the following characters: , % ' " / \ : * ? < > | and the space character.
• Where Used - Once variables are created you can include them, in their bracketed format, in any text entry field displayed by an IF-ELSE-STEP dialog box.
• Case Sensitivity - Variable names are case sensitive.
• Reserved Characters - Because the <, > and # characters are used to identify variable names, these characters must be entered twice as regular text in a command line. For example the following command c:\dir >> filelist.txt is interpreted at procedure runtime as c:\dir > filelist.txt.
• Types of Variable Values Possible - The following are the types of variable values typically obtained by using the getVariable() parameter.
  • Registry Value and 64-Bit Registry Value - See 64-Bit Commands - Data from the specified registry value on the managed machine. The last single backslash in a string is used to delimit the registry key from the registry value. To include backslashes as part of the value string, specify double slashes for each slash character. For example, the string HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey\Value\\Name is interpreted as the key HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey with a value of Value\Name.
  • File Content - Data from a specified file on the managed machine. See 64-Bit Commands.
  • Constant Value - Specified constant as typed in the procedure editor.
  • Agent Install Directory Path - Directory in which the agent is installed on the managed machine.
  • Agent Install Drive - Drive in which the agent is installed on the managed machine, such as c:\.
  • Agent Working Directory Path - Working directory on the managed machine as specified using Agent > Manage Agents.

    Warning: Do not delete files and folders in the working directory. The agent uses the data stored in the working directory to perform various tasks.

  • User Temporary Directory Path - The temporary directory for the user currently logged on the managed machine. This path is the expansion of the %TEMP% environment variable for the currently logged on user. If no user is logged on, it is the default Windows temporary directory.
  • Machine.Group ID - Machine ID of the agent executing the procedure.
  • File Version Number - The software version number of the specified file on the managed machine. For example, an exe or dll file often contain the version number of their release.
  • File Size - Size in bytes of the specified file on the managed machine.
  • File Last Modified Date - The last modified date and time in universal time, coordinated (UTC) of the specified file on the managed machine in the format of yyyy/mm/dd hh:mm:ss.
  • Automatic SQL View Data Variables - SQL view parameters are available as automatically declared procedure variables. Automatic variables enable you to skip using the GetVariable command before making use of the variable in a step. Use the format #SqlViewName.ColumnName# in a procedure to return the value of a dbo.SqlView.Column for the agent running the agent procedure. See System > Database Views for a list of the SQL views and columns that are available.

    Note: SQL View Data - This older method of returning a database view value is only necessary if you are trying to return a value from a different machine than the machine running the agent procedure. Use the GetVariable command with the SQL View Data option to create a new procedure variable and set it to the value of a dbo.SqlView.Column value. Use the format SqlViewName/ColumnName/mach.groupID or SqlViewName/ColumnName. If the optional machine ID is omitted, then the value for the agent executing the procedure is retrieved. If ColumnName contains a space, surround it with square brackets. Example: vSystemInfo/[Product Name]. See System > Database Views for a list of the SQL views and columns that are available.

  • Automatic Administrator Variables - Three administrator variables are declared automatically. These automatic administrator variables allow agent procedures to access values not present from an SQL view.
    • #adminDefaults.adminEmail# - Email address of the VSA user who scheduled the agent procedure.
    • #adminDefaults.adminName# - Name of the VSA user who scheduled the agent procedure.
    • #scriptIdTab.scriptName# - Name of the agent procedure.
  • WMI Property - A WMI namespace, class, and property. The format of the specified WMI property is NameSpace:Class.Property. For example, root\cimv2:Win32_OperatingSystem.FreePhysicalMemory. Specify an instance using the following syntax: NameSpace:Class[N].Property where [N] is the instance number. For example, root\cimv2:Win32_OnboardDevice[3].Description. The first instance may be specified with or without specifying the [1] instance number.
  • Expression Value - Specify an expression that consists of procedure variables and six mathematical operators +, -, *, /, (, and ) that are evaluated and assigned to a new procedure variable. For example, ((#variable1# + #variable2#) + 17.4) / (#variable3# * 4). The procedure variables must contain numeric values.
  • Prompt when procedure is scheduled - Displays a message prompt to enter a value when an agent procedure is run. The value is stored in the variable name you specify. Specify the prompt text and variable name. For example, each time this procedure is run, a VSA user could enter a different machine directory.
• Alert Variables - An agent procedure can be assigned to run when an alert is triggered. In most cases the alert passes predefined variables to the agent procedure. These alert variables are documented by alert topic. See Alerts - New Agent Installed for an example.
• Windows Environment Variables - You can reference Windows environmental variables within the executeFile(), Execute File in Path and executeShellCommand() only. Enclose the whole command in quotes, because the environmental variable may contain spaces which might affect execution. For other agent procedure commands, use getVariable() to get the registry key containing the environmental variables, located under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment.