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
Event information

You record information to a disk file with the record function. The properties associated with recording information to disk are given below.

Recording Properties

Property Name	Description
RecordDetail	Specify the amount of information saved to a record file.
RecordMode	Specify whether data and event information are saved to one record file or to multiple record files.
RecordName	Specify the name of the record file.
RecordStatus	Indicate if data and event information are saved to a record file.

Introduction to Recording Information

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.

Creating Multiple Record Files

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.

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.

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 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(2^exp-127)(1.significand)

Double-precision floating-point values consist of 64 bits, and the value is given by

value = (-1)^sign(2^exp-1023)(1.significand)

The floating-point format component and the associated single-precision and double-precision bits are given below.

Format Component	Single-Precision Bits	Double-Precision Bits
`sign`	1	1
`exp`	2-9	2-12
`significand`	10-32	13-64

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)⁰ = 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 2⁷+2⁰ = 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)⁰(2^{129 - 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 g associated 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;
```
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;
```
Configure g to record information to multiple disk files using the verbose format. The first disk file is defined as WaveForm1.txt.
```
g.RecordMode = 'index';
g.RecordDetail = 'verbose';
g.RecordName = 'WaveForm1.txt';
```
Connect to the instrument — Connect g to the oscilloscope.
```
fopen(g)
```

Write and read data — Initiate recording.

record(g)

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.

readasync(g)

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

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,

type WaveForm1.txt

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.