Struct PropertyObject 

pub struct PropertyObject { /* private fields */ }

Safe wrapper for TestStand™ PropertyObject (IPropertyObject).

Implementations

impl PropertyObject

pub fn exists(&self, lookup_string: &str, options: i32) -> Result<bool, Error>

Checks if a property exists by lookup path (PropertyObject.Exists).

Errors

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

Examples found in repository

examples/variables_manage.rs (line 28)

fn set_string(
    container: &PropertyObject,
    name: &str,
    value: &str,
) -> Result<(), rs_teststand::Error> {
    if !container.exists(name, 0)? {
        container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    }
    container.set_val_string(name, 0, value)
}

/// Creates a variable, retypes it, clones it, then removes both.
///
/// The type is fixed at creation, so each "retype" is a delete followed by a
/// fresh create, the same thing the sequence editor does behind the scenes.
fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

/// Opens a sequence file if one was named on the command line.
///
/// Locals, parameters and file globals all need a real file; without one the
/// example still demonstrates station globals.
fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

/// Everything that lives on the station rather than in a file.
///
/// Separated because it is the one scope that outlives the process, so it is
/// the one worth reading on its own.
fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

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

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

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

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

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

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

    Ok(())
}

examples/sequence_build.rs (line 53)

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

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

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

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

examples/execution_run_test_headless.rs (line 115)

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

pub fn get_val_string( &self, lookup_string: &str, options: i32, ) -> Result<String, Error>

Reads a string property by lookup path (PropertyObject.GetValString).

Errors

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

Examples found in repository

examples/execution_run_subsequence.rs (line 130)

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

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

examples/variables_manage.rs (line 51)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

/// Opens a sequence file if one was named on the command line.
///
/// Locals, parameters and file globals all need a real file; without one the
/// example still demonstrates station globals.
fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

/// Everything that lives on the station rather than in a file.
///
/// Separated because it is the one scope that outlives the process, so it is
/// the one worth reading on its own.
fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

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

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

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

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

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

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

    Ok(())
}

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

    show_station_globals(&engine)?;

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

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

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

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

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

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

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

examples/template_manage_complex.rs (line 166)

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

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

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_val_string( &self, lookup_string: &str, options: i32, value: &str, ) -> Result<(), Error>

Writes a string property by lookup path (PropertyObject.SetValString).

Errors

Error if the COM call fails.

Examples found in repository

examples/variables_manage.rs (line 31)

fn set_string(
    container: &PropertyObject,
    name: &str,
    value: &str,
) -> Result<(), rs_teststand::Error> {
    if !container.exists(name, 0)? {
        container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    }
    container.set_val_string(name, 0, value)
}

/// Creates a variable, retypes it, clones it, then removes both.
///
/// The type is fixed at creation, so each "retype" is a delete followed by a
/// fresh create, the same thing the sequence editor does behind the scenes.
fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

examples/template_manage_complex.rs (line 126)

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

examples/result_list_parse.rs (line 45)

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

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/data_type_manage.rs (line 32)

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

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

examples/step_insert_from_template.rs (lines 57-61)

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

Additional examples can be found in:

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

pub fn get_val_number( &self, lookup_string: &str, options: i32, ) -> Result<f64, Error>

Reads a numeric property by lookup path (PropertyObject.GetValNumber).

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 98)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

examples/sequence_build.rs (line 56)

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

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

examples/variables_manage.rs (line 59)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

/// Opens a sequence file if one was named on the command line.
///
/// Locals, parameters and file globals all need a real file; without one the
/// example still demonstrates station globals.
fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

/// Everything that lives on the station rather than in a file.
///
/// Separated because it is the one scope that outlives the process, so it is
/// the one worth reading on its own.
fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

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

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

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

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

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

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

    Ok(())
}

pub fn set_val_number( &self, lookup_string: &str, options: i32, value: f64, ) -> Result<(), Error>

Writes a numeric property by lookup path (PropertyObject.SetValNumber).

Errors

Error if the COM call fails.

Examples found in repository

examples/data_type_manage.rs (line 30)

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

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

examples/sequence_build.rs (line 41)

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/result_list_parse.rs (line 66)

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

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

examples/variables_manage.rs (line 56)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

/// Opens a sequence file if one was named on the command line.
///
/// Locals, parameters and file globals all need a real file; without one the
/// example still demonstrates station globals.
fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

/// Everything that lives on the station rather than in a file.
///
/// Separated because it is the one scope that outlives the process, so it is
/// the one worth reading on its own.
fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

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

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

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

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

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

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

    Ok(())
}

pub fn get_val_bool( &self, lookup_string: &str, options: i32, ) -> Result<bool, Error>

Reads a boolean property by lookup path (PropertyObject.GetValBoolean).

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 90)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

examples/variables_manage.rs (line 150)

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

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

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

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

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

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

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

    Ok(())
}

pub fn set_val_bool( &self, lookup_string: &str, options: i32, value: bool, ) -> Result<(), Error>

Writes a boolean property by lookup path (PropertyObject.SetValBoolean).

Errors

Error if the COM call fails.

Examples found in repository

examples/data_type_manage.rs (line 31)

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

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

examples/variables_manage.rs (line 118)

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

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

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

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

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

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

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

    Ok(())
}

pub fn get_num_sub_properties(&self, lookup_string: &str) -> Result<i32, Error>

How many sub-properties sit directly under lookup_string (GetNumSubProperties).

Pass an empty string for this object itself.

Errors

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

Examples found in repository

examples/variables_manage.rs (line 166)

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

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

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

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

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

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

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

    Ok(())
}

examples/users_manage.rs (line 71)

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

pub fn get_nth_sub_property_name( &self, lookup_string: &str, index: i32, options: i32, ) -> Result<String, Error>

The name of the index-th sub-property (GetNthSubPropertyName).

Errors

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

Examples found in repository

examples/variables_manage.rs (line 171)

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

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

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

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

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

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

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

    Ok(())
}

examples/users_manage.rs (line 74)

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

pub fn get_nth_sub_property( &self, lookup_string: &str, index: i32, options: i32, ) -> Result<Self, Error>

The index-th sub-property itself (GetNthSubProperty).

Errors

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

pub fn get_val_integer64( &self, lookup_string: &str, options: i32, ) -> Result<i64, Error>

Reads a signed 64-bit integer property (GetValInteger64).

The engine stores a number as one of three things, a double, a signed 64-bit integer, or an unsigned one, and the accessor must match. Use this when property_type reports PropertyRepresentation::Int64; get_val_number fails on such a property rather than converting.

Errors

Error if the COM call fails or the property is not stored as a signed 64-bit integer.

Examples found in repository

examples/variables_manage.rs (line 154)

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

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

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

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

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

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

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

    Ok(())
}

pub fn set_val_integer64( &self, lookup_string: &str, options: i32, value: i64, ) -> Result<(), Error>

Writes a signed 64-bit integer property (SetValInteger64).

Errors

Error if the COM call fails.

Examples found in repository

examples/variables_manage.rs (line 123)

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

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

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

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

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

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

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

    Ok(())
}

pub fn get_val_unsigned_integer64( &self, lookup_string: &str, options: i32, ) -> Result<u64, Error>

Reads an unsigned 64-bit integer property (GetValUnsignedInteger64).

Use this when the representation is UInt64. The value crosses the COM boundary as VT_UI8 and is returned with its bits intact, so the full unsigned range survives.

Errors

Error if the COM call fails or the property is not stored as an unsigned 64-bit integer.

pub fn set_val_unsigned_integer64( &self, lookup_string: &str, options: i32, value: u64, ) -> Result<(), Error>

Writes an unsigned 64-bit integer property (SetValUnsignedInteger64).

Errors

Error if the COM call fails.

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

The per-property numeric format string (PropertyObject.NumericFormat).

A printf-style format that decides how get_formatted_value renders a number, so the same stored value can display as decimal, hex, octal or binary. It is presentation only, the underlying number is unchanged.

Two departures from C: %b formats in binary, and a $ placed straight after the % strips trailing zeros after the decimal point. An empty string restores the default format.

Errors

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

pub fn set_numeric_format(&self, format: &str) -> Result<(), Error>

Sets the numeric format string (PropertyObject.NumericFormat).

Errors

Error if the COM call fails.

pub fn get_formatted_value( &self, lookup_string: &str, options: i32, format: &str, use_value_format_if_defined: bool, separator: &str, ) -> Result<String, Error>

Renders a property’s value as display text (GetFormattedValue).

format overrides the formatting for this call; pass an empty string to use the default. Set use_value_format_if_defined to honour the property’s own numeric_format instead. separator joins array elements.

Containers render as ... and an empty reference as Nothing, so the result is always displayable text rather than an error.

Errors

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

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

The object’s name (PropertyObject.Name).

A type definition must be named before it can be registered.

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 40)

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

examples/template_manage_complex.rs (line 51)

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

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

/// An empty array container to keep prototypes in.
fn new_template_group(engine: &Engine) -> Result<PropertyObject, Error> {
    engine.new_property_object(
        PropValType::Container,
        true,
        "",
        PropertyOptions::NONE.bits(),
    )
}

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

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

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

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

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

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

    sequence.as_property_object()
}

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

/// 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/data_type_manage.rs (line 93)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

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

Sets the object’s name (PropertyObject.Name).

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 125)

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

examples/data_type_manage.rs (line 34)

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

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

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

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

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

A type’s version, as major.minor.revision.build (PropertyObject.TypeVersion).

Which field is bumped carries meaning: raising the lowest field signals a change the engine can apply to existing instances silently, while raising a higher one marks the change as deliberate.

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 94)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

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 set_type_version(&self, version: &str) -> Result<(), Error>

Sets a type’s version (PropertyObject.TypeVersion).

Errors

Error if the COM call fails.

Examples found in repository

examples/data_type_manage.rs (line 159)

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 attributes(&self) -> Result<Self, Error>

The object’s attributes (PropertyObject.Attributes).

A property tree of its own, used for metadata that is not part of the value, an enumeration’s strictness flag, for instance.

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 57)

fn enumerator_array(
    engine: &Engine,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let array = engine.new_property_object(PropValType::Container, true, "", NO_OPTIONS)?;
    array.set_num_elements(i32::try_from(named_values.len()).unwrap_or(0), NO_OPTIONS)?;
    for (index, (name, value)) in named_values.iter().enumerate() {
        let element =
            array.get_property_object_by_offset(i32::try_from(index).unwrap_or(0), NO_OPTIONS)?;
        element.set_val_string("EnumeratorName", INSERT_IF_MISSING, name)?;
        element.set_val_number("EnumeratorValue", INSERT_IF_MISSING, *value)?;
    }
    array
        .attributes()?
        .set_val_bool(IS_STRICT_ATTRIBUTE, INSERT_IF_MISSING, strict)?;
    Ok(array)
}

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

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

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

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

An enumeration’s enumerators (PropertyObject.Enumerators).

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 87)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

pub fn update_enumerators(&self, enumerators: &Self) -> Result<bool, Error>

Replaces an enumeration’s enumerators (UpdateEnumerators).

Expects an array of containers, each holding EnumeratorName and EnumeratorValue. Strictness rides on the array’s attributes rather than on an element.

This only has an effect on a registered type definition; calling it on the loose object that was inserted changes nothing. Every loaded instance of the type is updated.

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 82)

fn register_enum(
    engine: &Engine,
    types: &TypeUsageList,
    name: &str,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let enum_type = engine.new_property_object(PropValType::Enum, false, "", NO_OPTIONS)?;
    enum_type.set_name(name)?;
    types.insert_type(
        &enum_type,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;

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

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

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 get_value_display_name( &self, lookup_string: &str, options: i32, ) -> Result<String, Error>

The display name of a value (GetValueDisplayName).

For an enumeration this is the enumerator’s name rather than its number.

Errors

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

Examples found in repository

examples/data_type_manage.rs (line 101)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

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

Evaluates an expression in this object’s context (Evaluate).

Superseded by evaluate_ex, which adds an options argument. This form is kept because it is the member available on engines from TestStand 2016, which the crate supports, a caller targeting the whole range can use it without a version check.

Errors

Error if the expression is invalid or the COM call fails.

pub fn evaluate_ex(&self, expression: &str, options: i32) -> Result<Self, Error>

Evaluates an expression in this object’s context (EvaluateEx).

The object is the scope: the expression can name this property’s subproperties directly. The result comes back as a PropertyObject holding whatever type the expression produced, so read it with the accessor that matches, or with to_value.

Evaluate is the obsolete form of this member; use this one.

Errors

Error if the expression is invalid or the COM call fails.

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

This property’s type object (PropertyObject.Type).

Errors

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

pub fn get_type_display_string( &self, lookup_string: &str, options: i32, ) -> Result<String, Error>

A human-readable name for a property’s type (GetTypeDisplayString).

Obsolete in the engine; prefer property_type then display_string.

This is the in-only route to identifying a type. GetType reports the same thing in more detail but returns three of its five arguments by reference, which the dispatch seam does not yet support.

Errors

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

pub fn get_type_flags( &self, lookup_string: &str, options: i32, ) -> Result<PropertyValueTypeFlags, Error>

A property’s type as a flag set (GetTypeFlags).

Errors

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

pub fn get_property_object_by_offset( &self, offset: i32, options: i32, ) -> Result<Self, Error>

An array element by position (GetPropertyObjectByOffset).

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 39)

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

examples/template_manage_complex.rs (line 48)

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

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

/// An empty array container to keep prototypes in.
fn new_template_group(engine: &Engine) -> Result<PropertyObject, Error> {
    engine.new_property_object(
        PropValType::Container,
        true,
        "",
        PropertyOptions::NONE.bits(),
    )
}

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

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

examples/data_type_manage.rs (line 52)

fn enumerator_array(
    engine: &Engine,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let array = engine.new_property_object(PropValType::Container, true, "", NO_OPTIONS)?;
    array.set_num_elements(i32::try_from(named_values.len()).unwrap_or(0), NO_OPTIONS)?;
    for (index, (name, value)) in named_values.iter().enumerate() {
        let element =
            array.get_property_object_by_offset(i32::try_from(index).unwrap_or(0), NO_OPTIONS)?;
        element.set_val_string("EnumeratorName", INSERT_IF_MISSING, name)?;
        element.set_val_number("EnumeratorValue", INSERT_IF_MISSING, *value)?;
    }
    array
        .attributes()?
        .set_val_bool(IS_STRICT_ATTRIBUTE, INSERT_IF_MISSING, strict)?;
    Ok(array)
}

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

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

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

examples/execution_run_subsequence.rs (line 126)

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

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

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

examples/execution_run_test_headless.rs (line 130)

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

pub fn set_num_elements(&self, count: i32, options: i32) -> Result<(), Error>

Resizes an array property (SetNumElements).

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 74)

fn append_template(group: &PropertyObject, template: &PropertyObject) -> Result<(), Error> {
    let index = group.get_num_elements()?;
    group.set_num_elements(index + 1, PropertyOptions::NONE.bits())?;
    group.set_property_object(
        &format!("[{index}]"),
        PropertyOptions::NONE.bits(),
        &template.clone_property("", PropertyOptions::NONE.bits())?,
    )
}

examples/data_type_manage.rs (line 49)

fn enumerator_array(
    engine: &Engine,
    named_values: &[(&str, f64)],
    strict: bool,
) -> Result<PropertyObject, rs_teststand::Error> {
    let array = engine.new_property_object(PropValType::Container, true, "", NO_OPTIONS)?;
    array.set_num_elements(i32::try_from(named_values.len()).unwrap_or(0), NO_OPTIONS)?;
    for (index, (name, value)) in named_values.iter().enumerate() {
        let element =
            array.get_property_object_by_offset(i32::try_from(index).unwrap_or(0), NO_OPTIONS)?;
        element.set_val_string("EnumeratorName", INSERT_IF_MISSING, name)?;
        element.set_val_number("EnumeratorValue", INSERT_IF_MISSING, *value)?;
    }
    array
        .attributes()?
        .set_val_bool(IS_STRICT_ATTRIBUTE, INSERT_IF_MISSING, strict)?;
    Ok(array)
}

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

The number of elements in an array property (GetNumElements).

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 38)

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

examples/template_manage_complex.rs (line 47)

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

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

/// An empty array container to keep prototypes in.
fn new_template_group(engine: &Engine) -> Result<PropertyObject, Error> {
    engine.new_property_object(
        PropValType::Container,
        true,
        "",
        PropertyOptions::NONE.bits(),
    )
}

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

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

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

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

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

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

    sequence.as_property_object()
}

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

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

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/data_type_manage.rs (line 96)

fn print_enumerators(definition: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let enumerators = definition.enumerators()?;
    let strict = enumerators
        .attributes()?
        .get_val_bool(IS_STRICT_ATTRIBUTE, NO_OPTIONS)?;
    println!(
        "  {} v{} (strict={strict}):",
        definition.name()?,
        definition.type_version()?
    );
    for index in 0..enumerators.get_num_elements()? {
        let element = enumerators.get_property_object_by_offset(index, NO_OPTIONS)?;
        let value = element.get_val_number("", COERCE_TO_NUMBER)?;
        println!(
            "    {} -> {value}",
            element.get_value_display_name("", NO_OPTIONS)?
        );
    }
    Ok(())
}

examples/execution_run_subsequence.rs (line 125)

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

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

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

examples/execution_run_test_headless.rs (line 120)

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

examples/users_manage.rs (line 105)

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

pub fn get_property_object( &self, lookup_string: &str, options: i32, ) -> Result<Self, Error>

Retrieves a nested PropertyObject by lookup path (PropertyObject.GetPropertyObject).

Errors

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

Examples found in repository

examples/step_insert_from_template.rs (line 37)

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

examples/template_manage_complex.rs (line 44)

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

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

examples/execution_run_subsequence.rs (line 124)

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

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

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

examples/execution_run_test_headless.rs (line 119)

fn report(results: &rs_teststand::PropertyObject) -> Result<(), Error> {
    if !results.exists("ResultList", none())? {
        println!("No results recorded.");
        return Ok(());
    }
    let result_list = results.get_property_object("ResultList", none())?;
    let count = result_list.get_num_elements()?;
    println!(
        "\n{count} of {} defined test(s) recorded a result:",
        TESTS.len()
    );
    if count < i32::try_from(TESTS.len()).unwrap_or(i32::MAX) {
        println!("  (a failure ended the run before the rest could execute)");
    }

    for index in 0..count {
        let entry = result_list.get_property_object_by_offset(index, none())?;
        let name = entry
            .get_val_string("TS.StepName", none())
            .unwrap_or_else(|_| "<unnamed>".to_owned());
        let status = entry
            .get_val_string("Status", none())
            .unwrap_or_else(|_| "<no status>".to_owned());
        // Only test steps record a measurement; an Action has no Numeric.
        match entry.get_val_number("Numeric", none()) {
            Ok(measured) => println!("  {name}: {status} (measured {measured})"),
            Err(_) => println!("  {name}: {status}"),
        }
    }
    Ok(())
}

examples/variables_manage.rs (line 112)

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

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

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

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

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

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

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

    Ok(())
}

examples/users_manage.rs (line 76)

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

pub fn set_property_object( &self, lookup_string: &str, options: i32, property_object_value: &Self, ) -> Result<(), Error>

Attaches a nested PropertyObject by lookup path (PropertyObject.SetPropertyObject).

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (lines 75-79)

fn append_template(group: &PropertyObject, template: &PropertyObject) -> Result<(), Error> {
    let index = group.get_num_elements()?;
    group.set_num_elements(index + 1, PropertyOptions::NONE.bits())?;
    group.set_property_object(
        &format!("[{index}]"),
        PropertyOptions::NONE.bits(),
        &template.clone_property("", PropertyOptions::NONE.bits())?,
    )
}

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

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

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

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

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

    sequence.as_property_object()
}

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

/// 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/variables_manage.rs (line 64)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

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

Creates a new sub-property (PropertyObject.NewSubProperty).

Errors

Error if the COM call fails.

Examples found in repository

examples/variables_manage.rs (line 29)

fn set_string(
    container: &PropertyObject,
    name: &str,
    value: &str,
) -> Result<(), rs_teststand::Error> {
    if !container.exists(name, 0)? {
        container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    }
    container.set_val_string(name, 0, value)
}

/// Creates a variable, retypes it, clones it, then removes both.
///
/// The type is fixed at creation, so each "retype" is a delete followed by a
/// fresh create, the same thing the sequence editor does behind the scenes.
fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

/// Opens a sequence file if one was named on the command line.
///
/// Locals, parameters and file globals all need a real file; without one the
/// example still demonstrates station globals.
fn open_sequence_file(engine: &Engine) -> Result<Option<SequenceFile>, rs_teststand::Error> {
    let Some(path) = std::env::args().nth(1) else {
        return Ok(None);
    };
    let file = engine.get_sequence_file_ex(
        &path,
        GetSeqFileOptions::DO_NOT_RUN_LOAD_CALLBACK,
        ConflictHandler::Error,
    )?;
    Ok(Some(file))
}

/// Everything that lives on the station rather than in a file.
///
/// Separated because it is the one scope that outlives the process, so it is
/// the one worth reading on its own.
fn show_station_globals(engine: &Engine) -> Result<(), rs_teststand::Error> {
    // Station globals: shared by every sequence file, and written to disk.
    let station_globals = engine.globals()?;
    if !station_globals.exists("StationInfo", 0)? {
        station_globals.new_sub_property(
            "StationInfo",
            PropValType::Container,
            false,
            "",
            INSERT_IF_MISSING,
        )?;
    }
    let station_info = station_globals.get_property_object("StationInfo", 0)?;

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

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

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

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

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

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

    Ok(())
}

examples/execution_run_subsequence.rs (lines 70-76)

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/data_type_manage.rs (lines 128-134)

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 delete_sub_property( &self, lookup_string: &str, options: i32, ) -> Result<(), Error>

Deletes a sub-property by lookup path (PropertyObject.DeleteSubProperty).

Errors

Error if the COM call fails.

Examples found in repository

examples/variables_manage.rs (line 43)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

pub fn clone_property( &self, lookup_string: &str, options: i32, ) -> Result<Self, Error>

Clones a sub-property by lookup path (PropertyObject.Clone).

Errors

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

Examples found in repository

examples/template_manage_complex.rs (line 78)

fn append_template(group: &PropertyObject, template: &PropertyObject) -> Result<(), Error> {
    let index = group.get_num_elements()?;
    group.set_num_elements(index + 1, PropertyOptions::NONE.bits())?;
    group.set_property_object(
        &format!("[{index}]"),
        PropertyOptions::NONE.bits(),
        &template.clone_property("", PropertyOptions::NONE.bits())?,
    )
}

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

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

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

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

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

    sequence.as_property_object()
}

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

/// 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/variables_manage.rs (line 63)

fn temporary_variable_lifecycle(container: &PropertyObject) -> Result<(), rs_teststand::Error> {
    let name = "TempScratch";
    let clone_name = "TempScratchCopy";
    for stale in [name, clone_name] {
        if container.exists(stale, 0)? {
            container.delete_sub_property(stale, 0)?;
        }
    }

    container.new_sub_property(name, PropValType::String, false, "", INSERT_IF_MISSING)?;
    container.set_val_string(name, 0, "scratch")?;
    println!(
        "  created {name} (String) = '{}'",
        container.get_val_string(name, 0)?
    );

    container.delete_sub_property(name, 0)?;
    container.new_sub_property(name, PropValType::Number, false, "", INSERT_IF_MISSING)?;
    container.set_val_number(name, 0, 42.0)?;
    println!(
        "  retyped {name} -> Number = {}",
        container.get_val_number(name, 0)?
    );

    // clone copies value and type; set_property_object attaches it under a new name.
    let copy = container.clone_property(name, 0)?;
    container.set_property_object(clone_name, INSERT_IF_MISSING, &copy)?;
    println!(
        "  cloned  {name} -> {clone_name} = {}",
        container.get_val_number(clone_name, 0)?
    );

    container.delete_sub_property(clone_name, 0)?;
    container.delete_sub_property(name, 0)?;
    println!(
        "  removed both: {name} exists={}, {clone_name} exists={}",
        container.exists(name, 0)?,
        container.exists(clone_name, 0)?
    );
    Ok(())
}

Trait Implementations

impl Debug for PropertyObject

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

Formats the value using the given formatter.