             Stream Line Read Function Version 1.0 for Clipper 5
             ---------------------------------------------------

                     Written By Chris Murray, April 1994

The Library has two Functions, StrmBufReset and StrmLineRead.  The routines
have been written to increase the speed of low level file reading.

I wrote the routines to create database's from large print files downloaded
from the mainframe where I work.  These files were typically upwards of 20
meg, and in one example on a IBM model 56 OBA it reduced the processing time
to ten minutes from a five hours (that's about 650 lines a second).

I would welcome any comments via compuserve.  I have written some routines to
buffer Fwrite, but it only speeds things up writing to slow drives (ie Floppy
drives, LAN drives or LAN printer devices ).  I guess Clipper buffers all
writes pretty well already.

Feel free to copy and distribute all the files, I would be interested in any
comments and I can be reached on compuserve mail (100043,2247).

I would be appreciate $25, for my time and effort from people that are going
to continue using the routines, (especially companies).

I will admit that the $25 is purely to feed my compuserve addiction, currently
runnning at $100 a month. Thats a lot of money compared to my salary !

For that fee I will do all the normal stuff, like sending updates when needed
and online support via compuserve.

Even if you are an unregistered user, feel free to contact me via Compuserve
if you have any questions.

Note : if the file you are dealing with ends without CRLF the function will
       return FALSE but the buffer will be filled with the remaining characters.
       I haven't come across this yet in a text file. The obvious way round it
       would be to use a repeat/until loop and process the buffer if the
       function returns FALSE, but the buffer is not empty, and of course when
       the function returns TRUE.

My mail address is :

	Chris Murray
	12 Cotham Hill
	Cotham
	Bristol
	BS6 6LF
	Avon
	England

Or I can be reached on Compuserve 100043,2247.

StrmBufReset()
Inialise buffer or clear buffer.

Syntax
------

        StrmBufReset( nHandle , nBufferSize ) --> NIL

Arguments
---------

        <nHandle> is the file handle returned by Fopen.

        <nBufferSize> is the requested buffersize.

Description
-----------

        StrmBufReset must be called to initialize the buffer and when called
        with no parameters clears the buffer.  nBufferSize is stored as a
        Clipper Static with a maxium of 32k, so be careful if you're using any
        3rd party Librarys (these typically use a lot of statics) as Statics
        are stored in the Dgroup which has a limit of 64k (please Email me if
        my understanding is incorrect).

        The buffersize HAS TO BE larger than the longest line, or StrmLineRead
        will think it got to the end of the file.

        It is important to reset the buffer once you have finished using the
        routines to free up the Static memory area to other routines.

Files: Library is StrmRead.Lib

StrmlineRead()
Get next line from file

Syntax
------

        StrmlineRead( @cBuf ) --> lSucces

Arguments
---------

        <cBuf> is passed by reference and filled with the next line.

Returns
-------

        StrmLineRead() returns True or False depending whether it can find
        another line, therefore it will return False when it gets to the end
        of the file. I would recommend using a repeat/until loop over a
        do/while loop, just in case a file might be terminated EOF instead of
        CR+LF+EOF, in this case StrmlineRead will return False but still fill
        cBuf with the remainder of the line. Of course this means your program
        processed a null string when you get to the end of the file. I haven't
        come across a text file like this yet !

Description
-----------

        StrmLineRead() will fill cBuf with the next line in the buffer if it
        is passed by reference. The function is written to work as fast as
        possible, if you try to compare it to Fread( nHandle , @cBuf , 1 ) you
        will be amazed.

Example
-------

        nHandle := Fopen( "testfile.txt" , FO_READ )

        If nHandle == F_ERROR
           ? "File open error :", FERROR()
        Else
           // accept default buffer of 32k
           StrmBufReset( nHandle )

           nCounter := 0

           Do While StrmLineRead( @cBuf )
              @ 10 , 10 Say Str( ++nCounter , 6 , 0 )
           Enddo

           // close stream
           StrmBufReset()

        Endif
        FClose( nHandle )

Files: Library is StrmRead.Lib
