Romfile Object

The romfile object allows you to access resource (ROM) files of your project. Resource files appear in the "Resource Files" folder of your project tree. These are files that are not processed by the compiler in any way -- they are just added to the compiled binary. Resource files are ideal for storing permanent data that never changes.

Calling romfile.open opens a resource file. Only one file can be opened at any given time and there is no need to close it. The size of the file you have opened can be checked through the romfile.size read-only property. If you attempt to open a non-existent file its size will be returned as 0. This is how you know that the file does not exist!

There is a file pointer. When you open or reopen the file the pointer is set to 1 (the first byte in the file), unless the file does not exist or empty, in which case the pointer will be at 0.

You read the data from the file using the romfile.getdata method. As you read from the file, the pointer moves - each time by the number of characters you've just read. The pointer can't exceed romfile.size+1 (unless the file does not exist or is empty, in which case the pointer will always be at 0).

You can read and set the pointer position directly using two properties -- romfile.pointer and romfile.pointer32. The difference between them is that romfile.pointer is of the word type and, hence, can only be used to set the pointer in the 1-65535 range. If the pointer is already above 65535, romfile.pointer will still return 65535.

The romfile.pointer32 property is of the dword type and can handle all pointer positions. Use it if you access resource files that are larger than 65535 bytes. The disadvantage of romfile.pointer32 is that using it will result in reduced code performance. For this reason, rely on romfile.pointer whenever possible.

The romfile.find and romfile.find32 methods search through the currently opened resource file. For example, supposing you have the following data in the file <parameters.txt>:

IP=192.168.1.40

PORT=1001

...

This sample data represents the list of parameters that your program uses. Now, supposing you need to extract the value of the "PORT" parameter. Here is the code:

dim dw,dw2 as dword

dim s as string(10)

'look for "PORT" first

romfile.open("resource2.txt")

dw=romfile.find(1,"PORT",1)

if dw=0 then sys.halt

dw=dw+len("PORT=")

'OK, now loop for CR after "PORT"

dw2=romfile.find(dw,chr(13),1)

if dw2=0 then sys.halt

'extract the value

romfile.pointer=dw

s=romfile.getdata(dw2-dw)

's now contains the port number

The difference between romfile.find and romfile.find32 is that the former is of the word type and the latter is of the dword type. Romfile.find can only "report back" file positions that are in the 1-65535 range. If the target instance of the substring was found beyond the 65535 position, romfile.find will still return 65535. Romfile.find32 doesn't have this limitation, but it will slow down your code, so use romfile.find whenever possible.

Sometimes you will need to open a resource file not for the purpose of accessing it, but for the purpose of "passing" this file to another object. Such reference is provided by the romfile.offset read-only property. For illustration of use, see lcd.setfont and wln.boot.