Open a File

OpenOffice.org uses low-level, system-specific methods to manipulate files. The operating system maintains a list of the open files and identifies them with a number, which is called a "file handle." In the world of Basic, this is usually called the "file number" or "data channel."

To open a file, you must tell it what file number to use. Use the FreeFile function to obtain an unused file number, which will be used when opening a file, referencing the open file, and when closing the file. The Open statement is used to open a file before it is usable for reading or writing. The Open statement requires a file number, which should always be obtained from the FreeFile function. Use the Close statement when you are finished with the file. You can close multiple files in a single statement by providing a comma-separated list of numbers after the Close statement. Use the Reset function to close all of the open files at one time without having to explicitly list the file numbers. All open file numbers are closed and their data is flushed to disk.

 n = FreeFile() Open FileName For Mode [Access ioMode] [Lock Mode] As #n [Len=Datalen] Close #n

"FileName" is the name of the file that you want to open. If the file name does not include the path , the current directory is assumed. "For Mode" specifies the state of the file when it is opened and how you'll deal with the file after it's opened (see Table 7 ).

Table 7: Valid "For Mode" values and the resulting configuration if Access is not used.
For Mode	File Pointer	File Exists	No File	Read	Write	Comment
For Append	end	Open	Create	Yes	Yes	Sequential access
For Input	start	Open	error	Yes	No	Sequential access
For Output	start	Delete	Create	Yes	Yes	Sequential access
For Binary	start	Delete	Create	Yes	Yes	Random access
For Random	start	Delete	Create	Yes	Yes	Random access

When a file is open, a pointer into the file is maintained . This pointer identifies where the next read or write operation will occur. For example, if the file pointer is at the start of the file, the next "read" command will read the first thing in the file. If the file pointer is at the end of the file, the next "write" command will append data to the end of the file. You have some control over the initial position of the file pointer when the file is opened, and you can move this file pointer around when the file is open. All of the "For" modes, except "For Append," position the file pointer at the start of the file.

You can access a file sequentially or randomly . A sequential file is similar to a video tape. Although you can fast forward and rewind the tape to a specific location on the tape, the entire tape moves past the read/write head. You then press Play or Record and the data is either sequentially read from or written to the tape. A random file is similar to a music CD. Although you can play the CD sequentially, it isn't required; you can quickly jump to any song and play it. To make the analogy more accurate, however, each song on the CD must be the same size . This is the disadvantage to the "For Random" mode.

Consider storing names of different lengths in a file on the disk. Storing one name per line in the file is efficient with respect to space. You can use a new-line character between each name. To find a specific name in the file, you start at the beginning and read until you find the person's name. On the other hand, if you know that the longest name is 100 characters, you can store each name on the disk, and store enough spaces after the name to use a total of 100 characters for each name. This wastes space, but it allows you to quickly move between names on the disk, because of the regular file structure. To read or write the 1000th name in the file, you simply move directly to that record. You have wasted space in this design, but you have gained speed performance. All of the "For" modes," except "For Random," specify sequential file access. Random files use this ability to fix the record length to the maximum size of interest in order to permit very rapid file access and retrieval.

The access modes in Table 8 affect the default treatment of a file when it is opened. When an access mode is specified, it also verifies that you have access to either read or write the file. If you do not have write access to a file opened with "Access Write," a run-time error occurs. The access mode affects every open "For" mode except "For Append"-which never deletes an existing file when it is opened.

Table 8: Valid Access ioModes.
Access ioMode	Description
Access Read	Do not delete an existing file. Verify that you have read access.
Access Write	Delete an existing file. Verify that you have write access.
Access Read Write	Delete an existing file. Verify that you have read and write access.

Using "Access Write" while opening a file "For Input" allows you to write to the file after it is opened; first the file is erased and then a new file is created. After the file is open, different operating systems enforce the access rights differently. As of OOo version 1.1.1, opening a binary or random file with "Access Read" allows you to write to the file when using Windows, but not on Linux. It is always safe to open a file "For Append" and then move the file pointer to the start of the file manually.

Tip	The only safe way to open a file for both reading and writing without erasing the contents of the file is to open the file "For Append," and then move the file pointer to the start of the file.

To limit access to a file while it's open, use the "Lock" modes (see Table 9 ). This prevents others from reading and/or writing to the file while you have it open. This is primarily used in multi- user environments because you can't control what others might try to do while you are using the file.

Table 9: Valid protected keywords.
Lock Mode	Description
Lock Read	Others cannot read the file while it's open, but they can write to it.
Lock Write	Others cannot write the file while it's open, but they can read from it.
Lock Read Write	Others cannot read or write the file while it is open.

Use the Len keywords to specify the size of each record when the file is opened "For Random" (discussed later).