Using CitectSCADA > Tagging Process Variables > Tag Extensions > Reading and Writing Tags

Reading and Writing Tags

CitectSCADA represents an I/O Device variable monitored or controlled by the system as a tag variable. You create a tag variable in the Project Editor specifying the tag variable name, data type, address, deadband and other attributes. After the tag variable has been created, you can reference it using the tag name. The tag name reference provides access to the value of the tag variable.

This functionality is available to be read from a tag with a text object on a graphics page and can be read, and in some cases written to, using Cicode functions or CtAPI functions.

Tag Extensions provide the following additional functionality:

Each DataSource owns a local tag data cache. This cache is periodically saved to disk, thus, maintaining last known value (LKV) for each tag. When a DataSource is restarted its local tags are initialised to their corresponding LKVs, unless the tags have never been cached before – in which case they are initialised to the default values.

Tag data from the DataSource cache is periodically saved to disk. When the time comes to save the file, a temporary file is used, which after it is written simply gets renamed to the original file name. This is done to avoid partial master file updates or corruption. If the DataSource is shutdown abruptly, some tag value changes that are waiting to be persisted to disk may get lost. The Field data are currently saved to disk.

The Tag cache file is saved in an XML format, as shown here, preserving the necessary information about each tag’s value, quality, and timestamp. On load the original persisted quality is substituted by BadLastKnown quality value. The file is saved in the CitectSCADA Data directory using the name format of:


If during the file load the schema validation is unsuccessful, the entire file is considered invalid and the tags LKVs are lost. If during the file load a particular tag’s value, quality, or timestamp is invalid, the corresponding invalid entry is simply ignored (and logged as such). Persistence is configurable within the extended section of the CitectSCADA I/O Devices properties dialog.

Minimum Update Rate

The DataSource will send tag update value notifications to subscription clients after a pre-defined period of time expires. The configuration of the minimum update rate period is performed via the IODevice configuration dialog. Devices that are configured for redundant operation needs to have minimum update rate set according to the rules specified in the table below.

Primary Device

Minimum Update Rate Value/Staleness Period Value
Standby Device

Minimum Update Rate Value/Staleness Period Value
Compilation Result
Blank (Default) Blank (Default) OK
Blank (Default) Value Defined Error
Value Defined Blank (Default) OK
Value Defined Same value as primary OK
Value Defined Value is different than on primary Error

Stale Tag Values

When an I/O Data Consumer does not get a tag element value update from the DataSource for a specific period of time, as specified by the Staleness period, the tag element value is considered to be “stale”. The Extended Quality Substatus QUAL_EXT_STALE will indicate this condition. Processing of staleness period for tags is performed on the client side of the connection.

Configuration can be performed on the server using the IODevice properties dialog, or on the client using Citect.ini parameters.

Staleness Period

The Staleness Period represents the total number of seconds that will elapse after the last update before extended quality of the tag element is set to “Stale”. It can be configured on both the server and client. The server configuration is specified in the table above. For client configuration details refer to the ClientStalenessPeriod parameter.

Staleness Period Tolerance

Staleness Period Tolerance represents the percentage of the staleness period within a total of which time a check or stale client tag elements will be performed. The default value is 10%, which caters for a large number of configuration scenarios. You can reduce or increase the tolerance as necessary by your particular scenario by configuring this value in the client machine’s using the ClientStalenessPeriodTolerance parameter. This parameter is not available for server configuration.


In order to reduce CPU load on the client machine,the default Staleness Period Tolerance is 10%. This means that if staleness period is set to 600 seconds, a check for stale client tag elements will be performed every 60 seconds.