VTI Instruments EX1000A, User Manual, Page: 115 / 320

www.vtiinstruments.com
EX10xxA Programming 115
There are two ways for the execution to complete. The most obvious way is for the requested number
of scans to actually be delivered by the EX10xxA. This is considered to be successful execution.
The other way is for a specified timeout period to elapse. In this case, the full number of requested
scans was not delivered; this is considered an execution error. However, there are applications where
this is the expected and desired behavior, and all data returned is completely valid, despite this being
technically an error condition. These concepts are clarified below.
This function accepts the following parameters:

the maximum number of scans to return ( maxscans ). This represents the desired number of
scans to retrieve. If FIFO count ≥
maxscans at the time of function issuance, then maxscans
are returned, and the function completes. If, however, FIFO count < maxscans at the time of
function issuance, the function will continue to poll the EX10xxA for data until maxscans are
returned or the timeout period ( to_secs ) is reached (see below).

a return array of scan start times ( ts_secs[] ), specified in seconds since the epoch (Jan. 1,
1970). To ensure data integrity, the declared dimension of ts_secs[] must be at least as large
as maxscans .

a return array of scan start times ( ts_fsecs[] ), specified in seconds since the last full second
represented in ts_secs[]. To ensure data integrity, the declared dimension of ts_fsecs[] must
be at least as large as maxscans .

a return value indicating the actual number of scans retrieved ( numscans ). If the function
completed by reaching maxscans , then numscans will be equal to maxscans . If, however, the
function completed by the timeout period, numscans will be less than maxscans .

the maximum length of the return data array ( maxdata ). This should specifically be the
declared dimension of the data[] array (see below). To ensure data integrity, maxdata must be
no less than maxscans multiplied by the number of channels in the scan list. Since data is
retrieved from the FIFO according to the maxscans parameter and not the maxdata parameter,
if maxdata is set too low, there is the possibility of data being permanently lost.

a return array of sample data ( data[] ).

a return value indicating the actual number of samples retrieved ( numdata) . This will be equal
to the lesser of maxdata or numscans multiplied by the number of channels in the scan list.

a timeout period in seconds ( to_secs ) that represents how long to poll the EX10xxA for data
(in an attempt to retrieve maxscans ). A value of 0 is used to indicate an infinite timeout
period.
The importance of the to_secs parameter depends on the trigger model configuration employed. In
a typical application where the ARM source is set to Immediate and the TRIG source is set to Timer,
the amount of data to be acquired and the time required to acquire that data are deterministic.
Specifically, upon the trigger initialize function, there will be a quantity of scans acquired that equals
TRIG count, acquired over a total time that is TRIG count multiplied by the timer interval. For
example, 500 scans taken with a timer interval of 5 ms would require 2.5 s. In this case,
to_secs
would normally be set to an arbitrary value greater than 2.5. In this case, function completion via
the timeout period does indeed represent an error condition.
By contrast, consider an application where data is desired from the EX10xxA only once a certain
test condition has occurred. Accordingly, the ARM source is set to a specific condition of the digital
I/O port. Moreover, this digital event is created asynchronously by a stimulus system being
controlled by the same application that is taking EX10xxA data. The logic of the control application
is such that the stimulus system is increased to a new value and then the EX10xxA is polled for data.
If data is returned, then the EX10xxA was triggered, and no further increase in the stimulus system
is required. If no data is returned after a specified period, then the stimulus system is increased
further. In this case, the timeout period value is important, as it determines the frequency at which
the stimulus system is updated. Moreover, it is completely expected that the
vtex10xxA_read_fifo
function initially completes due to the timeout period, and so this does not represent an error
condition that requires intervention.
Example: This code block reads the FIFO after a timer-based scan.