Reading and writing text or binary files

You use PowerScript text file functions to read and write text in line mode or text mode, or to read and write binary files in stream mode:

In line mode, you can read a file a line at a time until either a carriage return or line feed (CR/LF) or the end-of-file (EOF) is encountered. When writing to the file after the specified string is written, PowerScript appends a CR/LF.
In stream mode, you can read the entire contents of the file, including any CR/LFs. When writing to the file, you must write out the specified blob (but not append a CR/LF).
In text mode, you can read the entire contents of the file, including any CR/LFs. When writing to the file, you must write out the specified string (but not append a CR/LF).

Reading a file into a MultiLineEdit You can use stream mode to read an entire file into a MultiLineEdit, and then write it out after it has been modified.

Understanding the position pointer

When PowerBuilder opens a file, it assigns the file a unique integer and sets the position pointer for the file to the position you specify—the beginning, after the byte-order mark, if any, or end of the file. You use the integer to identify the file when you want to read the file, write to it, or close it. The position pointer defines where the next read or write will begin. PowerBuilder advances the pointer automatically after each read or write.

You can also set the position pointer with the FileSeek or FileSeek64 function.

File functions

These are the built-in PowerScript functions that manipulate files:

**Table 3-1: PowerScript functions that manipulate files**
Function	Datatype returned	Action
FileClose	Integer	Closes the specified file
FileDelete	Boolean	Deletes the specified file
FileEncoding	Encoding enumerated type	Returns the encoding used in the file
FileExists	Boolean	Determines whether the specified file exists
FileLength	Long	Obtains the length of a file with a file size of 2GB or less
FileLength64	LongLong	Obtains the length of a file of any size
FileOpen	Integer	Opens the specified file
FileRead	Integer	Reads from the specified file (deprecated)
FileReadEx	Long	Reads from the specified file
FileSeek	Long	Seeks to a position in a file with a file size of 2GB or less
FileSeek64	LongLong	Seeks to a position in a file of any size
FileWrite	Integer	Writes to the specified file (deprecated)
FileWriteEx	Long	Writes to the specified file

Encoding

The last argument in the FileOpen function lets you create an ANSI, UTF-8, UTF-16LE (Little Endian), or UTF16-BE (Big Endian) file.

The encoding argument, like all arguments of the FileOpen function except the file name, is optional. You need only specify it if you want to create a new text file with Unicode encoding. If the filename argument refers to a file that does not exist, the FileOpen function creates the file and sets the character encoding specified in the encoding argument.

By default, if the file does not exist and the encoding argument is not specified, PowerBuilder opens a file with ANSI encoding. This ensures compatibility with earlier versions of PowerBuilder.

The FileRead and FileWrite functions cannot read more than 32,766 bytes at a time. The FileReadEx and FileWriteEx functions can write an unlimited number of bytes at a time.