« Close

Datasheets and User Guides

App Notes

Software & Driver

 

2.4.2 - eStreamRead

Returns data from an initialized and running LJM stream buffer. Waits for data to become available, if necessary.

Syntax

LJM_ERROR_RETURN LJM_eStreamRead(
                int Handle, 
                double * aData, 
                int * DeviceScanBacklog, 
                int * LJMScanBacklog)

Parameters

Handle [in]
A device handle. The handle is a connection ID for an active device. Generate a handle with LJM_Open or LJM_OpenS.
aData [out]
An array that contains the values being read. Returns all channels interleaved. Must be large enough to hold (ScansPerRead * NumAddresses) values, where ScansPerRead and NumAddresses are values passed to LJM_eStreamStart. The data returned is removed from the LJM stream buffer.
DeviceScanBacklog [out]
The number of scans left in the device buffer, as measured from when data was last collected from the device. DeviceScanBacklog should usually be near zero and not growing.
LJMScanBacklog [out]
The number of scans left in the LJM buffer, which does not include concurrent data sent in the aData array. LJMScanBacklog should usually be near zero and not growing.

Returns

LJM errorcodes or 0 for no error.

Remarks

Before calling this function, create a data buffer using LJM_eStreamStart. To stop stream, use LJM_eStreamStop.

If LJM_eStreamRead gives error 1301 (LJME_LJM_BUFFER_FULL) or many -9999 values in aData, here are some strategies to help.

Example

See the LJM_eStreamStart page for an example using LJM_eStreamRead.

2 comments

Is it generally advised to periodically run this method to read the stream at a specified rate (dependent on your scan rate and buffer size), or is it better to use the LJM_SetStreamCallback and read the stream only from within the callback (BTW - I can't find the SetStreamCallback function in the documentation for the LJM lib)? Also I wish to understand the DeviceScanBacklog  parameter. Does this become non-zero when the output data size exceeds ScansPerRead * NumAddresses as dictated by  LJM_eStreamStart before the data gets a chance to unload?

Thanks,

Ian 

Hi Ian,

LJM_eStreamRead is usually a sufficient way to read stream data. Using the default configurations, LJM_eStreamRead will block until a full read of data has been collected. In other words, if you don't need to worry about updating a GUI or anything, LJM_eStreamRead is probably the easiest way to read stream data.

The DeviceScanBacklog parameter is basically the device-reported number of scans on the device's buffer. For a contrived example, if the device has collected 2 scans, then sends 1 scan, 1 scan will be left in the device buffer, and DeviceScanBacklog will be 1. (DeviceScanBacklog will always be reported in the same way -- it will not be affected by ScansPerRead or NumAddresses.)

In a healthy stream, LJM should have ample processor time to read scans from the device, so DeviceScanBacklog should remain small. However, if LJM starts falling behind, this value will begin to increase. If this value increases enough, stream on the device will "pause" and enter auto-recovery mode. More information on the T7's stream characteristics, including auto-recovery mode, can be found on the stream-mode page of the T7 datasheet.

More information on LJM_SetStreamCallback to come.