Fetching Multiple-Record Acquisitions

You use the same Fetch functions discussed in Acquisition Functions—Reading versus Fetching for retrieving multirecord acquisitions. However, two additional attributes are available for specifying which records to retrieve. The Fetch Record Number attribute is the zero-based index of the first record to fetch, and the Fetch Number of Records attribute specifies how many records to fetch. By default, the Fetch Number of Records is –1, which means fetch all the records starting at the Fetch Record Number.

The Fetch functions wait for specified number of samples to be acquired when the timeout parameter is positive. During a multirecord acquisition, they wait for the requested number of samples in each record. Because the number of records attribute defaults to –1 (or all the records), Fetch functions wait for all the specified number of samples in all the records.

Fetching multiple records with a single Fetch function requires understanding the order of the returned waveforms. All record 0 waveforms come before all record 1 waveforms. For example, fetching data with a channel list of "0,1" for three records results in the following order:

• Channel 0 Record 0
• Channel 1 Record 0
• Channel 0 Record 1
• Channel 1 Record 1
• Channel 0 Record 2
• Channel 1 Record 2

For C and Visual Basic users, the waveforms are all packed into a one-dimensional array that is declared using code such as the following:

// Set numWfms to 6, because the acquisition is for 2 channels times 3 records. niScope_ActualNumWfms (vi, "0,1", &numWfms); // Fetch the coerced record length niScope_ActualRecordLength (vi, &actualRecordLength); // Declare memory for the waveforms and waveform info structs wfm = malloc (sizeof (ViReal64) * actualRecordLength * numWfms); wfmInfo = malloc (sizeof (struct niScope_wfmInfo) * numWfms);

The first waveform starts at wfm[0], the second waveform at wfm[actualRecordLength], and so on.

For LabVIEW users, the waveforms are returned in either a two-dimensional array or an array of clusters that include timing information. In both cases, you can use the index array function to extract the waveform of interest.

You can also fetch each record individually by setting the Fetch Number of Records parameter to 1. Then, in a loop set the Fetch Record Number attribute to the zero-based index of the record you want to fetch and call one of the Fetch functions.