This section contains all data retrieving related functions. More...

Functions
uint64_t	ScpGetData (TpDeviceHandle_t hDevice, float **pBuffers, uint16_t wChannelCount, uint64_t qwStartIndex, uint64_t qwSampleCount)
	Get the measurement data for specified channels.

uint64_t	ScpGetData1Ch (TpDeviceHandle_t hDevice, float *pBufferCh1, uint64_t qwStartIndex, uint64_t qwSampleCount)
	Get the measurement data for the first channel.

uint64_t	ScpGetData2Ch (TpDeviceHandle_t hDevice, float pBufferCh1, float pBufferCh2, uint64_t qwStartIndex, uint64_t qwSampleCount)
	Get the measurement data for the first two channels.

uint64_t	ScpGetData3Ch (TpDeviceHandle_t hDevice, float pBufferCh1, float pBufferCh2, float *pBufferCh3, uint64_t qwStartIndex, uint64_t qwSampleCount)
	Get the measurement data for the first three channels.

uint64_t	ScpGetData4Ch (TpDeviceHandle_t hDevice, float pBufferCh1, float pBufferCh2, float pBufferCh3, float pBufferCh4, uint64_t qwStartIndex, uint64_t qwSampleCount)
	Get the measurement data for the first four channels.

uint64_t	ScpGetValidPreSampleCount (TpDeviceHandle_t hDevice)
	Get the number of valid pre samples in the measurement.

void	ScpChGetDataValueRange (TpDeviceHandle_t hDevice, uint16_t wCh, double pMin, double pMax)
	Get the minimum and maximum values of the input range the current data was measured with.

double	ScpChGetDataValueMax (TpDeviceHandle_t hDevice, uint16_t wCh)
	Get the maximum value of the input range the current data was measured with.

double	ScpChGetDataValueMin (TpDeviceHandle_t hDevice, uint16_t wCh)
	Get the minimum value of the input range the current data was measured with.

Detailed Description

This section contains all data retrieving related functions.

When a measurement is performed, the data is stored inside the instrument. When no pre samples are selected (pre sample ratio = 0), the trigger point is located at the start of the record and all samples are measured post samples.

When pre samples are selected (pre sample ratio > 0), the trigger point is located at position (pre sample ratio * record length), dividing the record in pre samples and post samples.

When after starting the measurement a trigger occurs before all pre samples are measured, not all pre samples will be valid. Invalid pre samples are set to 0 V. Use ScpGetValidPreSampleCount to determine the amount of valid pre samples. See trigger hold off to force all pre samples to be measured.

When retrieving the measured data, the full record can be get, including the invalid presamples. The start index needs to be set to 0 then. It is also possible to get only the valid samples. In that case, the start index needs to be set to ( record length - ( number of post samples + number of valid pre samples ).

Example:

uint64_t qwPostSamples = llround( ( 1 - ScpGetPreSampleRatio( hScp ) ) * ScpGetRecordLength( hScp ) );
uint64_t qwValidSamples = qwPostSamples + ScpGetValidPreSampleCount( hScp );
uint64_t qwStart = ScpGetRecordLength( hScp ) - qwValidSamples;
uint64_t qwSamplesRead = ScpGetData1Ch( hScp , pDataCh1 , qwStart , qwValidSamples );

The data retrieval functions use buffers to store the measured data in. The caller must assure that enough memory is allocated for the buffer, to contain all data.

Several routines are available to get the measured data, one universal applicable routine and a number of dedicated routines, to collect data from specific channels.

Additionally, routines are available to retrieve range information of the measured data. Once a measurement is ready, the input range of a channel can be changed, e.g. by the auto ranging function or by the user. The input range will then no longer match with the range of the measured data. Use these routines to determine the actual range of the measured data.

Function Documentation

uint64_t ScpGetData	(	TpDeviceHandle_t	hDevice,
		float **	pBuffers,
		uint16_t	wChannelCount,
		uint64_t	qwStartIndex,
		uint64_t	qwSampleCount
	)

Get the measurement data for specified channels.

This routine is used to get measured data from specific channels. It uses an array or pointers to data buffers to indicate from which channels the data must be get. NULL pointers can be used to indicate that no data needs to be get for a specific channel.

Examples:

To get data from channels 1 and 2 of the oscilloscope, create a pointer array with two pointers: { pDataCh1 , pDataCh2 } and set wChannelCount to 2.

To get data from channels 2 and 4 of the oscilloscope, create a pointer array with four pointers: { NULL , pDataCh2 , NULL , pDataCh4 } and set wChannelCount to 4.

uint64_t qwPostSamples = llround( ( 1 - ScpGetPreSampleRatio( hScp ) ) * ScpGetRecordLength( hScp ) );
uint64_t qwValidSamples = qwPostSamples + ScpGetValidPreSampleCount( hScp );
uint64_t qwStart = ScpGetRecordLength( hScp ) - qwValidSamples;
// Allocate memory for active channels:
float** ppChannelData = malloc( sizeof( float* ) * wChannelCount );
for( wCh = 0 ; wCh < wChannelCount ; wCh++ )
  if( ScpChGetEnabled( hScp , wCh ) )
    ppChannelData[ wCh ] = malloc( sizeof( float ) * qwValidSamples );
  else
    ppChannelData[ wCh ] = NULL;
// Get data:
uint64_t qwSamplesRead = ScpGetData( hScp , ppChannelData , wChannelCount , qwStart , qwValidSamples );
// do something with the data.
// Free memory:
for( wCh = 0 ; wCh < wChannelCount ; wCh++ )
  free( ppChannelData[ wCh ] );
free( ppChannelData );

Parameters

hDevice	A device handle.
pBuffers	Pointer to a buffer with pointers to buffers for channel data, the pointer buffer may contain `NULL` pointers.
wChannelCount	Number of pointers in the pointer buffer.
qwStartIndex	Position in the record to start reading.
qwSampleCount	Number of samples to read.

Returns: Number of samples read.

See Also: Pointer array

uint64_t ScpGetData1Ch	(	TpDeviceHandle_t	hDevice,
		float *	pBufferCh1,
		uint64_t	qwStartIndex,
		uint64_t	qwSampleCount
	)

Get the measurement data for the first channel.

Parameters

hDevice	A device handle.
pBufferCh1	Pointer to buffer for channel 1 data or `NULL`.
qwStartIndex	Position in the record to start reading.
qwSampleCount	Number of samples to read.

Returns: Number of samples read.

uint64_t ScpGetData2Ch	(	TpDeviceHandle_t	hDevice,
		float *	pBufferCh1,
		float *	pBufferCh2,
		uint64_t	qwStartIndex,
		uint64_t	qwSampleCount
	)

Get the measurement data for the first two channels.

Parameters

hDevice	A device handle.
pBufferCh1	Pointer to buffer for channel 1 data or `NULL`.
pBufferCh2	Pointer to buffer for channel 2 data or `NULL`.
qwStartIndex	Position in the record to start reading.
qwSampleCount	Number of samples to read.

Returns: Number of samples read.

uint64_t ScpGetData3Ch	(	TpDeviceHandle_t	hDevice,
		float *	pBufferCh1,
		float *	pBufferCh2,
		float *	pBufferCh3,
		uint64_t	qwStartIndex,
		uint64_t	qwSampleCount
	)

Get the measurement data for the first three channels.

Parameters

hDevice	A device handle.
pBufferCh1	Pointer to buffer for channel 1 data or `NULL`.
pBufferCh2	Pointer to buffer for channel 2 data or `NULL`.
pBufferCh3	Pointer to buffer for channel 3 data or `NULL`.
qwStartIndex	Position in the record to start reading.
qwSampleCount	Number of samples to read.

Returns: Number of samples read.

uint64_t ScpGetData4Ch	(	TpDeviceHandle_t	hDevice,
		float *	pBufferCh1,
		float *	pBufferCh2,
		float *	pBufferCh3,
		float *	pBufferCh4,
		uint64_t	qwStartIndex,
		uint64_t	qwSampleCount
	)

Get the measurement data for the first four channels.

Parameters

hDevice	A device handle.
pBufferCh1	Pointer to buffer for channel 1 data or `NULL`.
pBufferCh2	Pointer to buffer for channel 2 data or `NULL`.
pBufferCh3	Pointer to buffer for channel 3 data or `NULL`.
pBufferCh4	Pointer to buffer for channel 4 data or `NULL`.
qwStartIndex	Position in the record to start reading.
qwSampleCount	Number of samples to read.

Returns: Number of samples read.

uint64_t ScpGetValidPreSampleCount ( TpDeviceHandle_t hDevice )

Get the number of valid pre samples in the measurement.

When pre samples are selected (pre sample ratio > 0), the trigger point is located at position (pre sample ratio * record length), dividing the record in pre samples and post samples.

When after starting the measurement a trigger occurs before all presamples are measured, not all pre samples will be valid.

Parameters

hDevice A device handle.

Returns: The number of valid pre samples.

void ScpChGetDataValueRange	(	TpDeviceHandle_t	hDevice,
		uint16_t	wCh,
		double *	pMin,
		double *	pMax
	)

Get the minimum and maximum values of the input range the current data was measured with.

Parameters

hDevice	A device handle.
wCh	Channel number, `0` to `ScpGetChannelCount() - 1`.
pMin	Pointer to buffer for the minimum value of the range or `NULL`.
pMax	Pointer to buffer for the maximum value of the range or `NULL`.

See Also: ScpChGetDataValueMin; ScpChGetDataValueMax

double ScpChGetDataValueMax	(	TpDeviceHandle_t	hDevice,
		uint16_t	wCh
	)

Get the maximum value of the input range the current data was measured with.

Parameters

hDevice	A device handle.
wCh	Channel number, `0` to `ScpGetChannelCount() - 1`.

Returns: The maximum value of the input range the current data was measured with.

See Also: ScpChGetDataValueMin; ScpChGetDataValueRange

double ScpChGetDataValueMin	(	TpDeviceHandle_t	hDevice,
		uint16_t	wCh
	)

Get the minimum value of the input range the current data was measured with.

Parameters

hDevice	A device handle.
wCh	Channel number, `0` to `ScpGetChannelCount() - 1`.

Returns: The minimum value of the input range the current data was measured with.

See Also: ScpChGetDataValueMax; ScpChGetDataValueRange

Functions

Detailed Description

Function Documentation