FILEIO Subroutine

Read a line from a file into a string variable.

call ReadLineNumber(FILE_ID_IV, LINE_NUMBER_IV, TARGET_SV)

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_SV

A string variable to receive the data from the specified input line of the file. The target string will not contain any newline characters (\n) or carriage returns (\r).

Description

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

ReadLineNumber( ) 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 _IV of 3, the third line in the file will be read.

All Input subroutines use an internal buffer to read from files. ReadLineNumber( ) 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, ReadLineNumber( ) 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_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 close 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. Check the line number specification.

Example

integer FileID

integer FileIDout

string FileName is "input.txt"

string FileNameOut is "output.txt"

string Read is "read-only"

string WriteTo is "Write"

string Target

integer LineNum

string NewLine is "\n"

record LineOut is

    LineNum 5

    Target 20

    NewLine 1

end record

include "fileio.inc"

 

# User types in line number desired, and the first 20

# characters of that line and the one after it are read

# in and written out.

# To be brief, error handling is omitted.

 

response to line from keyboard

    call OpenFile ( FileID, FileName, Read )

    call OpenFile ( FileIDout, FileNameOut, WriteTo )

    copy input to LineNum

    call ReadLineNumber ( FileID, LineNum, Target )

    call WriteRecord ( FileIDout, LineOut )

    call ReadNext ( FileID, Target )

    copy (1 + LineNum) to LineNum

    call WriteRecord ( FileIDout, LineOut )

    call CloseFile ( FileID )

    call CloseFile ( FileIDout )

See Also

ReadNext( ) subroutine.