Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


General

The TwinCAT system can be started or stopped from a central location. This is usually done manually by the system startup engineer or developer, or from within the program due to external influences such as voltage failure or Windows shutdown. A COM object has been introduced within the TwinCAT system service, in order to enable greater influence of an application software upon the TwinCAT system.

Deployment

TwinCAT can be started or stopped via the TwinCAT system object. By using COM/DCOM, this can also happen via a network. Furthermore, the state (RUN or STOP) can be queried via this COM object, and COM events for signalling a start or stop of the TwinCAT system can also be triggered. Now it is possible, for example, for an application to be informed about a change in state of a remote TwinCAT system.


TcSystemServer (CoClass)

The COM interface to the TwinCAT system is implemented in the TcSystemServer class. In addition to ADS, TcSystemServer offers the opportunity to control the TwinCAT system via COM/DCOM. In contrast to ADS communication, COM offers the opportunity to start a stopped TwinCAT system, and to receive events relating to the TwinCAT start or stop. DCOM also makes all functions available via a network.

The default TcSystemServer interface is called ITcSystemServer. TcSystemServer is implemented as an "out of process server" within the EXE file "TCATSysSrv.exe".


ITcSystemServer - Overview

The TwinCAT system can be controlled via the ITcSystemServer interface. ITcSystemServer has been designed as an OLE automation interface, so that it can also be used by script languages such as Visual Basic Script.

Methods in Vtable sequence

IUnknown methods | Description
QueryInterface | Returns a pointer to the interface requested.
AddRef | Increments the reference counter.
Release | Decrements the reference counter.

IDispatch methods | Description
GetTypeInfoCount | Supplies the number of "type information" interfaces, that an object offers (0 or 1).
GetTypeInfo | Gets the type information for an object.
GetIDsOfNames | Connects names of methods with optional arguments with a corresponding set of DISPIDs.
Invoke | Offers access to properties and methods of an object.

ITcSystemServer methods | Description
StartSystem | Starts the TwinCAT system.
StopSystem | Stops the TwinCAT system.
RestartSystem | Stop with subsequent start of the TwinCAT system.
SaveServerCfg | Requests all TwinCAT COM servers to save their configuration in the TwinCAT project file (*.tps).
SystemState | Property displaying the current state of the TwinCAT system.
AmsNetId | Property, with which the AmsNetId of a TwinCAT system can be queried.
RtcTimeDiff | Property, with which the current time difference between the Windows NT system time and the real-time clock of the PC is displayed.
AdjustSystemTimeToRtcTime | Synchronises the Windows NT system time with the real-time clock of the PC.


_ITcSystemEvents

An application can sign on to the events listed below via the _ITcSystemEvents event interface. The event interface is implemented as an OLE connection point and can therefore easily be integrated with Visual Basic. Examples for the integration with other programming languages such as C++ are provided in the MSDN library.

Methods in Vtable sequence

IUnknown methods | Description
QueryInterface | Returns a pointer to the interface requested.
AddRef | Increments the reference counter.
Release | Decrements the reference counter.

IDispatch methods | Description
GetTypeInfoCount | Supplies the number of "type information" interfaces, that an object offers (0 or 1).
GetTypeInfo | Gets the type information for an object.
GetIDsOfNames | Connects names of methods with optional arguments with a corresponding set of DISPIDs.
Invoke | Offers access to properties and methods of an object.

_ITcSystemEvents methods | Description
OnSystemStart | Signals the starting of a TwinCAT system.
OnSystemStop | Signals the stopping of a TwinCAT system.


TwinCAT System COM Object: Reference

ITcSystemServer::StartSystem

Method for starting of the TwinCAT system via COM/DCOM.

HRESULT StartSystem(
  [in,optional] VARIANT startParm,
);

Parameters

startParm
[in,optional]
Optional start parameter which is currently not being evaluated.

Return Values

HRESULT == S_OK
TwinCAT start successful.
HRESULT == E_FAIL
Unable to execute start.

Comments

StartSystem starts the TwinCAT system on the computer on which the TcSystemServer object was instantiated. All messages are registered in the Windows events display of that computer.


ITcSystemServer::StopSystem

Method for stopping the TwinCAT system via COM/DCOM.

HRESULT StartSystem(
  [in,optional] VARIANT stopParm,
);

Parameters

stopParm
[in,optional]
Optional stop parameter which is currently not being evaluated.

Return Values

HRESULT == S_OK
TwinCAT halt successful.
HRESULT == E_FAIL
Error during TwinCAT system halt.

Comments

StopSystem stops the TwinCAT system on the computer on which the TcSystemServer object was instantiated. All messages are registered in the Windows events display of that computer. The TwinCAT system will be stopped, even if StopSystem returns an error.


ITcSystemServer::RestartSystem

Method for stopping with subsequent start of the TwinCAT system via COM/DCOM.

HRESULT RestartSystem(
  [in,optional] VARIANT restParm,
);

Parameters

restParm
[in,optional]
Optional parameter which is currently not being evaluated.

Return Values

HRESULT == S_OK
TwinCAT restart successful.
HRESULT == E_FAIL
Error during TwinCAT system restart.

Comments

RestartSystem stops and starts the TwinCAT system on the computer on which the TcSystemServer object was instantiated. All messages are registered in the Windows events display of that computer. If RestartSystem returns an error, the TwinCAT system in question will be in stop state.


ITcSystemServer::SaveServerConfig

This method causes all COM/DCOM servers logged on to TwinCAT to save their configuration.

HRESULT SaveServerConfig(
  [in,optional] VARIANT saveParm,
);

Parameters

saveParm
[in,optional]
If only a certain COM server is required to save its data, the relevant class ID can be specified as a BSTR via "saveParm".

Return Values

HRESULT == S_OK
Saving successful.
HRESULT != S_OK
Error during saving.

Comments

Depending on the configuration, calls of this method can be quite slow and should therefore only be executed if absolutely necessary.


ITcSystemServer::SystemState

Property displaying the current state of the TwinCAT system.

HRESULT SystemState(
  [out,retval] long* pVal,
);

Parameters

pVal
[out, retval]
pVal shows the current state of the TwinCAT system. The currently implemented states are ADSSTATE_RUN (5) and ADSSTATE_STOP (6).

Return Values

HRESULT == S_OK
Reading successful.
HRESULT != S_OK
Error during reading of the current status.

Comments

Calling of SystemState returns the current state of the TwinCAT system.


ITcSystemServer::AmsNetId

Property returning the AmsNetId of the TwinCAT system in question as a character string.

HRESULT AmsNetId(
  [out,retval] BSTR* pVal,
);

Parameters

pVal
[out, retval]
pVal returns the 6 byte AmsNetId as a basic string (BSTR).

Return Values

HRESULT == S_OK
Reading successful.
HRESULT != S_OK
Error during reading of AmsNetId.

Comments

After AmsNetId has been called, AmsNetId is available as a character string. The memory for the character string is provided by the system and does not have to be allocated by the calling application. If this method is called from C or C++ without "wrapper" functions, the calling application is responsible for releasing the memory via SysFreeString.


_ITcSystemEvents::OnSystemStart

Method which is called after the TwinCAT system has been started.

HRESULT OnSystemStart(
  [in,optional] VARIANT startParm,
);

Parameters

startParm
[in,optional]
Optional start parameter which is currently not being evaluated.

Return Values

The return values are not evaluated.

Comments

OnSystemStart is called after the successful start of TwinCAT. All TwinCAT components have been started, once this event is being signalled.


_ITcSystemEvents::OnSystemStop

Method which is called when the TwinCAT system is stopped.

HRESULT OnSystemStop(
  [in,optional] VARIANT stopParm,
);

Parameters

stopParm
[in,optional]
Optional parameter which is currently not being evaluated.

Return Values

The return values are not evaluated.

Comments

OnSystemStop is called prior to the final halt of TwinCAT.


ITcSystemServer::RtcTimeDiff

Property, in which the current time difference (in seconds) between the Windows NT system time and the real-time clock of the PC is displayed.

HRESULT RtcTimeDiff(
  [out,retval] LONG* pVal,
);

Parameters

pVal
[out, retval]
pVal returns the current time difference in seconds as a long value.

Return Values

HRESULT == S_OK
Reading successful.
HRESULT != S_OK
Error during reading of the time difference.

Comments

Calling of RtcTimeDiff causes the current real-time clock values (RTC or CMOS CLOCK) to be read and compared with the Windows NT system time. The difference is the NT system time minus the RTC time. Because the maximum daily deviation of the system time from the RTC time is 1 second, frequent calls of this function are not required.


ITcSystemServer::AdjustSystemTimeToRtcTime

Method for adapting the Windows NT system time to the real-time clock of the PC.

HRESULT AdjustSystemTimeToRtcTime(
  [in,optional] VARIANT parm,
);

Parameters

parm
[in,optional]
Optional boolean value which determines whether the TwinCAT system time should also be adjusted. Parm equals TRUE means the TwinCAT system time will be adjusted, FALSE or no parameter means that only the Windows NT system time will be adjusted. If C++ is called, please note that the parameter transferred is of type VT_BOOL, and TRUE corresponds to the value 0xFFFF.

Return Values

HRESULT == S_OK
Adaptation executed successfully.
HRESULT == E_FAIL
Unable to execute start.

Comments

AdjustSystemTimeToRtcTime compares the real-time clock with the Windows NT system time and corrects the Windows NT system time by the difference. Time zones and summer time are taken into account. If the optional parameter contains TRUE, the TwinCAT system time will also be corrected. Please note that the correction can lead to time jumps during measurements or log book entries.