FileOpen – PB Docs 2018

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

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.

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 you specify the optional encoding argument and the existing file
does not have the same encoding, FileOpen returns -1.

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:

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!):

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:

See also

FileClose

FileLength64

FileRead

FileReadEx

FileWrite

FileWriteEx