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.


Overview

TwinCAT TcAdsDLL: Introduction

Introduction

The TcAdsDll provides functions for communication with other ADS devices.

  • Communication to local TwinCAT systems or remote TwinCAT systems via the TwinCAT Message router.
  • Communication to remote TwinCAT systems via TCP/IP for Win32 Systems.

The TcAdsDll provides the TwinCAT Ads Client functions. These functions are provided in 2 different ways:

  • By C API.
  • By COM interfaces

It is recommended to use the TwinCAT CP (royalty free) version with the library.


API Overview

TwinCAT TcAdsDLL: API Overview

Overview

The TcAdsDll provides functions for communication with other ADS devices via the TwinCAT router through it's C API interface. You will find further information related to ADS under TwinCAT ADS.

All the examples used for illustration in this guide are implemented in Visual C++. None of the examples is particularly complicated, so very advanced knowledge of C/C++ is not needed.


ADS Return Codes

Error codes: 0x000..., 0x500..., 0x700..., 0x1000..., 0x274C...

Global Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x0 | 0 | no error |  |
0x1 | 1 | Internal error |  |
0x2 | 2 | No Rtime |  |
0x3 | 3 | Allocation locked memory error |  |
0x4 | 4 | Insert mailbox error | No ADS mailbox was available to process this message. | Reduce the number of ADS calls (e.g ADS-Sum commands or Max Delay Parameter)
0x5 | 5 | Wrong receive HMSG |  |
0x6 | 6 | target port not found | ADS Server not started |
0x7 | 7 | target machine not found | Missing ADS routes |
0x8 | 8 | Unknown command ID |  |
0x9 | 9 | Bad task ID |  |
0xA | 10 | No IO |  |
0xB | 11 | Unknown ADS command |  |
0xC | 12 | Win 32 error |  |
0xD | 13 | Port not connected |  |
0xE | 14 | Invalid ADS length |  |
0xF | 15 | Invalid ADS Net ID |  |
0x10 | 16 | Low Installation level |  |
0x11 | 17 | No debug available |  |
0x12 | 18 | Port disabled |  |
0x13 | 19 | Port already connected |  |
0x14 | 20 | ADS Sync Win32 error |  |
0x15 | 21 | ADS Sync Timeout |  |
0x16 | 22 | ADS Sync AMS error |  |
0x17 | 23 | ADS Sync no index map |  |
0x18 | 24 | Invalid ADS port |  |
0x19 | 25 | No memory |  |
0x1A | 26 | TCP send error |  |
0x1B | 27 | Host unreachable |  |
0x1C | 28 | Invalid AMS fragment |  |

Router Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x500 | 1280 | ROUTERERR_NOLOCKEDMEMORY | No locked memory can be allocated |
0x501 | 1281 | ROUTERERR_RESIZEMEMORY | The size of the router memory could not be changed |
0x502 | 1282 | ROUTERERR_MAILBOXFULL | The mailbox has reached the maximum number of possible messages. The current sent message was rejected | Check the connection between the communication partners
0x503 | 1283 | ROUTERERR_DEBUGBOXFULL | The mailbox has reached the maximum number of possible messages. The sent message will not be displayed in the debug monitor | Check the connection to the debug monitor
0x504 | 1284 | ROUTERERR_UNKNOWNPORTTYPE | The port type is unknown |
0x505 | 1285 | ROUTERERR_NOTINITIALIZED | Router is not initialised |
0x506 | 1286 | ROUTERERR_PORTALREADYINUSE | The desired port number is already assigned |
0x507 | 1287 | ROUTERERR_NOTREGISTERED | Port not registered |
0x508 | 1288 | ROUTERERR_NOMOREQUEUES | The maximum number of Ports reached |
0x509 | 1289 | ROUTERERR_INVALIDPORT | The port is invalid. |
0x50A | 1290 | ROUTERERR_NOTACTIVATED | TwinCAT Router not active |
0x50B | 1291 | ROUTERERR_FRAGMENTBOXFULL |  |
0x50C | 1292 | ROUTERERR_FRAGMENTTIMEOUT |  |
0x50D | 1293 | ROUTERERR_TOBEREMOVED |  |

General ADS Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x700 | 1792 | error class <device error> |  |
0x701 | 1793 | Service is not supported by server |  |
0x702 | 1794 | invalid index group |  |
0x703 | 1795 | invalid index offset |  |
0x704 | 1796 | reading/writing not permitted |  |
0x705 | 1797 | parameter size not correct |  |
0x706 | 1798 | invalid parameter value(s) |  |
0x707 | 1799 | device is not in a ready state |  |
0x708 | 1800 | device is busy |  |
0x709 | 1801 | invalid context (must be in Windows) |  |
0x70A | 1802 | out of memory |  |
0x70B | 1803 | invalid parameter value(s) |  |
0x70C | 1804 | not found (files, ...) |  |
0x70D | 1805 | syntax error in command or file |  |
0x70E | 1806 | objects do not match |  |
0x70F | 1807 | object already exists |  |
0x710 | 1808 | symbol not found |  |
0x711 | 1809 | symbol version invalid | Onlinechange | Release handle and get a new one
0x712 | 1810 | server is in invalid state |  |
0x713 | 1811 | AdsTransMode not supported |  |
0x714 | 1812 | Notification handle is invalid | Onlinechange | Release handle and get a new one
0x715 | 1813 | Notification client not registered |  |
0x716 | 1814 | no more notification handles |  |
0x717 | 1815 | size for watch too big |  |
0x718 | 1816 | device not initialized |  |
0x719 | 1817 | device has a timeout |  |
0x71A | 1818 | query interface failed |  |
0x71B | 1819 | wrong interface required |  |
0x71C | 1820 | class ID is invalid |  |
0x71D | 1821 | object ID is invalid |  |
0x71E | 1822 | request is pending |  |
0x71F | 1823 | request is aborted |  |
0x720 | 1824 | signal warning |  |
0x721 | 1825 | invalid array index |  |
0x722 | 1826 | symbol not active | Onlinechange | Release handle and get a new one
0x723 | 1827 | access denied |  |
0x724 | 1828 | missing license |  | Activate license for TwinCAT 3 function
0x72c | 1836 | exception occured during system start |  | Check each device transistions
0x740 | 1856 | Error class <client error> |  |
0x741 | 1857 | invalid parameter at service |  |
0x742 | 1858 | polling list is empty |  |
0x743 | 1859 | var connection already in use |  |
0x744 | 1860 | invoke ID in use |  |
0x745 | 1861 | timeout elapsed |  | Check ADS routes of sender and receiver and your firewall setting
0x746 | 1862 | error in win32 subsystem |  |
0x747 | 1863 | Invalid client timeout value |  |
0x748 | 1864 | ads-port not opened |  |
0x750 | 1872 | internal error in ads sync |  |
0x751 | 1873 | hash table overflow |  |
0x752 | 1874 | key not found in hash |  |
0x753 | 1875 | no more symbols in cache |  |
0x754 | 1876 | invalid response received |  |
0x755 | 1877 | sync port is locked |  |

RTime Error Codes

Hex | Dec | Description | Possible Causes
0x1000 | 4096 | RTERR_INTERNAL | Internal fatal error in the TwinCAT real-time system
0x1001 | 4097 | RTERR_BADTIMERPERIODS | Timer value not vaild
0x1002 | 4098 | RTERR_INVALIDTASKPTR | Task pointer has the invalid value ZERO
0x1003 | 4099 | RTERR_INVALIDSTACKPTR | Task stack pointer has the invalid value ZERO
0x1004 | 4100 | RTERR_PRIOEXISTS | The demand task priority is already assigned
0x1005 | 4101 | RTERR_NOMORETCB | No more free TCB (Task Control Block) available. Maximum number of TCBs is 64
0x1006 | 4102 | RTERR_NOMORESEMAS | No more free semaphores available. Maximum number of semaphores is 64
0x1007 | 4103 | RTERR_NOMOREQUEUES | No more free queue available. Maximum number of queue is 64
0x1008 | 4104 | TwinCAT reserved. |
0x1009 | 4105 | TwinCAT reserved. |
0x100A | 4106 | TwinCAT reserved. |
0x100B | 4107 | TwinCAT reserved. |
0x100C | 4108 | TwinCAT reserved. |
0x100D | 4109 | RTERR_EXTIRQALREADYDEF | An external synchronisation interrupt is already applied
0x100E | 4110 | RTERR_EXTIRQNOTDEF | No external synchronsiation interrupt applied
0x100F | 4111 | RTERR_EXTIRQINSTALLFAILED | The apply of the external synchronisation interrupt failed
0x1010 | 4112 | RTERR_IRQLNOTLESSOREQUAL | Call of a service function in the wrong context
0x1017 | 4119 | RTERR_VMXNOTSUPPORTED | Intel VT-x extension is not supported.
0x1018 | 4120 | RTERR_VMXDISABLED | Intel VT-x extension is not enabled in BIOS.
0x1019 | 4121 | RTERR_VMXCONTROLSMISSING | Missing feature in Intel VT-x extension.
0x101A | 4122 | RTERR_VMXENABLEFAILS | Enabling Intel VT-x fails.

TCP Winsock Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x274c | 10060 | A socket operation was attempted to an unreachable host | Host unreachable | Check network connection via ping
0x274d | 10061 | A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. | Host unreachable | Check network connection via ping
0x2751 | 10065 | No connection could be made because the target machine actively refused it |  |
 |  | Further Winsock error codes: Win32 Error Codes |  |


AdsGetDllVersion

Returns the version number, revision number and build number of the ADS-DLL.

LONG AdsGetDllVersion(
  void
);

Parameter

-

Return value

The return value, which is of type long, contains in coded form these three items related to the ADS-DLL.

Example

See example 1.


AdsPortOpen

Establishes a connection (communication port) to the TwinCAT message router.

LONG AdsPortOpen(
  void
);

Parameter

-

Return value

A port number that has been assigned to the program by the ADS router is returned.

Example

See example 2.


AdsPortClose

The connection (communication port) to the TwinCAT message router is closed.

LONG AdsPortClose(
  void
);

Parameter

-

Return value

Returns the function's error status.

Example

See example 2.


AdsGetLocalAddress

Returns the local NetId and port number.

LONG AdsGetLocalAddress(
  PAmsAddr     pAddr
);

Parameter

pAddr

[out] Pointer to the structure of type AmsAddr.

Return value

Returns the function's error status.

Example

See example 2.


AdsSyncWriteReq

Writes data synchronously to an ADS device.

LONG AdsSyncWriteReq(
  PAmsAddr    pAddr,
  ULONG       nIndexGroup,
  ULONG       nIndexOffset,
  ULONG       nLength,
  PVOID       pData
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Length of the data, in bytes, written to the ADS server.

pData

[in] Pointer to the data written to the ADS server.

Return value

Returns the function's error status.

Example

See example 2.


AdsSyncReadReq

Reads data synchronously from an ADS server.

LONG AdsSyncReadReq(
  PAmsAddr  pAddr,
  ULONG     nIndexGroup,
  ULONG     nIndexOffset,
  ULONG     nLength,
  PVOID     pData
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Length of the data in bytes.

pData

[out] Pointer to a data buffer that will receive the data.

Return value

Returns the function's error status.

Example

See example 3.


AdsSyncReadReqEx

Reads data synchronously from an ADS server.

LONG AdsSyncReadReq(
  PAmsAddr  pAddr,
  ULONG     nIndexGroup,
  ULONG     nIndexOffset,
  ULONG     nLength,
  PVOID     pData,
  ULONG*    pcbReturn
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Length of the data in bytes.

pData

[out] Pointer to a data buffer that will receive the data.
pcbReturn
[out] Pointer to a variable. This variable returns the number of succesfully read data bytes.

Return value

Returns the function's error status.


AdsSyncReadWriteReq

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReq(
  PAmsAddr      pAddr,
  ULONG         nIndexGroup,
  ULONG         nIndexOffset,
  ULONG         nReadLength,
  PVOID         pReadData,
  ULONG         nWriteLength,
  PVOID         pWriteData
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Length of the data, in bytes, returned by the ADS device.

pReadData

[out] Buffer with data returned by the ADS device.

nWriteLength

[in] Length of the data, in bytes, written to the ADS device.

pWriteData

[out] Buffer with data written to the ADS device.

Return value

Returns the function's error status.

Example

See example 7.


AdsSyncReadWriteReqEx

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReq(
  PAmsAddr      pAddr,
  ULONG         nIndexGroup,
  ULONG         nIndexOffset,
  ULONG         nReadLength,
  PVOID         pReadData,
  ULONG         nWriteLength,
  PVOID         pWriteData,
  ULONG*        pcbReturn
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Length of the data, in bytes, returned by the ADS device.

pReadData

[out] Buffer with data returned by the ADS device.

nWriteLength

[in] Length of the data, in bytes, written to the ADS device.

pWriteData

[out] Buffer with data written to the ADS device.
pcbReturn
[out] Pointer to a variable. This variable returns the number of succesfully read data bytes.

Return value

Returns the function's error status.


AdsSyncReadDeviceInfoReq

Reads the identification and version number of an ADS server.

LONG AdsSyncReadDeviceInfoReq(
  PAmsAddr        pAddr,
  PCHAR           pDevName,
  PAdsVersion     pVersion
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

pDevName

[out] Pointer to a character string that will receive the name of the ADS device.

pVersion

[out] Address of a variable of type AdsVersion, which will receive the version number, revision number and the build number.

Return value

Returns the function's error status.

Example

See example 5.


AdsSyncWriteControlReq

Changes the ADS status and the device status of an ADS server.

LONG AdsSyncWriteControlReq(
  PAmsAddr      pAddr,
  USHORT        nAdsState,
  USHORT        nDeviceState,
  ULONG         nLength,
  PVOID         pData
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nAdsState

[in] New ADS status.

nDeviceState

[in] New device status.

nLength

[in] Length of the data in bytes.

pData

[in] Pointer to data sent additionally to the ADS device.

Return value

Returns the function's error status.

Comments

In addition to changing the ADS status and the device status, it is also possible to send data to the ADS server in order to transfer further information. In the current ADS devices (PLC, NC, ...) this data has no further effect. Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.

Example

See example 6.


AdsSyncReadStateReq

Reads the ADS status and the device status from an ADS server.

LONG AdsSyncReadStateReq(
  PAmsAddr  pAddr,
  USHORT    *pAdsState,
  PUSHORT   pDeviceState
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

pAdsState

[out] Address of a variable that will receive the ADS status (see data type ADSSTATE).

pDeviceState

[out] Address of a variable that will receive the device status.

Return value

Returns the function's error status.

Remarks

Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.

Example 11 illustrates how the change can be detected with the aid of a callback function.

Example

See example 4.


AdsSyncAddDeviceNotificationReq

A notification is defined within an ADS server (e.g. PLC). When a certain event occurs a function (the callback function) is invoked in the ADS client (C program).

LONG AdsSyncAddDeviceNotificationReq(
  PAmsAddr                 pAddr,
  ULONG                    nIndexGroup,
  ULONG                    nIndexOffset,
  PAdsNotificationAttrib   pNoteAttrib,
  PAdsNotificationFuncEx   pNoteFunc,
  ULONG                    hUser,
  PULONG                   pNotification
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] IndexGroup.

nIndexOffset

[in] IndexOffset.

pNoteAttrib

[in] Pointer to the structure that contains further information.

pNoteFunc

[in] Name of the callback function.

hUser

[in] 32-bit value that is passed to the callback function.

pNotification

[out] Address of the variable that will receive the handle of the notification.

Return value

Returns the function's error status.

Limitation:

Per ADS-Port a limitted number of 550 notifications are available.

Remarks

Example

See example 8.


AdsSyncDelDeviceNotificationReq

A notification defined previously is deleted from an ADS server.

LONG AdsSyncDelDeviceNotificationReq(
  PAmsAddr       pAddr,
  ULONG          hNotification
);

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server.

hNotification

[out] Address of the variable that contains the handle of the notification.

Return value

Returns the function's error status.

Example

See example 8.


AdsSyncSetTimeout

Alters the timeout for the ADS functions. The standard value is 5000 ms.

LONG AdsSyncSetTimeout(
  LONG           nMs
);

Parameter

nMs

[in] Timeout in ms.

Return value

Returns the function's error status.

Example

-


AdsAmsRegisterRouterNotification

The AdsAmsRegisterNotificationReq() function can be used to detect a change in the status of the TwinCAT router. The given callback function is invoked each time the status changes. Monitoring of the router's status is ended once more by the AdsAmsUnRegisterNotification() function.

LONG AdsAmsRegisterRouterNotification(
    PAmsRouterNotificationFuncEx   pNoteFunc );

Parameter

pNoteFunc

[in] Name of the callback function

Return value

Returns the function's error status.

Hints:

  • Implemented from TcAdsDLL File Version: 2.8.0.21 ( delivered with TwinCAT 2.9 Build > 941).
  • A connection to the TwinCAT-Router can be done, if TwinCAT has been installed on the local PC. The function delivers an error on a system without TwinCAT.

Example

-


AdsAmsUnRegisterRouterNotification

Monitoring the router's status is ended by the AdsAmsUnRegisterNotification() function. See also AdsAmsRegisterNotificationReq().

LONG AdsAmsUnRegisterRouterNotification( void );

Parameter

-

Return value

Returns the function's error status.

Hints:

  • Implemented from TcAdsDLL File Version: 2.8.0.21 ( delivered with TwinCAT 2.9 Build > 941).
  • A connection to the TwinCAT-Router can be done, if TwinCAT has been installed on the local PC. The function delivers an error on a system without TwinCAT.

Example

-


PAmsRouterNotificationFuncEx

Type definition of the callback function required by the AdsAmsRegisterRouterNotification function.

typedef void  ( __stdcall *PAmsRouterNotificationFuncEx)( long nEvent );


PAdsNotificationFuncEx

Type definition of the callback function required by the AdsSyncAddDeviceNotificationReq function.

typedef void (__stdcall *PAdsNotificationFuncEx)(AmsAddr* pAddr, AdsNotificationHeader* pNotification, unsigned long hUser );


Overview

TwinCAT TcAdsDll

Extended functions (for multithreaded applications)

With the existing functions only one ADS port could be created for each process. Particularly for multithreaded applications this is not sufficient, since the individual Ads commands would block each other. With the new functions it is now possible to use more than one port. This would enable a separate ADS port to be used for each thread, for example. New ports can be opened via the AdsPortOpenEx function. The returned port number is then transferred as parameter to the individual sync functions.


AdsPortOpenEx

Establishes a connection (communication port) to the TwinCAT message router. Unlike with AdsPortOpen, a new ADS port is opened each time. The extended Ads functions have to be used for communicating with this port. The port number returned by AdsPortOpenEx is transferred as parameter to these functions. If no TwinCAT MessageRouter is present, the AdsPortOpenEx function will fail.

LONG AdsPortOpenEx(
  void
);

Parameters

-

Return value

Port number of the opened Ads port. A return value of 0 means the call has failed.

Example

See example 2.


AdsPortCloseEx

The connection (communication port) to the TwinCAT message router is closed. The port to be closed must previously have been opened via an AdsPortOpenEx call.

LONG AdsPortCloseEx(
  long nPort
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx.

Return value

Returns the function's error status.

Example

See example 2.


AdsGetLocalAddressEx

Returns the local NetId and port number.

LONG AdsGetLocalAddressEx(
  long         port
  PAmsAddr     pAddr
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[out] Pointer to the structure of type AmsAddr.

Return value

Returns the function's error status.

Example

See example 2.


AdsSyncWriteReqEx

Writes data synchronously to an ADS device.

LONG AdsSyncWriteReqEx(
  LONG        port,
  PAmsAddr    pAddr,
  ULONG       nIndexGroup,
  ULONG       nIndexOffset,
  ULONG       nLength,
  PVOID       pData
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Length of the data, in bytes, written to the ADS server.

pData

[in] Pointer to the data written to the ADS server.

Return value

Returns the function's error status.

Example

See example 2.


AdsSyncReadReqEx2

Reads data synchronously from an ADS server.

LONG AdsSyncReadReqEx2(
  LONG      port,
  PAmsAddr  pAddr,
  ULONG     nIndexGroup,
  ULONG     nIndexOffset,
  ULONG     nLength,
  PVOID     pData,
  ULONG*    pcbReturn
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Length of the data in bytes.

pData

[out] Pointer to a data buffer that will receive the data.

pcbReturn

[out] pointer to a variable. If successful, this variable will return the number of actually read data bytes.

Return value

Returns the function's error status.


AdsSyncReadWriteReqEx2

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReqEx2(
  LONG          port,
  PAmsAddr      pAddr,
  ULONG         nIndexGroup,
  ULONG         nIndexOffset,
  ULONG         nReadLength,
  PVOID         pReadData,
  ULONG         nWriteLength,
  PVOID         pWriteData,
  ULONG*        pcbReturn
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Length of the data, in bytes, returned by the ADS device.

pReadData

[out] Buffer with data returned by the ADS device.

nWriteLength

[in] Length of the data, in bytes, written to the ADS device.

pWriteData

[out] Buffer with data written to the ADS device.
pcbReturn

[out] pointer to a variable. If successful, this variable will return the number of actually read data bytes.

Return value

Returns the function's error status.


AdsSyncReadDeviceInfoReqEx

Reads the identification and version number of an ADS server.

LONG AdsSyncReadDeviceInfoReqEx(
  LONG         	port,
  PAmsAddr        pAddr,
  PCHAR           pDevName,
  PAdsVersion     pVersion
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

pDevName

[out] Pointer to a character string that will receive the name of the ADS device.

pVersion

[out] Address of a variable of type AdsVersion, which will receive the version number, revision number and the build number.

Return value

Returns the function's error status.

Example

See example 5.


AdsSyncWriteControlReqEx

Changes the ADS status and the device status of an ADS server.

LONG AdsSyncWriteControlReqEx(
  LONG          port,
  PAmsAddr      pAddr,
  USHORT        nAdsState,
  USHORT        nDeviceState,
  ULONG         nLength,
  PVOID         pData
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

nAdsState

[in] New ADS status.

nDeviceState

[in] New device status.

nLength

[in] Length of the data in bytes.

pData

[in] Pointer to data sent additionally to the ADS device.

Return value

Returns the function's error status.

Comments

In addition to changing the ADS status and the device status, it is also possible to send data to the ADS server in order to transfer further information. In the current ADS devices (PLC, NC, ...) this data has no further effect. Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.

Example

See example 6.


AdsSyncReadStateReqEx

Reads the ADS status and the device status from an ADS server.

LONG AdsSyncReadStateReqEx(
  LONG      port,
  PAmsAddr  pAddr,
  USHORT    *pAdsState,
  PUSHORT   pDeviceState
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

pAdsState

[out] Address of a variable that will receive the ADS status (see data type ADSSTATE).

pDeviceState

[out] Address of a variable that will receive the device status.

Return value

Returns the function's error status.

Remarks

Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.
Example 11 illustrates how the change can be detected with the aid of a callback function.

Example

See example 4.


AdsSyncAddDeviceNotificationReqEx

A notification is defined within an ADS server (e.g. PLC). When a certain event occurs a function (the callback function) is invoked in the ADS client (C program).

LONG AdsSyncAddDeviceNotificationReqEx(
  LONG     	         port,
  PAmsAddr                 pAddr,
  ULONG                    nIndexGroup,
  ULONG                    nIndexOffset,
  PAdsNotificationAttrib   pNoteAttrib,
  PAdsNotificationFuncEx   pNoteFunc,
  ULONG                    hUser,
  PULONG                   pNotification
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

nIndexGroup

[in] IndexGroup.

nIndexOffset

[in] IndexOffset.

pNoteAttrib

[in] Pointer to the structure that contains further information.

pNoteFunc

[in] Name of the callback function.

hUser

[in] 32-bit value that is passed to the callback function.

pNotification

[out] Address of the variable that will receive the handle of the notification.

Return value

Returns the function's error status.

Limitation:

Per ADS-Port a limited number of 550 notifications are available.

Remarks

If the TwinCAT router is stopped and then started again, the notifications become invalid. You can trap this event with the AdsAmsRegisterRouterNotification() function.

Example

See example 8.


AdsSyncDelDeviceNotificationReqEx

A notification defined previously is deleted from an ADS server.

LONG AdsSyncDelDeviceNotificationReqEx(
  LONG           port,
  PAmsAddr       pAddr,
  ULONG          hNotification
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pAddr

[in] Structure with NetId and port number of the ADS server.

hNotification

[out] Address of the variable that contains the handle of the notification.

Return value

Returns the function's error status.

Example

See example 8.


AdsSyncSetTimeoutEx

Alters the timeout for the ADS functions. The standard value is 5000 ms.

LONG AdsSyncSetTimeoutEx(
  LONG           port,
  LONG           nMs
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

nMs

[in] Timeout in ms.

Return value

Returns the function's error status.

Example

-


AdsSyncGetTimeoutEx

Returns the configured timeout for the ADS functions. The standard value is 5000 ms.

LONG AdsSyncGetTimeoutEx(
  LONG           port,
  LONG*          pnMs
);

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pnMs

[out] Buffer to store timeout value in ms.

Return value

Returns the function's error status.

Example

-


AdsAmsPortEnabledEx

Returns status of the ADS client connection.

LONG AdsAmsPortEnabledEx(
  LONG           nPort,
  BOOL*          pbEnabled
);

Parameters

nPort

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen.

pbEnabled

[out] buffer to store status value.

Return value

Returns the function's error status.

Example

-


AmsAddr

The complete address of an ADS device can be stored in this structure.

typedef struct {
  AmsNetId        netId;
  USHORT          port;
} AmsAddr, *PAmsAddr;

Elements

NetId

NetId.

port

Port number.


AmsNetId

The NetId of and ADS device can be represented in this structure.

typedef struct {
  UCHAR        b[6];
} AmsNetId, *PAmsNetId;

Elements

b[6]

NetId, consisting of 6 digits.

Comment

The structure consists of an array with 6 elements of type UCHAR. Each element in the array may adopt a value from 1 to 255. The NetId is set with the aid of the TwinCAT system service.


AdsVersion

The structure contains the version number, revision number and build number.

typedef struct {
  UCHAR           version;
  UCHAR           revision;
  USHORT          build;
} AdsVersion, *PAdsVersion;

Elements

version

Version number.

revision

Revision number.

build

Build number.


AdsNotificationAttrib

This structure contains all the attributes for the definition of a notification.

typedef struct {
  ULONG           cbLength;
  ADSTRANSMODE    nTransMode;
  ULONG           nMaxDelay;
  ULONG           nCycleTime;
} AdsNotificationAttrib, *PAdsNotificationAttrib;

Elements

cbLength

Length of the data that is to be passed to the callback function.

nTransMode

ADSTRANS_SERVERCYCLE: The notification's callback function is invoked cyclically.

ADSTRANS_SERVERONCHA: The notification's callback function is only invoked when the value changes.

nMaxDelay

The notification's callback function is invoked at the latest when this time has elapsed. The unit is 100 ns.

nCycleTime

The ADS server checks whether the variable has changed after this time interval. The unit is 100 ns.

Remarks

The ADS DLL is buffered from the real time transmission by a FIFO. TwinCAT first writes every value that is to be transmitted by means of the callback function into the FIFO. If the buffer is full, or if the nMaxDelay time has elapsed, then the callback function is invoked for each entry. The nTransMode parameter affects this process as follows:

ADSTRANS_SERVERCYCLE
The value is written cyclically into the FIFO at intervals of nCycleTime. The smallest possible value for nCycleTime is the cycle time of the ADS server; for the PLC, this is the task cycle time. The cycle time can be handled in 1ms steps. If you enter a cycle time of 0 ms, then the value is written into the FIFO with every task cycle.

ADSTRANS_SERVERONCHA
A value is only written into the FIFO if it has changed. The real-time sampling is executed in the time given in nCycleTime. The cycle time can be handled in 1ms steps. If you enter 0 ms as the cycle time, the variable is written into the FIFO every time it changes.

Warning: Too many read operations can load the system so heavily that the user interface becomes much slower.

Tip: Set the cycle time to the most appropriate values, and always close connections when they are no longer required.


AdsNotificationHeader

This structure is also passed to the callback function.

typedef struct {
  ULONG           hNotification;
  __int64         nTimeStamp;
  ULONG           cbSampleSize;
  UCHAR           data[ANYSIZE_ARRAY];
} AdsNotificationHeader, *PAdsNotificationHeader;

Elements

hNotification

Handle for the notification. Is specified when the notification is defined;

nTimeStamp

Time stamp in FILETIME format.

cbSampleSize

Number of bytes transferred.

data[ANY_SIZE_ARRAY]

Array with the transferred data.

Comment

The time stamp is transferred in the FILETIME format. FILETIME is a 64-bit variable, representing the time and date in 100 ns steps, starting from 01.01.1601. Local time shift is not considered; coordinated universal time (UTC) is used. If you want access to the individual elements (day, month, year, hour, minute, second) you need to convert the time stamp from the FILETIME format to the SYSTEMTIME format, and then calculate the time, taking local time shifts into account.

Example

See example 8.


ADSSTATE

typedef enum nAdsState {
 ADSSTATE_INVALID		= 0,
 ADSSTATE_IDLE		= 1,
 ADSSTATE_RESET		= 2,
 ADSSTATE_INIT		= 3,
 ADSSTATE_START		= 4,
 ADSSTATE_RUN		= 5,
 ADSSTATE_STOP		= 6,
 ADSSTATE_SAVECFG		= 7,
 ADSSTATE_LOADCFG		= 8,
 ADSSTATE_POWERFAILURE	= 9,
 ADSSTATE_POWERGOOD	= 10,
 ADSSTATE_ERROR		= 11,
 ADSSTATE_SHUTDOWN 	= 12,
 ADSSTATE_SUSPEND 	= 13,
 ADSSTATE_RESUME 		= 14,
 ADSSTATE_CONFIG 		= 15, // system is in config mode
 ADSSTATE_RECONFIG 	= 16, // system should restart in config mode
 ADSSTATE_MAXSTATES
} ADSSTATE;


ADSTRANSMODE

typedef enum nAdsTransMode {
  ADSTRANS_NOTRANS		= 0,
  ADSTRANS_CLIENTCYCLE	= 1,
  ADSTRANS_CLIENT1REQ	= 2,
  ADSTRANS_SERVERCYCLE	= 3,
  ADSTRANS_SERVERONCHA	= 4
} ADSTRANSMODE;


COM Overview

TwinCAT TcAdsDll: COM Overview

Overview

The TcAdsDll provides functions for communication with other ADS devices via the TwinCAT router through it's COM interface. You will find further information related to ADS under TwinCAT ADS.

The COM Class TcClient provides the user programs to establish a connection to ADS device to the local PC or to remote PC's. The TcAdsDll provides a multi-threaded threading model. It can be used by multi-threaded and single-threaded COM clients. If the TcAdsDll is used by single-threaded clients the method calls a synchronized by a marshaler. The marhsaler is compiled into the TcAdsDll. No additional proxy-stub-dll is needed.

The TcClient returns for each connection to one particular ADS device an object of the Type TcAdsSync. This class provides synchronous ADS communication to the ADS device. The Class TcAdsSync provides the communication function through the default interface ITcAdsSync. To receive Ads Notification from the TcAdsSync object the user program has to implement and connect the Event Interface ITcAdsSyncEvent.


CoClasses

TwinCAT Object Server: CoClasses

TcAdsDll::Classes

The TcAdsDll provides interface to the outside by COM (Component Object Model).

CoClasses | Description
TcClient | The Main class of the TcAdsDll. Provides a class factory to establish a ADS client connection


TcClient

The TcClient object provides a class factory to establish a ADS client connection.

Interface | Description
ITcClient | Interface provides a class factory


TcAdsSync

The TcAdsSync object provides ADS communication to an ADS device. The TcAdsSync object has no class factory and can just be created by an call.

to ITcClient::Connect

Interface | Description
ITcAdsSync | Interface that provides the Ads communication functions.


ITcClient

The ITcClient interface provides a class factory to create an object to communicate with one Ads device. The interface derives from IUnknown.

IUnknown Methods | Description
QueryInterface | Returns a pointer to the interface you query for
AddRef | Increments the reference counter
Release | Decrements the reference counter

ITcClient Methodes | Description
Connect | Creates an object of the type ITcAdsSync that provides Ads synchronous communication to one particular ADS device.

Remarks


ITcClient::Connect

Creates a new Ads Client communication object for one particular Ads device by given AdsNet Id and Port Number.

HRESULT Connect(AmsNetId* pAmsNetId, long nPort, ITcAdsSync** pipTcAdsSync);

Parameters

pAmsNetId
[in] variable presents the Ams Net Id by the structure type AmsNetId. If the Net Id is set to 0.0.0.0.0.0 the connection is made to the local TwinCAT system. If the client PC has no TwinCAT system installed the connection uses TCP/IP. The limitation on TCP/IP is that the client can just establish connections to the main remote device with the AMS Net Is = TCP/IP address + 1.1. .
nPort
[in] The Ads Port number of the Ads device we want to communicate with.
ITcAdsSync
[out, retval] Returns a pointer to an ITcAdsSync pointer that holds the object that is used for Ads communication.

Return Values

S_OK
The connect function was successfully called.
ADSERRORCODES
An error occurs

Remarks

To establish a connection to remote TwinCAT Systems, the remote device has to be added to the list of Remote Computer on the TwinCAT system. If on client PC and remote PC a TwinCAT system is installed, the client PC has to be added to the list of remote computer on the remote PC and vice versa. If the client PC does not have a TwinCAT system installed the client PC has just to be added to the list of remote computers on the remote PC.
If the Client PC has no TwinCAT system the AMS Net Id is just the TCP/IP address + 1.1. .


ITcAdsSync

The ITcClient interface provides a client the functionality to communicate to ads device. The interface derives from IUnknown.

IUnknown Methods | Description
QueryInterface | Returns a pointer to the interface you query for
AddRef | Increments the reference counter
Release | Decrements the reference counter

ITcAdsSync Methodes and Properties | Description
Write | Writes a value to a variable as byte stream in an Ads device.
Read | Reads the value of a variable as byte stream from an Ads device.
ReadWrite | Writes a value to an Ads device and reads back the result in one step.
WriteControl | Writes a control command to an Ads device.
AddDeviceNotification | Connects a variable to the client. The client will be notified by an event.
DelDeviceNotification | Removes the connection of a variable.
ReadDeviceInfo | Reads Device Information from an Ads device.
ReadState | Reads the state from an Ads device.
Timeout | Sets the time after which the client will get a timeout warning on all other Ads commands

Remarks


ITcAdsSync::Write

This method writes a value to a variable in an ADS device as byte stream

HRESULT Write(indexGroup, indexOffset, cbLen, pData);

Parameters

indexGroup
[in] A variable of the type long that holds the index group of the variable we want to write to.
indexOffset
[in] A variable of the type long that holds the index offset of the variable we want to write to.
cbLen
[in] Count of byte we want to write to the variable.
pData
[in, size_is(cbLen)] A pointer to the first element of a byte array with the length cbLen of the data we want to write to a variable in an Ads device.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::Read

This method reads a value of a variable from an ADS device as byte stream

HRESULT Read(long indexGroup, long indexOffset, long cbLen, long* pcbRead, [out, size_is(cbLen), length_is(*pcbRead)] byte* pData);

Parameters

indexGroup
[in] A variable of the type long that holds the index group of the variable we want to read.
indexOffset
[in] A variable of the type long that holds the index offset of the variable we want to read.
cbLen
[in] Count of byte we want to read from the variable.
pcbRead
[out] Pointer to a variable the returns the count of bytes we really had read.
pData
[out, size_is(cbLen), length_is(*pcbRead)] A pointer to the first element of a byte array with the length cbLen of the data we want to read from a variable in a Ads device.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::ReadWrite

This method writes a value to an ADS device and receive back the data device in one call.

HRESULT ReadWrite(long indexGroup, long indexOffset, long cbRdLen, long* pcbRead, byte* pRdData, [in] long cbWrLen, [in, size_is(cbWrLen)] byte* pWrData);

Parameters

indexGroup
[in] A variable of the type long that holds the index group of the variable we want to read.
indexOffset
[in] A variable of the type long that holds the index offset of the variable we want to read.
cbRdLen
[in] Count of byte we want to read from the variable.
pcbRead
[out] Pointer to a variable the returns the count of bytes we really had read.
pRdData
[out, size_is(cbRdLen), length_is(*pcbRead)] A pointer to the first element of a byte array with the length cbRdLen of the data we want to read from a variable in an Ads device.
cbWrLen
[in] Count of byte we want to write to the variable.
pWrData
[in, size_is(pWrData)] A pointer to the first element of a byte array with the length cbWrLen of the data we want to write to a variable in an Ads device.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::WriteControl

This method sets the state of the ADS system an devices

HRESULT WriteControl(ADSSTATE adsState, ADSSTATE deviceState, long cbLen, byte* pData);

Parameters

adsState
[in] The states as ADSSTATE we want to set onto the ADS system.
deviceState
[in] The states as ADSSTATE we want to set onto the ADS device.
cbLen
[in] Count of byte we want to write to the variable.
pData
[in, size_is(cbLen)] A pointer to the first element of a byte array with the length cbLen of additional the data we want to write to the Ads device.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::AddDeviceNotification

Connects a variable to the client. The client will be notified by a event.

HRESULT AddDeviceNotification(long indexGroup, long indexOffset,
long cbLenData, ADSTRANSMODE transMode,
long nMaxDelay, long nCycleTime, long* phNotification);

Parameters

indexGroup
[in] A variable of the type long that holds the index group of the variable we want to read.
indexOffset
[in] A variable of the type long that holds the index offset of the variable we want to read.
cbLenData
[in] Count of byte we want to read from the connected variable.
transMode
[out] The mode how the variable is connected with the type ADSTRANSMODE.
nMaxDelay
[in] The time with a resolution of 100 ns after we want to receive an callback on the implemented _ITcAdsSyncEvent interface.
nCycleTime
[in] The time with a resolution of 100 ns how the variable should be collected.
phNotification
[out, retval] A pointer to the handle that unique identifies the connection of our variable.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks

A nCycleTime= 10000 and nMaxDelay=100000 would receive every 10ms 10 values with the resolution of 1ms.


ITcAdsSync::DelDeviceNotification

This method removes the connection of a variable, that was connected before by an AddDeviceNotification

HRESULT DelDeviceNotification(long hNotication);

Parameters

phNotification
[in] The handle of the further established connection.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks

A nCycleTime= 10000 and nMaxDelay=100000 would receive every 10ms 10 values with the resolution of 1ms.


ITcAdsSync::ReadDeviceInfo

This method retrieves information about the Ads device.

HRESULT ReadDeviceInfo(BSTR* pName, AdsVersion* pVersion);

Parameters

pName
[out] A variable that holds the BSTR string that describes the ADS device.
pVersion
[out] A pointer to a variable of the type AdsVersion that holds the version number.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::ReadState

This method retrieves information about the ADA device State and the ADS system state.

HRESULT ReadState(ADSSTATE* pAdsState, ADSSTATE* pDeviceState);

Parameters

pAdsState
[out] Pointer to variable of the type ADSSTATE that holds the state of the ADS system.
pDeviceState
[out] Pointer to variable of the type ADSSTATE that holds the state of the ADS device.

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An error occurs

Remarks


ITcAdsSync::Timeout

This property is used to assign or retrieve the timeout value in milliseconds for all other Ads functions of the ITcAdsSync interface.

Retrieve the Timeout value

HRESULT get_Timeout(long *pTime);

Parameters

pTime
[out, retval] Pointer to a variable that holds the current timeout value

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An Error occurs

Assing a new Timeout value

HRESULT put_Timeout(long nTime);

Parameters

pTime
[in] A variable that holds the new timeout value

Return Values

S_OK
The function was successfully called
ADSERRORCODES
An Error occurs

Remarks


_ITcAdsSyncEvent

The _ITcAdsSyncEvent interface is the event Interface that a client has to implement if he wants to receive ADS Notification for connected variables. The interface derives from IUnknown.

IUnknown Methods | Description
QueryInterface | Returns a pointer to the interface you query for
AddRef | Increments the reference counter
Release | Decrements the reference counter

_ITcAdsSyncEvent Methodes | Description
DeviceNotification | This method is called from the server for all connected variables of this Ads device

Remarks


_ITcAdsSyncEvent::DeviceNotification

This method is called from the server for all connected variables of this Ads device. The Event occurs for those variables that had been connected by an AddDeviceNotification before.

HRESULT DeviceNotification([in]TimeStamp* pTime, [in] long hNotification, [in] long cbLen, [in, size_is(cbLen)]byte* pData );

Parameters

pTime
[in] A pointer to a variable of the type TimeStamp that holds the exact time when the connected variable was collected.
hNotification
[in] The handle that identifies one particular connected variable. The handle was retuned when the variable was connected by a call to method AddDeviceNotification.
cbLen
[in] Count of data bytes received by this method.
pData
[in, size_is(cbLen)]. A pointer to the first element of a byte array with the size of cbLen that contains the data of the connected variable

Return Values

S_OK
The connect function was successfully called
ADSERRORCODES
An error occurs

Remarks


TimeStamp

TwinCAT TcAdsDll: COM Error Codes

AdsVersion

The structure AdsVersion represents a version number spitted into version, revision and build number.

struct AdsVersion
{
BYTE version;
BYTE revision;
short build;
}

Remarks


AdsVersion

TwinCAT TcAdsDll: COM Error Codes

TimeStamp

The structure TimeStamp represents a windows FILETIME data structure. It is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. It is the means by which Win32 determines the date and time.

struct TimeStamp
{
long nLow;
long nHigh;
};

Remarks


ADS Error Codes

TwinCAT TcAdsDll: COM Error Codes

ADSERRORCODES

The enumeration type ADSERRORCODE describes Ads errors with the following values:

Const | Hex Value | Description
ADS_E_ERROR | 0x98117000 | this is the offset of Ads Errors presented a COM HRESULT
ADS_E_SRVNOTSUPP | 0x98117001 | the requested service is not supported by the ADS device
ADS_E_INVALIDGRP | 0x98117002 | invalided index group
ADS_E_INVALIDOFFSET | 0x98117003 | invalid index offset
ADS_E_INVALIDACCESS | 0x98117004 | reading an writing not permitted
ADSERR_DEVICE_INVALIDSIZE | 0x98117005 | parameter size is not correct
ADS_E_INVALIDDATA | 0x98117006 | invalided data value(s)
ADS_E_NOTREADY | 0x98117007 | device is not in a ready state
ADS_E_BUSY | 0x98117008 | device is busy
ADS_E_INVALIDCONTEXT | 0x98117009 | invalid context
ADS_E_NOMEMORY | 0x9811700A | out of memory
ADS_E_INVALIDPARM | 0x9811700B | invalid parameter value(s)
ADS_E_NOTFOUND | 0x9811700C | not found (files, ...)
ADS_E_SYNTAX | 0x9811700D | syntax error in command or file
ADS_E_INCOMPATIBLE | 0x9811700E | objects do not match
ADS_E_EXISTS | 0x9811700F | object already exists
ADS_E_SYMBOLNOTFOUND | 0x98117010 | symbol not found
ADS_E_SYMBOLVERSIONINVALID | 0x98117011 | symbol version invalid
ADS_E_INVALIDSTATE | 0x98117012 | server is in invalid state
ADS_E_TRANSMODENOTSUPP | 0x98117013 | AdsTransMode not supported
ADS_E_NOTIFYHNDINVALID | 0x98117014 | Notification handle is invalid
ADS_E_CLIENTUNKNOWN | 0x98117015 | Notification client not registered
ADS_E_NOMOREHDLS | 0x98117016 | no more notification handles
ADS_E_INVALIDWATCHSIZE | 0x98117017 | size for watch to big
ADS_E_NOTINIT | 0x98117018 | device not initialized
ADS_E_TIMEOUT | 0x98117019 | device has a timeout
ADS_E_NOINTERFACE | 0x9811701A | query interface failed
ADS_E_INVALIDINTERFACE | 0x9811701B | wrong interface required
ADS_E_INVALIDCLSID | 0x9811701C | class ID is invalid
ADS_E_INVALIDOBJID | 0x9811701D | object ID is invalid
ADS_E_CLIENT_ERROR | 0x98117040 | Error class: client error
ADS_E_CLIENT_INVALIDPARM | 0x98117041 | invalid parameter at service call
ADS_E_CLIENT_LISTEMPTY | 0x98117042 | polling list is empty
ADS_E_CLIENT_VARUSED | 0x98117043 | var connection already in use
ADS_E_CLIENT_DUPLINVOKEID | 0x98117044 | invoke id in use
ADS_E_CLIENT_SYNCTIMEOUT | 0x98117045 | timeout elapsed
ADS_E_CLIENT_W32ERROR | 0x98117046 | error in win32 subsystem
ADS_E_CLIENT_TIMEOUTINVALID | 0x98117047 |
ADS_E_CLIENT_PORTNOTOPEN | 0x98117048 |
ADS_E_CLIENT_NOAMSADDR | 0x98117049 |
ADS_E_CLIENT_SYNCINTERNAL | 0x98117050 | internal error in ads sync
ADS_E_CLIENT_ADDHASH | 0x98117051 | hash table overflow
ADS_E_CLIENT_REMOVEHASH | 0x98117052 | key not found in hash table
ADS_E_CLIENT_NOMORESYM | 0x98117053 | no more symbols in cache


ADSSTATE

The enumeration type ADSSTATE describes the Ads state with the following values:

Const | Int Value | Description
ADSSTATE_INVALID | 0 | Invalided state
ADSSTATE_IDLE | 1 | Idles state
ADSSTATE_RESET | 2 | Reset state
ADSSTATE_INIT | 3 | initialized
ADSSTATE_START | 4 | started
ADSSTATE_RUN | 5 | running
ADSSTATE_STOP | 6 | stopped
ADSSTATE_SAVECFG | 7 | saved configuration
ADSSTATE_LOADCFG | 8 | load configuration
ADSSTATE_POWERFAILURE | 9 | power failure
ADSSTATE_POWERGOOD | 10 | power good
ADSSTATE_ERROR | 11 | error state
ADSSTATE_SHUTDOWN | 12 | shutting down
ADSSTATE_SUSPEND | 13 | suspended
ADSSTATE_RESUME | 14 | resumed
ADSSTATE_CONFIG | 15 | system is in config mode
ADSSTATE_RECONFIG | 16 | system should restart in config mode


ADSSTATE

TwinCAT TcAdsDll: COM Error Codes

ADSTRANSMODE

The enumeration type ADSTRANSMODE describes the mode of an device notification with the following values:

Const | Int Value | Description
ADSTRANS_NOTRANS | 0 |
ADSTRANS_CLIENTCYCLE | 1 |
ADSTRANS_CLIENTONCHA | 2 |
ADSTRANS_SERVERCYCLE | 3 |
ADSTRANS_SERVERONCHA | 4 |
ADSTRANS_CLIENT1REQ | 5 |


Overview

The TcAdsDllCe enables ADS communication via Tcp/Ip on Windows CE devices.

The TcAdsDllCe supports the Pocket PC 3.0 and Handheld PC 2000 platforms on following devices

Prozessor | Installations-Dateien
StrongARM | setup\TcAdsDllCe.StrongARM.CAB
MIPS | setup\TcAdsDllCe.MIPS.CAB
Intel I486 compatible | setup\TcAdsDllCe.I486.CAB
Intel Pentium compatible | setup\TcAdsDllCe.I586.CAB

To install the TcAdsDllCe.dll on your device, you have to perform following steps:

  • Copy the appropriate TcAdsDllCe.XXX.CAB to the folder \Windows\Start Menu of your Windows CE device with the help of the Explorer and ActiveSync.
  • Start the file TcAdsDllCe.XXX.CAB from the Start Menu of your CE device.
  • Now the file can be deleted.


TcAdsDllCE Samples Übersicht

TwinCAT TcAdsDLLCe: Examples

Übersicht

Beschreibung | Quelltexte
Beispiel 1: Read the value of a SPS-Variable | AdsReadTestPPC01.exe
Beispiel 2: Write a value to a SPS-Variable | AdsWriteTestPPC01.exe
Beispiel 3: Access by variable name | AdsReadWriteTestPPC01.exe
Beispiel 4: Event driven reading | AdsDNotificTestPPC01.exe


Linking in Embedded Visual C++

To use the TcAdsDllCe in your Embedded Visual C++ project, you have to perform following steps:

  • Open Project Settings Dialog
  • Select Link Tab and insert the path of the library corresponding to your processor in the edit box Object/library modules:

- StrongArm: TwinCATDirectory\ADS Api\AdsDllCe\lib\arm\TcAdsDllCe.lib

- MIPS: StrongArm: TwinCATDirectory\ADS Api\AdsDllCe\lib\mips\TcAdsDllCe.lib

- X86: TwinCATDirectory\ADS Api\TcAdsDllCe\lib\x86\TcAdsDllCe.lib

The functions of the TcAdsDllCE.dll are compatible to those of the TcAdsDll.dll.