<< Click to Display Table of Contents >> Navigation:  NmxDLL Reference Guide > API (programming interface) > Sampling LowLevel (Time-Triggered Realtime Measurement) > NMX_Sampling_ReadColumn32_1

Read sampled values column-wise. Column-wise means, that multiple samples of the same sampling element are read-out. This could for example be samples 0..999 from measurement channel 1.

See also the HowTo-Guide.

 

Definition

---

NMX_STATUS NMX_Sampling_ReadColumn32_1(

 NMX_PHANDLE pHandle,

 signed long aslSamples[],

 unsigned long ulMaxSamples,

 unsigned long ulElementNo,

 unsigned long ulDoNotDelete,

 unsigned long* pulSamplesCopied,

 unsigned long long* pudNoFirstSample);

 

Parameter

---

pHandle

Connection Handle.

aslSamples

The measurement samples will be written into this array. For simplicity, all sampled values are provided with data type signed long. See chapter "data types" for more information.

ulMaxSamples

Maximum number of samples to read-out. This value must be ≤ the total number of elements of aslSamples.
Example: aslSamples is defined as "signed long aslSamples[1000]". Then ulMaxSamples must be ≤ 1000.

ulElementNo

Number of the sampling element, starting with 0 for the first sampling element.

ulDoNotDelete

0: samples will be deleted from the DLL-internal buffer after readout.
1: samples will NOT be deleted from the DLL-internal buffer after readout.

pulSamplesCopied

Number of samples copied into aslSamples. This value will be ≤ ulMaxSamples.

pudNoFirstSample

Number of the first sample in aslSamples, counted from the beginning of sampling, starting at 0.
Example:
The 1. time after the start of sampling, this function is called and 162 samples are read-out. pudNoFirstSample = 0 will be returned.
The 2. time this function is called, 97 samples are read-out. pudNoFirstSample = 162 will be returned.
The 3. time this function is called, 212 samples are read-out. pudNoFirstSample = 259 will be returned (162 + 97 = 259).

 

Typical function call (C example)

---

Assuming aslSamples is defined as: signed long aslSamples[10000];

Example 1: NMX_Sampling_ReadColumn32_1(pHandle, aslSamples, 10000, 4, 0, &ulSamplesCopied, &udNoFirstSample);

Example 2: NMX_Sampling_ReadColumn32_1(pHandle, &aslSamples[162], 10000-162, 4, 0, &ulSamplesCopied, &udNoFirstSample);

 

.Net DLL specific implementation

---

NMX_MSTATUS Sampling_ReadColumn32_1(

                 System::IntPtr pHandle,

                 array<System::Int32>^aslSamples,

                 System::UInt32 ulArrayIndex,

                 System::UInt32 ulMaxSamples,

                 System::UInt32 ulElementNo,

                 System::UInt32 ulDoNotDelete,

                 System::UInt32 %pulSamplesCopied,

                 System::UInt64 %pudNoFirstSample);

 

The array aslSamples will not be resized within the function call for performance reasons. This means it should be large enough to store all the data.

Via the parameters ulArrayIndex and ulMaxSamples, it can be defined in which area of aslSamples the sampled data can be written. This is especially helpful, if the sampled data is read in multiple blocks of data (-> no additional copying required).

If the sampled data is read at once, typically ulArrayIndex = 0 and ulMaxSamples = aslSamples.Length.

 

Comments

---

•The standard way is deleting sampled data inside the NMX DLL, after it has been read-out. This is done by setting: ulDoNotDelete = 0;
If you want to be able to read it out more than once, it is possible to set ulDoNotDelete = 1;. Naturally this makes no sense for endless sampling!

•It is possible to get informed about new data by the notification NMXNOTIFY_SAMPLING_NEW_DATA.

•It is good practice reading sampled data in small portions, for example each time new data has arrived at the DLL.