Cicode Programming Reference > Cicode Function Categories > Trend Functions Introduction > TrnSetPen


Sets the trend tag of a trend pen. The trend pen changes to the specified tag and the trend is refreshed. The trend pen needs to be in the operator's area to be displayed. If outside of the operator's area, data is not displayed. You cannot mix periodic trends and event trends in the same trend window.

This function may sometimes return before the pen is actually set when called on a PC which is not the trend server. This may create difficulties for following functions such as TrnSetScale. A wrapper function can be used to confirm the pen is set before returning. See example 2 below.


TrnSetPen(AN, Pen, Tag)


The AN where the trend is located.

-1 - All trends on the current trend page.

-2 - The function being called is using the special AN setup by the TrnSelect() function.


The pen for which the trend tag will be changed.

-2 - The first available pen (This value is automatically changed to 0 for SPC trends because they have only one pen per trend.)

-1 - All pens on the trend. (Not allowed for SPC trends.)

0 - The pen currently in focus.

1...8 - Pen1....Pen8


The trend tag. If Tag = ! the pen is deleted.

Return Value

0 (zero) if successful, otherwise an error is returned. Be aware that if a mixture of periodic and event trends is detected, the return value is 0 (zero), but the hardware alarm #329 is set.

Related Functions

TrnGetPen, TrnSelect

Example 1

! For the trend at AN20
! Sets the trend tag of Pen1 to "PV1".

Example 2

BlockedTrnSetPen(INT hAN, INT nPen, STRING sTrend)
INT timeout = 5000
INT sleepTime = 10
INT error = -1
INT elapsed = 0
INT currentTime
error = TrnSetPen(hAN, nPen, sTrend)
IF error = 0 THEN
error = -1
currentTime = SysTime()
WHILE error <> 0 AND elapsed < timeout DO
sPenName = TrnGetPen(hAN, nPen)
IF sPenName = sTrend THEN
error = 0
elapsed = elapsed + SysTimeDelta(currentTime)
RETURN error

See Also

Trend Functions