FileOpen

Opens a file for reading, writing or appending.

Syntax:

FileOpen(filename, mode [, Unicode [, timeout]])

Parameters:

(s) filename: name of the file to open.

(s) mode: "READ", "WRITE". or "APPEND"

(i) Unicode: flag If "Unicode" is @TRUE, the file will be treated as containing Unicode data, otherwise it will be treated as containing ANSI data.

(i) timeout: number of seconds to spend retrying the file open operation if it fails due to a sharing violation.

Returns:

(i) filehandle.

 

The filehandle returned by the FileOpen function may be subsequently used by the FileRead, FileWrite, and FileClose functions. If the file cannot be opened as requested, and errors are suppressed with Errormode then FileOpen returns a filehandle of 0.

You may have a maximum of 128 files open at one time.

FileOpen on an existing file in "WRITE" mode, will overwrite (zero out) the file. If you specify a non-existing file in "WRITE" or "APPEND" mode, it will create the file.

FileOpen by default expects each line to be terminated with a line feed character. The file must be some type of standard text file. The binary operations may be used for non text files.

The "Unicode" option will affect how FileRead and FileWrite process the file data.

If the file is opened in "APPEND" mode, subsequent calls to FileWrite always write the data in the format of the existing text in the file.

If you open the file in "WRITE" mode, then FileWrite will write the text lines according to the unicode parameter:

Mode

Unicode

Text in file

FileWrite output format

"APPEND"

ignored

ANSI

ANSI

"APPEND"

ignored

Unicode

Unicode

"WRITE"

@FALSE(default)

ignored

ANSI

"WRITE"

@TRUE

ignored

Unicode

 

By default, if the file is opened in "READ" mode then subsequent calls to FileRead will read the text lines as they exist in the file. But if unicode is @TRUE, then FileRead will always return the string as Unicode:

Mode

Unicode

Text in file

FileRead return format

"READ"

@FALSE(default)

ANSI

ANSI

"READ"

@FALSE(default)

Unicode

Unicode

"READ"

@TRUE

ignored

Unicode

 

The "timeout" option specifies the number of seconds to spend retrying the file open operation if it fails due to a sharing violation.  The default is 0, for no retry.  If "timeout" is 1 to 20, the operation will be retried 20 times, evenly-spaced over the specified time period. If "timeout" is greater than 20, the operation will be retried once every second for the specified time period.  If "timeout" is -1, the operation will be retried once every second with no timeout.  If the file can be opened before the specified time period has elapsed, FileOpen will return successfully, otherwise it will fail.

Windows Vista/2008 and newer: This function may require an Administrator level account if dealing with files located in a protected directories: 'Program Files' and 'Windows'.

This function supports extended-length path names.

Examples:

; To open for reading:
handle = FileOpen("stuff.txt", "READ")
; To open for writing:
handle = FileOpen("stuff.txt", "WRITE")
; To open for appending:
handle = FileOpen("stuff.txt", "APPEND")
Temp = Environment("temp")
If StrSub(temp,StrLen(temp),1)!="\" Then temp=StrCat(temp,"\")
testfile1=StrCat(temp,"test1.txt")
handle=FileOpen(testfile1, "write")
FileWrite(handle,"dummy data one")
FileClose(handle)
Message("FileOpen","File %testfile1% created")

 

See Also:

Binary Operations, IntControl 40, IntControl 39, IntControl 94, BinaryRead, BinaryWrite, FileClose, FileRead, FileWrite