Click above to get retro games delivered to your door ever month!

 fbread()            Read data from a binary file
------------------------------------------------------------------------------
 Declaration
   fileio.hdr

 Syntax
   func uint fbread extern
   param value _HFILE  hFile, ;
               untyped xBuffer, ;
         value uint    uBytes

 Arguments
   hFile is the handle of the file to manipulate.
   xBuffer is the buffer that receives data from the file.
   uBytes is the number of bytes to read.

 Return
   The number of bytes read.

 Description
   The fbread() function attempts to read uBytes bytes from the file
   specified by hFile into the buffer xBuffer. It returns the number of
   bytes actually transferred. If fbread() returns a value different from
   the value specified in uBytes, then the file is either at eof,
   truncated to 0 bytes or there is a physical defect with the file. It is
   most likely that the file is at eof.

   The maximum value for uBytes is 65535 or 0xffff. The buffer
   xBuffer may represent any data type - char, dbl, logical, etc. For
   example you may use fbread() to read into a byte array or a char variable.

   As data is read from the file, DOS adjusts the read/write pointer by
   uBytes. So, if fbread() reads 20 bytes, the read write pointer
   of the file is adjusted by 20 bytes. Use fbseek() to move the read write
   pointer.

   The file must have been opened prior to the read unless the function call
   uses one of the predefined DOS file handles. DOS has five file handles
   that are predefined that is handles 0 through 4. These handles do not need
   to be opened. By using DOS predefined handles, you can write DOS filters.

   The header fileio.hdr contains definitions for the DOS file handles.
   Refer to the DOS handle table for more details.

 Example
   #define EXAMPLE_FILE
   #include example.hdr

   /*
   By using DOS predefined handles, you can write a filter. This filter,
   arbitrarily called tab.exe, expands a TAB character into spaces. This is
   useful for printers that don't understand how to expand tabs. To use,
   type the following at the DOS prompt:
   
   C> type anytext.fil | tab > no9char.txt
   */
   
   proc TabFilter
   vardef
       int     nTabs
       byte    bChar
       char(8) cSpaces
   enddef
   nTabs := 8
   cSpaces := space( 8 )
   do while fbread( STD_IN, bChar, 1 ) > 0
      if bChar == 9                     // equal a tab?
         fbwrite( STD_OUT, cSpaces, nTabs )
         nTabs := 8
         loop
      endif
      if bChar == 0xd .or. bChar == 0xa // carriage return or line feed.
         nTabs := 8
      endif
      fbwrite( STD_OUT, bChar, 1 )
   enddo
   endproc
   
   proc PlayFile
   param const char cFile
   // Play a file. Read a byte into a variable, convert it to a note and
   // then use the sound() procedure to play the note.
   vardef
      _HFILE hFile
      uint   uNote
   enddef
   if fbopen( hFile, cFile, FB_READ )
      do while fbread( hFile, uNote, 1 ) > 0
         uNote := ( ( uNote % 12 ) * 72 ) + 440
         sound( uNote, 4 )
      enddo
   endif
   endproc
   
   proc Test_fbread
   if argc()
      PlayFile( argv( 1 ) )
   else
      TabFilter()
   endif
   endproc
   

   proc main
   Test_fbread()
   endproc