TOC PREV NEXT INDEX

Put your logo here!


15 File Class (fileclass.hhf)


The HLA Standard Library provides a file class that simplifies file I/O. The name of this class is file and you should declare all objects to be of this type or a pointer to this type, e.g.,


 
var
 
	MyOuputFile: file;
 
	filePtr:     pointer to file;
 

 

Once you declare a file variable, you access the remaining methods, procedures, and fields in the file class by specifying the file variable name and a period as a prefix to the field name.

Note: HLA also provides a fileio library module that does file I/O using traditional procedures rather than class objects. If you're more comfortable using such a programming paradigm, or you prefer your code to be a bit more efficient, you should use the fileio module.

Warning: Don't forget that HLA objects modify the values in the ESI and EDI registers whenever you call a class procedure, method, or iterator. Do not leave any important values in either of these register when making calls to the following routines. If the use of ESI and EDI is a problem for you, you might consider using the fileio module that does not suffer from this problem.

Note: Although the file class is convenient to use and provides some nice features to object-oriented programming, the way that the classes work pretty much means that you will be linking in the entire file class if you use only a single method from the class. If you're trying to write a small program, you should use the fileio module rather than the file class.

15.1 General File Operations

filevar.create; @returns( "esi" );
 
file.create; @returns( "esi" );  [for dynamic objects]
 

The file class provides a file.create constructor which you should always call before making use of a file variable. For file variables (as opposed to file pointer variables), you should call this routine specifying the name of the file variable. For file pointer variables, you should call this routine using the class name and store the pointer returned in EAX into your file variable. For example, to initialize the two files in the previous example, you would use code like the following:


 
	MyOutputFile.create();
 

 
	file.create();
 
	mov( eax, filePtr );
 

 

Note that the file.create constructor simply initializes the virtual method table pointer and does other necessary internal initialization. The constructor does not open a file or perform other file-related activities.

filevar.handle; @returns( "eax" );
 

This method returns the file handle in the EAX register. The returned value is invalid if you have not opened the file. You can pass this handle value to any of the Standard Library file routines (e.g., fileio.putc) that expect a handle. You may also pass this value to Windows or Linux API functions that expect a file handle.

filevar.open( filename:string; access:dword )
 

This method opens an existing file. The filename parameter is a string specifying the name of the file you wish to open. The access parameter is one of the following:

The fileio.r constant tells filevar.open to open the file for read-only access. The fileio.w constant tells filevar.open to open the file for writing. Using the fileio.rw constant tells fileio.open to open the file for reading and writing. The fileio.a option tells the filevar.open function to open the file for writing and append all written data to the end of the file.

Before accessing the data in a file, you must open the file (which initializes the file handle). The filevar.open and filevar.openNew methods are excellent tools for this purpose. You may also open the file using direct calls to the Windows or Linux API, but you must initialize the filevar.fileHandle field of the class variable before making any other method calls in the file class.

filevar.openNew( filename:string )
 

This function opens a new file for writing (if the file already exists, it is first deleted and then a new file is opened for writing). The file is given the "normal" attribute.

Before accessing the data in a file, you must open the file (which initializes the file handle). The filevar.open and filevar.openNew methods are excellent tools for this purpose. You may also open the file using direct calls to the Windows or Linux API, but you must initialize the filevar.fileHandle field of the class variable before making any other method calls in the file class.

filevar.close;
 

This method closes a file opened via file.Open or file.OpenNew and flushes any buffered data to the disk.

The following routines behave just like the routines of the same name described earlier in this document, except, of course, they write their data to the specified output file.

15.2 File Class Output Routines

15.2.1 Miscellaneous Output

The following file output routines all assume that you've opened the filevar file variable via a call to filevar.open and you've successfully opened the file for output.

filevar.write( var buffer:byte; count:dword )
 

This method writes the number of bytes specified by the count variable to the file. The bytes starting at the address of the buffer byte are written to the file. No range checking is done on the buffer, it is your responsibility to ensure that the buffer contains at least count valid data bytes.

filevar.putbool( b:boolean );
 

This procedure writes the string "true" or "false" to the filevar output file depending on the value of the b parameter.

filevar.newln( );
 

This function writes a newline sequence (carriage return/line feed) to the specified output file (filevar).

15.2.2 Character, Character Set, and String Output

filevar.putc( c:char )
 

Writes the character specified by the c parameter to the filevar file.

filevar.putcSize( c:char; width:int32; fill:char )
 

Outputs the character c to the file filevar using at least width output positions. If the absolute value of width is greater than one, then this function writes fill characters as padding characters during the output. If width is a positive value greater than one, then filevar.putcSize writes c left justfied in a field of width characters; if width is a negative value less than one, then filevar.putcSize writes c right justified in a field of width characters.

filevar.putcset(  cst:cset  );
 

This function writes all the members of the cst character set parameter to the specified file variable.

filevar.puts( s:string );
 

This procedure writes the value of the string parameter to the specified file.

filevar.putsSize(  s:string; width:int32; fill:char )
 

This function writes the s string to the filevar file using at least width character positions. If the absolute value of width is less than or equal to the length of s, then this function behaves exactly like filevar.puts. On the other hand, if the absolute value of width is greater than the length of s, then filevar.putsSize writes width characters to the output file. This procedure emits the fill character in the extra print positions. If width is positive, then filevar.putsSize right justifies the string in the print field. If width is negative, then filevar.putsSize left justifies the string in the print field. Generally, people expect the string to be left justified, so you should ensure that this value is negative to achieve this.

15.2.3 Hexadecimal Numeric Output

filevar.putb( b:byte 	 )

filevar.putbSize( b:byte; size:dword; fill:char )
 

This procedure writes the value of b to filevar using exactly two hexadecimal digits (including a leading zero if necessary). The filevar.putbSize function lets you specify a minimum field width and a fill character. The filevar.putb routine uses a minimum size of two and a fill character of '0'.

filevar.putw( w:word	 )

filevar.putwSize( w:word; size:dword; fill:char )
 

This procedure writes the value of w to filevar using exactly four hexadecimal digits (including leading zeros if necessary). The filevar.putwSize function lets you specify a minimum field width and a fill character. The filevar.putw routine uses a minimum size of two and a fill character of '0'.

filevar.putd( dw:dword )

filevar.putdSize( d:dword; size:dword; fill:char )
 

This procedure writes the value of d to filevar using exactly eight hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The filevar.putdSize function lets you specify a minimum field width and a fill character. The filevar.putd routine uses a minimum size of two and a fill character of '0'.

filevar.putq( qw:qword )

filevar.putqSize( q:qword; size:dword; fill:char )
 

This procedure writes the value of q to filevar using exactly sixteen hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The filevar.putqSize function lets you specify a minimum field width and a fill character. The filevar.putq routine uses a minimum size of two and a fill character of '0'.

filevar.puttb( tb:tbyte )
 

This procedure writes the value of tb to filevar using exactly 20 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).

15.2.4 Signed Integer Numeric Output

These routines convert signed integer values to string format and write that string to the filevar file. The filevar.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

If the absolute value of width is greater than the number of print positions the value requires, then these functions output width characters to the output file. If width is non-negative, then these functions right-justify the value in the output field; if value is negative, then these functions left-justify the value in the output field.

These functions print the fill character as the padding value for the extra print positions.

Note that unlike floating point values, these functions do not print a space in front of the value if it is non-negative.



Figure 10 filevar.xxxSize Output Format

filevar.puti64Size( q:qword; width:int32; fill:char )
 

This function writes the 64-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

filevar.puti32Size( d:dword; width:int32;  fill:char )
 

This function writes the 32-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.

filevar.puti16Size( w:word;  width:int32; fill:char )
 

This function writes the 16-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

filevar.puti8Size ( b:byte;  width:int32; fill:char )
 

This function writes the eight-bit signed integer value you pass to the specified output file using the width and fill values as specified above.

filevar.puti64( q:qword )
 

This function converts the 64-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.puti32( d:dword )
 

This function converts the 32-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.puti16( w:word  )
 

This function converts the 16-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.puti8 ( b:byte  )
 

This function converts the eight-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

15.2.5 Unsigned Integer Numeric Output

These routines convert unsigned integer values to string format and write that string to the filevar file. The filevar.putxxxSize functions contain width and fill parameters that let you specify the minimum field width when outputting a value.

If the absolute value of width is greater than the number of print positions the value requires, then these functions output width characters to the output file. If width is non-negative, then these functions right-justify the value in the output field; if value is negative, then these functions left-justify the value in the output field.

These functions print the fill character as the padding value for the extra print positions.



Figure 11 filevar.uxxxSize Output Format

filevar.putu64Size( q:qword; width:int32; fill:char )
 

This function writes the unsigned 64-bit value you pass to the specified output file using the width and fill values as specified above.

filevar.putu32Size( d:dword; width:int32; fill:char )
 

This function writes the unsigned 32-bit value you pass to the specified output file using the width and fill values as specified above.

filevar.putu16size( w:word; width:int32; fill:char )
 

This function writes the unsigned 16-bit value you pass to the specified output file using the width and fill values as specified above.

filevar.putu8size( b:byte; width:int32; fill:char )
 

This function writes the unsigned eight-bit value you pass to the specified output file using the width and fill values as specified above.

filevar.putu64( q:qword )
 

This function converts the 64-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.putu32( d:dword )
 

This function converts the 32-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.putu16( w:word  )
 

This function converts the 16-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

filevar.putu8 ( b:byte  )
 

This function converts theeight-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by filevar) using the minimum number of print positions the number requires.

15.2.6 Floating Point Output

The HLA file I/O class provides several procedures you can use to write floating point files to a text file. The following subsections describe these routines.

15.2.6.1 Real Output Using Scientific Notation

The floating point numeric output routines translate the three different binary floating point formats to their string representation and then write this string to the file that filevar specifies. There are two generic classes of these routines: those that convert their values to exponential/scientific notation and those that convert their string to a decimal form.

The filevar.pute80, filevar.pute64, and filevar.pute32 routines convert their values to a string using scientific notation. These three routines each have two parameters: the value to output and the field width of the result. These routines produce a string with the following format:



filevar.pute80( r:real80; width:uns32 )
 

This function writes the 80-bit extended precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 80-bit extended precision floating point values support about 18 significant digits. So a width value that yeilds more than 18 mantissa digits will produce garbage output in the low order digits of the number.

filevar.pute64( r:real64; width:uns32 )
 

This function writes the 64-bit double precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 64-bit double precision floating point values support about 15 significant digits. So a width value that yeilds more than 15 mantissa digits will produce garbage output in the low order digits of the number.

filevar.pute32( r:real32; width:uns32 )
 

This function writes the 32-bit single precision floating point value passed in r to the file using scientific/exponential notation. This procedure prints the value using width print positions in the file. width should have a minimum value of five for real numbers in the range 1e-9..1e+9 and a minimum value of six for all other values. Note that 32-bit extended precision floating point values support about 6-7 significant digits. So a width value that yeilds more than seven mantissa digits will produce garbage output in the low order digits of the number.

15.2.6.2 Real Output Using Decimal Notation

Although scientific (exponential) notation is the most general display format for real numbers, real numbers you display in this format are very difficult to read. Therefore, the HLA file class module also provides a set of functions that output real values using the decimal representation. Although you cannot (practically) use these decimal output routines for all real values, they are applicable to a wide variety of common numbers you will use in your programs.

These functions come in two varieties. The first variety requires four parameters: the real value to convert, the width of the converted value, the number of digit positions to the right of the decimal point, and a padding character. The second variety only requires the first three parameters and assumes the padding character is a space. These functions write their values using the following string format:



Figure 12 filevar.putrxx Conversion Format

filevar.putr80pad( r:real80; width:uns32; decpts:uns32; pad:char )
 

This procedure writes an 80-bit extended precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

filevar.putr64pad( r:real64; width:uns32; decpts:uns32; pad:char )
 

This procedure writes a 64-bit double precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

filevar.putr32pad( r:real32; width:uns32; decpts:uns32; pad:char )
 

This procedure writes a 32-bit single precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

filevar.putr80( r:real80; width:uns32; decpts:uns32 )
 

This procedure writes an 80-bit extended precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses the value of pad as the padding character to fill the output with width characters.

filevar.putr64( r:real64; width:uns32; decpts:uns32 )
 

This procedure writes a 64-bit double precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

filevar.putr32( r:real32; width:uns32; decpts:uns32 )
 

This procedure writes a 32-bit single precision floating point value to the filevar file as a string. The string consumes exactly width characters in the output file. If the numeric output, using the specified number of positions to the right of the decimal point, is sufficiently small that the string representation would be less than width characters, then this procedure uses spaces as the padding character to fill the output with width characters.

15.2.7 Generic File Output

filevar.put( parameter_list )
 

filevar.put is a macro that automatically invokes an appropriate filevar output routine based on the type of the parameter(s) you pass it. This is a very convenient output routine and is probably the file class output call you will use most often in your programs. Keep in mind that this macro is not a single function call; instead, HLA translates this macro into a sequence of calls to procedures like filevar.puti32, filevar.puts, etc.

filevar.put is a macro that provides a flexible syntax for outputting data to the standard output device. This macro allows a variable number of parameters. For each parameter present in the list, filevar.put will call the appropriate routine to emit that data, according to the type of the parameter. Parameters may be constants, registers, or memory locations. You must separate each macro parameter with a comma.

Here is an example of a typical invocation of filevar.put:


 
filevar.put( "I=", i, " j=", j, nl );
 

 

The above is roughly equivalent to


 
filevar.puts( "I=" );
 
filevar.puti32( i );
 
filevar.puts( " j=" );
 
filevar.puti32( j );
 
filevar.newln();
 

 

This assumes, of course, that i and j are int32 variables.

The filevar.put macro also lets you specify the minimum field width for each parameter you specify. To print a value using a minimum field width, follow the object you wish to print with a colon and the value of the minimum field width. The previous example, using field widths, could look like the following:


 
filevar.put( "I=", i:2, " j=", j:5, nl );
 

 

Although this example used the literal decimal constants two and five for the field widths, keep in mind that register values and memory value (integers, anyway) are prefectly legal here.

For floating point numbers you wish to display in decimal form, you can specify both the minimum field width and the number of digits to print to the right of the decimal point by using the following syntax:


 
filevar.put( "Real value is ", f:10:3, nl );
 

 

The filevar.put macro can handle all the basic primitive types, including boolean, unsigned (8, 16, 32), signed (8, 16, 32), character, character set, real (32, 64, 80), string, and hexadecimal (byte, word, dword).

If you specify a class variable (object) and that class defines a "toString" method, the filevar.put macro will call the associated toString method and output that string to the file. Note that the toString method must dynamically allocate storage for the string by calling stralloc. This is because filevar.put will call strfree on the string once it outputs the string.

There is a known "design flaw" in the filevar.put macro. You cannot use it to print HLA intermediate variables (i.e., non-local VAR objects). The problem is that HLA's syntax for non-local accesses takes the form "reg32:varname" and filevar.put cannot determine if you want to print reg32 using varname print positions versus simply printing the non-local varname object. If you want to display non-local variables you must copy the non-local object into a register, a static variable, or a local variable prior to using filevar.put to print it. Of course, there is no problem using the other filevar.putXXXX functions to display non-local VAR objects, so you can use those as well.

Important(!), don't forget that method calls (e.g., the routines that filevar.put translates into) modify the values in the ESI and EDI registers. Therefore, it never makes any sense to attempt to print the values of ESI and EDI within the parameter list. All you will wind up doing is printing the address of the file variable (ESI) or the address of its virtual method table (EDI). If you need to write these two values to a file, move them to another register or a memory location first.

15.3 File Input

The following file input routines behave just like their standard input and file input counterparts (unless otherwise noted):

15.3.1 Generic File Input

filevar.read( var buffer:byte; count:dword )
 

This function reads count bytes from the file and stores them into memory starting with the first byte of the buffer variable. This routine does not do any range checking. It is your responsibility to ensure that buffer is large enough to hold the data read.

Note: for the file.read and file.write methods, it is very common to use type coercion to allow you to pass some other type as a parameter. Consider the following example:

 
 
program fileWriteDemo;
 
#include( "fileclass.hhf" );
 

 
static
 
    f:file;
 
    s:string := "Hello World";
 
        
 
begin fileWriteDemo;
 

 
    f.create();
 
    f.OpenNew( "Hello.txt" );
 
    mov( s, esi );
 
    f.write( (type byte [esi]), 11 );
 
    f.close();
 
    
 
end fileWriteDemo;
 

Program 2 File Output Demo

filevar.readln
 

This function reads and discards all characters up to and including the newline sequence in the file.

filevar.eoln
 

This function returns true (1) in AL if the file is currently at the end of a line, false (0) otherwise. This function reads and discards the newline sequence.

15.3.2 Character and String Input

The following functions read character data from an input file specified by filevar. Note that HLA's file class module does not provide the ability to read character set data directly from the user. However, you can always read a string and then convert that string to a character set using the appropriate function in the cset module.

filevar.getc; @returns( "al" );
 

This function reads a single character from the filevar file and returns that chraacter in the AL register. This function assumes that the file you've opened is a text file. Note that filevar.getc does not return the end of line sequence as part of the input stream. Use the filevar.eoln function to determine when you've reached the end of a line of text. Because filevar.getc preprocesses the text file (removing end of line sequences) you should not use it to read binary data, use it only to read text files.

filevar.gets( s:string )
 

This function reads a sequence of characters from the current filevar file position through to the next end of line sequence and stores these characters (without the end of line sequence) into the string variable you pass as a parameter. Before calling this routine, you must allocate sufficient storage for the string. If filevar.gets attempts to read a larger string than the string's MaxStrLen value, filevar.gets raises a string overflow exception.

Note that this function does not store the end of line sequence into the string, though it does consume the end of line sequence. The next character a filevar function will read from the file will be the first character of the following line.

If the current file position is at the end of some line of text, then filevar.gets consumes the end of line and stores the empty string into the s parameter.

filevar.a_gets; @returns( "eax" );
 

Like filevar.gets, this function also reads a string from the filevar file. However, rather than storing the string data into a string you supply, this function allocates storage for the string on the heap and returns a pointer to this string in the EAX register. You code should call strfree to release this storage when you're done with the string data.

The filevar.a_gets function imposes a line length limit of 1,024 characters. If this is a problem, you should modify the source code for this function to raise the limit. This functions raises an exception if you attempt to read a line longer than this internal limit.

15.3.3 Signed Integer Input

filevar.geti8;  @returns( "al" );
 

This function reads a signed eight-bit decimal integer in the range -128..+127 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.geti8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -128..+127. This function returns the binary form of the integer in the AL register.

filevar.geti16;  @returns( "ax" );
 

This function reads a signed 16-bit decimal integer in the range -32768..+32767 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.geti16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range -32768..+32767. This function returns the binary form of the integer in the AX register.

filevar.geti32;  @returns( "eax" );
 

This function reads a signed 32-bit decimal integer in the (approximate) range ±2 Billion from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.geti32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range plus or minus two billion. This function returns the binary form of the integer in the EAX register.

filevar.geti64( var q:qword );
 

This function reads a signed 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.geti64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 64-bit signed integer. This function stores the 64-bit result in the qword you pass as a reference parameter.

15.3.4 Unsigned Integer Input

filevar.getu8; @returns( "al" );
 

This function reads an unsigned eight-bit decimal integer in the range 0..+255 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getu8 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..255. This function returns the binary form of the integer in the AL register.

filevar.getu16; @returns( "ax" );
 

This function reads an unsigned 16-bit decimal integer in the range 0..+65535 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getu16 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..65535. This function returns the binary form of the integer in the AX register.

filevar.getu32; @returns( "eax" );
 

This function reads an unsigned 32-bit decimal integer in the range 0..+4,294,967,295 from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getu32 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..4,294,967,295. This function returns the binary form of the integer in the EAX register.

filevar.getu64( var q:qword );
 

This function reads an unsigned 64-bit decimal integer from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more decimal digits. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getu64 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..264-1. This function returns the binary form of the integer in the qword parameter you pass by reference.

15.3.5 Hexadecimal Input

filevar.getb; @returns( "al" );
 

This function reads an eight-bit hexadecimal integer in the range 0..$FF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getb function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FF. This function returns the binary form of the value in the AL register.

filevar.getw; @returns( "ax" );
 

This function reads a 16-bit hexadecimal integer in the range 0..$FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getw function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF. This function returns the binary form of the value in the AX register.

filevar.getd; @returns( "eax" );
 

This function reads a 32-bit hexadecimal integer in the range 0..$FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getd function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF. This function returns the binary form of the value in the EAX register.

filevar.getq( var q:qword );
 

This function reads a 64-bit hexadecimal integer in the range 0..$FFFF_FFFF_FFFF_FFFF from the file. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by a string of one or more hexadecimal digits. Note that the value may not have a leading "$" unless you add this character to the delimiter character set. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. The filevar.getq function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..$FFFF_FFFF_FFFF_FFFF. This function stores the 64-bit result into the variable you pass as a reference parameter.

15.3.6 Floating Point Input

filevar.getf; @returns( "st0" );
 

This function reads an 80-bit floating point value in either decimal or scientific from from the file and leaves the result sitting on the FPU stack. The number may begin with any number of delimiter characters (see the conv.setDelimiter and conv.getDelimiter functions for details on the delimiter characters) followed by an optional minus sign and a sequence of characters that represent a floating point value. The number must end with a valid delimiter character or the end of the file. This function allows underscores in the interior of the number. This function raises an appropriate exception if an error occurs.

15.3.7 Generic File Input

filevar.get( List_of_items_to_read );
 

This is a macro that allows you to specify a list of variable names as parameters. The file.get macro reads an input value for each item in the list and stores the resulting value in each corresponding variable. This macro determines the type of each variable that you pass it and emits a call to the appropriate filevar.getxxx function to read the actual value. As an example, consider the following call to filevar.get:

	filevar.get( i32, charVar, u16, strVar );
 

 

The macro invocation above expands into the following:

push( eax );
 
filevar.geti32( i32 );
 
filevar.getc();
 
mov( al, charVar );
 
filevar.geti16();
 
mov( ax, u16 );
 
filevar.gets( strVar );
 
pop( eax );
 

 

Notice that filevar.get preserves the value in the EAX register even though various filevar.getxxx functions use this register. Note that filevar.get automatically handles the case where you specify EAX as an input variable and writes the value to [esp] so that in properly modifies EAX upon completion of the macro expansion.

Note that fielvar.get only supports eight-, sixteen-, and thirty-two bit integer input. If you need to read 64-bit values, you must use the appropriate filevar.getx64 function to achieve this.



TOC PREV NEXT INDEX