Writes to an I/O device variable by specifying the variable tag name or the variable tag name and the name of the requested element having read/write access. The variable tag needs to be defined in the Variable Tags database.
Note:For this function to be successful a user needs to be logged in.
This function completes asynchronously to the caller. It will be unsuccessful if the tag does not exist or if a write request could not be sent. This function does not test whether the write succeeded. In cases where the write does not succeed, TagWrite does not return a driver error code. You can use the TagReadEx function to confirm the write operation took place.
TagWrite should only be used when the variable tag name is a calculation such as sAlarmExt+".Paging". For assignment of variables use the assignment operator. For example, MyCluster.MyAlarm.MyProperty = MyString.
Note: When using this function and parameter [Code]ScaleCheck is set to 1, the attempt to write an out-of-range value to a device will not occur. No hardware alarm will be generated. This function checks a value before writing it to a PLC.
Syntax
TagWrite(STRING Tag, STRING sValue [, INT Offset] [, INT Synch] [, STRING ClusterName])
Tag:
A string that can be one of the following:
If the element name is not specified, the writing will be performed to the Field VQT element.
The name of the tag can be prefixed by the name of the cluster, for example, "ClusterName.Tag" or "ClusterName.Equipment.Item".
Note: If the tag name exceeds the length limit of 254 characters the hardware alarm "Tag name exceed length limit" will be raised.
Value:
The value to be written to the I/O device variable. The value is specified as a string, however if an integer or real is used the compiler will convert it to a string. The function converts the string into the correct format, and then writes it to the variable.
To write to a particular element in an array, you can enter the array name here, followed by an index to the element as follows:
"PLC_Array[9] "
The above example tells the function to write to the 10th element in the array variable PLC_Array (remember, the address of the first element in an array is 0 (zero)).
If you enter an array offset using the nOffset argument, it will be added to the index value. See example below.
Offset:
Optional offset for an array variable. Default is 0.
Note: If you enter an array index as part of the sValue argument, it will be added to this offset value. For example, TagWrite("PLC_Array[9]", 24, 4) will set the 14th element in PLC_Array to 24 (because [9] means the 10th element, and an offset of 4 means 4 elements after the 10th = element 14).
Synch:
An optional boolean argument that specifies whether the command is synchronous (blocking) or asynchronous (non- blocking). If it is specified as synchronous (blocking) the function will wait until the write has completed and returned from the server before further code execution. This parameter is "False", or asynchronous, by default. If you specify this parameter the rest of the parameters need to be explicitly specified, including nOffset which should be set as 0 if the tag is not an array tag.
ClusterName:
Specifies the name of the cluster in which the Tag resides. The argument is enclosed in quotation marks.
Return Value
0 (zero) if successful, otherwise an error code is returned.
Related Functions
TagRead, TagReadEx, IODeviceControl, IODeviceInfo
Example
TagWrite("PLC_VAR1", 123);
TagWrite("PLC_VAR1", 123, 0, TRUE); ! Write to PLC variable
! and block until write is successful.
TagWrite("PLC_VAR_STR", "string data to write");
TagWrite("PLC_ARRAY", 42, 3); ! Write to element 4 in array
TagWrite("PLC_Array[9]", 2); ! Write to element 12 in array
TagWrite ("Tag1", "123");
TagWrite("Tag1.Field", "123");
See Also
Published June 2018