Fact 7. Learn Path Substitution Strings

Quick Facts

Path Substitution Strings

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

  • Ensure that you locate the correct parent folder for FlexPLL'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 commands:

: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 file name when using a path substitution string. You may also append a sub-folder. Failure to append a file name will result either in a file created in an parent folder or a file error. For screen images, the file name must include a file name extension. For most other file types, do not append a file name 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 FlexPLL is running, the location of FlexPLL'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 \FlexPLL folder. You would need to append the standard subfolder name and filename.

:DISK:SIMage:FNAMe "%USER_DATA_DIR%\Screen Images\test.png"
User Folders

The following subfolders exist under the %USER_DATA_DIR% folder:

  • Documentation Results
  • Presets
  • Response Calibration
  • Responses
  • SCPI Scripts
  • Screen Images
  • Setups
%USER_DATA_DIR% Path Substitution String
Environment String Expansion
DCA-X Windows 10 D:\User Files\
Windows 7 D:\User Files\
PC Windows 10 (with OneDrive) C:\Users\<user>\OneDrive - Keysight Technologies\Documents\Keysight\FlexDCA\
Windows 10 C:\Users\<user>\Documents\Keysight\FlexDCA\
Windows 7 C:\Users\<user>\My Documents\Keysight\FlexDCA\

 

%DESKTOP% Path String

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

:DISK:SIMage:FNAMe "%DESKTOP%\test.png"
%DESKTOP% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\Desktop\
Windows 7 C:\Users\dca-admin\Desktop\
PC Windows 10 (with OneDrive) C:\Users\<user>\OneDrive - Keysight Technologies\Desktop\
Windows 10 C:\Users\<user>\Desktop\
Windows 7 C:\Users\<user>\Desktop\

 

%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"
%MY_DOCUMENTS% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\Documents\
Windows 7 C:\Users\dca-admin\Documents\
PC Windows 10 (with OneDrive) C:\Users\<user>\OneDrive - Keysight Technologies\Documents\
Windows 10 C:\Users\<user>\Documents\
Windows 7 C:\Users\<user>\Documents\

 

%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"
%TEMP_DIR% Path Substitution Strings
Environment String Expansion
DCA-X Windows 10 C:\Users\dca-admin\AppData\Local\Temp\Keysight\FlexDCA
Windows 7 C:\Users\dca-admin\AppData\Local\Temp\Keysight\FlexDCA
PC Windows 10 (with OneDrive) C:\Users\<user>\AppData\Local\Temp\Keysight\FlexDCA
Windows 10 C:\Users\<user>\AppData\Local\Temp\Keysight\FlexDCA
Windows 7 C:\Users\<user>\AppData\Local\Temp\Keysight\FlexDCA

 

%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"

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\
Windows 7 C:\Program Files\Keysight\FlexDCA\Demo\
PC Windows 10 (with OneDrive) C:\Program Files\Keysight\FlexDCA\Demo\
Windows 10 C:\Program Files\Keysight\FlexDCA\Demo\
Windows 7 C:\Program Files\Keysight\FlexDCA\Demo\

 

%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\
Windows 7 C:\Program Files\
PC Windows 10 (with OneDrive) C:\Program Files\
Windows 10 C:\Program Files\
Windows 7 C:\Program Files\

 

%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\
Windows 7 C:\Program Files\Keysight\Licensing\
PC Windows 10 (with OneDrive) C:\Program Files\Agilent\Licensing\
Windows 10 C:\Program Files\Agilent\Licensing\
Windows 7 C:\Program Files\Keysight\Licensing\