User manual

Programmer’s Guide Page 37 of 66
3.11.1. Reading Digitizer Waveforms with the Universal Read Function
For the general case, which includes the reading of more complex waveforms, we provide a universal read function
AcqrsD1_readData.
Control of the read parameters is passed through the input structure AqReadParameters. For the description of the
output data an array of segment descriptors, AqSegmentDescriptor, and a waveform descriptor,
AqDataDescriptor, are returned. These structures are defined in the header file AcqirisDataTypes.h.
The following parameter setting can be used for reading a single waveform segment in 8-bit representation.
static long nbrSegments = 1; // readMode = 0 requires this value
const long nbrPoints = 1000;
char dataArray[nbrPoints+32];
AqReadParameters *readPar = new AqReadParameters;
AqDataDescriptor *dataDesc = new AqDataDescriptor;
AqSegmentDescriptor *segDesc = new AqSegmentDescriptor[nbrSegments];
readPar->dataType = 0; // 0 = byte
readPar->readMode = 0; // 0 = standard waveform
readPar->nbrSegments = nbrSegments;
readPar->firstSampleInSeg = 0;
readPar->segmentOffset = 0; // unused parameter
readPar->firstSegment = 0;
readPar->nbrSamplesInSeg = nbrPoints;
readPar->dataArraySize = sizeof(dataArray);
readPar->segDescArraySize = sizeof(AqSegmentDescriptor)*nbrSegments;
readPar->flags = 0;
readPar->reserved = 0;
readPar->reserved2 = 0.0;
readPar->reserved3 = 0.0;
status = AcqrsD1_readData(instrID, channel, readPar, dataArray ,
dataDesc, segDesc);
Comments:
The segment numbers run from 0 to nbrSegments-1.
The value of segDesc->horPos is the time interval in seconds between the first data point and the nominal time
origin of the trigger delay. It is always in the range [-sampTime, 0]. It is useful for a very precise positioning, to
a fraction of the sampling interval, of the waveform. In many applications, it can be ignored. Refer to section
3.14, HORIZONTAL PARAMETERS IN ACQUIRED WAVEFORMS, for a detailed explanation of horPos.
Return values have to be interpreted in the same way as for the other readout functions.
Refer to the section 3.15, SEQUENCE ACQUISITIONS for detailed explanations on the interpretation of
segDesc->timeStampLo/Hi.
It is important to zero the unused parameters at the end of the readPar structure. An incorrect value of flags can
be very confusing.
3.11.2. Reading Sequences of Waveforms
In certain situations, see APPENDIX A: ESTIMATING DATA TRANSFER TIMES, it can be more efficient (in
time) to read Sequence Waveforms with readMode = 1 (ReadModeSeqW). This mode transfers all of the data from
the digitizer to the local memory in a single DMA as opposed to calling AcqrsD1_readData many times thus using
a transfer per segment. The price to be paid is a higher memory requirement. It can also be used to transfer blocks of
segments in the case of very large memories.
For dataType = 0 or 1, the amount of memory needed (in bytes) is
arraySize ≥ (nbrSamplesNom + currentSegmentPad) * (nbrSegments+1) * (dataType + 1)