Measurement Computing Data Acquisition Systems rev.10.4 - Manual (Page 113)

Function Usage
Data Retrieval Buffer
Upon completion of this function, the data retrieval buffer (buf) contains the requested data from the driver
buffer (if the data was retrieved – see the “Data Retrieval Modes” section below). The buffer must be
allocated by the application prior to calling this function. The diagram below illustrates the path of data
transfer:
The scanCount parameter defines the number of scans to be retrieved (or the length of the data retrieval
buffer in scans). The size of a scan is determined by the total number of channels in the scan group
configuration (see the daqAdcSetScan function for further information on scan group configuration).
Therefore the size of the data retrieval buffer to be allocated (in bytes) should be no smaller than:
scanCount * scan size (number of channels) * sample size (normally 2 bytes)
If using packed mode with a WaveBook/512, the above calculation should be multiplied by ¾ to
determine actual buffer allocation size required.
Data Retrieval Modes
The following values for the bufMask parameter set how recent the transferred data is and whether or not it
remains in the buffer after transfer:
DabtmOldest – This value specifies that the specified number of the earliest scans be retrieved from the
driver buffer. After they have been transferred, they will be removed from the buffer.
DabtmNewest – This value specifies that the specified number of the most recent scans be retrieved from
the driver buffer. These scans will remain in the buffer after transfer.
The following values can be set concurrently with the values above. They specify the timing of the retrieval
and the amount of data to transfer from the driver buffer:
DabtmWait – Instructs the function to wait until the requested number of scans (scanCount) are available
in the driver-allocated acquisition buffer. When the requested number of scans are available, the function will
return with retCount set to scanCount (the number of scans requested). Retrieved data will be returned
in the memory referred to by the buf parameter. Returns if the daqSetTimeout value is exceeded.
DabtmNoWait – Instructs the function to return immediately if the specified number of scans (scanCount)
are not available when the function is called. If the entire amount requested is not available, the function will
return with no data and retCount will be set to 0. If the requested number of scans are available in driver
buffer, the function will return with retCount set to scanCount (the number of scans requested).
Retrieved data will be returned in the memory referred to by the buf parameter.
DabtmRetAvail – Instructs the function to return immediately, with any scans that are available in the
driver-allocated acquisition buffer. The retCount parameter will return the total number of scans retrieved.
retCount
can return anything from 0 to scanCount (the number of scans requested). The retrieved data
will be returned in the memory referred to by the buf parameter.
DabtmRetNotDone – Instructs the function to return immediately if the acquisition is still active without
retrieving any data. If the acquisition is still active, the retCount parameter will return 0. If the acquisition
is complete, then retCount can return anything from 0 to scanCount (the number of scans requested).
The retrieved data will be returned in the memory referred to by the buf parameter.
Programmer’s Manual 908594 Daq API Command Reference 4.2-57