Debugging: Recording Information to Disk
Using the record Function
Recording information to disk provides a permanent record of your instrument control session, and is an easy way to debug your application. While the instrument object is connected to the instrument, you can record this information to a disk file:
The number of values written to the instrument, the number of values read from the instrument, and the data type of the values
Data written to the instrument, and data read from the instrument
You record information to a disk file with the
record function. The properties associated
with recording information to disk are given below.
Specify the amount of information saved to a record file.
Specify whether data and event information are saved to one record file or to multiple record files.
Specify the name of the record file.
Indicate if data and event information are saved to a record file.
Introduction to Recording Information
This example creates the GPIB object
the number of values transferred between
the instrument, and stores the information to the file text
g = gpib('ni',0,1); g.RecordName = 'myfile.txt'; fopen(g) record(g) fprintf(g,'*IDN?') out = fscanf(g);
End the instrument control session.
fclose(g) delete(g) clear g
myfile.txt at the command line.
Creating Multiple Record Files
When you initiate recording with the
RecordMode property determines if a new record
file is created or if new information is appended to an existing record
You can configure
then the record file is overwritten each time recording is initiated.
the new information is appended to the file specified by
index, a different
disk file is created each time recording is initiated. The rules for
specifying a record file name are discussed in Specifying a File Name.
Specifying a File Name
You specify the name of the record file with the
You can specify any value for
a directory path, provided the file name is supported by your operating
system. Additionally, if
then the file name follows these rules:
Indexed file names are identified by a number. This number precedes the file name extension and is increased by 1 for successive record files.
If no number is specified as part of the initial file name, then the first record file does not have a number associated with it. For example, if
myfile.txtis the name of the first record file,
myfile01.txtis the name of the second record file, and so on.
RecordNameis updated after the record file is closed.
If the specified file name already exists, then the existing file is overwritten.
Record File Format
The record file is an ASCII file that contains a record of one
or more instrument control sessions. You specify the amount of information
saved to a record file with the
RecordDetail can be
A compact record file contains the number of values written to the
instrument, the number of values read from the instrument, 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
Binary data with precision given by
int32 is recorded as hexadecimal
values. 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, and the value is given by
value = (-1)sign(2exp-127)(1.significand)
Double-precision floating-point values consist of 64 bits, and the value is given by
value = (-1)sign(2exp-1023)(1.significand)
The floating-point format component and the associated single-precision and double-precision bits are given below.
For example, suppose you record the decimal value 4.25 using
the single-precision format. The record file stores 4.25 as the hex
value 40880000, which is calculated from the IEEE single-precision
floating-point format. To reconstruct the original value, convert
the hex value to a decimal value using
dval = hex2dec('40880000') dval = 1.082654720000000e+009
Convert the decimal value to a binary value using
bval = dec2bin(dval,32) bval = 01000000100010000000000000000000
The interpretation of
bval is given by the
preceding table. The left most bit indicates the value is positive
because (-1)0 = 1. The next 8 bits correspond
to the exponent, which is given by
exp = bval(2:9) exp = 10000001
The decimal value of
exp is 27+20 =
129. The remaining bits correspond to the significant, which is given
significand = bval(10:32) significand = 00010000000000000000000
The decimal value of
significand is 2-4 =
0.0625. You reconstruct the original value by plugging the decimal
the formula for IEEE singles:
value = (-1)0(2129 - 127)(1.0625) value = 4.25
Recording Information to Disk
This example extends Writing and Reading Binary Data by recording the associated information to a record file. Additionally, the structure of the resulting record file is presented:
Create an instrument object — Create the GPIB object
gassociated with a National Instruments™ GPIB controller with board index 0, and an instrument with primary address 1.
g = gpib('ni',0,1);
Configure properties — Configure the input buffer to accept a reasonably large number of bytes, and configure the timeout value to two minutes to account for slow data transfer.
g.InputBufferSize = 50000; g.Timeout = 120;
gto execute the callback function
instrcallbackevery time 5000 bytes are stored in the input buffer.
g.BytesAvailableFcnMode = 'byte'; g.BytesAvailableFcnCount = 5000; g.BytesAvailableFcn = @instrcallback;
g.RecordMode = 'index'; g.RecordDetail = 'verbose'; g.RecordName = 'WaveForm1.txt';
Connect to the instrument — Connect
gto the oscilloscope.
Configure the scope to transfer the screen display as a bitmap.
fprintf(g,'HARDCOPY:PORT GPIB') fprintf(g,'HARDCOPY:FORMAT BMP') fprintf(g,'HARDCOPY START')
Initiate the asynchronous read operation, and begin generating events.
instrcallbackis called every time 5000 bytes are stored in the input buffer. The resulting displays are shown below.
BytesAvailable event occurred at 09:04:33 for the object: GPIB0-1. BytesAvailable event occurred at 09:04:42 for the object: GPIB0-1. BytesAvailable event occurred at 09:04:51 for the object: GPIB0-1. BytesAvailable event occurred at 09:05:00 for the object: GPIB0-1. BytesAvailable event occurred at 09:05:10 for the object: GPIB0-1. BytesAvailable event occurred at 09:05:19 for the object: GPIB0-1. BytesAvailable event occurred at 09:05:28 for the object: GPIB0-1.
Wait until all the data is stored in the input buffer, and then transfer the data to the MATLAB® workspace as unsigned 8-bit integers.
out = fread(g,g.BytesAvailable,'uint8');
Toggle the recording state from
off. Because the
index, the record file name is automatically updated.
record(g) g.RecordStatus ans = off g.RecordName ans = WaveForm2.txt
Disconnect and clean up — When you no longer need
g, you should disconnect it from the instrument, and remove it from memory and from the MATLAB workspace.
fclose(g) delete(g) clear g
The Record File Contents
To display the contents of the WaveForm1.txt record file,
The record file contents are shown below. Note that data returned
fread function is in hex format (most
of the bitmap data is not shown).
Legend: * - An event occurred. > - A write operation occurred. < - A read operation occurred. 1 Recording on 18-Jun-2000 at 09:03:53.529. Binary data in little endian format. 2 > 18 ascii values. HARDCOPY:PORT GPIB 3 > 19 ascii values. HARDCOPY:FORMAT BMP 4 > 14 ascii values. HARDCOPY START 5 * BytesAvailable event occurred at 18-Jun-2000 at 09:04:33.334 6 * BytesAvailable event occurred at 18-Jun-2000 at 09:04:41.775 7 * BytesAvailable event occurred at 18-Jun-2000 at 09:04:50.805 8 * BytesAvailable event occurred at 18-Jun-2000 at 09:04:00.266 9 * BytesAvailable event occurred at 18-Jun-2000 at 09:05:10.306 10 * BytesAvailable event occurred at 18-Jun-2000 at 09:05:18.777 11 * BytesAvailable event occurred at 18-Jun-2000 at 09:05:27.778 12 < 38462 uint8 values. 42 4d cf 03 00 00 00 00 00 00 3e 00 00 00 28 00 00 00 80 02 00 00 e0 01 00 00 01 00 01 00 00 00 00 00 00 96 00 00 00 00 00 00 00 00 00 00 00 00 . . . ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 13 Recording off.