FGETS( ) Function

Returns a series of bytes from a file or a communication port opened with a low-level file function until it encounters a carriage return.

FGETS(nFileHandle [, nBytes])

Return Values

Character

Parameters

  • nFileHandle
    Specifies the numeric file handle of the file or communication port from which FGETS( ) returns data.

  • nBytes
    Specifies the number of bytes FGETS( ) returns. FGETS( ) returns nBytes bytes unless a carriage return is encountered first. FGETS( ) returns data between the starting file-pointer position and the carriage return if a carriage return is encountered within nBytes bytes.

    FGETS( ) returns a maximum of 8192 bytes. If you omit nBytes, FGETS( )returns 254 bytes by default.

Remarks

You can read a file line by line by issuing a series of FGETS( ).

FGETS( ) returns a series of bytes as a character string. Data is returned starting from the current file's pointer position and continuing until a carriage return is encountered. The file pointer is then positioned on the byte immediately following the carriage return. The carriage return isn't returned as part of the string, and line feeds are discarded.

Example

** TEST.TXT must exist ** STORE FOPEN('test.txt') TO gnFileHandle && Open the file STORE FSEEK(gnFileHandle, 0, 2) TO gnEnd && Move pointer to EOF STORE FSEEK(gnFileHandle, 0) TO gnTop && Move pointer to BOF IF gnEnd <= 0 && Is file empty? WAIT WINDOW 'This file is empty!' NOWAIT ELSE && If not gcString = FGETS(gnFileHandle, gnEnd) && Store contents ? gcString ENDIF = FCLOSE(gnFileHandle) && Close the file

See Also

FCHSIZE( ) | FCLOSE( ) | FCREATE( ) | FEOF( ) | FFLUSH( ) | FILETOSTR( ) | FOPEN( ) | FPUTS( ) | FREAD( ) | FSEEK( ) | FWRITE( )