scanstr (Instrument Control Toolbox)

Read data from the instrument, format as text, and parse

Syntax

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

Arguments

obj
An instrument 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.

`obj`	An instrument 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 string.

A = scanstr(obj,'delimiter') parses the data into separate variables based on the specified delimiter. delimiter can be a single character or a string array. If delimiter is a string 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 M-file 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 string) 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.

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

Example

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'

See Also

Functions

fopen, fscanf, instrhelp, sscanf, textread

Properties

EOSCharCode, EOSMode, Status, Terminator, ValuesReceived

save serial