WinCC Trend Control: TlgGetRulerValueTrend Ruler Value Guide

Overview

Siemens WinCC Online Trend Control displays live and archived process values as a function of time. Operators can drag a vertical ruler (also called a lineal or cursor) over a trend curve to read the archived value at that exact instant. A recurring engineering task is to mirror the ruler value into other screen elements, such as a bar graph, a numeric I/O field, or a status panel, so the operator sees a consistent snapshot of the data point that the trend is currently pointing at.

The native WinCC C/Basic API exposes a set of Tlg... functions that read the trend control's state and that return values associated with the ruler position. The principal function is TlgGetRulerValueTrend(). This reference covers the function signature, parameter conventions, the difference between Window Title and ObjectName, the behaviour when the ruler is hidden, and the supported approaches for synchronising an on-screen bar display with the ruler readout on WinCC V6.2 SP2 through to V7.x, with a forward-looking note on WinCC Unified Trend Control.

Prerequisites and Environment

• Engineering Station: SIMATIC WinCC V6.2 SP2 (or later) with the Graphics Designer installed. The same scripts and call patterns apply to V7.0, V7.4, and V7.5; the only differences are in the property sheet layout and the introduction of the ribbon UI in V7.3+.
• Runtime: WinCC Runtime with a configured project. The Online Trend Control must be embedded into a PDL (Process Designer Library) picture.
• Tag Logging: At least one archive configured under Tag Logging → Archives with the relevant temperature tag inserted as a process value archive.
• Licensing: A valid WinCC RT license; the trend control OCX ships with the standard installation and requires no add-on package.
• Scripting access: C scripting (ANSI C, Project Functions) or VBScript. Both engines can call the Tlg... C-API functions through the Internal → Tlg include path when VBScript is used.

Configuring the Online Trend Control

Before the ruler function can return a value, the control itself must be correctly parameterised. The relevant configuration steps are summarised in the Siemens article How to Configure Trends in Online Trend Control - WinCC V7.4 and apply equally to V6.2 SP2.

1. Open Graphics Designer and drop an Online Trend Control from the Controls palette into your picture.
2. Open the configuration dialog and switch to the Curves tab.
3. Use the + key to add as many curves as the picture needs. For a temperature profile, one curve per physical sensor is typical.
4. Define the order of curves with the Up and Down keys. The order here is the same order the nTrend parameter in TlgGetRulerValueTrend will index.
5. On the General tab, set the update rate and archive source. The ruler acts on whichever data is currently visible; if the control is displaying the live (online) buffer, the ruler reads live values; if it is in Back.../archive mode, the ruler reads archived values.
6. Click OK and then open Object Properties → Control Properties → Miscellaneous → Caption. The text in this field is the value the C API treats as the Window Title of the control. This is the parameter the script must pass as lpszTemplate; it is not the picture-level object name.

TlgGetRulerValueTrend Function Reference

The function reads the value of a single curve at the current ruler position. Its C signature is:

Return value: double. The numeric value of the curve at the time the ruler is positioned. If the ruler is currently off (hidden), the function returns the value of the curve at the time the ruler was last switched off. If the ruler has never been activated in the lifetime of the picture, the function returns 0.0 for numeric tags and the empty string for string tags.

On a WinCC V6.2 SP2 engineering station, the corresponding VBScript invocation uses the same prototype with a string literal as the first argument:

The function has no separate error code channel; the caller must validate the returned value against a sentinel (e.g. compare against the previous reading) and decide whether the value represents fresh or stale data.

Implementing Ruler-Triggered Bar Updates in C

The cleanest implementation is a C Project Function that runs on a trigger event. Wire the function call to a C-action on the bar graph so that the bar refreshes whenever the script is fired. The trigger should be either a one-second timer or, preferably, a Triggered event on the trend control if the project exposes one. The minimum C implementation is:

// Project function: GetRulerValue_BarFeed
#include "apdefap.h"
double GetRulerValue_BarFeed(void)
{
    return TlgGetRulerValueTrend("TrendControl_01", 0);
}

Bind the bar's Process Value property to GetRulerValue_BarFeed() through a tag prefix in the Dynamic Wizard. The bar will then mirror the trend's first curve at the ruler position once the picture has been opened and the user has activated the ruler at least once.

Implementing Ruler-Triggered Bar Updates in VBScript

WinCC V6.2 SP2 also supports VBScript actions on the same OCX. A VBScript equivalent of the C function above is:

' VBS action attached to the bar object (event: "Property Change" or a 1s timer)
Dim dblRuler
dblRuler = TlgGetRulerValueTrend("TrendControl_01", 0)

If IsNumeric(dblRuler) Then
    BarGraph.ProcessValue = CDbl(dblRuler)
Else
    BarGraph.ProcessValue = 0
End If

The IsNumeric guard is mandatory when the underlying tag is a string type, because the function returns a Variant of VT_BSTR for string-valued trends; coercing it to CDbl would raise a type mismatch error.

Detecting Ruler State On/Off

The principal limitation of TlgGetRulerValueTrend is the absence of a companion call that returns the visibility state of the ruler. If the operator hides the ruler (or it has never been activated), the function silently returns the last held value. Two field-proven workarounds are documented below.

Workaround 1 – Suppress the Native Ruler Button and Drive It Externally

Hide the integrated ruler button in the trend control's toolbar and place a custom button on the picture, wired to TlgTrendWindowPressLinealButton. The button toggle is then used to write an internal tag (e.g. TrendRulerActive as a binary tag) which the bar-driving script can read to decide whether the value is fresh.

1. Open Object Properties → Toolbar → Button Configuration and disable the Ruler (lineal) entry. The toolbar's visible buttons shrink accordingly.
2. Add a WinCC button to the picture and assign a C action that calls TlgTrendWindowPressLinealButton("TrendControl_01"); and then flips the internal tag:

// C action on custom button click
TlgTrendWindowPressLinealButton("TrendControl_01");
SetTagBit("TrendRulerActive", (GetTagBit("TrendRulerActive") == 0));

3. On the picture's Open event, set the internal tag to 0 so the state cannot leak from a previous navigation:

// C action on picture open
SetTagBit("TrendRulerActive", 0);

4. In the bar-driving function, gate the assignment:

if (GetTagBit("TrendRulerActive") == 1)
    BarGraph.ProcessValue = TlgGetRulerValueTrend("TrendControl_01", 0);
else
    BarGraph.ProcessValue = GetTagFloat("Live_Temperature"); // fallback to live

Workaround 2 – Detect Ruler Activity by Polling the Value

When the project cannot add custom toolbar buttons, a coarse but functional heuristic is to compare successive samples of TlgGetRulerValueTrend and treat a value change as evidence of ruler activity. The approach is sensitive to genuinely changing process values, so it is best combined with the TrendRulerActive internal tag from Workaround 1 for confidence.

TlgGetRulerTimeTrend for Time-Based Lookups

The companion API is TlgGetRulerTimeTrend, which returns the time stamp at the ruler position:

The return is a double representing the time in WinCC's internal time format (days since 30.12.1899, including the fractional day). It is the same encoding returned by GetTagValue for internal time tags, so the value can be forwarded directly to archive queries. The typical use case is to combine it with TlgGetRulerValueTrend to populate a bar chart and its associated time stamp label simultaneously.

double dblTime, dblValue;
dblTime  = TlgGetRulerTimeTrend("TrendControl_01");
dblValue = TlgGetRulerValueTrend("TrendControl_01", 0);
SetTagFloat("Ruler_Time",  dblTime);
SetTagFloat("Ruler_Value", dblValue);

For string-format display, convert the double through SysTime / Format in the C action before writing to a text I/O field.

Linking Bar Graph Displays to Ruler Values

Two integration patterns are common in production screens.

The third pattern is the one most commonly shipped in WinCC V6.2 SP2 retrofit projects, because it preserves the live display as a safety baseline while still giving the operator the historical read-out.

Performance and Triggering Considerations

• Timer resolution. A 250 ms timer is sufficient for a bar graph that drives a single curve. Using a 100 ms or faster timer does not improve the bar's visual smoothness because the bar's own refresh is rate-limited by the picture cycle.
• Multiple curves. When bars are linked to several curves, call TlgGetRulerValueTrend once per curve. Each call walks the trend's internal value cache and is O(log n) in the number of archived samples. The function is safe to call from a 1 Hz timer in projects with up to ~50 curves.
• Picture navigation. Always reset the TrendRulerActive internal tag in the picture's Open event. Stale tags from a previously open picture will otherwise leave the bar locked on a stale value.
• Cross-picture trends. If the same trend control instance is embedded in more than one picture, the function returns values from the currently visible instance only. The lpszTemplate must match the active picture's control, otherwise the call silently returns the cache value from the most recent instance.

Troubleshooting Matrix

Cross-Version Migration: V6.2 SP2 to V7.x and Unified

WinCC V6.2 SP2, V7.0, V7.4, and V7.5 share the same TlgGetRulerValueTrend C signature; scripts written for V6.2 typically compile and run unchanged on V7.x, provided the project is migrated via the WinCC Project Migrator. The Visible differences between the versions that affect this scenario are:

• Toolbar configuration – V7.3 introduced a ribbon-style dialog. The Ruler button is still under the Toolbar tab but the icon set differs.
• Object naming – Picture Window references in V7.4 are case-insensitive on the PDL level but remain case-sensitive at the C API level. Verify case after migration.
• WinCC Unified (TIA Portal V17+) – The OCX is replaced by an HTML5-based trend control. The TlgGetRulerValueTrend C API is not available. The Unified equivalent is exposed through JavaScript in the runtime API as TrendControl.GetRulerValue(trendIndex). Operators drag a cursor across the trend; the function returns the value at the cursor position in the same units as the configured trend. For migration projects, the legacy C function must be re-implemented in JavaScript and the VBScript wrapper must be removed. Refer to Trend control (RT Unified) for the runtime configuration model.

Best Practices Summary

• Always pass the Window Title (Caption), never the ObjectName, to TlgGetRulerValueTrend.
• Track ruler visibility through a custom button and an internal tag; do not rely on the function to signal whether the ruler is active.
• Reset the ruler-state tag in the picture's Open event.
• Pair the value call with TlgGetRulerTimeTrend when the bar graph is part of a larger archive view.
• Wrap VBScript calls in IsNumeric() when the trend carries a string-typed tag.
• For new projects, evaluate WinCC Unified before committing to V6.2 SP2; the JavaScript API of the Unified trend control is more idiomatic and exposes the ruler state directly.

FAQ