Instrument Control Toolbox | ![]() ![]() |
Read data from the instrument, and format as text
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
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,'
reads data and converts it according to format
')
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,'
reads the number of values specified by format
',size)
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 [ ].
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 -- including the terminator -- each time fscanf
is issued.
Rules for Completing a Read Operation with fscanf
A read operation with fscanf
blocks access to the MATLAB command line until
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
.
EOSCharCode
property.
Timeout
property passes.
size
is read. For UDP objects, DatagramTerminateMode
must be off
.
DatagramTerminateMode
is on
).
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.
Example
Create the serial port object s
and connect s
to a Tektronix TDS 210 oscilloscope, which is displaying a sine wave.
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.
Use fscanf
to read the measurement type. The operation will complete when the first terminator is read.
Use fscanf
to read the peak-to-peak voltage as a floating-point number, and exclude the terminator.
Disconnect s
from the scope, and remove s
from memory and the workspace.
Functions
fgetl
, fgets
, fopen
, fread
, instrhelp
, scanstr
, sscanf
Properties
BytesAvailable
, BytesAvailableFcn
, EOSCharCode
, EOSMode
, InputBufferSize
, Status
, Terminator
, Timeout
, TransferStatus
![]() | freeserial | fwrite | ![]() |