Main Content

fgetl

(To be removed) Read line of text from instrument and discard terminator

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

tline = fgetl(obj)
[tline,count] = fgetl(obj)
[tline,count,msg] = fgetl(obj)
[tline,count,msg,datagramaddress,datagramport] = fgetl(obj)

Arguments

obj

An interface object.

tline

The text read from the instrument, excluding the terminator.

count

The number of values read, including the terminator.

msg

A message indicating if the read operation was unsuccessful.

datagramaddress

The datagram address.

datagramport

The datagram port.

Description

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

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

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

[tline,count,msg,datagramaddress,datagramport] = fgetl(obj) returns the remote address and port from which the datagram originated. These values are returned only if obj is a UDP object.

Examples

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 fgetl to transfer the data from the input buffer to the MATLAB® workspace, and discard the terminator.

idn = fgetl(g)
idn =
TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04

length(idn)
ans =
    55

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

fclose(g)
delete(g)
clear g

Tips

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

Note

You cannot use ASCII values larger than 127 characters. The function is limited to 127 binary characters.

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.

Rules for Completing a Read Operation with fgetl

A read operation with fgetl blocks access to the MATLAB Command Window until

  • The terminator is read. For serial port, TCPIP, 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 interface 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.

Note

You cannot use ASCII values larger than 127 characters. The function is limited to 127 binary characters.

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

Version History

Introduced before R2006a

expand all

R2021b: gpib object interface will be removed

Use of this function with a gpib object will be removed. To access a GPIB instrument, use the VISA-GPIB interface with a visadev object, its functions, and its properties instead.

The recommended functionality has additional capabilities and improved performance. See Transition Your Code to VISA-GPIB Interface for more information about using the recommended functionality.

See Also

Functions