FreeFile Function

Returns an Integer representing the next file number available for use by the Open statement.

Syntax

FreeFile[(rangenumber)]

Parameters

• rangenumber - Optional. Variant that specifies which range of file numbers to use.
• 0 (default) - Returns a file number in the range 1-255 (inclusive).
• 1 - Returns a file number in the range 256-511 (inclusive).

Return Value

Returns an Integer representing the next available file number that is not already in use.

Remarks

• Use FreeFile to obtain a file number that is not already associated with an open file.
• FreeFile returns the lowest available file number in the specified range.
• When using multiple files, always use FreeFile to avoid conflicts with file numbers.
• The file number returned can be used with the Open statement to open a file.
• After obtaining a file number with FreeFile, use it immediately to avoid conflicts.
• File numbers are released when the file is closed with the Close statement.
• The function is particularly important in libraries and reusable code where you don't know what file numbers are already in use.

Typical Uses

• Opening files for sequential, random, or binary access
• Writing to log files
• Reading configuration files
• Temporary file operations
• Data import/export operations
• File-based data storage

Basic Usage Examples

' Basic file operations
Dim fileNum As Integer
fileNum = FreeFile
Open "data.txt" For Output As #fileNum
Print #fileNum, "Hello, World!"
Close #fileNum

' Multiple file operations
Dim inputFile As Integer
Dim outputFile As Integer
inputFile = FreeFile
Open "input.txt" For Input As #inputFile
outputFile = FreeFile
Open "output.txt" For Output As #outputFile
' Process files...
Close #inputFile
Close #outputFile

' Using range parameter
Dim highRangeFile As Integer
highRangeFile = FreeFile(1)  ' Returns 256-511
Open "temp.dat" For Binary As #highRangeFile
Close #highRangeFile

' Immediate use pattern
Open "log.txt" For Append As #FreeFile
' Note: Cannot close without saving the file number

Common Patterns

1. Simple File Read

Sub ReadTextFile(filename As String)
Dim fileNum As Integer
Dim line As String

fileNum = FreeFile
Open filename For Input As #fileNum

Do While Not EOF(fileNum)
Line Input #fileNum, line
Debug.Print line
Loop

Close #fileNum
End Sub

2. Simple File Write

Sub WriteTextFile(filename As String, content As String)
Dim fileNum As Integer

fileNum = FreeFile
Open filename For Output As #fileNum
Print #fileNum, content
Close #fileNum
End Sub

3. Append to Log File

Sub LogMessage(message As String)
Dim fileNum As Integer

fileNum = FreeFile
Open App.Path & "\app.log" For Append As #fileNum
Print #fileNum, Now & " - " & message
Close #fileNum
End Sub

4. Copy File Contents

Sub CopyFile(source As String, destination As String)
Dim sourceNum As Integer
Dim destNum As Integer
Dim line As String

sourceNum = FreeFile
Open source For Input As #sourceNum

destNum = FreeFile
Open destination For Output As #destNum

Do While Not EOF(sourceNum)
Line Input #sourceNum, line
Print #destNum, line
Loop

Close #sourceNum
Close #destNum
End Sub

5. Read Binary File

Function ReadBinaryFile(filename As String) As Byte()
Dim fileNum As Integer
Dim fileSize As Long
Dim buffer() As Byte

fileNum = FreeFile
Open filename For Binary As #fileNum

fileSize = LOF(fileNum)
ReDim buffer(0 To fileSize - 1)
Get #fileNum, , buffer

Close #fileNum
ReadBinaryFile = buffer
End Function

6. Write Binary File

Sub WriteBinaryFile(filename As String, data() As Byte)
Dim fileNum As Integer

fileNum = FreeFile
Open filename For Binary As #fileNum
Put #fileNum, , data
Close #fileNum
End Sub

7. Read INI-Style Configuration

Function ReadConfigValue(filename As String, key As String) As String
Dim fileNum As Integer
Dim line As String
Dim pos As Integer

fileNum = FreeFile
Open filename For Input As #fileNum

Do While Not EOF(fileNum)
Line Input #fileNum, line
line = Trim(line)

If Left(line, Len(key) + 1) = key & "=" Then
ReadConfigValue = Mid(line, Len(key) + 2)
Close #fileNum
Exit Function
End If
Loop

Close #fileNum
ReadConfigValue = ""
End Function

8. Write CSV File

Sub WriteCSV(filename As String, data() As Variant)
Dim fileNum As Integer
Dim i As Long, j As Long
Dim row As String

fileNum = FreeFile
Open filename For Output As #fileNum

For i = LBound(data, 1) To UBound(data, 1)
row = ""
For j = LBound(data, 2) To UBound(data, 2)
If j > LBound(data, 2) Then row = row & ","
row = row & CStr(data(i, j))
Next j
Print #fileNum, row
Next i

Close #fileNum
End Sub

9. Read Entire File into String

Function ReadFileAsString(filename As String) As String
Dim fileNum As Integer
Dim fileContent As String

fileNum = FreeFile
Open filename For Input As #fileNum
fileContent = Input(LOF(fileNum), fileNum)
Close #fileNum

ReadFileAsString = fileContent
End Function

10. Process Large File Line by Line

Sub ProcessLargeFile(filename As String)
Dim fileNum As Integer
Dim line As String
Dim lineCount As Long

fileNum = FreeFile
Open filename For Input As #fileNum

lineCount = 0
Do While Not EOF(fileNum)
Line Input #fileNum, line
lineCount = lineCount + 1

' Process line here
If lineCount Mod 1000 = 0 Then
Debug.Print "Processed " & lineCount & " lines..."
End If
Loop

Close #fileNum
Debug.Print "Total lines: " & lineCount
End Sub

Advanced Usage

1. File Manager Class

' Class module: FileManager
Private m_FileNumber As Integer

Public Sub OpenFile(filename As String, mode As String)
m_FileNumber = FreeFile

Select Case LCase(mode)
Case "read"
Open filename For Input As #m_FileNumber
Case "write"
Open filename For Output As #m_FileNumber
Case "append"
Open filename For Append As #m_FileNumber
Case "binary"
Open filename For Binary As #m_FileNumber
End Select
End Sub

Public Sub WriteLine(text As String)
Print #m_FileNumber, text
End Sub

Public Function ReadLine() As String
Dim line As String
If Not EOF(m_FileNumber) Then
Line Input #m_FileNumber, line
ReadLine = line
End If
End Function

Public Function IsEOF() As Boolean
IsEOF = EOF(m_FileNumber)
End Function

Public Sub CloseFile()
If m_FileNumber > 0 Then
Close #m_FileNumber
m_FileNumber = 0
End If
End Sub

Private Sub Class_Terminate()
CloseFile
End Sub

2. Safe File Operations with Error Handling

Function SafeWriteFile(filename As String, content As String) As Boolean
Dim fileNum As Integer

On Error GoTo ErrorHandler

fileNum = FreeFile
Open filename For Output As #fileNum
Print #fileNum, content
Close #fileNum

SafeWriteFile = True
Exit Function

ErrorHandler:
If fileNum > 0 Then Close #fileNum
SafeWriteFile = False
Debug.Print "Error writing file: " & Err.Description
End Function

3. Multi-File Transaction Manager

Type FileHandle
Number As Integer
Filename As String
IsOpen As Boolean
End Type

Sub TransactionExample()
Dim files(1 To 3) As FileHandle
Dim i As Integer

On Error GoTo Rollback

' Open multiple files
For i = 1 To 3
files(i).Number = FreeFile
files(i).Filename = "file" & i & ".txt"
files(i).IsOpen = False
Next i

' Perform operations
For i = 1 To 3
Open files(i).Filename For Output As #files(i).Number
files(i).IsOpen = True
Print #files(i).Number, "Data for file " & i
Next i

' Success - close all
For i = 1 To 3
Close #files(i).Number
files(i).IsOpen = False
Next i

Exit Sub

Rollback:
' Clean up any open files
For i = 1 To 3
If files(i).IsOpen Then
Close #files(i).Number
End If
Next i

MsgBox "Transaction failed: " & Err.Description
End Sub

4. File Pool Manager

' Module-level variables
Private m_FilePool() As Integer
Private m_PoolSize As Integer

Sub InitializeFilePool(poolSize As Integer)
Dim i As Integer

m_PoolSize = poolSize
ReDim m_FilePool(1 To poolSize)

For i = 1 To poolSize
m_FilePool(i) = FreeFile(1)  ' Use high range
Next i
End Sub

Function GetPooledFileNumber() As Integer
Static currentIndex As Integer

currentIndex = currentIndex + 1
If currentIndex > m_PoolSize Then currentIndex = 1

GetPooledFileNumber = m_FilePool(currentIndex)
End Function

5. Buffered File Writer

Type BufferedWriter
FileNumber As Integer
Buffer As String
BufferSize As Long
MaxBufferSize As Long
End Type

Sub InitBufferedWriter(writer As BufferedWriter, filename As String, _
Optional maxBuffer As Long = 4096)
writer.FileNumber = FreeFile
writer.MaxBufferSize = maxBuffer
writer.BufferSize = 0
writer.Buffer = ""

Open filename For Output As #writer.FileNumber
End Sub

Sub BufferedWrite(writer As BufferedWriter, text As String)
writer.Buffer = writer.Buffer & text & vbCrLf
writer.BufferSize = Len(writer.Buffer)

If writer.BufferSize >= writer.MaxBufferSize Then
Print #writer.FileNumber, writer.Buffer;
writer.Buffer = ""
writer.BufferSize = 0
End If
End Sub

Sub FlushBufferedWriter(writer As BufferedWriter)
If writer.BufferSize > 0 Then
Print #writer.FileNumber, writer.Buffer;
writer.Buffer = ""
writer.BufferSize = 0
End If

Close #writer.FileNumber
End Sub

6. Temporary File Manager

Function CreateTempFile() As Integer
Dim fileNum As Integer
Dim tempPath As String
Dim tempFile As String

tempPath = Environ("TEMP")
If Right(tempPath, 1) <> "\" Then tempPath = tempPath & "\"

tempFile = tempPath & "temp_" & Format(Now, "yyyymmddhhnnss") & ".tmp"

fileNum = FreeFile
Open tempFile For Binary As #fileNum

CreateTempFile = fileNum
End Function

Sub DeleteTempFile(fileNum As Integer)
Dim filename As String

' Get filename before closing
filename = FileAttr(fileNum, 1)  ' Returns filename

Close #fileNum
Kill filename  ' Delete the file
End Sub

Error Handling

Function SafeFileOperation(filename As String) As Boolean
Dim fileNum As Integer

On Error GoTo ErrorHandler

fileNum = FreeFile
Open filename For Input As #fileNum

' Process file...

Close #fileNum
SafeFileOperation = True
Exit Function

ErrorHandler:
' Always try to close the file
On Error Resume Next
If fileNum > 0 Then Close #fileNum
On Error GoTo 0

Select Case Err.Number
Case 53  ' File not found
Debug.Print "File not found: " & filename
Case 55  ' File already open
Debug.Print "File already open: " & filename
Case 70  ' Permission denied
Debug.Print "Permission denied: " & filename
Case 71  ' Disk not ready
Debug.Print "Disk not ready"
Case 76  ' Path not found
Debug.Print "Path not found: " & filename
Case Else
Debug.Print "Error " & Err.Number & ": " & Err.Description
End Select

SafeFileOperation = False
End Function

Common errors: - Error 55 (File already open): File number is already in use. Always use FreeFile to avoid this. - Error 52 (Bad file name or number): Invalid file number. Ensure the number is in the valid range. - Error 53 (File not found): The specified file does not exist. - Error 76 (Path not found): The specified path does not exist.

Performance Considerations

• FreeFile is a very fast operation - no overhead in calling it
• Always store the result in a variable for later use with Close
• Don't call FreeFile repeatedly in tight loops - get the number once and reuse it
• Consider using the high range (256-511) for system or library files to avoid conflicts with user code
• File operations themselves (Open, Close, Read, Write) are much slower than FreeFile

Best Practices

1. Always use FreeFile instead of hard-coding file numbers
2. Store the file number in a variable so you can close the file later
3. Close files promptly when done to release the file number
4. Use error handling to ensure files are closed even if an error occurs
5. Use high range (1) for system/library code to avoid conflicts
6. Open and close files in pairs - every Open should have a corresponding Close
7. Don't assume file numbers - always get a fresh number with FreeFile

Comparison with Other Approaches

FreeFile vs Hard-Coded Numbers

' Bad - Hard-coded file number
Open "data.txt" For Input As #1
' What if file #1 is already open?

' Good - Use FreeFile
Dim fileNum As Integer
fileNum = FreeFile
Open "data.txt" For Input As #fileNum

FreeFile vs FileSystemObject

' FreeFile approach - built-in, fast, simple
Dim fileNum As Integer
fileNum = FreeFile
Open "data.txt" For Input As #fileNum
' ...
Close #fileNum

' FileSystemObject - more features, requires reference
Dim fso As New FileSystemObject
Dim ts As TextStream
Set ts = fso.OpenTextFile("data.txt", ForReading)
' ...
ts.Close
Set ts = Nothing
Set fso = Nothing

Limitations

• Maximum of 255 files in the default range (1-255)
• Maximum of 256 files in the high range (256-511)
• Total maximum of 511 files open simultaneously
• File numbers are process-specific (not thread-safe in modern contexts)
• No built-in file locking mechanism
• Traditional file I/O is slower than modern streaming APIs

Range Selection

When to use different ranges:

• Range 0 (1-255): Default for application code, user files
• Range 1 (256-511): System files, library code, background operations

' Application uses default range
Dim userFile As Integer
userFile = FreeFile(0)  ' or just FreeFile

' Library uses high range to avoid conflicts
Dim sysFile As Integer
sysFile = FreeFile(1)

Related Functions

• Open - Opens a file for reading or writing
• Close - Closes an open file
• EOF - Tests for end-of-file
• LOF - Returns the length of an open file
• FileAttr - Returns file mode or file handle
• Seek - Sets or returns the current file position
• Input - Reads data from a sequential file
• Print - Writes data to a sequential file
• Get - Reads data from a binary or random file
• Put - Writes data to a binary or random file