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