Class ParameterDataAccessBase

This is used to defines how data is sampled or interpolated and obtained from SQL Race.

The ParameterDataAccess and RemoteParameterDataAccess object is created by calling the Session.CreateParameterDataAccess(parameterIdentifier) method and is associated with both the session and a Parameter. More than one ParameterDataAccess object can exist within a session as each can used to retrieve the parameter data.

A ParameterDataAccess object can be created to retrieve data from all the Channel within Parameter or for data from specific Channel.

Methods on the ParameterDataAccess object allow you to:

• Move to specific point in time
• Set the sample time
• Read subsampled data
• Read interpolated data
• Read the actual sample values

Follow the below best practices:

• Opening a PDA uses up memory until the session is closed and disposed. It is best to open a PDA for a parameter once and cache it. Then you can reuse it throughout the session. An example of when this is particularly useful is when iterating through laps. It is better to open each PDA once than to open and dispose of them inside the lap iteration.
• Calls to a PDA are not thread safe. If you are wanting to access data using the same Parameter in different threads, it is better to consider opening a small pool of PDAs for the threads to use. You have to be extra careful when using method that require the PDA's current position to ensure that it is only being used by one thread.

The following code snippet shows an example of using the ParameterDataAccess class to read subsampled data across all channels for a parameter:

  // Local database connection string and session key for data already recorded
  string connectionString = @"Data Source=.\sqlexpress;Initial Catalog=SQLRACE01;Integrated Security=SSPI";
  SessionKey sessionKey = new Guid("7DD05707-EAA2-4A36-BB8A-E2327AA52BFC");

  // Initialise
  Core.Initialize();
  SessionManager sessionManager = SessionManager.CreateSessionManager();

  // Create storage for output values
  double[] data = new double[10];
  DataStatusType[] status = new DataStatusType[10];

  // Load existing session
  Session session = sessionManager.Load(sessionKey, connectionString);

  // Use PDA to get subsampled data across all channels in parameter: ParameterId
  using(ParameterDataAccessBase pda = session.CreateParameterDataAccess("ParameterId"))
  {
       // Go to 0:00:01am
       pda.GoTo(1000000000);

       // Set sample time to 500Hz ~ 2000000ns 
       pda.SampleTime = 2000000;

       // Get 10 samples, use first sample, do not interpolate
       var parameterValues = pda.GetNextData(10, SampleModeType.First);

       // Print data and status to console window
       for (int i = 0; i < 10; i++)
       {
            Console.WriteLine("Data: {0}, Status: {1}", parameterValues.Data[i], parameterValues.DataStatus[i]); 
       }
  } 
  // Always close the session
  session.Close();

Simple example of opening a PDA setting the read cursor to the start of the session and reading the first 1000 samples. Then disposing the pda.

using (var pda = session.CreateParameterDataAccess(parameterIdentifer))
{
   pda.GoTo(session.StartTime);
   var samples = pda.GetNextData(1000);
}

An example of using a PDA cache to reuse pdas to the access data of one session and then closing the session

 // Open and cache PDA
 ParameterDataAccessBase pda;
 if (pdaCache.ContainsKey(parameterIdentifer))
 {
     pda = pdaCache[parameterIdentifer];
 }
 else
 {
     pda = session.CreateParameterDataAccess(parameterIdentifer);
     pdaCache[parameterIdentifer] = pda;
 }

 ... Do work using PDA ...

 // Before disposing of the session we want to remember to dispose the pdas openned.
 foreach (var parameterDataAccessBase in pdaCache)
 {
     parameterDataAccessBase.Value.Dispose();
 }

Inheritance

System.Object

ParameterDataAccessBase

ConstantParameterDataAccess

FixedValueParameterDataAccess

ParameterDataAccess

Implements

IParameterDataAccess

System.IDisposable

Namespace: MESL.SqlRace.Domain

Assembly: MESL.SqlRace.Domain.dll

Syntax

public abstract class ParameterDataAccessBase : Object, IParameterDataAccess, IDisposable

Fields

CurrentPosition

The current position for the PDA.

Declaration

protected Nullable<long> CurrentPosition

Field Value

Type	Description
System.Nullable<System.Int64>

DefaultSampleTime

Default sample time.

Declaration

protected const int DefaultSampleTime = 10000000

Field Value

Type	Description
System.Int32

SampleSizeCap

The sample size cap

Declaration

public const int SampleSizeCap = 10000

Field Value

Type	Description
System.Int32

Properties

CoverageCursor

Gets the coverage cursor for the PDA.

Declaration

public abstract long CoverageCursor { get; }

Property Value

Type	Description
System.Int64

CurrentTime

Gets the current position.

Declaration

public Nullable<long> CurrentTime { get; }

Property Value

Type	Description
System.Nullable<System.Int64>	The current timestamp for the PDA.

DataChangedCounter

Gets a count of changes made to the data of any channel used by the PDA.

Declaration

public abstract int DataChangedCounter { get; }

Property Value

Type	Description
System.Int32

DemandTimerange

Gets the overall time range of requests to the PDA (i.e. from minimum requested start time maximum requested end time).

Declaration

public Nullable<TimeRange> DemandTimerange { get; }

Property Value

Type	Description
System.Nullable<TimeRange>

ErrorDefinition

The ErrorDefinition that contains this PDA's ParameterIdentifier as the Current or Logged Identifier

Declaration

public ErrorDefinition ErrorDefinition { get; }

Property Value

Type	Description
ErrorDefinition

Invalid

Gets a value indicating whether this ParameterDataAccessBase is invalid.

Declaration

public bool Invalid { get; }

Property Value

Type	Description
System.Boolean	true if invalid; otherwise, false.

ParameterIdentifier

Gets or sets the parameter identifier.

Declaration

public string ParameterIdentifier { get; protected set; }

Property Value

Type	Description
System.String	The parameter identifier.

SampleTime

Gets or sets the sample time (in nanoseconds) for the data. This value will only affect requests to get data (using the GetNextData method ) and will not affect calls to get samples (using the GetNextSamples/GetSamplesUntil methods).

Declaration

public long SampleTime { get; set; }

Property Value

Type	Description
System.Int64

Remarks

This time is the interval between data samples. For example: 1,000,000 ns = 1000Hz 10,000,000 ns = 100Hz 100,000,000 ns = 10Hz 1,000,000,000 ns = 1Hz If this value is not set then the default sample time is 100Hz (10,000,000 ns).

Session

Gets or sets the session.

Declaration

public SessionBase Session { get; }

Property Value

Type	Description
SessionBase	The session.

UseSubSampledChannels

Gets or sets a value indicating whether to use subsampled channels if available. Default value is True.

Declaration

public bool UseSubSampledChannels { get; set; }

Property Value

Type	Description
System.Boolean

Methods

AssignErrorDefinition(ErrorDefinition)

Assigns the error definition.

Declaration

public virtual void AssignErrorDefinition(ErrorDefinition errorDefinition)

Parameters

Type	Name	Description
ErrorDefinition	errorDefinition	The error definition.

CancelSearch()

Cancel/Abort Any Searches

Declaration

public abstract void CancelSearch()

Contains(Int64, Int64, MatchingRule, Double, Nullable<Double>, Nullable<Int32>)

Does this PDA's data contain a value

Declaration

public abstract bool Contains(long startAt, long endAt, MatchingRule rule, double value, Nullable<double> upperValue, Nullable<int> timespan)

Parameters

Type	Name	Description
System.Int64	startAt	Seach Start Position
System.Int64	endAt	Search End Position
MatchingRule	rule	Comparison operator
System.Double	value	Value to Search For
System.Nullable<System.Double>	upperValue	Upper Value - used when using the Between Operator
System.Nullable<System.Int32>	timespan	Period of time the condition must be met for

Returns

Type	Description
System.Boolean	Was the ValueFound

Contains(Int64, Int64, MatchingRule, String, Nullable<Int32>)

Does this PDA's data contain a value

Declaration

public abstract bool Contains(long startAt, long endAt, MatchingRule rule, string value, Nullable<int> timespan)

Parameters

Type	Name	Description
System.Int64	startAt	Seach Start Position
System.Int64	endAt	Search End Position
MatchingRule	rule	Comparison operator
System.String	value	Value to Search For
System.Nullable<System.Int32>	timespan	Period of time the condition must be met for

Returns

Type	Description
System.Boolean	Was the ValueFound

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. Implement IDisposable to allow the PDA to be used within the using statement.

Declaration

public void Dispose()

Dispose(Boolean)

Releases unmanaged and - optionally - managed resources.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	true to release both managed and unmanaged resources; false to release only unmanaged resources.

GetData(Int64[], SampleModeType, Boolean, ParameterValuesTemplate)

Gets the sampled data values and DataStatusType from the requested timestamps and sample types.

Declaration

public abstract ParameterValues GetData(long[] sampleTimestamps, SampleModeType withSampleMode, bool linearInterpolation = false, ParameterValuesTemplate template = null)

Parameters

Type	Name	Description
System.Int64[]	sampleTimestamps	The timestamps requested
SampleModeType	withSampleMode	The SampleModeType which can be used. These are Minimum, Maximum, Mean and First. This is defaulted to Mean. These can be specified as flags to get more than one type
System.Boolean	linearInterpolation	This option only really matters when you are requesting data at a higher frequency than it was collected. For example, if you have low rate data collection at 1hz and request a sample rate of 10hz. This setting is defaulted to be false which means it will extend previous samples to fill the gaps in samples. If this is set to true, returned data is linearly interpolated, so the data changes in the samples will be smoother.
ParameterValuesTemplate	template	Optional template to be populated with samples. This can be used if the client wants to manage the memory to perform it's own memory management/buffering. The use of this is discouraged as the SQL Race memory pooling means it is more efficient in the large object heap and reduces fragmentation. When specifing a template you should follow these rules: You always need a DataStatus array If using the mode type Mean you need a Data array If using the mode type First you need a DataFirst array If using the mode type Minimum you need a DataMin array If using the mode type Maximum you need a DataMax array The arrays must have the length equal or greater to number of samples. If it is greater than the array past the index of the number of samples will be left untouched by this call If you want the timestamps in the result, you must specify a Timestamp array

Returns

Type	Description
ParameterValues	Returns a ParameterValues object containing the resulting data

Remarks

On completion of this call, the CurrentTime will be set to the end of the returned data

Examples

The most simple call to this method, provides just the timestamps. This call will return the mean samples for the given timestamps

pda.GetData(timestamps)

This call will return the first samples for the given timestamps

pda.GetData(timestamps, SampleModeType.First)

This call will return the linearly interpolated mean values for the given timestamps

pda.GetData(timestamps, linearInterpolation: true)

Get minimum and maximum values and populate the given template

pda.GetData(timestamps, SampleModeType.Minimum | SampleModeType.Maximum, interpolate, new ParameterValuesTemplate { DataMin = minimumValues, DataMax = maximumValues, DataStatus = status });

Exceptions

Type	Condition
System.ArgumentException	This is thrown if the timestamps is an empty array or if the length of the arrays in the template are less than the number of timestamps requested
System.ArgumentNullException	This is thrown if timestamps is set to null or if a template is provided, but it does not contain the array definitions it need for the given SampleModeType(s). You need to follow the template definition rules documented.

GetDataStatistics(Int64, Int64, Boolean, StatisticOption, IParameterDataStatistics)

Returns the statistical values requested with statistic option flag(s) for a time range of data.

It takes a show you workings approach. For example when you specify StandardDeviation it will include the sum of values and mean in the result.

Any samples that have a NaN value are skipped.

Declaration

public abstract IParameterDataStatistics GetDataStatistics(long startTimeStamp, long duration, bool weightStatistics = false, StatisticOption statisticOption, IParameterDataStatistics statisticsResult = null)

Parameters

Type	Name	Description
System.Int64	startTimeStamp	Start time of data range in nanoseconds. This number is inclusive so will include the sample at this given timestamp
System.Int64	duration	Length of data range in nanoseconds. This duration is exclusive, it will ignore any sample at the end of the sample range (startTimeStamp + duration)
System.Boolean	weightStatistics	Weight statistics flag, this is defaulted to false. If this is set to true then the mean, absolute mean and standard deviation calculations are weighted against the sample interval
StatisticOption	statisticOption	The statistic to be retrieved. This is defaulted to None which will only return start/end values. This is a flag field so mutiple types of statistics can be requested in one call.
IParameterDataStatistics	statisticsResult	Optional base statistics result

Returns

Type

Description

IParameterDataStatistics

Returns a IParameterDataStatistics object containing the results for the requested statistic options. Depending on the statistic options depends which fields will be populated: AbsoluteMeanValue is populated when AbsoluteMean option is used DeltaValue is populated when the Delta option is used. This value is the delta between the first and last sample. EndValue is always populated with the last value in the sample time range GeometricMeanValue is populated when the GeometricMean sample option is used. Geometric mean cannot be calculated for negative values Lap is always null for GetDataStatistics, it is only used in GetLapStatistics MaximumStatus is populated with the maximum sample's status when Max option is used, otherwise it is defaulted to missing MaximumTime is populated with the maximum sample's timestamp when Max option is used, otherwise it is set to 0 MaximumValue is populated with the maximum sample's value when Max option is used MeanValue is populated when Mean and/or StandardDevation sample options are used MinimumStatus is populated with the minimum sample's status when Min option is used, otherwise it is defaulted to missing MinimumTime is populated with the minimum sample's timestamp when Min option is used, otherwise it is set to 0 MinimumValue is populated with the minimum sample's value when Min option is used NumberOfSamples is always populated with the number of samples used to derive the statistics RegressionInterceptValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) RegressionRSquaredValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) RegressionSlopeValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) SessionKey is always populated with the session key StandardDeviation is populated by specifing the StandardDeviation statistic option. This is calculated using the Population Standard deviation. StartValue is always populated with the first value in the sample time range SumOfAbsoluteSampleValues is populated when AbsoluteMean option is used. If weighted is true this is the sum of values after weighting has been applied SumOfSampleValues is populated when Mean and/or StandardDevation sample options are used. If weighted is true this is the sum of values after weighting has been applied SumOfSquaredSampleValues is populated when StandardDevation sample option is used. If weighted is true this is the sum of values after weighting has been applied TimeRange is always populated with the time range used to derive the statistics NumberOfNansSkipped is always populated with the number of samples which had the value NaN and where therefore skipped.

Remarks

If data is requested data is either before or after samples are available then a zero numberOfSamples will be returned.

Examples

Get the minimum value for the given time range

var result = this.pda.GetDataStatistics(
                        startTime,
                        duration,
                        false,
                        StatisticOption.Min);

Get the Max, Min and Mean for a given time range

pda.GetDataStatistics(
              startTime,
              duration,
              false,
              StatisticOption.Max | StatisticOption.Min | StatisticOption.Mean,
              compositeStatistics);

Exceptions

Type	Condition
System.ArgumentException	Thrown if the startTimeStampis less than zero or duration is less than, or equal to zero.

GetEndTime()

Returns the end time of the parameters data.

Declaration

public abstract Nullable<long> GetEndTime()

Returns

Type	Description
System.Nullable<System.Int64>	The end time.

GetLapStatistics(Lap, Boolean, StatisticOption, IParameterDataStatistics)

Returns the statistical values for the requested lap with statistic option flag(s) for lap time range of data. The calculated statistics will be cached for improved performance. It takes a show you workings approach. For example when you specify StandardDeviation it will include the sum of values and mean in the result.
Any samples that have a NaN value are skipped.

Declaration

public abstract IParameterDataStatistics GetLapStatistics(Lap lap, bool weightStatistics = false, StatisticOption statisticOption, IParameterDataStatistics statisticsResult = null)

Parameters

Type	Name	Description
Lap	lap	The Lap to get statistics for.
System.Boolean	weightStatistics	Weight statistics flag, this is defaulted to false. If this is set to true then the mean, absolute mean and standard deviation calculations are weighted
StatisticOption	statisticOption	The statistic to be retrieved. This is defaulted to None which will only return start/end values. This is a flag field so mutiple types of statistics can be requested in one call.
IParameterDataStatistics	statisticsResult	Optional base statistics result

Returns

Type

Description

IParameterDataStatistics

Returns a IParameterDataStatistics object containing the results for the requested statistic options. Depending on the statistic options depends which fields will be populated: AbsoluteMeanValue is populated when AbsoluteMean option is used DeltaValue is populated when the Delta option is used. This value is the delta between the first and last sample. EndValue is always populated with the last value in the sample time range GeometricMeanValue is populated when the GeometricMean sample option is used. Geometric mean cannot be calculated for negative values Lap is populated with the lap provided MaximumStatus is populated with the maximum sample's status when Max option is used, otherwise it is defaulted to missing MaximumTime is populated with the maximum sample's timestamp when Max option is used, otherwise it is set to 0 MaximumValue is populated with the maximum sample's value when Max option is used MeanValue is populated when Mean and/or StandardDevation sample options are used MinimumStatus is populated with the minimum sample's status when Min option is used, otherwise it is defaulted to missing MinimumTime is populated with the minimum sample's timestamp when Min option is used, otherwise it is set to 0 MinimumValue is populated with the minimum sample's value when Min option is used NumberOfSamples is always populated with the number of samples used to derive the statistics RegressionInterceptValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) RegressionRSquaredValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) RegressionSlopeValue is populated by specifing SlopeIntercept, SlopeRIntercept and/or SlopeRSquared statistic options. X is the sample number and Y is the sample value. For example the samples 10, 11, 12 would be mapped to (1, 10)(2, 11)(3, 12) SessionKey is always populated with the session key StandardDeviation is populated by specifing the StandardDeviation statistic option. This is calculated using the Population Standard deviation. StartValue is always populated with the first value in the sample time range SumOfAbsoluteSampleValues is populated when AbsoluteMean option is used SumOfSampleValues is populated when Mean and/or StandardDevation sample options are used SumOfSquaredSampleValues is populated when StandardDevation sample option is used TimeRange is always populated with the time range used to derive the statistics NumberOfNansSkipped is always populated with the number of samples which had the value NaN and where therefore skipped.

Remarks

If data is requested data is either before or after samples are available then a zero numberOfSamples will be returned.

Examples

Get the minimum value for the given lap

var result = this.pda.GetLapStatistics(
                        lap,
                        false,
                        StatisticOption.Min);

Get the Max, Min and Mean for a given lap

pda.GetLapStatistics(
              lap
              false,
              StatisticOption.Max | StatisticOption.Min | StatisticOption.Mean,
              compositeStatistics);

Exceptions

Type	Condition
System.ArgumentException	Thrown if the laps start is less than zero or if the start time is after the end time
System.ArgumentNullException	Thrown if the lap is null or if the lap does not have an end time

GetMaximumFrequency()

Returns the maximum frequency in Hz.

Declaration

public abstract double GetMaximumFrequency()

Returns

Type	Description
System.Double	The maximum frequency.

Remarks

If zero, then the frequency could not be determined.

GetMaximumSampleRate()

Returns the maximum sample rate available from the channels within the underlying Parameter associated with the PDA.

Declaration

public abstract Nullable<long> GetMaximumSampleRate()

Returns

Type	Description
System.Nullable<System.Int64>	The maximum sample rate.

Remarks

This time returned is in nanoseconds.

GetMinimumFrequency()

Returns the minimum frequency in Hz.

Declaration

public abstract double GetMinimumFrequency()

Returns

Type	Description
System.Double	The minimum frequency.

Remarks

If zero, then the frequency could not be determined.

GetMinimumSampleInterval(Int64, Boolean)

Gets the minimum sample interval.

Declaration

public abstract long GetMinimumSampleInterval(long sampleTime, bool useSubSampledChannels)

Parameters

Type	Name	Description
System.Int64	sampleTime	The sample time.
System.Boolean	useSubSampledChannels	if set to true [use sub sampled channels].

Returns

Type	Description
System.Int64

GetNextData(Int32, SampleModeType, Boolean, ParameterValuesTemplate)

Gets the next sampled data values and DataStatusType based on the number of samples requested and the PDA's current position.

Declaration

public abstract ParameterValues GetNextData(int numberOfSamples, SampleModeType withSampleMode, bool linearInterpolation = false, ParameterValuesTemplate template = null)

Parameters

Type	Name	Description
System.Int32	numberOfSamples	Number of samples to retrieve.
SampleModeType	withSampleMode	The SampleModeType which can be used. These are Minimum, Maximum, Mean and First. This is defaulted to Mean. These can be specified as flags to get more than one type
System.Boolean	linearInterpolation	This option only really matters when you are requesting data at a higher frequency than it was collected. For example, if you have low rate data collection at 1hz and request a sample rate of 10hz. This setting is defaulted to be false which means it will extend previous samples to fill the gaps in samples. If this is set to true, returned data is linearly interpolated, so the data changes in the samples will be smoother.
ParameterValuesTemplate	template	Optional template to be populated with samples. This can be used if the client wants to manage the memory to perform it's own memory management/buffering. The use of this is discouraged as the SQL Race memory pooling means it is more efficient in the large object heap and reduces fragmentation. When specifing a template you should follow these rules: You always need a DataStatus array If using the mode type Mean you need a Data array If using the mode type First you need a DataFirst array If using the mode type Minimum you need a DataMin array If using the mode type Maximum you need a DataMax array The arrays must have the length equal or greater to number of samples. If it is greater than the array past the index of the number of samples will be left untouched by this call

Returns

Type	Description
ParameterValues	Returns a ParameterValues object containing the resulting data

Remarks

On completion of this call, the CurrentTime will be set to the end of the returned data

Examples

This example is the most simple call to the method. It fetches the mean samples which are not linearly interpolated.

  var parameterValues = this.sourcePda.GetNextData(numberOfSamples);

This example gets the next mean, minimum and maximum samples which are linearly interpolated

  var parameterValues = this.sourcePda.GetNextData(numberOfSamples, SampleModeType.Minimum | SampleModeType.Maximum | SampleModeType.Mean, true);

Using the template to populate arrays in the client. This is particularly useful if you want to reuse the same array for multiple calls to perform buffering or object reuse.

 var data = new double[numberOfSamples];
 var status = new DataStatusType[numberOfSamples];
 parameterDataAccess.GetNextData(numberOfSamples, template: new ParameterValuesTemplate { Data = data, DataStatus = status});

If using the template and specifing different sample types, you need to ensure that you have defined the correct arrays in the template to be populated

 parameterDataAccess.GetNextData(numberOfSamples, SampleModeType.Minimum | SampleModeType.Maximum, 
   template: new ParameterValuesTemplate { DataMin = minimumValues, DataMax = maximumValues, DataStatus = dataStatusTypes});

Exceptions

Type	Condition
System.ArgumentException	This is thrown if number of samples requested is less than 1 or if the length of the arrays in the template are less than the number of samples requested
System.ArgumentNullException	This is thrown if a template is provided, but it does not contain the array definitions it need for the given SampleModeType(s). You need to follow the template definition rules documented.

GetNextSamples(Int32, StepDirection, ParameterValuesTemplate)

Returns the next raw data samples, their DataStatusType and time based on the number of samples requested.

Declaration

public abstract ParameterValues GetNextSamples(int numberOfSamples, StepDirection direction, ParameterValuesTemplate template = null)

Parameters

Type	Name	Description
System.Int32	numberOfSamples	Number of samples to retrieve. This has to be larger than 0.
StepDirection	direction	Set this to Reverse if you want to read the previous samples (read backwards)
ParameterValuesTemplate	template	Optional template to be populated with samples. This can be used if the client wants to manage the memory to perform it's own memory management/buffering. The use of this is discouraged as the SQL Race memory pooling means it is more efficient in the large object heap and reduces fragmentation. When specifing a template you should follow these rules: Provide a DataStatus array Prove a Data array Provide a Timestamp Array Avoid providing a DataMin, DataFirst, DataMax or TimeStampValues arrays The arrays must have the length equal or greater to number of samples. If it is greater than the array past the index of the number of samples will be left untouched by this call

Returns

Type	Description
ParameterValues	Returns a ParameterValues object with the Data, Timestamp and DataStatus arrays populated with the results. Use the ParameterValues.SampleCount field to determine how much data to read out of the array. If there are no samples then SampleCount will be 0. The if the template array size is larger than the requested number of samples the extra array space will be left untouched.

Remarks

On completion of this call, the CurrentTime will be set to the end of the returned data

Examples

Example of usage and then iterating over the results using the SampleCount field not the array size.

this.pda.GoTo(startTime);
var pdaSamples = this.pda.GetNextSamples(noOfSamples);
for (var i = 0; i < pdaSamples.SampleCount; i++)
{
    if(pdaSamples.DataStatus[i] != DataStatusType.Missing)
    {
        var data = pdaSamples.Data[i];
        var timestamp = pdaSamples.Timestamp[i]
        //Do something with data
    }
}

This is the same code example, but called using a template.

this.pda.GoTo(startTime);
var pdaSamples = this.pda.GetNextSamples(noOfSamples, template: new ParameterValuesTemplate
               {
                   Data = this.data,
                   DataStatus = this.dataStatus,
                   Timestamp = this.timeStamps
                });
for (var i = 0; i < pdaSamples.SampleCount; i++)
{
    if(this.dataStatus[i] != DataStatusType.Missing)
    {
        var data = this.data[i];
        var timestamp = this.timeStamps[i]
        //Do something with data
    }
}

Exceptions

Type	Condition
System.ArgumentNullException	Thrown if a template is provided without Data, DataStatus or Timestamp arrays
System.ArgumentException	Thrown if; template arrays are too short, the smallest array is less than the number of samples in length or the number of samples is less than 1

GetSamplesBetween(Int64, Int64, Int32)

Gets a number of raw data samples, timestamps and DataStatusType based on the time range between the current position to the end sample time and sample size cap requested.
If the start time is after the end time it will read the data backwards in reverse. The CurrentTime is not updated by this call.

Declaration

public abstract ParameterValues GetSamplesBetween(long startTimeStamp, long endTimeStamp, int sampleSizeCap = 10000)

Parameters

Type	Name	Description
System.Int64	startTimeStamp	The start time stamp for the range to be read. If this is larger than the end time then the data will be read in reverse.
System.Int64	endTimeStamp	The end time stamp for the range to be read. If this is smaller than the start time then the data will be read in reverse.
System.Int32	sampleSizeCap	The maximum number of samples to return, this is defaulted to 10000. If the cap is exceeded it will return the first X number of samples. This is a useful protection in case you query for high resolution data over an extended time.

Returns

Type

Description

ParameterValues

Returns a ParameterValues object with the Data, Timestamp and DataStatus arrays populated with the results. Use the ParameterValues.SampleCount field to determine how much data to read out of the array. If there are no samples then SampleCount will be 0. The array size is allocated by an estimate and then expanded if needed by a factor. Therefore the array size can be bigger than required and have empty data on the end. Because of this nature, there is no feature to allow a ParameterValuesTemplate field.

Remarks

If start and end time are equal then the sample for that timestamp is returned

Examples

Example of usage and then iterating over the results using the SampleCount field not the array size.

var pdaSamples = this.pda.GetSamplesBetween(startTime, endTime, maxSampleCountForPdaCall);
for (var i = 0; i < pdaSamples.SampleCount; i++)
{
    if(pdaSamples.DataStatus[i] != DataStatusType.Missing)
    {
        var data = pdaSamples.Data[i];
        var timestamp = pdaSamples.Timestamp[i]
        //Do something with data
    }
}

Exceptions

Type	Condition
System.ArgumentException	This is thrown if start or end time are minus numbers
System.ArgumentOutOfRangeException	This is thrown if the sampleSizeCap is less than 1

GetSamplesCount(Int64, Int64)

Returns the numbers of samples between a specified start and end time.

Declaration

public abstract long GetSamplesCount(long startTimeStamp, long endTimeStamp)

Parameters

Type	Name	Description
System.Int64	startTimeStamp	Start time stamp of the data.
System.Int64	endTimeStamp	End time stamp of the data.

Returns

Type	Description
System.Int64	Number of samples between the start and end time, or zero if not samples found.

GetSamplesCountEstimate(Int64, Int64)

Returns the theoretical sample count between a specified start and end time based on the highest frequency channel for this PDA's Parameter. If the return value is zero means that was impossible to calculate the sample count, or this PDA is created on a SlowRow parameter

Declaration

public abstract long GetSamplesCountEstimate(long startTimeStamp, long endTimeStamp)

Parameters

Type	Name	Description
System.Int64	startTimeStamp	Start time stamp of the data.
System.Int64	endTimeStamp	End time stamp of the data.

Returns

Type	Description
System.Int64	Theoretical sample count between the start and end time, or zero if it was impossible to calculate, or this PDA is created on a SlowRow parameter.

GetSamplesUntil(Int64, Int32)

Returns a number of raw data samples between the current position to the end sample time. If the endtime is after the CurrentTime then the position will be updated to be the last timestamp + 1.
If the endtime is before the CurrentTime then the position will be updated to be the last timestamp - 1 and the data will be read in reverse. If there are no samples then the PDA position is not updated.

Declaration

public abstract ParameterValues GetSamplesUntil(long endTimeStamp, int sampleSizeCap = 10000)

Parameters

Type	Name	Description
System.Int64	endTimeStamp	The end time stamp. If this is before the PDA current time then it will read backwards to that point.
System.Int32	sampleSizeCap	This is a cap on the amount of samples which will be returned. This is defaulted to 10,000. This is a useful protection in case you query for high resolution data over and extended time. If the cap is exceeded it will return the first X number of samples.. This can be overriden if required

Returns

Type

Description

ParameterValues

Returns a ParameterValues object with the Data, Timestamp and DataStatus arrays populated with the results. Use the ParameterValues.SampleCount field to determine how much data to read out of the array. If there are no samples then SampleCount will be 0. The array size is allocated by an estimate and then expanded if needed by a factor. Therefore the array size can be bigger than the required and have empty data on the end. Because of this nature, there is no feature to allow a ParameterValuesTemplate field.

Remarks

If current time and end time are equal then the sample for that timestamp is returned

Examples

Example of usage and then iterating over the results using the SampleCount field not the array size.

this.pda.GoTo(startTime);
var pdaSamples = this.pda.GetSamplesUntil(endTime);
for (var i = 0; i < pdaSamples.SampleCount; i++)
{
    if(pdaSamples.DataStatus[i] != DataStatusType.Missing)
    {
        var data = pdaSamples.Data[i];
        var timestamp = pdaSamples.Timestamp[i]
        //Do something with data
    }
}

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	Thrown if sampleSizeCap is less than 1
System.ArgumentException	Is thrown if endtime equals the PDa current position or in less than 0

GetStartTime()

Returns the start time for the parameters data.

Declaration

public abstract Nullable<long> GetStartTime()

Returns

Type	Description
System.Nullable<System.Int64>	The start time.

GetTimeRange()

Gets the time range for the PDA.

Declaration

public abstract Nullable<TimeRange> GetTimeRange()

Returns

Type	Description
System.Nullable<TimeRange>	Returns time range or null if there is no data.

GoTo(Double)

Positions the ParameterDataAccess object to a specific position (i.e. when the X Axis is not Time) within the parameter's data. This value can be used to set the start point for GetNextData calls.

Declaration

public virtual void GoTo(double position)

Parameters

Type	Name	Description
System.Double	position	Required position.

GoTo(Int64)

Positions the ParameterDataAccess object to a specific time within the parameter's data. This value can be used to set the start point for GetNextData calls.

Declaration

public virtual void GoTo(long time)

Parameters

Type	Name	Description
System.Int64	time	Required time location in nano-seconds.

GuardAgainstInvocationWhenInvalidated()

Guards against invocation when invalid

Declaration

protected void GuardAgainstInvocationWhenInvalidated()

Exceptions

Type	Condition
System.InvalidOperationException	PDA has been invalidated

OnInvalidated()

Called when [invalidated].

Declaration

protected virtual void OnInvalidated()

Search(Int64, Int64, MatchingRule, Double, Nullable<Double>, Nullable<Int32>)

Search PDA for all occurances of a data value

Declaration

public abstract IList<QuerySample> Search(long startAt, long endAt, MatchingRule rule, double value, Nullable<double> upperValue, Nullable<int> timespan)

Parameters

Type	Name	Description
System.Int64	startAt	Seach Start Position
System.Int64	endAt	Search End Position
MatchingRule	rule	Comparison operator
System.Double	value	Value to Search For
System.Nullable<System.Double>	upperValue	Upper Value - used when using the Between Operator
System.Nullable<System.Int32>	timespan	Period of time the condition must be met for

Returns

Type	Description
System.Collections.Generic.IList<QuerySample>	Matching samples

Search(Int64, Int64, MatchingRule, String, Nullable<Int32>)

Search PDA for all occurances of a data value

Declaration

public abstract IList<QuerySample> Search(long startAt, long endAt, MatchingRule rule, string value, Nullable<int> timespan)

Parameters

Type	Name	Description
System.Int64	startAt	Seach Start Position
System.Int64	endAt	Search End Position
MatchingRule	rule	Comparison operator
System.String	value	Value to Search For
System.Nullable<System.Int32>	timespan	Period of time the condition must be met for

Returns

Type	Description
System.Collections.Generic.IList<QuerySample>	Matching samples

SetMapper(String)

Sets the mapper for the PDA.

Declaration

public abstract void SetMapper(string mapper)

Parameters

Type	Name	Description
System.String	mapper	The name of the mapper.

SetSampleIncrement(Double)

Sets the current sample increment for the PDA, when the X Axis is not Time

Declaration

public virtual void SetSampleIncrement(double increment)

Parameters

Type	Name	Description
System.Double	increment	The required sample increment.

SetSampleIncrement(Int64)

Sets the current sample increment for the PDA, in nanoseconds (supersedes SampleTime). This value will only affect requests to get data (using the GetNextData method ) and will not affect calls to get samples (using the GetSamples/GetNextSamples/GetPreviousSamples/GetSamplesUntil methods).

Declaration

public virtual void SetSampleIncrement(long increment)

Parameters

Type	Name	Description
System.Int64	increment	The required sample increment

Remarks

This time is the interval between data samples. For example: 1,000,000 ns = 1000Hz 10,000,000 ns = 100Hz 100,000,000 ns = 10Hz 1,000,000,000 ns = 1Hz If this value is not set then the default sample time is 100Hz (10,000,000 ns).

ValidateArguments<T, TU>(Int32, T[], TU[])

Validates the arguments.

Declaration

protected void ValidateArguments<T, TU>(int numberOfSamples, T[] first, TU[] second)

Parameters

Type	Name	Description
System.Int32	numberOfSamples	The number of samples.
T[]	first	The first.
TU[]	second	The second.

Type Parameters

Name	Description
T	Array type 1.
TU	Array type 2.

ValidateArguments<T, TU, TV>(Int32, T[], TU[], TV[])

Validates the arguments.

Declaration

protected void ValidateArguments<T, TU, TV>(int numberOfSamples, T[] first, TU[] second, TV[] third)

Parameters

Type	Name	Description
System.Int32	numberOfSamples	The number of samples.
T[]	first	The first.
TU[]	second	The second.
TV[]	third	The third.

Type Parameters

Name	Description
T	Array type 1.
TU	Array type 2.
TV	Array type 3.

ValidateSampleTime()

Validates the sample time.

Declaration

protected void ValidateSampleTime()

ValidateStartAndEndTime(Int64, Int64)

Validates the start and end time.

Declaration

protected static void ValidateStartAndEndTime(long endTimeStamp, long startTimeStamp)

Parameters

Type	Name	Description
System.Int64	endTimeStamp	The end time stamp.
System.Int64	startTimeStamp	The start time stamp.

ValidateStartPositionOfPda()

Check that the client has positioned this object to a start position.

Declaration

protected long ValidateStartPositionOfPda()

Returns

Type	Description
System.Int64	Returns current position.

Events

Invalidated

Occurs when this PDA has been invalidated.

Declaration

public abstract event EventHandler Invalidated

Event Type

Type	Description
System.EventHandler

UnderlyingDataSourceChanged

Occurs when the underlying data source has been changed. This event will be raised if the source data context of this PDA changes - any previously-requested data is invalid.

Declaration

public abstract event EventHandler UnderlyingDataSourceChanged

Event Type

Type	Description
System.EventHandler

Implements

IParameterDataAccess

System.IDisposable