pub struct SequenceContext { /* private fields */ }Expand description
A point in a running sequence, and everything reachable from it
(SequenceContext).
This is what an expression calls ThisContext, obtained from
Thread::get_sequence_context. It is
the door to the variable scopes, Locals, Parameters, FileGlobals,
StationGlobals, and to RunState.
§Lifetimes: what may outlive the run, and what may not
A host holding the wrong reference after an execution ends keeps a COM object alive on a finished run. The documentation draws the line explicitly: these exist before, and persist after, the execution, ///
station_globals, shared by the whole session, and modifications from one execution are seen by all of themsequence_file
, while everything else belongs to the run, file_globals
most notably: it is the execution’s own copy, and writing to it does not
touch the file’s stored defaults.
So the safe pattern for a host is to read what it needs from a context while
the run is alive and keep the data, not the reference. Values that must
outlive the run come from the engine or the file instead:
Engine::globals for station globals with no
execution at all, and
SequenceFile::file_globals_default_values
for the file’s edit-time defaults.
Implementations§
Source§impl SequenceContext
impl SequenceContext
Sourcepub fn as_property_object(&self) -> Result<PropertyObject, Error>
pub fn as_property_object(&self) -> Result<PropertyObject, Error>
Sourcepub fn locals(&self) -> Result<PropertyObject, Error>
pub fn locals(&self) -> Result<PropertyObject, Error>
Sourcepub fn parameters(&self) -> Result<PropertyObject, Error>
pub fn parameters(&self) -> Result<PropertyObject, Error>
Sourcepub fn file_globals(&self) -> Result<PropertyObject, Error>
pub fn file_globals(&self) -> Result<PropertyObject, Error>
The executing file’s globals (SequenceContext.FileGlobals).
Belongs to the run. This is the execution’s own copy: changes here
do not affect the defaults stored in the sequence file, and the object
is meaningless once the run is over. Read what is needed now, or use
SequenceFile::file_globals_default_values
for the values that live in the file.
§Errors
Error if the COM call fails or returns an unexpected type.
Sourcepub fn station_globals(&self) -> Result<PropertyObject, Error>
pub fn station_globals(&self) -> Result<PropertyObject, Error>
The station’s global variables (SequenceContext.StationGlobals).
Outlives the run, and is shared: a change made here is seen by every
execution in the session, and persists on disk. Reachable without any
execution through Engine::globals, which is
the better route when no run is involved.
§Errors
Error if the COM call fails or returns an unexpected type.
Sourcepub fn run_state(&self) -> Result<PropertyObject, Error>
pub fn run_state(&self) -> Result<PropertyObject, Error>
The runtime state tree a running sequence sees as RunState.
Not a COM member: RunState carries no DISPID in any supported type
library, it is a node in the context’s property tree, which is why this
goes through the property object rather than a dispatch call. The vendor
reaches it the same way, by lookup string.
Under it sit the things a host reports on that have no member of their
own, notably TestSockets for a multi-UUT panel, alongside duplicates
of members this type already exposes directly, such as Sequence and
CallStackDepth. Prefer the direct accessors where they exist, and
reach through here for the rest.
§Errors
Error if the context carries no RunState or a COM call fails.
Sourcepub fn sequence_file(&self) -> Result<SequenceFile, Error>
pub fn sequence_file(&self) -> Result<SequenceFile, Error>
Sourcepub fn call_stack_depth(&self) -> Result<i32, Error>
pub fn call_stack_depth(&self) -> Result<i32, Error>
Sourcepub fn step_index(&self) -> Result<i32, Error>
pub fn step_index(&self) -> Result<i32, Error>
Sourcepub fn next_step_index(&self) -> Result<i32, Error>
pub fn next_step_index(&self) -> Result<i32, Error>
Sourcepub fn previous_step_index(&self) -> Result<i32, Error>
pub fn previous_step_index(&self) -> Result<i32, Error>
Sourcepub fn loop_index(&self) -> Result<i32, Error>
pub fn loop_index(&self) -> Result<i32, Error>
The loop position at this point (SequenceContext.LoopIndex).
This view is a 32-bit integer. Read RunState.LoopIndex as a number
through as_property_object when the
fractional or wider value matters.
§Errors
Error if the COM call fails or returns an unexpected type.
Sourcepub fn previous_step(&self) -> Result<Step, Error>
pub fn previous_step(&self) -> Result<Step, Error>
Sourcepub fn num_steps_executed(&self) -> Result<i32, Error>
pub fn num_steps_executed(&self) -> Result<i32, Error>
Sourcepub fn sequence_failed(&self) -> Result<bool, Error>
pub fn sequence_failed(&self) -> Result<bool, Error>
Sourcepub fn error_reported(&self) -> Result<bool, Error>
pub fn error_reported(&self) -> Result<bool, Error>
Sourcepub fn run_time_error_message(&self) -> Result<String, Error>
pub fn run_time_error_message(&self) -> Result<String, Error>
Sourcepub fn step(&self) -> Result<Step, Error>
pub fn step(&self) -> Result<Step, Error>
The step being run right now (SequenceContext.Step).
Fallible by nature. The engine documents this property as existing only while a step executes, between steps, and at a breakpoint, there is no current step. An error here is a legitimate state, not a defect, which is why it is not reported as an empty value.
§Errors
Error if no step is executing, or the COM call fails.