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.


Beckhoff Information System - English

TwinCAT AdsToJava.dll

Introduction

The AdsToJava.dll is a library, which allows your software communicating with ADS devices.

Notice: To create a new project which uses the AdsToJava.dll the TcJavaToAds.jar needs to be added to it. Importing the de.beckhoff.jni.tcads package then allows you to use all of the provided functions, objects and constants. Additionaly, the AdsToJava.dll has to be copied to "Windows\System32".

The TcJavaToAds.jar can be found at "TwinCAT\ADS Api\AdsToJava". The AdsToJava.dll is located in the subfolder "XP" (An additional version for WinCE does exist and is located in the subfolder "CE").

The Information System provides a list of samples where the use of the AdsToJava.dll in combination with the TcJavaToAds.jar is explained. It can be found here.


Beckhoff Information System - English

TwinCAT AdsToJava.dll

Linking into Eclipse Galileo

In order to make use of the AdsToJava.dll you need to add the TcJavaToAds.jar to your Eclipse project. This article shows how to add the library and describes which imports are needed in order to make use of it (Please note that procedure can change as your Eclipse version differs from the version mentioned above):

First you need to start Eclipse and create a new project. After that navigate to the Package Explorer and right click your project and choose Properties (see picture below).

Accessing the properties window

The next step is to select the "Java Build Path" category and click the "Add External JARs..." button. In the upcoming browser you need to select the TcJavaToAds.jar. The TcJavaToAds.jar can be found at "TwinCAT\ADS Api\AdsToJava".

Adding the TcJavaToAds.jar

Finally, you need to import the libraries packages depending on which components you want to use. For further information see Java Ads samples.

   import de.beckhoff.jni.AdsConstants;
   import de.beckhoff.jni.Convert;
   import de.beckhoff.jni.JNIByteBuffer;
   import de.beckhoff.jni.JNILong;

   import de.beckhoff.jni.tcads.AdsCallDllFunction;
   import de.beckhoff.jni.tcads.AdsCallbackObject;
   import de.beckhoff.jni.tcads.AdsDevName;
   import de.beckhoff.jni.tcads.AdsNotificationAttrib;
   import de.beckhoff.jni.tcads.AdsNotificationHeader;
   import de.beckhoff.jni.tcads.AdsState;
   import de.beckhoff.jni.tcads.AdsSymbolEntry;
   import de.beckhoff.jni.tcads.AdsVersion;
   import de.beckhoff.jni.tcads.AmsAddr;
   import de.beckhoff.jni.tcads.AmsNetId;
   import de.beckhoff.jni.tcads.CallbackListenerAdsRouter;
   import de.beckhoff.jni.tcads.CallbackListenerAdsStatel;


Beckhoff Information System - English

TwinCAT AdsToJava.dll

Linking into Netbeans 6.7.1

In order to make use of the AdsToJava.dll you need to add the TcJavaToAds.jar to your Netbeans project. This article shows how to add the library and describes which imports are needed in order to make use of it (Please note that procedure can change as your Netbeans version differs from the version mentioned above):

First you need to start Netbeans and create a new project. After that navigate to the project-view and right click your project and choose Properties (see picture below).

Accessing the properties window

The next step is to select the "Libraries" category and click the "Add JAR/Folder" button. In the upcoming browser you need to select the TcJavaToAds.jar. The TcJavaToAds.jar can be found at "TwinCAT\ADS Api\AdsToJava".

Adding the TcJavaToAds.jar

Finally, you need to include the libraries packages depending on which components you want to use. For further information see Java Ads samples.

   import de.beckhoff.jni.AdsConstants;
   import de.beckhoff.jni.Convert;
   import de.beckhoff.jni.JNIByteBuffer;
   import de.beckhoff.jni.JNILong;

   import de.beckhoff.jni.tcads.AdsCallDllFunction;
   import de.beckhoff.jni.tcads.AdsCallbackObject;
   import de.beckhoff.jni.tcads.AdsDevName;
   import de.beckhoff.jni.tcads.AdsNotificationAttrib;
   import de.beckhoff.jni.tcads.AdsNotificationHeader;
   import de.beckhoff.jni.tcads.AdsState;
   import de.beckhoff.jni.tcads.AdsSymbolEntry;
   import de.beckhoff.jni.tcads.AdsVersion;
   import de.beckhoff.jni.tcads.AmsAddr;
   import de.beckhoff.jni.tcads.AmsNetId;
   import de.beckhoff.jni.tcads.CallbackListenerAdsRouter;
   import de.beckhoff.jni.tcads.CallbackListenerAdsStatel;


adsGetDllVersion

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

    AdsVersion adsGetDllVersion (
    );

Parameter

Return value

AdsVersion: Returns an AdsVersion object containing version number, revision number and build number.


adsPortOpen

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

    long adsPortOpen (
    );

Parameter

Return value

long: Returns the function's error status.


adsPortClose

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

    long adsPortClose (
    );

Parameter

Return value

long: Returns the function's error status.


adsGetLocalAddress

Returns the local NetId and port number.

    long adsGetLocalAddress (
        AmsAddr		lj_AmsAddr
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr that will contain the local NetID and port after the call.

Return value

long: Returns the function's error status.


adsSyncWriteReq

Writes data synchronously to an ADS device.

    long adsSyncWriteReq (
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_length,
        JNIByteBuffer	lj_pData
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr that contains the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_length: Length of the data in bytes.
  • JNIByteBuffer lj_pData: JNIByteBuffer that contains the data, to be written to the ADS server

Return value

long: Returns the function's error status.


adsSyncWriteReqArray

Writes data synchronously to an ADS device.

    long adsSyncWriteReqArray (
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_length,
        byte[]		lj_pData
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_length: Length of the data in bytes.
  • byte[] lj_pData: byte array that holds the data, to be written to the ADS server

Return value

long: Returns the function's error status.


adsSyncReadReq

Reads data synchronously from an ADS server.

    long adsSyncReadReq (
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_length,
        JNIByteBuffer	lj_pData
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_length: Length of the data in bytes.
  • JNIByteBuffer lj_pData: JNIByteBuffer which will contain the data after the call.

Return value

long: Returns the function's error status.


adsSyncReadReqEx

Extended function that reads data synchronously from an ADS device.

The additional JNILong-buffer will contain the amount of bytes written into the data-buffer during the call.

    long adsSyncReadReqEx (
        AmsAddr 	lj_AmsAddr,
        long 		lj_indexGroup,
        long 		lj_indexOffset,
        long 		lj_length,
        JNIByteBuffer 	lj_pData,
        JNILong 	lj_pBytesRead
    );

Parameter

  • AmsAddr: lj_AmsAddr AmsAddr object containing the port number and the NetId of the ADS server.
  • long: lj_indexGroup Index Group.
  • long: lj_indexOffset Index Offset.
  • long: lj_length Length of the data in bytes.
  • JNIByteBuffer: lj_pData JNIByteBuffer which will contain the data after the call.
  • JNILong: lj_pBytesRead Will contain the amount of bytes successfully written into the readdata-buffer during the call.

Return value

long: Returns the function's error status.


adsSyncReadWriteReq

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

    long adsSyncReadWriteReq (
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_lengthRead,
        JNIByteBuffer	lj_pDataRead,
        long		lj_lengthWrite,
        JNIByteBuffer	lj_pDataWrite
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_lengthRead: Length of the data, in bytes, returned by the ADS device.
  • JNIByteBuffer lj_pDataRead: Buffer with data returned by the ADS device.
  • long lj_lengthWrite: Length of the data, in bytes, written to the ADS device.
  • JNIByteBuffer lj_pDataWrite: Buffer with data written to the ADS device.

Return value

long: Returns the function's error status.


adsSyncReadWriteReqEx

Extended function that writes data synchronously into an ADS server and receives data back from the ADS device.

The additional JNILong-buffer will contain the amount of bytes written into the readdata-buffer during the call.

    long adsSyncReadWriteReqEx (
        AmsAddr 	lj_AmsAddr,
        long 		lj_indexGroup,
        long 		lj_indexOffset,
        long 		lj_lengthRead,
        JNIByteBuffer 	lj_pDataRead,
        long 		lj_lengthWrite,
        JNIByteBuffer 	lj_pDataWrite,
        JNILong 	lj_pBytesRead
    );

Parameter

  • AmsAddr: lj_AmsAddr AmsAddr object containing the port number and the NetId of the ADS server.
  • long: lj_indexGroup Index Group.
  • long: lj_indexOffset Index Offset.
  • long: lj_lengthRead Length of the data, in bytes, returned by the ADS device.
  • JNIByteBuffer: lj_pDataRead Buffer with data returned by the ADS device.
  • long: lj_lengthWrite Length of the data, in bytes, written to the ADS device
  • JNIByteBuffer: lj_pDataWrite Buffer with data written to the ADS device.
  • JNILong: lj_pBytesRead Will contain the amount of bytes successfully written into the readdata-buffer during the call.

Return value

long: Returns the function's error status.


adsSyncReadDeviceInfoReq

Reads the identification and version number of an ADS server.

    long adsSyncReadDeviceInfoReq (
        AmsAddr		lj_AmsAddr
        AdsDevName	lj_pDevName,
        AdsVersion	lj_pVersion
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • Object lj_pDevName: AdsDeviceName that contain the name of the ADS device after the call.
  • Object lj_pVersion: AdsVersion that will contain the version number, revision number and the build number after the call.

Return value

long: Returns the function's error status.


adsSyncWriteControlReq

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

    long adsSyncWriteControlReq (
        AmsAddr		lj_AmsAddr
        int		lj_adsState,
        int		lj_deviceState,
        long		lj_length,
        JNIByteBuffer	lj_pData
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_adsState: New ADS status.
  • long lj_deviceState: New device status.
  • long lj_length: Length of the data in bytes.
  • JNIByteBuffer lj_pData: JNIByteBuffer that holds the data sent additionally to the ADS device.

Return value

long: Returns the function's error status.

Comments

In addition to change 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.


adsSyncReadStateReq

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

    long adsSyncReadStateReq (
        AmsAddr		lj_AmsAddr
        AdsState	lj_nAdsState,
        AdsState	lj_nDeviceState
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • AdsState lj_nAdsState: AdsState that will contain the ADS status after the call.
  • AdsState lj_nDeviceState: AdsState that will contain the device status after the call.

Return value

long: Returns the function's error status.


adsSyncAddDeviceNotificationReq

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

To be able to receive events with the needed information an AdsCallbackObject has to be created and a listener has to be added. The listener has to implement the CallbackListenerAdsState interface. When a certain event occurs the callback function is invoked by the ADS client.

    long adsSyncAddDeviceNotificationReq (
        AmsAddr			lj_AmsAddr
        long			lj_indexGroup,
        long			lj_indexOffset,
        AdsNotificationAttrib	lj_pNoteAttrib,
        long			lj_hUser,
        JNILong			lj_pNotification
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • AdsNotificationAttrib lj_pNoteAttrib: AdsNotificationAttrib that contains further information.
  • long lj_hUser: User handle
  • JNILong lj_pNotification: notification handle (return value)

Return value

long: Returns the function's error status.


adsSyncDelDeviceNotificationReq

Aborts the detection of events with the specified notification.

This has no effect on the AdsCallbackObject.

    long adsSyncDelDeviceNotificationReq (
        AmsAddr		lj_AmsAddr
        JNILong		lj_hNotification
    );

Parameter

  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • JNILong lj_hNotification: notification handle

Return value

long: Returns the function's error status.


adsSyncSetTimeout

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

    long adsSyncSetTimeout (
        long		lj_nMs
    );

Parameter

  • long lj_nMs: Timeout in ms.

Return value

long: Returns the function's error status.


adsSyncGetTimeout

This function retrieves the current timeout for the ADS functions. The standard value is 5000 ms.

    long adsSyncGetTimeout (
        JNILong		lj_pMs
    );

Parameter

  • JNILong lj_pMs: Timeout-buffer

Return value

long: Returns the function's error status.


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

To be able to receive events with the needed information an AdsCallbackObject has to be created and a listener has to be added. The listener has to implement the CallbackListenerAdsRouter interface. The ADS client then invokes the specified onEvent method.

    long adsAmsRegisterRouterNotification (
    );

Parameter

Return value

long: Returns the function's error status.


adsAmsUnRegisterRouterNotification

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

To be able to receive events with the needed information an AdsCallbackObject has to be created and a listener has to be added. The listener has to implement the CallbackListenerAdsRouter interface. The Ads client then invokes the specified onEvent method.

    long adsAmsUnRegisterRouterNotification (
    );

Parameter

Return value

long: Returns the function's error status.


adsAmsPortEnabled

The adsAmsPortEnabled() function retrieves a JNIBool indicating whether or not the ADS-port is currently open.

    long adsAmsPortEnabled (
        JNIBool  		lj_pEnabled
    );

Parameter

  • JNIBool: j_pEnabled State-buffer

Return value

long: Returns the function's error status.


getAdsCallbackObject

Returns the associated AdsCallbackObject.

    AdsCallbackObject getAdsCallbackObject (
    );

Parameter

Return value

AdsCallbackObject: Returns the associated AdsCallbackObject.


Overview

TwinCAT TcAdsToJava: Reference

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 port number returned by AdsPortOpenEx is transferred as parameter to every other ADS function marked as thread-safe.

If no TwinCAT MessageRouter is present, the AdsPortOpenEx function will fail.

    long adsPortOpenEx (
    );

Parameter

Return value

long: Port number that has been assigned to the program by the ADS router is returned.


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		lj_port
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.

Return value

long: Returns the function's error status.


adsGetLocalAddressEx

Thread safe function that returns the local NetId and port number..

    long adsGetLocalAddressEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr that will contain the AmsAddress and the port after the call.

Return value

long: Returns the function's error status.


adsSyncWriteReqEx

Thread safe function that writes data synchronously to an ADS device.

    long adsSyncWriteReqEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_length,
        JNIByteBuffer	lj_pData
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_length: Length of the data in bytes.
  • JNIByteBuffer lj_pData: JNIByteBuffer that contains the data, to be written to the ADS server

Return value

long: Returns the function's error status.


adsSyncWriteReqExArray

Thread safe function that writes data synchronously to an ADS device.

    long adsSyncWriteReqExArray (
        long		lj_port
        AmsAddr		lj_AmsAddr
        long		lj_indexGroup,
        long		lj_indexOffset,
        long		lj_length,
        byte[]		lj_pData
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • long lj_length: Length of the data in bytes.
  • byte[] lj_pData: byte array that holds the data, to be written to the ADS server

Return value

long: Returns the function's error status.


adsSyncReadReqEx2

Thread safe function that reads data synchronously from an ADS device.

The additional JNILong-buffer will contain the amount of bytes written into the data-buffer during the call.

    long adsSyncReadReqEx2 (
        long		lj_port
        AmsAddr 	lj_AmsAddr,
        long 		lj_indexGroup,
        long 		lj_indexOffset,
        long 		lj_length,
        JNIByteBuffer 	lj_pData,
        JNILong 	lj_pBytesRead
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr: lj_AmsAddr AmsAddr containing the port number and the NetId of the ADS server.
  • long: lj_indexGroup Index Group.
  • long: lj_indexOffset Index Offset.
  • long: lj_length Length of the data in bytes.
  • JNIByteBuffer: lj_pData JNIByteBuffer which will contain the data after the call.
  • JNILong: lj_pBytesRead Will contain the amount of bytes successfully written into the readdata-buffer during the call.

Return value

long: Returns the function's error status.


adsSyncReadWriteReqEx2

Thread safe function that writes data synchronously into an ADS server and receives data back from the ADS device.

The additional JNILong-buffer will contain the amount of bytes written into the readdata-buffer during the call.

    long adsSyncReadWriteReqEx2 (
        long		lj_port
        AmsAddr 	lj_AmsAddr,
        long 		lj_indexGroup,
        long 		lj_indexOffset,
        long 		lj_lengthRead,
        JNIByteBuffer 	lj_pDataRead,
        long 		lj_lengthWrite,
        JNIByteBuffer 	lj_pDataWrite,
        JNILong 	lj_pBytesRead
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr: lj_AmsAddr AmsAddr object containing the port number and the NetId of the ADS server.
  • long: lj_indexGroup Index Group.
  • long: lj_indexOffset Index Offset.
  • long: lj_lengthRead Length of the data, in bytes, returned by the ADS device.
  • JNIByteBuffer: lj_pDataRead Buffer with data returned by the ADS device.
  • long: lj_lengthWrite Length of the data, in bytes, written to the ADS device
  • JNIByteBuffer: lj_pDataWrite Buffer with data written to the ADS device.
  • JNILong: lj_pBytesRead Will contain the amount of bytes successfully written into the readdata-buffer during the call.

Return value

long: Returns the function's error status.


adsSyncReadDeviceInfoReqEx

Thread safe function which reads the identification and version number of an ADS server.

    long adsSyncReadDeviceInfoReqEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
        AdsDevName	lj_pDevName,
        AdsVersion	lj_pVersion
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr containing the port number and the NetId of the ADS server.
  • AdsDevName lj_pDevName: String that will receive the name of the ADS device.
  • AdsVersion lj_pVersion: AdsVersion which, will receive the version number, revision number and the build number.

Return value

long: Returns the function's error status.


adsSyncWriteControlReqEx

Thread safe function that changes the ADS status and the device status of an ADS server to the defined values.

    long adsSyncWriteControlReqEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
        int		lj_adsState,
        int		lj_deviceState,
        long		lj_length,
        JNIByteBuffer	lj_pData
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_adsState: New ADS status.
  • long lj_deviceState: New device status.
  • long lj_length: Length of the data in bytes.
  • JNIByteBuffer lj_pData: JNIByteBuffer that holds the data additionally sent to the ADS device.

Return value

long: Returns the function's error status.

Comments

In addition to change 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.


adsSyncReadStateReqEx

Thread safe function that reads the ADS status and the device status from an ADS server.

    long adsSyncReadStateReqEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
        AdsState	lj_nAdsState,
        AdsState	lj_nDeviceState
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • AdsState lj_nAdsState: AdsState that will contain the ADS-status after the call.
  • AdsState lj_nDeviceState: AdsState that will contain the device status after the call.

Return value

long: Returns the function's error status.


adsSyncAddDeviceNotificationReqEx

Thread safe function that defines a notification within an ADS server (e.g. PLC). When a certain event occurs a function (the callback function) is invoked in the ADS client.

To be able to receive events with the needed information an AdsCallbackObject has to be created and a listener has to be added. The listener has to implement the CallbackListenerAdsState interface. When a certain event occurs the callback function is invoked by the ADS client.

    long adsSyncAddDeviceNotificationReqEx (
        long			lj_port
        AmsAddr			lj_AmsAddr
        long			lj_indexGroup,
        long			lj_indexOffset,
        AdsNotificationAttrib	lj_pNoteAttrib,
        long			lj_hUser,
        JNILong			lj_pNotification
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • long lj_indexGroup: Index Group
  • long lj_indexOffset: Index Offset
  • AdsNotificationAttrib lj_pNoteAttrib: AdsNotificationAttrib that contains further information.
  • long lj_hUser: User handle
  • JNILong lj_pNotification: notification handle (return value)

Return value

long: Returns the function's error status.


adsSyncDelDeviceNotificationReqEx

Thread safe function that deletes a previously defined notification.

This has no effect on the AdsCallbackObject.

    long adsSyncDelDeviceNotificationReqEx (
        long		lj_port
        AmsAddr		lj_AmsAddr
        JNILong		lj_hNotification
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • AmsAddr lj_AmsAddr: AmsAddr object containing the port number and the NetId of the ADS server.
  • JNILong lj_hNotification: Notification handle

Return value

long: Returns the function's error status.


adsSyncSetTimeoutEx

Thread safe function used to alter the timeout for the ADS functions. The default value is 5000 ms.

    long adsSyncSetTimeoutEx (
        long		lj_port
        long		lj_nMs
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • long lj_nMs: Timeout in ms.

Return value

long: Returns the function's error status.


adsSyncGetTimeoutEx

Thread safe function to retrieve the timeout for the ADS functions. The default value is 5000 ms.

    long adsSyncGetTimeoutEx (
        long		lj_port
        JNILong		lj_pMs
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • JNILong lj_pMs: Timeout-buffer

Return value

long: Returns the function's error status.


adsAmsPortEnabledEx

Thread safe function which indicates whether or not the ADS port lj_port is currently open.

    long adsAmsPortEnabledEx (
        long		lj_port
        JNIBool  	lj_pEnabled
    );

Parameter

  • long: lj_port Port number of an ADS port that had previously been opened with AdsPortOpenEx.
  • JNIBool: j_pEnabled State-buffer

Return value

long: Returns the function's error status.


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