Data references are used to associate various items to attributes in your AF hierarchy. In
the case of PI point data references, we have the option to add value retrieval methods. Value
retrieval methods change the type of requests for data made to the PI data archive, based on
the time context of the client. Before hopping on to PI System Explorer to configure a PI point data
reference with a value retrieval method, let's explore what's meant by the client time context.
The most simple time context is the current time, often denoted by star in PI time. PI
System Explorer as a client is set to have a time context of now by default. But a single
timestamp can also be some specific time in the past or future including T, Y, or even
a specific time. Time context can also refer to a time range with both a start and end time. In
this case from now to 24 hours ago. We may want to request summary data over that time range,
such as a time-weighted average, event weighted average, maximum, minimum or others. Let's start
by looking at a simple value retrieval method configuration designed to take the average over a
time period and see how its settings interact with the start or end time passed by different clients.
Three of the by time configurations are used for summary calls or calls that require a time
range. Those three are time range, time range override and not supported. Let's start with
time range and request a time weighted average. One additional important piece of information
is relative time. Here we've chosen a relative time of 24 hours, but what exactly does this
mean? Since PSE by default has an end time context of star but no start time context,
the time range to be used when calculating the average will assume to go back 24 hours into the
past from the end time context of star passed by PSE. However, some clients like PI Vision and PI
ProcessBook will pass both a start and end time. So, the value of 24 hours as the relative time is
not actually used by that client. These clients will use the start and end times of the display.
So, when using time range the relative start time is used if the client doesn't have its own start
time context. So, what do you do if you want PI Vision and PI ProcessBook to also use 24 hours for
the average, even if the display time range isn't 24 hours? This is why you use time range override.
In this case the end time of the summary call refers to the end time of the display. But the
summary call is forced to be the end time minus 24 hours since we're using time range override.
The third summary call is not supported. Not supported requires that both the start and end
time are provided by the client. For PI Vision and PI ProcessBook, these will be the start and
end times of the display. However, since PI System Explorer by default has only an end
time context of now and by default no start time context, not supported will show an error in PSE.
There are a large number of time range options that can be selected when using time range,
time range override and not supported. We used average and the others are mostly
self-explanatory, but details are provided in the documentation linked below. Also,
if you wish to use a calculation basis other than time-weighted, please see the documentation. So,
what about the other by time options? The other options don't refer to summary calculations over
a time range, instead are used with a single time context. In PSE again this is by a default
now but for PI Vision and PI ProcessBook we've selected the by time range to be the end time of
the display. Now that we have a different time context depending on what client we're using,
we need to determine how to find a value at this time and seven options are available.
After, refers to the first value after the timestamp while at or after is the first
recorded value at or after the timestamp as expected. However, note that in both PSE and
PI Vision this is also interpreted as the snapshot. So even if the value is before
the client end time it still will return that snapshot. Similar definitions exist for before
and at or before. Note that automatic and interpolation are very similar but there is
a slight difference in the time stamp returned when the tag is set to step. And one final note
on using a single time context. Relative time is a time delay from the time context in this basis.
Let's go ahead and setup a simple example. We have an attribute being the pump flow rate in
gallons per minute. We would like three more attributes that show the total flow so far today,
this month and this year. In each case the relative time is set to determine the time
range over which we would like to take this total. Just a couple more notes before we hop on to PI
System Explorer. The calculation has resolved to locally by the client and it's not saved in a PI
tag. Since it is resolved locally this also means that PI time like T, or the midnight associated
with today, is the local time of your client. So different people on different machines and
different time zones will have different midnights resolving for this calculation.
With that said let's hop on to PSE to set this up. Here in PSE,
we have our inlet pump with our attribute pumps flow rate and if we go ahead and trend the data,
we can see that we tend to have about 1.1 gallons per minute. Let's go ahead and create the value
retrieval method attributes that we discussed. Let's create them as new child attributes because
it'll help us keep them organized. The first one will be total flow so far today. And let me go
ahead and click on settings to assign it as a PI point data reference. Instead of selecting
the tag name directly let's just reference the attribute above. It will automatically fill in the
units of measure and for value retrieval method I'm going to use time range override and use a
relative time of T for today at midnight. For by time-range I want the total flow over that time,
so I'm going to go with total. We do need to make a correction for units of measure to explicitly
tell it that we have our inlet in gallons per minute and let me go ahead and click OK.
And does this value make sense? It's about 16 hours into the day since it's 4 p.m. and we have
a flow rate of about 1, little over 1 gallon per minute, so a flow total flow today of about 1100
does make sense here. Now just as a reminder this is the total flow from T at midnight today on this
client machine, to star since PSE is passing in an endtime context of now. But this could look
slightly different if you're on a different machine since T could resolve to a slightly
different time because it'll be midnight local to that time zone. And also, the end time context may
be slightly different if for instance your PI Vision display doesn't have an end time of now.
Let's make another child attribute for the total flow so far this month. Let me click settings
and I'll again assign it to the attribute. Value retrieval method by time is time range
override. And by time range again will be total and we'll make sure to correctly set the units
of measure. Relative time in this case is going to be a value of 1, since in PI time 1 refers to
the day of the month and then it automatically defaults to the current month, the current year
at midnight which would be midnight on the 1st of the month. And again, this value looks reasonable.
Let's go ahead and right click and create another one total so far this year. Click
on the attribute, pump flow rate, time range override, total. In a relative time,
this time is going to be January first and then it'll assume the current year and midnight on that
day. And each time I hit refresh it's actually going to re-query the PI data archive for the data
over this time range and the client is then going to update. Now just to be consistent, let's make
sure that we set our units of measure explicitly on what we would like to output. And these will
not be saved to PI tags, so here we have the total so far today, this month and this year. PI point
data references as value retrieval methods. Now that you understand how the time context of the
client interacts with value retrieval methods of PI point data references, you can set up summary
or single value calculations and understand how different clients interact with these settings.