fscanf

(To be removed) Read data from instrument, and format as text

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 Compatibility Considerations.

Syntax

A = fscanf(obj)
A = fscanf(obj,'format')
A = fscanf(obj,'format',size)
[A,count] = fscanf(...)
[A,count,msg] = fscanf(...)
[A,count,msg,datagramaddress] = fscanf(obj,...)
[A,count,msg,datagramaddress,datagramport] = fscanf(obj,...)


Arguments

obj	An interface object.
'format'	C language conversion specification.
size	The number of values to read.
A	Data read from the instrument and formatted as text.
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 = fscanf(obj) reads data from the instrument connected to obj, and returns it to A. The data is converted to text using the %c format.

A = fscanf(obj,'format') reads data and converts it according to format.

format is a C language conversion specification. Conversion specifications involve the % character and the conversion characters d, i, o, u, x, X, f, e, E, g, G, c, and s. Refer to the sscanf file I/O format specifications or a C manual for more information.

A = fscanf(obj,'format',size) reads the number of values 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. If size is not of the form [m,n], and a character conversion is specified, then A is returned as a row vector. You specify the size, in bytes, of the input buffer with the InputBufferSize property. An ASCII value is one byte.

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,count] = fscanf(...) returns the number of values read to count.

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

[A,count,msg,datagramaddress] = fscanf(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] = fscanf(obj,...) returns the datagram port to datagramport if obj is a UDP object. If more than one datagram is read, datagramport is [ ].

Examples

Create the serial port object s on a Windows^® machine and connect s to a Tektronix^® TDS 210 oscilloscope, which is displaying a sine wave.

s = serial('COM1');
fopen(s)

Use the fprintf function to configure the scope to measure the peak-to-peak voltage of the sine wave, return the measurement type, and return the peak-to-peak voltage.

fprintf(s,'MEASUREMENT:IMMED:TYPE PK2PK')
fprintf(s,'MEASUREMENT:IMMED:TYPE?')
fprintf(s,'MEASUREMENT:IMMED:VAL?')

Because the default value for the ReadAsyncMode property is continuous, data associated with the two query commands is automatically returned to the input buffer.

s.BytesAvailable
ans =
    13

Use fscanf to read the measurement type. The operation will complete when the first terminator is read.

meas = fscanf(s)
meas =
PK2PK

Use fscanf to read the peak-to-peak voltage as a floating-point number, and exclude the terminator.

pk2pk = fscanf(s,'%e',6)
pk2pk =
    2.0200

Disconnect s from the scope, and remove s from memory and the workspace.

fclose(s)
delete(s)
clear s

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 — including the terminator — each time fscanf 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 Read Operation with fscanf

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

• The terminator is read. For serial port, TCPIP, UDP, and VISA-serial objects, the terminator is given by the Terminator property. If Terminator is empty, fscanf will complete execution and return control when another criterion is met. For UDP objects, DatagramTerminateMode must be off.

  For all other interface objects, the terminator is given by the EOSCharCode property.

• The time specified by the Timeout property passes.

• The number of values specified by size is read. For UDP objects, DatagramTerminateMode must be off.

• 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).

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, fscanf will complete execution and return control to the command when another criterion, such as a timeout, is met.

Version History

Introduced before R2006a

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