Description
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.
Syntax
FileOpen ( filename {, filemode {, fileaccess {, filelock {, writemode { encoding }}}}} )
|
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 PowerBuilder 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! |
|
encoding |
Character encoding of the file you want to create. Specify this argument when you create a new text file using text or line mode. If you do not specify an encoding, the file is created with ANSI encoding. Values are:
|
Return value
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.
Usage
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. They do not support text mode. For more information, see FileRead and FileWrite.
The support for reading from and writing to blobs and strings for the FileReadEx and FileWriteEx functions depends on the mode. The following table shows which datatypes are supported in each mode.
|
Mode |
Blob |
String |
|---|---|---|
|
Line |
Not supported |
Supported |
|
Stream |
Supported |
Not supported |
|
Text |
Supported |
Supported |
When a file has been opened in line mode, each call to the FileReadEx function reads until it encounters a carriage return (CR), linefeed (LF), or end-of-file mark (EOF). Each call to FileWriteEx adds a CR and LF at the end of each string it writes.
When a file has been opened in stream mode or text mode, FileReadEx reads the whole file until it encounters an EOF or until it reaches a length specified in an optional parameter. FileWriteEx writes the full contents of the string or blob or until it reaches a length specified in an optional parameter.
The optional length parameter applies only to blob data. If the length parameter is provided when the datatype of the second parameter is string, the code will not compile.
In all modes, PowerBuilder can read ANSI, UTF-16, and UTF-8 files.
The behavior in stream and text modes is very similar. However, stream mode is intended for use with binary files, and text mode is intended for use with text files. When you open an existing file in stream mode, the file's internal pointer, which indicates the next position from which data will be read, is set to the first byte in the file.
A byte-order mark (BOM) is a character code at the beginning of a data stream that indicates the encoding used in a Unicode file. For UTF-8, the BOM uses three bytes and is EF BB BF. For UTF-16, the BOM uses two bytes and is FF FE for little endian and FE FF for big endian.
When you open an existing file in text mode, the file's internal pointer is set based on the encoding of the file:
-
If the encoding is ANSI, the pointer is set to the first byte
-
If the encoding is UTF-16LE or UTF-16BE, the pointer is set to the third byte, immediately after the BOM
-
If the encoding is UTF-8, the pointer is set to the fourth byte, immediately after the BOM
If you specify the optional encoding argument and the existing file does not have the same encoding, FileOpen returns -1.
File not found
If PowerBuilder does not find the file, it creates a new file, giving it the specified name, if the fileaccess argument is set to Write!. If the argument is not set to Write!, FileOpen returns -1.
If the optional encoding argument is not specified and the file does not exist, the file is created with ANSI encoding.
When you create a new text file using FileOpen, use line mode or text mode. If you specify the encoding parameter, the BOM is written to the file based on the specified encoding.
When you create a new binary file using stream mode, the encoding parameter, if provided, is ignored.
Examples
This example uses the default arguments and opens the file EMPLOYEE.DAT for reading. The default settings are LineMode!, Read!, LockReadWrite!, and EncodingANSI!. 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!)This example creates a new file that uses UTF8 encoding. The file is called new.txt and is in the D:\temp directory. It is opened in text mode with write-only access, and no other user can read or write to the file:
integer li_ret string ls_file ls_file = "D:\temp\new.txt" li_ret = FileOpen(ls_file, TextMode!, Write!, & LockReadWrite!, Replace!, EncodingUTF8!)
See also
