FileOpen PowerScript function
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
|
1 |
<span>FileOpen</span> ( <span>filename </span>{, <span>filemode </span>{, <span>fileaccess</span> {, <span>filelock </span>{, <span>writemode</span><br> { <span>encoding</span><span></span> }}}}} ) |
|
Argument |
Description |
|---|---|
|
filename |
A string whose value is the name of the |
|
filemode (optional) |
A value of the FileMode enumerated type
For more information, see Usage below. |
|
fileaccess |
A value of the FileAccess enumerated
If PowerBuilder does not find the file, a new file is created |
|
filelock (optional) |
A value of the FileLock enumerated type
|
|
writemode (optional) |
A value of the WriteMode enumerated datatype.
Writemode is ignored if the fileaccess argument |
|
encoding |
Character encoding of the file you want
|
Return Values
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:
|
1 |
integer li_FileNum |
|
1 |
li_FileNum = <span>FileOpen</span>("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!):
|
1 |
integer li_FileNum |
|
1 |
li_FileNum = <span>FileOpen</span>("C:DEPTEMPLOYEE.DAT", & |
|
1 |
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: emp directory.
It is opened in text mode with write–only access, and no
other user can read or write to the file:
|
1 |
integer li_ret |
|
1 |
string ls_file |
|
1 2 |
ls_file = "D: emp ew.txt"<br>li_ret = FileOpen(ls_file, TextMode!, Write!, &<br>   LockReadWrite!, Replace!, EncodingUTF8!) |