|On this page…|
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.
This example creates the GPIB object g, records the number of values transferred between g and the instrument, and stores the information to the file text myfile.txt.
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
Use the type command to display myfile.txt at the command line.
When you initiate recording with the record function, the RecordMode property determines if a new record file is created or if new information is appended to an existing record file.
You can configure RecordMode to overwrite, append, or index. If RecordMode is overwrite, then the record file is overwritten each time recording is initiated. If RecordMode is append, then 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 file name are discussed in Specifying a File Name.
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 file name is supported by your operating system. Additionally, if RecordMode is index, 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 RecordName is myfile.txt, then 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 file name already exists, then the existing file is overwritten.
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 property.
RecordDetail can be compact or verbose. 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 the instrument.
Binary data with precision given by uchar, schar, (u)int8, (u)int16, or (u)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 hex2dec:
dval = hex2dec('40880000') dval = 1.082654720000000e+009
Convert the decimal value to a binary value using dec2bin:
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 by
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 values of exp and significand into the formula for IEEE singles:
value = (-1)0(2129 - 127)(1.0625) value = 4.25
This example extends Reading and Writing Binary Data by recording the associated information to a record file. Additionally, the structure of the resulting record file is presented:
g = gpib('ni',0,1);
g.InputBufferSize = 50000; g.Timeout = 120;
Configure g to execute the callback function instrcallback every 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';
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.
instrcallback is 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 on to off. Because the RecordMode value is index, the record file name is automatically updated.
record(g) g.RecordStatus ans = off g.RecordName ans = WaveForm2.txt
fclose(g) delete(g) clear g
To display the contents of the WaveForm1.txt record file,
The record file contents are shown below. Note that data returned by the 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.