Object

Namespace: ZCore

Implements: IObject

IError

IObject is the heart of the Zeugwerk Framework. The central feature of the interface are methods to indicate the operation state of a framework object. At its core theses states are the foundation of all sequences within the framework. Almost all classes (aka functionblocks) in the framework use these states to propagate within sequences.

Every object can be in one of the following states.

Booting intially after the PLC (re-)starts and an object still has to perform its initialization phase (i.e. waiting for hardware, a connection, ...) the object is in the booting state. In this case the object isBusy and has no error. The ErrorMessage method may still show a message, but in this state this message is invalid.
BootingError when the initialization phase fails an object will trigger a transition from booting to bootingError. This usally indicates a configuration or hardware error. The exact reason for the error can be retrieved by the ErrorMessage methods.
Idle this state indicates that an object is ready to start a (new) sequence. The object is not busy, does not have an error. The ErrorMessage methods may still show a message, but in this state this message is invalid.
Busy this state indicates that an object is executing a sequence. The ErrorMessages method may still show a message, but in this state this message is invalid.
Error an object is in this state if the initialization phase succeeded, but a sequence failed. The exact reason for the error can be retrieved by the ErrorMessages or ErrorMessageRef method.

There are some helper methods to check for a specific state of an object, which are summerized in the following table.

State	Busy	Done	Error
Booting	TRUE	FALSE	FALSE
BootingError	FALSE	FALSE	TRUE
Idle	FALSE	TRUE	FALSE
Busy	TRUE	FALSE	FALSE
Error	FALSE	FALSE	TRUE

FUNCTION_BLOCK ABSTRACT Object IMPLEMENTS ZCore.IObject, ZCore.IError

Outputs

State ObjectState

Properties

Booted

PROPERTY Booted : BOOL

Property Value

BOOL

Busy

This property returns TRUE if the object is Busy executing a sequence or still in its initialization phase (if applicable). It returns FALSE if the object is Idle or in an Error state.

Use State to find out if the object is busy executing its initialization phase, or it is busy performing an actual sequence.

PROPERTY Busy : BOOL

Property Value

BOOL

Done

If the object is in idle state (often mentioned as "the object is not busy and not on error"), this is indicated by this property returning TRUE.

PROPERTY Done : BOOL

Property Value

BOOL

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

Methods

Abort

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence and was caused by itself. The method changes the state of the object to Error or BootingError depending on the previous state of the object Busy or Booting, respectively. Additionally, it 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.

Preexisting errors are not overwritten by calling this method twice or more.

METHOD PROTECTED 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 and was caused by itself. Compared to method Abort here it is possible to set a specific ErrorId for an error to differentiate between different error causes inside an application or sequence without the need of evaluating the error-strings.

The method changes the state of the object to Error or BootingError depending on the previous state of the object Busy or Booting, respectively.

Additionally, it 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. Preexisting errors are not overwritten by calling this method twice or more.

Calling this method also resets a stored execution token from a former "Async" call as the token is not relevant any more.

METHOD PROTECTED AbortErrorId (
 errorId : UDINT,
 message : ZString)

Inputs

errorId UDINT

(optional) error code of the issue

message ZString

Accept

This method stores the passed IStartToken so that the caller can be informed if the expected task cannot be finished. The token is only stored if its property MonitorExecution is TRUE. An existing execution token is aborted if it is not equal to the passed token to inform the former caller to react appropriate.

METHOD PROTECTED Accept (
 executionToken : IStartToken,
 reason : ZString)

Inputs

executionToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

reason ZString

Abort message, simply the reason why an active execution token was interrupted

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

If this object had an error before or after calling Assert, the method returns FALSE, otherwise it returns TRUE. To remember the usage more easily, Assert tests the obj if it is OK (no error existing), if yes Assert returns TRUE otherwise FALSE. Preexisting errors are not overwritten by calling this method twice or more.

Most likely this will be used when observing controlling tasks which should never end but should throw an error if for example a limit has been reached.

For the better understanding here are two examples with a controller task. We often use the OnOffController who is controlling a pneumatic pressure of a system by switching a compressor on and of via a (DigitalOutput).

The controller gets started and should run forever, only if a certain max pressure limit is exceeded or min pressure limit is underrun it should throw an error. Here is an example of the usage in a Sequence

(* -------------------------------------------------------------------------------------------- *)
InfrastructureStep.AutomaticRunController:
(* -------------------------------------------------------------------------------------------- *)
  IF _step.OnEntry()
  THEN       
    _controller.SetOnOffThreshold(switchOnAt:=2.6, switchOffAt:=3.4);
    _controller.SetSettling(settlingDuration:=5, settlingTimeout:=50, feedbackTolerance:=0.6);
    _controller.RunAsync(THIS^);
  END_IF
 
  IF NOT Assert(obj:=_controller)
  THEN
    SetBusy(TRUE);
    Step.SetNext(InfrastructureStep.RecoverError);
  END_IF

A second example could be, you start the controller and you want to test if it throws an error until the pressure is settled. In this case, the homing sequence will automatically abort and the statemachine transitions to FaultReaction.

(* -------------------------------------------------------------------------------------------- *)
InfrastructureStep.GoHomeStartController:
(* -------------------------------------------------------------------------------------------- *)
  IF _step.OnEntry()
  THEN       
    _controller.SetOnOffThreshold(switchOnAt:=2.6, switchOffAt:=3.4);
    _controller.SetSettling(settlingDuration:=5, settlingTimeout:=50, feedbackTolerance:=0.6);
    _controller.RunAsync(THIS^);
  END_IF
 
  Assert(obj:=_controller);
  IF _controller.Settled
  THEN
    Step.SetNext(InfrastructureStep.GoHomeEnd);
  END_IF

Calling this method also resets a stored execution token from a former "Async" call if the object changes Error state as the token is not relevant any more.

METHOD PROTECTED 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^.

Preexisting errors are not overwritten by calling this method twice or more.

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

Preexisting errors are not overwritten by calling this method twice or more.

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

METHOD PROTECTED 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

Reject

With this method, calls to an Async method can be rejected. This may be done for several reasons, including, but not limited to, invalid parameters or any other reason without aborting the object itself (maybe because its already running). The method should only be used internally in Async mehhods of an object.

The behavior of Reject is as follows.

It always aborts startToken (if available)
It aborts the object itself if
- no startToken was given by passing 0 as parameter
- the object is NOT Busy when calling the method.

Note that this implies that an active object is not aborted - even if a consecutive call to Async is invalid.

Example 1: An axis is already moving and another consecutive call to a different position has been made but a wrong speed has been given in that call

METHOD MoveAbsoluteAsync
VAR_INPUT
  startToken : ZCore.IStartToken
  position : LREAL;
  speed : LREAL;
END_VAR
------------------------------------------
IF IsNullLreal(speed, 1E-5)
THEN
  Reject(startToken, 'Action can not be started, invalid speed parameter given!');
  RETURN;
END_IF
...

Example 2: An axis should be enabled but has no power
```st
METHOD EnableDriveAsync
VAR_INPUT
  startToken : ZCore.IStartToken;  
  on : BOOL;
END_VAR
------------------------------------------
IF NOT Busy
THEN
  SetBusy(TRUE);

  IF NOT _drive.IsDrivePowered() AND_THEN on
  THEN
    Reject(startToken, 'Failed to start EnableDriveAsync command, no power available');
    RETURN;
  END_IF
...

METHOD PROTECTED Reject (
 startToken : IStartToken,
 reason : ZString)

Inputs

startToken IStartToken

Starttoken which has to be aborted

reason ZString

Abort message, simply the reason why a call to an Async method is rejected

SetBusy

This method should be called whenever an object starts an active action or when the object finished executing an action. The method will perform the following state transitions

busy Parameter	State before	State after
TRUE	Idle	Busy
TRUE	Error	Busy
TRUE	BootingError	Booting
FALSE	Busy	Idle

Other states are not effected by calling this method. The state table shows, that this method should/can only be used if an object is in its normal operation mode, after it has finished its initial Booting phase. To get from the Booting phase into the normal operation mode, use SetIdle.

Calling this method also resets a stored execution token from a former "Async" call if the object changes from Busy to Idle as the token is not relevant any more.

METHOD PROTECTED SetBusy (
 busy : BOOL)

Inputs

busy BOOL

SetIdle

This method resets the error state. It can be used as a shortcut for SetBusy(FALSE) in the normal operation mode of an object. However, calling this method is the only way to exit an objects Booting phase.

Note

The method is commonly used in constructors (i.e. FB_init) for objects that do not have or need a Booting phase to immidiatally get into the normal operation mode. That's why this object must not be overwritten, which in enforced by the FINAL attribute.

Calling this method also resets a stored execution token from a former "Async" call if the object changes from Busy to Idle as the token is not relevant any more.

METHOD PROTECTED FINAL SetIdle ()

TraceErrorStack

This method is used internally when recording an error trace.

METHOD TraceErrorStack (
 trace : IErrorTrace)

Inputs

trace IErrorTrace

Table of Contents

Object

Outputs

Properties

Booted

Property Value

Busy

Property Value

Done

Property Value

Error

Property Value

Methods

Abort

Inputs

AbortErrorId

Inputs

Accept

Inputs

Assert

Inputs

Returns

AssertCondition

Inputs

Returns

ErrorId

Returns

ErrorMessage

Returns

ErrorSource

Returns

Reject

Inputs

SetBusy

Inputs

SetIdle

Note

TraceErrorStack

Inputs