Struct Execution 

pub struct Execution { /* private fields */ }

A running sequence (Execution).

Created by Engine::new_execution, which starts it immediately, there is no separate “run” step.

Implementations

impl Execution

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

The execution’s identifier (Execution.Id).

Messages posted by a sequence carry the execution that posted them, so this is how a host attributes a message to the run that produced it.

Errors

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

Examples found in repository

examples/ui_messages_handle.rs (line 74)

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

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

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

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

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

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

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

pub fn wait_for_end_ex( &self, milliseconds: i32, process_windows_messages: bool, ) -> Result<bool, Error>

Waits for the execution to finish (Execution.WaitForEndEx).

Returns true when it ended, false when the timeout came first. Pass -1 for no timeout.

Not for a host that polls for messages. This does not pump the message queue while it waits, so a synchronous message posted by the sequence would never be acknowledged and both sides would stop. A polling host should watch for UIMessageCode::EndExecution on the queue instead, which is how a front end knows an execution finished.

This is for synchronising between executions, waiting from a step for another execution to finish.

Errors

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

pub fn wait_for_end( &self, milliseconds: i32, process_windows_messages: bool, ) -> Result<bool, Error>

Waits for the execution to finish (Execution.WaitForEnd).

Superseded by wait_for_end_ex; kept because it is the member available on engines from TestStand 2016. The same warning applies: it does not pump the message queue.

Errors

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

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

Asks the execution to stop (Execution.Terminate).

Termination is requested, not immediate: cleanup still runs.

Errors

Error if the COM call fails.

Examples found in repository

examples/execution_run_subsequence.rs (line 114)

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

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

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

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

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

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

examples/result_list_parse.rs (line 134)

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

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

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

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

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

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

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

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

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

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

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

The name a front end shows for this execution (Execution.DisplayName).

Errors

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

Examples found in repository

examples/execution_run_test_headless.rs (line 159)

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

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

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

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

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

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

The overall result so far (Execution.ResultStatus).

A string the engine owns, "Passed", "Failed", "Terminated", "Error", "Running" and others. Deliberately not narrowed to an enum: a sequence may set a status of its own, and folding an unknown one into a fixed set would lose it.

Errors

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

Examples found in repository

examples/execution_run_subsequence.rs (line 117)

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

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

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

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

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

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

examples/result_list_parse.rs (line 137)

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

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

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

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

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

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

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

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

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

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

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

The path of the sequence file being run (Execution.SequenceFilePath).

Errors

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

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

How many threads the execution currently has (Execution.NumThreads).

Errors

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

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

Seconds spent executing (Execution.SecondsExecuting).

Errors

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

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

Seconds spent suspended (Execution.SecondsSuspended).

Errors

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

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

Suspends the execution (Execution.Break).

Asynchronous, like every control member here: it asks, and the engine acts when the running step allows. Do not assume the execution is suspended by the time this returns.

Errors

Error if the COM call fails.

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

Resumes a suspended execution (Execution.Resume).

Errors

Error if the COM call fails.

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

Stops the execution without running cleanup (Execution.Abort).

The blunt counterpart to terminate: terminating still runs Cleanup groups, so hardware is left in a safe state, and aborting does not. Prefer terminating unless the point is to stop now.

Errors

Error if the COM call fails.

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

Calls off a termination already under way (Execution.CancelTermination).

Deadlock

Call this only from inside a running step. The reference is explicit that calling it from an application’s main thread, or from a step type’s edit substep, deadlocks, and it does: measured from a test thread, the call never returns and the process has to be killed, which then leaves sequence files unreleased.

A host driving an engine from its own thread is in exactly the position the reference warns about, so this is not a member a host calls to stop a termination it started. It exists for code running as part of the execution itself.

Errors

Error if the COM call fails.

pub fn get_thread(&self, index: i32) -> Result<Thread, Error>

One of the execution’s threads, by index (Execution.GetThread).

Errors

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

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

The thread a front end is following (Execution.ForegroundThread).

Errors

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

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

The execution as a property tree (Execution.AsPropertyObject).

Errors

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

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

The sequence file this execution is running (Execution.GetSequenceFile).

Distinct from GetModelSequenceFile, which is the process model, a neighbouring identifier, and mixing the two is silent.

Errors

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

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

What the run recorded (Execution.ResultObject).

The root of the results tree. ResultList beneath it holds one entry per step that recorded a result, which is what a headless caller reads instead of a report file.

Errors

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

Examples found in repository

examples/execution_run_subsequence.rs (line 119)

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

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

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

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

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

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

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

The results this run recorded, ready to read.

Composed from result_object, which is where the ResultList array lives. This is the short path a headless caller wants: run a sequence, then read what it produced without walking the tree by hand.

Errors

Error if the run recorded no result list, or a COM call fails.

Examples found in repository

examples/result_list_parse.rs (line 139)

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

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

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

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

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

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

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

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

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

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

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

The error the execution recorded (Execution.ErrorObject).

Errors

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

Trait Implementations

impl Debug for Execution

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

Formats the value using the given formatter.