OPEN statement

Purpose

Prepare a file or device for reading or writing.

Syntax

OPEN filespec [FOR mode] [ACCESS access] [LOCK lock] AS _

[#] filenum& [LEN = record_size] [BASE = base] [CHR = ANSI|WIDE]

OPEN HANDLE filehandle [FOR mode] [ACCESS access] [LOCK lock] AS _

[#] filenum& [LEN = record_size] [BASE = base] [CHR = ANSI|WIDE]

Remarks

The main function of OPEN is to associate a file number (filenum&) with a file or physical device and to prepare that device for reading and/or writing. This file number is then used, rather than its name, in every statement that refers to the file. The FREEFILE function can be used to determine the next unused file number, or you can pick one yourself. An OPEN statement is usually balanced by a matching CLOSE statement. The OPEN statement comprises the following elements:

filespec

A string expression specifying the name of the file to be opened, and may optionally include a drive and/or path specification. filespec may be either a Short File Name (SFN) or a Long File Name (LFN). filespec has a limit of 259 characters (%MAX_PATH - 1), although the file name portion of filespec may be no more than 255 characters (%MAX_FNAME - 1).

mode

Specifies the file organization and style of access (sequential, random access, or binary) for reading, writing (or both), or appending. If mode is not specified, the default is RANDOM access.

Mode	File type	Action
INPUT	Sequential	Read from
OUTPUT	Sequential	Write to
APPEND	Sequential	Append to
BINARY	Binary	Reading or writing
RANDOM	Random	Reading or writing (default)

access

Specifies the type of access this process will have to the file. By default, the file may be written to and read from.

*Access*	Description
READ	Only read operations allowed
WRITE	Only write operations allowed
READ WRITE	Both read and write operations allowed (default)

Note that APPEND mode requires READ/WRITE access.

lock

Specifies the type of access other processes will have to the file. If a LOCK clause is not specified in the OPEN statement, the default LOCK READ WRITE mode is applied. This mode ensures exclusive access to the file, and enables PowerBASIC to optimize its internal buffering for utmost I/O performance. If other processes or threads are to be permitted WRITE access to the file (LOCK SHARED or LOCK READ), internal buffering is disabled. Whilst performance may be marginally lower, it ensures that data read from the file is completely up-to-date.

*Lock*	Description
SHARED	Both read and write operations allowed
WRITE	Prevent write operations
READ	Prevent read operations
READ WRITE	Neither read nor write operations allowed (default)

To open a text file for OUTPUT and allow other processes to only read the file, use the following:

OPEN "MYFILE.TXT" FOR OUTPUT LOCK WRITE AS #1

It is possible for an application to open more than one copy of a given file at the same time. In this case, each OPEN statement must use a unique file number, and LOCK READ WRITE mode should not be used.

filenum&

A unique integer value identifying the file, in the range 1 to 32767. Typically, this value is obtained from the FREEFILE function.

record_size

Specifies the size of each record of a random access file. The default record length is 128 if not specified. If record_size is specified for a sequential file, it instructs PowerBASIC to use internal buffering to improve I/O performance. A random access file is limited to 32768 bytes per record, to ensure consistent behavior across all Win32 platforms.

base

Specifies the number of the first record in a random access file, or the number of the first byte in a sequential or binary file. It can be either zero (0) or one (1). The default value for base is 1, if not specified.

Chr

Specifies the character mode for this file: ANSI or WIDE (Unicode). Since sequential files consist of text alone, the selected mode is enforced by PowerBASIC. All data read or written to the file is automatically forced to the selected mode, regardless of the type of variables or expressions used. With binary or random files, this specification has no effect, but it may be included in your code for self-documentation purposes.

ANSI characters in the U.S. range of CHR$(0) to CHR$(127) are known as ASCII, and are always represented by a single byte. International ANSI characters in the range of CHR$(128) to CHR$(255) may be followed by one or more additional bytes in order to accurately represent non-U.S. characters. The exact definition of these characters depends upon the character set in use. WIDE characters are always represented by two bytes per character. If the Chr option is not specified, the default mode is ANSI.

HANDLE

The HANDLE option allows you to access files that have already been opened by another process, DLL, or API function. The filehandle specified here must be a valid Win32 operating system file handle.

When PowerBASIC closes a file opened with OPEN HANDLE, the Win32 handle is simply detached from the internal PowerBASIC handle table. The file is not physically closed since PowerBASIC did not originally open it. In PowerBASIC, the FILEATTR function can be used to obtain the operating system file handle for a file opened with the OPEN statement.

Restrictions

Attempting to OPEN a file for INPUT that does not exist causes a run-time Error 53 ("File not found"). Attempting to open a file that is locked can result in either an Error 70 ("Permission denied"), or an Error 75 ("Path/file access error").

Similarly, attempting to OPEN a file using a file number that is already in use will result in a run-time Error 55 ("File is already open "). For this reason, programs that use hard-coded file numbers should take special care to close files before the file number is used again. In addition, code that may be used by more than one thread should use FREEFILE and avoid hard-coded file numbers.

If you try to open a nonexistent file for OUTPUT, APPEND, RANDOM, or BINARY operations, a new file is automatically created. For this reason, files on Read-only network drives may only be opened in INPUT mode.