IF-THEN-ELSE Commands

The following is a summary of IF-THEN-ELSE parameters used in VSA scripts.

Using Variables

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

• Two Methods for Creating Variables:
  • Script Variables - Use the Get Variable command within a script to create a new variable name without any special characters. Example: VariableName. In subsequent steps, including steps in nested scripts, reference the variable by bracketing the variable name with the # character. Example: #VariableName#. Scripts variables cannot be referenced outside of the script or nested scripts that use them.
  • Managed Variables - Use the Variable Manager to define variables that can be used repeatedly in different scripts. 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 script. Within a script, reference a managed variable by bracketing the variable name with the < and > character. Example: <VariableName>.
• Where Used - Once variables are created you can include them, in their bracketed format, in any text entry field displayed by an IF-THEN-ELSE 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 script runtime as c:\dir > filelist.txt.
• Types of Variable Values Possible - The following are the types of variable values typically obtained by using the Get Variable parameter.
  • Registry Value - Data from the specified registry value on the managed machine.
  • File Content - Data from a specified file on the managed machine.
  • Constant Value - Specified constant as typed in the script editor.
  • Expression Value - Specify an expression that consists of script variables and six mathematical operators +, -, *, /, (, and ) that are evaluated and assigned to a new script variable. For example, ((#variable1# + #variable2#) + 17.4) / (#variable3# * 4). The script variables must contain numeric values.
  • 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 Temp Directory Path - Temporary directory on the managed machine as specified on the Temp Directory function on the agent tab.
  • User Temp Directory Path - The temporary directory for the user currently logged in on the managed machine. This path is the expansion of the %TEMP% environment variable for the currently logged in user. If no user is logged in, it is the default Windows temporary directory.
  • Machine.Group ID - Machine ID of the agent executing the script.
  • File Version Number - Version number from the property of the specified file on the managed machine.
  • File Size - Size in bytes of the specified file on the managed machine.
  • File Last Modified Date - Date of the specified file on the managed machine in the format of yyyy/mm/dd hh:mm:ss.
  • SQL View Data - Use the GetVariable command with the SQL View Data option to create a new script 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 script 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.

    Note: - Automatic SQL View Data Variables - SQL view parameters are available as automatically declared script variables. Automatic variables enable you to skip using the GetVariable command with the SQL View Data option. Use the format #SqlViewName.ColumnName# in a script to return the value of a dbo.SqlView.Column for the agent executing the script.

  • 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.

IF Parameters

Application is Running

Checks to see if a specified application is currently running on the managed machine. If the application is running, the THEN statement is executed; otherwise, the ELSE statement is executed. When this option is selected from the drop-down list, the Enter the application name field appears.

Check Registry Value

After entering the registry path, the value contained in the key is returned. A check can be made for existence, absence, equality, or size differences. For example, HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\AppPaths\AgentMon.exe\path contains the directory path identifying where the agent is installed on the target machine. The test determines if the value stored for this key exists, thereby verifying the agent is installed.

A backslash character \ at the end of the key returns the default value of that key. HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\WORDPAD.EXE\ returns a default value, such as %ProgramFiles%\Windows NT\Accessories\WORDPAD.EXE

The available tests are:

• Exists : true if the registry key exists in the hive.
• Absent : true if the registry key does not exist in the hive.
• = : true if value of the registry key equals the test value.
• Not = : true if value of the registry key does not equal the test value.
• > : true if value of the registry key is greater than the test value (value must be a number).
• >= : true if value of the registry key is greater than or equal to the test value (value must be a number).
• < : true if value of the registry key is less than the test value (value must be a number).
• <= : true if value of the registry key is less than or equal to the test value (value must be a number).
• Contains : true if the test value is a sub string of the registry key value (value must be a string).
• Not Contains : true if the test value is not a sub string of the registry key value (value must be a string).

Check Variable

Enter a variable name, in the form #var_name#, in the space provided. Check Variable evaluates the current values assigned #var_name# and compares it with the supplied value. The supplied value may also be another variable name in the form of #var_name2#.  If the check is true, THEN steps are executed. If the check is false, ELSE steps are executed.The available tests are:

• Exists : true if the variable exists.
• Absent : true if the variable does not exist.
• = : true if value of the variable equals the test value.
• Not = : true if value of the variable does not equal the test value.
• > : true if value of the variable is greater than the test value.
• >= : true if value of the variable is greater than or equal to the test value.
• < : true if value of the variable is less than the test value.
• <= : true if value of the variable is less than or equal to the test value.
• Contains : true if the test value is a sub string of the variable (variable must be a string).
• Not Contains : true if the test value is not a sub string of the variable (variable must be a string).

For the tests =, Not =, >, >=, <, and <= the variables compared may be a string, a number, a date in the format of yyyy/mm/dd or yyyy/mm/dd hh:mm or yyyy/mm/dd hh:mm:ss, or a version number containing dots or commas such as 1.2.3 or 4,5,6,7. If a date format is specified, it may be offset using + dd:hh:mm:ss or - dd:hh:mm:ss. Only dd days are required; hh hours, mm minutes, and ss seconds may be omitted and are assumed to be zero when absent. CURRENT_TIMESTAMP may be specified to indicate that the current time be substituted in the comparison at the time the script is executed.  e.g. CURRENT_TIMESTAMP - 7:12:00:00 will be evaluated as 7 days and 12 hours subtracted from the time that the script is executed.

Evaluate Expression

Enter an expression containing one or more variable names, in the form #var_name#, in the space provided. Evaluate Expression uses the current value assigned to each #var_name#, evaluates the mathematical expression, and compares it with the supplied value. The supplied value may also be another expression. The mathematical expression may contain +, -, *, /, (, and ).  e.g.  (3.7 + (200 * #countA#)) / (#countB# - #countC#). If the check is true, THEN steps are executed. If the check is false, ELSE steps are executed. The available tests are:

• = : true if value of the variable equals the test value.
• Not = : true if value of the variable does not equal the test value.
• > : true if value of the variable is greater than the test value.
• >= : true if value of the variable is greater than or equal to the test value.
• < : true if value of the variable is less than the test value.
• <= : true if value of the variable is less than or equal to the test value.

  Note: Cannot be used with Exists, Absent, Contains, or Not Contains operators.

Service is Running

Determines if a service is running on the managed machine.

• True if the service is running.
• False if the service stopped or does not exist.

Test File

Determines if a file exists on a managed machine. Enter the full path and filename. For example, entering c:\windows\notepad.exe returns True if Notepad.exe exists, False if it does not.

Note: Environment variables such as %windir%\notepad.exe are acceptable.

Test File in Directory Path

Enter the name of a file to see if it exists on the managed machine. Because a THEN or ELSE step must be executed prior to this IF test, Test File in Directory Path is only useful for scripts called by the THEN or ELSE step of a parent script.

Test Registry Key

Tests for the existence of a registry key. Test Registry Key differs from Check Registry Value since it can check for a directory level registry entry that only contains more registry keys (no values).

True

Selecting True directs the THEN steps to execute. Use True to directly execute a series of steps that do not require any decision points, such as determining whether a file exists using Test File.

User Is Logged In

Tests to see if a specific user or any user is logged in on the managed machine. Enter the user's logon name or leave the field blank to check for any user logged in. The THEN steps are executed if a user is logged in. The ELSE steps are executed if the user is not logged in.

User Response is Yes

Displays a dialog box on the managed machine with Yes and No buttons. Also carries out the ELSE statement if an administrator-configured specified amount of time has timed out. If Yes is selected by the user, the THEN statement is executed. If the selection times out or the user selects No, the ELSE statement is executed. This function requests the user's permission to proceed with the script. This query is useful for scripts that require a reboot of the managed machine before completion.

Script variables, for example #varName#, may be used inside User Response is Yes fields to dynamically generate messages based on script data.

THEN-ELSE Parameters

Operating System Detect

When writing a THEN-ELSE statement, you can select the operating system the script will execute on. This parameter is useful when you want to write one script that can be executed on different operating systems. For example, directory paths in Windows and Macintosh can require different directory path syntax in order to work correctly. Creating two separate script steps within the same script for All Windows Operating Systems and a Mac OS X operating system, avoids having to create an extra script for a separate operating system.

Close Application

If the specified application is running on the managed machine, then that application is closed down.

Delete File

Deletes a file on a managed machine. Enter the full path and filename.

Note: Environment variables are acceptable if they are set on a user's machine.  For example, using a path %windir%\notepad.exe would be similar to C:\windows\notepad.exe.

Delete File in Directory Path

Deletes the specified file located at the path returned using the Get Directory Path From Registry parameter.

Delete Registry Key

Delete the specified registry key and all its sub-keys.

Delete Registry Value

Delete the value stored at the specified registry key.

Execute File

Executes the specified file on the managed machine. This function replicates launching an application using the Run… command located in the Microsoft Windows Start menu. This function takes three parameters:

• Full path filename to the .exe file.
• Argument list to pass to the .exe file
• Flag indicating whether the script should wait until the .exe completes or not. (1 to wait, 0 to have the script continue without waiting).

  Note: Environment variables are acceptable, if they are set on a user's machine.  For example, using a path %windir%\notepad.exe, would be similar to C:\windows\notepad.exe.

Execute File in Directory Path

Same as Execute File except the location of the .exe file is located at the path returned from a Get Directory Path From Registry parameter.

Note: Environment variables are acceptable if they are set on a user's machine.  For example, using a path %windir%\notepad.exe would be similar to C:\windows\notepad.exe.

Execute Script

Causes another named script to execute. Use this capability to string multiple IF-THEN-ELSE clauses together. If the script no longer exists on the KServer, an error message displays next to the script drop-down list. You can use this command to run a system script.

Execute Shell Command

Allows the script to pass commands to the command interpreter on the managed machine. When this command is selected, the field Enter the command to execute in a command prompt is displayed. Enter a command in the field. The command must be syntactically correct and executable with the OS version on the managed machine. Commands and parameters containing spaces should be surrounded by quotes. Since the command is executed relative to the agent directory, absolute paths should be used when entering commands.

Note: Execute Shell Command opens a command prompt window on the managed machine to execute in. If you do not want a window opening on the managed machine, because it might confuse users, put all the commands into a batch file. Send that file to the managed machine using the Write File command. Then run the batch file with the Execute File command. Execute File does not open a window on the managed machine.

Get Directory Path From Registry

Returns a file path stored in the specified registry key. Use this command to fetch the file location. For instance, use this command to find the directory where an application has been installed.

Get File

Upload the file at the specified path from the managed machine. Be sure to enter a full path filename that you want to upload. The file is stored on the KServer in a private directory for each managed machine. Access the uploaded file using Scripts > Get File.

• Optionally, existing copies of uploaded files are renamed with a .bak extension prior to the next upload of the file. This allows you to examine both the latest version of the file and the previous version.
• Optionally send an email alert if the uploaded file differs from the file that was uploaded previously.
• Optionally send an email alert if the uploaded file is the same as the file that was uploaded previously.

Get File in Directory Path

Just like the Get File command but it adds the path returned from the Get Directory Path From Registry command to the beginning of the remote file path. Access the uploaded file using Scripts > Get File function.

Get URL

Returns the URL of a website page and stores it in a file.

Get Variable

Defines a new agent variable. When the script step executes, the system defines a new variable and assigns it a value based on data fetched from the managed machine's agent.

Note: See Using Variables at the top of this topic for the types of variable values supported by the Get Variable parameter.

Impersonate User

Enter a username, password, and domain for the agent to log in with, when Execute as user... is specified using Execute File, Execute File in Directory Path or Execute Shell Command. Leave the domain blank to log into an account on the local machine.

Pause Script

Pause the script for N seconds. Use this command to give Windows time to complete an asynchronous task, like starting or stopping a service.

Reboot

Unconditionally reboots the managed machine. To warn the user first, preface this command with a User Response is Yes message. A User Response is Yes message prompts the user before rebooting their machine.

Rename Locked File

Renames a file that is currently in use. The file is renamed the next time the system is rebooted. The specified filename is a complete file path name. Rename locked file can also be used to delete a file that is currently in use if the destination is empty. The file is deleted when the system is rebooted.

Rename Locked File in Directory Path

Renames a file that is currently in use. The file is renamed the next time the system is rebooted. The specified file name is appended to the directory path. Rename locked file in directory path can also be used to delete a file that is currently in use if the destination is empty. The file is deleted when the system is rebooted.

Schedule Script

Schedules a script to be run. Optionally specifies the time to wait after executing this step before running the script and the specific machine ID to run the script on. You can use this command to run a system script.

Send Email

Sends an email to one or more recipients. Specifies the subject and body text of the email.

Send Message

Sends the entered message to a managed machine. Selecting Immediately displays a message dialog box immediately. Selecting After user clicks the flashing system tray icon flashes the agent system tray icon when a message is received. The message is displayed when the user clicks the icon.

Send URL

Sends the entered URL to a managed machine. Selecting Immediately launches the default web browser and the specified URL is displayed. Selecting After user clicks the flashing system tray icon flashes the agent system tray icon when a message is received. The URL is displayed in the default web browser when the user clicks the icon.

Set Registry Value

Writes data to the specified registry value. This function takes three parameters:

• Enter the full path to a registry key containing a value - Specify the (Default) value for a registry key by adding a trailing backslash \. Otherwise specify a name for an existing value or to create a new value. See Name column in image below.
  Example of setting the (Default) value: HKEY_LOCAL_MACHINE\SOFTWARE\000Sample\
• Enter the data to write to the registry value
• Select the data type
  • REG_SZ - String value.
  • REG_BINARY - Binary data displayed in hexadecimal format.
  • DWORD - Binary data limited to 32 bits. Can be entered in hexadecimal or decimal format.
  • REG_EXPAND_SZ - An "expandable" string value holding a variable. Example: %SystemRoot%.
  • REG_MULTI_SZ - A multiple string array. Used for entering more than one value, each one separated by a \0 string. Use \\0 to include \0 within a string array value.

Use Credential

Use the credentials set for the machine ID in Set Credential to execute a file or shell when Execute as user... is specified using Execute File, Execute File in Directory Path or Execute Shell Command. The Use Credential script command behaves the same as the Impersonate User command except a unique credential can be used to access each machine instead of using a fixed credential in a script.

Note: A script execution error is logged if a Set Credential script command encounters an empty username.

Write Directory

Writes a selected directory, including subdirectories and files, from Manage Files Stored on Server to the full path directory name specified on the managed machine.

Write File

Writes a file selected from a drop down list from Manage Files Stored on Server to the full path filename specified on the managed machine. Enter a new filename if you want the file to be renamed.

Each time a script executes the Write File command, the agent checks to see if the file is already there or not by hashing the file to verify integrity. If not, the file is written. If the file is already there, the script moves to the next step. You can repeatedly run a script with Write File that sends a large file to a managed machine and know that the VSA only downloads that file once.

Note: Environment variables are acceptable if they are set on a user's machine. For example, using the path %windir%\notepad.exe would be equivalent to C:\windows\notepad.exe.

Write File in Directory Path

Writes the specified filename to the path returned from a Get Directory Path From Registry command.

Write Script Log Entry

Writes the supplied string to the script log for the agent executing this script.

Topic 674: Send Feedback. Download a PDF of this online book from the first topic in the table of contents.