Struct SequenceFile 

pub struct SequenceFile { /* private fields */ }

A sequence file held open by the engine.

Obtained from crate::Engine::get_sequence_file_ex. Dropping this value releases the wrapper’s own reference, but the engine keeps the file in its cache until it is released explicitly, see crate::Engine::release_sequence_file_ex.

Implementations

impl SequenceFile

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

The file’s path on disk (Path).

Errors

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

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

How many sequences the file contains (NumSequences).

Errors

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

Examples found in repository

examples/execution_run_subsequence.rs (line 145)

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(())
}

pub fn insert_sequence(&self, sequence: &Sequence) -> Result<(), Error>

Adds a sequence to the file (SequenceFile.InsertSequence).

Errors

Error if the sequence is not a live object or the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 80)

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 100)

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 84)

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 insert_sequence_from_template( &self, template: &PropertyObject, ) -> Result<Sequence, Error>

Inserts a copy of a template sequence and returns the copy (PropertyObject.Clone + SequenceFile.InsertSequence).

The sequence-level counterpart of Sequence::insert_step_from_template, and composed for the same reason: a clone arrives on the PropertyObject interface, which shares no dispatch identifiers with Sequence. The copy is looked up by name after insertion so the caller only ever holds the right interface.

The copy keeps the template’s name, so inserting the same template twice without renaming the first copy puts two sequences of one name in the file. Every step in the copy also still carries the template’s step ID, /// see Sequence::create_new_unique_step_ids.

Errors

Error if the template is not a live object, has no name, or a COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 147)

fn apply_templates(
    sequence_file: &SequenceFile,
    step: &PropertyObject,
    sequence: &PropertyObject,
    variable: &PropertyObject,
) -> Result<(), Error> {
    let main_sequence = sequence_file.get_sequence_by_name(MAIN_SEQUENCE)?;

    // Inserting returns the copy on the Step interface, so it can be renamed
    // and re-identified straight away. Without a new step ID the copy would go
    // on claiming the prototype's identity.
    let inserted_step = main_sequence.insert_step_from_template(step, 0, StepGroup::Main)?;
    inserted_step.set_name("Step From Template")?;
    inserted_step.create_new_unique_step_id()?;
    println!("  step:     {}", inserted_step.name()?);

    let inserted_sequence = sequence_file.insert_sequence_from_template(sequence)?;
    inserted_sequence.create_new_unique_step_ids()?;
    println!(
        "  sequence: {} ({} step(s))",
        inserted_sequence.name()?,
        inserted_sequence.get_num_steps(StepGroup::Main)?
    );

    // A variable is the easy case: Locals is a property tree, so a clone drops
    // straight in under the template's own name.
    let locals = main_sequence.locals()?;
    locals.set_property_object(
        &variable.name()?,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        &variable.clone_property("", PropertyOptions::NONE.bits())?,
    )?;
    println!(
        "  variable: {} = {:?}",
        variable.name()?,
        locals.get_val_string(&variable.name()?, PropertyOptions::NONE.bits())?
    );

    // A file that does not believe it changed will not write anything.
    sequence_file
        .as_property_object_file()?
        .inc_change_count()?;
    Ok(())
}

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

The file seen as a property-object file (AsPropertyObjectFile).

This is the route to the file’s registered types.

Errors

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

Examples found in repository

examples/template_manage_complex.rs (line 171)

fn apply_templates(
    sequence_file: &SequenceFile,
    step: &PropertyObject,
    sequence: &PropertyObject,
    variable: &PropertyObject,
) -> Result<(), Error> {
    let main_sequence = sequence_file.get_sequence_by_name(MAIN_SEQUENCE)?;

    // Inserting returns the copy on the Step interface, so it can be renamed
    // and re-identified straight away. Without a new step ID the copy would go
    // on claiming the prototype's identity.
    let inserted_step = main_sequence.insert_step_from_template(step, 0, StepGroup::Main)?;
    inserted_step.set_name("Step From Template")?;
    inserted_step.create_new_unique_step_id()?;
    println!("  step:     {}", inserted_step.name()?);

    let inserted_sequence = sequence_file.insert_sequence_from_template(sequence)?;
    inserted_sequence.create_new_unique_step_ids()?;
    println!(
        "  sequence: {} ({} step(s))",
        inserted_sequence.name()?,
        inserted_sequence.get_num_steps(StepGroup::Main)?
    );

    // A variable is the easy case: Locals is a property tree, so a clone drops
    // straight in under the template's own name.
    let locals = main_sequence.locals()?;
    locals.set_property_object(
        &variable.name()?,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        &variable.clone_property("", PropertyOptions::NONE.bits())?,
    )?;
    println!(
        "  variable: {} = {:?}",
        variable.name()?,
        locals.get_val_string(&variable.name()?, PropertyOptions::NONE.bits())?
    );

    // A file that does not believe it changed will not write anything.
    sequence_file
        .as_property_object_file()?
        .inc_change_count()?;
    Ok(())
}

examples/data_type_manage.rs (line 110)

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(())
}

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

The file’s edit-time global variables (FileGlobalsDefaultValues).

These are the defaults stored in the file, which is what an editor shows and what this API can change. A running execution works on its own run-time copy instead, and edits made there do not travel back here, /// reach that copy through the execution, not through this method.

Errors

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

Examples found in repository

examples/variables_manage.rs (line 195)

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 get_sequence_by_name(&self, name: &str) -> Result<Sequence, Error>

Looks a sequence up by name (GetSequenceByName).

Errors

Error if no such sequence exists or the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 62)

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)
}

/// Waits for a run to finish, pumping and draining as it goes.
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)
}

/// Starts a run at the named sequence and prints what it recorded.
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(())
}

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 153)

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 137)

fn apply_templates(
    sequence_file: &SequenceFile,
    step: &PropertyObject,
    sequence: &PropertyObject,
    variable: &PropertyObject,
) -> Result<(), Error> {
    let main_sequence = sequence_file.get_sequence_by_name(MAIN_SEQUENCE)?;

    // Inserting returns the copy on the Step interface, so it can be renamed
    // and re-identified straight away. Without a new step ID the copy would go
    // on claiming the prototype's identity.
    let inserted_step = main_sequence.insert_step_from_template(step, 0, StepGroup::Main)?;
    inserted_step.set_name("Step From Template")?;
    inserted_step.create_new_unique_step_id()?;
    println!("  step:     {}", inserted_step.name()?);

    let inserted_sequence = sequence_file.insert_sequence_from_template(sequence)?;
    inserted_sequence.create_new_unique_step_ids()?;
    println!(
        "  sequence: {} ({} step(s))",
        inserted_sequence.name()?,
        inserted_sequence.get_num_steps(StepGroup::Main)?
    );

    // A variable is the easy case: Locals is a property tree, so a clone drops
    // straight in under the template's own name.
    let locals = main_sequence.locals()?;
    locals.set_property_object(
        &variable.name()?,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        &variable.clone_property("", PropertyOptions::NONE.bits())?,
    )?;
    println!(
        "  variable: {} = {:?}",
        variable.name()?,
        locals.get_val_string(&variable.name()?, PropertyOptions::NONE.bits())?
    );

    // A file that does not believe it changed will not write anything.
    sequence_file
        .as_property_object_file()?
        .inc_change_count()?;
    Ok(())
}

examples/step_insert_from_template.rs (line 78)

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 71)

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 202)

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(())
}

Additional examples can be found in:

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

pub fn get_sequence(&self, index: i32) -> Result<Sequence, Error>

Fetches a sequence by position (GetSequence).

Errors

Error if the index is out of range or the COM call fails.

pub fn save(&self, path: &str) -> Result<(), Error>

Saves the file, optionally to a new path (Save).

An empty path saves in place.

Errors

Error if the COM call fails.

Examples found in repository

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 110)

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 119)

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 171)

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(())
}

examples/step_insert.rs (line 143)

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(())
}

Trait Implementations

impl Debug for SequenceFile

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

Formats the value using the given formatter.