sqmSQLTool › Commands › Get-sqmTsmConfiguration

Get-sqmTsmConfiguration Configuration

Reads the IBM TSM / Spectrum Protect client option file (dsm.opt) locally or from a remote computer and extracts the server address, user ID, and password. Returns a structured result object; the password is always returned as a SecureString.

Execution Flow

START ① Determine dsm.opt path if -DsmOptPath: use directly; else: call _FindDsmOptPath -ComputerName $ComputerName -IsLocal $isLocal Success=false / throw ② Read file: _ReadRemoteFile -ComputerName $ComputerName -FilePath $optFile -Credential $Credential UNC/remote-capable; returns $lines[] ③ Parse options: foreach ($line in $lines) Skip empty lines and lines starting with '*' (comments) Regex: ^([A-Za-z0-9_-]+)\s+(.+)$ → $options[$key] = $value.Trim().Trim("'").Trim('"') Extract: TCPServeraddress → $serverName; USERID → $userName; PASSWORD → $passwordPlain ConvertTo-SecureString -String $passwordPlain -AsPlainText -Force → $passwordSecure ④ Build result object: Success, ErrorMessage, FilePath, ServerName, UserName, Password (SecureString), PasswordPlain (only if -IncludePasswordPlain), AllOptions [hashtable], RawContent [string[]] On catch: return [PSCustomObject]@{ Success=$false; ErrorMessage=...; FilePath=$null } or throw (if -EnableException) Return result [PSCustomObject] DONE

Synopsis

Locates the dsm.opt IBM TSM client option file via the private helper _FindDsmOptPath (or accepts an explicit path). Reads the file through _ReadRemoteFile which handles UNC paths for remote targets. Parses all non-comment key-value pairs into a hashtable and extracts TCPServeraddress, USERID, and PASSWORD. The password is always returned as a SecureString; plain text is available only when -IncludePasswordPlain is set.

No dbatools required. Requires private helpers _FindDsmOptPath and _ReadRemoteFile (both internal to sqmSQLTool). For remote computers, the caller must have access to the UNC path of the target's file system or the helpers handle WinRM-based transfer. On any error Success = $false is returned unless -EnableException is set.

Syntax

Get-sqmTsmConfiguration
    [-ComputerName <String>]        # default $env:COMPUTERNAME
    [-DsmOptPath <String>]          # explicit path; skips auto-detect
    [-IncludePasswordPlain]
    [-Credential <PSCredential>]
    [-EnableException]

Parameters

ParameterTypeDefaultDescription
-ComputerNameString$env:COMPUTERNAMETarget computer. Local when matching $env:COMPUTERNAME, localhost, 127.0.0.1, or ..
-DsmOptPathString—Explicit path to dsm.opt. When provided, _FindDsmOptPath is skipped.
-IncludePasswordPlainSwitchfalseAlso populate PasswordPlain in the result. Off by default for security.
-CredentialPSCredential—Credential for accessing a remote file via UNC.
-EnableExceptionSwitchfalseThrow terminating exceptions instead of returning Success=$false.

Return Value

PropertyDescription
Success$true on success; $false on any error.
ErrorMessageError description when Success = $false, otherwise $null.
FilePathResolved path to the dsm.opt file that was read.
ServerNameValue of TCPServeraddress from the option file.
UserNameValue of USERID from the option file.
PasswordPassword as [SecureString]; $null if not set in the file.
PasswordPlainPlain-text password — populated only when -IncludePasswordPlain is set.
AllOptionsHashtable of all parsed key-value pairs from the option file.
RawContentArray of non-comment lines from the file as parsed.

Examples

# Read TSM config from local machine (auto-detect path)
Get-sqmTsmConfiguration

# Read from remote SQL server
Get-sqmTsmConfiguration -ComputerName "SQL01"

# Explicit path + plain-text password for scripting
Get-sqmTsmConfiguration -DsmOptPath 'C:\Program Files\Tivoli\TSM\baclient\dsm.opt' -IncludePasswordPlain

# Use server name from result
$tsm = Get-sqmTsmConfiguration
Write-Host "TSM Server: $($tsm.ServerName), User: $($tsm.UserName)"