Variables and Functions

Security Controls provides a set of PowerShell variables and functions to every script. The variable names all begin with “ST_”. The function names all begin with “ST-“. You can use these variables and functions in your scripts.

PowerShell variables can have different scopes:

Global: Available to the current PowerShell session

Script: Declared in the script (outside of functions) and local to that script

Private: Declared in a function and local to that function

Local: The current scope, which can be global, script, or private

The variables supplied with Security Controls are declared at the global scope. Since each target machine is running in its own PowerShell session, this is equivalent to being declared in the scope of the script.

Run Variables

The following table lists the per-run variables. All machines will see the same value for these variables. Do not modify the values of variables marked as [Read-only].

Variable Name Description
ST_OutputDirectory The full path to the base output directory. A subdirectory will be created for the run. [Read-only]
ST_RunDirectory The full path to the run output directory. [Read-only]
ST_RunErrorFile The full path to the run error file. Errors that are not specific to a particular machine should be written to this file. This file will also contain messages about machines that could not be resolved to an IP address, and no machine-specific subfolder will be created for machines that could not be resolved. [Read-only]
ST_RunName The name of the run specified in the user-interface when the run was initiated or scheduled, with the run time appended. The default is the name of the script or template. [Read-only]
ST_RunOnConsole Set to $false if the script is using PowerShell remoting; otherwise $true. [Read-only]
ST_RunOutputFile The full path to the standard run output file. All output that would appear on the console if run at a command prompt will be placed in this file. [Read-only]
ST_RunResult This is a short run result that will appear in the Operations Monitor. It is limited to 100 characters in length. If you do not explicitly set this variable in your script, it will be set to indicate the number of machines that had errors and the number of machine resolution errors.

Machine Variables

The following table lists the per-machine variables. The value of these variables may be different for each target machine. You should not modify the values of variables marked as [Read-only].

Variable Name Description
ST_ComputerName The name of the target computer. [Read-only]
ST_Credential A PSCredential object that contains the user name and SecureString password used to connect to the target machine. This variable can be passed to any command that supports the the Credential parameter. [Read-only]
ST_DomainName The name of the target computer domain or workgroup. [Read-only]
ST_MachineDirectory The full path to the machine directory. This will typically be the machine name, but if the machine name contains characters that are not allowed in folder names, then those characters will be replaced with underscore characters. [Read-only]
ST_MachineError A Boolean value indicating that one or more errors were detected during the execution of this script targeting this specific machine.
ST_MachineErrorFile The full path to the machine error file. If errors are detected during execution of the script, they will appear in this file. [Read-only]
ST_MachineOutputFile The full path to the machine output file. Output generated by the script to the standard output will be captured in this file.
ST_MachineResult This is a short machine result that will appear in the Operations Monitor. It is limited to 100 characters in length. If you do not explicitly set this variable in your script, it will be set to “Success” if no machine errors were detected, or to the error message of the first error encountered for that machine. Use the ST-SetMachineResult function to explicitly set the value of this variable.
ST_MachineResultSet A Boolean value indicating that the script set the ST_MachineResult variable. Use the ST-SetMachineResult function to set both the ST_MachineResult variable and this variable.

Functions

Security Controls provides a set of functions that are available to every script you create. They are listed in the following table.

Variable Name Description
ST_GetTargetOS This function attempts to connect to the target system, query WMI and retrieve the Win32_OperatingSystem object.
ST_SetMachineResult This function takes a string parameter. It sets the ST_MachineResult variable to the string passed in and set ST_MachineResultSet to $true.
ST_SetMachineError This function takes a string argument. It sets the ST_MachineResult variable to the string passed in. It also sets the ST_MachineResultSet and ST_MachineError variables to $true.
ST_SendMessage This function takes a string parameter. The string will be displayed in the Operations Monitor. Use this function to monitor the progress of long-running scripts. When the script is complete the string in ST_MachineResult will be displayed in the operations monitor. Except during debug, you should avoid calling this method in scripts that execute quickly. The string will be truncated to 100 characters if a longer string is passed in.
ST_CreateMachineDirectory Normally, the machine directory is not created until output is written. If your script is creating files in the machine directory, you should invoke this function to create the directory before writing anything to the directory. Calling this function more than once will have no negative effect.
ST_CreateRunDirectory Normally, the run directory is not created until the run writes some output. If your script is creating files in the run directory, you should invoke this function to create the directory before writing anything to the directory. Calling this function more than once will have no negative effect.
ST_ComputerAndCredential This function returns appropriate values to use for the ComputerName and Credential parameters for the target machine. See Specifying ComputerName and Credential Parameters for details.
ST_SubCC This function takes a string parameter, which is a valid PowerShell command. This function substitutes “$ST_CC” in that command string with appropriate values to use for the ComputerName and Credential parameters for the command. It then executes the resulting command and returns the results of the execution. See Specifying ComputerName and Credential Parameters for details.