binblockread

(To be removed) Read binblock data from instrument

This serial, Bluetooth, tcpip, udp, visa, and gpib object function will be removed in a future release. Use serialport, bluetooth, tcpclient, tcpserver, udpport, and visadev object functions instead. For more information on updating your code, see Version History.

Syntax

A = binblockread(obj)
A = binblockread(obj,'precision')
[A,count] = binblockread(...)
[A,count,msg] = binblockread(...)

Arguments

obj

An interface object.

'precision'

The number of bits read for each value, and the interpretation of the bits as character, integer, or floating-point values.

A

Binblock data returned from the instrument.

count

The number of values read.

msg

A message indicating if the read operation was unsuccessful.

Description

A = binblockread(obj) reads binary-block (binblock) data from the instrument connected to obj and returns the values to A. The binblock format is described in the binblockwrite reference pages.

A = binblockread(obj,'precision') reads binblock data translating the MATLAB® values to the precision specified by precision. By default the uchar precision is used and numeric values are returned in double-precision arrays. Refer to the fread function for a list of supported precisions.

[A,count] = binblockread(...) returns the number of values read to count.

[A,count,msg] = binblockread(...) returns a warning message to msg if the read operation did not complete successfully.

Examples

Create the GPIB object g associated with a National Instruments™ GPIB controller with board index 0, and a Tektronix® TDS 210 oscilloscope with primary address 2.

g = gpib('ni',0,2);
g.InputBufferSize = 3000;

Connect g to the instrument, and write string commands that configure the scope to transfer binary waveform data from memory location A.

fopen(g)
fprintf(g,'DATA:DESTINATION REFA');
fprintf(g,'DATA:ENCDG SRPbinary');
fprintf(g,'DATA:WIDTH 1');
fprintf(g,'DATA:START 1');

Write the CURVE? command, which prepares the scope to transfer data, and read the data using the binblock format.

fprintf(g,'CURVE?')
data = binblockread(g);

If the scope sends a terminating character after the binblock, binblockread does not read the terminating character. Read it by using fread. In this example, count is the number of bytes of the terminating character and can be 1 or 2.

if g.BytesAvailable == count
   fread(g,count,'uint8');
end

Tips

Before you can read data from the instrument, it must be connected to obj with the fopen function. A connected interface object has a Status property value of open. An error is returned if you attempt to perform a read operation while obj is not connected to the instrument.

binblockread blocks the MATLAB Command Window until one of the following occurs:

  • The data is completely read.

  • The time specified by the Timeout property passes.

If msg is not included as an output argument and the read operation was not successful, then a warning message is returned to the command line.

Each time binblockread is issued, the ValuesReceived property value is increased by the number of values read.

Some instruments may send a terminating character after the binblock. binblockread will not read the terminating character. You can read the terminating character with the fread function. Additionally, if obj is a GPIB, VISA-GPIB, VISA-VXI, VISA-USB, or VISA-RSIB object, you can use the clrdevice function to remove the terminating character.

Note

To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.

Version History

Introduced before R2006a

expand all

See Also

Functions