Export (0) Print
Expand All

TextIo.new Method

Creates a new instance of the TextIO class.


public void new(
    str filename, 
    str mode, 

Called

Parameter

Description

filename

The name of the file to open.

mode

The mode in which the file should be opened. Specify one the following:

  • R - Read

  • W - Write

  • A - Append (implies "W")

  • T - Translate (text)

  • B - Binary

codepage

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:

  • 0 - CP_ACP; the ANSI code page

  • 437 - OEM code page 437

  • 850 - Code page 850

  • 1200 - UTF-16LE

  • 1201 - UTF-16BE

  • 65001 - UTF-8

  • 54936: GB-18030

For more information about these options, see the list of code page identifiers.

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.

Parameter value

Code page

Description

0

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.

NoteNote
The ACP on the server may be different from the ACP on the client's system.

437

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.

850

Code page 850

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

1200

UTF-16LE

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.

1201

UTF-16BE

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.

65001

UTF-8

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.

54936

GB-18030

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 called 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));
    }
}

Community Additions

ADD
Show:
© 2014 Microsoft