scanstr

(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 Version History.

Syntax

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

Arguments

obj

An interface object.

'delimiter'

One or more delimiters used to parse the data.

'format'

C language conversion specification.

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.

Description

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.

Examples

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);
fopen(g)

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

fprintf(g,'*IDN?');
idn = scanstr(g)
idn = 
    'TEKTRONIX'
    'TDS 210'
    [        0]
    'CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04'

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

Version History

Introduced before R2006a

expand all

See Also

Functions