ajReadFile function
Description
The ajReadFile function imports the content of a file into a defined area in Excel worksheet. It is mainly used for loading data from a text file to Excel for processing.
Syntax
ajReadFile(file_location, [column_separator], [left_enclosure_character], [right_enclosure_character], [begin_at_line], [number_of_lines], [character_set], [skip_empty_row], [run_condition], [run_by_function_point_only])
| Argument Name | Description |
|---|---|
| file_location (required) | Specify the path of the file to be read. |
| column_separator (optional) | Specify that character that is used to split input record into fields. In a CSV file, a comma is usually used. |
| left_enclosure_character (optional) | Specify the left enclosure character. When a Column_separator is used, a field value itself can contain a column separator character. For example, when using a comma-delimited format and with a field containing "Cathy, Chow" as its actual value, the field would be separated into two fields as there is a comma in it. Using an enclosure character in writing and reading operations can solve this problem. If you do not specify anything, the default value will always be an empty string (“”) which means no enclosure character. |
| right_enclosure_character (optional) | Specify the right enclosure character. If you do not specify anything, the default value will always be an empty string (“”) which means no enclosure character. |
| begin_at_line (optional) | Specify the starting line to begin the extraction of the content of the file. If you do not specify anything, it will start from the beginning. |
| number_of_lines (optional) | Specify the number of lines to be extracted from the file. If you do not specify anything, it will read all the lines starting from Begin_at_line and till the end of the file. |
| character_set (optional) | Specify the character set used when writing the file. Some common character set codes are UTF-8 (ISO 10646 Unicode), GB2312 (Chinese Simplified), Big5 (Chinese Traditional) and us-ascii. If you do not specify anything, the default value is UTF-8. |
| skip_empty_row (optional) | If it equals FALSE, the empty rows will be read from the file. If it equals TRUE, the empty rows will not be read from the file. If you do not specify anything, the default value will always be FALSE. |
| run_condition (optional) | The function will run when the value is TRUE. Otherwise, it will not run. If you do not specify anything, the default value will always be TRUE. |
| run_by_function_point_only (optional) | If it equals FALSE, the function can be executed through ‘Excel Calculation’ (can be either Automatic or Manual, Calculate Now or Calculate Sheet) or Run Function Point. If it equals TRUE, the function can be executed with Run Function Point (AlchemyJ toolbar \ Run Function Point) only. If you do not specify anything, the default value will always be TRUE. |
The function will return:
1) Content type: Contents of the selected file
2) Method: Cell array
Examples
Here are a few examples of ajReadFile function.
Example 1
The file below uses comma as the column separator and round brackets as the left and right enclosure character.
We call ajReadFile without specifying any column separator and enclosure character. The content is read line by line. Each cell contains the whole line.
Example 2
In this example, it reads the same file using ajReadFile but we specify comma as column_separator, ( as left_enclosure_character and ) as right_enclosure_character. ajReadFile properly loads the content in its intended format.
In addition, we set begin_at_line to 2 and the number_of_lines to 3 so that only lines 2 to 4 are loaded.
