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

##############################################################################
###+-----------+##############################################################
#+-| FB_READ() |--------------------------------------------------------+#####
#| +-----------+ Read number_of_bytes from the file specified by handle |#####
#+----------------------------------------------------------------------+#####
##############################################################################
##############################################################################
#+--| Summary |----------------+##############################################
#|     #INCLUDE fileio.hdr     |##############################################
#+-----------------------------+##############################################
##############################################################################
##############################################################################
#+--| Syntax |---------------------------------------------------+############
#|     FUNCTION UINT fb_read PROTOTYPE                           |############
#|      PARAMETERS VALUE INT handle, UNTYPED trans_buffer,;      |############
#|      VALUE INT number_of_bytes                                |############
#+---------------------------------------------------------------+############
##############################################################################
##############################################################################
##########+---| Description |---------------------------------------+#########
##########| The fb_read() function attempts to read number_of_bytes |#########
##########| bytes from the file specified by handle into the buffer |#########
##########| trans_buffer.  It returns the number of bytes actually  |#########
##########| transferred.  If fb_read() returns a value different    |#########
##########| from the value specified in number_of_bytes, 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 number_of_bytes is 65535 or       |#########
##########| 0xffff.  The buffer trans_buffer may represent any data |#########
##########| type - CHAR, DBL, LOGICAL, etc..  For example you may   |#########
##########| use fb_read() to read into a BYTE array or a CHAR       |#########
##########| variable.                                               |#########
##########| ------------------------------------------------------- |#########
##########| As data is read from handle, DOS adjusts the read write |#########
##########| pointer by number_of_bytes.  So, if fb_read() reads 20  |#########
##########| bytes, the read write pointer of the file is adjusted   |#########
##########| by 20 bytes.  Use fb_seek() 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 file fileio.hdr contains defines for the DOS |#########
##########| file handles.                                           |#########
##########| refer to the table DOS HANDLES TABLE for more details.  |#########
##########+---------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Read 20 bytes into a CHAR variable.                 |#########
#########|                                                          |#########
#########| VARDEF                                                   |#########
#########|     CHAR(20)    read_into                                |#########
#########|     UINT        bytes_transferred, h                     |#########
#########| ENDDEF                                                   |#########
#########|                                                          |#########
#########| bytes_transferred = fb_read( h, read_into, 20 )          |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    Read 3 bytes into a CHAR variable and two           |#########
#########| *    bytes into a LOGICAL variable.                      |#########
#########|                                                          |#########
#########| VARDEF                                                   |#########
#########|     CHAR(3)     cvar                                     |#########
#########|     LOGICAL     ivar                                     |#########
#########| ENDDEF                                                   |#########
#########|                                                          |#########
#########| IF fb_read( h, cvar, 3 )+fb_read(h, lvar, 2 ) <> 5       |#########
#########|     ? "At eof()"                                         |#########
#########| ENDIF                                                    |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 3 |-------------------------------------------+#########
#########| *    By using DOS predefined handles, you can write      |#########
#########| *    a filter.  This filter, 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        |#########
#########|                                                          |#########
#########| #include fileio.hdr                                      |#########
#########| VARDEF                                                   |#########
#########|     INT     tab_count = 8                                |#########
#########|     BYTE    c                                            |#########
#########|     CHAR(8) spaces = "        "                          |#########
#########| ENDDEF                                                   |#########
#########|                                                          |#########
#########| PROCEDURE force_main                                     |#########
#########|     DO WHILE fb_read( &STD_IN, c, 1 ) > 0                |#########
#########|         IF c = 9            && equal a tab?              |#########
#########|             fb_write( &STD_OUT, spaces, tab_count )      |#########
#########|             tab_count = 8                                |#########
#########|             LOOP                                         |#########
#########|         ENDIF                                            |#########
#########|                                                          |#########
#########|         IF c = 0xd .OR. c = 0xa  && carriage return      |#########
#########|                                  && or line feed.        |#########
#########|             tab_count = 8                                |#########
#########|         ENDIF                                            |#########
#########|         fb_write( &STD_OUT, c, 1 )                       |#########
#########|     ENDDO                                                |#########
#########| ENDPRO                                                   |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 4 |-------------------------------------------+#########
#########| *    Play a file! Read a byte into a variable, convert   |#########
#########| *    it to a NOTE and then use the SOUND procedure       |#########
#########| *    to play the note.                                   |#########
#########|                                                          |#########
#########| DO WHILE fb_read( f, anote, 1 ) > 0                      |#########
#########|     anote = (( anote % 12 ) * 72 ) + 440                 |#########
#########|     SOUNT( anote, 4 )                                    |#########
#########| ENDDO                                                    |#########
#########+----------------------------------------------------------+#########
##############################################################################