Cicode Programming Reference > Cicode Function Categories > Tag Functions > TagGetProperty

TagGetProperty

This function reads a property of a variable tag from the data source. This function replaces TagInfo.

Syntax

STRING TagGetProperty(STRING Name, STRING Property [, INT CachedMode] [, STRING ClusterName] )

Name:

The name of the tag or the equipment and item name of a variable tag (using equipment.item notation) from which to get information. The tag can be prefixed by the name of the cluster that is "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.

Property:

The property to read. Property names are case sensitive. Supported properties are:

Address - Returns the configured address of the tag (as specified in the variable tags form).

ArraySize - Array size of the associated tag. Returns 1 for non-array types.

ClusterName - Name of the cluster the tag resides on.

DataBitWidth - Number of bits used to store the value

Description - Tag description

EngUnitsHigh - Maximum scaled value

EngUnitsLow - Minimum scaled value

Equipment - Name of the equipment associated with the Tag.

Format - Format bit string. The format information is stored in the integer as follows:

FormatDecPlaces - Number of decimal places for default format

FormatWidth - Number of characters used in default format

FullName - Full name of the tag in the form cluster.tagname.

Item - Name of the equipment item associated with the Tag. If the tag is not resolved, returns an empty string.

RangeHigh - Maximum unscaled value

RangeLow - Minimum unscaled value

TagName - Name of the tag specified.

Type - General type of tag. Allowed values are:

Units - Engineering Units for example, %, mm, Volts.

Custom1 ... Custom8 - User-defined strings.

CachedMode:

Optional parameter that specifies from where to retrieve the value for the property.

Note: When retrieving bit width ("DataBitWidth" property) or array size ("ArraySize" property) from the local configuration (iCachedMode 2), the value is related to the data structure in the device. For example, MODNET, is a 16 bit device and does not have native LONG and REAL numbers. So when you have a LONG variable, an array of 2 INTEGERS are needed to store it. In the example, the property "DataBitWidth" against the variable will return 16 and property "ArraySize" will return 2. The combination of these two return values will add up to the correct bits.

-1 - The mode is determined by the INI parameter [Client]TagReadCachedMode.

0 - The property value is retrieved direct from the server in blocking mode and an error code is returned if it is not on the server (or the server is unavailable).

Note: For the first call of TagGetProperty to return a proper value for custom fields, mode 0 needs to be specified.

1 - The property value is retrieved from the cache and an error code is returned if the cache is not loaded yet.

2 - The property value is retrieved from the local configuration and an error code is returned if it is not available (this is the traditional behaviour).

3 - The property value is retrieved from the cache, if the cache is loaded, and from the local configuration, if the cache is not loaded yet.

Default value is -1.

ClusterName:

Specifies the name of the cluster in which the Tag resides. The argument is enclosed in quotation marks.

Return Value

String representation of the property of the tag. If unsuccessful, an empty string and an error code is set.

Related Functions

AssGetProperty, AssGetScale, AssInfo, AssScaleStr, TagGetScale, TagScaleStr, TagInfo

Example

// Get the engineering full scale value for the variable "PV131"
EngFullScale = TagGetProperty("PV131", "EngUnitsHigh", 0);
// Get the cached array size for the array variable "PLC_Array"
ArrayLength = TagGetProperty("PLC_Array", "ArraySize", 1);

See Also

Tag Functions

Published June 2018