Instrument Control Toolbox

fgets

Read one line of text from the instrument and include the terminator

Syntax

• tline = fgets(obj)
  [tline,count] = fgets(obj)
  

[tline,count,msg] = fgets(obj)

Arguments

obj	An instrument object.
tline	The text read from the instrument, including the terminator.
count	The number of values read.
msg	A message indicating that the read operation did not complete successfully.

Description

tline = fgets(obj) reads one line of text from the instrument connected to obj, and returns the data to tline. The returned data includes the terminator with the text line. To exclude the terminator, use fgetl.

[tline,count] = fgets(obj) returns the number of values read to count.

[tline,count,msg] = fgets(obj) returns a warning message to msg if the read operation was unsuccessful.

Remarks

Before you can read text 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 fgets is issued.

Rules for Completing a Read Operation with fgets

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

• The terminator is read. For serial port, TCP/IP, UDP, and VISA-serial objects, the terminator is given by the Terminator property. Note that for UDP objects, DatagramTerminateMode must be off.

• For all other instrument objects except VISA-RSIB, the terminator is given by the EOSCharCode property.

• The EOI line is asserted (GPIB and VXI instruments only).
• A datagram has been received (UDP objects only if DatagramTerminateMode is on).
• The time specified by the Timeout property passes.
• The input buffer is filled.

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

Example

Create the GPIB object g, connect g to a Tektronix TDS 210 oscilloscope, configure g to complete read operations when the End-Of-String character is read, and write the *IDN? command with the fprintf function. *IDN? instructs the scope to return identification information.

• g = gpib('ni',0,1);
  fopen(g)
  g.EOSMode = 'read';
  fprintf(g,'*IDN?')
  

Asynchronously read the identification information from the instrument.

• readasync(g)
  g.BytesAvailable
  ans =
      56
  

Use fgets to transfer the data from the input buffer to the MATLAB workspace, and include the terminator.

• idn = fgets(g)
  idn =
  TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
  length(idn)
  ans =
      56
  

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

• fclose(g)
  delete(g)
  clear g
  

See Also

Functions

fgetl, fopen, instrhelp, query

Properties

BytesAvailable, EOSCharCode, EOSMode, InputBufferSize, Status, Terminator, Timeout, ValuesReceived

fgetl

flushinput