fprintf

(To be removed) Write text to instrument

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

fprintf(obj,'cmd')
fprintf(obj,'format','cmd')
fprintf(obj,'cmd','mode')
fprintf(obj,'format','cmd','mode')

Arguments

obj

An interface object.

'cmd'

The string written to the instrument.

'format'

C language conversion specification.

'mode'

Specifies whether data is written synchronously or asynchronously.

Description

fprintf(obj,'cmd') writes the string cmd to the instrument connected to obj. The default format is %s\n. The write operation is synchronous and blocks the command line until execution is complete.

fprintf(obj,'format','cmd') writes the string using the format specified by format.

format is a C language conversion specification. Conversion specifications involve the % character and the conversion characters d, i, o, u, x, X, f, e, E, g, G, c, and s. Refer to the sprintf file I/O format specifications or a C manual for more information.

fprintf(obj,'cmd','mode') writes the string with command-line access specified by mode. If mode is sync, cmd is written synchronously and the command line is blocked. If mode is async, cmd is written asynchronously and the command line is not blocked. If mode is not specified, the write operation is synchronous.

fprintf(obj,'format','cmd','mode') writes the string using the specified format. If mode is sync, cmd is written synchronously. If mode is async, cmd is written asynchronously.

Examples

Create the serial port object s, connect s on a Windows® machine to a Tektronix® TDS 210 oscilloscope, and write the RS232? command with the fprintf function. RS232? instructs the scope to return serial port communications settings.

s = serial('COM1');
fopen(s)
fprintf(s,'RS232?')
settings = fscanf(s)
settings =
9600;1;0;NONE;LF

Because the default format for fprintf is %s\n, the terminator specified by the Terminator property was automatically written. However, in some cases you might want to suppress writing the terminator. To do so, you must explicitly specify a format for the data that does not include the terminator, or configure the terminator to empty.

fprintf(s,'%s','RS232?')

Tips

Before you can write text to 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 write operation while obj is not connected to the instrument.

The ValuesSent property value is increased by the number of values written each time fprintf is issued.

An error occurs if the output buffer cannot hold all the data to be written. You can specify the size of the output buffer with the OutputBufferSize property.

fprintf function will return an error message if you set the flowcontrol property to hardware on a serial object, and a hardware connection is not detected. This occurs if a device is not connected, or a connected device is not asserting that is ready to receive data. Check you remote device's status and flow control settings to see if hardware flow control is causing errors in MATLAB®.

Note

If you want to check to see if the device is asserting that it is ready to receive data, set the FlowControl to none. Once you connect to the device check the PinStatus structure for ClearToSend. If ClearToSend is off, there is a problem on the remote device side. If ClearToSend is on, there is a hardware FlowControl device prepared to receive data and you can execute fprintf.

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.

Synchronous Versus Asynchronous Write Operations

By default, text is written to the instrument synchronously and the command line is blocked until the operation completes. You can perform an asynchronous write by configuring the mode input argument to be async. For asynchronous writes,

  • The BytesToOutput property value is continuously updated to reflect the number of bytes in the output buffer.

  • The callback function specified for the OutputEmptyFcn property is executed when the output buffer is empty.

You can determine whether an asynchronous write operation is in progress with the TransferStatus property.

Rules for Completing a Write Operation with fprintf

A write operation using fprintf completes when

  • The specified data is written.

  • The time specified by the Timeout property passes.

Rules for Writing the Terminator

For serial port, TCPIP, UDP, and VISA-serial objects, all occurrences of \n in cmd are replaced with the Terminator property value. Therefore, when using the default format %s\n, all commands written to the instrument will end with this property value.

For GPIB, VISA-GPIB, VISA-VXI, and VISA-GPIB-VXI objects, all occurrences of \n in cmd are replaced with the EOSCharCode property value if the EOSMode property is set to write or read&write. For example, if EOSMode is set to write and EOSCharCode is set to LF, then all occurrences of \n are replaced with a line feed character. Additionally, for GPIB objects, the End Or Identify (EOI) line is asserted when the terminator is written out.

Note

The terminator required by your instrument will be described in its documentation.

Version History

Introduced before R2006a

expand all

See Also

Functions