Main Content


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

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.


A = scanstr(obj)
A = scanstr(obj,'delimiter')
A = scanstr(obj,'delimiter','format')
[A,count] = scanstr(...)
[A,count,msg] = scanstr(...)



An interface object.


One or more delimiters used to parse the data.


C language conversion specification.


Data read from the instrument and formatted as text.


The number of values read.


A message indicating if the read operation was unsuccessful.


A = scanstr(obj) reads formatted data from the instrument connected to obj, parses the data using both a comma and a semicolon delimiter, and returns the data to the cell array A. Each element of the cell array is determined to be either a double or a character vector.

A = scanstr(obj,'delimiter') parses the data into separate variables based on the specified delimiter. delimiter can be a single character or a character vector array. If delimiter is a character vector array, then each character in the array is used as a delimiter.

A = scanstr(obj,'delimiter','format') converts the data according to the specified format. A can be a matrix or a cell array depending on format. See the textread help for complete details. format is a string containing C language conversion specifications.

Conversion specifications involve the % character and the conversion characters d, i, o, u, x, X, f, e, E, g, G, c, and s. See the sscanf file I/O format specifications or a C manual for complete details.

If format is not specified, then the best format (either a double or a character vector) is chosen.

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

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


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

g = gpib('ni',0,2);

Return identification information to separate elements of a cell array using the default delimiters.

idn = scanstr(g)
idn = 
    'TDS 210'
    [        0]
    'CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04'


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 scanstr is issued.


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

Not recommended starting in R2021b

Not recommended starting in R2021a

Not recommended starting in R2020b

Not recommended starting in R2019b