Lego NXT File Handling- Save and Close

This is an advanced topic, please make sure you've read the "Introduction To File Handling" tutorial before you continue reading this chapter.

Usages

The following are usages to the FileClose command:

• Release unused resources- When a file is opened, a new handler is created in the file that is registered to the internal tracking table.
  There are some limitations to the number of opened file handlers at the time.
  FileClose command removes the opened file handler record from the tracking table and reduces the current state of active handlers;
• Save changes- Non textual files are created in the RAM.
  Non textual files must be filled completely before calling the FileClose command.
  Only after the close command, the file system on the flash memory is updated with the newly created non textual file;
• Reopening the file for other purposes- Operation commands cannot be performed on a file that was opened to a different purpose than the operation.
  For example, file that has been opened for writing purposes using the TextFileOpenAppend command,
  but after or instead of the writing command (FileWrite), it gets the FileRead command.
  In this case, 0x93 error message will be retrieved from the response command.
  Use the FileClose command to close the file and reopen it for a different purpose;
• Close after search- When a file search is performed, a handler is registered to the found file.
  Make sure to close the handler before any other operations on the file;
• Preserve file's original size- When a file is created, its size is specified.
  All opened files handles will be closed automatically when the program is finished.
  When the file is closed automatically, unused space inside the specified file is removed to maximize the free space on the device.
  If you are planning to edit this file later on (only textual files can be edited using the TextFileOpenAppend command),
  make sure to use the FileClose command to save the file with unallocated space;

Open handler limitations:

• 16 open handlers (read and write) for each thread;
• 4 open handlers for writing purposes at the same time;

FileClose command

This command is used to close opened file handler when it is no longer needed.
When a file is closed successfully, the following operations are performed:

• File handle is released from system resources.
• Unused space in the file remains while the file is closed.
• Pending file write buffers are committed to flash memory.
• The specified file handler is removed from the tracker table; therefore, ResolveHandle command will no longer recognize this file name (will be discussed in later posts).

If the program is about to be closed, all opened file handlers will be closed automatically. When the file is closed automatically, unused space inside the specified file is removed to maximize the free space on the device.

It is important to use this command to free unused resources. There is a limitation of 16 opened file handlers (read and write) in the same thread, and four files that can be opened for writing purposes at the same time.

Syntax

[0x03] [0x00] [0x01 or 0x81] [0x84] [Handle id]

Explanation:

• Byte 0-1: Command length LSB first.
• Byte 2: Command type- system command. For system command with response message use 0x01, otherwise, for system command without the reply message, use 0x81.
• Byte 3: Command- file close
• Byte 4: Handle id. This number is included in the response message of any of the open file commands.

The reply message that is coming back (if requested) looks like:

[0x04] [0x00] [0x02] [0x84] [0x00 or error] [Handle id]

Explanation:

• Byte 0-1: Message length LSB first.
• Byte 2: Command type- reply message
• Byte 3: Command that has requested for this reply.
• Byte 4: Command status- 0x00 for success or error number for failure. Check the NXT File Handling over Bluetooth- Introduction chapter for error numbers.
• Byte 5: Handler id. The id of a handle that has been closed.

Example:

A file was opened using OpenFile command. In the response message of the open command, a handle id of 0x04 has been received (check the return message explanation for the handle id byte). This handle is no longer needed, therefore, can be closed.

The command that is sent to NXT is:
0x03 0x00 0x01 0x84 0x04

The command that is received from NXT as a reply is:
0x04 0x00 0x02 0x84 0x00 0x04

What's next?

Let's move forward and learn NXT File Handling- Delete Files

signs of a cheater what makes married men cheat married men that cheat