Instrument Control Toolbox

fread

Read binary data from the instrument

Syntax

A = fread(obj,size)
A = fread(obj,size,'precision')
[A,count] = fread(...)

[A,count,msg] = fread(...)

Arguments

obj	An instrument object.
size	The number of values to read.
'precision'	The number of bits read for each value, and the interpretation of the bits as character, integer, or floating-point values.
A	Binary data returned from the instrument.
count	The number of values read.
msg	A message indicating if the read operation was unsuccessful.

Description

A = fread(obj,size) reads binary data from the instrument connected to obj, and returns the data to A. The maximum number of values to read is specified by size. Valid options for size are:

n	Read at most n values into a column vector.
[m,n]	Read at most m-by-n values filling an m-by-n matrix in column order.

size cannot be inf, and an error is returned if the specified number of values cannot be stored in the input buffer. You specify the size, in bytes, of the input buffer with the InputBufferSize property. A value is defined as a byte multiplied by the precision (see below).

A = fread(obj,size,'precision') reads binary data with precision specified by precision.

precision controls the number of bits read for each value and the interpretation of those bits as integer, floating-point, or character values. If precision is not specified, uchar (an 8-bit unsigned character) is used. By default, numeric values are returned in double-precision arrays. The supported values for precision are listed below in Remarks.

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

[A,count,msg] = fread(...) returns a warning message to msg if the read operation was unsuccessful.

Remarks

Before you can read data from the instrument, it must be connected to obj with the fopen function. A connected instrument 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.

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.

The ValuesReceived property value is increased by the number of values read, each time fread is issued.

Rules for Completing a Binary Read Operation

A read operation with fread blocks access to the MATLAB command line until:

• The specified number of values are read.
• The time specified by the Timeout property passes.
• The EOI line is asserted (GPIB and VXI instruments only).
• The EOSCharCode is received (GPIB and VXI instruments only).

More About the GPIB and VXI Terminator

The EOSCharCode property value is recognized only when the EOSMode property is configured to read or read&write. For example, if EOSMode is configured to read and EOSCharCode is configured to 10, then one of the ways that the read operation terminates is when the linefeed character is received.

If EOSMode is none or write, then there is no terminator defined for read operations. In this case, fread will complete execution and return control to the command when another criteria, such as a timeout, is met.

Supported Precisions

The supported values for precision are listed below.

Data Type	Precision	Interpretation
Character	uchar	8-bit unsigned character
	schar	8-bit signed character
	char	8-bit signed or unsigned character
Integer	int8	8-bit integer
	int16	16-bit integer
	int32	32-bit integer
	uint8	8-bit unsigned integer
	uint16	16-bit unsigned integer
	uint32	32-bit unsigned integer
	short	16-bit integer
	int	32-bit integer
	long	32- or 64-bit integer
	ushort	16-bit unsigned integer
	uint	32-bit unsigned integer
	ulong	32- or 64-bit unsigned integer
Floating-point	single	32-bit floating point
	float32	32-bit floating point
	float	32-bit floating point
	double	64-bit floating point
	float64	64-bit floating point

See Also

Functions

fgetl, fgets, fopen, fscanf, instrhelp

Properties

BytesAvailable, InputBufferSize, Status, ValuesReceived

fprintf

fscanf