|On this page…|
Recording information to disk provides a permanent record of your serial port session, and is an easy way to debug your application. While the serial port object is connected to the device, you can record the following information to a disk file:
The number of values written to the device, the number of values read from the device, and the data type of the values
Data written to the device, and data read from the device
You record information to a disk file with the record function. The following table shows the properties associated with recording information to disk.
Amount of information saved to a record file
Specify whether data and event information is saved to one record file or to multiple record files
Name of the record file
Indicate if data and event information are saved to a record file
Note: All examples in this section are based on a Windows® 32-bit platform. For more information about other supported platforms, refer to Overview of a Serial Port Object.
This example records the number of values written to and read from the device, and stores the information to the file myfile.txt.
s = serial('COM1'); fopen(s) s.RecordName = 'myfile.txt'; record(s) fprintf(s,'*IDN?') idn = fscanf(s); fprintf(s,'RS232?') rs232 = fscanf(s);
End the serial port session.
fclose(s) delete(s) clear s
To display myfile.txt at the command line, use the type command.
You can configure RecordMode to overwrite, append, or index. If RecordMode is overwrite, the record file is overwritten each time recording is initiated. If RecordMode is append, the new information is appended to the file specified by RecordName. If RecordMode is index, a different disk file is created each time recording is initiated. The rules for specifying a record filename are discussed in the next section.
You specify the name of the record file with the RecordName property. You can specify any value for RecordName — including a directory path — provided the filename is supported by your operating system. Additionally, if RecordMode is index, the filename follows these rules:
Indexed filenames are identified by a number. This number precedes the filename extension and is increased by 1 for successive record files.
If no number is specified as part of the initial filename, the first record file does not have a number associated with it. For example, if RecordName is myfile.txt, myfile.txt is the name of the first record file, myfile01.txt is the name of the second record file, and so on.
RecordName is updated after the record file is closed.
If the specified filename already exists, the existing file is overwritten.
The record file is an ASCII file that contains a record of one or more serial port sessions. You specify the amount of information saved to a record file with the RecordDetail property.
RecordDetail can be compact or verbose. A compact record file contains the number of values written to the device, the number of values read from the device, the data type of the values, and event information. A verbose record file contains the preceding information as well as the data transferred to and from the device.
Binary data with precision given by uchar, schar, (u)int8, (u)int16, or (u)int32 is recorded using hexadecimal format. For example, if the integer value 255 is read from the instrument as a 16-bit integer, the hexadecimal value 00FF is saved in the record file. Single- and double-precision floating-point numbers are recorded as decimal values using the %g format, and as hexadecimal values using the format specified by the IEEE® Standard 754-1985 for Binary Floating-Point Arithmetic.
The IEEE floating-point format includes three components: the sign bit, the exponent field, and the significant field. Single-precision floating-point values consist of 32 bits. The value is given by
Double-precision floating-point values consist of 64 bits. The value is given by
The floating-point format component, and the associated single-precision and double-precision bits are shown in the following table.
|Component||Single-Precision Bits||Double-Precision Bits|
Bit 1 is the left-most bit as stored in the record file.
This example illustrates how to record information transferred between a serial port object and a Tektronix® TDS 210 oscilloscope. Additionally, the structure of the resulting record file is presented.
s = serial('COM1');
Connect to the device — Connect s to the oscilloscope. Because the default value for the ReadAsyncMode property is continuous, data is asynchronously returned the input buffer as soon as it is available from the instrument.
s.RecordMode = 'index'; s.RecordDetail = 'verbose'; s.RecordName = 'WaveForm1.txt'; record(s)
Write and read data — The commands written to the instrument, and the data read from the instrument are recorded in the record file. For an explanation of the oscilloscope commands, see Example — Writing and Reading Text Data.
fprintf(s,'*IDN?') idn = fscanf(s); fprintf(s,'MEASUREMENT:IMMED:SOURCE CH2') fprintf(s,'MEASUREMENT:IMMED:SOURCE?') source = fscanf(s);
Read the peak-to-peak voltage with the fread function. Note that the data returned by fread is recorded using hex format.
fprintf(s,'MEASUREMENT:MEAS1:TYPE PK2PK') fprintf(s,'MEASUREMENT:MEAS1:VALUE?') ptop = fread(s,s.BytesAvailable);
Convert the peak-to-peak voltage to a character array.
char(ptop)' ans = 2.0199999809E0
The recording state is toggled from on to off. Because the RecordMode value is index, the record filename is automatically updated.
record(s) s.RecordStatus ans = off s.RecordName ans = WaveForm2.txt
fclose(s) delete(s) clear s
The contents of the WaveForm1.txt record file are shown below. Because the RecordDetail property was verbose, the number of values, commands, and data were recorded. Note that data returned by the fread function is in hex format.
type WaveForm1.txt Legend: * - An event occurred. > - A write operation occurred. < - A read operation occurred. 1 Recording on 22-Jan-2000 at 11:21:21.575. Binary data in... 2 > 6 ascii values. *IDN? 3 < 56 ascii values. TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04 4 > 29 ascii values. MEASUREMENT:IMMED:SOURCE CH2 5 > 26 ascii values. MEASUREMENT:IMMED:SOURCE? 6 < 4 ascii values. CH2 7 > 27 ascii values. MEASUREMENT:MEAS1:TYPE PK2PK 8 > 25 ascii values. MEASUREMENT:MEAS1:VALUE? 9 < 15 uchar values. 32 2e 30 31 39 39 39 39 39 38 30 39 45 30 0a 10 Recording off.