Miscellaneous

GDL TEXT I/O ADD-ON

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.

It assumes that a folder named “ArchiCAD Data Folder” exists beside ArchiCAD for user defined files. (The name of this folder is defined in the Add-On resource fork, therefore it can be localized.) If a folder with that name doesn't exist, the Add-On will create one. 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)

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

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. The paramstring can contain the following:

SEPARATOR: after the keyword between single quotation marks (‘’) 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.

Always put a comma (,) between the keywords.

If you use keywords that don’t exist, if the separator characters given are wrong or there is nothing in the parameter string, the extension uses the default settings: SEPARATOR = ‘\t’, MODE=RO.

ArchiCAD 11 GDL Reference Guide

303

Miscellaneous

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, ...])
channel: channel value		or string)
recordID: the row number (numeric
fieldID: the column	number in the	given	row
var1,...: variables	to receive the read		record items

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.

Example:

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

PRINT nr, v1, v2, v3

304	ArchiCAD 11 GDL Reference Guide

Miscellaneous

Writing Values

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

recordID: if positive, the output values will be followed by a new row fieldID: no role, its value is not used

expr1: values to output

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.

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.

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

ArchiCAD 11 GDL Reference Guide

305

Miscellaneous

Closing File

CLOSE channel

channel: channel value

Closes the data base identified by the 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 2 endif 2:

close ch1 close ch2 close ch3 end

306	ArchiCAD 11 GDL Reference Guide