GetFile

Specify the name, and optionally, the path, of the file you want to open.

A string indicating how you want to access the file. The mode can be one of the following:

• "R" (Read mode): opens the file for reading, starting at the beginning.

• "W" (Write mode): opens the file for writing.

  Warning! When you specify Write mode, any existing content in the file is discarded.

• "A" (Append mode): opens the file for writing, starting at the end. Any existing content is retained.

• "U" (Update mode): opens the file for reading or writing, starting at the beginning of the file. Any existing content is retained. Use this mode and the GetPosition and SetPosition methods to maintain checkpoints of the current read/write position in the file.

  In Update mode, any write operation clears the file of all data that follows the position you set.

  Note: Currently, the effect of the Update mode and the GetPosition and SetPosition methods is not well defined for Unicode files. Use the Update mode only on files stored with a non-Unicode character set.

• "E" (Conditional "exist" read mode): opens the file for reading only if it exists, starting at the beginning. If it doesn’t exist, the Open method has no effect. Before attempting to read from the file, use the IsOpen property to confirm that it’s open.

• "N" (Conditional "new" write mode): opens the file for writing, only if it doesn’t already exist. If a file by the same name already exists, the Open method has no effect. Before attempting to write to the file, use the IsOpen property to confirm that it’s open. You can insert an asterisk (*) in the file name to ensure that a new file is created. The system replaces the asterisk with numbers starting at 1 and incrementing by 1, and checks for the existence of a file by each resulting name in turn. It uses the first name for which a file doesn’t exist. In this way you can generate a set of automatically numbered files. If you insert more than one asterisk, all but the first one are discarded.

A string indicating the character set you expect when you read the file, or the character set you want to use when you write to the file. You can abbreviate Unicode UCS-2 to "U" and the host operating system's default non-Unicode (sometimes referred to as the ANSI character set) to “A”. All other character sets must be spelled out in full, for example, ASCII, Big5, Shift-JIS, UTF8, or UTF8BOM.

If “A” is specified as the character set, or you do not specify a character set, the character set used is dependent on the application server configuration. On a Windows application server, the default non-Unicode character set is dependent on the Windows ANSI Codepage (ACP) which can be checked using the DOS command chcp. On a Unix application server, the default non-Unicode character set is specified in the application server configuration file, psappsrv.cfg, and can be modified using PSADMIN. You can also use a record field value to specify the character set (for example, RECORD.CHARSET.)

A list of supported character set names valid for this argument can be found in PeopleTools: Global Technology .

See .

When a file is opened for reading using the “U” charset argument, GetFile expects the file to begin with a Unicode byte order mark (BOM). This mark indicates whether the file is written in big endian order or little endian order. A BOM consisting of the hex value 0xFEFF indicates a big endian file, a BOM consisting of the hex value 0xFFEF indicates a little endian file. If the Unicode UCS-2 file being opened does not start with a BOM, an error is returned. The BOM is automatically stripped from the file when it is read into the buffers by GetFile.

When a file is opened for writing using the “U” charset argument, the appropriate Unicode BOM is automatically written to the start of the file depending on whether the application server hardware platform operates in little endian or big endian mode.

BOMs are only expected or supported for files in Unicode character sets such as UTF8, UTF8BOM, and UCS2. For consuming applications that do expect the BOM for UTF-8 files, use the UTF8BOM character set to create UTF-8 files with the BOM.

When working with XML documents, specify UTF8 or UTF8BOM for charset . If you are writing an XML file using a different character set, you must remember to include a character set declaration in the XML file.

In some cases, a Unicode file (UCS-2 or UTF-8) cannot be opened. An error message is displayed, when one of the following error conditions is encountered:

• If the character set is U (that is, UCS2) and the mode is:

  • A: The file is empty or the BOM is missing or incorrect.

  • R: The BOM is missing or incorrect.

  • W: The file does not exist, or adding the BOM failed.

• If the character set is UTF8 or UTF8BOM and the mode is:

  • R: For UTF8BOM, the BOM is missing or the file is empty; for UTF8, the file is empty.

  • A or W: For UTF8BOM only, the file does not exist or adding the BOM failed.

If you have prepended a path to the file name, use this parameter to specify whether the path is an absolute or relative path. The valid values for this parameter are:

• %FilePath_Relative (default)

• %FilePath_Absolute

If you don’t specify pathtype the default is %FilePath_Relative.

If you specify a relative path, that path is appended to the path constructed from a system-chosen environment variable. A complete discussion of relative paths and environment variables is provided in documentation on the File class.

See .

If the path is an absolute path, whatever path you specify is used verbatim. You must specify a drive letter and the complete path. You can’t use any wildcards when specifying a path.

The Component Processor automatically converts platform-specific separator characters to the appropriate form for where your PeopleCode program is executing. On a Windows system, UNIX "/" separators are converted to "\", and on a UNIX system, Windows "\" separators are converted to "/".