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