The easiest way to find yourself in a programming environment for GDL is to create a new object in ARCHICAD (File/Libraries and Object/New Object…), or to open a placed, existing and selected object (File/Libraries and Object/Open Object…)

The GDL editor window is the best place to start your explorations of GDL programming:


The codes will be entered into the script windows: Master, 2D, 3D, Properties, Parameter, Interface, Forward Migration, Backward Migration.
Every script runs in its corresponding ARCHICAD context (floor plan, 3D window, Listing, etc.).
Master script is special: it runs before every other script type, so it is always evaluated first. Variables and calculations declared here are available for every other script automatically. This is very convenient in many cases (otherwise redundant codes can be reduced to one Master script copy), but on the other hand, there is a big temptation to be lazy. This script runs all the time, so make sure you only put calculation and declarations here which are absolutely necessary for multiple scripts. Don’t make your object slow just because of laziness to think and plan ahead.

As most programming languages, GDL has its own syntax rules and functions. To create perfectly working objects, one must follow these rules, and consider following our additional recommendations as well.

Some basic syntax rules:

• GDL is (unfortunately) case insensitive, except some string functions
• variable or parameter name can only consist of the small/capital letters of the English alphabet, the character _, and Arabic numbers
• variable or parameter name can not start with numbers
• built-in functions must be called with the exact parameter order
• commands must be used with the exact parameter order
• indentation is not forced, but highly recommended
• there are some reserved words already taken by a function, do not use them as variable or macro names

This information is enough to start your first script, but since we have a lot of material about the subject in detail, please, read on:
GDL Manual: GDL Syntax chapter
Style Guide Naming Conventions chapter.

Disregarding a syntax rule results in the form of a GDL error.

To check if your script is correct in syntax and function, always use the “Check script” option of the GDL editor before saving (button on top of the script window). Most cases it will tell you exactly what and where is wrong with the script. Fix it, any move on. Just don’t panic, ever.
To read more about GDL Warnings, check out the Basic Technical Standards page.

But how to write code?
Basically, one only has to type statements using commands, variables, parameters and arithmetical signs into lines. If a statement is too long to be contained within one line (character limit is 255, but we recommend stopping around 80), another GDL warning appears when checking the script or trying to save your work.

Let’s take a look at basic GDL programming elements:

Commands
A command is usually a very specific way of telling a computer (a program) what to do next. It is not different in GDL: using commands you can use predefined geometric forms and functions. A command usually has a restricted keyword in front (the command itself), and one or more input parameters (making most of them flexible):

CIRCLE2 coorX, coorY, radius
! command inputParam1, inputParam2, inputParam3

In GDL, the number of input parameters is always defined (can be flexible, where indicated so), the order of them is always fixed, and the parameters are separated with commas.
Every command has its own syntax (look them up it the GDL Reference Guide).

Keywords
There is a list of words which already have a meaning in GDL syntax, so they should not be used as parameter or variable name in codes.
For the full list, see Keywords in GDL Manual.

Comments
Comments in GDL start with the exclamation mark character (“!”), and not executed during script run.
They can occupy a full line, or be placed after a statement.
Comment lines help you to understand the code better and faster, make it easier to find what you are looking for while bugfixing or developing a new function into an existing object.
More about comments: GDL Style Guide, Writing comments.

Variables
A variable is a named (labeled) storage place in the computer’s memory where the programmer can put data and later retrieve it using the variable’s name as reference. The data stored in the labeled place can be modified in a later statement.
The name serves as a fix identifier in the current script. The variable has to be initialized, but as the name suggests, the value is supposed to change during the script’s run.
In GDL, there are 3 types of variables:

• integer number
• real number
• string (text)

The type of the variable is decided during initialization: the data type you assign to it declares the type for the interpreter automatically.
Examples:

_stVariable = "Hello World!"	! string type
_iVariable = 23			! integer type
_rVariable = 2.33		! real type

Variables can have 2 types of data structure:

• simple types: one variable stores one assigned value
• array types: one variable stores multiple values in a predefined structure. A certain stored value is referenced by the variable’s name and a position index.

Array types come in 2 forms: 1-dimension, and 2-dimension arrays. An array can either declare its size before the actual initialization, or leave it blank, and let the number and index of initialized items to define the size (this is only recommended if the number of values are truly flexible: for dynamic arrays, GDL allocates memory space for safety reasons anyway, and sometimes it’s a lot more than the actual size needed for the used values. Fixed sizes arrays use exactly the amount of memory space they need).

Examples:

! string array with one dimension
dim _stArray[2]
	_stArray[1] = "apple"
	_stArray[2] = "pie"

! integer array with two dimensions: 2 rows and 3 columns
dim _iArray[2][3]
	_iArray[1][1] = 11
	_iArray[1][2] = 12
	_iArray[1][3] = 13
	_iArray[2][1] = 21
	_iArray[2][2] = 22
	_iArray[2][3] = 23

! dynamic string array 
dim _stArrayDinamic[]
	_stArrayDinamic[1] = "one"
	_stArrayDinamic[2] = "two"
	_stArrayDinamic[3] = "three"

In ARCHICAD and GDL, there is an other way of grouping variables:

• local variables: these variables only exist in the actual script, the programmer can choose a suitable name, and passing them between 2 objects is not possible unless they are turned into a parameter of the caller object
• global variables: these variables are created by ARCHICAD, the actual runtime environment controls their value, they have a fixed name, and they are available to be used by any object placed in the plan.

To read more about global variables and their functions, check out the GDL Manual’s Global Variables section.

Constants
Constants have the same structure as variables, but they are supposed to have fixed values. This value is initialized once only, and usually not changing during the run of the script. We use them to keep the code more easy to read and understand. GRAPHISOFT’s GDL Style Guide suggests to use them with full uppercase letters, but the interpreter does not make a difference between uppercase or lowercase, so it’s only a recommendation.

ARCHITECTNAME = "Stanley Tutorial"    ! string type constant
NUM_MAX_LINES = 5   ! integer type constant

A statement with a variable on the left side (_x), an arithmetical operator (=) and a numeric constant (2) on the right side:

_x = 2

A statement with a variable on the left side (_stText), an arithmetical operator (=), and 3 string constants on the right side connected with more arithmetical operators (+):

_stText = "Hello" + " " + "World!"

Built-in functions
GDL includes a lot of built-in functions to spare you a lot of time. Usually these functions would be very complicated to write at home.
When using functions, always remember to keep the exact syntax of the command: the type, number and order of input parameters must match the function’s declarations exactly.
A function usually has one (or more) returned parameter: this is the result of the function.
The most commonly used functions in GDL are:

• Arithmetical functions: abs, ceil, int, sqr, round_int
• Circular functions: sin, cos, tan, acs, asn, atn, pi
• Transcendental functions: exp, lgt, log
• Statistical functions: min, max, rnd

To see the complete list, check out the Functions page of the GDL Manual.

Operators
Programming computations are basically the same as computations in mathematics, with a bit more formality.
Calculating values is like using very shortly defined functions.
An operation gives a result based on the input operands and the function used.

GDL works with 4 operator types:

• Arithmetical: ^ (or **), *, /, MOD (or %), +, –
• Relational: <, <=, <>, >=, >, =
• Boolean: & (and), | (or), @ (exor), not
• Array: [], for indexing

Arithmetical operations work with integers or real numbers, resulting an integer if no real type is involved, otherwise the result is real type.
Addition (+) can be used with string type data: the string input gets concatenated.
Example:

_stStart = "Hello"
_stEnd = "World!"
_stFullSentence = _stStart + " " + _stEnd  ! result is a variable containing: "Hello World!", concatenated

As in mathematics, GDL has precedence of operations, too. This means there is a specific order of statement evaluation in the program.
To force an operation to be evaluated in a statement before its actual precedence, use parenthesis. Operations in parenthesis are always evaluated first:

1. parenthesis
2. power of
3. multiplication, division
4. addition, subtraction
5. relations
6. & (and)
7. | (or)
8. @ (exor)

Example (notice the different outcome):

_x = 5 + 3 * 4 - 2     ! _x = 15
_y = 5 + 3 * (4 - 2)   ! _y = 11

To read about operators, check out the GDL Manual’s Operators section.

Flow control statements
Sometimes you want your program to do a certain thing as long as a certain condition is met. Or you want to skip parts of it depending on the value of a variable. Or you just want to structure it to make it more easy to read and maintain. For all these purposes a programmer can use flow control statements (conditions, loops, jumps).
In GDL, there are many types:

• if – then – (else) – endif: if a condition is met (statement is true between “if” and “then”), the program runs the code between “then” and “endif”. If the condition is not met, but there is an “else” section, the code jumps to that part.
• for – to – next: the code written in the loop is repeated until the iteration variable reaches a declared value. The “next” command increments this variable after the run of every loop, before the next evaluation of the top condition. This statement always starts by comparing the iteration variable’s value to the defined limit. If the iteration variable is already over the limit, the loop code may not be run at all. If the limit is reached, the loop runs a last time, and the code moves on.
• do – while: do something, while the end condition is met. The code after “do” will run at least once, but before the second loop, the “while” condition is evaluated. If it’s true, the loop runs again. If not, the program moves on.
• gosub – return: this statement is used to structure your code. You can have labeled sections of it, moved to the end of the script, and “call” those labeled sections with the gosub keyword followed by the section’s name. The “return” statement is used at the end of the section, telling the program to jump back to the next line after the “gosub” statement. This will be discussed in more detail later on (we LOVE structured code).
• call: very similar to gosub, but the code this command jumps to is not in the same file, but a separate library part. Usually these objects are not placeable on the floorplan, they contain a certain functionality only, and are called macros.

There are more, less frequently used flow control statements available in GDL.
To cover it all, check the GDL Manual’s Flow Control Statements section, or the very helpful Basic Technical Standards.