Description
The WriteToTextFile method opens a text file using the specified character encoding and writes text to it either appending to or replacing the current contents. After the data has been written, the file is closed automatically.
Declaration
aqFile.WriteToTextFile(Path, String, TextCodingType, OverwriteOrCreate)
| Path | [in] | Required | String | |
| String | [in] | Required | String | |
| TextCodingType | [in] | Required | Integer | |
| OverwriteOrCreate | [in] | Optional | Boolean | Default value: False |
| Result | Boolean | |||
Applies To
The method is applied to the following object:
Parameters
The method has the following parameters:
Path
The fully-qualified path to the file.
String
The text to be written to the file.
TextCodingType
One of the following constants that specify the file’s character encoding:
| Constant | Value | Description |
|---|---|---|
| aqFile.ctANSI | 20 | ANSI |
| aqFile.ctUnicode | 21 | Unicode (UTF-16) |
| aqFile.ctUTF8 | 22 | UTF8 |
OverwriteOrCreate
Specifies whether or not the method will create a new file in place of existing or non-existent files. The following table summarizes possible combinations of the parameter value and file operations:
| OverwriteOrCreate | ||
|---|---|---|
| False (Default) | True | |
| The file does not exist | Does not create a file and returns False. | Creates a file with the specified text. |
| The file already exists | Appends text at the end of the file. | Overwrites file contents with the new text. |
Result Value
True if the data has been written successfully, and False if an error has occurred (for example, if the specified file does not exist and OverwriteOrCreate is False).
Remarks
Since the aqFile.WriteToTextFile method opens and closes the file automatically, it is better suited for writing text to the file at once in one turn. If you want to write text to the file in several steps, it is recommended to open the file as a text stream using the aqFile.OpenTextFile method and use the resulting aqTextFile object to write the data. This approach provides a better file I/O performance than when calling WriteToTextFile several times in a row.
For example, instead of:
JavaScript, JScript
// This code opens and closes the file 3 times - once per each WriteToTextFile method call
aqFile.WriteToTextFile("C:\\MyFile.txt", "one ", aqFile.ctANSI, true);
aqFile.WriteToTextFile("C:\\MyFile.txt", "two ", aqFile.ctANSI);
aqFile.WriteToTextFile("C:\\MyFile.txt", "three", aqFile.ctANSI);
Python
# This code opens and closes the file 3 times - once per each WriteToTextFile method call
aqFile.WriteToTextFile("C:\\MyFile.txt", "one ", aqFile.ctANSI, True)
aqFile.WriteToTextFile("C:\\MyFile.txt", "two ", aqFile.ctANSI)
aqFile.WriteToTextFile("C:\\MyFile.txt", "three", aqFile.ctANSI)VBScript
' This code opens and closes the file 3 times - once per each WriteToTextFile method call
Call aqFile.WriteToTextFile("C:\MyFile.txt", "one ", aqFile.ctANSI, True)
Call aqFile.WriteToTextFile("C:\MyFile.txt", "two ", aqFile.ctANSI)
Call aqFile.WriteToTextFile("C:\MyFile.txt", "three", aqFile.ctANSI)
DelphiScript
// This code opens and closes the file 3 times - once per each WriteToTextFile method call
aqFile.WriteToTextFile('C:\MyFile.txt', 'one ', aqFile.ctANSI, true);
aqFile.WriteToTextFile('C:\MyFile.txt', 'two ', aqFile.ctANSI);
aqFile.WriteToTextFile('C:\MyFile.txt', 'three', aqFile.ctANSI);
C++Script, C#Script
// This code opens and closes the file 3 times - once per each WriteToTextFile method call
aqFile["WriteToTextFile"]("C:\\MyFile.txt", "one ", aqFile["ctANSI"], true);
aqFile["WriteToTextFile"]("C:\\MyFile.txt", "two ", aqFile["ctANSI"]);
aqFile["WriteToTextFile"]("C:\\MyFile.txt", "three", aqFile["ctANSI"]);
use code as follows:
JavaScript, JScript
// This code opens and closes the file only once
var oFile = aqFile.OpenTextFile("C:\\MyFile.txt", aqFile.faWrite, aqFile.ctANSI, true);
oFile.Write("one ");
oFile.Write("two ");
oFile.Write("three");
oFile.Close();
Python
# This code opens and closes the file only once
oFile = aqFile.OpenTextFile("C:\\MyFile.txt", aqFile.faWrite, aqFile.ctANSI, True)
oFile.Write("one ")
oFile.Write("two ")
oFile.Write("three")
oFile.Close()VBScript
' This code opens and closes the file only once
Dim oFile
Set oFile = aqFile.OpenTextFile("C:\MyFile.txt", aqFile.faWrite, aqFile.ctANSI, True)
Call oFile.Write("one ")
Call oFile.Write("two ")
Call oFile.Write("three")
oFile.Close
DelphiScript
// This code opens and closes the file only once
procedure Test;
var oFile;
begin
oFile := aqFile.OpenTextFile('C:\MyFile.txt', aqFile.faWrite, aqFile.ctANSI, true);
oFile.Write('one ');
oFile.Write('two ');
oFile.Write('three');
oFile.Close;
end;
C++Script, C#Script
// This code opens and closes the file only once
var oFile = aqFile["OpenTextFile"]("C:\\MyFile.txt", aqFile["faWrite"], aqFile["ctANSI"], true);
oFile["Write"]("one ");
oFile["Write"]("two ");
oFile["Write"]("three");
oFile["Close"]();
Example
The example below demonstrates how you can create a file and write text to it using the aqFile object.
JavaScript, JScript
function CreatingAndWritingToTextFile()
{
if (aqFile.Create("C:\\MyFiles\\DemoFile.txt") == 0)
{
aqFile.WriteToTextFile("C:\\MyFiles\\DemoFile.txt", "Hello!", aqFile.ctUTF8);
Log.Message("The file is created and the specified text is written to it successfully.");
}
else
{
Log.Error("The file was not created.");
}
}
Python
def CreatingAndWritingToTextFile():
if aqFile.Create("C:\\MyFiles\\DemoFile.txt") == 0:
aqFile.WriteToTextFile("C:\\MyFiles\\DemoFile.txt", "Hello!", aqFile.ctUTF8)
Log.Message("The file is created and the specified text is written to it successfully.")
else:
Log.Error("The file was not created.")VBScript
Sub CreatingAndWritingToTextFile
If (aqFile.Create("C:\MyFiles\DemoFile.txt") = 0) Then
Call aqFile.WriteToTextFile("C:\MyFiles\DemoFile.txt", "Hello!", aqFile.ctUTF8)
Call Log.Message("The file is created and the specified text is written to it successfully.")
else
Call Log.Error("The file was not created.")
End If
End Sub
DelphiScript
function CreatingAndWritingToTextFile;
begin
if (aqFile.Create('C:\\MyFiles\\DemoFile.txt') = 0) then
begin
aqFile.WriteToTextFile('C:\\MyFiles\\DemoFile.txt', 'Hello!', aqFile.ctUTF8);
Log.Message('The file is created and the specified text is written to it successfully.');
end
else
begin
Log.Error('The file was not created.');
end;
end;
C++Script, C#Script
function CreatingAndWritingToTextFile()
{
if (aqFile["Create"]("C:\\MyFiles\\DemoFile.txt") == 0)
{
aqFile["WriteToTextFile"]("C:\\MyFiles\\DemoFile.txt", "Hello!", aqFile.ctUTF8);
Log["Message"]("The file is created and the specified text is written to it successfully.");
}
else
{
Log["Error"]("The file was not created.");
}
}
See Also
Working With Files From Scripts
aqFile.ReadWholeTextFile Method
aqFile.OpenTextFile Method
WriteToTextFile Method