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.


TwinCAT TCP/IP Connection Server Overview

TS6421 | TwinCAT XML Data Server

Overview

The TwinCAT XML Data Server enables initialising of TwinCAT PLC variables with data stored in an XML file, or formatted saving of PLC variables in an XML file. The structure of a variable in the XML document matches the structure of the variables in the PLC. This enables individual subelements of a variable to be accessed directly. Only those subelements (elements of a structure or an array) are transferred that are also defined in the XML file. When the PLC variables are written, missing elements can optionally be added.


Requirements

TS6421 | TwinCAT XML Data Server

System Requirements

Technical Data | TS6421 XML Data Server
Target System | Windows NT/2000/XP/Vista/7 PC (x86-kompatibel)
Min. TwinCAT-Version | 2.10.0
Min. TwinCAT-Level | TwinCAT PLC

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


Installation

This part of the documentation gives a step-by-step explanation of the TwinCAT 3 XML Data Server setup process for Windows based operating systems. The following topics are part of this document:

  • Starting the installation
  • After the installation

Starting the installation

To install the Supplement, please perform the following steps:

  • Double-click the downloaded setup file "TcXmlDataSrv.exe". Please note: Under Windows 32-bit/64-bit, please start the installation with "Run as Administrator" by right-clicking the setup file and selecting the corresponding option in the context menu.
  • Click on "Next" and accept the license agreement.

Enter your user information:

Click on "Next" to start the installation

TwinCAT system has to be stopped before proceeding with installation. Select "Yes" to stop TwinCAT system service

Select "Finish" to end the setup process

After the installation

After restarting your computer the supplement "TwinCAT XML Data Server" is ready for use.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


TcpIp.Lib: Overview

Overview

The PLC library is supplied with the TwinCAT XML Data Server and copied into folder ...\TwinCAT\PLC\Lib during installation.

There are two function blocks for reading variables from the XML file:

  • FB_XmlSrvRead
  • FB_XmlSrvReadByName

and two function blocks for writing PLC variables to the XML file:

  • FB_XmlSrvWrite
  • FB_XmlSrvWriteByName

The first version (FB_XMLSrvRead, FB_XMLSrvWrite) uses the address and the size of the PLC variable for specifying the variable. The second version (FB_XMLSrvReadByName, FB_XMLSrvWriteByName) uses the symbol name for specifying the variable. The first version offers higher performance, although it is only supported from Build 1235 of TwinCAT version 2.10. For older TwinCAT versions only the function blocks FB_XMLSrvReadByName and FB_XMLSrvWriteByName can be used. In addition, the path of the XML file and the location of the variables within the XML document has to be transferred as input parameter to the function blocks in XPath format.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


FB_XmlSrvRead

FUNCTION_BLOCK FB_XmlSrvRead

The function block FB_XmlSrvRead can be used to initialise a PLC variable with data from an XML file. The input variable sXPath has to point to a valid node in the XML file specified via sFilePath. The symbol to be initialised is identified unambiguously by the symbol address and size.

VAR_INPUT

VAR_INPUT
        sNetId          : T_AmsNetId;
        ePath           : E_OpenPath := PATH_GENERIC;
        nMode           : WORD := XMLSRV_SKIPMISSING;
        pSymAddr        : DWORD;
        cbSymSize       : UDINT;
        sFilePath       : T_MaxString;
        sXPath          : T_MaxString;
        bExecute        : BOOL;
        tTimeout        : TIME := T#60s;
END_VAR

sNetId: String containing the network address of the TwinCAT XML Data Server. For the local computer (default) an empty string may be specified.

ePath: This input can be used to select a TwinCAT system path on the target device for opening the file.

nMode: This input can be used to influence how the XML file is analysed. For the XmlSrvRead command, only XMLSRV_SKIPMISSING mode is currently supported.

pSymAddr: Address of the PLC variable to which the data from the XML file are to be written.

cbSymSize: Size of the PLC variable to which the data from the XML file are to be written.

sFilePath: Contains the path and file name for the file to be opened. Note: The path can only point to the local computer’s file system! This means that network paths can not be used here!

sXPath: Contains the address of the tag in the XML document from which the data are to be written. The address must be a valid XPath instruction. The name of the tag must be different from the name of the symbol.

bExecute: The block is activated by a rising edge at this input.

tTimeout: Maximum time allowed for the execution of the function block.

VAR_OUTPUT

VAR_OUTPUT
        bBusy   : BOOL;
        bError  : BOOL;
        nErrId  : UDINT;
END_VAR

bBusy: This output is set when the function block is activated. It remains set until feedback is received.

bError: This output is set up after the bBusy output has been reset if there has been an error in transmission of the command.

nErrId : If the bError output is set, this parameter returns the TwinCAT XML Data Server error number.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 from Build 1235 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


FB_XmlSrvWrite

FUNCTION_BLOCK FB_XmlSrvWrite

The function block FB_XmlSrvWrite can be used for writing the value of a PLC variable into an XML file. The input variable sXPath has to point to a valid node in the XML file specified via sFilePath. The symbol to be written is identified unambiguously by the symbol address and size.

VAR_INPUT

VAR_INPUT
        sNetId          : T_AmsNetId;
        ePath           : E_OpenPath := PATH_GENERIC;
        nMode           : WORD := XMLSRV_SKIPMISSING;
        pSymAddr        : DWORD;
        cbSymSize       : UDINT;
        sFilePath       : T_MaxString;
        sXPath          : T_MaxString;
        bExecute        : BOOL;
        tTimeout        : TIME := T#60s;
END_VAR

sNetId: String containing the network address of the TwinCAT XML Data Server. For the local computer (default) an empty string may be specified.

ePath: This input can be used to select a TwinCAT system path on the target device for opening the file.

nMode: This input can be used to specify which data are written to the XML file. XMLSRV_SKIPMISSING and XMLSRV_ADDMISSING mode are available for the XmlSrvWrite command. In XMLSRV_SKIPMISSING mode, only those subelements of a PLC symbol that already exist in the XML file are written to the XML file. In XMLSRV_ADDMISSING mode, missing subelements are added to the XML file.

pSymAddr: Address of the PLC variable to be written to the XML file.

cbSymSize: Size of the PLC variable to be written to the XML file.

sFilePath: Contains the path and file name for the file to be opened. Note: The path can only point to the local computer’s file system! This means that network paths can not be used here!

sXPath: Contains the address of the tag in the XML document from which the data are to be written. The address must be a valid XPath instruction. The name of the tag must be different from the name of the symbol.

bExecute: The block is activated by a rising edge at this input.

tTimeout: Maximum time allowed for the execution of the function block.

VAR_OUTPUT

VAR_OUTPUT
        bBusy   : BOOL;
        bError  : BOOL;
        nErrId  : UDINT;
END_VAR

bBusy: This output is set when the function block is activated. It remains set until feedback is received.

bError: This output is set up after the bBusy output has been reset if there has been an error in transmission of the command.

nErrId : If the bError output is set, this parameter returns the TwinCAT XML Data Server error number.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 from Build 1235 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


FB_XmlSrvReadByName

FUNCTION_BLOCK FB_XmlSrvReadByName

The function block FB_XmlSrvReadByName can be used to initialise a PLC variable with data from an XML file. The input variable sXPath has to point to a valid node in the XML file specified via sFilePath. The symbol to be initialised is identified unambiguously by the symbol name.

VAR_INPUT

VAR_INPUT
        sNetId          : T_AmsNetId;
        ePath           : E_OpenPath := PATH_GENERIC;
        nMode           : WORD := XMLSRV_SKIPMISSING;
        sSymName        : T_MaxString;
        sFilePath       : T_MaxString;
        sXPath          : T_MaxString;
        bExecute        : BOOL;
        tTimeout        : TIME := T#60s;
END_VAR

sNetId: String containing the network address of the TwinCAT XML Data Server. For the local computer (default) an empty string may be specified.

ePath: This input can be used to select a TwinCAT system path on the target device for opening the file.

nMode: This input can be used to influence how the XML file is analysed. For the XmlSrvReadByName command, only XMLSRV_SKIPMISSING mode is currently supported.

sSymName: Name of the PLC symbol to which the data from the XML file are to be written.

sFilePath: Contains the path and file name for the file to be opened. Note: The path can only point to the local computer’s file system! This means that network paths can not be used here!

sXPath: Contains the address of the tag in the XML document from which the data are to be written. The address must be a valid XPath instruction. The name of the tag must be different from the name of the symbol.

bExecute: The block is activated by a rising edge at this input.

tTimeout: Maximum time allowed for the execution of the function block.

VAR_OUTPUT

VAR_OUTPUT
        bBusy   : BOOL;
        bError  : BOOL;
        nErrId  : UDINT;
END_VAR

bBusy: This output is set when the function block is activated. It remains set until feedback is received.

bError: This output is set up after the bBusy output has been reset if there has been an error in transmission of the command.

nErrId : If the bError output is set, this parameter returns the TwinCAT XML Data Server error number.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


FB_XmlSrvWriteByName

FUNCTION_BLOCK FB_XmlSrvWriteByName

The function block FB_XmlSrvWriteByName can be used for writing the value of a PLC variable into an XML file. The input variable sXPath has to point to a valid node in the XML file specified via sFilePath. The symbol to be written is identified unambiguously by the symbol name.

VAR_INPUT

VAR_INPUT
        sNetId          : T_AmsNetId;
        ePath           : E_OpenPath := PATH_GENERIC;
        nMode           : WORD := XMLSRV_SKIPMISSING;
        sSymName        : T_MaxString;
        sFilePath       : T_MaxString;
        sXPath          : T_MaxString;
        bExecute        : BOOL;
        tTimeout        : TIME := T#60s;
END_VAR

sNetId: String containing the network address of the TwinCAT XML Data Server. For the local computer (default) an empty string may be specified.

ePath: This input can be used to select a TwinCAT system path on the target device for opening the file.

nMode: This input can be used to specify which data are written to the XML file. XMLSRV_SKIPMISSING and XMLSRV_ADDMISSING mode are available for the XmlSrvWriteByte command. In XMLSRV_SKIPMISSING mode, only those subelements of a PLC symbol that already exist in the XML file are written to the XML file. In XMLSRV_ADDMISSING mode, missing subelements are added to the XML file.

sSymName: Name of the PLC symbol to be written to the XML file.

sFilePath: Contains the path and file name for the file to be opened. Note: The path can only point to the local computer’s file system! This means that network paths can not be used here!

sXPath: Contains the address of the tag in the XML document from which the data are to be written. The address must be a valid XPath instruction. The name of the tag must be different from the name of the symbol.

bExecute: The block is activated by a rising edge at this input.

tTimeout: Maximum time allowed for the execution of the function block.

VAR_OUTPUT

VAR_OUTPUT
        bBusy   : BOOL;
        bError  : BOOL;
        nErrId  : UDINT;
END_VAR

bBusy: This output is set when the function block is activated. It remains set until feedback is received.

bError: This output is set up after the bBusy output has been reset if there has been an error in transmission of the command.

nErrId : If the bError output is set, this parameter returns the TwinCAT XML Data Server error number.

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


F_GetVersionTcXmlDataSrv

FUNCTION F_GetVersionTcXmlDataSrv

This function can be used to read PLC library version information.

FUNCTION F_GetVersionTcXmlDataSrv : UINT

VAR_INPUT
        nVersionElement : INT;
END_VAR

nVersionElement : Version element to be read. Possible parameters:

  • 1 : major number;
  • 2 : minor number;
  • 3 : revision number;
Development environment | Target system type | PLC libraries to be linked
TwinCAT 2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


Globale Variablen

Global Variables

VAR_GLOBAL CONSTANT

XMLSRV_AMSPORT :UINT :=10600;

XMLSRV_IGR_CLOSE :UDINT := 121;
XMLSRV_IGR_READ :UDINT := 122;
XMLSRV_IGR_WRITE :UDINT := 123;
XMLSRV_IGR_OPENREAD :UDINT := 124;
XMLSRV_IGR_OPENWRITE :UDINT := 125;

XMLSRV_SKIPMISSING :WORD := 0;
XMLSRV_ADDMISSING :WORD := 1; (*for write commands*)

XMLSRV_MAX_FRAGSIZE :UDINT := 16#40000;

XMLSRVERROR_INTERNAL :UDINT:= 16#8000;
XMLSRVERROR_NOTFOUND :UDINT:= 16#8001;
XMLSRVERROR_PARSERERROR :UDINT:= 16#8002;
XMLSRVERROR_INCOMPATIBLE :UDINT:= 16#8003;
XMLSRVERROR_NOMEMORY :UDINT:= 16#8004;
XMLSRVERROR_ADDNODE :UDINT:= 16#8005;
XMLSRVERROR_INVALIDXPATH :UDINT:= 16#8006;

END_VAR

Development Environment | Target System | PLC Libraries to include
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib ( Standard.Lib; TcBase.Lib; TcSystem.Lib are included automatically )


sample overview

Overview Samples

In the following you will find Samples that show the handling of the TwinCAT XML Data Server. The samples are consecutively numbered and can be downloaded here.

Getting Started

The basic handling of the TwinCAT XML Data Server is shown. Besides you get to know how to work with structures and arrays.

Function Blocks

Four samples show the usage and configuration of the function blocks included in TcXmlDataSrv.Lib. (Sample 1-4)

Further Samples

This document includes further samples which show an initialization once at program startup and cyclic as well as event-driven writing. (Sample 5-6)

Production Sample

This sample shows the processing of a small production order. It makes use of FB_XmlSrvReadByName and FB_XmlSrvWriteByName. (Sample 7)


Sample Getting Started

Getting Started

In the following you will get to know the basics in working with the TwinCAT XML Data Server.

The global variable .Var1 of type DINT is defined in the PLC. The XML file is then defined as follows:

<dataentry>
    <Var1>10</Var1>
</dataentry>

Therefore the input variables of the function block FB_XmlSrvRead have to be set as follows:

fbRead.pSymAddr         := ADR(value1);
fbRead.cbSymSize        := SIZEOF(value1);
fbRead.sFilePath        := Pfad zur XML-Datei z.B. 'C:\Test.xml';
fbRead.sXPath           := '/dataentry/Var1';

The root element in the XML file and the name of the variables are freely selectable in the XML file. The only modification required is the path in input variable sXPath. An XML file may contain definitions for several variables:

<dataentry>
    <Var1>10</Var1>
    <Var2>100</Var2>
    <Var3>
        <a>100</a>
        <b>10</b>
    </Var3>
</dataentry>

For accessing the symbol .Var3.a, sXpath has to be set to '/dataentry/Var3.a'.

Structures

XML files have the same hierarchical structure as the PLC. Individual subelements of the XML file may be skipped. The names of the individual subelements of the structure must match the names in the PLC, otherwise they are skipped. If subelements of the XML file cannot be converted to the correct data type, they are skipped as well.

Example: The global variable .Var2 of type ST_MYSTRUCT is defined in the PLC:

TYPE ST_MYSTRUCT:
STRUCT
        a:  UINT;
        b:  DINT;
        c:  LREAL;
        d:  STRING;
END_STRUCT
END_TYPE

The XML file could then look like this:

<variables>
    <Var1>10</Var1>
    <Var2>                         <!-- sXPath := '/variables/Var2' -->
        <a>100</a>
        <b>-10</b>
        <c>1.2</c>
        <d>Hallo</d>
    </Var2>
</variables>

In this case all subelements are defined fully and correctly, so that the variable is fully initialized. In the following example, on the other hand, only subelement c is serialized:

<variables>
    <Var1>10</Var1>
    <Variable2>                   <!-- sXPath := '/variables/Variable2' -->
         <Info>dies ist ein Test</Info>
         <a>-100</a>
         <c>1.2</c>
    </Variable2>
</variables>

Subelement a cannot be converted since the sign is wrong, subelement b is missing completely. The tag is skipped, since it is not defined in the PLC.

Arrays

In order to specify an array index, the attribute "index" has to be used for the individual array elements. Individual array elements may be omitted and will be skipped.

Example: A variable .array1 of type ARRAY[1..4] OF DINT is defined in the PLC. The XML file will then look as follows:

<dataentry>
    <array1 index="1">10</array1>
    <array1 index="2">10</array1>
    <array1 index="3">10</array1>
    <array1 index="4">10</array1>
</dataentry>

Entwicklungsumgebung | Zielplattform | Einzubindende SPS Bibliotheken
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


Sample Functionblocks

Function blocks

The following samples show the handling of the functionblocks of the tcXmlDataSrv-Library. The PLC projekt, which contains the samples, can be downloaded here.

All samples work with the structure ST_MYSTRUCT, which in turn includes ST_INNTERSTRUCT. Both Structures are shown in the following:

Structures

TYPE ST_MYSTRUCT:
STRUCT
   fReal          : REAL;
   bBool          : ARRAY [0..2] OF BOOL;
   stInner        : ST_INNTERSTRUCT;
END_STRUCT
END_TYPE
TYPE ST_INNTERSTRUCT:
STRUCT
  nInteger        : INT;
  sString	         : STRING;
END_STRUCT
END_TYPE

Sample 1: Basic printing procedure with FB_XmlSrvWrite

In the first step the structure ST_MyStruct shall be written to an XML file. The mode is set to XMLSRV_ADMISSING, so that the XML file will be created automatically (if it does not already exist) as well as the structure in it. Folders will not be created automatically! This method is recommended even then, if you do not intend to write but just to read the file. So the XML file does not have to be created manually, which saves time and avoids mistakes.

(* Sample1 creates an XML-file under the path C:\Test.xml and writes value1 to it.
   FUNCTIONBLOCK: FB_XmlSrvWrite *)
PROGRAM Sample1
VAR
   value1          : ST_MyStruct;
   fbXmlSrvWrite   : FB_XmlSrvWrite;
   bExecute        : BOOL;
   sFilePath       : T_MaxString := 'C:\Test.xml';  (* CE: '\Hard Disk\Test.xml' *)
   sXPath          : T_MaxString := '/dataentry/MAIN.value1';
END_VAR

fbXmlSrvWrite(
   nMode           := XMLSRV_ADDMISSING,
   pSymAddr        := ADR(value1),
   cbSymSize       := SIZEOF(value1),
   sFilePath       := sFilePath,
   sXPath	          := sXPath,
   bExecute        := bExecute
);
bExecute:= TRUE;

Sample 2: Basic printing procedure with FB_XmlSrvWriteByName

Sample 2 has the same result as sample 1, but makes use of FB_XmlSrvWriteByNamen. However Sample 1 is more performant.

(* Sample2 creates an XML-file under the path C:\Test.xml and writes value1 to it.
   FUNCTIONBLOCK: FB_XmlSrvWriteByName *)
PROGRAM Sample2
VAR
   value1          : ST_MyStruct;
   fbXmlSrvWrite   : FB_XmlSrvWriteByName;
   bExecute        : BOOL;
   sSymName        : T_MaxString := 'Sample2.value1';
   sFilePath       : T_MaxString := 'C:\Test.xml';  (* CE: '\Hard Disk\Test.xml' *)
   sXPath          : T_MaxString := '/dataentry/MAIN.value1';
END_VAR

fbXmlSrvWrite(
   nMode           := XMLSRV_ADDMISSING,
   sSymName        := sSymName,
   sFilePath       := sFilePath,
   sXPath	          := sXPath,
   bExecute        := bExecute
);
bExecute:= TRUE;

XML file

No matter which function block is used, the XML file 'Test.xml' will be created under C:\. For that you get the same XML-content both times, sXPath has to be the same ('/dataentry/MAIN.value1'). It does not matter that value1 is not directly created in the main, but in the specific program. This path in TwinCAT is set by sSymName (Sample 2): 'Sample2.value1'.

<dataentry>
  <MAIN.value1>
    <fReal>0</fReal>
    <bBool index="0">false</bBool>
    <bBool index="1">false</bBool>
    <bBool index="2">false</bBool>
    <stInner>
      <nInteger>0</nInteger>
      <sString></sString>
    </stInner>
  </MAIN.value1>
</dataentry>

Sample 3: Basic reading procedure with FB_XmlSrvRead

In the following the structure created in Sample 1 or Sample 2 shall be read.

(* Sample3 reads an XML-file (C:\Test.xml) FUNCTIONBLOCK: FB_XmlSrvRead *)
PROGRAM Sample3
VAR
   value1         : ST_MyStruct;
   fbXmlSrvRead   : FB_XmlSrvRead;
   bExecute       : BOOL;
   sFilePath      : T_MaxString := 'C:\Test.xml';  (* CE: '\Hard Disk\Test.xml' *)
   sXPath         : T_MaxString := '/dataentry/MAIN.value1';
END_VAR

fbXmlSrvRead(
   pSymAddr       := ADR(value1),
   cbSymSize      := SIZEOF(value1),
   sFilePath      := sFilePath,
   sXPath	         := sXPath,
   bExecute       := bExecute
);
bExecute:= TRUE;

Sample 4: Basic reading procedure with FB_XmlSrvReadByName

Sample 4 shows the reading procedure under usage of FB_XmlSrvReadByName.

(* Sample4 reads an XML-file (C:\Test.xml) FUNCTIONBLOCK: FB_XmlSrvReadByName *)
PROGRAM Sample4
VAR
   value1         : ST_MyStruct;
   fbXmlSrvRead   : FB_XmlSrvReadByName;
   bExecute       : BOOL;
   sSymName       : T_MaxString := 'Sample4.value1';
   sFilePath      : T_MaxString := 'C:\Test.xml';  (* CE: '\Hard Disk\Test.xml' *)
   sXPath         : T_MaxString := '/dataentry/MAIN.value1';
END_VAR

fbXmlSrvRead(
   sSymName       := sSymName,
   sFilePath      := sFilePath,
   sXPath	         := sXPath,
   bExecute       := bExecute
);
bExecute:= TRUE;

Here again (as in sample 2) you have to differentiate between sSymName and sXPath: sXPath sets the path within the XML file - determined in sample 1 and 2. sSymName on the other hand sets the symbol name of the variable in TwinCAT, which is 'Sample4.value1'.

Entwicklungsumgebung | Zielplattform | Einzubindende SPS Bibliotheken
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


Sample further samples

Further Samples

The following samples show different types of application of the TwinCAT XML Data Servers. The PLC-projekt, which contains the samples, can be downloaded here.

Sample 5 shows an initialization once at program startup, Sample 6 shows cyclic and event-driven printing procedures. Both samples again use the structure ST_MYSTRUCT, which in turn includes ST_INNTERSTRUCT. Both Structures are shown in the following:

Structures

TYPE ST_MYSTRUCT:
STRUCT
   fReal       : REAL;
   bBool       : ARRAY [0..2] OF BOOL;
   stInner     : ST_INNTERSTRUCT;
END_STRUCT
END_TYPE
TYPE ST_INNTERSTRUCT:
STRUCT
  nInteger     : INT;
  sString	      : STRING;
END_STRUCT
END_TYPE

Sample 5: Initialization once at program startup

Sample 5 shows the initialization of value1 once at program startup. Therefore FB_XmlSrvRead is used.

(* Sample5 reads and initializes value1 when the PLC is started FUNCTIONBLOCK: FB_XmlSrvRead *)
PROGRAM Sample5
VAR
   value1        : ST_MyStruct;
   fbXmlSrvRead  : FB_XmlSrvRead;
   bExecute      : BOOL;
   sFilePath     : T_MaxString := 'C:\Test.xml'; (* CE: '\Hard Disk\Test.xml' *)
   sXPath        : T_MaxString := '/dataentry/MAIN.value1';
   nState        : INT := 0;
END_VAR

CASE nState OF
0: (* initialize *)
   fbXmlSrvRead(
   pSymAddr  := ADR(value1),
   cbSymSize := SIZEOF(value1),
   sFilePath := sFilePath,
   sXPath    := sXPath,
   bExecute  := bExecute
   );
   fbXmlSrvRead(bExecute:= TRUE);
   nState:= 1;

1: (* wait for read operation *)
   fbXmlSrvRead(bExecute:= FALSE);
   IF NOT fbXmlSrvRead.bBusy AND NOT fbXmlSrvRead.bError THEN
     nState:= 2;
   ELSIF fbXmlSrvRead.bError THEN
     nState:= 100;
   END_IF

2: (* operations *)
   ;

100:(* errorState *)
   ;

END_CASE

Sample 6: Cyclic and event-driven printing

The following sample creates a new XML file every 20 seconds and writes the above-mentioned structure to it. The filename is made up of the current windows-date, -time and the string sFileName. Furthermore the printing procedure can be started by pressing a button (or setting the respective variable bButton). If the printing procedure is triggered twice a second the latest file will be overwritten.

(* Sample6: Every 20s value1 will be written into a new XML-File named after the current date and
   time. Furthermore you can activate the printing procedure by pressing a button (or setting the
   corresponding variable *)
PROGRAM Sample6
VAR
   value1            : ST_MyStruct;
   fbXmlSrvWrite     : FB_XmlSrvWrite;

   sFileFolder       : T_MaxString :='C:\'; (* CE: '\Hard Disk\' *)
   sFileName         : T_MaxString:= '_test.xml';
   sFilePathWrite    : T_MaxString
   (*sFilePathWrite = sFileFolder + time + sFileName*)

   sXPathWrite       : T_MaxString :='/dataentry/MAIN.value1';
   ntGetTime         : NT_GetTime;
   stMyTimestruct    : TIMESTRUCT;
   iState            : INT := 1;
   bTwentySec        : BOOL:= FALSE;
   bButton           : BOOL:= FALSE;
   bTwentySecOver    : BOOL;
   triggerWrite      : R_TRIG;
   triggerButton     : R_TRIG;
END_VAR

triggerButton(CLK:= bButton);

CASE iState OF
0: (* idle state *)
   ;

1: (* initialize *)
   fbXmlSrvWrite(nMode:=XMLSRV_ADDMISSING, pSymAddr:= ADR(value1),
     cbSymSize:= SIZEOF(value1));
   ntGetTime(START:= TRUE, TIMESTR=>stMyTimestruct);  (* get Windows time *)
   IF NOT ntGetTime.BUSY AND NOT ntGetTime.ERR THEN
     iState:= 2;
   ELSIF ntGetTime.ERR THEN
     iState:= 100;
   END_IF

2: (* working state *)
   (* change some values - replace with production-process *)
   value1.stInner.nInteger:= value1.stInner.nInteger + 1;
   IF value1.stInner.nInteger = 32767 THEN
     value1.stInner.nInteger:= 0;
   END_IF

   (* get Windows time *)
   ntGetTime(START:= FALSE);
   IF NOT ntGetTime.BUSY AND NOT ntGetTime.ERR THEN
     ntGetTime(START:= TRUE, TIMESTR=>stMyTimestruct);
   ELSIF ntGetTime.ERR THEN
     iState:= 100;
   END_IF

   (* check if 20s have passed*)
   IF stMyTimestruct.wSecond = 0  OR stMyTimestruct.wSecond = 20  OR stMyTimeStruct.wSecond = 40  THEN
     bTwentySecOver:= TRUE;
   ELSE
     bTwentySecOver:= FALSE;
   END_IF

   (* if 20s have passed => trigger writing-process *)
   triggerWrite(CLK:=bTwentySecOver);
   IF (triggerWrite.Q OR triggerButton.Q) AND NOT fbXmlSrvWrite.bBusy
                                          AND NOT fbXmlSrvWrite.bError THEN
     (* create filename *)
     sFilePathWrite:= CONCAT(sFileFolder, SYSTEMTIME_TO_STRING(stMyTimestruct)); (* set folder + time *)
     sFilePathWrite:= DELETE(STR:= sFilePathWrite, LEN:= 4 ,
                             POS:= LEN(STR:=sFilePathWrite)-3); (* delete milliseconds *)
     sFilePathWrite:= REPLACE(STR1:= sFilePathWrite , STR2:= '.' , L:= 1,
                              P:= LEN(STR:=sFilePathWrite)-2); (* replace colon with point *)
     sFilePathWrite:= REPLACE(STR1:= sFilePathWrite , STR2:= '.' , L:= 1,
                              P:= LEN(STR:=sFilePathWrite)-5); (* replace colon with point *)
     sFilePathWrite:= CONCAT(sFilePathWrite, sFileName);  (* add filename (default: test) *)
     (* write *)
     fbXmlSrvWrite(sFilePath:=sFilePathWrite, sXPath:=sXPathWrite, bExecute:= TRUE);
   ELSIF fbXmlSrvWrite.bError THEN
     iState:= 100;
   END_IF

   (* reset fbXmlSrvWrite *)
   IF fbXmlSrvWrite.bBusy AND NOT ntGetTime.ERR THEN
     fbXmlSrvWrite(bExecute:= FALSE);
   ELSIF ntGetTime.ERR THEN
     iState:= 100;
   END_IF

100: (* error state*)
   ;

END_CASE

Entwicklungsumgebung | Zielplattform | Einzubindende SPS Bibliotheken
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


ProductionSampleXMLDataSrv

Sample 7 (Production Sample)

The production data are read, the production is carried out and, according to the quantity and the production order, completed with an entry in the XML file.
To start the program the XML file needs to be stored at the corresponding place of the data path and the variable bStart needs to be set TRUE in the PLC program.

The PLC-projekt, which includes this sample, can be downloaded here.

Variable declaration

PROGRAM Sample7
VAR
   fbXmlSrvReadByName      : FB_XmlSrvReadByName;
   fbXmlSrvWriteByName     : FB_XmlSrvWriteByName;

   value                   : ST_MyProductionStruct;

   state                   : INT := 0;
   R_Edge                  : R_TRIG;
   bStart                  : BOOL;
   bError                  : BOOL;
   nErrId                  : UDINT;
END_VAR

Structure ST_MyProductionStruct

TYPE ST_MyProductionStruct :
STRUCT
   rLength         : REAL;
   rWidth          : REAL;
   rHeight         : REAL;
   iQuantity       : INT;
   iCounter        : INT;
   bReady          : BOOL;
   stInfo          : STRING;
END_STRUCT
END_TYPE

PLC Program

(* The production data are read, the production is carried out and, according to the
   quantity and the production order, completed with an entry in the XML file.
   To start the program the XML file needs to be stored at the corresponding place
   of the data path and the variable bStart needs to be set TRUE in the PLC program. *)
R_Edge (CLK := bStart);
IF R_Edge.Q THEN
    state := 1;
END_IF

CASE state OF
0: (* idle state *)
       ;

1: (* init state *)
    fbXmlSrvReadByName( sNetId     := '',
                        sSymName   := 'Sample7.value',
                        sFilePath  := 'C:\Production1.xml',
                        sXPath     := '/dataentry/MAIN.value',
                        bExecute   := TRUE,
                        tTimeout   := t#10s,
                        bError     => bError,
                        nErrId     => nErrId);
    state := 2;

2:
    fbXmlSrvReadByName(bExecute := FALSE);
    IF NOT fbXmlSrvReadByName.bBusy AND NOT fbXmlSrvReadByName.bError THEN
        state := 3;
    ELSIF fbXmlSrvReadByName.bError THEN
        state := 100;
    END_IF

3:  (* working state *)
    IF value.bReady = TRUE THEN
        value.stInfo := 'The order was already processed!';
        (* replace your production XML file! *)
        state := 4;
        RETURN;
    END_IF

    (* Call production program with
    new length, width and height here *)

    value.iCounter := value.iCounter + 1;
    IF value.iCounter = value.iQuantity THEN
        value.bReady := TRUE;
        state := 4;
    END_IF

4:  (* documentation state *)
    fbXmlSrvWriteByName( sNetId     := '',
                         nMode      := XMLSRV_SKIPMISSING,
                         sSymName   := 'Sample7.value',
                         sFilePath  := 'C:\Production1.xml',
                         sXPath     := '/dataentry/MAIN.value',
                         bExecute   := TRUE,
                         tTimeout   := t#10s,
                         bError     => bError,
                         nErrId     => nErrId);
    state := 5;

5:
    fbXmlSrvWriteByName(bExecute := FALSE);
    IF NOT fbXmlSrvWriteByName.bBusy AND NOT fbXmlSrvWriteByName.bError THEN
        state := 0;
    ELSIF fbXmlSrvWriteByName.bError THEN
        state := 100;
    END_IF

100:(* error state *)
        ;
END_CASE

XML File

<dataentry>
    <MAIN.value>
       <rLength>65.85</rLength>
       <rWidth>30</rWidth>
       <rHeight>2.5</rHeight>
       <iQuantity>500</iQuantity>
       <iCounter>0</iCounter>
       <bReady>false</bReady>
       <stInfo></stInfo>
    </MAIN.value>
</dataentry>

Entwicklungsumgebung | Zielplattform | Einzubindende SPS Bibliotheken
TwinCAT v2.10.0 | PC or CX (x86) | TcXmlDataSrv.Lib


Overview

TS6421 | TwinCAT XML Data Server

Overview of TwinCAT XML Data Server error codes

Offset + error code | Range | Description
0x00000000 + TwinCAT system error | 0x00000000-0x00007800 | TwinCAT system error (including ADS error codes)
0x00008000 + internal TwinCAT XML Data Server error | 0x00008000-0x000080FF | Internal TwinCAT XML Data Server error


Internal TCP/IP Connection Server error codes

Internal error codes of the TwinCAT XML Data Server

Code | Description | Symbolic name
0x00008000 | Internal error | XMLSRVERROR_INTERNAL
0x00008001 | Handle not found. | XMLSRVERROR_NOTFOUND
0x00008002 | Error during parsing of the XML file | XMLSRVERROR_PARSERERROR
0x00008003 | Incompatible data type. | XMLSRVERROR_INCOMPATIBLE
0x00008004 | Error during memory allocation | XMLSRVERROR_NOMEMORY
0x00008005 | Error during adding of an XML node | XMLSRVERROR_ADDNODE
0x00008006 | Invalid sXPath | XMLSRVERROR_INVALIDXPATH
0x00008007 | Invalid String in TC | XMLSRVERROR_INVALIDSTRING
0x00008800 | Invalid Client Handle | XMLSRVERROR_INVALIDCLIENTHANDLE
0x00008900 | Wrong Version of TcXmlDataSrv.exe in use (TC2 instead of TC3) | XMLSRVERROR_INVALIDTWINCATVERSION