Struct Engine 

pub struct Engine { /* private fields */ }

The TestStand™ Engine.

Constructing an Engine creates the underlying COM object; dropping it releases it. It is the entry point of the API:

use rs_teststand::Engine;

let engine = Engine::new()?;
println!("TestStand {}", engine.version_string()?);

Implementations

impl Engine

pub fn new() -> Result<Self, Error>

Creates the engine (STA COM apartment plus the TestStand.Engine object).

Errors

Error::Com if COM cannot be initialized or the engine class cannot be created (e.g. no TestStand™ installation is registered).

Examples found in repository

examples/version_print.rs (line 20)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

examples/workspace_create.rs (line 6)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    println!("Creating a new workspace file...");
    let ws_file = engine.new_workspace_file()?;
    let root_obj = ws_file.root_workspace_object()?;

    println!("Root workspace object:");
    println!("  Display Name: '{}'", root_obj.display_name()?);
    println!("  Object Type: {}", root_obj.object_type()?);
    println!("  Child Objects: {}", root_obj.num_contained_objects()?);

    println!("\nCreating project and folder structure...");
    let project = root_obj.new_folder("Project Alpha")?;
    println!("  Created project folder: '{}'", project.display_name()?);

    let seq_entry = project.new_file("MainTest.seq")?;
    println!(
        "  Created sequence file entry: '{}'",
        seq_entry.display_name()?
    );

    println!(
        "\nUpdated root child objects count: {}",
        root_obj.num_contained_objects()?
    );

    Ok(())
}

examples/execution_run_subsequence.rs (line 141)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = build(&engine)?;
    println!("File holds {} sequence(s).", sequence_file.num_sequences()?);

    // The conventional entry point.
    run(&engine, &sequence_file, "MainSequence")?;

    // A subsequence run on its own has no caller, so nothing supplies its
    // parameters, they keep whatever default the sequence carries. Setting
    // that default is therefore how a direct run is given its input.
    let diagnostics = sequence_file.get_sequence_by_name(SUBSEQUENCE)?;
    diagnostics
        .parameters()?
        .set_val_string(PARAMETER, none(), "FIXTURE-07")?;
    println!(
        "\n{SUBSEQUENCE}.{PARAMETER} default is now {:?}",
        diagnostics
            .parameters()?
            .get_val_string(PARAMETER, none())?
    );

    run(&engine, &sequence_file, SUBSEQUENCE)?;

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/station_options_update.rs (line 6)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let station_options = engine.station_options()?;

    station_options.set_tracing_enabled(true)?;
    station_options.set_disable_results(false)?;
    station_options.set_breakpoints_enabled(true)?;
    station_options.set_check_out_files_when_edited(false)?;
    station_options.set_language("English")?;
    station_options.set_always_goto_cleanup_on_failure(true)?;
    station_options.set_show_hidden_properties(true)?;
    station_options.set_prompt_to_find_files(false)?;
    station_options.set_auto_login_system_user(true)?;
    station_options.set_ui_message_delay(100)?;
    station_options.set_ui_message_min_delay(10)?;
    station_options.set_station_id("STATION_RUST_01")?;
    station_options.set_use_station_model(true)?;
    station_options.set_allow_other_models(false)?;
    station_options.set_use_localized_decimal_point(false)?;
    station_options.set_time_limit(0, 0, 60.0)?;
    station_options.set_time_limit_enabled(0, 0, true)?;

    engine.commit_globals_to_disk(false)?;
    println!("Station options updated and committed to disk.");

    Ok(())
}

examples/execution_run_test_headless.rs (line 147)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    // Nothing reaches the queue until this is on, and without the queue there
    // is no way to know the run ended.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for (name, data_source, low, high) in TESTS {
        add_numeric_limit_test(&engine, &main_sequence, name, data_source, low, high)?;
    }

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!("Running {} headless...", execution.display_name()?);

    if wait_for_end(&engine, RUN_DEADLINE)? {
        println!("Finished with status: {}", execution.result_status()?);
        report(&execution.result_object()?)?;
    } else {
        // Reported rather than ignored: a host that assumes success here would
        // publish results from a run that never finished.
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/template_manage_complex.rs (line 177)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_station_templates(&engine)?;

    println!("\nBuilding an in-memory template group...");
    let group = new_template_group(&engine)?;
    append_template(&group, &step_template(&engine)?)?;
    append_template(&group, &sequence_template(&engine)?)?;
    append_template(&group, &variable_template(&engine)?)?;
    println!("  {} template(s) stored", group.get_num_elements()?);

    let step = require(find_template(&group, STEP_TEMPLATE)?, STEP_TEMPLATE)?;
    let sequence = require(find_template(&group, SEQUENCE_TEMPLATE)?, SEQUENCE_TEMPLATE)?;
    let variable = require(find_template(&group, VARIABLE_TEMPLATE)?, VARIABLE_TEMPLATE)?;

    // Saving first, then reopening, is deliberate: templates are worth having
    // because they are applied to files a program did not build in this run.
    let path = std::env::temp_dir().join("rs_teststand_from_templates.seq");
    let path = path.to_string_lossy().into_owned();
    engine.new_sequence_file()?.save(&path)?;

    println!("\nApplying templates to the saved file...");
    let target = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        rs_teststand::ConflictHandler::Error,
    )?;
    apply_templates(&target, &step, &sequence, &variable)?;
    target.save(&path)?;
    println!("\nSaved to {path}");

    engine.release_sequence_file_ex(target, PropertyOptions::NONE.bits())?;
    Ok(())
}

Additional examples can be found in:

• examples/step_insert_from_template.rs
• examples/search_directory_manage.rs
• examples/sequence_build.rs
• examples/variables_manage.rs
• examples/data_type_manage.rs
• examples/result_list_parse.rs
• examples/step_insert.rs
• examples/ui_messages_handle.rs
• examples/users_manage.rs

pub fn startup_dialogs(&self) -> &[DialogInfo]

Dialogs that were closed while this engine was being created.

A non-empty list is worth logging: it is the only record that something asked a question and was answered by closing the window.

Empty means nothing owned by this process was found, which is not the same as no dialog having appeared. Detection cannot see another process’s windows, and whether the engine’s unreleased-files warning is raised in-process has not been established. Do not treat an empty list as proof that startup was clean.

pub fn load_type_palette_files_ex( &self, handler: ConflictHandler, options: i32, ) -> Result<(), Error>

Loads the type palette files (Engine.LoadTypePaletteFilesEx).

Called during construction; exposed for a caller that reconfigures the palette list and needs to reload.

Errors

Error if the COM call fails.

pub fn load_type_palette_files(&self) -> Result<(), Error>

Loads the type palette files (Engine.LoadTypePaletteFiles).

The older form, without conflict handling. Kept because it is the member available on engines from TestStand 2016.

Errors

Error if the COM call fails.

pub fn unload_type_palette_files(&self) -> Result<(), Error>

Unloads the type palette files (Engine.UnloadTypePaletteFiles).

Errors

Error if the COM call fails.

pub fn major_version(&self) -> Result<i32, Error>

The engine’s major version number (Engine.MajorVersion): the two-digit major, so TestStand™ 2026 reports 26 and 2016 reports 16.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 25)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn minor_version(&self) -> Result<i32, Error>

The engine’s minor version number (Engine.MinorVersion).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 26)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn revision_version(&self) -> Result<i32, Error>

The engine’s revision version number (Engine.RevisionVersion).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 27)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn build_version(&self) -> Result<i32, Error>

The engine’s build version number (Engine.BuildVersion).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 28)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn version_string(&self) -> Result<String, Error>

The engine’s full version string (Engine.VersionString).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 22)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn is_64bit(&self) -> Result<bool, Error>

Returns true if the TestStand™ engine is running as a 64-bit process (Engine.Is64Bit).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 30)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn teststand_directory(&self) -> Result<String, Error>

The path to the TestStand™ root directory (Engine.TestStandDirectory).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/version_print.rs (line 31)

fn main() -> Result<(), Error> {
    let engine = Engine::new()?;

    println!("version : {}", engine.version_string()?);
    println!(
        "numeric : {}.{}.{} build {}",
        engine.major_version()?,
        engine.minor_version()?,
        engine.revision_version()?,
        engine.build_version()?
    );
    println!("bitness : {}", if engine.is_64bit()? { 64 } else { 32 });
    println!("install : {}", engine.teststand_directory()?);

    Ok(())
}

pub fn bin_directory(&self) -> Result<String, Error>

The path to the TestStand™ Bin directory (Engine.BinDirectory).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/search_directory_manage.rs (line 60)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let search_directories = engine.search_directories()?;

    println!("Total search directories: {}", search_directories.count()?);
    for (index, directory) in search_directories.iter()?.enumerate() {
        print_entry(index, &directory?)?;
    }

    // Insert at the front, so the new entry is searched first.
    println!("\nInserting a new explicit search directory...");
    let new_path = engine.bin_directory()?;
    search_directories.insert(&new_path, 0, true, "", false, false)?;
    println!("Total after insert: {}", search_directories.count()?);

    let inserted = search_directories.get(0)?;
    println!(
        "New [0] Path: '{}', Subdirs: {}",
        inserted.path()?,
        inserted.search_subdirectories()?
    );

    // A disabled entry stays in the list but is not searched.
    println!("Disabling the new directory...");
    inserted.set_disabled(true)?;
    println!("New [0] Disabled: {}", inserted.disabled()?);

    // Order matters: entries are searched in list order.
    println!("Moving the new directory to index 1...");
    search_directories.move_search_directory(0, 1)?;
    println!(
        "Directory at index 1 is now: '{}'",
        search_directories.get(1)?.path()?
    );

    println!("Removing the added directory to clean up...");
    search_directories.remove(1)?;
    println!("Total after cleanup: {}", search_directories.count()?);

    // The engine writes search directories out at shutdown anyway. Committing
    // now makes the change visible to other processes immediately, and passing
    // `false` keeps a save conflict from raising a dialog.
    engine.commit_globals_to_disk(false)?;
    println!("Committed search directories configuration to disk.");

    Ok(())
}

pub fn config_directory(&self) -> Result<String, Error>

The path to the TestStand™ Cfg directory (Engine.ConfigDirectory).

Errors

Error if the COM call fails or returns an unexpected type.

pub fn station_options(&self) -> Result<StationOptions, Error>

Accesses the station’s configuration settings (Engine.StationOptions).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/station_options_update.rs (line 7)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let station_options = engine.station_options()?;

    station_options.set_tracing_enabled(true)?;
    station_options.set_disable_results(false)?;
    station_options.set_breakpoints_enabled(true)?;
    station_options.set_check_out_files_when_edited(false)?;
    station_options.set_language("English")?;
    station_options.set_always_goto_cleanup_on_failure(true)?;
    station_options.set_show_hidden_properties(true)?;
    station_options.set_prompt_to_find_files(false)?;
    station_options.set_auto_login_system_user(true)?;
    station_options.set_ui_message_delay(100)?;
    station_options.set_ui_message_min_delay(10)?;
    station_options.set_station_id("STATION_RUST_01")?;
    station_options.set_use_station_model(true)?;
    station_options.set_allow_other_models(false)?;
    station_options.set_use_localized_decimal_point(false)?;
    station_options.set_time_limit(0, 0, 60.0)?;
    station_options.set_time_limit_enabled(0, 0, true)?;

    engine.commit_globals_to_disk(false)?;
    println!("Station options updated and committed to disk.");

    Ok(())
}

pub fn new_sequence_file(&self) -> Result<SequenceFile, Error>

Creates an empty sequence file (Engine.NewSequenceFile).

The file exists only in memory until it is saved.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/execution_run_subsequence.rs (line 60)

fn build(engine: &Engine) -> Result<SequenceFile, Error> {
    let sequence_file = engine.new_sequence_file()?;

    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for name in ["Initialize", "Run Test", "Shut Down"] {
        add_action(engine, &main_sequence, name)?;
    }

    let diagnostics = engine.new_sequence()?;
    diagnostics.set_name(SUBSEQUENCE)?;
    // A parameter is an ordinary property in the sequence's Parameters scope.
    diagnostics.parameters()?.new_sub_property(
        PARAMETER,
        PropValType::String,
        false,
        "",
        insert_if_missing(),
    )?;
    for name in ["Check Power Rails", "Check Clock"] {
        add_action(engine, &diagnostics, name)?;
    }
    sequence_file.insert_sequence(&diagnostics)?;

    Ok(sequence_file)
}

examples/execution_run_test_headless.rs (line 152)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    // Nothing reaches the queue until this is on, and without the queue there
    // is no way to know the run ended.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for (name, data_source, low, high) in TESTS {
        add_numeric_limit_test(&engine, &main_sequence, name, data_source, low, high)?;
    }

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!("Running {} headless...", execution.display_name()?);

    if wait_for_end(&engine, RUN_DEADLINE)? {
        println!("Finished with status: {}", execution.result_status()?);
        report(&execution.result_object()?)?;
    } else {
        // Reported rather than ignored: a host that assumes success here would
        // publish results from a run that never finished.
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/template_manage_complex.rs (line 195)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_station_templates(&engine)?;

    println!("\nBuilding an in-memory template group...");
    let group = new_template_group(&engine)?;
    append_template(&group, &step_template(&engine)?)?;
    append_template(&group, &sequence_template(&engine)?)?;
    append_template(&group, &variable_template(&engine)?)?;
    println!("  {} template(s) stored", group.get_num_elements()?);

    let step = require(find_template(&group, STEP_TEMPLATE)?, STEP_TEMPLATE)?;
    let sequence = require(find_template(&group, SEQUENCE_TEMPLATE)?, SEQUENCE_TEMPLATE)?;
    let variable = require(find_template(&group, VARIABLE_TEMPLATE)?, VARIABLE_TEMPLATE)?;

    // Saving first, then reopening, is deliberate: templates are worth having
    // because they are applied to files a program did not build in this run.
    let path = std::env::temp_dir().join("rs_teststand_from_templates.seq");
    let path = path.to_string_lossy().into_owned();
    engine.new_sequence_file()?.save(&path)?;

    println!("\nApplying templates to the saved file...");
    let target = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        rs_teststand::ConflictHandler::Error,
    )?;
    apply_templates(&target, &step, &sequence, &variable)?;
    target.save(&path)?;
    println!("\nSaved to {path}");

    engine.release_sequence_file_ex(target, PropertyOptions::NONE.bits())?;
    Ok(())
}

examples/step_insert_from_template.rs (line 77)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_templates(&engine)?;

    let prototype = build_prototype(&engine)?;
    println!(
        "Prototype: {} via {:?}, run mode {:?}",
        prototype.name()?,
        prototype.adapter_key_name()?,
        prototype.run_mode()?
    );

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    let template = prototype.as_property_object()?;

    for copy_number in 1..=COPIES {
        let index = main_sequence.get_num_steps(StepGroup::Main)?;
        let inserted =
            main_sequence.insert_step_from_template(&template, index, StepGroup::Main)?;
        inserted.set_name(&format!("Measure {copy_number} (from template)"))?;
        // Each copy needs an identity of its own; the clone brought the
        // prototype's.
        inserted.create_new_unique_step_id()?;
    }

    println!(
        "\nMainSequence now holds {} step(s):",
        main_sequence.get_num_steps(StepGroup::Main)?
    );
    for index in 0..main_sequence.get_num_steps(StepGroup::Main)? {
        let step = main_sequence.get_step(index, StepGroup::Main)?;
        println!(
            "  [{index}] {} -> {}",
            step.name()?,
            step.as_property_object()?
                .get_val_string(VI_PATH, PropertyOptions::NONE.bits())?
        );
    }

    // The prototype is untouched and can go on producing copies.
    println!("\nPrototype still named: {}", prototype.name()?);

    let path = std::env::temp_dir().join("rs_teststand_from_template.seq");
    let path = path.to_string_lossy().into_owned();
    sequence_file.save(&path)?;
    println!("Saved to {path}");
    Ok(())
}

examples/sequence_build.rs (line 70)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Steps are placed by group and index, so order is explicit.
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Temperature Check",
            "Locals.TempSensorPresent == True",
            15.0,
            85.0,
        )?,
        0,
        StepGroup::Main,
    )?;
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Voltage Monitor",
            "Locals.DUTPowered == True",
            4.75,
            5.25,
        )?,
        1,
        StepGroup::Main,
    )?;

    // A subsequence, so a later example has something to call.
    let subsequence = engine.new_sequence()?;
    subsequence.set_name("CustomSubsequence")?;
    sequence_file.insert_sequence(&subsequence)?;

    let init_step = engine.new_step(NO_ADAPTER, "Action")?;
    init_step.set_name("Initialize Hardware")?;
    subsequence.insert_step(&init_step, 0, StepGroup::Main)?;

    describe(&main_sequence)?;
    println!();
    describe(&subsequence)?;

    // Cleanup runs even when Main fails, which is why it is worth showing.
    println!(
        "\nGroup sizes in MainSequence: setup={}, main={}, cleanup={}",
        main_sequence.get_num_steps(StepGroup::Setup)?,
        main_sequence.get_num_steps(StepGroup::Main)?,
        main_sequence.get_num_steps(StepGroup::Cleanup)?
    );

    let path = std::env::temp_dir().join("rs_teststand_built_sequence.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

examples/data_type_manage.rs (line 109)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let file = sequence_file.as_property_object_file()?;
    let types = file.type_usage_list()?;

    types.insert_type(
        &build_multimeter_type(&engine)?,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;
    let coupling = register_enum(
        &engine,
        &types,
        "Coupling",
        &[("AC", 0.0), ("DC", 1.0)],
        true,
    )?;

    // A variable of the enum type, so the change below has an instance to update.
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    main_sequence.locals()?.new_sub_property(
        "InputCoupling",
        PropValType::NamedType,
        false,
        "Coupling",
        INSERT_IF_MISSING,
    )?;

    println!(
        "Registered custom data types ({} in file):",
        types.num_types()?
    );
    print_enumerators(&coupling)?;

    // Evolve it: add an enumerator and raise the version.
    println!(
        "\nCoupling version before update: {}",
        coupling.type_version()?
    );
    coupling.update_enumerators(&enumerator_array(
        &engine,
        &[("AC", 0.0), ("DC", 1.0), ("GND", 2.0)],
        true,
    )?)?;

    // Raising the lowest field signals a change the engine applies silently;
    // raising a higher one marks it as deliberate.
    let version = coupling.type_version()?;
    let mut fields = version.split('.');
    let major: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    let minor: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    coupling.set_type_version(&format!("{major}.{}.0.0", minor + 1))?;
    println!(
        "Coupling version after  update: {}",
        coupling.type_version()?
    );

    println!("\nCoupling now defines (InputCoupling reflects this):");
    print_enumerators(&coupling)?;

    // Saving does nothing unless the file believes it changed.
    file.inc_change_count()?;
    let path = std::env::temp_dir().join("rs_teststand_with_custom_types.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

Additional examples can be found in:

• examples/result_list_parse.rs
• examples/step_insert.rs
• examples/ui_messages_handle.rs

pub fn new_execution( &self, sequence_file: &SequenceFile, sequence_name: &str, process_model: Option<&SequenceFile>, break_at_first_step: bool, execution_type_mask: i32, ) -> Result<Execution, Error>

Starts a sequence running (Engine.NewExecution).

The execution begins immediately.

Pass None for process_model to run the sequence directly; supply one to run a process-model entry point instead. execution_type_mask is normally 0.

Errors

Error if the sequence cannot be started or the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 109)

fn run(engine: &Engine, sequence_file: &SequenceFile, entry_point: &str) -> Result<(), Error> {
    let execution = engine.new_execution(sequence_file, entry_point, None, false, 0)?;
    println!("\nRunning {entry_point}...");

    if !wait_for_end(engine, RUN_DEADLINE)? {
        println!("  did not finish within {RUN_DEADLINE:?}; terminating");
        execution.terminate()?;
        return Ok(());
    }
    println!("  status: {}", execution.result_status()?);

    let results = execution.result_object()?;
    if !results.exists("ResultList", none())? {
        println!("  no results recorded");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    for index in 0..result_list.get_num_elements()? {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        println!(
            "  {}: {}",
            entry
                .get_val_string("TS.StepName", none())
                .unwrap_or_else(|_| "<unnamed>".to_owned()),
            entry
                .get_val_string("Status", none())
                .unwrap_or_else(|_| "<no status>".to_owned())
        );
    }
    Ok(())
}

examples/execution_run_test_headless.rs (line 158)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    // Nothing reaches the queue until this is on, and without the queue there
    // is no way to know the run ended.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for (name, data_source, low, high) in TESTS {
        add_numeric_limit_test(&engine, &main_sequence, name, data_source, low, high)?;
    }

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!("Running {} headless...", execution.display_name()?);

    if wait_for_end(&engine, RUN_DEADLINE)? {
        println!("Finished with status: {}", execution.result_status()?);
        report(&execution.result_object()?)?;
    } else {
        // Reported rather than ignored: a host that assumes success here would
        // publish results from a run that never finished.
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/result_list_parse.rs (line 130)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    add_pass_fail(&engine, &main_sequence, "Verify Power Rail", "True")?;
    add_unrecorded_filler(&engine, &main_sequence, "Filler (not recorded)")?;
    add_numeric(
        &engine,
        &main_sequence,
        "Verify Current Draw",
        "1.5",
        1.0,
        2.0,
    )?;
    add_pass_fail(&engine, &main_sequence, "Verify Ground Bond", "True")?;

    let step_count = main_sequence.get_num_steps(StepGroup::Main)?;
    println!("Running {step_count} steps...");
    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;

    if !wait_for_end(&engine, RUN_DEADLINE)? {
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
        return Ok(());
    }
    println!("Finished with status: {}\n", execution.result_status()?);

    let results = execution.result_list()?;
    let parsed = results.parse()?;

    println!("{} of {step_count} steps recorded a result:", parsed.len());
    for (index, result) in parsed.iter().enumerate() {
        let measurement = match &result.value {
            Some(ResultValue::Number(number)) => format!("measured {number}"),
            Some(ResultValue::Text(text)) => format!("measured {text:?}"),
            None => "no measurement".to_owned(),
        };
        println!(
            "  [{index}] {} ({}) -> {}, {measurement}",
            result.name, result.step_type, result.status
        );
    }

    // The step whose recording was switched off is absent, by design.
    println!(
        "\nThe unrecorded step left no entry, which is why {} < {step_count}.",
        parsed.len()
    );

    // The parsed results are plain data, so they outlive the run and can be
    // handed to anything: a report writer, a database, a serde format.
    let failures: Vec<&str> = parsed
        .iter()
        .filter(|result| result.status == "Failed")
        .map(|result| result.name.as_str())
        .collect();
    if failures.is_empty() {
        println!("No failures.");
    } else {
        println!("Failed steps: {}", failures.join(", "));
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/ui_messages_handle.rs (line 71)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;

    // Nothing reaches the queue until polling is switched on.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Posted through the engine and tagged with the execution. Synchronous, so
    // the sequence waits until the host acknowledges it.
    add_statement(
        &engine,
        &main_sequence,
        "Report Stage",
        &format!(
            "RunState.Engine.PostUIMessage(RunState.Execution, RunState.Thread, {STAGE_MESSAGE}, \
             1, \"stage: configuring instruments\", Nothing, True)"
        ),
    )?;
    // Posted through the thread. Asynchronous, so the sequence carries on.
    add_statement(
        &engine,
        &main_sequence,
        "Report Progress",
        &format!(
            "RunState.Thread.PostUIMessageEx({PROGRESS_MESSAGE}, 50, \"progress: halfway\", \
             Nothing, False)"
        ),
    )?;

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!(
        "Execution {} started; polling for messages...",
        execution.id()?
    );

    // The end is detected from the message stream, not by waiting on the
    // execution: a wait call does not pump the queue, so a synchronous message
    // would sit unacknowledged and both sides would stop.
    let started = Instant::now();
    let mut ended = false;
    while started.elapsed() < Duration::from_secs(60) && !ended {
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let code = message.event()?;
            if matches!(
                UIMessageCode::from_bits(code),
                Ok(UIMessageCode::EndExecution)
            ) {
                ended = true;
            }
            let origin = if UIMessageCode::is_user_message(code) {
                "sequence".to_owned()
            } else {
                format!("engine {:?}", UIMessageCode::from_bits(code))
            };
            println!(
                "  [{origin}] code={code} numeric={} string={:?} synchronous={}",
                message.numeric_data()?,
                message.string_data()?,
                message.is_synchronous()?
            );
            // Required: releases a synchronous poster and asks for the next.
            message.acknowledge()?;
        }
    }

    println!("\nExecution ended: {ended}");
    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn post_ui_message( &self, execution: &Execution, thread: &Thread, event_code: i32, numeric_data: f64, string_data: &str, activex_data: Option<&PropertyObject>, synchronous: bool, ) -> Result<(), Error>

Posts a message on behalf of an execution (Engine.PostUIMessage).

The counterpart to Thread::post_ui_message_ex, for code that is not itself running inside the sequence and therefore has no current thread to post from. Because there is no implied context, the execution and thread the message belongs to are given explicitly.

activex_data carries structured data, read back by the host from UIMessage::activex_data. Pass None to leave the slot empty.

Pass synchronous = true in the ordinary case; see Thread::post_ui_message_ex for why the blocking form is the safe default.

Errors

Error if the COM call fails, or if a wrapper has no COM identity.

pub fn set_current_user(&self, user: Option<&User>) -> Result<(), Error>

Logs a user in, or logs the current one out (Engine.CurrentUser).

Some(user) makes that user current; None clears it, which the engine documents as logging out.

This does not check the password. Setting the property is the act of logging in, not an authentication step: a host that cares must call User::validate_password first and refuse on false. Written this way because the engine draws the same line, and hiding a check inside a setter would make it unclear which one a caller had actually performed.

A host built on the ActiveX UI controls should use their own login method instead, so the controls raise the event they expect; this is the headless path.

Errors

Error if the COM call fails, or if user has no COM identity.

pub fn terminate_all(&self) -> Result<(), Error>

Asks every execution to stop (Engine.TerminateAll).

Termination, not abort: cleanup groups still run, so hardware is left in a safe state. Like Execution::terminate it is a request, and returns before the runs have finished unwinding. A caller that needs them stopped must then wait for UIMessageCode::EndExecution.

Errors

Error if the COM call fails.

pub fn abort_all(&self) -> Result<(), Error>

Stops every execution without running cleanup (Engine.AbortAll).

The blunt counterpart to terminate_all. Cleanup groups do not run, so anything a sequence would have switched off stays on. Prefer terminating unless the point is to stop now.

Errors

Error if the COM call fails.

pub fn license_type(&self) -> Result<LicenseType, Error>

The license the engine is currently using (Engine.LicenseType).

Using, not holding. A freshly created engine has acquired nothing and reports LicenseType::NoLicense even on a fully licensed station; the answer only becomes meaningful after something acquires. Use require_license to ask whether the station can license this host.

Reads state, so it acquires nothing and raises no dialog.

Errors

Error if the COM call fails, or Error::UnknownLicenseType if the engine reports a type this build does not name.

pub fn require_license(&self) -> Result<HeldLicense<'_>, Error>

Acquires a license, or fails if the station cannot grant one.

The check a headless host should make before anything else, and the object it should keep alive while it runs.

Acquiring is what makes a license real. license_type reports the license the engine is using, and a freshly created engine is using none, measured on a station with a valid development system license, it reads NoLicense until something acquires. So reading before acquiring answers the wrong question, and this method acquires first.

The request is ApplicationLicense::Unspecified, which lets the engine grant whatever it has. Naming a kind can be refused even when the station is properly licensed: on a development system station, ApplicationLicense::OperatorInterface is turned down while unspecified succeeds. Ask for a specific kind through acquire_license only when the host genuinely requires that one.

The startup dialog is suppressed, so an unlicensed station returns an error rather than opening a window nobody will close.

Refusal is retried for a few seconds before it is believed. The licensing subsystem is not ready the instant the engine object exists: measured on a properly licensed station, acquiring immediately after construction is refused, while the same call half a second later succeeds. A host that trusted the first answer would report an unlicensed station to its operator and stop. So a refusal is retried until it stops changing, which costs an unlicensed station a few seconds once, at startup.

Success is the handle, not the type. HeldLicense::kind reports what the engine says it is using and can still read NoLicense after an unspecified request was granted, so treat it as information rather than as the verdict.

Errors

Error::NoLicense if no license can be acquired, or Error if the COM call fails.

pub fn get_license_description(&self) -> Result<String, Error>

A description of the current license (Engine.GetLicenseDescription).

Free text meant for a person, so log it rather than branch on it; use license_type for decisions.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn application_license(&self) -> Result<ApplicationLicense, Error>

The license this application requested (Engine.ApplicationLicense).

Errors

Error if the COM call fails, or Error::UnknownLicenseType if the engine reports a value this build does not name.

pub fn acquire_license( &self, license: ApplicationLicense, options: AcquireLicenseOptions, ) -> Result<i32, Error>

Acquires a license and returns its handle (Engine.AcquireLicense).

Release it with release_license; the license is held until every handle for it is released.

Pass AcquireLicenseOptions::SUPPRESS_STARTUP_DIALOG on any station without a person at it. Without it, an engine that cannot acquire the license opens a window offering to evaluate, activate or buy, and waits. A headless host stops there until something kills it. With it, the same situation returns an error this method propagates.

Prefer ApplicationLicense::Unspecified, which lets the engine grant whatever it has. Naming a kind is a constraint, not a preference, and a smaller request is not a safer one: on a station licensed for a development system, OperatorInterface is refused while unspecified succeeds. Name a kind only when the host truly requires it.

Most callers want require_license instead, which acquires and hands back a guard that releases on drop.

Errors

Error::NoLicense if the license was not granted, or Error if the COM call fails.

A handle of zero is treated as refusal. The reference says this member returns an error when it cannot acquire the license; measured against an unlicensed station it succeeds and hands back zero instead. A caller that trusted the documented behavior would carry on unlicensed, so the zero is turned into the error the caller was promised.

pub fn release_license(&self, handle: i32) -> Result<(), Error>

Releases a license handle (Engine.ReleaseLicense).

Errors

Error if the COM call fails.

pub fn has_addon_license(&self, feature_name: &str) -> Result<bool, Error>

Whether the station licenses an add-on feature (Engine.HasAddonLicense).

Errors

Error if the COM call fails or returns an unexpected type.

pub fn unload_all_modules(&self) -> Result<(), Error>

Releases every code module the engine has loaded (Engine.UnloadAllModules).

Loading a sequence file loads its modules, and they stay loaded until that file is closed. That is what makes the second run fast, and also what holds a DLL open against the build that wants to replace it. Unloading here frees them all at once, without closing anything.

Call it between runs, not during one: a module in use by a live execution is not a candidate, and the next run reloads whatever it needs.

State inside a module does not survive. Anything a module kept in a static or a global is gone once it is unloaded, and the reload starts from nothing. A station whose modules carry state between steps that way should keep that state in the engine instead, or not call this.

Errors

Error if the COM call fails.

pub fn breakpoints_enabled(&self) -> Result<bool, Error>

Whether breakpoints stop an execution (Engine.BreakpointsEnabled).

The master switch. With it off, breakpoints stay set but nothing stops on them, which is how a station runs unattended without anyone having to strip a sequence file of the breakpoints someone left in it.

Distinct from the station option of the same name, which is the setting written to disk. This is the engine’s live state.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn set_breakpoints_enabled(&self, enabled: bool) -> Result<(), Error>

Turns breakpoints on or off (Engine.BreakpointsEnabled).

Errors

Error if the COM call fails.

pub fn persist_breakpoints(&self) -> Result<bool, Error>

Whether breakpoints survive the file they are set in (Engine.PersistBreakpoints).

On, the engine remembers them across a close and reopen. A host that sets breakpoints on behalf of a remote panel usually wants this off, so that a debugging session leaves nothing behind on the station.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn set_persist_breakpoints(&self, persist: bool) -> Result<(), Error>

Chooses whether breakpoints are remembered (Engine.PersistBreakpoints).

Errors

Error if the COM call fails.

pub fn do_dot_net_garbage_collection(&self) -> Result<(), Error>

Runs a .NET garbage collection now (Engine.DoDotNetGarbageCollection).

Only relevant to a station whose steps call .NET code. Collection is otherwise periodic, on the interval; this forces one, which is worth doing between runs on a long-lived host rather than during a measurement, since collection pauses the runtime.

Errors

Error if the COM call fails.

pub fn dot_net_garbage_collection_interval(&self) -> Result<i32, Error>

How often the engine collects .NET garbage, in milliseconds (Engine.DotNetGarbageCollectionInterval).

Zero or less means automatic collection is off. A host built on this crate will normally read -1, and that is correct rather than broken: the three-second default belongs to applications built on the UI control, and a headless host does not create one. Nothing collects on a timer unless this is set to a positive interval, so a long-lived host that runs .NET steps should either set one or call do_dot_net_garbage_collection between runs.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn set_dot_net_garbage_collection_interval( &self, milliseconds: i32, ) -> Result<(), Error>

Sets the .NET collection interval, in milliseconds (Engine.DotNetGarbageCollectionInterval).

Zero or less switches automatic collection off.

Errors

Error if the COM call fails.

pub fn dot_net_clr_version(&self) -> Result<String, Error>

The .NET runtime version the engine loaded (Engine.DotNetCLRVersion).

Empty on a station where nothing has pulled the runtime in yet, so treat an empty string as “not loaded” rather than as an error.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn users_file(&self) -> Result<UsersFile, Error>

The station’s user list, as a file (Engine.UsersFile).

The users the engine loaded at startup, and the only route to writing them back. new_user builds a user in memory; without saving through this file the station is unchanged once the process exits.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/users_manage.rs (line 96)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    // Passing no profile means the user inherits nothing.
    let user = engine.new_user(None)?;
    user.set_login_name("operator1")?;
    user.set_full_name("Test Operator")?;
    user.set_password("ts-secret")?;

    println!("User: {} ({})", user.login_name()?, user.full_name()?);

    // Check a credential without handling the stored value.
    println!(
        "  password 'ts-secret' valid: {}",
        user.validate_password("ts-secret")?
    );
    println!(
        "  password 'wrong' valid:     {}",
        user.validate_password("wrong")?
    );

    println!("  privilege checks:");
    report_privileges(
        &user,
        &[
            UserPrivilege::Operate,
            UserPrivilege::Execute,
            UserPrivilege::Develop,
            UserPrivilege::Debug,
            UserPrivilege::EditUsers,
        ],
    )?;

    // A privilege can also be named by its full path, which is how a leaf
    // inside a category is reached.
    println!(
        "  Debug.RunSelectedTests:  {}",
        user.has_privilege_named("Debug.RunSelectedTests")?
    );

    // The privilege tree is nested: categories hold the individual rights.
    let privileges = user.privileges()?;
    let count = privileges.get_num_sub_properties("")?;
    println!("  privilege tree ({count} categories):");
    for index in 0..count {
        let name = privileges.get_nth_sub_property_name("", index, 0)?;
        let members = privileges
            .get_property_object(&name, 0)?
            .get_num_sub_properties("")?;
        println!("    {name:<12} {members} member(s)");
    }

    // The station itself, read-only.
    println!("\nStation:");
    match engine.current_user()? {
        Some(current) => println!("  logged in as {}", current.login_name()?),
        None => println!("  nobody logged in (usual when login is not required)"),
    }
    println!(
        "  is 'operator1' a real account here? {}",
        engine.user_name_exists("operator1")?
    );

    // Where accounts actually live. Everything above this point exists only in
    // memory: `new_user` builds a User, it does not enrol one. A user becomes
    // part of the station when it is inserted into this file's list and the
    // file is written.
    let users_file = engine.users_file()?;
    let file = users_file.as_property_object_file()?;
    println!(
        "
Users file:"
    );
    println!("  path            {}", file.path()?);
    println!(
        "  users           {}",
        users_file.user_list()?.get_num_elements()?
    );
    println!(
        "  groups          {}",
        users_file.user_group_list()?.get_num_elements()?
    );
    println!(
        "  profiles        {}",
        users_file.user_profile_list()?.get_num_elements()?
    );

    // Deliberately not run: it would edit the station this example is reading.
    // The two calls a host makes to enrol the user built above are
    //
    //     users_file.user_list()?.set_num_elements(count + 1, 0)?;   // then fill
    //     file.save_file_if_modified(false)?;                        // then write
    //
    // `false` matters: with `true` the engine puts a save dialog on screen, and
    // a host with no operator would wait for an answer that never comes.
    println!(
        "
  (this example does not write; enrolling a user would alter the station)"
    );

    Ok(())
}

pub fn ui_message_polling_enabled(&self) -> Result<bool, Error>

Whether the host polls for messages (Engine.UIMessagePollingEnabled).

Errors

Error if the COM call fails or returns an unexpected type.

pub fn set_ui_message_polling_enabled(&self, enabled: bool) -> Result<(), Error>

Turns message polling on or off (Engine.UIMessagePollingEnabled).

Off by default. A headless host must turn it on before anything appears in the queue, without it the queue stays empty however much a sequence posts.

Errors

Error if the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 142)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = build(&engine)?;
    println!("File holds {} sequence(s).", sequence_file.num_sequences()?);

    // The conventional entry point.
    run(&engine, &sequence_file, "MainSequence")?;

    // A subsequence run on its own has no caller, so nothing supplies its
    // parameters, they keep whatever default the sequence carries. Setting
    // that default is therefore how a direct run is given its input.
    let diagnostics = sequence_file.get_sequence_by_name(SUBSEQUENCE)?;
    diagnostics
        .parameters()?
        .set_val_string(PARAMETER, none(), "FIXTURE-07")?;
    println!(
        "\n{SUBSEQUENCE}.{PARAMETER} default is now {:?}",
        diagnostics
            .parameters()?
            .get_val_string(PARAMETER, none())?
    );

    run(&engine, &sequence_file, SUBSEQUENCE)?;

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/execution_run_test_headless.rs (line 150)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    // Nothing reaches the queue until this is on, and without the queue there
    // is no way to know the run ended.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for (name, data_source, low, high) in TESTS {
        add_numeric_limit_test(&engine, &main_sequence, name, data_source, low, high)?;
    }

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!("Running {} headless...", execution.display_name()?);

    if wait_for_end(&engine, RUN_DEADLINE)? {
        println!("Finished with status: {}", execution.result_status()?);
        report(&execution.result_object()?)?;
    } else {
        // Reported rather than ignored: a host that assumes success here would
        // publish results from a run that never finished.
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/result_list_parse.rs (line 111)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    add_pass_fail(&engine, &main_sequence, "Verify Power Rail", "True")?;
    add_unrecorded_filler(&engine, &main_sequence, "Filler (not recorded)")?;
    add_numeric(
        &engine,
        &main_sequence,
        "Verify Current Draw",
        "1.5",
        1.0,
        2.0,
    )?;
    add_pass_fail(&engine, &main_sequence, "Verify Ground Bond", "True")?;

    let step_count = main_sequence.get_num_steps(StepGroup::Main)?;
    println!("Running {step_count} steps...");
    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;

    if !wait_for_end(&engine, RUN_DEADLINE)? {
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
        return Ok(());
    }
    println!("Finished with status: {}\n", execution.result_status()?);

    let results = execution.result_list()?;
    let parsed = results.parse()?;

    println!("{} of {step_count} steps recorded a result:", parsed.len());
    for (index, result) in parsed.iter().enumerate() {
        let measurement = match &result.value {
            Some(ResultValue::Number(number)) => format!("measured {number}"),
            Some(ResultValue::Text(text)) => format!("measured {text:?}"),
            None => "no measurement".to_owned(),
        };
        println!(
            "  [{index}] {} ({}) -> {}, {measurement}",
            result.name, result.step_type, result.status
        );
    }

    // The step whose recording was switched off is absent, by design.
    println!(
        "\nThe unrecorded step left no entry, which is why {} < {step_count}.",
        parsed.len()
    );

    // The parsed results are plain data, so they outlive the run and can be
    // handed to anything: a report writer, a database, a serde format.
    let failures: Vec<&str> = parsed
        .iter()
        .filter(|result| result.status == "Failed")
        .map(|result| result.name.as_str())
        .collect();
    if failures.is_empty() {
        println!("No failures.");
    } else {
        println!("Failed steps: {}", failures.join(", "));
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/ui_messages_handle.rs (line 44)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;

    // Nothing reaches the queue until polling is switched on.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Posted through the engine and tagged with the execution. Synchronous, so
    // the sequence waits until the host acknowledges it.
    add_statement(
        &engine,
        &main_sequence,
        "Report Stage",
        &format!(
            "RunState.Engine.PostUIMessage(RunState.Execution, RunState.Thread, {STAGE_MESSAGE}, \
             1, \"stage: configuring instruments\", Nothing, True)"
        ),
    )?;
    // Posted through the thread. Asynchronous, so the sequence carries on.
    add_statement(
        &engine,
        &main_sequence,
        "Report Progress",
        &format!(
            "RunState.Thread.PostUIMessageEx({PROGRESS_MESSAGE}, 50, \"progress: halfway\", \
             Nothing, False)"
        ),
    )?;

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!(
        "Execution {} started; polling for messages...",
        execution.id()?
    );

    // The end is detected from the message stream, not by waiting on the
    // execution: a wait call does not pump the queue, so a synchronous message
    // would sit unacknowledged and both sides would stop.
    let started = Instant::now();
    let mut ended = false;
    while started.elapsed() < Duration::from_secs(60) && !ended {
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let code = message.event()?;
            if matches!(
                UIMessageCode::from_bits(code),
                Ok(UIMessageCode::EndExecution)
            ) {
                ended = true;
            }
            let origin = if UIMessageCode::is_user_message(code) {
                "sequence".to_owned()
            } else {
                format!("engine {:?}", UIMessageCode::from_bits(code))
            };
            println!(
                "  [{origin}] code={code} numeric={} string={:?} synchronous={}",
                message.numeric_data()?,
                message.string_data()?,
                message.is_synchronous()?
            );
            // Required: releases a synchronous poster and asks for the next.
            message.acknowledge()?;
        }
    }

    println!("\nExecution ended: {ended}");
    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn is_ui_message_queue_empty(&self) -> Result<bool, Error>

Whether the message queue is empty (Engine.IsUIMessageQueueEmpty).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/execution_run_subsequence.rs (line 92)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/result_list_parse.rs (line 94)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/execution_run_test_headless.rs (line 96)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            // Acknowledging is what releases a synchronous poster; skipping it
            // stalls the sequence rather than merely losing a notification.
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/ui_messages_handle.rs (line 83)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;

    // Nothing reaches the queue until polling is switched on.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Posted through the engine and tagged with the execution. Synchronous, so
    // the sequence waits until the host acknowledges it.
    add_statement(
        &engine,
        &main_sequence,
        "Report Stage",
        &format!(
            "RunState.Engine.PostUIMessage(RunState.Execution, RunState.Thread, {STAGE_MESSAGE}, \
             1, \"stage: configuring instruments\", Nothing, True)"
        ),
    )?;
    // Posted through the thread. Asynchronous, so the sequence carries on.
    add_statement(
        &engine,
        &main_sequence,
        "Report Progress",
        &format!(
            "RunState.Thread.PostUIMessageEx({PROGRESS_MESSAGE}, 50, \"progress: halfway\", \
             Nothing, False)"
        ),
    )?;

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!(
        "Execution {} started; polling for messages...",
        execution.id()?
    );

    // The end is detected from the message stream, not by waiting on the
    // execution: a wait call does not pump the queue, so a synchronous message
    // would sit unacknowledged and both sides would stop.
    let started = Instant::now();
    let mut ended = false;
    while started.elapsed() < Duration::from_secs(60) && !ended {
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let code = message.event()?;
            if matches!(
                UIMessageCode::from_bits(code),
                Ok(UIMessageCode::EndExecution)
            ) {
                ended = true;
            }
            let origin = if UIMessageCode::is_user_message(code) {
                "sequence".to_owned()
            } else {
                format!("engine {:?}", UIMessageCode::from_bits(code))
            };
            println!(
                "  [{origin}] code={code} numeric={} string={:?} synchronous={}",
                message.numeric_data()?,
                message.string_data()?,
                message.is_synchronous()?
            );
            // Required: releases a synchronous poster and asks for the next.
            message.acknowledge()?;
        }
    }

    println!("\nExecution ended: {ended}");
    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn get_ui_message(&self) -> Result<UIMessage, Error>

Takes the next message from the queue (Engine.GetUIMessage).

Check is_ui_message_queue_empty first. The message must be acknowledged once handled, see UIMessage::acknowledge.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/execution_run_subsequence.rs (line 93)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/result_list_parse.rs (line 95)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/execution_run_test_headless.rs (line 97)

fn wait_for_end(engine: &Engine, deadline: Duration) -> Result<bool, Error> {
    let started = Instant::now();
    while started.elapsed() < deadline {
        if pump_thread_messages() {
            return Ok(false);
        }
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let ended = matches!(
                UIMessageCode::from_bits(message.event()?),
                Ok(UIMessageCode::EndExecution)
            );
            // Acknowledging is what releases a synchronous poster; skipping it
            // stalls the sequence rather than merely losing a notification.
            message.acknowledge()?;
            if ended {
                return Ok(true);
            }
        }
    }
    Ok(false)
}

examples/ui_messages_handle.rs (line 84)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;

    // Nothing reaches the queue until polling is switched on.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Posted through the engine and tagged with the execution. Synchronous, so
    // the sequence waits until the host acknowledges it.
    add_statement(
        &engine,
        &main_sequence,
        "Report Stage",
        &format!(
            "RunState.Engine.PostUIMessage(RunState.Execution, RunState.Thread, {STAGE_MESSAGE}, \
             1, \"stage: configuring instruments\", Nothing, True)"
        ),
    )?;
    // Posted through the thread. Asynchronous, so the sequence carries on.
    add_statement(
        &engine,
        &main_sequence,
        "Report Progress",
        &format!(
            "RunState.Thread.PostUIMessageEx({PROGRESS_MESSAGE}, 50, \"progress: halfway\", \
             Nothing, False)"
        ),
    )?;

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!(
        "Execution {} started; polling for messages...",
        execution.id()?
    );

    // The end is detected from the message stream, not by waiting on the
    // execution: a wait call does not pump the queue, so a synchronous message
    // would sit unacknowledged and both sides would stop.
    let started = Instant::now();
    let mut ended = false;
    while started.elapsed() < Duration::from_secs(60) && !ended {
        while !engine.is_ui_message_queue_empty()? {
            let message = engine.get_ui_message()?;
            let code = message.event()?;
            if matches!(
                UIMessageCode::from_bits(code),
                Ok(UIMessageCode::EndExecution)
            ) {
                ended = true;
            }
            let origin = if UIMessageCode::is_user_message(code) {
                "sequence".to_owned()
            } else {
                format!("engine {:?}", UIMessageCode::from_bits(code))
            };
            println!(
                "  [{origin}] code={code} numeric={} string={:?} synchronous={}",
                message.numeric_data()?,
                message.string_data()?,
                message.is_synchronous()?
            );
            // Required: releases a synchronous poster and asks for the next.
            message.acknowledge()?;
        }
    }

    println!("\nExecution ended: {ended}");
    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn new_step( &self, adapter_key_name: &str, step_type_name: &str, ) -> Result<Step, Error>

Creates a step (Engine.NewStep).

adapter_key_name selects the code-module adapter, see AdapterKeyName. step_type_name names the step type, for example NumericLimitTest or Action.

An empty key does not mean “no code module”. It means the step type chooses, falling back to the station’s DefaultAdapter when the type designates none, so an empty key on an Action yields whatever adapter the station happens to default to. Pass AdapterKeyName::NoneAdapter to actually mean no code module.

The step is not part of any sequence until it is inserted.

Errors

Error if the step type is unknown or the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 103)

fn step_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name(STEP_TEMPLATE)?;
    step.set_post_expression(r#"Locals.Result = "Hello from step template!""#)?;
    step.as_property_object()
}

/// A whole sequence, one step included, as a single prototype.
fn sequence_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let sequence = engine.new_sequence()?;
    sequence.set_name(SEQUENCE_TEMPLATE)?;

    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name("Inside_Sequence_Template")?;
    sequence.insert_step(&step, 0, StepGroup::Main)?;

    sequence.as_property_object()
}

examples/result_list_parse.rs (line 42)

fn add_pass_fail(
    engine: &Engine,
    sequence: &Sequence,
    name: &str,
    source: &str,
) -> Result<(), Error> {
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "PassFailTest")?;
    step.set_name(name)?;
    step.as_property_object()?
        .set_val_string("DataSource", insert_if_missing(), source)?;
    sequence.insert_step(
        &step,
        sequence.get_num_steps(StepGroup::Main)?,
        StepGroup::Main,
    )
}

/// Adds a numeric limit test with a fixed measurement.
fn add_numeric(
    engine: &Engine,
    sequence: &Sequence,
    name: &str,
    source: &str,
    low: f64,
    high: f64,
) -> Result<(), Error> {
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "NumericLimitTest")?;
    step.set_name(name)?;
    let properties = step.as_property_object()?;
    properties.set_val_string("DataSource", insert_if_missing(), source)?;
    properties.set_val_number("Limits.Low", insert_if_missing(), low)?;
    properties.set_val_number("Limits.High", insert_if_missing(), high)?;
    sequence.insert_step(
        &step,
        sequence.get_num_steps(StepGroup::Main)?,
        StepGroup::Main,
    )
}

/// Adds a statement step that records nothing, to show the gap it leaves.
fn add_unrecorded_filler(engine: &Engine, sequence: &Sequence, name: &str) -> Result<(), Error> {
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "Statement")?;
    step.set_name(name)?;
    step.set_result_recording_option(ResultRecordingOption::Disabled)?;
    sequence.insert_step(
        &step,
        sequence.get_num_steps(StepGroup::Main)?,
        StepGroup::Main,
    )
}

examples/ui_messages_handle.rs (line 28)

fn add_statement(
    engine: &Engine,
    sequence: &Sequence,
    name: &str,
    expression: &str,
) -> Result<(), rs_teststand::Error> {
    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name(name)?;
    step.as_property_object()?
        .set_val_string("TS.PostExpr", INSERT_IF_MISSING, expression)?;
    sequence.insert_step(
        &step,
        sequence.get_num_steps(StepGroup::Main)?,
        StepGroup::Main,
    )?;
    Ok(())
}

examples/sequence_build.rs (line 35)

fn numeric_limit_test(
    engine: &Engine,
    name: &str,
    precondition: &str,
    low: f64,
    high: f64,
) -> Result<Step, rs_teststand::Error> {
    let step = engine.new_step(NO_ADAPTER, "NumericLimitTest")?;
    step.set_name(name)?;
    step.set_precondition(precondition)?;
    step.set_record_result(true)?;

    let properties = step.as_property_object()?;
    properties.set_val_number("Limits.High", INSERT_IF_MISSING, high)?;
    properties.set_val_number("Limits.Low", INSERT_IF_MISSING, low)?;
    Ok(step)
}

fn describe(sequence: &Sequence) -> Result<(), rs_teststand::Error> {
    let count = sequence.get_num_steps(StepGroup::Main)?;
    println!("{} holds {count} step(s) in Main:", sequence.name()?);
    for index in 0..count {
        let step = sequence.get_step(index, StepGroup::Main)?;
        let properties = step.as_property_object()?;
        println!("  [{index}] {}", step.name()?);
        if properties.exists("Limits.Low", NO_OPTIONS)? {
            println!(
                "      limits: low={}, high={}",
                properties.get_val_number("Limits.Low", NO_OPTIONS)?,
                properties.get_val_number("Limits.High", NO_OPTIONS)?
            );
        }
        let precondition = step.precondition()?;
        if !precondition.is_empty() {
            println!("      runs when: {precondition}");
        }
    }
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Steps are placed by group and index, so order is explicit.
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Temperature Check",
            "Locals.TempSensorPresent == True",
            15.0,
            85.0,
        )?,
        0,
        StepGroup::Main,
    )?;
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Voltage Monitor",
            "Locals.DUTPowered == True",
            4.75,
            5.25,
        )?,
        1,
        StepGroup::Main,
    )?;

    // A subsequence, so a later example has something to call.
    let subsequence = engine.new_sequence()?;
    subsequence.set_name("CustomSubsequence")?;
    sequence_file.insert_sequence(&subsequence)?;

    let init_step = engine.new_step(NO_ADAPTER, "Action")?;
    init_step.set_name("Initialize Hardware")?;
    subsequence.insert_step(&init_step, 0, StepGroup::Main)?;

    describe(&main_sequence)?;
    println!();
    describe(&subsequence)?;

    // Cleanup runs even when Main fails, which is why it is worth showing.
    println!(
        "\nGroup sizes in MainSequence: setup={}, main={}, cleanup={}",
        main_sequence.get_num_steps(StepGroup::Setup)?,
        main_sequence.get_num_steps(StepGroup::Main)?,
        main_sequence.get_num_steps(StepGroup::Cleanup)?
    );

    let path = std::env::temp_dir().join("rs_teststand_built_sequence.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

examples/step_insert_from_template.rs (line 54)

fn build_prototype(engine: &Engine) -> Result<Step, Error> {
    // The maintained LabVIEW adapter. The standard-prototype key still exists
    // but the documentation marks it obsolete in favour of this one.
    let step = engine.new_step(AdapterKeyName::LabView.as_str(), "Action")?;
    step.set_name("Measure (VI)")?;
    step.set_run_mode(RunMode::Normal)?;
    step.as_property_object()?.set_val_string(
        VI_PATH,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        r"example.lvlibp\measure.vi",
    )?;
    Ok(step)
}

examples/execution_run_subsequence.rs (line 48)

fn add_action(engine: &Engine, sequence: &Sequence, name: &str) -> Result<(), Error> {
    // The None adapter is what actually means "no code module"; an empty key
    // would let the step type pick, and a step on a real adapter fails at run
    // time with "module has not yet been specified".
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "Action")?;
    step.set_name(name)?;
    step.set_record_result(true)?;
    sequence.insert_step(
        &step,
        sequence.get_num_steps(StepGroup::Main)?,
        StepGroup::Main,
    )
}

Additional examples can be found in:

• examples/execution_run_test_headless.rs
• examples/step_insert.rs

pub fn new_sequence(&self) -> Result<Sequence, Error>

Creates a sequence (Engine.NewSequence).

The sequence is not part of any file until it is inserted.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/template_manage_complex.rs (line 111)

fn sequence_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let sequence = engine.new_sequence()?;
    sequence.set_name(SEQUENCE_TEMPLATE)?;

    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name("Inside_Sequence_Template")?;
    sequence.insert_step(&step, 0, StepGroup::Main)?;

    sequence.as_property_object()
}

examples/execution_run_subsequence.rs (line 67)

fn build(engine: &Engine) -> Result<SequenceFile, Error> {
    let sequence_file = engine.new_sequence_file()?;

    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for name in ["Initialize", "Run Test", "Shut Down"] {
        add_action(engine, &main_sequence, name)?;
    }

    let diagnostics = engine.new_sequence()?;
    diagnostics.set_name(SUBSEQUENCE)?;
    // A parameter is an ordinary property in the sequence's Parameters scope.
    diagnostics.parameters()?.new_sub_property(
        PARAMETER,
        PropValType::String,
        false,
        "",
        insert_if_missing(),
    )?;
    for name in ["Check Power Rails", "Check Clock"] {
        add_action(engine, &diagnostics, name)?;
    }
    sequence_file.insert_sequence(&diagnostics)?;

    Ok(sequence_file)
}

examples/sequence_build.rs (line 98)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Steps are placed by group and index, so order is explicit.
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Temperature Check",
            "Locals.TempSensorPresent == True",
            15.0,
            85.0,
        )?,
        0,
        StepGroup::Main,
    )?;
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Voltage Monitor",
            "Locals.DUTPowered == True",
            4.75,
            5.25,
        )?,
        1,
        StepGroup::Main,
    )?;

    // A subsequence, so a later example has something to call.
    let subsequence = engine.new_sequence()?;
    subsequence.set_name("CustomSubsequence")?;
    sequence_file.insert_sequence(&subsequence)?;

    let init_step = engine.new_step(NO_ADAPTER, "Action")?;
    init_step.set_name("Initialize Hardware")?;
    subsequence.insert_step(&init_step, 0, StepGroup::Main)?;

    describe(&main_sequence)?;
    println!();
    describe(&subsequence)?;

    // Cleanup runs even when Main fails, which is why it is worth showing.
    println!(
        "\nGroup sizes in MainSequence: setup={}, main={}, cleanup={}",
        main_sequence.get_num_steps(StepGroup::Setup)?,
        main_sequence.get_num_steps(StepGroup::Main)?,
        main_sequence.get_num_steps(StepGroup::Cleanup)?
    );

    let path = std::env::temp_dir().join("rs_teststand_built_sequence.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

examples/step_insert.rs (line 79)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;

    // A file to insert into. Built here so the example depends on nothing that
    // has to exist on the station first.
    let sequence_file = engine.new_sequence_file()?;
    let subsequence = engine.new_sequence()?;
    subsequence.set_name("CustomSubsequence")?;
    let existing = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "Action")?;
    existing.set_name(TARGET_STEP)?;
    subsequence.insert_step(&existing, 0, StepGroup::Main)?;
    sequence_file.insert_sequence(&subsequence)?;

    // Where to insert: in front of the target, or at the end if it is absent.
    let insert_at = if let Some(index) = index_of(&subsequence, TARGET_STEP, StepGroup::Main)? {
        println!("Found {TARGET_STEP} at index {index}; inserting in front of it.");
        index
    } else {
        let end = subsequence.get_num_steps(StepGroup::Main)?;
        println!("{TARGET_STEP} not found; appending at index {end}.");
        end
    };

    for (offset, (name, vi, project, mode)) in [
        (
            "Measure Voltage (VI)",
            r"instruments.lvlibp\measure_voltage.vi",
            "",
            RunMode::Normal,
        ),
        (
            "Measure Current (VI)",
            r"instruments.lvlibp\measure_current.vi",
            r"instruments.lvproj",
            RunMode::Skip,
        ),
    ]
    .into_iter()
    .enumerate()
    {
        let step = vi_call_step(&engine, name, vi, project, mode)?;
        let at = insert_at + i32::try_from(offset).unwrap_or(0);
        subsequence.insert_step(&step, at, StepGroup::Main)?;
    }

    println!(
        "\n{} now holds {} step(s):",
        subsequence.name()?,
        subsequence.get_num_steps(StepGroup::Main)?
    );
    for index in 0..subsequence.get_num_steps(StepGroup::Main)? {
        let step = subsequence.get_step(index, StepGroup::Main)?;
        let properties = step.as_property_object()?;
        let vi = properties
            .get_val_string(VI_PATH, none())
            .unwrap_or_else(|_| "<no VI>".to_owned());
        println!(
            "  [{index}] {} - {:?}, run mode {:?}, records {:?}",
            step.name()?,
            step.adapter_key_name()?,
            step.run_mode()?,
            step.result_recording_option()?
        );
        if vi != "<no VI>" {
            println!("        calls {vi}");
        }
    }

    let path = std::env::temp_dir().join("rs_teststand_step_insert.seq");
    let path = path.to_string_lossy().into_owned();
    sequence_file.save(&path)?;
    println!("\nSaved to {path}");
    Ok(())
}

pub fn new_user(&self, profile: Option<&User>) -> Result<User, Error>

Creates a user account object (Engine.NewUser).

Pass an existing user as profile to inherit its privileges; the new user does not join any group the profile belongs to. Pass None for a user with no privileges.

The result exists only in memory, nothing is written to the station’s users file by creating one.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/users_manage.rs (line 33)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    // Passing no profile means the user inherits nothing.
    let user = engine.new_user(None)?;
    user.set_login_name("operator1")?;
    user.set_full_name("Test Operator")?;
    user.set_password("ts-secret")?;

    println!("User: {} ({})", user.login_name()?, user.full_name()?);

    // Check a credential without handling the stored value.
    println!(
        "  password 'ts-secret' valid: {}",
        user.validate_password("ts-secret")?
    );
    println!(
        "  password 'wrong' valid:     {}",
        user.validate_password("wrong")?
    );

    println!("  privilege checks:");
    report_privileges(
        &user,
        &[
            UserPrivilege::Operate,
            UserPrivilege::Execute,
            UserPrivilege::Develop,
            UserPrivilege::Debug,
            UserPrivilege::EditUsers,
        ],
    )?;

    // A privilege can also be named by its full path, which is how a leaf
    // inside a category is reached.
    println!(
        "  Debug.RunSelectedTests:  {}",
        user.has_privilege_named("Debug.RunSelectedTests")?
    );

    // The privilege tree is nested: categories hold the individual rights.
    let privileges = user.privileges()?;
    let count = privileges.get_num_sub_properties("")?;
    println!("  privilege tree ({count} categories):");
    for index in 0..count {
        let name = privileges.get_nth_sub_property_name("", index, 0)?;
        let members = privileges
            .get_property_object(&name, 0)?
            .get_num_sub_properties("")?;
        println!("    {name:<12} {members} member(s)");
    }

    // The station itself, read-only.
    println!("\nStation:");
    match engine.current_user()? {
        Some(current) => println!("  logged in as {}", current.login_name()?),
        None => println!("  nobody logged in (usual when login is not required)"),
    }
    println!(
        "  is 'operator1' a real account here? {}",
        engine.user_name_exists("operator1")?
    );

    // Where accounts actually live. Everything above this point exists only in
    // memory: `new_user` builds a User, it does not enrol one. A user becomes
    // part of the station when it is inserted into this file's list and the
    // file is written.
    let users_file = engine.users_file()?;
    let file = users_file.as_property_object_file()?;
    println!(
        "
Users file:"
    );
    println!("  path            {}", file.path()?);
    println!(
        "  users           {}",
        users_file.user_list()?.get_num_elements()?
    );
    println!(
        "  groups          {}",
        users_file.user_group_list()?.get_num_elements()?
    );
    println!(
        "  profiles        {}",
        users_file.user_profile_list()?.get_num_elements()?
    );

    // Deliberately not run: it would edit the station this example is reading.
    // The two calls a host makes to enrol the user built above are
    //
    //     users_file.user_list()?.set_num_elements(count + 1, 0)?;   // then fill
    //     file.save_file_if_modified(false)?;                        // then write
    //
    // `false` matters: with `true` the engine puts a save dialog on screen, and
    // a host with no operator would wait for an answer that never comes.
    println!(
        "
  (this example does not write; enrolling a user would alter the station)"
    );

    Ok(())
}

pub fn get_user(&self, login_name: &str) -> Result<Option<User>, Error>

Finds a user by login name (Engine.GetUser).

Returns None when no user has that name, rather than erroring.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn user_name_exists(&self, login_name: &str) -> Result<bool, Error>

Whether a login name is already taken (Engine.UserNameExists).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/users_manage.rs (line 89)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    // Passing no profile means the user inherits nothing.
    let user = engine.new_user(None)?;
    user.set_login_name("operator1")?;
    user.set_full_name("Test Operator")?;
    user.set_password("ts-secret")?;

    println!("User: {} ({})", user.login_name()?, user.full_name()?);

    // Check a credential without handling the stored value.
    println!(
        "  password 'ts-secret' valid: {}",
        user.validate_password("ts-secret")?
    );
    println!(
        "  password 'wrong' valid:     {}",
        user.validate_password("wrong")?
    );

    println!("  privilege checks:");
    report_privileges(
        &user,
        &[
            UserPrivilege::Operate,
            UserPrivilege::Execute,
            UserPrivilege::Develop,
            UserPrivilege::Debug,
            UserPrivilege::EditUsers,
        ],
    )?;

    // A privilege can also be named by its full path, which is how a leaf
    // inside a category is reached.
    println!(
        "  Debug.RunSelectedTests:  {}",
        user.has_privilege_named("Debug.RunSelectedTests")?
    );

    // The privilege tree is nested: categories hold the individual rights.
    let privileges = user.privileges()?;
    let count = privileges.get_num_sub_properties("")?;
    println!("  privilege tree ({count} categories):");
    for index in 0..count {
        let name = privileges.get_nth_sub_property_name("", index, 0)?;
        let members = privileges
            .get_property_object(&name, 0)?
            .get_num_sub_properties("")?;
        println!("    {name:<12} {members} member(s)");
    }

    // The station itself, read-only.
    println!("\nStation:");
    match engine.current_user()? {
        Some(current) => println!("  logged in as {}", current.login_name()?),
        None => println!("  nobody logged in (usual when login is not required)"),
    }
    println!(
        "  is 'operator1' a real account here? {}",
        engine.user_name_exists("operator1")?
    );

    // Where accounts actually live. Everything above this point exists only in
    // memory: `new_user` builds a User, it does not enrol one. A user becomes
    // part of the station when it is inserted into this file's list and the
    // file is written.
    let users_file = engine.users_file()?;
    let file = users_file.as_property_object_file()?;
    println!(
        "
Users file:"
    );
    println!("  path            {}", file.path()?);
    println!(
        "  users           {}",
        users_file.user_list()?.get_num_elements()?
    );
    println!(
        "  groups          {}",
        users_file.user_group_list()?.get_num_elements()?
    );
    println!(
        "  profiles        {}",
        users_file.user_profile_list()?.get_num_elements()?
    );

    // Deliberately not run: it would edit the station this example is reading.
    // The two calls a host makes to enrol the user built above are
    //
    //     users_file.user_list()?.set_num_elements(count + 1, 0)?;   // then fill
    //     file.save_file_if_modified(false)?;                        // then write
    //
    // `false` matters: with `true` the engine puts a save dialog on screen, and
    // a host with no operator would wait for an answer that never comes.
    println!(
        "
  (this example does not write; enrolling a user would alter the station)"
    );

    Ok(())
}

pub fn current_user(&self) -> Result<Option<User>, Error>

The user currently logged in (Engine.CurrentUser).

Returns None when nobody is logged in, which is the normal state on a station that does not require a login.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/users_manage.rs (line 83)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    // Passing no profile means the user inherits nothing.
    let user = engine.new_user(None)?;
    user.set_login_name("operator1")?;
    user.set_full_name("Test Operator")?;
    user.set_password("ts-secret")?;

    println!("User: {} ({})", user.login_name()?, user.full_name()?);

    // Check a credential without handling the stored value.
    println!(
        "  password 'ts-secret' valid: {}",
        user.validate_password("ts-secret")?
    );
    println!(
        "  password 'wrong' valid:     {}",
        user.validate_password("wrong")?
    );

    println!("  privilege checks:");
    report_privileges(
        &user,
        &[
            UserPrivilege::Operate,
            UserPrivilege::Execute,
            UserPrivilege::Develop,
            UserPrivilege::Debug,
            UserPrivilege::EditUsers,
        ],
    )?;

    // A privilege can also be named by its full path, which is how a leaf
    // inside a category is reached.
    println!(
        "  Debug.RunSelectedTests:  {}",
        user.has_privilege_named("Debug.RunSelectedTests")?
    );

    // The privilege tree is nested: categories hold the individual rights.
    let privileges = user.privileges()?;
    let count = privileges.get_num_sub_properties("")?;
    println!("  privilege tree ({count} categories):");
    for index in 0..count {
        let name = privileges.get_nth_sub_property_name("", index, 0)?;
        let members = privileges
            .get_property_object(&name, 0)?
            .get_num_sub_properties("")?;
        println!("    {name:<12} {members} member(s)");
    }

    // The station itself, read-only.
    println!("\nStation:");
    match engine.current_user()? {
        Some(current) => println!("  logged in as {}", current.login_name()?),
        None => println!("  nobody logged in (usual when login is not required)"),
    }
    println!(
        "  is 'operator1' a real account here? {}",
        engine.user_name_exists("operator1")?
    );

    // Where accounts actually live. Everything above this point exists only in
    // memory: `new_user` builds a User, it does not enrol one. A user becomes
    // part of the station when it is inserted into this file's list and the
    // file is written.
    let users_file = engine.users_file()?;
    let file = users_file.as_property_object_file()?;
    println!(
        "
Users file:"
    );
    println!("  path            {}", file.path()?);
    println!(
        "  users           {}",
        users_file.user_list()?.get_num_elements()?
    );
    println!(
        "  groups          {}",
        users_file.user_group_list()?.get_num_elements()?
    );
    println!(
        "  profiles        {}",
        users_file.user_profile_list()?.get_num_elements()?
    );

    // Deliberately not run: it would edit the station this example is reading.
    // The two calls a host makes to enrol the user built above are
    //
    //     users_file.user_list()?.set_num_elements(count + 1, 0)?;   // then fill
    //     file.save_file_if_modified(false)?;                        // then write
    //
    // `false` matters: with `true` the engine puts a save dialog on screen, and
    // a host with no operator would wait for an answer that never comes.
    println!(
        "
  (this example does not write; enrolling a user would alter the station)"
    );

    Ok(())
}

pub fn current_user_has_privilege( &self, privilege: UserPrivilege, ) -> Result<bool, Error>

Whether the logged-in user holds a privilege (Engine.CurrentUserHasPrivilege).

Errors

Error if the COM call fails or returns an unexpected type.

pub fn new_property_object( &self, value_type: PropValType, as_array: bool, type_name: &str, options: i32, ) -> Result<PropertyObject, Error>

Creates a standalone PropertyObject (Engine.NewPropertyObject).

The object belongs to no sequence file or station; it is useful as the root of a tree you build in memory. Pass a type name only when value_type is NamedType.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/template_manage_complex.rs (lines 60-65)

fn new_template_group(engine: &Engine) -> Result<PropertyObject, Error> {
    engine.new_property_object(
        PropValType::Container,
        true,
        "",
        PropertyOptions::NONE.bits(),
    )
}

/// Appends a detached copy of a prototype to the group.
///
/// The copy matters: the group must not share the object the caller keeps
/// editing, or adding a second template would change the first.
fn append_template(group: &PropertyObject, template: &PropertyObject) -> Result<(), Error> {
    let index = group.get_num_elements()?;
    group.set_num_elements(index + 1, PropertyOptions::NONE.bits())?;
    group.set_property_object(
        &format!("[{index}]"),
        PropertyOptions::NONE.bits(),
        &template.clone_property("", PropertyOptions::NONE.bits())?,
    )
}

/// Finds a prototype in the group by name.
fn find_template(group: &PropertyObject, name: &str) -> Result<Option<PropertyObject>, Error> {
    for index in 0..group.get_num_elements()? {
        let candidate = group.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        if candidate.name()? == name {
            return Ok(Some(candidate));
        }
    }
    Ok(None)
}

/// Turns "not found" into an error naming the template that is missing.
fn require(found: Option<PropertyObject>, name: &'static str) -> Result<PropertyObject, Error> {
    found.ok_or(Error::UnexpectedType {
        expected: name,
        actual: "no template of that name in the group",
    })
}

/// A configured Statement step, taken as a property tree so it can be cloned.
fn step_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name(STEP_TEMPLATE)?;
    step.set_post_expression(r#"Locals.Result = "Hello from step template!""#)?;
    step.as_property_object()
}

/// A whole sequence, one step included, as a single prototype.
fn sequence_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let sequence = engine.new_sequence()?;
    sequence.set_name(SEQUENCE_TEMPLATE)?;

    let step = engine.new_step(NO_ADAPTER, "Statement")?;
    step.set_name("Inside_Sequence_Template")?;
    sequence.insert_step(&step, 0, StepGroup::Main)?;

    sequence.as_property_object()
}

/// A string variable carrying its default value.
fn variable_template(engine: &Engine) -> Result<PropertyObject, Error> {
    let variable =
        engine.new_property_object(PropValType::String, false, "", PropertyOptions::NONE.bits())?;
    variable.set_name(VARIABLE_TEMPLATE)?;
    variable.set_val_string("", PropertyOptions::NONE.bits(), "Template Variable Value")?;
    Ok(variable)
}

examples/data_type_manage.rs (line 29)

fn build_multimeter_type(engine: &Engine) -> Result<PropertyObject, rs_teststand::Error> {
    let data_type = engine.new_property_object(PropValType::Container, false, "", NO_OPTIONS)?;
    data_type.set_val_number("Resolution", INSERT_IF_MISSING, 6.5)?;
    data_type.set_val_bool("AutoZero", INSERT_IF_MISSING, false)?;
    data_type.set_val_string("Mode", INSERT_IF_MISSING, "Voltage")?;
    data_type.set_val_number("Range", INSERT_IF_MISSING, 100.0)?;
    data_type.set_name("DigitalMultimeter")?;
    Ok(data_type)
}

/// Builds the array `UpdateEnumerators` expects.
///
/// One container per enumerator, each carrying `EnumeratorName` and
/// `EnumeratorValue`. Strictness is an attribute of the array, not a member of
/// it, a strict enumeration refuses values outside the declared set.
fn enumerator_array(
    engine: &Engine,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let array = engine.new_property_object(PropValType::Container, true, "", NO_OPTIONS)?;
    array.set_num_elements(i32::try_from(named_values.len()).unwrap_or(0), NO_OPTIONS)?;
    for (index, (name, value)) in named_values.iter().enumerate() {
        let element =
            array.get_property_object_by_offset(i32::try_from(index).unwrap_or(0), NO_OPTIONS)?;
        element.set_val_string("EnumeratorName", INSERT_IF_MISSING, name)?;
        element.set_val_number("EnumeratorValue", INSERT_IF_MISSING, *value)?;
    }
    array
        .attributes()?
        .set_val_bool(IS_STRICT_ATTRIBUTE, INSERT_IF_MISSING, strict)?;
    Ok(array)
}

/// Registers an enumeration, then returns its **registered** definition.
///
/// The distinction matters: enumerators can only be set on the definition the
/// file holds, not on the loose object that was inserted.
fn register_enum(
    engine: &Engine,
    types: &TypeUsageList,
    name: &str,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let enum_type = engine.new_property_object(PropValType::Enum, false, "", NO_OPTIONS)?;
    enum_type.set_name(name)?;
    types.insert_type(
        &enum_type,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;

    let definition = types.get_type_definition(types.get_type_index(name)?)?;
    definition.update_enumerators(&enumerator_array(engine, named_values, strict)?)?;
    Ok(definition)
}

pub fn close(self, timeout: Duration) -> Result<bool, Error>

Shuts the engine down and leaves this thread’s COM apartment.

For a host that owns the engine on a spawned thread. Such a thread really does detach when it ends, so the apartment it initialized has to be closed or the COM runtime is left believing a live thread still owns one. The process’s main thread does not need this: it is ending anyway.

Consuming self is what makes the ordering safe, the engine is released before the apartment closes, and no caller can hold a reference across the boundary.

Errors

Error if a COM call during shutdown fails. The apartment is closed either way.

pub fn shutdown(&self, timeout: Duration) -> Result<bool, Error>

Closes files, terminates executions, and waits for the engine to say it is done (Engine.ShutDown).

ShutDown is asynchronous. It returns as soon as the request is accepted, having only started terminating executions and closing files; the engine reports completion later by posting UIMessageCode::ShutDownComplete to its message queue. So a caller that simply calls it and drops the engine tears down COM underneath work that is still running.

This does the whole protocol: enables message polling, asks the engine to shut down, then pumps and drains until the engine confirms or timeout elapses.

Returns true when the engine confirmed. false means the timeout came first, or the engine posted ShutDownCanceled, which a sequence can cause, for instance by refusing to terminate. Either way the wait is bounded: an unattended host must not be able to hang here.

Shutting down twice is harmless; the second call simply finds nothing to do and returns once the engine answers.

Errors

Error if a COM call fails.

pub fn get_templates_file( &self, options: GetTemplatesFileOptions, ) -> Result<PropertyObjectFile, Error>

The station’s templates file (Engine.GetTemplatesFile).

Holds the variable, step and sequence prototypes the editor offers when inserting. It is a station-wide file, so it is empty until someone adds templates to it, an empty one is the normal state, not a failure.

A template is an ordinary PropertyObject, not a type of its own, so a program is free to keep its own prototypes in a container it builds itself rather than in this file.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/step_insert_from_template.rs (line 34)

fn describe_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        if category.name()? == "Steps" {
            println!(
                "Step templates defined on this station: {}",
                category.get_num_elements()?
            );
        }
    }
    Ok(())
}

examples/template_manage_complex.rs (line 41)

fn describe_station_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;

    println!("Station templates file: {}", templates_file.path()?);
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        println!(
            "  {}: {} template(s)",
            category.name()?,
            category.get_num_elements()?
        );
    }
    Ok(())
}

pub fn get_sequence_file_ex( &self, path: &str, options: GetSeqFileOptions, handler: ConflictHandler, ) -> Result<SequenceFile, Error>

Opens a sequence file, or returns the already-loaded one (Engine.GetSequenceFileEx).

The engine caches the file and counts load references, so every successful call must be paired with release_sequence_file_ex.

Both option arguments matter on an unattended host: crate::sequence::GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK suppresses a load callback that could raise a dialog, and crate::sequence::ConflictHandler::Error fails the load instead of prompting.

Errors

Error if the file cannot be opened or the COM call fails.

Examples found in repository

examples/variables_manage.rs (lines 88-92)

fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

examples/template_manage_complex.rs (lines 198-202)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_station_templates(&engine)?;

    println!("\nBuilding an in-memory template group...");
    let group = new_template_group(&engine)?;
    append_template(&group, &step_template(&engine)?)?;
    append_template(&group, &sequence_template(&engine)?)?;
    append_template(&group, &variable_template(&engine)?)?;
    println!("  {} template(s) stored", group.get_num_elements()?);

    let step = require(find_template(&group, STEP_TEMPLATE)?, STEP_TEMPLATE)?;
    let sequence = require(find_template(&group, SEQUENCE_TEMPLATE)?, SEQUENCE_TEMPLATE)?;
    let variable = require(find_template(&group, VARIABLE_TEMPLATE)?, VARIABLE_TEMPLATE)?;

    // Saving first, then reopening, is deliberate: templates are worth having
    // because they are applied to files a program did not build in this run.
    let path = std::env::temp_dir().join("rs_teststand_from_templates.seq");
    let path = path.to_string_lossy().into_owned();
    engine.new_sequence_file()?.save(&path)?;

    println!("\nApplying templates to the saved file...");
    let target = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        rs_teststand::ConflictHandler::Error,
    )?;
    apply_templates(&target, &step, &sequence, &variable)?;
    target.save(&path)?;
    println!("\nSaved to {path}");

    engine.release_sequence_file_ex(target, PropertyOptions::NONE.bits())?;
    Ok(())
}

pub fn release_sequence_file_ex( &self, sequence_file: SequenceFile, options: i32, ) -> Result<bool, Error>

Drops one load reference on a sequence file (Engine.ReleaseSequenceFileEx).

Returns true when that was the last reference and the engine has discarded the file. false means something else still holds it open, so the file stays loaded, which is why only the true case also releases the wrapper’s own COM reference.

Errors

Error if the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 166)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = build(&engine)?;
    println!("File holds {} sequence(s).", sequence_file.num_sequences()?);

    // The conventional entry point.
    run(&engine, &sequence_file, "MainSequence")?;

    // A subsequence run on its own has no caller, so nothing supplies its
    // parameters, they keep whatever default the sequence carries. Setting
    // that default is therefore how a direct run is given its input.
    let diagnostics = sequence_file.get_sequence_by_name(SUBSEQUENCE)?;
    diagnostics
        .parameters()?
        .set_val_string(PARAMETER, none(), "FIXTURE-07")?;
    println!(
        "\n{SUBSEQUENCE}.{PARAMETER} default is now {:?}",
        diagnostics
            .parameters()?
            .get_val_string(PARAMETER, none())?
    );

    run(&engine, &sequence_file, SUBSEQUENCE)?;

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/execution_run_test_headless.rs (line 171)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    // Nothing reaches the queue until this is on, and without the queue there
    // is no way to know the run ended.
    engine.set_ui_message_polling_enabled(true)?;

    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    for (name, data_source, low, high) in TESTS {
        add_numeric_limit_test(&engine, &main_sequence, name, data_source, low, high)?;
    }

    let execution = engine.new_execution(&sequence_file, "MainSequence", None, false, 0)?;
    println!("Running {} headless...", execution.display_name()?);

    if wait_for_end(&engine, RUN_DEADLINE)? {
        println!("Finished with status: {}", execution.result_status()?);
        report(&execution.result_object()?)?;
    } else {
        // Reported rather than ignored: a host that assumes success here would
        // publish results from a run that never finished.
        println!("The run did not finish within {RUN_DEADLINE:?}; terminating.");
        execution.terminate()?;
    }

    engine.release_sequence_file_ex(sequence_file, none())?;
    Ok(())
}

examples/template_manage_complex.rs (line 207)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    describe_station_templates(&engine)?;

    println!("\nBuilding an in-memory template group...");
    let group = new_template_group(&engine)?;
    append_template(&group, &step_template(&engine)?)?;
    append_template(&group, &sequence_template(&engine)?)?;
    append_template(&group, &variable_template(&engine)?)?;
    println!("  {} template(s) stored", group.get_num_elements()?);

    let step = require(find_template(&group, STEP_TEMPLATE)?, STEP_TEMPLATE)?;
    let sequence = require(find_template(&group, SEQUENCE_TEMPLATE)?, SEQUENCE_TEMPLATE)?;
    let variable = require(find_template(&group, VARIABLE_TEMPLATE)?, VARIABLE_TEMPLATE)?;

    // Saving first, then reopening, is deliberate: templates are worth having
    // because they are applied to files a program did not build in this run.
    let path = std::env::temp_dir().join("rs_teststand_from_templates.seq");
    let path = path.to_string_lossy().into_owned();
    engine.new_sequence_file()?.save(&path)?;

    println!("\nApplying templates to the saved file...");
    let target = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        rs_teststand::ConflictHandler::Error,
    )?;
    apply_templates(&target, &step, &sequence, &variable)?;
    target.save(&path)?;
    println!("\nSaved to {path}");

    engine.release_sequence_file_ex(target, PropertyOptions::NONE.bits())?;
    Ok(())
}

examples/sequence_build.rs (line 122)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

    // Steps are placed by group and index, so order is explicit.
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Temperature Check",
            "Locals.TempSensorPresent == True",
            15.0,
            85.0,
        )?,
        0,
        StepGroup::Main,
    )?;
    main_sequence.insert_step(
        &numeric_limit_test(
            &engine,
            "Voltage Monitor",
            "Locals.DUTPowered == True",
            4.75,
            5.25,
        )?,
        1,
        StepGroup::Main,
    )?;

    // A subsequence, so a later example has something to call.
    let subsequence = engine.new_sequence()?;
    subsequence.set_name("CustomSubsequence")?;
    sequence_file.insert_sequence(&subsequence)?;

    let init_step = engine.new_step(NO_ADAPTER, "Action")?;
    init_step.set_name("Initialize Hardware")?;
    subsequence.insert_step(&init_step, 0, StepGroup::Main)?;

    describe(&main_sequence)?;
    println!();
    describe(&subsequence)?;

    // Cleanup runs even when Main fails, which is why it is worth showing.
    println!(
        "\nGroup sizes in MainSequence: setup={}, main={}, cleanup={}",
        main_sequence.get_num_steps(StepGroup::Setup)?,
        main_sequence.get_num_steps(StepGroup::Main)?,
        main_sequence.get_num_steps(StepGroup::Cleanup)?
    );

    let path = std::env::temp_dir().join("rs_teststand_built_sequence.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

examples/variables_manage.rs (line 224)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    show_station_globals(&engine)?;

    // The other three scopes need a sequence file.
    if let Some(sequence_file) = open_sequence_file(&engine)? {
        // File globals: shared by every sequence in this file. These are the
        // defaults stored in the file; a running execution gets its own copy.
        let file_globals = sequence_file.file_globals_default_values()?;
        set_string(&file_globals, "BatchID", "BATCH-2026-Q2-001")?;
        println!(
            "FileGlobals.BatchID                   = '{}'",
            file_globals.get_val_string("BatchID", 0)?
        );

        let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

        // Locals: private to one call of this sequence.
        let locals = main_sequence.locals()?;
        set_string(&locals, "OperatorName", "Alice")?;
        println!(
            "MainSequence.Locals.OperatorName      = '{}'",
            locals.get_val_string("OperatorName", 0)?
        );

        // Parameters: supplied by whoever calls this sequence.
        let parameters = main_sequence.parameters()?;
        set_string(&parameters, "DUTSerial", "SN-000000")?;
        println!(
            "MainSequence.Parameters.DUTSerial     = '{}'",
            parameters.get_val_string("DUTSerial", 0)?
        );

        println!("\nTemporary variable lifecycle (Locals.TempScratch):");
        temporary_variable_lifecycle(&locals)?;

        // Nothing is saved: the file is left exactly as it was found.
        engine.release_sequence_file_ex(sequence_file, 0)?;
    } else {
        println!("\n(pass a .seq path to also demonstrate locals, parameters and file globals)");
        println!("\nTemporary variable lifecycle (StationGlobals.TempScratch):");
        temporary_variable_lifecycle(&engine.globals()?)?;
    }

    engine.commit_globals_to_disk(false)?;
    println!("\nStation globals committed to disk.");
    Ok(())
}

examples/data_type_manage.rs (line 174)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let file = sequence_file.as_property_object_file()?;
    let types = file.type_usage_list()?;

    types.insert_type(
        &build_multimeter_type(&engine)?,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;
    let coupling = register_enum(
        &engine,
        &types,
        "Coupling",
        &[("AC", 0.0), ("DC", 1.0)],
        true,
    )?;

    // A variable of the enum type, so the change below has an instance to update.
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    main_sequence.locals()?.new_sub_property(
        "InputCoupling",
        PropValType::NamedType,
        false,
        "Coupling",
        INSERT_IF_MISSING,
    )?;

    println!(
        "Registered custom data types ({} in file):",
        types.num_types()?
    );
    print_enumerators(&coupling)?;

    // Evolve it: add an enumerator and raise the version.
    println!(
        "\nCoupling version before update: {}",
        coupling.type_version()?
    );
    coupling.update_enumerators(&enumerator_array(
        &engine,
        &[("AC", 0.0), ("DC", 1.0), ("GND", 2.0)],
        true,
    )?)?;

    // Raising the lowest field signals a change the engine applies silently;
    // raising a higher one marks it as deliberate.
    let version = coupling.type_version()?;
    let mut fields = version.split('.');
    let major: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    let minor: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    coupling.set_type_version(&format!("{major}.{}.0.0", minor + 1))?;
    println!(
        "Coupling version after  update: {}",
        coupling.type_version()?
    );

    println!("\nCoupling now defines (InputCoupling reflects this):");
    print_enumerators(&coupling)?;

    // Saving does nothing unless the file believes it changed.
    file.inc_change_count()?;
    let path = std::env::temp_dir().join("rs_teststand_with_custom_types.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

Additional examples can be found in:

• examples/result_list_parse.rs
• examples/ui_messages_handle.rs

pub fn search_directories(&self) -> Result<SearchDirectories, Error>

Accesses the collection of search directories (Engine.SearchDirectories).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/search_directory_manage.rs (line 51)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let search_directories = engine.search_directories()?;

    println!("Total search directories: {}", search_directories.count()?);
    for (index, directory) in search_directories.iter()?.enumerate() {
        print_entry(index, &directory?)?;
    }

    // Insert at the front, so the new entry is searched first.
    println!("\nInserting a new explicit search directory...");
    let new_path = engine.bin_directory()?;
    search_directories.insert(&new_path, 0, true, "", false, false)?;
    println!("Total after insert: {}", search_directories.count()?);

    let inserted = search_directories.get(0)?;
    println!(
        "New [0] Path: '{}', Subdirs: {}",
        inserted.path()?,
        inserted.search_subdirectories()?
    );

    // A disabled entry stays in the list but is not searched.
    println!("Disabling the new directory...");
    inserted.set_disabled(true)?;
    println!("New [0] Disabled: {}", inserted.disabled()?);

    // Order matters: entries are searched in list order.
    println!("Moving the new directory to index 1...");
    search_directories.move_search_directory(0, 1)?;
    println!(
        "Directory at index 1 is now: '{}'",
        search_directories.get(1)?.path()?
    );

    println!("Removing the added directory to clean up...");
    search_directories.remove(1)?;
    println!("Total after cleanup: {}", search_directories.count()?);

    // The engine writes search directories out at shutdown anyway. Committing
    // now makes the change visible to other processes immediately, and passing
    // `false` keeps a save conflict from raising a dialog.
    engine.commit_globals_to_disk(false)?;
    println!("Committed search directories configuration to disk.");

    Ok(())
}

pub fn globals(&self) -> Result<PropertyObject, Error>

Accesses the station global variables container (Engine.Globals).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/variables_manage.rs (line 102)

fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

    // A container holds mixed types, so one station record can carry the name,
    // a count and a flag without three separate globals.
    set_string(&station_info, "StationName", "STATION_01")?;
    station_info.set_val_number("CalibrationIntervalDays", INSERT_IF_MISSING, 90.0)?;
    station_info.set_val_bool("FixtureInstalled", INSERT_IF_MISSING, true)?;

    // A 64-bit count. `SetValNumber` stores a double, which starts losing whole
    // numbers past 2^53, so anything that counts for the life of a station wants
    // the integer path instead.
    station_info.set_val_integer64("UnitsTestedTotal", INSERT_IF_MISSING, 9_007_199_254_740_993)?;

    // A nested container, because station data is rarely one level deep.
    if !station_info.exists("LastCalibration", 0)? {
        station_info.new_sub_property(
            "LastCalibration",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let calibration = station_info.get_property_object("LastCalibration", 0)?;
    set_string(&calibration, "Technician", "R. Alvarez")?;
    set_string(&calibration, "Date", "2026-06-14")?;

    println!("StationGlobals.StationInfo:");
    println!(
        "  StationName             = '{}'",
        station_info.get_val_string("StationName", 0)?
    );
    println!(
        "  CalibrationIntervalDays = {}",
        station_info.get_val_number("CalibrationIntervalDays", 0)?
    );
    println!(
        "  FixtureInstalled        = {}",
        station_info.get_val_bool("FixtureInstalled", 0)?
    );
    println!(
        "  UnitsTestedTotal        = {}",
        station_info.get_val_integer64("UnitsTestedTotal", 0)?
    );
    println!(
        "  LastCalibration.Technician = '{}' on {}",
        calibration.get_val_string("Technician", 0)?,
        calibration.get_val_string("Date", 0)?
    );

    // Walk the container rather than naming each field, which is what a host
    // does when it does not know the shape in advance.
    println!(
        "  walked, {} field(s):",
        station_info.get_num_sub_properties("")?
    );
    for index in 0..station_info.get_num_sub_properties("")? {
        println!(
            "    {}",
            station_info.get_nth_sub_property_name("", index, 0)?
        );
    }

    // Station globals live in memory until this is called. Without it the values
    // above are gone when the engine goes away, which is the difference between
    // a station global and a file global.
    // `false` means do not prompt if another process changed the file first.
    // An example must never raise a dialog, and neither must a headless host.
    engine.commit_globals_to_disk(false)?;
    println!("  committed to disk");

    Ok(())
}

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    show_station_globals(&engine)?;

    // The other three scopes need a sequence file.
    if let Some(sequence_file) = open_sequence_file(&engine)? {
        // File globals: shared by every sequence in this file. These are the
        // defaults stored in the file; a running execution gets its own copy.
        let file_globals = sequence_file.file_globals_default_values()?;
        set_string(&file_globals, "BatchID", "BATCH-2026-Q2-001")?;
        println!(
            "FileGlobals.BatchID                   = '{}'",
            file_globals.get_val_string("BatchID", 0)?
        );

        let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

        // Locals: private to one call of this sequence.
        let locals = main_sequence.locals()?;
        set_string(&locals, "OperatorName", "Alice")?;
        println!(
            "MainSequence.Locals.OperatorName      = '{}'",
            locals.get_val_string("OperatorName", 0)?
        );

        // Parameters: supplied by whoever calls this sequence.
        let parameters = main_sequence.parameters()?;
        set_string(&parameters, "DUTSerial", "SN-000000")?;
        println!(
            "MainSequence.Parameters.DUTSerial     = '{}'",
            parameters.get_val_string("DUTSerial", 0)?
        );

        println!("\nTemporary variable lifecycle (Locals.TempScratch):");
        temporary_variable_lifecycle(&locals)?;

        // Nothing is saved: the file is left exactly as it was found.
        engine.release_sequence_file_ex(sequence_file, 0)?;
    } else {
        println!("\n(pass a .seq path to also demonstrate locals, parameters and file globals)");
        println!("\nTemporary variable lifecycle (StationGlobals.TempScratch):");
        temporary_variable_lifecycle(&engine.globals()?)?;
    }

    engine.commit_globals_to_disk(false)?;
    println!("\nStation globals committed to disk.");
    Ok(())
}

pub fn new_workspace_file(&self) -> Result<WorkspaceFile, Error>

Creates a new workspace file object (Engine.NewWorkspaceFile).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/workspace_create.rs (line 9)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    println!("Creating a new workspace file...");
    let ws_file = engine.new_workspace_file()?;
    let root_obj = ws_file.root_workspace_object()?;

    println!("Root workspace object:");
    println!("  Display Name: '{}'", root_obj.display_name()?);
    println!("  Object Type: {}", root_obj.object_type()?);
    println!("  Child Objects: {}", root_obj.num_contained_objects()?);

    println!("\nCreating project and folder structure...");
    let project = root_obj.new_folder("Project Alpha")?;
    println!("  Created project folder: '{}'", project.display_name()?);

    let seq_entry = project.new_file("MainTest.seq")?;
    println!(
        "  Created sequence file entry: '{}'",
        seq_entry.display_name()?
    );

    println!(
        "\nUpdated root child objects count: {}",
        root_obj.num_contained_objects()?
    );

    Ok(())
}

pub fn open_workspace_file( &self, path: &str, read_only: bool, options: i32, ) -> Result<WorkspaceFile, Error>

Opens an existing workspace file (Engine.OpenWorkspaceFile).

Errors

Error if the COM call fails or returns an unexpected type.

pub fn commit_globals_to_disk( &self, prompt_on_save_conflicts: bool, ) -> Result<(), Error>

Flushes modified station globals and configuration to disk (Engine.CommitGlobalsToDisk).

Errors

Error if the COM call fails.

Examples found in repository

examples/station_options_update.rs (line 27)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let station_options = engine.station_options()?;

    station_options.set_tracing_enabled(true)?;
    station_options.set_disable_results(false)?;
    station_options.set_breakpoints_enabled(true)?;
    station_options.set_check_out_files_when_edited(false)?;
    station_options.set_language("English")?;
    station_options.set_always_goto_cleanup_on_failure(true)?;
    station_options.set_show_hidden_properties(true)?;
    station_options.set_prompt_to_find_files(false)?;
    station_options.set_auto_login_system_user(true)?;
    station_options.set_ui_message_delay(100)?;
    station_options.set_ui_message_min_delay(10)?;
    station_options.set_station_id("STATION_RUST_01")?;
    station_options.set_use_station_model(true)?;
    station_options.set_allow_other_models(false)?;
    station_options.set_use_localized_decimal_point(false)?;
    station_options.set_time_limit(0, 0, 60.0)?;
    station_options.set_time_limit_enabled(0, 0, true)?;

    engine.commit_globals_to_disk(false)?;
    println!("Station options updated and committed to disk.");

    Ok(())
}

examples/search_directory_manage.rs (line 91)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;
    let search_directories = engine.search_directories()?;

    println!("Total search directories: {}", search_directories.count()?);
    for (index, directory) in search_directories.iter()?.enumerate() {
        print_entry(index, &directory?)?;
    }

    // Insert at the front, so the new entry is searched first.
    println!("\nInserting a new explicit search directory...");
    let new_path = engine.bin_directory()?;
    search_directories.insert(&new_path, 0, true, "", false, false)?;
    println!("Total after insert: {}", search_directories.count()?);

    let inserted = search_directories.get(0)?;
    println!(
        "New [0] Path: '{}', Subdirs: {}",
        inserted.path()?,
        inserted.search_subdirectories()?
    );

    // A disabled entry stays in the list but is not searched.
    println!("Disabling the new directory...");
    inserted.set_disabled(true)?;
    println!("New [0] Disabled: {}", inserted.disabled()?);

    // Order matters: entries are searched in list order.
    println!("Moving the new directory to index 1...");
    search_directories.move_search_directory(0, 1)?;
    println!(
        "Directory at index 1 is now: '{}'",
        search_directories.get(1)?.path()?
    );

    println!("Removing the added directory to clean up...");
    search_directories.remove(1)?;
    println!("Total after cleanup: {}", search_directories.count()?);

    // The engine writes search directories out at shutdown anyway. Committing
    // now makes the change visible to other processes immediately, and passing
    // `false` keeps a save conflict from raising a dialog.
    engine.commit_globals_to_disk(false)?;
    println!("Committed search directories configuration to disk.");

    Ok(())
}

examples/variables_manage.rs (line 180)

fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

    // A container holds mixed types, so one station record can carry the name,
    // a count and a flag without three separate globals.
    set_string(&station_info, "StationName", "STATION_01")?;
    station_info.set_val_number("CalibrationIntervalDays", INSERT_IF_MISSING, 90.0)?;
    station_info.set_val_bool("FixtureInstalled", INSERT_IF_MISSING, true)?;

    // A 64-bit count. `SetValNumber` stores a double, which starts losing whole
    // numbers past 2^53, so anything that counts for the life of a station wants
    // the integer path instead.
    station_info.set_val_integer64("UnitsTestedTotal", INSERT_IF_MISSING, 9_007_199_254_740_993)?;

    // A nested container, because station data is rarely one level deep.
    if !station_info.exists("LastCalibration", 0)? {
        station_info.new_sub_property(
            "LastCalibration",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let calibration = station_info.get_property_object("LastCalibration", 0)?;
    set_string(&calibration, "Technician", "R. Alvarez")?;
    set_string(&calibration, "Date", "2026-06-14")?;

    println!("StationGlobals.StationInfo:");
    println!(
        "  StationName             = '{}'",
        station_info.get_val_string("StationName", 0)?
    );
    println!(
        "  CalibrationIntervalDays = {}",
        station_info.get_val_number("CalibrationIntervalDays", 0)?
    );
    println!(
        "  FixtureInstalled        = {}",
        station_info.get_val_bool("FixtureInstalled", 0)?
    );
    println!(
        "  UnitsTestedTotal        = {}",
        station_info.get_val_integer64("UnitsTestedTotal", 0)?
    );
    println!(
        "  LastCalibration.Technician = '{}' on {}",
        calibration.get_val_string("Technician", 0)?,
        calibration.get_val_string("Date", 0)?
    );

    // Walk the container rather than naming each field, which is what a host
    // does when it does not know the shape in advance.
    println!(
        "  walked, {} field(s):",
        station_info.get_num_sub_properties("")?
    );
    for index in 0..station_info.get_num_sub_properties("")? {
        println!(
            "    {}",
            station_info.get_nth_sub_property_name("", index, 0)?
        );
    }

    // Station globals live in memory until this is called. Without it the values
    // above are gone when the engine goes away, which is the difference between
    // a station global and a file global.
    // `false` means do not prompt if another process changed the file first.
    // An example must never raise a dialog, and neither must a headless host.
    engine.commit_globals_to_disk(false)?;
    println!("  committed to disk");

    Ok(())
}

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    show_station_globals(&engine)?;

    // The other three scopes need a sequence file.
    if let Some(sequence_file) = open_sequence_file(&engine)? {
        // File globals: shared by every sequence in this file. These are the
        // defaults stored in the file; a running execution gets its own copy.
        let file_globals = sequence_file.file_globals_default_values()?;
        set_string(&file_globals, "BatchID", "BATCH-2026-Q2-001")?;
        println!(
            "FileGlobals.BatchID                   = '{}'",
            file_globals.get_val_string("BatchID", 0)?
        );

        let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;

        // Locals: private to one call of this sequence.
        let locals = main_sequence.locals()?;
        set_string(&locals, "OperatorName", "Alice")?;
        println!(
            "MainSequence.Locals.OperatorName      = '{}'",
            locals.get_val_string("OperatorName", 0)?
        );

        // Parameters: supplied by whoever calls this sequence.
        let parameters = main_sequence.parameters()?;
        set_string(&parameters, "DUTSerial", "SN-000000")?;
        println!(
            "MainSequence.Parameters.DUTSerial     = '{}'",
            parameters.get_val_string("DUTSerial", 0)?
        );

        println!("\nTemporary variable lifecycle (Locals.TempScratch):");
        temporary_variable_lifecycle(&locals)?;

        // Nothing is saved: the file is left exactly as it was found.
        engine.release_sequence_file_ex(sequence_file, 0)?;
    } else {
        println!("\n(pass a .seq path to also demonstrate locals, parameters and file globals)");
        println!("\nTemporary variable lifecycle (StationGlobals.TempScratch):");
        temporary_variable_lifecycle(&engine.globals()?)?;
    }

    engine.commit_globals_to_disk(false)?;
    println!("\nStation globals committed to disk.");
    Ok(())
}

Trait Implementations

impl Debug for Engine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.