FILEIO Subroutine

Read a line from a file into a record.

call ReadRecordAtLine(FILE_ID_IV, LINE_NUMBER_IV, TARGET_REC)

FILE_ID_IV

A file identifier previously declared with the integer statement. This must be the same as the file identifier used when the file was opened.

LINE_NUMBER_IV

An integer variable that contains the positive, non-zero number of the line to be read.

TARGET_REC

The name of a record previously defined by a record definition statement. The variables specified in the record definition receive the data from the appropriate input line of the file.

Description

This subroutine allows you to read a line of an ASCII or EBCDIC file into a previously defined record.

ReadRecordAtLine( ) finds the requested line, if it is in the file, according to its position from the beginning of the file. For example, if you specify a line number of 3, the third line in the file will be read.

All input subroutines use an internal buffer to read from files. ReadRecordAtLine( ) first scans the file to find the beginning of the specified line by repeatedly filling and scanning the file's buffer until the specified line is found. A buffer size of 1K is best, and we recommend increments of 1K when increasing or decreasing the buffer's size.

The input subroutines also count lines as they scan the file, and keep track of where each scanned line is located. This information, called a file's index, is stored in a buffer in memory. With a large file, the index could grow unreasonably large. Therefore, each file has a limit for its index size. When the limit is reached, ReadRecordAtLine( ) reduces the index size by storing only half as many line locations while scanning the file. The index then stores the beginning position of every other line. This process of reducing the index size is repeated as necessary to keep each file's index under its specified limit, which starts at 1024 bytes (1K) total space, or 256 line beginning positions, since each index takes up four bytes. You can alter the limit by calling SetIndexSize( ) for a specified file.

Errors

FIO_E_BADFIELD

Bad field in a record.

FIO_E_BADLINENO

Specified line number not in file.

FIO_E_BUFFTOOSMALL

Internal buffer too small. Although an attempt was made to increase the buffer's size to fit in a complete line, system memory ran out before the current line could be accommodated. Make sure lines are terminated by a carriage return (\r) or newline (\n), otherwise the entire file will be interpreted as one line.

FIO_E_EOF

Attempt to read at end-of-file. All lines have been read.

FIO_E_FILEHANDLE

Invalid file handle - internal error.

FIO_E_FILELOCKED

File locked by another program.

FIO_E_LINETOOBIG

Current line exceeded buffer size. Although an attempt was made to increase the buffer's size to fit in a complete line, system memory ran out before the current line could be accommodated. Make sure lines are terminated by a carriage return (\r) or newline (\n), otherwise the entire file will be interpreted as one line.

FIO_E_NOTOPEN

File has not been opened. This error occurs when you try to use a file that has not been opened.

FIO_E_OPENFORWRITE

Reading from file open for writing.

FIO_E_READACC

Read access violation. Should never happen during input.

FIO_E_SEEK

Error during seek - internal error. Check the line number specification.

FIO_E_SUBSCRIPTCOUNT

Wrong number of array subscripts. The array referenced in the record has more dimensions than the number of subscripts specified.

FIO_E_SUBSCRIPTRANGE

Array subscript reference out of range. One of the array subscripts in the record is greater than the highest allowable subscript for that dimension.

See Also

ReadNextRecord( ) subroutine.