Opens the specified file for reading or writing and assigns it a unique integer file number. You use this integer to identify the file when you read, write, or close the file. The optional arguments filemode, fileaccess, filelock, and writemode determine the mode in which the file is opened.
FileOpen ( filename {, filemode {, fileaccess {, filelock {, writemode }}}} )
Argument |
Description |
|---|---|
filename |
A string whose value is the name of the file you want to open. If filename is not on the current directory’s relative search path, you must enter the fully qualified name. |
filemode (optional) |
A value of the FileMode enumerated type that specifies how the end of a file read or file write is determined. Values are:
For more information, see Usage below. |
fileaccess (optional) |
A value of the FileAccess enumerated type that specifies whether the file is opened for reading or writing. Values are:
If PocketBuilder does not find the file, a new file is created if the fileaccess argument is set to Write! |
filelock (optional) |
A value of the FileLock enumerated type specifying whether others have access to the opened file. Values are:
|
writemode (optional) |
A value of the WriteMode enumerated datatype. When fileaccess is Write!, specifies whether existing data in the file is overwritten. Values are:
Writemode is ignored if the fileaccess argument is Read! |
Integer. Returns the file number assigned to filename if it succeeds and -1 if an error occurs. If any argument’s value is null, FileOpen returns null.
The FileOpen function can open Unicode and ANSI files. If the file does not exist, FileOpen creates a Unicode file.
Creating valid Unicode files
A Unicode file that you create with FileOpen does
not contain the Unicode byte order mark (BOM) at the beginning of
the file when you set the filemode argument
to StreamMode!. To include the BOM in a file that you open in stream
mode, you can do one of the following:
Create the file by calling FileOpen in line mode, add an innocuous character, such as a single space, then close the file and reopen it in stream mode using the Append! value for the writemode argument.
Call FileWrite and pass the 2 byte binary blob “Char(65279)” before the rest of the string that you want to write to the file in stream mode.
The mode in which you open a file determines the behavior of the functions used to read and write to a file. There are two functions that read data from a file: FileRead and FileReadEx, and two functions that write data to a file: FileWrite and FileWriteEx. FileRead and FileWrite have limitations on the amount of data that can be read or written and are maintained for backward compatibility.
When a file has been opened in line mode, each call to the FileRead or FileReadEx function reads until it encounters a carriage return (CR), linefeed (LF), or end-of-file mark (EOF). Each call to FileWrite or FileWriteEx adds a CR and LF at the end of each string it writes. Line mode is not supported when reading from or writing to blobs.
When a file has been opened in stream mode, a call to FileRead reads the whole file (until it encounters an EOF) or 32,765 bytes, whichever is less. FileWrite writes a maximum of 32,765 bytes in a single call and does not add CR and LF characters. A byte size of 32,765 does not cause termination of the FileReadEx or FileWriteEx calls.
File not found
If PocketBuilder does not find the file, it creates a new
file, giving it the specified name, if the fileaccess argument
is set to Write!.
This example uses the default arguments and opens the file EMPLOYEE.DAT for reading. The default settings are LineMode!, Read!, and LockReadWrite!. FileReadEx reads the file line by line and no other user is able to access the file until it is closed:
integer li_FileNum
li_FileNum = FileOpen("EMPLOYEE.DAT")
This example opens the file EMPLOYEE.DAT in the DEPT directory in stream mode (StreamMode!) for write only access (Write!). Existing data is overwritten (Replace!). No other users can write to the file (LockWrite!):
integer li_FileNum
li_FileNum = FileOpen("C:\DEPT\EMPLOYEE.DAT", &
StreamMode!, Write!, LockWrite!, Replace!)
