Open statement (LotusScript® Language)

Opens a file, enabling access to it for reading or writing data.

Syntax

Open fileName

[ For { Random | Input | Output | Append | Binary } ]

[ Access { Read | Read Write | Write } ]

[{ Shared | Lock Read | Lock Read Write | Lock Write }]

As [#]fileNumber

[ Len = recLen ]

[Charset = MIMECharsetName]

This statement must appear on one line, unless you use an underscore ( _ ) for line continuation.

Elements

fileName

A string expression indicating the file to open. fileName may include a complete path. If you do not specify a drive and a directory, LotusScript® looks for the file in the default directory on the default drive. If you specify a drive but no directory, LotusScript® looks for the file in the default directory of the specified drive. On platforms without drive letters, the default directory is used. If you specify a fileName that does not exist, LotusScript® generates an error if the mode is Input; for all other modes, LotusScript® creates the file and opens it.

For mode

Optional. Specifies the file's mode; the default is Random.

  • Random

    Default mode. Designates random access mode; that is, the file is accessible by record number. Use the Get and Put statements to read and write the file. If you omit the Access clause, LotusScript® makes three attempts to open the file, using Read Write access, then Write access, and finally Read access. If all three attempts fail, an error is generated.

  • Input

    Designates sequential input mode. Use the Input and Input # statements to read the file. If the mode conflicts with the Access type, LotusScript® generates an error. For example, you can't open a file in Input mode with Write access.

  • Output

    Designates sequential output mode. Use the Write # and Print # statements to write to the file. If the mode conflicts with the Access type, LotusScript® generates an error. For example, you can't open a file in Output mode with Read access.

  • Append

    Designates sequential output mode, beginning at the current end-of-file. If the mode conflicts with the Access type, LotusScript® generates an error. For example, you can't open a file in Append mode with Read access. Unless you use the Seek statement to move to a file position other than the end of the file, the Print # and Write # statements append text to the end of the file.

  • Binary

    Designates binary file mode. Use the Get and Put statements to read and write the file. If you omit the Access clause, LotusScript® makes three attempts to open the file, using Read Write access, thenWrite access, and finally Read access. If all three attempts fail, an error is generated.

Access operations

Optional. Specifies what operations can be performed on the file. An error is generated if the access type conflicts with the file mode specified in the For clause.

  • Read

    Default access type for Input mode. Only read operations are permitted.

  • Read Write

    Default access type for Random mode. Both read and write operations are permitted.

  • Write

    Default access type for Output, Append, and Binary modes. Only write operations are permitted.

Lock type

Optional. The default is Shared.Determines how the open file can be shared when accessed over a network by other processes, including processes owned by other users.

Under Windows™ 3.1, you must run SHARE.EXE to enable the locking feature if you are using MS-DOS version 3.1 or later. Lock is not supported for earlier versions of MS-DOS.

  • Shared

    Default locking type. No file locking is performed. Any process on any machine on the network can read from or write to the file.

  • Lock Read

    Prevents other processes from reading the file, although they can write to it. The lock is applied only if read access has not already been granted to another process.

  • Lock Read Write

    Prevents other processes from reading and writing to the file. The lock is applied only if read or write access has not already been granted to another process. If a lock is already in place, it must be released before opening a file with Lock Read Write.

  • Lock Write

    Prevents other processes from writing to the file, although they can read from it. The lock is applied only if write access has not already been granted to another process.

fileNumber

An integer expression with a value between 1 and 255, inclusive. This number is associated with the file when you open the file. Other file-manipulation commands use this number to refer to the file.

recLen

Optional. Designates the record length; use an integer expression with a value between 1 and 32767, inclusive.

For a Random file, recLen is the record length for the file (all records in a single file must have the same length). The default record length is 128 bytes.

For a sequential (Input, Output, or Append) file, recLen is the number of characters to be read from the file into an internal buffer, or assigned to an internal buffer before it is written to the file. This need not correspond to a record size, because the records in a sequential file can vary in size. A larger buffer uses more memory but provides faster file I/O. The default buffer size is 512 bytes.

For a Binary file, recLen is ignored.

MIMECharsetName

Note: This element is new with Domino® Release 6.

Optional. Designates the character set to use for sequential file I/O. If no character set is provided, file I/O is done in the platform code page with the following exceptions:

  • If a UTF-16 or UTF-8 byte order mark (BOM) is detected at the beginning of the file, the file I/O is done in the code page specified by the BOM.

  • For existing IBM i® (iSeries®) files, if no UTF-16 or UTF-8 BOM is detected, the file's CCSID (character set) attribute determines the code page.

See MIME charset names for a list of valid MIME charset values.

Usage

If a file is already open in Binary, Random, or Input mode, you can open a copy of the file using a different file number, without closing the open file. If a file is already open in Append or Output mode, you must close it before opening it with a different file number.

LotusScript® limits the number of open files to 255. Depending on your operating system environment and the HCL software you are running, the actual number of files that you can open may be 15 or less. See your product documentation for details.

Example