External Interfaces Previous page   Next Page

Writing Data

This section describes writing data to your serial port device in three parts:

The functions associated with writing data are given below.

Table 10-5: Functions Associated with Writing Data 
Function Name
Description
fprintf
Write text to the device
fwrite
Write binary data to the device
stopasync
Stop asynchronous read and write operations

The properties associated with writing data are given below.

Table 10-6: Properties Associated with Writing Data 
Property Name
Description
BytesToOutput
Indicate the number of bytes currently in the output buffer
OutputBufferSize
Specify the size of the output buffer in bytes
Timeout
Specify the waiting time to complete a read or write operation
TransferStatus
Indicate if an asynchronous read or write operation is in progress
ValuesSent
Indicate the total number of values written to the device

The Output Buffer and Data Flow

The output buffer is computer memory allocated by the serial port object to store data that is to be written to the device. When writing data to your device, the data flow follows these two steps:

  1. The data specified by the write function is sent to the output buffer.
  2. The data in the output buffer is sent to the device.

The OutputBufferSize property specifies the maximum number of bytes that you can store in the output buffer. The BytesToOutput property indicates the number of bytes currently in the output buffer. The default values for these properties are given below.

If you attempt to write more data than can fit in the output buffer, an error is returned and no data is written.

For example, suppose you write the string command *IDN? to the TDS 210 oscilloscope using the fprintf function. As shown below, the string is first written to the output buffer as six values.

writing to an output buffer

The *IDN? command consists of six values because the terminator is automatically written. Moreover, the default data format for the fprintf function specifies that one value corresponds to one byte. For more information about bytes and values, refer to Bytes Versus Values. fprintf and the terminator are discussed in Writing Text Data.

As shown below, after the string is written to the output buffer, it is then written to the device via the serial port.

writing from an output buffer to an instrument

Writing Text Data

You use the fprintf function to write text data to the device. For many devices, writing text data means writing string commands that change device settings, prepare the device to return data or status information, and so on.

For example, the Display:Contrast command changes the display contrast of the oscilloscope.

By default, fprintf writes data using the %s\n format because many serial port devices accept only text-based commands. However, you can specify many other formats as described in the fprintf reference pages.

You can verify the number of values sent to the device with the ValuesSent property.

Note that the ValuesSent property value includes the terminator because each occurrence of \n in the command sent to the device is replaced with the Terminator property value.

The default value of Terminator is the line feed character. The terminator required by your device will be described in its documentation.

Synchronous Versus Asynchronous Write Operations.   By default, fprintf operates synchronously and will block the MATLAB command line until execution completes. To write text data asynchronously to the device, you must specify async as the last input argument to fprintf.

Asynchronous operations do not block access to the MATLAB command line. Additionally, while an asynchronous write operation is in progress, you can:

You can determine which asynchronous operations are in progress with the TransferStatus property. If no asynchronous operations are in progress, then TransferStatus is idle.

Rules for Completing a Write Operation with fprintf.   A synchronous or asynchronous write operation using fprintf completes when:

Additionally, you can stop an asynchronous write operation with the stopasync function.

Writing Binary Data

You use the fwrite function to write binary data to the device. Writing binary data means writing numerical values. A typical application for writing binary data involves writing calibration data to an instrument such as an arbitrary waveform generator.

By default, fwrite translates values using the uchar precision. However, you can specify many other precisions as described in the reference pages for this function.

By default, fwrite operates synchronously. To write binary data asynchronously to the device, you must specify async as the last input argument to fwrite. For more information about synchronous and asynchronous write operations, refer to the Writing Text Data. For a description of the rules used by fwrite to complete a write operation, refer to its reference pages.


Previous page  Controlling Access to the MATLAB Command Line Reading Data Next page

© 1994-2005 The MathWorks, Inc.