GDL Text I/O Add-On

GDL Text I/O

The GDL Text In/Out Add-On allows you to open external text files for reading/writing
and to manipulate them by putting/getting values from/to GDL scripts.

This Add-On interprets the strings on the parameter list of the OPEN, INPUT, OUTPUT commands from the GDL script.

The created files are placed in a subfolder of the application data folder if it is given by a relative path.
The folder can contain subfolders where the extension will look for existing files. It can read and write TEXT type files.

Opening File

channel = OPEN (filter, filename, paramstring)


Opens the file. If the file into which you want to write doesn’t exist, it creates the file.
If a file to be read doesn’t exist, an error message is displayed.

Its return value is a positive integer that will identify the specific file. This value will be the file’s future reference number.

filter: the internal name of the Add-On, in this case “TEXT”

filename: the name of the file to be opened

paramstring: add-on specific parameter, contains separator characters and file opening mode parameters

The paramstring may contain the following:

SEPARATOR: 
after the keyword between apostrophes (”) you can assign a character to use in the text file
(for both writing and reading) to separate columns.
Special cases are the tabulator (‘\t’) and the new row (‘\n’) characters.
MODE: 
the mode of opening has to follow this keyword. There are only three modes of opening:
  • RO (read only)
  • WA (write only, append at the end of the file)
  • WO (write only, overwrite) the data previously stored in the
    file will be lost!

A file cannot be open for reading and writing at the same time.

DIALOG: 
If this keyword is present, a dialog box will appear in which you can enter a file name.
FULLPATH: 
If this keyword is present, the file name will be interpreted as a full path name.
LIBRARY: 
If this keyword is present, the data file must be in the loaded library.
Opening data file from the loaded library for reading is possible from all scripts, but writing is only enabled in the parameter, user interface and property scripts.
Available options for files outside of the loaded libraries:
  • Writing from 2D and 3D scripts are enabled
  • Reading data from external files is regarded as non-determinictic actions, see Background Conversion.

Always put a comma (,) between the keywords.

NEWLINE: 
definition of new line character(s). Possible values:
  • CR (Carriage return, 0x0D)
  • LF (Line feed, 0x0A)
  • CRLF (Carriage return + Line feed, 0x0D0x0A)

For Windows-like line ends use “NEWLINE = CRLF”

If you use keywords that don’t exist, if the separator characters given are wrong or if there is nothing in the parameter string,
the extension will use the default settings: "SEPARATOR = 't', MODE = RO, NEWLINE = LF"

Example:

ch1 = OPEN ("TEXT", "file1", "SEPARATOR = ';', MODE = RO")
ch2 = OPEN ("TEXT", "file2", "")
ch3 = OPEN ("TEXT", "file3", "SEPARATOR = 'n', MODE = WO")

Reading Values

INPUT (channel, recordID, fieldID, var1 [, var2, ...])


It reads as many values from the given starting position of the file identified by the channel value as many parameters are given.
In the parameter list there has to be at least one value. The function puts the read values into the parameters in sequence.
The values can be of numeric or string type independently of the parameter type defined for them.

The return value is the number of successfully read values, in case of end of file (-1).

Both the row and the column numbers have to be positive integers, otherwise you will get an error message.

If the row or column numbers are incorrect, the input will not be carried out. (n = 0)


If the row and the column can be identified, as many values shall be input from the given starting position as many parameters are given,
or if there are more parameters than values, the parameters without corresponding values will be set to zero.

In case of empty columns (i.e. if there is nothing between the separator characters) the parameters will be set to zero.

channel: channel value, used to identify the connection.

recordID: the row number (numeric or string)

fieldID: the column number in the given row

var1, ...: variables to receive the read record items

Example:

nr = INPUT (ch1, 1, 1, v1, v2, v3) ! input of three values
! from the firstcolumn of the first row
PRINT nr, v1, v2, v3

Writing Values

OUTPUT channel, recordID, fieldID, expr1 [, expr2, ...]


Outputs as many values into the file identified by the channel value from the given position as many expressions are defined.
There has to be at least one expression. The types of the output values are the same as those of the expressions.


In case of a text extension, the OUTPUT will either (depending on the mode of opening) overwrite the file
or add to the end of the file the given expressions to consecutive positions using between them the separator characters defined when opening the file.
In this case, the given position is not interpreted.


Modifying data files loaded with the library is only enabled in the parameter, user interface and property scripts.

channel: channel value

recordID: The recordID is used to direct the new rows in the output

If the recordID is positive, the output values will be followed by a new row,
otherwise the last value will be followed by a separator character.

fieldID: no role, its value is not used

expr1: values to output

Example:

string = "Date: 19.01.1996"
a = 1.5
OUTPUT ch2, 1, 0, string ! string followed by a new row
OUTPUT ch2, 0, 0, a, a + 1, a + 2! separator character after a + 2 ! without new row

Closing File

CLOSE channel

Closes the text file identified by the channel value.

channel: channel value

Example:

A GDL object that will simply copy the contents of the “f1”
file both into the “f2” and the “f3” files, but will write all the
values tabulated in “f1” into a separate row in both “f2” and
“f3”.

ch1 = open ("TEXT", "f1", "mode = ro")
ch2 = open ("TEXT", "f2", "separator = 'n', mode = wo")
ch3 = open ("TEXT", "f3", "separator = 'n', mode = wo")
i = 1

1:
    n = input (ch1, i, 1, var1, var2, var3, var4)
    if n <> -1 then
        output ch2, 1, 0, var1, var2, var3, var4
        output ch3, 1, 0, var1, var2, var3, var4
        i = i + 1
        goto 1
    else
        goto "close all"
    endif

"close all":
    close ch1
    close ch2
    close ch3
    end