TestStand uses custom sequence file translators to load test description files saved in a custom format, such as text or XML. The translator reads the contents of the custom sequence file, translates the content to a TestStand sequence file, and opens the TestStand sequence file in the TestStand Sequence Editor or a TestStand User Interface. A custom sequence file translator can use predefined step types to simplify the mapping of common operations the custom file format defines to TestStand steps in sequence files.

Within the sequence editor or user interface, you can perform all typical operations TestStand sequence files support, such as executing and debugging sequences, diffing files, adding custom sequence files to workspaces, and deploying custom sequence files. However, you cannot automatically save changes you make to the sequence file in the sequence editor or user interface back to the custom sequence file format. You must make all changes to the custom sequence file directly.

You can create sequence file translators in various development environments, use versioning schemes with custom files, and deploy translators with TestStand. Refer to the <TestStand Public>\Examples\Fundamentals\Sequence File Translators - Examples directory for example custom sequence files and translators.

Note A sequence file translator can cause the TestStand UI in the sequence editor or in a user interface to hang if the translator launches a dialog box that is modal to the UI and if the translation occurs from within an execution. To prevent this behavior, avoid launching modal dialog boxes during translation, or ensure that you never translate a file from an execution. A dialog box is modal if you call the Engine.NotifyStartOfModalDialogEx method or if you use the Engine.AppMainHwnd property to specify the owner window for the dialog box. Translation occurs within an execution if you call the Engine.GetSequenceFileEx method in a sequence or if you execute a Sequence Call step that calls a custom sequence file.

Sequence File Translator Functions

A TestStand sequence file translator DLL must export and implement the following C callback functions. When a translator DLL does not export all the callback functions, TestStand does not load the DLL.

  • CanTranslate
  • GetDescription
  • GetExtension
  • GetFileFormatVersion
  • GetFileVersion
  • GetTranslatorCount
  • IsCurrentFileVersion
  • TranslateToSequenceFile

Error Handling

Each callback function contains three parameters for error handling—an error code, an error string, and the maximum length for the error string. When an error occurs within a callback function, set the error code to a non-zero value. When the value you assign is a TestStand error code, TestStand uses the standard error code description. The callback function can copy additional error details to the standard error message string. However, the callback must not exceed the specified number of bytes for the maximum length for the error message. TestStand uses the error message string the callback function specifies.

Note Avoid returning errors from C callback functions to TestStand, which might not properly handle the errors. Refer to the example translator projects in <TestStand Public>\Examples\Fundamentals\Sequence File Translators - Examples for examples of how to return errors from within callback functions.