FileRead PowerScript function
Description
Reads data from the file associated with the specified file
number, which was assigned to the file with the FileOpen function. FileRead is
maintained for backward compatibility. Use the FileReadEx function
for new development.
Syntax
|
1 |
<span>FileRead</span> ( <span>file#</span>, <span>variable</span> ) |
|
Argument |
Description |
|---|---|
|
file# |
The integer assigned to the file when |
|
variable |
The name of the string or blob variable |
Return Values
Integer. Returns the number of bytes
read. If an end-of-file mark (EOF) is encountered before any characters
are read, FileRead returns -100. If the file
is opened in LineMode and a CR or LF is encountered before any characters
are read, FileRead returns 0. If an error occurs, FileRead returns
-1. If any argument’s value is null, FileRead returns null.
If the file length is greater than 32,765 bytes, FileRead returns
32,765.
Usage
FileRead can read files with ANSI, UTF-8,
UTF-16LE, and UTF-16BE encoding.
If the file is an ANSI or UTF-8 file and is read into a string, FileRead converts the
text to Unicode before saving it in the string variable. No conversion
is needed for UTF-16 files. For Unicode files, the BOM is not written
to the string.
If the file is read into a blob, FileRead saves
the contents of the file with no conversion. For Unicode files,
the BOM is not written to the blob in text mode, but it is written
to the blob in stream mode.
If the file was opened in line mode, FileRead reads
a line of the file (that is, until it encounters a CR, LF, or EOF).
It stores the contents of the line in the specified variable, skips
the line-end characters, and positions the file pointer at the beginning
of the next line. If the second argument is a blob, FileRead returns
-1.
If the file was opened in text mode, FileRead returns
-1. Use FileReadEx to read a file in text mode.
If the file was opened in stream mode, FileRead reads
to the end of the file or the next 32,765 bytes, whichever is shorter. FileRead begins
reading at the file pointer, which is positioned at the beginning
of the file when the file is opened for reading. If the file is
longer than 32,765 bytes, FileRead automatically positions
the pointer after each read operation so that it is ready to read
the next chunk of data.
FileRead can read a maximum of 32,765 bytes
at a time. Therefore, before calling the FileRead function,
call the FileLength64 function to check the file length.
If your system has file sharing or security restrictions, you might
need to call FileLength64 before you call FileOpen.
Use FileReadEx to read longer files.
An end-of-file mark is a null character
(ASCII value 0). Therefore, if the file being read contains null
characters, FileRead stops reading at the first
null character, interpreting it as the end of the file. For Unicode
files and files that you convert to Unicode, you must make sure
that the file length value is an even number. Otherwise FileRead cannot
parse the entire file.
Examples
This example reads the file EMP_DATA.TXT if
it is short enough to be read with one call to FileRead:
|
1 |
integer li_FileNum |
|
1 |
string ls_Emp_Input |
|
1 |
long ll_FLength |
|
1 |
|
1 |
ll_FLength = FileLength64("C:HREMP_DATA.TXT") |
|
1 |
li_FileNum = FileOpen("C:HREMP_DATA.TXT", & |
|
1 |
LineMode!) |
|
1 |
IF ll_FLength < 32767 THEN |
|
1 |
<span> FileRead</span>(li_FileNum, ls_Emp_Input) |
|
1 |
END IF |
This example reads the file EMP_PIC1.BMP and
stores the data in the blob Emp_Id_Pic.
The number of bytes read is stored in li_bytes:
|
1 |
integer li_fnum, li_bytes |
|
1 |
blob Emp_Id_Pic |
|
1 |
|
1 |
li_fnum = FileOpen("C:HREMP_PIC1.BMP", & |
|
1 |
StreamMode!) |
|
1 |
li_bytes = <span>FileRead</span>(li_fnum, Emp_Id_Pic) |