EN/documentation/basic guide/files and directories runtime library

 < EN | The OpenOffice.org Documentation Project | OpenOffice.org BASIC Programming Guide

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|← Previous Section ]]

[[{{{NextPart}}}|Next Section →]]

• The Language of OpenOffice.org Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

← Previous Page

Next Page →

Working with files is one of the basic tasks of an application. The OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org Basic provides several fundamental functions for these tasks.

Some DOS-specific file and directory functions are no longer provided in OpenOffice.org, or their function is only limited. For example, support for the ChDir, ChDrive and CurDir functions is not provided. Some DOS-specific properties are no longer used in functions that expect file properties as parameters (for example, to differentiate from concealed files and system files). This change became necessary to ensure the greatest possible level of platform independence for OpenOffice.org.

Administering Files

Compatibility Mode

The CompatibilityMode statement and function provide greater compatibility with VBA, by changing the operation of certain functions. The effect on any particular function is described with that function, below.

As a statement, CompatibilityMode( value ) takes a Boolean value to set or clear the mode. As a function, CompatibilityMode() returns the Boolean value of the mode.

CompatibilityMode( True ) 'set mode
CompatibilityMode( False ) 'clear mode

Dim bMode as Boolean
bMode = CompatibilityMode()

Searching Through Directories

The Dir function in OpenOffice.org 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. OpenOffice.org 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; 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 = Dir
  Wend

  MsgBox AllDirs
End Sub

VBA : When requested in OpenOffice.org Basic, the Dir function, using the parameter 16, only returns the sub-directories of a folder. In VBA, the function also returns the names of the standard files so that further checking is needed to retrieve the directories only. When using the CompatibilityMode ( true ) function, OpenOffice.org Basic behaves like VBA and the Dir function, using parameter 16, returns sub-directories and standard files.

VBA : The options provided in VBA for searching through directories specifically for files with the concealed, system file, archived, and volume name properties does not exist in OpenOffice.org Basic because the corresponding file system functions are not available on all operating systems.

VBA : The path specifications listed in Dir may use the * and ? place holders in both VBA and OpenOffice.org Basic. In OpenOffice.org Basic, the * place holder may however only be the last character of a file name and/or file extension, which is not the case in VBA.

Creating and Deleting Directories

OpenOffice.org 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.

VBA : In VBA, the MkDir and RmDir functions only relate to the current directory. In OpenOffice.org Basic on the other hand, MkDir and RmDir can be used to create or delete levels of directories.

VBA : In VBA, RmDir produces an error message if a directory contains a file. In OpenOffice.org Basic, the directory and all its files are deleted. If you use the CompatibilityMode ( true ) function, OpenOffice.org Basic will behave like VBA.

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

VBA : The flags used in VBA for querying the concealed, system file,archived and volume name file properties are not supported in OpenOffice.org Basic because these are Windows-specific and are not or are only partially available on other operating systems.

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

OpenOffice.org 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:

FileNo = FreeFile

FileNo is an integer variable that receives the file handle. The handle is then used as a parameter for the Open instruction, which opens the file.

To open a file so that it can be written 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 create the file contents, 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, written, 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.

Content on this page is licensed under the Public Documentation License (PDL).