To specify an expression that generates the report file path during execution, select Specify Report File Path by Expression from the File/Directory Options ring control on the Report File Pathname tab of the Report Options dialog box. When you select this option, the expression controls become visible depending on the process model you use. If you are using the Sequential or Parallel process model, or if you are using the Batch process model and you select ATML Report Document as the report format, only the Report File Path expression control is visible. If you are using the Batch process model and you select a report format other than ATML Report Document, both the Report File Path and Batch Report File Path expression controls are visible.

For example, to store an XML report file in the C:\Temp\Reports directory with the filename stored in a variable FileGlobals.ReportFileName in the current process model, use the expression "C:\\Temp\\Reports\\" + FileGlobals.ReportFileName + ".xml".

You can use predefined macros to customize the UUT or Batch Report File Path expression. During an execution, the process model replaces the predefined macros in the UUT or Batch Report File Path expressions according to the options you select. You can use the following macros in the UUT or Batch Report File Path expressions, with some exceptions.
Note   The list of macros is for use only in the Specify Report File Path by Expression control on the Report File Pathname tab of the Report Options dialog box and not in any other TestStand expression controls.
  • $(Batch)—Replaces the macro with the batch serial number. The $(Batch) macro creates new Batch Report files for each serial number in the batch.
    Note   You can use the $(Batch) macro only with the Batch process model.
  • $(ClientFileDir)—Replaces the macro with the directory that contains the client sequence file. For example, if you execute the client sequence saved as c:\Tests\TestSequences\TestSequence1.seq using an Execution entry point, $(ClientFileDir) specifies the c:\Tests\TestSequences directory.
    Note   If you use the $(ClientFileDir) macro without saving the sequence file to disk, the macro evaluates to the <TestStand>\Temp directory.
  • $(ClientFileName)—Replaces the macro with the name of the client sequence file. For example, if you execute the client sequence file saved as c:\Tests\TestSequences\TestSequence1.seq using an Execution entry point, the $(ClientFileName) macro evaluates to the string "TestSequence1".
    Note   If you use the $(ClientFileName) macro without saving the sequence file to disk, the report generator replaces the macro with the string "Unsaved Sequence File". You can modify the string by changing the ModelStrings.ini language file.
  • $(Desktop)—Replaces the macro with the directory path of the desktop.
  • $(FileExtension)—Replaces the macro with a file format extension that corresponds to the report format you specify on the Contents tab of the Report Options dialog box. For example, if you specify the report file format as HTML, the process model replaces the macro with the string "html".
  • $(FileDate)—Replaces the macro with a string containing the current date in localized format when the report is first saved.
  • $(FileDay)—Replaces the macro with a string containing the numeric day of the month when the report is first saved.
  • $(FileMonth)—Replaces the macro with a string containing the numeric month when the report is first saved.
  • $(FileTime)—Replaces the macro with a string containing the current time in localized format when the report is first saved.
  • $(FileYear)—Replaces the macro with a string containing the numeric year when the report is first saved.
  • $(PublicDocumentsDir)—Replaces the macro with the file system directory that contains documents common to all users. A typical path is C:\Users\Public\Documents on Microsoft Windows 10/8.1/7.
  • $(StationID)—Replaces the macro with the station ID.
  • $(TempDir)—Replaces the macro with the <TestStandTemp> directory.
  • $(TestSocket)—Replaces the macro with TestSocketIndex during run time. This macro creates new report files for each test socket.
    Note   The $(TestSocket) macro is invalid in the Batch Report File Path expression.
  • $(TestStandExecutableDir)—Replaces the macro with the directory of the TestStand executable. For example, if you are using the TestStand Sequence Editor, the <TestStand>\Bin directory path replaces this macro.
  • $(TestStandPublicDir)—Replaces the macro with the <TestStand Public> directory, in which TestStand stores publicly editable files.
  • $(Unique)—Replaces the macro with a unique numeric value if the file already exists in the path. If you use more than one $(Unique) macro in the Report File Path expression, TestStand replaces only the first instance from left with the unique numerical value. For example, if you specify the Report File Path expression as "C:\\Temp$(Unique)\\TSReports$(Unique)\\Report$(Unique).xml" and C:\\Temp\\TSReports\\Report.xml already exists, the process model saves the report file path at C:\Temp0001\Reports\Report.xml.
    Note   You cannot use the $(Unique) macro as a stand-alone directory or filename in the Report File Path or the Batch Report File Path expression.
  • $(UserDocumentsDir)—Replaces the macro with the My Documents desktop item.
  • $(UserName)—Replaces the macro with the user name of the currently logged in user.
    Note   If no user is currently logged in, an empty string replaces the $(UserName) macro.
  • $(UUT)—Replaces the macro with the UUT serial number. This macro creates new UUT report files for each UUT.
    Note
    • If you use the $(UUT) macro and the UUT serial number is the same for two different UUT loops, the new report file might overwrite the older report file when the Append if File Already Exists option on the Contents tab is disabled. To avoid overwriting the file, use the $(Unique), $(FileTime), or $(FileDate) macros, or enable the Append if File Already Exists option.
    • The $(UUT) macro is invalid in the Batch Report File Path expression.
  • $(UUTStatus)—Replaces the macro with the UUT status during run time. When you use the $(UUTStatus) macro, TestStand creates separate files for each UUT status. If the UUT Report File Path expression contains the $(UUTStatus) and $(UUT) macros, TestStand creates new UUT report files for each UUT status. If the UUT Report File Path expression contains the $(UUTStatus) and $(TestSocket) macros when using the Parallel or Batch process model, for each test socket index, TestStand creates separate files for each UUT status. If the UUT Report File Path expression contains the $(UUTStatus) and $(Batch) macros, for each batch serial number, TestStand creates separate files for each UUT status.
    Note
    • If you use on-the-fly (OTF) reporting with the $(UUTStatus) macro in the Report File Path expression, the process model creates the temporary file used during OTF reporting in the <TestStand>\Temp directory. The process model copies the temporary file to the correct location when the execution completes.
    • If you use the $(UUTStatus) macro in the Report File Path expression and execute the sequence file using the Test UUTs Execution entry point, TestStand displays only the complete report for the last UUT status at the end of the execution.
    • The $(UUTStatus) macro is invalid in the Batch Report File Path expression.
  • $(UUTPartNum)—Specifies the UUT part number.
    Note
    • If you use the $(UUTPartNum) macro and the UUT part number is the same for two different UUT loops, the new report file might overwrite the older report file when the Append if File Already Exists option on the Contents tab is disabled. To avoid overwriting the file, use the $(Unique), $(FileTime), or $(FileDate) macros, or enable the Append if File Already Exists option.
    • The $(UUTPartNum) macro is invalid in the Batch Report File Path expression control.

Processing Report and Batch Report File Path Expressions

The process model generates the report and batch report file paths by evaluating the Report and Batch Report File Path expressions and then replacing the macros. Since the expression is evaluated first, you can also define macros in variables. When you use the Sequential model, TestStand evaluates all Report File Path expressions in the context of the entry point sequence at run time. When you use the Batch or Parallel process model, TestStand evaluates all Report File Path expressions in the context of the test socket Execution entry point sequence at run time. For example, if you execute the sequence file in the Batch process model using the Test UUTs Execution entry point, the process model evaluates all Report File Path expressions in the context of the Test UUTs - Test Socket Entry Point sequence.

The Report File Path and Batch Report File Path expression controls use the context of the first Execution entry point in the current process model to perform syntax checking on the expressions. The Report Options dialog box stores the Report File Path expression separately for each process model. Therefore, you might see different Report File Path expressions when you switch to a different process model.

Note
  • Because the Report File Path is an expression, a "/" precedes all escape characters.
  • The static text box in the Report Options dialog box shows the evaluated report file path as you edit the expression. The static text box does not evaluate or replace the $(UUTStatus), $(UUT), $(TestSocket), and $(Batch) macros.
  • If the output format of the report is an ATML report, report generation will always create a new file for each UUT regardless of Report File Path expression. The ATML report format does not support multiple UUT reports in one file.

The process model determines the report file path at different points during the execution of the process model depending on the macro you use, according to the following guidelines:

  • If the Report File Path expression contains the $(UUT) macro, the report generator determines the report file path before calling the MainSequence callback sequence for each UUT.
  • If the Report File Path expression contains the $(UUTPartNum) macro, the report generator determines the report file path before calling the MainSequence callback sequence for each UUT.
  • If the Report File Path expression contains the $(TestSocket) macro, the report generator determines the report file path before calling the MainSequence callback for the first UUT in the test socket.
  • If the Report File Path expression contains the $(Batch) macro, the report generator determines the report file path before calling the MainSequence callback for the first UUT in the batch.
  • If the Report File Path expression contains the $(UUTStatus) macro, the report generator determines the report file path after calling the MainSequence callback. The $(UUTStatus) macro causes the process model to group UUT reports into different files according to their status. For example, if a Report File Path expression contains the $(UUTStatus) and $(TestSocket) macros, the process model stores all the PASSED UUT results for a given test socket in one file and stores all FAILED UUT results for a given test socket in another file. The process model keeps track of the UUT files generated for each UUT status and appends them as necessary. The following example illustrates the recommended usage of the $(UUTStatus) macro for process models.
    • Sequential model—Use the $(UUTStatus) macro in the Report File Path expression to generate report files containing UUT reports for UUTs with the same UUT status in the same file. For example, to obtain all PASSED results in the file path "C:\TestStandReports\Report_Passed.xml" and FAILED results in the file path "C:\TestStandReports\Report_Failed.xml", use the expression "C:\\TestStandReports\\Report_$(UUTStatus).xml" as the report file path.
    • Parallel model—Use the $(UUTStatus) and $(TestSocket) macros in the Report File Path expression to generate report files containing UUT reports of UUTs with the same UUT status in the same file for each test socket. For example, to obtain for each test socket all PASSED results of test socket index 1 in the file path C:\TestStandReports\TestSocketIndex_1\Report_Passed.xml, all FAILED results of test socket index 1 in the file path "C:\TestStandReports\\TestSocketNo_1\Report_Failed.xml", and so on, use the expression "C:\\TestStandReports\\TestSocketIndex_$(TestSocket)\\Report_$(UUTStatus).xml" as the report file path.
    • Batch Model—Use the $(UUTStatus) and $(Batch) macros in the Report File Path expression to group all UUT reports within the batch that have similar UUT status into one UUT Report file. For example, to obtain for each batch all PASSED results of a batch with batch number 'abc' in the file path "C:\TestStandReports\Batch_abc\Report_Passed.xml", all FAILED results of a batch with batch number 'abc' in the file path "C:\TestStandReports\Batch_abc\Report_Failed.xml", and so on, use the expression "C:\TestStandReports\Batch_$(Batch)\Report_$(UUTStatus).xml" as the report file path.