Miscellaneous

PROPERTY GDL ADD-ON

The purpose of this add-on is to make an ArchiCAD property database accessible from GDL scripts. You can open database tables and query their contents, just like you would do it with SQL. You can query single records and multiple records (lists). Note that you cannot modify the database, and you cannot append records to it.

For the detailed description of the property database please refer to the “ArchiCAD 10 Calculation Guide” in the Help menu.

OPEN

Syntax: OPEN ("PROP", "database set name", ["database files"])

Parameters: <database set name> is an arbitrary name that will identify a set of database files in subsequent OPEN calls.

<database files> is a list of text files that are part of the property database. This parameter is optional, if you have previously assigned a <database set name> to the files you would like to read. The order of the files is fixed: <key file>, <component file>, <descriptor file>, <unit file>. You don’t need to give full paths, because ArchiCAD will look up these files for you in the active libraries. If you use long filenames, put them between quotes (‘ or ").

Return value: channel number

Opens a communication channel to the given database files. The content of the database files are read into memory for faster access. As long as it is open modifications to the property database will not be accessible from this add-on. This is usually not a problem though.

Examples:

1.

channel = OPEN ("PROP", "sample", "’AC 8_KEY.txt’, ’AC 8_COMP.txt’, ‘AC 8_DESC.txt’, ‘AC 8_UNIT.txt’")

This opens a database that consists of the files above (those are the files of the ArchiCAD 7.0 Property database), and names it "sample". Note that inside the third parameter you must use a different quotation character (you can use " and ‘).

2.

channel = OPEN ("PROP", "sample", "")

This command can be issued after explicitly opening the database files (like in example 1), but before closing it. This lets you use the explicit command at one place in the Master_GDL script, and use the shorter version later.

CLOSE

Syntax: CLOSE (channel_number)

Return value: none

Closes the previously opened communication channel.

Miscellaneous

INPUT

Syntax: INPUT (channel_number, "query type", "field list", variable1[, …])

Parameters:

<channel number> is a valid communication channel number given by a previous OPEN command. <query type> specifies the query you would like to execute. The add-on understands the following keywords:

Single-record queries:

KEY, <keycode> – query the record from the key database where <keycode> is the value of the keycode attribute. Valid fields: KEYCODE, KEYNAME

UNIT, <unitcode> – query the record from the unit database where <unitcode> is the value of the unit code attribute. Valid fields: UNITCODE, UNITNAME, UNITFORMATSTR

COMP, <keycode>, <code> – query the record from the unit database where <keycode> is the key code attribute value, and <code> is the component code attribute value. Valid fields: KEYCODE, KEYNAME, CODE, NAME, QUANTITY, QUANTITYSTR, UNITCODE, UNITNAME, UNITFORMATSTR

DESC, <keycode>, <code> – query the record from the unit database where <keycode> is the key code attribute value, and <code> is the descriptor code attribute value. Valid fields: KEYCODE, KEYNAME, CODE, NAME, NUMOFLINES, FULLNAME

Listing queries:

KEYLIST – list all records in the key database. Valid fields: KEYCODE, KEYNAME

UNITLIST – list all records in the unit database. Valid fields: UNITCODE, UNITNAME, UNITFORMATSTR

COMPLIST[, <keycode>] – list all records in the component database, or if <keycode> is given, then only those records are listed whose keycode equals <keycode>. Valid fields: KEYCODE, KEYNAME, CODE, NAME, QUANTITY, QUANTITYSTR, UNITCODE, UNITNAME, UNITFORMATSTR

DESCLIST[, keycode] – list all records in the descriptor database, or if <keycode> is given, then only those records are listed whose keycode equals <keycode>. Valid fields: KEYCODE, KEYNAME, CODE, NAME, NUMOFLINES, FULLNAME

COMPDESCLIST[, <keycode>] – list all records in the component and the descriptor database, or if <keycode> is given, then only those records are listed whose keycode equals <keycode>. Valid fields: ISCOMP, KEYCODE, KEYNAME, CODE, NAME, QUANTITY, QUANTITYSTR, UNITCODE, UNITNAME, UNITFORMATSTR, NUMOFLINES, FULLNAME

Use this query with care! If either field is not valid in a database (eg. FULLNAME in the component database) it will be simply left out from the resulting list (you should be aware of that).

<field list> lists the database attributes whose values you would like to see in the output. If the output is a list, it will be sorted in the order of the fields listed here.

The following fields can be used:

KEYCODE – key code attribute. Type: string. Usable in queries: KEY, COMP, DESC, KEYLIST, COMPLIST, DESCLIST, COMPDESCLIST

Miscellaneous

KEYNAME – key name attribute. Type: string. Usable in queries: KEY, COMP, DESC, KEYLIST, COMPLIST, DESCLIST, COMPDESCLIST.

UNITCODE – unit code attribute. Type: string. Usable in queries: UNIT, COMP, UNITLIST, COMPLIST, COMPDESCLIST

UNITNAME – unit name attribute. Type: string. Usable in queries: UNIT, COMP, UNITLIST, COMPLIST, COMPDESCLIST

UNITFORMATSTR – GDL format string of the unit. Type: string. Usable in queries: UNIT, COMP, UNITLIST, COMPLIST, COMPDESCLIST.

CODE – component or descriptor code attribute (depends on the query). Type: string. Usable in queries: COMP, DESC, COMPLIST, DESCLIST, COMPDESCLIST.

NAME – name of component or the first line of a descriptor record. Type: string. Usable in queries: COMP, DESC, COMPLIST, DESCLIST, COMPDESCLIST.

QUANTITY – quantity of a component as a number (for calculations). Type: number. Usable in queries: COMP, COMPLIST, COMPDESCLIST.

QUANTITYSTR – quantity of a component in string format. Type: string. Usable in queries: COMP, COMPLIST, COMPDESCLIST.

NUMOFLINES – number of lines in a descriptor record. Type: number. Usable in queries: DESC, DESCLIST. FULLNAME – the whole descriptor record. Type: string(s). Usable in queries: DESC, DESCLIST.

ISCOMP – tells you whether the next record is a component or a descriptor. Type: number (1 if component, 0 if descriptor). Usable in queries: COMPDESCLIST

<variables> will hold the result of the query upon completion. You can list several variables if you know exactly how many you need (eg. with single queries) or you can specify a dynamic array. The records are listed sequentially.

Examples:

1.

INPUT (channel, "KEY, 001", "KEYNAME", keyname)

This is a simple query: the name of the key with ‘001’ code is put into the keyname variable.

2.

INPUT (channel, "DESC, 004, 10", "NUMOFLINES, FULLNAME", desc_txt)

The descriptor record with keycode ‘004’ and code ‘10’ is processed, the number of lines of the description text and the text itself is put into the desc_txt array. The result is:

desc_txt[1] = <numoflines> (number) desc_txt[2] = <first row of description> (string)

…

desc_txt[<numoflines+1>] = <last row of description

3.

INPUT (channel, "COMPLIST", "NAME, KEYNAME, QUANTITY", comp_list)

Miscellaneous

Create a component list, sort it by the name field, then by the keyname and finally by the quantity field and put it into the comp_list array. The result is:

complist[1] = <name1> (string) complist[2] = <keyname1> (string) complist[3] = <quantity1> (number) complist[4] = <name2> (string)

... etc.

4.

INPUT (channel, "COMPDESCLIST, 005", "ISCOMP, KEYNAME, NAME, QUANTITY", x_list)

Creates a common component and descriptor list, which means that records from both tables are listed where <keycode> is ‘005’. The output is:

x_list[1] = 0 (number, 0 –> it is descriptor)

x_list[2] = <name1> (string –> descriptors do not have <keyname> field, so it is left out) x_list[3] = 0 (number, descriptors do not have quantity field)

…

x_list[(n*2)-1] = 1 (number –> there were n-1 descriptors listed, now come the components) x_list[n*2] = <keyname_n> (string)

… etc.