Measure User's Guide

Creating a Custom Measurement Application
Measure User’s Guide—520560-003
6-15
Reading Counter Records From a Data File
By default, both MEASREAD and MEASREAD_DIFF_ return the most recent record
for an entity. This record is written at measurement, at entity stop time, or at the last
collection interval. Both procedures have optional parameters you can use to specify a
target time for records:
•
With the MEASREAD procedure, the nomtime parameter specifies a target time.
Instead of returning the most recent record for an entity, MEASREAD returns the
record whose TO-TIMESTAMP field is closest to the specified target time.
The timetol parameter establishes a time window in which the record must
reside. The window is the interval between nomtime - timetol and nomtime +
timetol. If MEASREAD does not find a record whose TO-TIMESTAMP resides
within the window, it does not return a record for that entity. If it finds more than
one record, it returns the record whose TO-TIMESTAMP is closest to nomtime.
If you use the timetol parameter, remember that some entities do not exist for an
entire measurement interval. If you use timetol to specify a window that is less
than the measurement interval, you might unintentionally exclude transient entity
records. For example, if you have a measurement interval of 30 seconds, a
transient entity can start and stop during the first 10 seconds of this interval. If you
specify a timetol of 15 seconds, you will not receive this entity record.
•
With the MEASREAD_DIFF_ procedure, the to^time and from^time
parameters specify a target time window for the records. The timetol parameter
specifies the tolerance on either side of the time window.
Instead of returning the most recent record for an entity, MEASREAD_DIFF_
returns the records at to^time subtracted from the records at from^time. If
MEASREAD_DIFF_ does not find a record within the window, it does not return a
record for that entity. If it finds more than one record that could satisfy the to^time
or from^time specification, it returns the record closest to the respective end
point (either to^time or from^time). For more information, see the
MEASREAD_DIFF_ procedure in the Measure Reference Manual.
Example 6-3
on page 6-16 shows how to use MEASREAD to open a data file and read
the most recent records for all DISC entities into an extended segment; 65536 bytes
are allocated in the extended segment for the returned records. (In many cases, you
might need more space.)