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.

See also | CLOSE, FILEATTR, FILENAME$, FILESCAN, FREEFILE, TCP OPEN, UDP OPEN

Example

This program is divided into five procedures. The difference between each procedure is the mode in which the file is opened, and the way the data in the file is manipulated:

SUB SequentialOutput

' The file is opened for sequential output,

' and some data is written to it. If the file

' exists, it is over-written.

OPEN "OPEN.DTA" FOR OUTPUT AS #1

IntegerVar% = 12345

TempStr$ = "History is made at night."

WRITE #1, TempStr$, IntegerVar%*2, TempStr$, IntegerVar% \ 2

CLOSE #1

END SUB ' end procedure Sequential Output

SUB SequentialAppend

' The file is opened for sequential output, and

' data in this case is added to the end of file.

' If the file does not exist, it is created.

OPEN "OPEN.DTA" FOR APPEND AS #1

IntegerVar% = 32123

TempStr$ = "I am not a number!"

WRITE #1, TempStr$, IntegerVar% * 0.2

CLOSE #1

END SUB ' end procedure Sequential Append

SUB SequentialInput

' The file is opened for sequential input,

' and data is read from the file.

DIM a$

OPEN "OPEN.DTA" FOR INPUT AS #1

LINE INPUT #1, TempStr$

TempStr$ = ""

WHILE ISFALSE EOF(1) ' check if at end of file

LINE INPUT #1, a$

TempStr$ = TempStr$ + a$

WEND

CLOSE #1

END SUB ' end procedure SequentialInput

SUB BinaryIO

' The file is opened for binary I/O. Data is

' read 'using GET$. SEEK explicitly moves the

' file pointer to 'the end of file, and the

' same data is written back to 'the file.

OPEN "OPEN.DTA" FOR BINARY AS #1

TempStr$ = ""

WHILE ISFALSE EOF(1)

GET$ #1, 1, Char$

TempStr$ = TempStr$ + Char$

WEND

SEEK #1, LOF(1)

FOR I& = 1 TO LEN(TempStr$)

PUT$ #1, MID$(TempStr$,I&,1)

NEXT I&

CLOSE 1

END SUB ' end procedure BinaryIO

SUB RandomIO

' Open file for random I/O. GET and PUT read

' and write the data.

OPEN "OPEN.DTA" FOR RANDOM AS #1 LEN = 1

TempStr$ = ""

TempSize& = LOF(1) ' save file size

' using GET, read in the entire file

FOR I& = 1 TO TempSize&

GET #1, I&, Char$

TempStr$ = TempStr$ + Char$

NEXT I&

' PUT copies the data in reverse into the

' random access file.

SEEK #1, 1

FOR I& = TempSize& TO 1 STEP -1

LSET Char$ = MID$(TempStr$,I&,1)

PUT #1,, Char$

NEXT I&

CLOSE #1

END SUB ' end procedure RandomIO