READ_DATA_FROM_FILE:Read text from File

This feature in GPP2 allows the program to read in text data from any file, and store it, line by line, in an array of strings. Then, this data can be used inside the EX2 program like any other string.

For instance, one use of the new feature has been to read in XY location correction data for EDM electrodes. Each line was formatted like "T10/X0.123/Y-0.001" and contained the correction data for a given electrode (T10). Inside the EX2 program, each line was split into 3 parts using STR_SPLIT (with "/" as the splitting string) and the numbers were converted to numeric data using the STR_NUM function. In the output file, these numbers were used to modify the EDM electrode location.

READ_DATA_FROM_FILE array-var-name <str-expr> ;

The array variable must be defined and of format CHARACTER (array of strings). It should have enough entries to contain ALL the data in the file.

The string expression gives the name of the text file to be read. Any string expression may be used. It may contain the full path of the file, or just the file name. If the full path is NOT provided, then GPP2 will look for this text file in the OUTPUT folder of that run.

A special convention allows using "*" at the beginning of the file name to represent the PP name (like in the INIT_FILE command).

Example

READ_DATA_FROM_FILE MyArray "C:\Temp\data.txt"; // full path

READ_DATA_FROM_FILE MyArray "data.txt"; // assume output folder

READ_DATA_FROM_FILE MyArray "*.dat"; // '*' replaced with PP name

Unlike the INIT_FILE command, which can only be used in the declarative part of the EX2 program, the READ_DATA_FROM_FILE command can be used anywhere in the program, which makes its use much more flexible. Furthermore, the text file being read can be of any format and contain any text whatsoever. Note that UNICODE or other multi-byte character sets are not supported inside GPP2.

Special note to German PP developers who wish to use the comma (',') as the decimal point separator: reading in numerical data with ',' as the decimal point requires additional processing, since STR_NUM will only recognize a regular decimal point ('.'). Therefore, before using STR_NUM, be sure to replace the ',' with a '.', using STR_REPLACE. For instance:

MyNum = STR_NUM(STR_REPLACE(MyString, "," , "."));

Run-time warnings and errors:

- If the file cannot be found, a run-time error is issued, and execution stops.

- If the array is too small to store all lines, a run-time error is generated, and execution is stopped.