![]() |
![]() |
![]() |
![]() |
16 The File I/O Module (fileio.hhf)
The file I/O functions are quite similar to the file class functions except that you explicitly pass a file handle to these routines rather than invoking a method via a file class variable. In fact, the file class methods call the corresponding fileio functions whenever you invoke a file object's methods. Therefore, if you want your programs to be a little smaller, you should use the fileio functions rather than the file class package.
16.1 General File I/O Functions
Here are the file output routines provided by the HLA fileio unit:
fileio.open( FileName: string; Access:dword ); @returns( "eax" );The fileio.open routine opens the file by the specified name. The Access parameter is one of the following:
The fileio.r constant tells HLA to open the file for read-only access. The fileio.w constant tells HLA 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 fileio.open function to open the file for writing and append all written data to the end of the file.
This routine raise an exception if there is a problem opening the file (e.g., the file does not exist). If the file is successfully opened, this function returns the file handle in the EAX register.
fileio.openNew( FileName: string ); @returns( "eax" );This function opens a new file for writing. The single parameter specifies the file's (path) name. This function raises an exception if there is an error opening the file. If the file is opened successfully, this function returns the file handle in the EAX register. If the file already exists, this function will successfully open the file and delete any existing data in the file.
fileio.close( Handle:dword );This function closes the file specfied by the handle passed as the parameter. You should close all files as soon as you are done using them. Note that successful program termination automatically closes all files, but it is exceeding poor programming practice to rely on the operating system to close any files you've left open. Were the machine to crash, data could be lost; for this reason, you should close all files as soon as you are finished reading and writing data.
fileio.eof( Handle:dword ); @returns( "al" );This function returns true (1) in AL if the specified file is at the end of file. It returns false (0) otherwise. Note that this function actually returns true/false in EAX even though the "returns" value is "AL". So don't count on it preserving the value in AH or the upper 16 bits of EAX.
Warning: fileio.eof only functions properly for actual disk files. If you attempt to read data from an interactive device like the system console (keyboard) or a serial port, fileio.eof's behavior is incorrect (it will wind up eating a character from the interactive input stream every time you call it). Unfortunately, neither Windows nor Linux provides a way to test for EOF until after you've actually read a character from the input stream. A better solution, which works fine with both interactive input streams and file data is to use HLA's try..endtry statement to trap and EOF error when it occurs. For example, rather than writing the following:
while( !fileio.eof( someHandle )) do . . . endwhile;You should write the following:
try forever . . . endfor; exception( ex.EndOfFile ); endtry;Note: under Windows, fileio.eof always returns false for character device files (e.g., keyboard input) and it returns false for all other non-disk file device types. Note that if the user presses ctrl-Z on the keyboard, fileio.eof will not return true, but the system will return an ex.endOfFile exception. If there is any chance you'll be reading data from a device file rather than a disk file, always use the try..endtry block to test for EOF.
16.2 Directory and File Manipulation Functions
fileio.rewind( Handle:dword ); @returns( "eax" );The Handle parameter specifies the handle of an open file. This function positions the file pointer to the beginning of the file (file position zero). This function returns the error code in EAX.
fileio.append( handle:dword ); @returns( "eax" );This function positions the file pointer of the file specified by the handle parameter to the end of that file. The file should have been opened for writing.
fileio.position( Handle:dword ); @returns( "eax" );This function returns the file position (in bytes) of the file specified by the handle parameter. It returns the file position offset in the EAX register.
fileio.seek( Handle:dword; offset:dword ); @returns( "eax" );This function sets the file position in the file specified by the Handle parameter to the position specified by the offset parameter. The offset parameter specifies the file position in bytes from the beginning of the file. It returns the error status in EAX.
fileio.rSeek( Handle:dword; offset:dword ); @returns( "eax" );This function sets the file position in the file specified by the Handle parameter to the position specified by the offset parameter. The offset parameter specifies the file position in bytes from the end of the file. It returns the error status in EAX.
fileio.truncate( Handle:dword ); @returns( "eax" );This function deletes all bytes in the file specified by the Handle parameter from the current file position to the end of the file. It returns the error status in EAX.
fileio.copy( source:string; dest:string; failIfExists:boolean ); @returns( "eax" );This function copies the file specified by the source filename to the file specified by the dest filename. This function returns an error if the fileIfExists parameter contains true and the destination file already exists.
fileio.move( source:string; dest:string ); @returns( "eax" );This function moves the file specified by the source filename to the destination file. If the paths are the same except for the filename, then this function renames the source file to use the dest filename.
fileio.delete( filename:string ); @returns( "eax" );This function deletes the specified filename. Obviously, use this function with care. It returns the Windows error status in EAX.
fileio.mkdir( dirname:string ); @returns( "eax" );This function creates a directory using the pathname you supply as a parameter. It returns the error status in EAX.
fileio.cd( dirname:string ); @returns( "eax" );This function sets the current working directory to the filename you pass as a parameter. It returns the error status in the EAX register.
fileio.exists( pathname:string ); @returns( "eax" );This function returns true if the file exists and the application can open the file (at least for reading). It returns false in EAX if the file does not exist, is inaccessible, or there is some other error that occurs when attemting to open the file.
fileio.gwd( dest:string );This function returns a string containing the current working directory's pathname in the string you pass as a parameter. The string must have storage allocated for it and it must be large enough to hold the pathname or HLA will raise a string overflow exception.
fileio.size( Handle:dword ); @returns( "eax" );This function returns the current size of an open file whose handle you pass as a parameter. It returns the size in the EAX register. Note the overloaded version below.
fileio.size( filename:string ); @returns( "eax" );This function returns the size of the file whose filename you pass as a parameter. It returns the file's size in the EAX register. Also see the overloaded version above.
16.3 File Output Routines
The file output routines in the fileio module are very similar to the file output routines in the file class module as well as the output routines in the standard output library module. In general, these routines require (at least) two parameters; the first is the file handle that you obtain via the fileio.open or fileio.openNew call, the second parameter is usually the value to write to the file. Some function contain additional parameters that provide formatting information. Note that these functions require that you've opened the file for writing, reading and writing, for for appending. If the file is not open or you've only opened it for reading, these routines will raise an appropriate exception.
16.3.1 Miscellaneous Output Routines
fileio.write( Handle:dword; var buffer:byte; count:uns32 )This procedure 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.
fileio.newln( Handle:dword )This function writes a newline sequence (carriage return/line feed) to the specified output file.
fileio.putbool( Handle:dword; b:boolean )This procedure writes the string "true" or "false" to the output file depending on the value of the b parameter.
16.3.2 Character, String, and Character Set Output Routines
fileio.putc( Handle:dword; c:char )Writes the character specified by the c parameter to the file.
fileio.putcSize( Handle:dword; c:char; width:int32; fill:char )Outputs the character c to the file 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 fileio.putcSize writes c left justfied in a field of width characters; if width is a negative value less than one, then fileio.putcSize writes c right justified in a field of width characters.
fileio.putcset( Handle:dword; cs:cset )This function writes all the members of the cst character set parameter to the specified file variable.
fileio.puts( Handle:dword; s:string )This procedure writes the value of the string parameter to the specified file.
fileio.putsSize( Handle:dword; s:string; width:int32; fill:char )This function writes the s string to the 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 fileio.puts. On the other hand, if the absolute value of width is greater than the length of s, then fileio.putsSize writes width characters to the output file. This procedure emits the fill character in the extra print positions. If width is positive, then fileio.putsSize right justifies the string in the print field. If width is negative, then fileio.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.
16.3.3 Hexadecimal Output Routines
fileio.putb( Handle:dword; b:byte ) fileio.putbSize( Handle:dword; b:byte; size:dword; fill:char )This procedure writes the value of b to the file using exactly two hexadecimal digits (including a leading zero if necessary). The fileio.putbSize function lets you specify a minimum field width and a fill character. The fileio.putb routine uses a minimum size of two and a fill character of '0'.
fileio.putw( Handle:dword; w:word ) fileio.putwSize( Handle:dword; w:word; size:dword; fill:char )This procedure writes the value of w to the file using exactly four hexadecimal digits (including leading zeros if necessary). The fileio.putwSize function lets you specify a minimum field width and a fill character. The fileio.putw routine uses a minimum size of two and a fill character of '0'.
fileio.putd( Handle:dword; dw:dword ) fileio.putdSize( Handle:dword; d:dword; size:dword; fill:char )This procedure writes the value of d to the file using exactly eight hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The fileio.putdSize function lets you specify a minimum field width and a fill character. The fileio.putd routine uses a minimum size of two and a fill character of '0'. Note that if underscore output is enabled, this routine will actually emit nine characters (eight digits plus an underscore).
fileio.putq( Handle:dword; qw:qword ) fileio.putqSize( Handle:dword; q:qword; size:dword; fill:char )This procedure writes the value of q to the file using exactly sixteen hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The fileio.putqSize function lets you specify a minimum field width and a fill character. The fileio.putq routine uses a minimum size of two and a fill character of '0'. Note that if underscore output is enabled, this routine will emit 19 characters (16 digits plus three underscores).
fileio.puttb( Handle:dword; tb:tbyte )This procedure writes the value of tb to the file using exactly 20 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled).
fileio.putl( Handle:dword; l:lword ) fileio.putlSize( Handle:dword; l:lword; size:dword; fill:char )This procedure writes the value of l to the file using exactly 32 hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). The fileio.putlSize function lets you specify a minimum field width and a fill character. The fileio.putl routine uses a minimum size of two and a fill character of '0'. Note that if underscore output is enabled, then this routine will actually emit 39 characters (32 digits plus seven underscores).
16.3.4 Signed Integer Output Routines
These routines convert signed integer values to string format and write that string to the file specified by the Handle parameter. The fileio.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 13 fileio.xxxSize Output Format
fileio.puti8Size ( Handle:dword; 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.
fileio.puti16Size( Handle:dword; 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.
fileio.puti32Size( Handle:dword; 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.
fileio.puti64Size( Handle:dword; 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.
fileio.puti128Size( Handle:dword; l:lword; width:int32; fill:char )This function writes the 128-bit value you pass as a signed integer to the specified output file using the width and fill values as specified above.
fileio.puti8 ( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.puti16( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.puti32( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.puti64( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.puti128( Handle:dword; l:lword )This function converts the 128-bit signed integer you pass as a parameter to a string and writes this string to the file (specified by Handle) using the minimum number of print positions the number requires.
16.3.5 Unsigned Integer Output Routines
These routines convert unsigned integer values to string format and write that string to the file specified by the Handle parameter. The fileio.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 14 fileio.uxxxSize Output Format
fileio.putu8Size( Handle:dword; 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.
fileio.putu16Size( Handle:dword; 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.
fileio.putu32Size( Handle:dword; 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.
fileio.putu64Size( Handle:dword; 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.
fileio.putu128Size( Handle:dword; l:lword; width:int32; fill:char )This function writes the unsigned 128-bit value you pass to the specified output file using the width and fill values as specified above.
fileio.putu8 ( Handle:dword; b:byte )This function converts the eight-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle) using the minimum number of print positions the number requires.
fileio.putu16( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.putu32( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.putu64( Handle:dword; 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 Handle) using the minimum number of print positions the number requires.
fileio.putu128( Handle:dword; l:lword )This function converts the 128-bit unsigned integer you pass as a parameter to a string and writes this string to the file (specified by Handle) using the minimum number of print positions the number requires.
16.3.6 Floating Point Output Routines
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.
16.3.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 the Handle parameter 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 fileio.pute80, fileio.pute64, and fileio.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:
![]()
Figure 15 Exponential (Scientific Notation) Output Format
fileio.pute80( Handle:dword; 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.
fileio.pute64( Handle:dword; 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.
fileio.pute32( Handle:dword; 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.
16.3.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 fileio 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 five 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 four parameters and assumes the padding character is a space. These functions write their values using the following string format:
![]()
Figure 16 fileio.putrxx Conversion Format
fileio.putr80pad( Handle:dword; r:real80; width:uns32; decpts:uns32; pad:char )This procedure writes an 80-bit extended precision floating point value to the 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.
fileio.putr64pad( Handle:dword; r:real64; width:uns32; decpts:uns32; pad:char )This procedure writes a 64-bit double precision floating point value to the 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.
fileio.putr32pad( Handle:dword; 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 the value of pad as the padding character to fill the output with width characters.
fileio.putr80( Handle:dword; r:real80; width:uns32; decpts:uns32 )This procedure writes an 80-bit extended precision floating point value to the 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.
fileio.putr64( Handle:dword; r:real64; width:uns32; decpts:uns32 )This procedure writes a 64-bit double precision floating point value to the 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.
fileio.putr32( Handle:dword; 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.
16.3.7 Generic File Output Routine
fileio.put( list_of_items )fileio.put is a macro that automatically invokes an appropriate fileio output routine based on the type of the parameter(s) you pass it. This is a very convenient output routine and is probably the fileio 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 fileio.puti32, fileio.puts, etc.
fileio.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, fileio.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 fileio.put:
fileio.put( "I=", i, " j=", j, nl );The above is roughly equivalent to
fileio.puts( "I=" ); fileio.puti32( i ); fileio.puts( " j=" ); fileio.puti32( j ); fileio.newln();This assumes, of course, that i and j are int32 variables.
The fileio.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:
fileio.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:
fileio.put( "Real value is ", f:10:3, nl );The fileio.put macro can handle all the basic primitive types, including boolean, unsigned (8, 16, 32, 64, 128), signed (8, 16, 32, 64, 128), character, character set, real (32, 64, 80), string, and hexadecimal (byte, word, dword, qword, lword).
If you specify a class variable (object) and that class defines a "toString" method, then fileio.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 fileio.put will call strfree on the string once it outputs the string.
There is a known "design flaw" in the fileio.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 fileio.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 fileio.put to print it. Of course, there is no problem using the other fileio.putXXXX functions to display non-local VAR objects, so you can use those as well.
16.4 File Input Routines
The HLA Standard Library provides a complementary set of file input routines. These routines behave in a fashion quite similar to the stdin.XXXX routines. See those routines for a additional examples of these procedures.
16.4.1 General File Input Routines
fileio.read( Handle:dword; var buffer:byte; count:uns32 )This routine reads a sequence of count bytes from the specified file, storing the bytes into memory at the address specified by buffer.
fileio.readLn( Handle:dword );This function reads, and discards, all characters in the file up to the next newline sequence (or end of file).
fileio.eoln( Handle:dword ); @returns( "al" );This function returns true (1) in EAX if the file is at the end of a line (note that the "returns" value is "al" even though this function returns its result in all of EAX). This function eats the newline sequence from the input.
16.4.2 Character and String Input Routines
The following functions read character data from an input file specified by filevar. Note that HLA's fileio 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.
fileio.getc( Handle:dword ); @returns( "al" );This function reads a single character from the file and returns that chraacter in the AL register. This function assumes that the file you've opened is a text file. Note that fileio.getc does not return the end of line sequence as part of the input stream. Use the fileio.eoln function to determine when you've reached the end of a line of text. Because fileio.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.
fileio.gets( Handle:dword; s:string );This function reads a sequence of characters from the current 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 fileio.gets attempts to read a larger string than the string's MaxStrLen value, fileio.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 fileio 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 fileio.gets consumes the end of line and stores the empty string into the s parameter.
fileio.a_gets( Handle:dword ); @returns( "eax" );Like fileio.gets, this function also reads a string from the 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 fileio.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.
16.4.3 Signed Integer Input Routines
fileio.geti8( Handle:dword ); @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 fileio.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.
fileio.geti16( Handle:dword ); @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 fileio.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.
fileio.geti32( Handle:dword ); @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 fileio.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.
fileio.geti64( Handle:dword );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 fileio.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 returns the 64-bit result in EDX:EAX.
fileio.geti128( Handle:dword; var dest:lword );This function reads a signed 128-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 fileio.geti128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range of a 128-bit signed integer. This function stores the 128-bit result in the lword you pass as a reference parameter.
16.4.4 Unsigned Integer Input Routines
fileio.getu8( Handle:dword ); @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 fileio.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.
fileio.getu16( Handle:dword ); @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 fileio.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.
fileio.getu32( Handle:dword ); @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 fileio.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.
fileio.getu64( Handle:dword );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 fileio.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 the EDX:EAX registers.
fileio.getu128( Handle:dword; var dest:lword );This function reads an unsigned 128-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 fileio.getu128 function raises an appropriate exception if the input violates any of these rules or the value is outside the range 0..2128-1. This function returns the binary form of the integer in the lword parameter you pass by reference.
16.4.5 Hexadecimal Input Routines
fileio.getb( Handle:dword ); @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 fileio.geth 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.
fileio.getw( Handle:dword ); @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 fileio.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.
fileio.getd( Handle:dword ); @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 fileio.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.
fileio.getq( Handle:dword );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 fileio.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 returns the 64-bit result in the EDX:EAX register pair.
fileio.getl( Handle:dword; var dest:lword );This function reads a 128-bit hexadecimal integer in the range zero through $FFFF_FFFF_FFFF_FFFF_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 fileio.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_FFFF_FFFF_FFFF_FFFF. This function stores the 128-bit result into the variable you pass as a reference parameter.
16.4.6 Floating Point Input
fileio.getf( Handle:dword );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.
16.4.7 Generic File Input
fileio.get( List_of_items_to_read );
This is a macro that allows you to specify a list of variable names as parameters. The fileio.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 fileio.getxxx function to read the actual value. As an example, consider the following call to filevar.get:
fileio.get( i32, charVar, u16, strVar );The macro invocation above expands into the following:
push( eax ); fileio.geti32( i32 ); fileio.getc(); mov( al, charVar ); fileio.geti16(); mov( ax, u16 ); fileio.gets( strVar ); pop( eax );Notice that fileio.get preserves the value in the EAX and EDX registers even though various fileio.getxxx functions use these registers. Note that fileio.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 fileio.get supports eight-bit, 16-bit, 32-bit, 64-bit, and 128-bit input values. It automatically selects the approriate input routine based on the type of the variable you specify.
![]() |
![]() |
![]() |
![]() |
![]() |