TagWrite
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. An error occurs 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. For important write operations, perform a TagReadEx to confirm that the write 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 sTag, STRING sValue [, INT nOffset] [, INT bSynch] [, STRING ClusterName])
sTag:
The string can refer to either: the variable tag name, the alarm name and the alarm property name, the tag name and the tag element name (Refer to Tag Extensions for more information). 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 that is "ClusterName.Tag".
sValue:
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.
nOffset:
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).
bSynch:
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 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