fread

Syntax

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

Arguments

`obj`	An interface 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.
`datagramaddress`	The address of the datagram sender.
`datagramport`	The port of the datagram sender.

Description

A = fread(obj) and A = fread(obj,size) read 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. If size is not specified, the maximum number of values to read is determined by the object's InputBufferSize property. 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).

If obj is a UDP object and DatagramTerminateMode is off, the size value is honored. If size is less than the length of the datagram, only size values are read. If size is greater than the length of the datagram, a warning is issued stating that a complete datagram was read before size values was reached.

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 Tips.

[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.

[A,count,msg,datagramaddress] = fread(obj,...) returns the datagram address to datagramaddress if obj is a UDP object. If more than one datagram is read, datagramaddress is ' '.

[A,count,msg,datagramaddress,datagramport] = fread(obj,...) returns the datagram port to datagramport if obj is a UDP object. If more than one datagram is read, datagramport is [ ].

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.

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.

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.

Rules for Completing a Binary Read Operation

A read operation with fread blocks access to the MATLAB Command Window until

The specified number of values is read. For UDP objects, DatagramTerminateMode must be off.
The time specified by the Timeout property passes.
A datagram is received (for UDP objects only when DatagramTerminateMode is on).
The input buffer is filled.
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 LF, then one of the ways that the read operation terminates is when the line feed 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 criterion, 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

Version History

Introduced before R2006a

expand all

R2024a: `i2c` object interface warns

Use of this function with an i2c object issues a warning that i2c will be removed in a future release. To connect to a peripheral device on an I2C controller, use the device function with an aardvark or ni845x object, its functions, and its properties instead.

The recommended functionality has additional capabilities and improved performance. See Transition Your Code to aardvark or ni845x Interface for more information about using the recommended functionality.

R2023a: `i2c` object interface will be removed

Use of this function with an i2c object will be removed in a future release.

R2021b: `gpib` object interface will be removed

Use of this function with a gpib object will be removed. To access a GPIB instrument, use the VISA-GPIB interface with a visadev object, its functions, and its properties instead.

The recommended functionality has additional capabilities and improved performance. See Transition Your Code to VISA-GPIB Interface for more information about using the recommended functionality.

R2021a: `tcpip`, `visa`, and `serial` object interfaces will be removed

Use of this function with the tcpip (with NetworkRole set to server), visa, and serial interfaces will be removed. Use the following interfaces and their functions instead. The recommended interfaces have additional capabilities and improved performance.

Functionality	Use This Instead	Additional Information
`tcpip`	`tcpserver`	Transition Your Code to tcpserver Interface
`visa`	`visadev`	Transition Your Code to visadev Interface
`serial`	`serialport`	Transition Your Code to serialport Interface

R2020b: `Bluetooth`, `tcpip`, and `udp` object interfaces will be removed

Use of this function with the Bluetooth, tcpip (with NetworkRole set to client), and udp interfaces will be removed. Use the following interfaces and their functions instead. The recommended interfaces have additional capabilities and improved performance.

Functionality	Use This Instead	Additional Information
`Bluetooth`	`bluetooth` (case-sensitive)	Transition Your Code to bluetooth Interface
`tcpip`	`tcpclient`	Transition Your Code to tcpclient Interface
`udp`	`udpport`	Transition Your Code to udpport Interface

R2019b: `serial` object interface is not recommended

Use of this function with a serial object is not recommended. To access a serial port, use a serialport object instead.

The recommended functionality has additional capabilities and improved performance. See Transition Your Code to serialport Interface for more information about using the recommended functionality.

fread

Syntax

Arguments

Description

Tips

Rules for Completing a Binary Read Operation

More About the GPIB and VXI Terminator

Supported Precisions

Version History

R2024a: i2c object interface warns

R2023a: i2c object interface will be removed

R2021b: gpib object interface will be removed

R2021a: tcpip, visa, and serial object interfaces will be removed

R2020b: Bluetooth, tcpip, and udp object interfaces will be removed

R2019b: serial object interface is not recommended

See Also