All registered properties allow certain 'meta' information to be obtained about the properties themselves. This information is supplied by accessing the stock 'meta' properties whose property names are formed by appending a registered property name with the TINE stock meta property tags. Note that the meta properties do NOT explicity appear in a list of property queries! The only time a meta property would appear in a queried list is if the meta property has been 'overloaded'. That is, a server can explicity register, for example, a property "ABC.HIST" which will supercede the defacto meta property ".HIST" applied to the registered property "ABC". In this case, calls to "ABC.HIST" will be directed to the equipment module's dispatch routine.
These meta property tags include the following:
- ".EGU" returns the engineering units and set points for the associated property. This meta property supports the output formats
- CF_USTRING giving the units in the string part, the minimum and maximum set points in the float parts, the graph type in the first integer part, and the server start time (UTC) as the second integer part.
- CF_NAME16, CF_NAME32, CF_TEXT gives the units
- CF_FLOAT gives the minimum and maximum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4" or (better still) a call to GetSystemPropertyInformation() or GetDevicePropertyEGU().
- ".XEGU" returns the x-axis engineering units and set points for the associated property. An X-axis is only applicable for AT_SPECTRUM properties (i.e. a 'wave-form' spectrum or trace). Thus most properties will return '0' for the set points and an empty string for the units, if they are not registered as an AT_SPECTRUM array type. This meta property supports the output formats
- CF_USTRING giving the units in the string part, the minimum and maximum set points in the float parts, the graph type in the first integer part, and the server start time (UTC) as the second integer part.
- CF_NAME16, CF_NAME32, CF_TEXT gives the units
- CF_FLOAT gives the minimum and maximum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4".
- ".MAX" returns the registered maximum setting for the associated property. In case of spectrum type array properties, this refers to the vertical maximum setting. This value is identical to the maximum setting returned in some variations of the call to ".EGU".
- CF_FLOAT gives the maximum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4".
- ".MIN" returns the registered minimum setting for the associated property. In case of spectrum type array properties, this refers to the vertical minimum setting. This value is identical to the minimum setting returned in some variations of the call to ".EGU".
- CF_FLOAT gives the minimum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4".
- ".XMAX" returns the registered x-axis maximum setting for the associated property. In case of spectrum type array properties, this refers to the vertical maximum setting. This value is identical to the maximum setting returned in some variations of the call to ".XEGU". An X-axis is only applicable for AT_SPECTRUM properties (i.e. a 'wave-form' spectrum or trace). Thus most properties will return '0' for the set points and an empty string for the units, if they are not registered as an AT_SPECTRUM array type.
- CF_FLOAT gives the x-axis maximum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4".
- ".XMIN" returns the registered x-axis minimum setting for the associated property. In case of spectrum type array properties, this refers to the vertical minimum setting. This value is identical to the minimum setting returned in some variations of the call to ".XEGU". An X-axis is only applicable for AT_SPECTRUM properties (i.e. a 'wave-form' spectrum or trace). Thus most properties will return '0' for the set points and an empty string for the units, if they are not registered as an AT_SPECTRUM array type.
- CF_FLOAT gives the x-axis minimum set points.
This same information is available via a call to the stock property "PROPERTIES" with a request for output type CF_STRUCT and tag "PRPQSr4".
- ".HIST" (synonym ".HST") returns the local history for the associated property. This meta property supports server output format specifications. Important to remember is that the call should return an array of values over a time range and therefore needs to return not only values but timestamps. Thus, as a miminum, the requested format type should be a doublet type capable of containing the original property's format as will as a timestamp (for example CF_FLTINT). Supported output formats include (but are not limited to):
- CF_FLTINT value - timestamp pairs in the simplest variant (convert stored value to float and timestamp to UTC seconds.
- CF_DBLDBL value - timestamp pairs in a more general (albeit larger) variant (convert value to double and timestamp to UTC seconds with millisecond part).
- CF_INTFLTINT - traditional doocs format (UTC seconds - value - status triplet).
- CF_HISTORY - all inclusive variant which embeds the original format and carries the full timestamp as well as other data stamps. This is obviously the 'best' retrieval data type to use from the point of view of 'not missing anything'. However it is also a difficult format to use for the layman.
Other output format types are possible but will not be listed here. In general one should make use of the standard history API routines GetArchivedData(), GetArchivedDataAsAny(), GetArchivedDataAsText(), etc. This stock meta property also accepts input specifying the time range and other parameters. Input can be
- CF_INT32 or CF_DOUBLE an array of up to 4 values. The first value gives the start time (UTC). The second value gives the stop time (UTC). The third value gives the starting index (in case the stored property is an array). The fourth value is the sampling raster.
- CF_FWINDOW containg the start and stop as UTC values in the first and second integers and lower and upper filter values as the first and second floats.
If there is no input, or fewer than 4 CF_LONG or CF_DOUBLE values are passed, then the default stop time is the current time and the default start time is the current time minus the extrapolated time based on the requested size of the call. The default index is '0', and the sampling raster is determined by the number of stored points, the size of the call, and the time range.
- ".HIST@" (synonym ".HST@") returns the local history for the associated property. This call is a variation of the ".HIST" call in that it accepts a single input (CF_INT32, or CF_DOUBLE) specifying a targetted time. The call will deliver the record at the specified time or next stored data if there is no record at the specified time. The returned timestamp is the timestamp stored with the data returned. As this call does NOT deliver an set of data over a time range, the requested output format should be that of the stored property.
- ".ARCH" (synonym ".ARC", ".AR") returns the central archive history for the associated property. If the device server has registered the the corresponding entry in the central archive server and this stock meta property is accessed, then the call will be redirected to the corresponding entry at the central archive server. The calling formats for input and output follow the discussion for the meta property ".HIST".
- ".NAM" returns the property specific channel names list for the associated property. For 'device-oriented' properties, where a property is either not available for the complete list of registered devices or otherwise needs to associate a different set of names than the registered device list, this meta property can be used to return this information. The returned list is as in the case of the stock property "DEVICES" a list of string types (e.g. CF_NAME64). This list of property specific devices is either provided by configuration (e.g. <property name>-names.csv) or API call AssignPropertyList(). If at least one property has an associated list it established 'property-query precedence' for the device server. Note: the stock meta property can be called for any property and will return the registered device list if no associated channel names have been registered for the property in question.
- ".DESC" (synonym ".DSC") returns the registered description of the associated property. This can be an string type format (CF_TEXT or CF_NAME64).
- ".BIT." returns the specified bit from the output of the associated property. This meta property will only be applied to calls for integer type data (CF_INT16, CF_INT32) and will call the property given and then extract the bit specified in the meta property. For example "ABC.BIT.3" will call property "ABC" and then extract bit 3 from the output and return it in the call.
- ".MASK." returns the masked output for the associated property. In analogy with the ".BIT." meta property, This meta property will only be applied to calls for integer type data (CF_INT16, CF_INT32) and will call the property given and then mask the output against the mask specified in the meta property. For example "ABC.MASK.0x7" will call property "ABC" and mask the output against '0x7' and return the results.
- ".GATE." returns the gated output for the associated property. In analogy with the ".BIT." meta property, This meta property will only be applied to calls for integer type data (CF_INT16, CF_INT32) and will call the property given and then gate the output against the mask specified in the meta property. For example "ABC.GATE.0x7" will call property "ABC" and mask the output against '0x7' and return a '1' if the result is non-zero or '0' if the result is zero.
