fprintf (Instrument Control Toolbox)

Write text to the instrument

Syntax

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

Arguments

obj
An instrument object.

'cmd'
The string written to the instrument.

'format'
C language conversion specification.

'mode'
Specifies whether data is written synchronously or asynchronously.

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

Remarks

Before you can write text to 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 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.

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 M-file 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.

Synchronous and asynchronous write operations are discussed in more detail in Synchronous Versus Asynchronous Write Operations.

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, TCP/IP, 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.

Example

Create the serial port object s, connect s 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?')
```

See Also

Functions

fopen, fwrite, instrhelp, query, sprintf

Properties

BytesToOutput, EOSCharCode, EOSMode, OutputBufferSize, OutputEmptyFcn, Status, TransferStatus, ValuesSent

fopen fread