Sancho at 16:56, 2 September 2011

2011-09-02T16:56:00Z

Sancho: moved EN/documentation/basic guide/files and directories (runtime library) to EN/documentation/basic guide/files and directories runtime library

2011-09-02T16:51:09Z

moved EN/documentation/basic guide/files and directories (runtime library) to EN/documentation/basic guide/files and directories runtime library

Sancho at 10:50, 2 September 2011

2011-09-02T10:50:00Z

Sancho: Основной текст

2011-09-02T10:49:26Z

Основной текст

New page

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Files and Directories ({{OOo}} Runtime Library)<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

{{Documentation/BASICGuideTOC
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=EN/documentation/basic_guide/date_and_time_(runtime_library)
|NextPage=EN/documentation/basic_guide/message_and_input_boxes_(runtime_library)
|runtime=block
}}

__NOTOC__

Working with files is one of the basic tasks of an application. The {{OOo}} 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 [[EN/documentation/basic_guide/api_intro|Introduction to the {{OOo}} 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 {{OOo}} Basic provides several fundamental functions for these tasks.

{{Note|Some DOS-specific file and directory functions are no longer provided in {{OOo}}, or their function is only limited. For example, support for the <tt>ChDir</tt>, <tt>ChDrive</tt> and <tt>CurDir</tt> 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 {{OOo}}.}}

== Administering Files ==

=== Compatibility Mode ===

The <tt>CompatibilityMode</tt> 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, <tt>CompatibilityMode( value )</tt> takes a Boolean value to set or clear the mode. As a function, <tt>CompatibilityMode()</tt> returns the Boolean value of the mode.

<source lang="oobas">
CompatibilityMode( True ) 'set mode
CompatibilityMode( False) 'clear mode

Dim bMode as Boolean
bMode = CompatibilityMode()
</source>

=== Searching Through Directories ===

The <tt>Dir</tt> function in {{OOo}} 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 <tt>Dir</tt> as its first parameter. The second parameter of <tt>Dir</tt> specifies the file or directory to be searched for. {{OOo}} Basic returns the name of the first directory entry found. To retrieve the next entry, the <tt>Dir</tt> function should be requested without parameters. If the <tt>Dir</tt> function finds no more entries, it returns an empty string.

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

<source lang="oobas">
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
</source>

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

* <tt>0</tt> : returns normal files
* <tt>16</tt> : sub-directories

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

<source lang="oobas">
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
</source>

{{VBAnote|When requested in {{OOo}} Basic, the <tt>Dir</tt> 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 <tt>CompatibilityMode ( true )</tt> function, {{OOo}} Basic behaves like VBA and the Dir function, using parameter 16, returns sub-directories and standard files.}}

{{VBAnote|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 {{OOo}} Basic because the corresponding file system functions are not available on all operating systems.}}

{{VBAnote|The path specifications listed in <tt>Dir</tt> may use the * and ? place holders in both VBA and {{OOo}} Basic. In {{OOo}} 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 ===

{{OOo}} Basic provides the <tt>MkDir</tt> function for creating directories.

<source lang="oobas">
MkDir ("C:\SubDir1")
</source>

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

<source lang="oobas">
MkDir ("C:\SubDir1\SubDir2\SubDir3\")
</source>

creates both the <tt>C:\SubDir1\SubDir2</tt> directory and the <tt>C:\SubDir1\SubDir2\SubDir3</tt> directory.

The <tt>RmDir</tt> function deletes directories.

<source lang="oobas">
RmDir ("C:\SubDir1\SubDir2\SubDir3\")
</source>

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

{{VBAnote|In VBA, the <tt>MkDir</tt> and <tt>RmDir</tt> functions only relate to the current directory. In {{OOo}} Basic on the other hand, <tt>MkDir</tt> and <tt>RmDir</tt> can be used to create or delete levels of directories.}}

{{VBAnote|In VBA, <tt>RmDir</tt> produces an error message if a directory contains a file. In {{OOo}} Basic, the directory '''and all its files''' are deleted. If you use the <tt>CompatibilityMode ( true )</tt> function, {{OOo}} Basic will behave like VBA.}}

=== Copying, Renaming, Deleting and Checking the Existence of Files ===

The following call creates a copy of the <tt>Source</tt> file under the name of <tt>Destination</tt>:

<source lang="oobas">
FileCopy(Source, Destination)
</source>

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

<source lang="oobas">
Name OldName As NewName
</source>

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

<source lang="oobas">
Kill(Filename)
</source>

The <tt>FileExists</tt> function can be used to check whether a file exists:

<source lang="oobas">
If FileExists(Filename) Then
MsgBox "file exists."
End If
</source>

=== 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.

<source lang="oobas">
Dim Attr As Integer
Attr = GetAttr(Filename)
</source>

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 <tt>test.txt</tt> file and checks whether this is read-only whether it is a directory. If neither of these apply, <tt>FileDescription</tt> is assigned the "normal" string.

<source lang="oobas">
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
</source>

{{VBAnote|The flags used in VBA for querying the '''concealed''', '''system file,archived''' and '''volume name''' file properties are not supported in {{OOo}} Basic because these are Windows-specific and are not or are only partially available on other operating systems.}}

The <tt>SetAttr</tt> 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:

<source lang="oobas">
SetAttr("test.txt", 1)
</source>

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

<source lang="oobas">
SetAttr("test.txt", 0)
</source>

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

<source lang="oobas">
FileDateTime("test.txt") ' Provides date and time of the last file amendment.
</source>

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

<source lang="oobas">
FileLen("test.txt") ' Provides the length of the file in bytes
</source>

== Writing and Reading Text Files ==

{{OOo}} 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 <tt>FreeFile</tt> function is used to create a free file handle:

<source lang="oobas">
FileNo = FreeFile
</source>

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

To open a file so that it can be written as a text file, the <tt>Open</tt> call is:

<source lang="oobas">
Open Filename For Output As #FileNo
</source>

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

Once the file is opened, the <tt>Print</tt> instruction can create the file contents, line by line:

<source lang="oobas">
Print #FileNo, "This is a test line."
</source>

<tt>FileNo</tt> 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 <tt>Close</tt> call:

<source lang="oobas">
Close #FileNo
</source>

Again here, the file handle should be specified.

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

<source lang="oobas">
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
</source>

=== Reading Text Files ===

Text files are read in the same way that they are written. The <tt>Open</tt> instruction used to open the file contains the <tt>For Input</tt> expression in place of the <tt>For Output</tt> 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 <tt>eof</tt> instruction is used to check whether the end of the file has been reached:

<source lang="oobas">
eof(FileNo)
</source>

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

<source lang="oobas">
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
</source>

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

{{PDL1}}

← Older revision		Revision as of 10:50, 2 September 2011
Line 1:		Line 1:
	<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Files and Directories ({{OOo}} Runtime Library)<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}		<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Files and Directories ({{OOo}} Runtime Library)<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}
−
−

	{{Documentation/BASICGuideTOC		{{Documentation/BASICGuideTOC

@@ Line 4: / Line 4: @@
 |ShowPrevNext=block
 |ShowPrevPage=block
-|PrevPage=EN/documentation/basic_guide/date_and_time_(runtime_library)
+|PrevPage=EN/documentation/basic_guide/date_and_time_runtime_library
-|NextPage=EN/documentation/basic_guide/message_and_input_boxes_(runtime_library)
+|NextPage=EN/documentation/basic_guide/message_and_input_boxes_runtime_library
 |runtime=block
 }}
@@ Line 25: / Line 25: @@
 <source lang="oobas">
 CompatibilityMode( True ) 'set mode
-CompatibilityMode( False) 'clear mode
+CompatibilityMode( False ) 'clear mode
 Dim bMode as Boolean

← Older revision	Revision as of 16:51, 2 September 2011
(No difference)

EN/documentation/basic guide/files and directories runtime library - Revision history

Sancho at 16:56, 2 September 2011

Sancho: moved EN/documentation/basic guide/files and directories (runtime library) to EN/documentation/basic guide/files and directories runtime library

Sancho at 10:50, 2 September 2011

Sancho: Основной текст