Fact 4. Learn Path Substitution Strings

SCPI Basics

Path Substitution Strings

When programming, always use a path substitution strings when specifying file. Path substitution strings:

  • Ensure that you locate the correct parent folder for FlexOTO's standard user folders.
  • Shorten the writing of a file path
  • Eliminate the need to remember path variances between Windows 7, 8, and 10 on the DCA-X or PC.

For example, when programatically saving a screen capture to the Windows desktop you could use the following command:

:DISK:SIMage:FNAMe "c:\Users\<user>\Desktop\test.png"
:DISK:SIMage SAVE

but, the recommended and reliable technique is to use the %DESKTOP% path substitution string:

:DISK:SIMage:FNAMe "%DESKTOP%\test.png"
:DISK:SIMage SAVE

You must always append a filename when using a path substitution string. Failure to so will result either in a file created in an parent folder or a file error. For screen images, the filename must include a filename extension. For most other file types, do not append a filename extension as the file type is specified using an :FNAMe:FTYPe child command. For example, :DISK:WAVeform:SAVE:FTYPe.

The following user accounts are available on DCA-X instruments:

  • dca-admin on an DCA-X under Windows 10.
  • dca-user on an DCA-X under Windows 7.

Use the Interactive SCPI Command Tree to see the expanded path

If you want to see how path strings are expanded, use the string in one of the many :FNAMe commands and then query the command for the expanded path. Don't forget to add a subfolder and test filename. For example,

  1. Click Tools > SCPI Programming Tools > Interactive SCPI Command Tree.
  2. In the Interactive SCPI Command Tree, locate the :DISK:SIMage:FNAMe command as shown in the following picture.
  3. Enter the path string with subfolder and filename. For example:
    • %USER_DATA_DIR%\Screen Images\DUT-4.png
  4. Click Run.
  5. Click Query to view the expanded path which is shown in the dialog's Run/Query Output field.

 

%USER_DATA_DIR% Path String

Use the %USER_DATA_DIR% string to place a file in a folder beneath the standard user folder as shown in this example. Depending on where FlexOTO is running, the location of FlexOTO's standard user folders varies as shown in the following pictures. The %USER_DATA_DIR% path substitution string points to the root user folder: \User Files or \FlexOTO folder. You would need to append the standard subfolder name and filename.

:DISK:SIMage:FNAMe "%USER_DATA_DIR%\Screen Images\test.png"
:DISK:SIMage SAVE  //  Save screen image to standard user folder
%USER_DATA_DIR% Path Substitution String
Environment String Expansion
DCA-X Windows 10 D:\User Files\subfolder\filename
Windows 7 D:\User Files\subfolder\filename
PC Windows 10 C:\Users\<user>\Documents\Keysight\FlexDCA\subfolder\filename
Windows 7 C:\Users\<user>\My Documents\Keysight\FlexDCA\subfolder\filename

 

%DESKTOP% Path String

Use the %DESKTOP% string to place a file on the Windows desktop. For example,

:DISK:SIMage:FNAMe "%DESKTOP%\test.png"
		:DISK:SIMage SAVE  //  Save screen image to desktop
%DESKTOP% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\Desktop\filename
Windows 7 C:\Users\dca-admin\Desktop\filename
PC Windows 10 C:\Users\<user>\Desktop\filename
Windows 7 C:\Users\<user>\Desktop\filename

 

%MY_DOCUMENTS% Path String

Use the %MY_DOCUMENTS% string to place a file in the Windows My. For example,

:DISK:SIMage:FNAMe "%MY_DOCUMENTS%\MyFolder\test.png"
:DISK:SIMage SAVE  //  Save screen image to a custom user folder
%MY_DOCUMENTS% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\Documents\filename
Windows 7 C:\Users\dca-admin\Documents\filename
PC Windows 10 C:\Users\<user>\Documents\filename
Windows 7 C:\Users\<user>\Documents\filename

 

%TEMP_DIR% Path String

Use the %TEMP_DIR% string to place a file in a temporary Windows folder. For example,

:DISK:SIMage:FNAMe "%TEMP_DIR%\test.png"
:DISK:SIMage SAVE  //  Save screen image to desktop
%TEMP_DIR% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\AppData\Local\Temp\Keysight\filename
Windows 7 C:\Users\dca-admin\AppData\Local\Temp\Keysight\filename
PC Windows 10 C:\Users\<user>\AppData\Local\Temp\Keysight\filename
Windows 7 C:\Users\<user>\AppData\Local\Temp\Keysight\filename

 

%DEMO_DIR% Path String

Use the %DEMO_DIR% string to place a file under the \Demo folder in with the FlexDCA installation files. The following example loads a jitter database file from the \Demo folder into FlexDCA's Jitter database memory.

:DISK:JDATabase:FNAMe "%DEMO_DIR%\Jitter Data\Demo\CH1_81141A_10.3125Gbps_PRBS7.jdx"
:DISK:JDATabase RECall  //  Save screen image to desktop

The following subfolders exist under the \Demo folder:

  • Adapter Definitions
  • Calibration Kit Definitions
  • Example Programs
  • Jitter Data
  • Limit Lines
  • Masks
  • Presets
  • SCPI Scripts
  • Setups
  • S-Parameter Data
  • User Functions
  • User Measurements
  • Waveforms
%DEMO_DIR% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Program Files\Keysight\FlexDCA\Demo\subfolder\filename
Windows 7 C:\Program Files\Keysight\FlexDCA\Demo\subfolder\filename
PC Windows 10 C:\Program Files\Keysight\FlexDCA\Demo\subfolder\filename
Windows 7 C:\Program Files\Keysight\FlexDCA\Demo\subfolder\filename

 

%PROGRAM_FILES% Path String

Use the %PROGRAM_FILES% string to access a file in the \Program Files folder. Most users will never need to use this string.

%PROGRAM_FILES% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Program Files\filename
Windows 7 C:\Program Files\filename
PC Windows 10 C:\Program Files\filename
Windows 7 C:\Program Files\filename

 

%PROGRAM_FILES_x86% Path String

Use the %PROGRAM_FILES_x86% string to access a file in the \Program Files folder. Most users will never need to use this string.

%PROGRAM_FILES_x86% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Program Files (x86)\filename
Windows 7 C:\Program Files (x86)\filename
PC Windows 10 C:\Program Files (x86)\filename
Windows 7 C:\Program Files (x86)\filename

 

%LICENSE_DIR% Path String

Use the %LICENSE_DIR% string to place a Keysight license file in the \Licensing folder. Most users will never need to use this string.

%LICENSE_DIR% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Program Files\Agilent\Licensing\filename
Windows 7 C:\Program Files\Keysight\Licensing\filename
PC Windows 10 C:\Program Files\Agilent\Licensing\filename
Windows 7 C:\Program Files\Keysight\Licensing\filename