TextIo.new Method

Creates a new instance of the TextIO class.


public void new(
    str filename, 
    str mode, 
   [int codepage])

Run On



  • filename
    Type: str
    The name of the file to open.
  • mode
    Type: str
    The mode in which the file should be opened. Specify one the following:
  • codepage
    Type: int
    The code page number for the character set to be read from or written to the file. The default value is 1200 (UTF-16LE). This parameter is optional.
    Following are the most common values:
    For more information about these options, see the list of https://go.microsoft.com/fwlink/?LinkID=78282\&clcid=0x409.
    An error is reported if an invalid code page is requested. Notice that a code page is reported as "invalid" if it is not installed on the computer (different code pages may be installed on the client and server). For example, specifying code page 1253 for Greek fails unless the computer's ACP is Greek or Greek language support has been loaded by using Control Panel > Regional Options.


A run-time error occurs if the file is accessed with a method that does not correspond to the current opened mode (for example, you try to write to a read-mode file).

If an attacker can control input to the new method, a security risk exists. This method runs under Code Access Security. Calls to this method on the server require permission from the FileIoPermission class. Ensure that the user has development privileges by setting the security key to SysDevelopment on the control that calls this method.

The following table describes some of the more common code pages that might be specified for the _codePage parameter.


ANSI code page (ACP)

The code page that supports only characters in the user's current language. The code page is unsuitable for anything that might contain multilingual data or for monolingual data that might be transferred between two systems by using different code pages.


OEM code page 437

The IBM PC or MS-DOS code page 437. It is often abbreviated as CP437 and also called DOS-US or OEM-US.


Code page 850

A code page that was used in Western Europe running on operating systems, such as MS-DOS.



The native Unicode representation on Microsoft Windows x86 systems. Almost all characters are stored as 16 bit. Some Chinese characters require 32 bit. An identifying byte-order mark is written, examined, and then discarded when the rest of the character is read.



The same as UTF-16LE but byte-swapped. Used for compatibility with some non-x86 systems, which store bytes from left-to-right instead of low-order to high-order. An identifying byte-order mark is written first, examined, and then discarded when the rest of the character is read.



Stores Unicode in a byte-stream–friendly way:

  • ASCII characters are 1 byte

  • European alphabets (including basic diacritics) are 2 bytes per character

  • Chinese, Japanese, and Korean require 3 bytes per character

This code page is a good choice when a file contains a very high percentage of ASCII, relatively few other characters, and it is important to save space. For example, .xpo files are stored in UTF-8. UTF-8 files begin with a 3-byte byte-order mark sequence, which is the first item written. It is examined, and then discarded when the rest of the character is read.



Stores data in the GB-18030 character representation that is required by the Chinese government. No byte-order mark is written. These files cannot be distinguished from those written in code page 20936 (GB-2312, which is the ACP for Simplified Chinese systems) unless the file contains characters outside the repertoire of GB-2312.


The following example creates a TextIO object to access a file that is named filename in read mode by using code page 850 encoding.

protected void openFile(str _fileOpen = #io_read) 
    importFile = new TextIo(filename, _fileOpen, 850); 
    if (! importFile) 
        throw error(strfmt("@SYS18678", filename)); 

See Also


TextIo Class