Table of Contents

StartToken

Namespace
ZCore
Implements

This object is commonly used by methods to indicate if the method was executed successfully. Since this functionblock implements the IObject it can be used rather easily throughout the framework.

The main difference of this functionblock to namely Object is, that StartToken allows the user to explicitly call the Abort methods (and its derivatives). The latter method should be called by the user to indicate problems. Object only uses such methods internally (i.e. in its Cyclic method) and does not allow a user to call these methods externally.

For best practice, StartToken should be created on the heap and Recover should be called before actually using it as a parameter. (or alternatively the RunActionAsync in the following example should call Recover at the very top.

(...)
VAR_INST
  startToken : ZCore.StartToken;
END_VAR
(...)
startToken.Recover();
RunActionAsync(startToken);
IF NOT startToken.Error
THEN
  (...)
END_IF

If the StartToken is instead created on the stack (VAR ... END_VAR) instead of (VAR_INST ... END_VAR) the explicit call to Recover is not necessary. However, this practice is usually slower than using the heap.

Note

Conveniently to let Sequences extends from ExecutionToken. That is why in sequences, no additional objects have to be created on the stack or heap and error propagation is straight forward, by using THIS^ in cases where a StartToken is required.

FUNCTION_BLOCK StartToken IMPLEMENTS ZCore.IObject, ZCore.IStartToken, ZCore.IRecoverable, ZCore.IError

Outputs

State ObjectState

Diagnostics DiagnosticMessage

Constructor

FB_init 

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL) : BOOL

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

Returns

BOOL

Properties

Error

If the object aborts its execution with an error, this is indicated by this property returning TRUE. Information about the error may be retrieved by utilizing the methods that are implemented from the IError.

Returns TRUE if a fault occured within a sequence or the initialization phase of an object, respectively. If this property returns TRUE, use

to get insights about the origin of the fault.

PROPERTY Error : BOOL

Property Value

BOOL

MonitorExecution

This property indicates if an object, which gets this Token in an async method call, whether it shall be stored to monitor the whole execution of the task or not. In case the execution shall be monitored (property=TRUE), the object can inform this Token as the caller of an originally started task, if it has changed unexpected, with aborting the Token.

For example you can think of an axis starting MoveAbsoluteAsync in a sequence. Stopping the axis at a different place in your application without or with another Token leads to aborting the stored Token, therefore, the caller gets informed about the change.

Tokens with this property being TRUE are the ExecutionToken and a Sequence.

To 'only' ask if an async call was executed successfully, use the StartToken

PROPERTY MonitorExecution : BOOL

Property Value

BOOL

Methods

Abort

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence. The method changes the state of the object to error and additionally, sets a message to indicate the problem. The error source of the issue is set to THIS^ object and the error code is set to 0. If the error should be more specific and be externally evaluated with the ErrorId method, AbortErrorId should be used instead.

If called during initialization (state_ = Booting) the state variable is set to BootingError.

Note

For pure Objects the abort method is not callable from the outside, because its abort method is PROTECTED. The StartToken, however, make the method available from the outside API.

METHOD Abort (
 message : ZString)

Inputs

message ZString

AbortErrorId

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence. The method changes the internal state of the object to error and additionally, sets a message to indicate the problem. The error source of the issue is set to THIS^ object and the error code is set to errorId.

If called during initialization (state_ = Booting) the state variable is set to BootingError.

Note

For pure Objects the abort method is not callable from the outside, because its abort method is PROTECTED. The StartToken, however, make the method available from the outside API.

METHOD AbortErrorId (
 errorId : UDINT,
 message : ZString)

Inputs

errorId UDINT

message ZString

AbortWithContext

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence. The method changes the internal state of the object to error and additionally, sets a message to indicate the problem. The error source of the issue is set to THIS^ object and the error code is set to errorId.

If called during initialization (state_ = Booting) the state variable is set to BootingError.

Note

For pure Objects the abort method is not callable from the outside, because its abort method is PROTECTED. The StartToken, however, make the method available from the outside API.

If the optional context parameter is provided, error tracing is more detailed

METHOD AbortWithContext (
 message : ZString,
 context : REFERENCE TO ManagedObject)

Inputs

message ZString

context REFERENCE TO ManagedObject

Assert

This method is used for error propagation from one object obj to this object. The error state of this object is set if it is not already in error state and obj has an error. The error source is set to obj, such that for hierarchies the initial error source can be specified by recursion (see ErrorSource).

Note

For pure Objects the abort method is not callable from the outside, because its abort method is PROTECTED. The StartToken, however, make the method available from the outside API.

METHOD Assert (
 obj : IError) : BOOL

Inputs

obj IError

Returns

BOOL

AssertCondition

This method evaluates a condition. If the condition is not satisfied, a call to AbortErrorId is made, which puts the object into its error state, setting the error source to THIS^.

IF NOT condition
THEN
  AbortErrorId(0, ErrorMessage);
END_IF

The condition check is meant to be similar to other programming languages, e.g. assert in C++.

Note

For pure Objects the abort method is not callable from the outside, because its abort method is PROTECTED. The StartToken, however, make the method available from the outside API.

METHOD AssertCondition (
 condition : BOOL,
 message : ZString) : BOOL

Inputs

condition BOOL

message ZString

Returns

BOOL

ErrorId

Returns the error code of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

METHOD ErrorId () : UDINT

Returns

UDINT

ErrorMessage

Returns the error description of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

METHOD ErrorMessage () : ZString

Returns

ZString

ErrorSource

This method returns the direct error source of this object. This method can then be used to retrieve the actual error source by using the method of the returned IError.

METHOD ErrorSource () : IError

Returns

IError

LogDiagnostics

This method can be used to explicitly write a diagnostics information with a given LogLevel

METHOD LogDiagnostics (
 level : LogLevel,
 message : ZString)

Inputs

level LogLevel

message ZString

Recover

Set the internal error state to false. This is useful after the Abort method was called and error handling can recover from this error. It is mainly used to recover Tokens as seen in the following example.

(...)
VAR_INST
  startToken : ZCore.StartToken;
END_VAR
(...)
startToken.Recover();
RunActionAsync(startToken);
IF NOT startToken.Error
THEN
  (...)
END_IF

METHOD Recover ()

TraceErrorStack

This method is used internally when recording an error trace.

METHOD TraceErrorStack (
 trace : IErrorTrace)

Inputs

trace IErrorTrace