Difference between revisions of "Documentation/BASIC Guide/Files and Directories (Runtime Library)"

Revision as of 13:36, 2 April 2008

>]]

Working with files is one of the basic tasks of an application. The Apache OpenOffice API provides you with a whole range of objects with which you can create, open and modify Office documents. These are presented in detail in the Introduction to the Apache OpenOffice API. Regardless of this, in some instances you will have to directly access the file system, search through directories or edit text files. The runtime library from Apache OpenOffice Basic provides several fundamental functions for these tasks.

Template:Documentation/Note

Administering Files

Searching Through Directories

The Dir function in Apache OpenOffice Basic is responsible for searching through directories for files and sub-directories. When first requested, a string containing the path of the directories to be searched must be assigned to Dir as its first parameter. The second parameter of Dir specifies the file or directory to be searched for. Apache OpenOffice Basic returns the name of the first directory entry found. To retrieve the next entry, the Dir function should be requested without parameters. If the Dir function finds no more entries, it returns an empty string.

The following example shows how the Dir function can be used to request all files located in one directory. The procedure saves the individual file names in the AllFiles variable and then displays this in a message box.

Sub ShowFiles
  Dim NextFile As String
  Dim AllFiles As String
 
  AllFiles = ""
  NextFile = Dir("C:\", 0)
 
  While NextFile  <> ""
    AllFiles = AllFiles & Chr(13) &  NextFile 
    NextFile = Dir
  Wend
 
  MsgBox AllFiles
End Sub

The 0 (zero) used as the second parameter in the Dir function ensures that Dir only returns the names of files and directories are ignored. The following parameters can be specified here:

• 0 : returns normal files
• 16 : sub-directories

The following example is virtually the same as the preceding example, but the Dir function transfers the value 16 as a parameter, which returns the sub-directories of a folder rather than the file names.

Sub ShowDirs
  Dim NextDir As String
  Dim AllDirs As String
 
  AllDirs = ""
  NextDir = Dir("C:\", 16)
 
  While NextDir <> ""
    AllDirs = AllDirs & Chr(13) &  NextDir
    NextDir  <nowiki>= Dir</nowiki>
  Wend
 
  MsgBox AllDirs
End Sub

Template:Documentation/Note

Template:Documentation/Note

Template:Documentation/Note

Creating and Deleting Directories

Apache OpenOffice Basic provides the MkDir function for creating directories.

MkDir ("C:\SubDir1")

This function creates directories and sub-directories. All directories needed within a hierarchy are also created, if required. For example, if only the C:\SubDir1 directory exists, then a call

MkDir ("C:\SubDir1\SubDir2\SubDir3\")

creates both the C:\SubDir1\SubDir2 directory and the C:\SubDir1\SubDir2\SubDir3 directory.

The RmDir function deletes directories.

RmDir ("C:\SubDir1\SubDir2\SubDir3\")

If the directory contains sub-directories or files, these are also deleted. You should therefore be careful when using RmDir.

Template:Documentation/Note

Template:Documentation/Note

Copying, Renaming, Deleting and Checking the Existence of Files

The following call creates a copy of the Source file under the name of Destination:

FileCopy(Source, Destination)

With the help of the following function you can rename the OldName file with NewName. The As keyword syntax, and the fact that a comma is not used, goes back to the roots of the Basic language.

Name OldName As NewName

The following call deletes the Filename file. If you want to delete directory (including its files) use the RmDir function.

Kill(Filename)

The FileExists function can be used to check whether a file exists:

If FileExists(Filename) Then 
  MsgBox "file exists."
End If

Reading and Changing File Properties

When working with files, it is sometimes important to be able to establish the file properties, the time the file was last changed and the length of the file.

The following call returns some properties about a file.

Dim Attr As Integer
Attr = GetAttr(Filename)

The return value is provided as a bit mask in which the following values are possible:

• 1 : read-only file
• 16 : name of a directory

The following example determines the bit mask of the test.txt file and checks whether this is read-only whether it is a directory. If neither of these apply, FileDescription is assigned the "normal" string.

Dim FileMask As Integer
Dim FileDescription As String
 
FileMask = GetAttr("test.txt")
 
If (FileMask AND 1) > 0 Then
  FileDescription = FileDescription & " read-only "
End IF
 
If (FileMask AND 16) > 0 Then
  FileDescription = FileDescription & " directory "
End IF
 
If FileDescription = "" Then
  FileDescription = " normal "
End IF
 
MsgBox FileDescription

Template:Documentation/Note

The SetAttr function permits the properties of a file to be changed. The following call can therefore be used to provide a file with read-only status:

SetAttr("test.txt", 1)

An existing read-only status can be deleted with the following call:

SetAttr("test.txt", 0)

The date and time of the last amendment to a file are provided by the FileDateTime function. The date is formatted here in accordance with the country-specific settings used on the system.

FileDateTime("test.txt")   ' Provides date and time of the last file amendment.

The FileLen function determines the length of a file in bytes (as long integer value).

FileLen("test.txt")      ' Provides the length of the file in bytes

Writing and Reading Text Files

Apache OpenOffice Basic provides a whole range of methods for reading and writing files. The following explanations relate to working with text files (not text documents).

Writing Text Files

Before a text file is accessed, it must first be opened. To do this, a free file handle is needed, which clearly identifies the file for subsequent file access.

The FreeFile function is used to create a free file handle. The handle is used as a parameter for the Open instruction, which opens the file. To open a file so that it can be specified as a text file, the Open call is:

Open Filename For Output As #FileNo

Filename is a string containing the name of the file. FileNo is the handle created by the FreeFile function.

Once the file is opened, the Print instruction can be described line by line:

Print #FileNo, "This is a test line."

FileNo also stands for the file handle here. The second parameter specifies the text that is to be saved as a line of the text file.

Once the writing process has been completed, the file must be closed using a Close call:

Close #FileNo

Again here, the file handle should be specified.

The following example shows how a text file is opened, described and closed:

Dim FileNo As Integer
Dim CurrentLine As String
Dim Filename As String
 
Filename = "c:\data.txt"            ' Define file name 
FileNo = Freefile               ' Establish free file handle
 
Open Filename For Output As #FileNo         ' Open file (writing mode)
Print #FileNo, "This is a line of text"      ' Save line 
Print #FileNo, "This is another line of text"   ' Save line 
Close #FileNo                  ' Close file

Reading Text Files

Text files are read in the same way that they are written. The Open instruction used to open the file contains the For Input expression in place of the For Output expression and, rather than the Print command for writing data, the Line Input instruction should be used to read the data.

Finally, when calling up a text file, the eof instruction is used to check whether the end of the file has been reached:

eof(FileNo)

The following example shows how a text file can be read:

Dim FileNo As Integer
Dim CurrentLine As String
Dim File As String
Dim Msg as String
 
' Define filename 
Filename = "c:\data.txt"
 
' Establish free file handle
FileNo = Freefile
 
' Open file (reading mode)
Open Filename For Input As FileNo
 
' Check whether file end has been reached
Do While not eof(FileNo)
  ' Read line 
  Line Input #FileNo, CurrentLine   
  If CurrentLine <>"" then
    Msg = Msg & CurrentLine & Chr(13)
  end if
Loop
 
 
' Close file 
 
Close #FileNo               
Msgbox Msg

The individual lines are retrieved in a Do While loop, saved in the Msg variable, and displayed at the end in a message box.