Romfile Object

Top  Previous  Next

object_romfile

The romfile. object provides access to resource files of your project (resource files appear in the "Resource Files" branch of your project tree).

Resource files are not processed by the compiler in any way — they are just added to the compiled binary.

Resource files are for storing permanent data that never changes (hence, the "rom" in "romfile" — as in "Read-Only Memory").

 

Opening resource files

Calling the romfile.open method opens a resource file. Only one resource file can be opened at any given time. There is no need to close resource files.

The size of the opened file can be checked through the romfile.size read-only property.

If you attempt to open a non-existent or empty file its size will be returned as 0.

 

Tibbo BASIC:

Tibbo C:

romfile.open("loremipsum.txt")
if romfile.size=0 then
  sys.halt 'this resource file does not exist
end if

romfile.open("loremipsum.txt");
if(romfile.size==0)
  sys.halt(); //this resource file does not exist

 

File pointer

The current file position in a resource file is indicated by the file pointer.

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

The value of the pointer can't exceed romfile.size+1 (unless the file does not exist or is empty, in which case the only possible pointer value is 0).

You can read and set the pointer position directly using the romfile.pointer32 property (more).

There is a second property — romfile.pointer. It is of the 16-bit type, so it won't work correctly for files larger than 64K bytes. This property exists to maintain compatibility with old applications. Do not use it for new projects.

 

Reading from resource files

Use the romfile.getdata method to read from the currently opened resource file.

The following example demonstrates a loop that exists once there is nothing left to read from the file:

 

Tibbo BASIC:

Tibbo C:

'read out the entire contents of a resource file
dim s as string
romfile.open("loremipsum.txt")
s=romfile.getdata(255)
while s<>""
  s=romfile.getdata(255)
wend

//read out the entire contents of a resource file
string s;
romfile.open("loremipsum.txt");
s=romfile.getdata(255);
while(s!="")
  s=romfile.getdata(255);

 

As you read from the file the pointer will move — each time by the number of bytes you've read.

Here is another file reading loop. This one is based on the pointer value:

 

Tibbo BASIC:

Tibbo C:

dim s as string
romfile.open("loremipsum.txt")
do
  s=romfile.getdata(255)
loop while romfile.pointer32<=romfile.size

string s;
romfile.open("loremipsum.txt");
do{
  s=romfile.getdata(255);
}while(romfile.pointer32<=romfile.size);

 

Searching within resource files

One of the primary uses for resource files is to store configuration data. For example, our own STG (settings) library relies on a resource file that describes available settings, their types, minimum and maximum values, and so on.

What's required for efficient work with configuration files is fast search, and the romfile.find32 method implements just that.

The search speed offered by this method far exceeds anything you would be able to achieve through a search function written in Tibbo BASIC or C.

In addition, romfile.find32 allows you to specify the starting search position and the occurrence number you are interested in (more).

There is a second property — romfile.find. It is of the 16-bit type, so it won't work correctly for files larger than 64K bytes. This property exists to maintain compatibility with old applications. Do not use it for new projects.

 

As an example, let's assume there is a configuration file with parameters:

 

parameters.txt:

...

IP=192.168.1.40

PORT=1001

...

 

Here is the code that will find the value of the IP parameter:

 

Tibbo BASIC:

Tibbo C:

const IP_STR="IP="
dim s as string
dim pos,pos2 as dword
romfile.open("text.txt")
pos=romfile.find32(1,IP_STR,1)
pos=pos+len(IP_STR)
romfile.pointer32=pos
pos2=romfile.find32(pos,chr(13),1) 'searching for the CR (line end)
s=romfile.getdata(pos2-pos)
'at this point s will contain "192.168.1.40"

#define IP_STR "IP="
string s;
unsigned long pos,pos2;
romfile.open("text.txt");
pos=romfile.find32(1,IP_STR,1);
pos+=len(IP_STR);
romfile.pointer32=pos;
pos2=romfile.find32(pos,chr(13),1);
s=romfile.getdata(pos2-pos);
//at this point s will contain "192.168.1.40"

 

File offset

Sometimes you will need to "pass" a resource file to another object. This is done through the romfile.offset read-only property. For examples of use see lcd.setfont and wln.boot.