[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
##############################################################################
###+-----------+##############################################################
#+-| 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 |#########
#########+----------------------------------------------------------+#########
##############################################################################
See Also:
fb_close
fb_eof()
fb_open()
fb_seek()
fb_write()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson