· Uwe Janke
Commands / Get-sqmTsmConfiguration

Get-sqmTsmConfiguration Configuration

Reads the IBM TSM / Spectrum Protect client option file (dsm.opt or a differently named file) 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 options file path if -DsmOptPath: use directly; else _FindDsmOptPath: service -optfile → DSM_CONFIG/DSM_DIR → *.opt Success=false / throw ② Read file: Get-Content (local) or admin share via _ToUncPath (remote) with -Credential through a temporary PSDrive; 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 IBM TSM client option file via the private helper _FindDsmOptPath (or accepts an explicit path). The file may have a different name than dsm.opt; see Options File Detection Order below. Reads the file directly, for remote computers through the admin share (UNC path). 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 the private helpers _FindDsmOptPath and _ToUncPath (both internal to sqmSQLTool). For remote computers, the caller must have access to the admin share of the target (or pass -Credential), and the remote registry is used to read the TSM service settings. 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 the options file (dsm.opt or a differently named file). 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 options file that was read (the name can differ from dsm.opt).
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.

Options File Detection Order

The TSM options file does not have to be called dsm.opt. The first existing file wins; -DsmOptPath skips the detection completely.

PrioritySourceDetail
1TSM services-optfile= in the ImagePath of the TSM services (scheduler, CAD, journal) and the registry value optfile below Parameters. Local and remote.
2Environment%DSM_DIR%\dsm.opt and %DSM_CONFIG% (local only)
3RegistryDSM_DIR under HKLM:\SOFTWARE\IBM\ADSM\CurrentVersion\BackupClient (64 and 32 bit) + dsm.opt
4Standard pathsdsm.opt in the Tivoli, IBM TSM and Spectrum Protect baclient directories
5FallbackAny *.opt in those directories that contains TCPServeraddress. Files named ie_*, incl* and excl* are skipped; dsm.opt is preferred.

Examples

Example 1, Read TSM config from local machine (auto-detect path)

Get-sqmTsmConfiguration

Example 2, Read from remote SQL server

Get-sqmTsmConfiguration -ComputerName "SQL01"

Example 3, Explicit path + plain-text password for scripting

Get-sqmTsmConfiguration -DsmOptPath 'C:\Program Files\Tivoli\TSM\baclient\dsm.opt' -IncludePasswordPlain

Example 4, Options file with a different name

Get-sqmTsmConfiguration -DsmOptPath 'C:\Program Files\Tivoli\TSM\baclient\node01.opt'
# Without -DsmOptPath the name is taken from the TSM service (-optfile=) or from any *.opt with TCPServeraddress

Example 5, Use server name from result

$tsm = Get-sqmTsmConfiguration
Write-Host "TSM Server: $($tsm.ServerName), User: $($tsm.UserName)"