15 The File I/O Module (fileio.hhf)

Transcription

1 HLA Standard Library Reference 5 The File I/O Module (fileio.hhf) This unit contains routines that read data from and write data to files. The fileio functions can be broken down into four generic categories: general functions that open and close files, file position functions that get or set the current file position (or test the file position), output functions that write data to a file, and input functions that read data from a file. Note to stdlib v.x users: Several routines originally found in the fileio package have been moved to the new filesys package. The affected routines did not operate on file data, but on the file system itself. Examples include file deletion, get working directory, and change directory. Please see the filesys.rtf documentation for a description of those routines. Note: be sure to read the chapter on "Passing Parameters to Standard Library Routines" (parmpassing.rtf) before reading this chapter. Note about stack diagrams: this documentation includes stack diagrams for those functions that pass parameters on the stack. To conserve space, this documentation does not include a stack diagram for any function that does not pass data on the stack (that is, only a return address appears on the stack). A Note About the FPU: The Standard Library code makes occasional use of the FPU, particularly when converting between real and string formats and when computung certain mathematical functions. You should exercise caution when using MMX instructions in a program that makes use of the Standard Library. In particular, you should ensure that you are always in FPU mode (by executing an EMMS instruction) after you are finished using MMX instructions. Better yet, you should avoid the MMX instruction set altogether and use the improved SSE instruction set that accomplishes the same tasks (and doesn t disturb the FPU). 5. Conversion Format Control The fileio output functions that convert numeric values to hexadecimal, unsigned decimal, and signed decimal output provide the ability to inject underscores between groups of three (decimal) or four (hexadecimal) digits to make it easier to read large numbers. You enable and disable underscore output using the conv.setunderscores and conv.getunderscores functions. Please refer to their documentation in the conv.rtf file for more details. When reading numeric data from a text file, the fileio functions use an internal delimiters character set to determine which characters may legally end a sequence of numeric digits. You can change the complexion of this character set using the conv.getdelimiters and conv.setdelimiters functions. Please refer to their documentation in the conv.rtf file for more details. When converting numeric values to string form for output, the fileio routines call the conversion functions found in the conv (conversions) module. For detailed information on the actual conversions, please consult the conv.rtf document. 5. General File I/O Functions Here are the file output routines provided by the HLA fileio unit: Note: fileio.open is part of the os_fileio module in v. of the HLA stdlib. This function has not been updated yet and the semantics may change during the conversion to v.. fileio.open( FileName: string; Access:dword "eax" ); The fileio.open routine opens the file by the specified name. The Access parameter is one of the following: fileio.r fileio.w fileio.rw fileio.a 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. Released to the Public Domain Page 4

2 HLA Standard Library fileio.open( "myfile.txt", fileio.r ); mov( eax, filehandle ); // Note: the Access parameter is almost always a constant in // calls to fileio.open. However, if you want to pass a variable // value or a register value in this parameter, you may certainly // do so: fileio.open( filenamestr, accessvar ); mov( eax, filehandle ); fileio.open( somestr, al ); mov( eax, filehandle ); // Constant Access value: push( filenamestr ); pushd( fileio.r ); call fileio.open; mov( eax, filehandle ); // Access value in register (AL in this example) push( filenamestr ); call fileio.open; mov( eax, filehandle ); // Access value is in a (byte) variable push( filenamestr ); push( (type dword accessvalue)); //Not always safe! call fileio.open; mov( eax, filehandle ); // Solution if accessing accessvalue as a dword // might cause a memory access error (last three // bytes on a 4K page in memory, etc.): push( filenamestr ); sub( 4, esp ); movzx( accessvalue, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.open; mov( eax, filehandle ); // Note: If you want to use a string literal, the best solution is // to create a string object in the readonly section, e.g., // // readonly // filenamestr :string := "myfile.txt"; // // and just use the "filenamestr" object you ve created. You may also Page 4 Version: 4/8/ Written by Randall Hyde

3 HLA Standard Library Reference // do the following if you have a register available: lea( eax, "myfile.txt" ); pushd( fileio.r ); call fileio.open; mov( eax, filehandle ); fileio.open stack diagram +8 FileName :string Access :dword fileio.opennew( FileName: string "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.opennew( "myfile.txt" ); mov( eax, filehandle ); // If the filename string pointer is in a register (EAX): fileio.opennew( eax ); mov( eax, filehandle ); push( filenamestr ); call fileio.opennew; mov( eax, filehandle ); // If the string pointer value is in a register (EAX // in this example): call fileio.opennew; mov( eax, filehandle ); Released to the Public Domain Page 4

4 HLA Standard Library // Note: If you want to use a string literal, the best solution is // to create a string object in the readonly section, e.g., // // readonly // filenamestr :string := "myfile.txt"; // // and just use the "filenamestr" object you ve created. You may also // do the following if you have a register available: lea( eax, "myfile.txt" ); call fileio.opennew; mov( eax, filehandle ); fileio.opennew stack diagram FileName :string 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.close( filehandle ); // If the file handle is in a register (EAX): fileio.close( eax ); call fileio.close; // If the file handle is in a register (EAX): Page 44 Version: 4/8/ Written by Randall Hyde

5 HLA Standard Library Reference call fileio.close; fileio.putcsize stack diagram fill :char width :int c :char fileio.flush( Handle:dword ); This function flushes all pending data to the file (same operation as closing the file, without actually closing it). Note that successful program termination automatically closes all files, but were a crash to occur, some data might be lost. Flushing the file on a periodic basis can help prevent file data loss. fileio.flush( filehandle ); // If the file handle is in a register (EAX): fileio.flush( eax ); call fileio.flush; // If the file handle is in a register (EAX): call fileio.flush; Released to the Public Domain Page 45

6 HLA Standard Library fileio.flush stack diagram fileio.eof( Handle:dword "al" ); This function returns true () in AL if the specified file is at the end of file. It returns false () 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 6 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. while(!fileio.eof( filehandle ) ) do <<something while not at EOF>> Page 46 Version: 4/8/ Written by Randall Hyde

7 HLA Standard Library Reference endwhile; whilenoteof: call fileio.flush; cmp( al, true ); jne ateof; << something while not at EOF>> jmp whilenoteof; ateof: fileio.eof stack diagram fileio.rewind( Handle:dword "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.rewind( filehandle ); // If the file handle is in a register (EAX): fileio.rewind( eax ); call fileio.rewind; // If the file handle is in a register (EAX): Released to the Public Domain Page 47

8 HLA Standard Library call fileio.rewind; fileio.rewind stack diagram fileio.append( handle:dword "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.append( filehandle ); // If the file handle is in a register (EAX): fileio.append( eax ); call fileio.append; // If the file handle is in a register (EAX): call fileio.append; Page 48 Version: 4/8/ Written by Randall Hyde

9 HLA Standard Library Reference fileio.rewind stack diagram fileio.position( Handle:dword "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.position( filehandle ); mov( eax, (type dword fileposition)); // If the file handle is in a register (EAX): fileio.position( eax ); mov( eax, (type dword fileposition)); call fileio.position; mov( eax, (type dword fileposition)); // If the file handle is in a register (EAX): call fileio.position; mov( eax, (type dword fileposition)); Released to the Public Domain Page 49

10 HLA Standard Library fileio.position stack diagram fileio.seek( Handle:dword; offset:qword "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.seek( filehandle, qwordoffsetvar ); push( (type dword qwordoffsetvar[4])); push( (type dword qwordoffsetvar)); call fileio.seek; // If the file handle is in a register (EAX): push( (type dword qwordoffsetvar[4])); push( (type dword qwordoffsetvar)); call fileio.seek; // If the offset is in a register pair (EDX:EAX): push( edx ); // H.O. dword of offset // L.O. dword of offset call fileio.seek; Page 5 Version: 4/8/ Written by Randall Hyde

11 HLA Standard Library Reference fileio.seek stack diagram + +8 offset (H.O. dword) offset (L.O. dword) offset :qword fileio.rseek( Handle:dword; offset:qword "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.rseek( filehandle, qwordoffsetvar ); push( (type dword qwordoffsetvar[4])); push( (type dword qwordoffsetvar)); call fileio.rseek; // If the file handle is in a register (EAX): push( (type dword qwordoffsetvar[4])); push( (type dword qwordoffsetvar)); call fileio.rseek; // If the offset is in a register pair (EDX:EAX): push( edx ); // H.O. dword of offset // L.O. dword of offset call fileio.rseek; Released to the Public Domain Page 5

12 HLA Standard Library fileio.rseek stack diagram + +8 offset (H.O. dword) offset (L.O. dword) offset :qword fileio.truncate( Handle:dword "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.truncate( filehandle ); // If the file handle is in a register (EAX): fileio.truncate( eax ); call fileio.truncate; // If the file handle is in a register (EAX): call fileio.truncate; Page 5 Version: 4/8/ Written by Randall Hyde

13 HLA Standard Library Reference fileio.truncate stack diagram fileio.size( Handle:dword "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( filehandle ); mov( eax, filesize ); // If the file handle is in a register (EAX): fileio.size( eax ); mov( eax, filesize ); call fileio.size; mov( eax, filesize ); // If the file handle is in a register (EAX): call fileio.size; mov( eax, filesize ); Released to the Public Domain Page 5

14 HLA Standard Library fileio.size stack diagram 5. 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. 5.. Miscellaneous Output Routines fileio.write( Handle:dword; var buffer:var; count:uns ); 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. Note that buffer is an untyped reference parameter. This means that fileio.write will take the address of whatever object you provide as this parameter (including pointer variables, which may not be what you want). If you want to pass the value of a pointer variable as the buffer address (rather than the address of the pointer variable) when using the high-level style calling syntax, use the VAL keyword as a prefix to the parameter (see the following examples). fileio.write( filehandle, buffer, count ); // If bufptr is a dword object containing the // address of the buffer whose data you wish to // write to the file: fileio.write( filehandle, val bufptr, count ); // The following writes the four-byte value of // the bufptr variable to the file (an unusual // operation): fileio.write( filehandle, bufptr, 4 ); Page 54 Version: 4/8/ Written by Randall Hyde

15 HLA Standard Library Reference // Assumes buffer is a static object at a fixed // address in memory: pushd( &buffer ); push( count ); call fileio.write; // If a -bit register is available and buffer // isn t at a fixed, static, address: lea( eax, buffer ); push( count ); call fileio.write; // If a -bit register is not available and buffer // isn t at a fixed, static, address: sub( 4, esp ); lea( eax, buffer ); mov( eax, [esp+4] ); pop( eax ); push( count ); call fileio.write; // If bufptr points at the buffer to write, // then use code like this: push( bufptr); push( count ); call fileio.write; // To write the 4 bytes at bufptr to // the file (unusual), you could use // code like this: lea( eax, bufptr ); pushd( 4 ); call fileio.write; Released to the Public Domain Page 55

16 HLA Standard Library fileio.write stack diagram + +8 count :uns buffer :pointer fileio.newln( Handle:dword ) This function writes a newline sequence (e.g., carriage return/line feed under Windows or line feed under Linux) to the specified output file. fileio.newln( filehandle ); // If the file handle is in a register (EAX): fileio.newln( eax ); call fileio.newln; // If the file handle is in a register (EAX): call fileio.newln; Page 56 Version: 4/8/ Written by Randall Hyde

17 HLA Standard Library Reference fileio.append stack diagram 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. fileio.putbool( filehandle, boolvar ); // If the boolean is in a register (AL): fileio.putbool( filehandle, al ); // If "boolvar" is not one of the last three // bytes on a page of memory, you can do this: push( (type dword boolvar ) ); call fileio.putbool; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( boolvar, eax ); // Assume EAX is available call fileio.putbool; // If no register is available, do something // like the following code: sub( 4, esp ); Released to the Public Domain Page 57

18 HLA Standard Library movzx( boolvar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.putbool; // If the boolean value is in al, bl, cl, or dl // then you can use code like the following: // Assume boolvar is in AL call fileio.putbool; // If the Boolean value is in ah, bh, ch, or dh // you ll have to use code like the following: xchg( al, ah ); // Assume boolvar is in AH // It s now in AL xchg( al, ah ); // Restore al/ah call fileio.putbool; fileio.putbool stack diagram +8 b :boolean 5.. Character, String, and Character Set Output Routines fileio.putc( Handle:dword; c:char ) Writes the character specified by the c parameter to the file specified by the Handle parameter. fileio.putc( filehandle, charvar ); // If the character is in a register (AL): fileio.putc( filehandle, al ); Page 58 Version: 4/8/ Written by Randall Hyde

19 HLA Standard Library Reference // If "charvar" is not one of the last three // bytes on a page of memory, you can do this: push( (type dword charvar) ); call fileio.putc; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( charvar, eax ); // Assume EAX is available call fileio.putc; // If no register is available, do something // like the following code: sub( 4, esp ); movzx( charvar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.putc; // If the character value is in al, bl, cl, or dl // then you can use code like the following: // Assume charvar is in AL call fileio.putc; // If the character value is in ah, bh, ch, or dh // you ll have to use code like the following: xchg( al, ah ); // Assume charvar is in AH // It s now in AL xchg( al, ah ); // Restore al/ah call fileio.putc; fileio.putc stack diagram +8 c :char Released to the Public Domain Page 59

20 HLA Standard Library fileio.putcsize( Handle:dword; c:char; width:int; 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.putcsize( filehandle, charvar, width, padchar ); // If "charvar" and "padchar" are not one of the last three // bytes on a page of memory, you can do this: push( (type dword charvar) ); push( (type dword padchar) ); call fileio.putcsize; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( charvar, eax ); // Assume EAX is available movzx( padchar, ebx ); // Assume EBX is available push( ebx ); call fileio.putcsize; // If no registers are available, do something // like the following code: sub(, esp ); movzx( charvar, eax ); mov( eax, [esp+] ); mov( width, eax ); mov( eax, [esp+8] ); movzx( padchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.putcsize; // If "charvar" or "padchar" are in an // 8-bit register, then you can push // the corresponding -bit register if // the register is AL, BL, CL, or DL: // Assume charvar is in AL Page 6 Version: 4/8/ Written by Randall Hyde

21 HLA Standard Library Reference push( ebx ); // Assume padchar is in BL call fileio.putcsize; // Do the following if the characters are // in AH, BH, CH, or DH: xchg( al, ah ); // Assume charvar is in AH xchg( bl, bh ); // Assume padchar is in BH push( ebx ); xchg( al, ah ); xchg( bl, bh ); call fileio.putcsize; fileio.putcsize stack diagram fill :char width :int c :char fileio.putcset( Handle:dword; cst:cset ) This function writes all the members of the cst character set parameter to the file specified by the Handle variable. fileio.putcset( filehandle, csvar ); fileio.putcset( filehandle, [ebx] ); // EBX points at the cset. push( (type dword csvar[]) ); // Push H.O. dword first push( (type dword csvar[8]) ); push( (type dword csvar[4]) ); push( (type dword csvar) ); // Push L.O. dword last call fileio.putcset; Released to the Public Domain Page 6

22 HLA Standard Library fileio.putcset stack diagram cs (H.O. dword) cs (L.O. dword) cs:cset fileio.puts( Handle:dword; s:string ) This procedure writes the value of the string parameter to the specified file. Remember, string values are actually 4-byte pointers to the string s character data. fileio.puts( filehandle, strvar ); fileio.puts( filehandle, ebx ); // EBX holds a string value. fileio.puts( filehandle, "Hello World" ); // For string variables: push( strvar ); call fileio.puts; // For string values held in registers: push( ebx ); // Assume EBX holds the string value call fileio.puts; // For string literals, assuming a -bit register // is available: lea( eax, "Hello World" ); // Assume EAX is available. call fileio.puts; Page 6 Version: 4/8/ Written by Randall Hyde

23 HLA Standard Library Reference // If a -bit register is not available: readonly literalstring :string := "Hello World";... push( literalstring ); call fileio.puts; fileio.puts stack diagram +8 s :string fileio.putssize( Handle:dword; s:string; width:int; 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. fileio.putssize( filehandle, strvar, width, ); // For the following, EBX holds the string value, // ECX contains the width, and AL holds the pad // character: fileio.putssize( filehandle, ebx, ecx, al ); fileio.putssize( filehandle, "Hello World", 5, padchar ); // For string variables: push( strvar ); Released to the Public Domain Page 6

24 HLA Standard Library pushd( ); call fileio.putssize; // For string values held in registers: push( ebx ); // Assume EBX holds the string value push( ecx ); // Assume ECX holds the width // Assume AL holds the fill character call fileio.putssize; // For string literals, assuming a -bit register // is available: lea( eax, "Hello World" ); // Assume EAX is available. pushd( 5 ); movzx( padchar, eax ); call fileio.putssize; // If a -bit register is not available: readonly literalstring :string := "Hello World"; // Note: element zero is the actual pad character. // The other elements are just padding. padchar :char[4] := [., #, #, # ];... push( literalstring ); pushd( 5 ); push( (type dword padchar) ); call fileio.putssize; fileio.putssize stack diagram fill :char width :int s :string Page 64 Version: 4/8/ Written by Randall Hyde

25 HLA Standard Library Reference 5.. Hexadecimal Output Routines fileio.putb( Handle:dword; b:byte ) This procedure writes the value of b to the file using exactly two hexadecimal digits (including a leading zero if necessary). fileio.putb( filehandle, bytevar ); // If the character is in a register (AL): fileio.putb( filehandle, al ); // If "bytevar " is not one of the last three // bytes on a page of memory, you can do this: push( (type dword bytevar ) ); call fileio.putb; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( bytevar, eax ); // Assume EAX is available call fileio.putb; // If no register is available, do something // like the following code: sub( 4, esp ); movzx( bytevar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.putb; // If the character value is in al, bl, cl, or dl // then you can use code like the following: // Assume bytevar is in AL call fileio.putb; // If the byte value is in ah, bh, ch, or dh // you ll have to use code like the following: xchg( al, ah ); // Assume bytevar is in AH // It s now in AL Released to the Public Domain Page 65

26 HLA Standard Library xchg( al, ah ); // Restore al/ah call fileio.putb; fileio.putb stack diagram +8 b :byte fileio.puth8( Handle:dword; b:byte ) This procedure writes the value of b to the file using the minimum necessary number of hexadecimal digits. fileio.puth8( filehandle, bytevar ); // If the character is in a register (AL): fileio.puth8( filehandle, al ); // If "bytevar " is not one of the last three // bytes on a page of memory, you can do this: push( (type dword bytevar ) ); call fileio.puth8; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( bytevar, eax ); // Assume EAX is available call fileio.puth8; // If no register is available, do something // like the following code: Page 66 Version: 4/8/ Written by Randall Hyde

27 HLA Standard Library Reference sub( 4, esp ); movzx( bytevar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth8; // If the character value is in al, bl, cl, or dl // then you can use code like the following: // Assume bytevar is in AL call fileio.puth8; // If the byte value is in ah, bh, ch, or dh // you ll have to use code like the following: xchg( al, ah ); // Assume bytevar is in AH // It s now in AL xchg( al, ah ); // Restore al/ah call fileio.puth8; fileio.puth8 stack diagram +8 b :byte fileio.puth8size( Handle:dword; b:byte; size:dword; fill:char ) The fileio.puth8size function writes an 8-bit hexadecimal value to a file allowing you specify a minimum field width and a fill character. fileio.puth8size( filehandle, bytevar, width, padchar ); // If "bytevar" and "padchar" are not one of the last three // bytes on a page of memory, you can do this: Released to the Public Domain Page 67

28 HLA Standard Library push( (type dword bytevar) ); push( (type dword padchar) ); call fileio.puth8size; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( bytevar, eax ); // Assume EAX is available movzx( padchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puth8size; // If no registers are available, do something // like the following code: sub(, esp ); movzx( bytevar, eax ); mov( eax, [esp+] ); mov( width, eax ); mov( eax, [esp+8] ); movzx( padchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth8size; // If "bytevar" or "padchar" are in an // 8-bit register, then you can push // the corresponding -bit register if // the register is AL, BL, CL, or DL: // Assume bytevar is in AL push( ebx ); // Assume padchar is in BL call fileio.puth8size; // Do the following if the characters are // in AH, BH, CH, or DH: xchg( al, ah ); // Assume bytevar is in AH xchg( bl, bh ); // Assume padchar is in BH push( ebx ); xchg( al, ah ); xchg( bl, bh ); call fileio.puth8size; Page 68 Version: 4/8/ Written by Randall Hyde

29 HLA Standard Library Reference fileio.puth8size stack diagram fill :char width :int b :byte fileio.putw( Handle:dword; w:word ) This procedure writes the value of w to the file using exactly four hexadecimal digits (including leading zeros if necessary). fileio.putw( filehandle, wordvar ); // If the word is in a register (AX): fileio.putw( filehandle, ax ); // If "wordvar " is not one of the last three // bytes on a page of memory, you can do this: push( (type dword wordvar) ); call fileio.putw; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( wordvar, eax ); // Assume EAX is available call fileio.putw; // If no register is available, do something // like the following code: Released to the Public Domain Page 69

30 HLA Standard Library sub( 4, esp ); movzx( wordvar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.putw; // If the word value is in a 6-bit register // then you can use code like the following: // Assume wordvar is in AX call fileio.putw; fileio.putw stack diagram +8 w :word fileio.puth6( Handle:dword; w:word ) This procedure writes the value of w to the file using the minimum necessary number of hexadecimal digits. fileio.puth6( filehandle, wordvar ); // If the word is in a register (AX): fileio.puth6( filehandle, ax ); // If "wordvar " is not one of the last three // bytes on a page of memory, you can do this: push( (type dword wordvar) ); call fileio.puth6; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like Page 7 Version: 4/8/ Written by Randall Hyde

31 HLA Standard Library Reference // the following: movzx( wordvar, eax ); // Assume EAX is available call fileio.puth6; // If no register is available, do something // like the following code: sub( 4, esp ); movzx( wordvar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth6; // If the word value is in a 6-bit register // then you can use code like the following: // Assume wordvar is in AX call fileio.puth6; fileio.puth6 stack diagram +8 w :word fileio.puth6size( Handle:dword; w:word; size:dword; fill:char ) The fileio.puth6size function writes a 6-bit hexadecimal value to a file allowing you specify a minimum field width and a fill character. fileio.puth6size( filehandle, wordvar, width, padchar ); // If "wordvar" and "padchar" are not one of the last three // bytes on a page of memory, you can do this: Released to the Public Domain Page 7

32 HLA Standard Library push( (type dword wordvar) ); push( (type dword padchar) ); call fileio.puth6size; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( wordvar, eax ); // Assume EAX is available movzx( padchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puth6size; // If no registers are available, do something // like the following code: sub(, esp ); movzx( wordvar, eax ); mov( eax, [esp+] ); mov( width, eax ); mov( eax, [esp+8] ); movzx( padchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth6size; // If "wordvar" is in a 6-bit register // and "padchar" is in an // 8-bit register, then you can push // the corresponding -bit register if // the register is AL, BL, CL, or DL: // Assume wordvar is in AX push( ebx ); // Assume padchar is in BL call fileio.puth6size; Page 7 Version: 4/8/ Written by Randall Hyde

33 HLA Standard Library Reference fileio.puth6size stack diagram fill :char width :int w :word fileio.putd( Handle:dword; d:dword ) This procedure writes the value of d to the file using exactly eight hexadecimal digits (including leading zeros if necessary), if underscore output is not enabled. This routine will emit nine characters (eight digits plus an underscore) if underscore output is enabled. fileio.putd( filehandle, dwordvar ); // If the dword value is in a register (EAX): fileio.putd( filehandle, eax ); push( dwordvar ); call fileio.putd; call fileio.putd; Released to the Public Domain Page 7

34 HLA Standard Library fileio.putd stack diagram +8 d :dword fileio.puth( Handle:dword; d:dword ) This procedure writes the value of d to the file using the minimum number of hexadecimal digits necessary. If underscore output is enabled (see conv.setunderscores and conv.getunderscores) then this function will emit an underscore between groups of four hexadecimal digits, starting from the least signficant digit. fileio.puth( filehandle, dwordvar ); // If the dword is in a register (EAX): fileio.puth( filehandle, eax ); push( dwordvar ); call fileio.puth; call fileio.puth; Page 74 Version: 4/8/ Written by Randall Hyde

35 HLA Standard Library Reference fileio.puth stack diagram +8 d :dword fileio.puthsize( Handle:dword; d:dword; size:dword; fill:char ) The fileio.puthsize function outputs d as a hexadecimal string (including underscores, if enabled) and it allows you specify a minimum field width and a fill character. fileio.puthsize( filehandle, dwordvar, width, ); // If the dword is in a register (EAX): fileio.puthsize( filehandle, eax, width, cl ); push( dwordvar ); pushd( ); call fileio.puthsize; push( ecx ); // fill char is in CL call fileio.puthsize; // Assume fill char is in CH xchg( cl, ch ); // fill char is in CH push( ecx ); xchg( cl, ch ); call fileio.puthsize; Released to the Public Domain Page 75

36 HLA Standard Library // Alternate method of the above sub( 4, esp ); mov( ch, [esp] ); call fileio.puthsize; // If the fill char is a variable and // a register is available, try this code: movzx( fillchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puthsize; // If the fill char is a variable and // no register is available, here s one // possibility: push( (type dword fillchar) ); // Chance of page crossing! call fileio.puthsize; // In the very rare case that the above would // cause an illegal memory access, use this: sub( 4, esp ); movzx( fillchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puthsize; fileio.puthsize stack diagram fill :char width :int d :dword Page 76 Version: 4/8/ Written by Randall Hyde

37 HLA Standard Library Reference fileio.putq( Handle:dword; q:qword ) 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). fileio.putq( filehandle, qwordvar ); push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last call fileio.putq; fileio.putq stack diagram + +8 qw (H.O. dword) qw (L.O. dword) qw :qword fileio.puth64( Handle:dword; q:qword ) This procedure writes the value of q to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled). fileio.puth64( filehandle, qwordvar ); push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last call fileio.puth64; Released to the Public Domain Page 77

38 HLA Standard Library fileio.puth64 stack diagram + +8 qw (H.O. dword) qw (L.O. dword) qw :qword fileio.puth64size( Handle:dword; q:qword; size:dword; fill:char ) 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. Note that if underscore output is enabled, this routine will emit 9 characters (6 digits plus three underscores). fileio.puth64size( filehandle, qwordvar, width, ); push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last pushd( ); call fileio.puth64size; push( edx ); // Assume 64-bit value in edx:eax push( ecx ); // fill char is in CL call fileio.puth64size; // Assume fill char is in CH push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last xchg( cl, ch ); // fill char is in CH push( ecx ); xchg( cl, ch ); call fileio.puth64size; Page 78 Version: 4/8/ Written by Randall Hyde

39 HLA Standard Library Reference // Alternate method of the above push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last sub( 4, esp ); mov( ch, [esp] ); call fileio.puth64size; // If the fill char is a variable and // a register is available, try this code: push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last movzx( fillchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puth64size; // If the fill char is a variable and // no register is available, here s one // possibility: push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last push( (type dword fillchar) ); // Chance of page crossing! call fileio.puth64size; // In the very rare case that the above would // cause an illegal memory access, use this: push( (type dword qwordvar[4]) ); // H.O. dword first push( (type dword qwordvar)); // L.O. dword last sub( 4, esp ); movzx( fillchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth64size; Released to the Public Domain Page 79

40 HLA Standard Library fileio.puth64size stack diagram q (H.O. dword) q (L.O. dword) fill :char width :uns a :qword fileio.puttb( Handle:dword; tb:tbyte ) This procedure writes the value of tb to the file using exactly hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). fileio.puttb( filehandle, tbytevar ); pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last call fileio.puttb; Page 8 Version: 4/8/ Written by Randall Hyde

41 HLA Standard Library Reference fileio.puttb stack diagram (padding) tb (L.O. dword) tb (H.O. word) tb :tbyte fileio.puth8( Handle:dword; tb:tbyte ) This procedure writes the value of tb to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled). fileio.puth8( filehandle, tbytevar ); pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last call fileio.puth8; Released to the Public Domain Page 8

42 HLA Standard Library fileio.puth8 stack diagram (padding) tb (L.O. dword) tb (H.O. word) tb :tbyte fileio.puth8size( Handle:dword; tb:tbyte; size:dword; fill:char ) The fileio.puth8size function lets you specify a minimum field width and a fill character. It writes the tbyte value tb as a hexadecimal string to the specified file using the provided minimum size and fill character. fileio.puth8size( filehandle, tbytevar, width, ); pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last pushd( ); call fileio.puth8size; // Assume fill char is in CH pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last xchg( cl, ch ); // fill char is in CH push( ecx ); xchg( cl, ch ); Page 8 Version: 4/8/ Written by Randall Hyde

43 HLA Standard Library Reference call fileio.puth8size; // Alternate method of the above pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last sub( 4, esp ); mov( ch, [esp] ); call fileio.puth8size; // If the fill char is a variable and // a register is available, try this code: pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last movzx( fillchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puth8size; // If the fill char is a variable and // no register is available, here s one // possibility: pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last push( (type dword fillchar) ); // Chance of page crossing! call fileio.puth8size; // In the very rare case that the above would // cause an illegal memory access, use this: pushw( ); // Push push a pad word push( (type word tbytevar[8])); // Push H.O. word first push( (type dword tbytevar[4]) ); // M.O. dword second push( (type dword tbytevar)); // L.O. dword last sub( 4, esp ); movzx( fillchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth8size; Released to the Public Domain Page 8

44 HLA Standard Library fileio.puth8size stack diagram (padding) tb (L.O. dword) fill :char size :uns tb (H.O. word) tb :tbyte fileio.putl( Handle:dword; l:lword ) This procedure writes the value of l to the file using exactly hexadecimal digits (including leading zeros if necessary and an intervening underscores if underscore output is enabled). fileio.putl( filehandle, lwordvar ); push( (type dword lwordvar[]) ); // H.O. dword first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last call fileio.putl; Page 84 Version: 4/8/ Written by Randall Hyde

45 HLA Standard Library Reference fileio.putl stack diagram l (H.O. dword) l (L.O. dword) l :lword fileio.puth8( Handle:dword; l:lword ) This procedure writes the value of l to the file using the minimum necessary number of hexadecimal digits (including intervening underscores if underscore output is enabled). fileio.puth8( filehandle, lwordvar ); push( (type dword lwordvar[]) ); // H.O. dword first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last call fileio.puth8; Released to the Public Domain Page 85

46 HLA Standard Library fileio.puth8 stack diagram l (H.O. dword) l (L.O. dword) l :lword fileio.puth8size( Handle:dword; l:lword; size:dword; fill:char ) The fileio.puth8size function writes an lword value to the file and it lets you specify a minimum field width and a fill character. fileio.puth8size( filehandle, tbytevar, width, ); push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last pushd( ); call fileio.puth8size; // Assume fill char is in CH push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last xchg( cl, ch ); // fill char is in CH push( ecx ); xchg( cl, ch ); Page 86 Version: 4/8/ Written by Randall Hyde

47 HLA Standard Library Reference call fileio.puth8size; // Alternate method of the above push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last sub( 4, esp ); mov( ch, [esp] ); call fileio.puth8size; // If the fill char is a variable and // a register is available, try this code: push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last movzx( fillchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puth8size; // If the fill char is a variable and // no register is available, here s one // possibility: push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last push( (type dword fillchar) ); // Chance of page crossing! call fileio.puth8size; // In the very rare case that the above would // cause an illegal memory access, use this: push( (type dword lwordvar[])); // Push H.O. word first push( (type dword lwordvar[8]) ); push( (type dword lwordvar[4]) ); push( (type dword lwordvar)); // L.O. dword last sub( 4, esp ); movzx( fillchar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puth8size; Released to the Public Domain Page 87

48 HLA Standard Library fileio.puth8size stack diagram l (H.O. dword) l (L.O. dword) fill :char width :uns l :lword 5..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 nonnegative. xxxsize( value, width, fill ); Assuming value requires five print positions, width is eight, and fill is f then the xxxsize functions produce the string f f f V A L U E Assuming value requires five print positions, width is minus eight, and fill is f then the xxxsize functions produce the string V A L U E f f f 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.puti8( filehandle, bytevar ); Page 88 Version: 4/8/ Written by Randall Hyde

49 HLA Standard Library Reference // If the character is in a register (AL): fileio.puti8( filehandle, al ); // If "bytevar " is not one of the last three // bytes on a page of memory, you can do this: push( (type dword bytevar ) ); call fileio.puti8; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( bytevar, eax ); // Assume EAX is available call fileio.puti8; // If no register is available, do something // like the following code: sub( 4, esp ); movzx( bytevar, eax ); mov( eax, [esp+4] ); pop( eax ); call fileio.puti8; // If the character value is in al, bl, cl, or dl // then you can use code like the following: // Assume bytevar is in AL call fileio.puti8; // If the byte value is in ah, bh, ch, or dh // you ll have to use code like the following: xchg( al, ah ); // Assume bytevar is in AH // It s now in AL xchg( al, ah ); // Restore al/ah call fileio.puti8; Released to the Public Domain Page 89

50 HLA Standard Library fileio.puti8 stack diagram +8 b :byte fileio.puti8size ( Handle:dword; b:byte; width:int; 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.puti8size( filehandle, bytevar, width, padchar ); // If "bytevar" and "padchar" are not one of the last three // bytes on a page of memory, you can do this: push( (type dword bytevar) ); push( (type dword padchar) ); call fileio.puti8size; // If you can t guarantee that the previous code // won t generate an illegal memory access, and a // -bit register is available, use code like // the following: movzx( bytevar, eax ); // Assume EAX is available movzx( padchar, ebx ); // Assume EBX is available push( ebx ); call fileio.puti8size; // If no registers are available, do something // like the following code: sub(, esp ); Page 9 Version: 4/8/ Written by Randall Hyde