File System - Read from file |
Declaration
|
<AMFILESYSTEM ACTIVITY="read_file" FILE="text" RESULTVARIABLE="text" ENCODING="text (options)" MAXBYTES="number" POSITION="number" NEWPOSITIONVARIABLE="text" BYTESVARIABLE="text" REPLACENULL="YES/NO" REPLACE="text" /> |
Description
Retrieves textual data from a file (usually a text file) and places the data in a variable so it may be read in subsequent task steps or employed in a repetitive process using appropriate Loop activities.
Practical Usage
Commonly used to read data from a text file onto a variable. The data can then be used later in the task by simply specifying the variable name in the properties of subsequent steps.
Parameters
General
|
Property |
Type |
Required |
Default |
Markup |
Description |
|
File |
Text |
Yes |
(Empty) |
|
The file (normally a .txt file) containing the text that should be read. This can be an absolute path (full path and file name) or a file name only (requires use of the Change folder activity). |
|
Populate variable with data |
Text |
Yes |
(Empty) |
RESULTVARIABLE="theVarName" |
The name of the variable to populate with text contents of the file. The variable must be created in a previous step using the Create variable activity. |
advanced
|
Property |
Type |
Required |
Default |
Markup |
Description |
|
Encoding |
Text (options) |
No |
ANSI |
ENCODING="Unicode" |
The character encoding method to use when reading the file into a variable. The available options are:
|
|
Populate variable with total characters read |
Text |
No |
(Empty) |
BYTESVARIABLE="bytesvar" |
The name of the variable to populate with the total number of characters (bytes) read. |
|
Read file partially |
If enabled, only a portion of the file will be read. The default behavior is to read the entire file. However, you can set this activity to read only a section of the file if it is particularly large in size. This is a visual mode parameter only used during design time, therefore, contains no markup. |
||||
|
Read from character position |
Number |
No |
(Empty) |
POSITION="34" |
The character position in the text file that this activity should start reading from. Using this parameter along with the Number of characters to read parameter, you can read a particularly large file portions at a time. This also limits the amount of system memory used, thus speeding up execution. This parameter is available only if the Read file partially parameter is enabled. |
|
Number of characters to read |
Number |
No |
(Empty) |
MAXBYTES="7777" |
The maximum number of bytes that should be read from the file starting from the position entered in the Read from character position parameter. This parameter is important because it prevents Automate from taking up a virtually unlimited amount of system memory depending on the size of the file. Text beyond this amount of space is truncated. This parameter is available only if the Read file partially parameter is enabled. |
|
Populate variable with new position in file. |
Number |
No |
(Empty) |
NEWPOSITIONVARIABLE="position" |
The name of the variable to populate with the new position in the file. Use this value as a starting point when retrieving the next section of data in a large file. This parameter is available only if the Read file partially parameter is enabled. This parameter is available only if the Read file partially parameter is enabled. |
|
Replace Null (0x00) character with |
Text |
No |
(Empty) |
REPLACE="text" |
A string may contain NULL (0x00) characters. In some programming languages, notably C, null characters are used to mark the end of a character string. In database or spreadsheet applications, null characters are often used as padding and are displayed as spaces. Therefore, problems may arise when reading a file that contains null characters. If this is the case, you can use this parameter to replace a null character with another character (i.e. a space) to remedy the problem. |
Examples
- The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
- Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.
Example 1
This sample task reads data from "C:\Temp\monthlyreport.txt" starting at position 120 and reading 2360 bytes. The variable named "datavar" is populated with the text. The variable "bytesvar" is populated with the with the number of bytes read. And the variable named "positionvar" is populated with the new position in the file after reading. The last step of the task writes the variable contents to a new file.
<AMVARIABLE NAME="datavar" VALUE="" />
<AMVARIABLE NAME="bytesvar" VALUE="" />
<AMVARIABLE NAME="positionvar" VALUE="" />
<AMFILESYSTEM ACTIVITY="read_file" FILE="C:\Temp\monthlyreport.txt" RESULTVARIABLE="datavar" MAXBYTES="2360" POSITION="120" NEWPOSITIONVARIABLE="bytesvar" />
<AMFILESYSTEM ACTIVITY="write_file" FILE="c:\temp\statusfile.txt">File contents - %datavar%Number of bytes read - %bytesvar%Current position in file - %positionvar%</AMFILESYSTEM>Example 2
This task writes contents to C:\Temp\TestFile.txt using the Write to File action and reads the contents into a variable using a Read from File action.
<AMVARIABLE NAME="TheData" VALUE="" />
<AMFILESYSTEM ACTIVITY="write_file" FILE="C:\Temp\TestFile.txt" DATA="I love Automate!!!" APPEND="no" />
<AMFILESYSTEM ACTIVITY="read_file" FILE="C:\Temp\TestFile.txt" RESULTVARIABLE="TheData" />
<AMSHOWDIALOG>Contents of text file: %TheData%</AMSHOWDIALOG>