Struct Step 

pub struct Step { /* private fields */ }

One step of a sequence (Step).

Built by Engine::new_step and placed with Sequence::insert_step.

This type carries the properties every step has, whatever its type. Anything specific to a step type, a numeric limit test’s limits, for instance, /// lives in the property tree reached through as_property_object.

Implementations

impl Step

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

The step’s name (Step.Name).

Errors

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

Examples found in repository

examples/step_insert.rs (line 66)

fn index_of(sequence: &Sequence, name: &str, group: StepGroup) -> Result<Option<i32>, Error> {
    for index in 0..sequence.get_num_steps(group)? {
        if sequence.get_step(index, group)?.name()? == name {
            return Ok(Some(index));
        }
    }
    Ok(None)
}

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

examples/sequence_build.rs (line 52)

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

examples/template_manage_complex.rs (line 145)

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

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

pub fn set_name(&self, name: &str) -> Result<(), Error>

Sets the step’s name (Step.Name).

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 104)

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

/// Stamps one copy of each template into a file that is already on disk.
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/result_list_parse.rs (line 43)

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

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

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

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

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/execution_run_subsequence.rs (line 49)

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 precondition(&self) -> Result<String, Error>

The expression deciding whether the step runs (Step.Precondition).

An empty precondition means the step always runs.

Errors

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

Examples found in repository

examples/sequence_build.rs (line 60)

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

pub fn set_precondition(&self, expression: &str) -> Result<(), Error>

Sets the precondition expression (Step.Precondition).

The text is not checked here; a precondition that does not parse fails when the sequence runs, not when it is set.

Errors

Error if the COM call fails.

Examples found in repository

examples/sequence_build.rs (line 37)

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

pub fn run_mode(&self) -> Result<Option<RunMode>, Error>

What the engine does with the step when it reaches it (Step.RunMode).

None means the engine reported a mode this build does not name, which is worth telling apart from a failure to read it at all.

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 74)

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/step_insert.rs (line 133)

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 set_run_mode(&self, mode: RunMode) -> Result<(), Error>

Sets the run mode (Step.RunMode).

Errors

Error if the COM call fails.

Examples found in repository

examples/step_insert_from_template.rs (line 56)

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/step_insert.rs (line 46)

fn vi_call_step(
    engine: &Engine,
    name: &str,
    vi_path: &str,
    project_path: &str,
    run_mode: RunMode,
) -> Result<Step, Error> {
    let step = engine.new_step(AdapterKeyName::LabView.as_str(), "Action")?;
    step.set_name(name)?;
    step.set_run_mode(run_mode)?;
    // Recorded explicitly rather than left to the default, so the step shows up
    // in the result list a report is built from.
    step.set_result_recording_option(ResultRecordingOption::Enabled)?;

    let properties = step.as_property_object()?;
    properties.set_val_string(VI_PATH, insert_if_missing(), vi_path)?;
    if !project_path.is_empty() {
        properties.set_val_string(PROJECT_PATH, insert_if_missing(), project_path)?;
    }
    Ok(step)
}

pub fn adapter_key_name(&self) -> Result<Option<AdapterKeyName>, Error>

The adapter the step calls its code module through (Step.AdapterKeyName).

None means the engine reported a key this build does not name, or the step calls no code module at all.

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 73)

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/step_insert.rs (line 132)

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 post_expression(&self) -> Result<String, Error>

The expression evaluated after the step runs (Step.PostExpression).

An empty expression means nothing runs afterwards.

Errors

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

pub fn set_post_expression(&self, expression: &str) -> Result<(), Error>

Sets the post expression (Step.PostExpression).

Like a precondition, the text is not checked here: an expression that does not parse fails when the sequence runs, not when it is set.

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 105)

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

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

Gives the step a fresh unique identity (Step.CreateNewUniqueStepId).

A copy of a step carries the original’s step ID, so a sequence built by cloning a prototype ends up with several steps claiming the same identity. Anything that refers to a step by ID, a result, a report entry, a GoTo, then cannot tell them apart. Call this on each copy.

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 144)

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

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

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

Whether this step contributes an entry to the result list (Step.ResultRecordingOption).

Distinct from record_result, the plain on/off switch: this one can also say “record even when the sequence says not to”. A step set to Disabled leaves no entry in ResultList, which is the usual reason a parsed report is shorter than the sequence that produced it.

Errors

Error if the COM call fails or the engine reports an unnamed value.

Examples found in repository

examples/step_insert.rs (line 134)

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 set_result_recording_option( &self, option: ResultRecordingOption, ) -> Result<(), Error>

Sets whether this step records a result (Step.ResultRecordingOption).

Errors

Error if the COM call fails.

Examples found in repository

examples/result_list_parse.rs (line 79)

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/step_insert.rs (line 49)

fn vi_call_step(
    engine: &Engine,
    name: &str,
    vi_path: &str,
    project_path: &str,
    run_mode: RunMode,
) -> Result<Step, Error> {
    let step = engine.new_step(AdapterKeyName::LabView.as_str(), "Action")?;
    step.set_name(name)?;
    step.set_run_mode(run_mode)?;
    // Recorded explicitly rather than left to the default, so the step shows up
    // in the result list a report is built from.
    step.set_result_recording_option(ResultRecordingOption::Enabled)?;

    let properties = step.as_property_object()?;
    properties.set_val_string(VI_PATH, insert_if_missing(), vi_path)?;
    if !project_path.is_empty() {
        properties.set_val_string(PROJECT_PATH, insert_if_missing(), project_path)?;
    }
    Ok(step)
}

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

Whether the step’s result is recorded (Step.RecordResult).

Errors

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

pub fn set_record_result(&self, record: bool) -> Result<(), Error>

Sets whether the step’s result is recorded (Step.RecordResult).

Errors

Error if the COM call fails.

Examples found in repository

examples/sequence_build.rs (line 38)

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

examples/execution_run_subsequence.rs (line 50)

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

examples/execution_run_test_headless.rs (line 72)

fn add_numeric_limit_test(
    engine: &Engine,
    sequence: &Sequence,
    name: &str,
    data_source: &str,
    low: f64,
    high: f64,
) -> Result<(), Error> {
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "NumericLimitTest")?;
    step.set_name(name)?;
    step.set_record_result(true)?;

    let properties = step.as_property_object()?;
    properties.set_val_string("DataSource", insert_if_missing(), data_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,
    )
}

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

The step as a property tree (Step.AsPropertyObject).

Type-specific settings live here, addressed by lookup path, /// Limits.High on a numeric limit test, for instance.

Errors

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

Examples found in repository

examples/template_manage_complex.rs (line 106)

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

examples/result_list_parse.rs (line 44)

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

examples/ui_messages_handle.rs (line 30)

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

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

examples/step_insert_from_template.rs (line 57)

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

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/execution_run_test_headless.rs (line 74)

fn add_numeric_limit_test(
    engine: &Engine,
    sequence: &Sequence,
    name: &str,
    data_source: &str,
    low: f64,
    high: f64,
) -> Result<(), Error> {
    let step = engine.new_step(AdapterKeyName::NoneAdapter.as_str(), "NumericLimitTest")?;
    step.set_name(name)?;
    step.set_record_result(true)?;

    let properties = step.as_property_object()?;
    properties.set_val_string("DataSource", insert_if_missing(), data_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,
    )
}

Additional examples can be found in:

• examples/step_insert.rs

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

The step’s type definition (Step.StepType).

Errors

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

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

Whether this step carries a breakpoint (Step.BreakOnStep).

Reads the step itself. To ask about one run instead, use break_on_step_for.

True here does not mean a run will stop. Breakpoints are only honored while they are switched on, which Engine::breakpoints_enabled controls for the session.

Errors

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

pub fn break_on_step_for( &self, scope: BreakpointScope<'_>, ) -> Result<bool, Error>

Whether this step carries a breakpoint in the given scope (Step.GetBreakOnStepEx).

Errors

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

pub fn set_break_on_step( &self, enabled: bool, scope: BreakpointScope<'_>, ) -> Result<(), Error>

Sets or clears the breakpoint on this step (Step.SetBreakOnStepEx).

The scope decides how long it lasts. BreakpointScope::Step writes it into the step, so it survives the run and is saved with the sequence file. BreakpointScope::Execution scopes it to one run and leaves the file alone, which is what a host debugging for a remote panel should use.

A stop announces itself as UIMessageCode::BreakOnBreakpoint, which arrived about 300 ms after the run started in a live measurement. Continue with Execution::resume, not Thread::resume, which does not release a breakpoint stop.

Errors

Error if the COM call fails.

pub fn set_break_settings( &self, is_set: bool, enabled: bool, pass_count: i32, condition: &str, scope: BreakpointScope<'_>, ) -> Result<(), Error>

Sets a breakpoint together with its pass count and condition (Step.SetBreakSettings).

is_set places or removes the breakpoint and enabled decides whether it is armed, so a breakpoint can stay in place while switched off. pass_count stops on the nth arrival rather than the first. condition is an expression the engine evaluates when it arrives; an empty string means stop unconditionally.

Reading these back needs Step.GetBreakSettings, which returns everything through [out] parameters and is not wrapped yet.

Errors

Error if the COM call fails.

Trait Implementations

impl Debug for Step

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

Formats the value using the given formatter.