Miscellaneous

Parameter Naming Convention

Because of the subtype hierarchy, the child library parts automatically inherit all parameters of the parent. (Read more about subtypes and parameter in the ArchiCAD User Guide). Parameters are identified by their name, so inherited and original parameters can have the same name. It is the responsibility of the library author to avoid conflicts by using descriptive parameter names†prefixed with abbreviated library part names.

For handler parameters and user-defined parameters, Graphisoft has introduced a parameter naming convention in its libraries. Note: Handlers add extra functionality to library parts (e.g doors and windows cut holes in walls).

Parameters names with the prefix ac_ are reserved for special parameters associated with ArchiCAD handlers (e.g. ac_corner_window). Check the standard ArchiCAD Library subtype templates for the complete list.

Standard Graphisoft parameter names are marked with the gs_ prefix (e.g. gs_frame_pen). Please check the AC library parts for reference. Use these parameters in your GDL scripts to ensure full compatibility with Graphisoft libraries.

FM_ is reserved for ArchiFM (e.g. FM_Type) and HVAC_ is assigned to HVAC for ArchiCAD parameters (e.g. HVAC_Manufacturer).

GDL DATA I/O ADD-ON

The “GDL Data In/Out” Add-On allows you to access a simple kind of database by using GDL commands. Otherwise this Add-On is similar to the “Text GDL In/Out” Add-On.

Description of Database

The database is a text file in which the records are stored in separate lines. The database can be queried and modified based on a single key. The key and the other items are separated by a character (specified in the OPEN command).

The length of the lines does not need to be the same and even the number of columns in the records may be different. If a database is open for writing then there should be enough space beside the database file for duplicating the whole file.

Opening and closing a database may be time consuming, so consecutive closing and openning of a adatabase should be avoided. Large databases (with more than some hundred thousand records) should be ordered by the key values.

A database can be opened, queried, modified and closed by this Add-On using the OPEN, INPUT, OUTPUT and CLOSE GDL commands.

Opening a Database

channel = OPEN (filter, filename, paramstring)

filter: the internal name of the Add-On, in this case "DATA" filename: the name of the database file to be opened

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

Opens the database. If the database file is to be opened for modification and the file does not exist, it creates a new file. If the database file is to be opened for reading and the file does not exist, an error message is displayed.

Its return value is a positive integer that will identify the specific database. This value will be the database's future reference number. If the database is opened before open command, it will generate a channel number only.

ArchiCAD 11 GDL Reference Guide

295

Miscellaneous

The paramstring may contain the following:

SEPARATOR: after the keyword between single quotation marks ('') you can define a character that you want to use in your text file (both in case of writing and reading) for the separation of columns. A special case is the tabulator character ('\t').

MODE: after the keyword the mode of opening has to follow. There are three modes of opening:

•RO (read only)

•WA (read, modify)

•WO (read, modify) Empties the database if exists.

DIALOG: the 'filename' parameter is handling as a file-identifier, otherwise it is a full-path-name. The file-identifier is a simple string, which will be corresponded to an existing file by the Add-On during a standard 'Open/Save as' dialog. These correspodence is stored by the Add-On and do not ask again except the file is not available. If the open-mode is read only, the Add-On put an Open dialog to select an existing document. Otherwise the Add-On put an alert-dialog to select between the 'Create' and 'Browse' option:

•Browse: search an existing data-file (Open dialog)

•Create: create a new data-file (Save as Dialog).

Always put a comma (,) between SEPARATOR, MODE and DIALOG.

LIBRARY: If the LIBRARY keyword is present in the parameter string, the data file has to be in the loaded library.

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.

Example:

ch1 = OPEN ("DATA", "file1", "SEPARATOR=';', MODE = RO", DIALOG)

ch2 = OPEN ("DATA", "file2", "")

ch3 = OPEN ("DATA", "newfile", "SEPARATOR = '\t', MODE = WA")

296	ArchiCAD 11 GDL Reference Guide

Miscellaneous

Reading Values from Database

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

recordID: key value (numeric or string)

fieldID: the column number in the given record (the smallest number : 1 refers to the item after the key value)

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

Queries the database based on the key value.

If it finds the record then it reads items from the record starting from the given column and puts the read values into the parameters in sequence.

In the parameter list there has to be at least one value. 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.

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.

If it finds no record it returns (-1).

Example:

nr = INPUT (ch1, "key1", 1, v1, v2, v3)

!input of three values from the first column

!(after the key) of the record containing the

!key "key1"

PRINT nr, v1, v2, v3

ArchiCAD 11 GDL Reference Guide

297

Miscellaneous

Writing Values into Database

OUTPUT channel, recordID, fieldID, expr1 [, expr2, ...] recordID: key value (numeric or string)

fieldID: flag: specify 0 (or <= 0) to delete a record, specify 1 (or > 0) to create or modify a record

expr1,...: new item values of the found or new record in case of deletion these values are ignored

In case of record creation or modification it sets the record belonging to the given key value. The record will contain the given values in the same sequence as the appear in the command. The values can be of numeric or string type. There has to be at least one expression.

In case of deletion the record belonging to the given key value is removed from the database. The expression values are ignored, however at least one should be specified.

Example:

string = "Date: 19.01.1996" a = 1.5

OUTPUT ch2, "keyA", 1, "New record" OUTPUT ch2, "keyA", 1, "Modified record"

OUTPUT ch2, "keyA", 0, 0 ! deletes the record

OUTPUT ch2, "keyB", 1, a, string

Closing Database

CLOSE channel

channel: channel value

Closes the database identified by the channel value.

298	ArchiCAD 11 GDL Reference Guide