Additional Functions

GTS(0)

GTS returns the current date and time. It is a replacement for the Now() function. GTS is used so that the calc script will work properly when backfilling, as Now() will always return the current time even when backfilling data whereas GTS will return the current cycle time.

GetInputTagCount

GetInputTagCount returns a number (long) that is the max ID number of the input tags.

Example code:

                Dim MaxInputTag as long

                Dim i as long

                Dim Total as double

                MaxInputTag = GetInputTagCount

                For i = 1 to MaxInputTag

                                Total = Total + GD(i)

                Next i

GetOutputTagCount

Returns a number (long) that is the max ID number of the output tags.

Example code:

Dim MaxOutputTag as long

                Dim i as long

                MaxOutputTag = GetOutputTagCount

                For i = 1 to MaxOutputTag

                                Writeval(i,False)

                Next i

GQual(Tagnumber)

GQual returns the quality of a tag as an integer. Good quality will return a value of 262336.

Example code:

Dim Quality as integer

Quality=GQual(1)

This sets Quality equal to the “quality” of tag 1

GQualStr(Tagnumber)

GQualStr returns the quality of the tag as a string (i.e. good or bad).

Possible values to be returned are:

qualitystring = "Good"

qualitystring = "Bad"

qualitystring = "Uncertain"

qualitystring = "Config Error"

qualitystring = "Not Connected"

qualitystring = "Device Failure"

qualitystring = "Sensor Failure"

qualitystring = "Last Known"

qualitystring = "Comm Failure"

qualitystring = "Out of Service"

qualitystring = "Last Usable"

qualitystring = "ECU Exceeded"

qualitystring = "Sub Normal"

qualitystring = "Local Override"

qualitystring = "Unknown"

Example code:

                Dim sQuality as string

                sQuality=GQualStr(1)

This sets Quality equal to the quality of tag 1.

fnTagStat(tagnumber, starttime, stoptime, stattype)

Calculates a statistic for a given tag over a specified period of time.

The inputs are:

tagnumber: The number of the tag to get values from, or the full tag name (loc.source.tag).

starttime: The time to start stat from.

stoptime: The time to stop the stat.

stattype: select from:

TIMEAVG

TAVG

TIMEAVERAGE

TIMEAVG2

TAVG2

TIMEAVERAGE2

LINEAR

LIN

AVG

AVERAGE

RAWAVG

RAWAVERAGE

SUM

COUNT

MIN

MINIMUM

MAX

MAXIMUM

SD

STDEV

SDEV

START

TOTAL

END

DELTA

Example code:

Dim average as single

                Dim start as date

                Dim stop as date

                Start=gts(0)-1

                Stop=gts(0)

                Average=fnTagStat(1,start,stop,”avg”)

This will set Average to the average for the last 1 day for the tag.

fnTagStatArray(tagname, starttime, stoptime, stattype, stepsize)

Returns an array of stats for the stepsize over the set period of time.  The stat types are the same as in fnTagStat, and they are calculated for an interval equal to the stepsize.  The step size is in units of seconds.  The step size can also be inputed as a string and by indicating “s” for second, “m” for minutes, “h” for hours, “d” for days after the numbers different units can be used.  For example, “24h” sets the step size to 24 hours.

The inputs are:

Tagname: The number of the tag to get values from, or the full tag name (loc.source.tag).

Starttime: The time to start stat from.

stoptime: The time to stop the stat.

stattype: select from:

TIMEAVG

TAVG

TIMEAVERAGE

TIMEAVG2

TAVG2

TIMEAVERAGE2

LINEAR

LIN

AVG

AVERAGE

RAWAVG

RAWAVERAGE

SUM

COUNT

MIN

MINIMUM

MAX

MAXIMUM

SD

STDEV

SDEV

START

TOTAL

END

DELTA

stepsize: The stepsize for the aggregate, can be either as a number in seconds or a string like 60S, 30M, 6H or 3D.

Example code:    

Dim average as variant

                Dim start as date

                Dim stop as date

                Start=gts(0)-1

                Stop=gts

                Average=fnTagStatArray(1,start,stop,”avg”,1000)

This will give the average every 1000 seconds for the previous day.

Writeval(tagnumber, status)

In a calculation cycle an output tag will write out a value even without hitting a Tag statement with that tag’s output number (in this case it will write out the last value it did calculate).  However, if the status is set to false with Writeval then that tag will not be written out on that pass through the script.  Caution should be taken if there is a Tag statement for this tag later in the script, because the status will be overwritten to true.

Example code:

Writeval(1,false)

This makes tag 1 not write this time through the code.

GetInputTagname(tagnumber)

Returns the tag name.

Example code:

                Dim name as string

                Name=GetInputTagname(1)

This will set Name equal to the name of input tag 1.

fnTagRawArray(tagnumber, starttime, stoptime, vValues, vtimes)

Fills the vValues array with values from the tag and fills the vtimes array with time stamps for the values.  The vValues and vTimes variables should already be dimmed variables of the variant type.  fnTagRawArray is sub routine and not a function it fills the two arrays.

Example code:

Dim vValues as variant

                Dim vTimes as variant

                Dim starttime as date

                Dim stoptime as date

                Starttime=gts(0)-1

                Stoptime=gts(0)

                fnTagRawArray(1,starttime,stoptime,vValues, vTimes)   

This gives the two arrays, one of values and one of timestamps, filled with raw data from Tag 1 for the last 1 day.

fnTagAtTimeArray (tagnumber, vTimes, vValues)

Takes in an array of times and fills the vValues array with linearly interpolated values from the tag.  The vValues and vTimes variables should already be dimmed variables of the variant type.  fnTagRawArray is sub routine and not a function, it fills the values arrays.

Example code:    

Dim vValues as variant

                Dim vTimes as variant

                Redim vTimes(3)

                Dim i as long

                vTimes(1) = gts() - 3

                vTimes(2) = gts() - 2

                vTimes(3) = gts() - 1

                fnTagAtTimeArray(1 , vTimes, vValues)   

fnLimit(TagName/Number, GradeName, LimitType, Lower, Target, Upper, Optional LimitDate)

Gets the upper, lower and/or target for a tag. If the tag has grade based limits, it can get those limits at a certain grade or at the current grade. If non-grade based, no grade needs to be specified.  There is an option limitdate input parameter if a limit version at a certain date should be returned.

The inputs are:

TagName/Number: The tag index number or tag name to get limits for

GradeName: The name of the grade to get limits for.  If non-grade based, just leave blank, if grade base want to get for the current grade, enter “Current”.

LimitType: Numeric limit type, 1 is control, 2 is spec

Lower: Output parameter, the lower limit

Target: Output parameter, the target

Upper: Output parameter, the upper limit

LimitDate: Optional input parameter, if not set, will always return the most recent limit, if set, will return limit that would be applied for the date and time.

If there is no value for Lower, Upper and/or Target, it will return a string equal to “#NA”, so the variables to return the limits to should be dim as Variants.

Example code:

Dim vLower as variant

                Dim vTarget as variant

                Dim vUpper as variant

                Call fnLimit(1,”Current”,1,vLower,vTarget,vUpper)

Set_Quality(tagnumber, quality)

Sets the quality of the tag equal to the input quality. 

Quality of bad=0

Quality of good=192

Example code:

Set_quality(1,192)

This sets the quality of tag 1 to good

WriteStatic(writevariable, setnumber) and ReadStatic(writevariable, setnumber)

Readstatic and Writestatic work together to create static variables.  These functions are more reliable than just creating static variables because they write the variables to a file, so that if there is a power loss or the program crashes the data is not lost.  Place Writestatic at the end of the code to write a variable out to a file, and place Readstatic at the beginning of the code to read the data from the file into a variable. 

The parameters for both functions are (num,1), where num is the variable to be written to or from. The second parameter is a set number that tells the function which file to write or read from. To set up multiple static variables, use a different set number for each one.

Example code:

Readstatic(num,1)

                Num=num+1

                Writestatic(num, 1)

This will add 1 to num every time this program is run.

AddOutPutTag(strTagName As String, strTagDesc As String, plotmin As Long, plotmax As Long)

AddOutPutTag automatically adds an output tag to the output tags list. This only functions in configuration/testing mode, not for the code running in the PARCcalc Server. It is used to dynamically create output tags in the code based on logic built into the code.

Example Code:

Dim j as long

Dim sTag as string

For j = 1 to 10

sTag = “OutputTag” & j

Call AddOutputTag(sTag,sTag,0,100)

Tag(sTag,j)

Next j

This would create 10 output tags (OutputTag1, OutputTag2, etc.) and assign them each a value. The first test run in CalcConfig would create tags.

Function GetCycleTime() As Long

GetCycleTime returns the calc serverss cycle time in seconds.

Example Code:

Dim iCycleTime as long

iCycleTime = GetCycleTime()

This code set the value of the calc server’s cycle time to the variable iCycleTime.

Function GetDBConnectionString() As String

This function returns the database connection string to the configuration databases for the dataPARC instance the PARCcalc tools are connected too.

Example Code:

Dim sConnStr as string

sConnStr = GetDBConnectionString

This code sets the string variable sConnStr to the database connection string. This can then be used to make a connection to the dataPARC configuration database.

Function GetTagTime(ByVal varTag As Variant) As Date

The GetTagTime Function returns the current time of the tag, based on the tag’s defined time zone compared to the time zone the PARCcalc application is running in. varTag can be either the input tag’s index number or the full UTag name of the input tag.

Example Code:

Dim dtDate as datetime

dtDate = GetTagTime(3)

This code sets the dtDate variable to the current time of the input tag 3’s timezone.

Sub WriteDataToHistory()

WriteDataToHistory is a Sub Routine that, when called, forces a write to history in the middle of the script. Any tags written at that time will be written to history. This is used when it is necessary to write different values at different times to the same tag in one cycle. Otherwise, if the same tag index is written to more than once in a script, only the last written value is sent to history.

Example Code:

Dim dblTagVal as double

Dim dtTS as datetime

dblTagVal = 32.3

dtTS = GTS() – 1/24

Tag(2,dblTagVal,dtTS)

Call WriteDataToHistory

dblTagVal = 25

dtTS = GTS()

Tag(2,dblTagVal,dtTS)

This code will write a value of 32.3 to output tag 2 at a time of one hour ago, then force a write to history. It then will write out a value of 25 to input tag 2 at a time of Now when the code is finished.