Reads bytes from the specified file.
[ lBytesRead = ] FileRead ( hFile, pDst, lBytes [, sEOS] [, enMode ] )
The FileRead procedure syntax has the following parts:
|
Name |
Type |
Description |
|
lBytesRead |
Long |
Number of bytes read |
|
hFile |
Val AFile |
Handle to an open file |
|
pDst |
Var Any |
Receive data buffer |
|
lBytes |
Val Long |
Number of bytes to read. If the default value is used (-1) the byte length of the pDst is used as the maximum of bytes to read. To read the whole file to a string pass in a large number. |
|
sEOS |
Val BString |
Terminator string |
|
enMode |
Val enumAIoMode |
Input mode. Only the default value is 0 (aioDefault) which can be combined with aioDisableBstrConvert. |
enumAIoMode can have one of the following values:
|
Name |
Value |
Description |
|
aioImmediate |
0 * |
Receive on data available |
|
aioWaitGpibSrqVxiDor |
1 |
Receive on Srq (gpib) or on Dor (vxi) |
|
aioGpibImmediateOrSrq |
2 |
Receive on Immediate or Srq (gpib) |
|
aioDisableBstrConvert |
4 |
Disable conversion of BString to String, can be combined with one of the previous values. |
The hFile specifies the ATEasy file handle obtained by the FileOpen or FileCreate functions.
The lBytesRead may be one of the following:
|
0 |
EOF has been reached or sEOS found at the current file pointer. |
|
n |
n number of bytes read to pDst |
|
-1 |
An error encountered by the procedure or the sEos not found. |
The receive data buffer pDst contains the bytes read from the file. If the function fails, the return value lBytesRead contains -1. If the file pointer is already at the EOF, the return value lBytesRead contains 0. If the function encounters the EOF before reading the specified amount, the return value is less than the number of bytes specified by the lBytes parameter.
The function reads the data starting with the current position of the file's pointer. This position may be read using the FileTell procedure and may also be changed using the FileSeek function.
If the terminator string (sEos) is given, the file pointer will be set to the beginning of the lBytes of data prior to the first instance of the terminator.
An example of a normal conversion (default case) is from normal text string to BString (if destination buffer is a BString).
The following example writes and read line from a file.
! open a file
hFile=FileCreate("\\~~a.txt")
if hFile=-1
TestStatus=FAIL
endif
! write a line from a string using \r\n terminator
i=FileWrite(hFile, "abcd", ,"\r\n")
if i<>6
TestStatus=FAIL
endif
! seek to the begining
i=FileSeek(hFile, 0, 0)
! read back first line using \r\n terminator
i=FileRead(hFile, s, , "\r\n")
if i<>4 or s<>"abcd"
TestStatus=FAIL
endif
i=FileClose(hFile)
The following example reads each line until EOF is reached.
hfile=FileOpen("c:\\a.txt")
while (FileEOF(hfile)=0)
lBytes=FileRead(hfile, s,, "\r")
if lBytes=-1 ! not found sEOS, read the rest without sEOS
lBytes=FileRead(hfile, s)
endif
endwhile
FileClose(hfile)
FileClose, FileCreate, FileEOF, FileOpen, FileSeek, FileTell, FileWrite, GetDir