AdsReadVarConvertConnect
From TwinCAT 2.8 Build > 743 and above.
This method creates a fixed connection to a variable in an ADS device. The 'usrConvertType' parameter can be used to specify which data type (format) the incoming variable data should have in the event function. The 'usrConvertType' parameter is passed by value, which means that the data type passed is only used as a "template" for the conversion. During the conversion, the appropriate quantity of data bytes is copied into the data type specified by the user.
object.AdsReadVarConvertConnect(nIndexOffset As String,
nRefreshType As ADSOCXTRANSMODE,
nCycleTime As Long,
phConnectAs Long,
usrConvertType As Variant,
hUser As Variant
) As Long
Parameter
adsVarName
[in] Name of the ADS variable
nRefreshType
[in] Type of data exchange between VB variable and ADS variable (see the ADSOCXTRANSMODE data type)
nCycleTime
[in] Read cycle in ms
phConnect
[out] Contains a unique handle for the connection that has been established (this is not the handle of the ADS variable!).
usrConverType
[in] Data type into which the event data is to be converted. The following table contains a list of the supported VB data types that can be passed as parameters.
Visual Basic data type | Equal to C++ VARTYPE | Equal to PLC data type (memory use) |
|---|---|---|
Byte | VT_UI1 | BYTE (1 byte) |
Integer | VT_I2 | INT (2 bytes) and enums |
Long | VT_I4 | DINT (4 bytes) |
Single | VT_R4 | REAL (4 bytes) |
Double | VT_R8 | LREAL (8 bytes) |
String* | VT_BSTR | STRING (declared string length + null termination) |
Boolean** | VT_BOOL | BOOL (1 byte) |
Date*** | VT_DATE | DT; DATE_AND_TIME (4 bytes) |
not supported in VB | VT_UI2 | WORD; UINT (2 bytes) |
not supported in VB | VT_UI4 | DWORD; UDINT (4 bytes) |
not supported in VB | VT_I1 | SINT (1 byte) |
Variant**** | VT_VARIANT | - |
Dim varArray() As <anything of above types> | VT_ARRAY | <anything of above types> | - |
* The string length must be set to the maximum number of characters (including the closing NULL) that the string variable can adopt. (VB string length + 1 byte (for null termination)) bytes are then copied from the event data into a string variable. After this, the length of the string is then shortened to the actual length. In other words, the string is truncated at the first null character. With appropriately set string length, string arrays can also be read from the PLC. E.g.:
VAR_GLOBAL
plcStringArr : ARRAY[ 1..2 ] OF STRING(30);
END_VAR
in VB:
Dim vbStringArr( 1 To 2) As String
vbStringArr(1) = String( 31, "#")
vbStringArr(2) = String( 31, "#")
call AdsOcx1.AdsReadVarConvertConnect(".plcStringArr", ADSTRANS_SERVERONCHA, 300, hConnect, vbStringArr )
** During the conversion, one byte of event data at a time is converted to a 2-byte OleVariant data type. The following applies: TRUE when data <> 0 and FALSE when data = 0;
*** The OLE variant data type Date can only be used, for instance, to read PLC variables of type DATE_AND_TIME into a VB application. The local settings of the PC are taken into account during the conversion. Other PLC data types such as TIME or TOD are not supported, because they cannot be appropriately converted.
**** The variant variable must be initialized with a data type. VT_EMPTY or VT_NULL, for instance, are not allowed.
hUser
[in] Optional: This value is passed when the AdsReadConvertConnectUpdate() event is called.
Return value
See ADS error codes
Comments
If the connection to an ADS variable is no longer required, it should be released using the AdsDisconnectEx() method. If only certain specific values are required in a form, the connection should only be created when the form is loaded, and should be released again when the form is closed.
Note on PLC: Ensure that Symbol download is enabled in PLC Control under Project / Options / TwinCAT. You will find more detailed information in the PLC Control manual.
The method's first parameter is composed of the POE name and the PLC variable that is to be addressed. If, for instance, the variable 'SPSVar1' from the function 'Funk1' is to be accessed, then 'Funk1.SPSVar1' must be supplied as the first parameter. When global variables are being accessed, the POE name is omitted, as, for instance, in '.SPSGlobVar'. The parameter adsVarName does not distinguish between upper and lower case letters.
Note on NC: Symbol download must be enabled for each axis in the System Manager. This can be specified in the configuration dialog for the axis under General. The 'Create symbols' box must be checked. See System Manager manual.
The symbolic names of the individual NC parameters have a fixed specification, and can be found in the NC documentation.