Arithmetical Functions


ABS (x)

Returns the absolute value of x (integer if x integer, real otherwise).


CEIL (x)

Returns the smallest integral value that is not smaller than x (always integer). (e.g., CEIL(1.23) = 2; CEIL (-1.9) = -1).


INT (x)

Returns the integral part of x (always integer). (e.g., INT(1.23) = 1, INT(-1.23) = -2).


FRA (x)

Returns the fractional part of x (integer 0 if x integer, real otherwise). (e.g., FRA(1.23) = 0.23, FRA(-1.23) = 0.77).



Returns the rounded integer part of x. The ‘i = ROUND_INT (x)’ expression is equivalent with the following script:

IF x < 0.0 THEN i = INT (x – 0.5) ELSE i = INT (x + 0.5)


SGN (x)

Returns +1 integer if x positive, -1 integer if x negative, otherwise 0 integer.


SQR (x)

Returns the square root of x (always real).

Circular Functions

These functions use degrees for arguments (COS, SIN, TAN) and for return values (ACS, ASN, ATN).


ACS (x)

Returns the arc cosine of x. (-1.0 <= x <= 1.0; 0°
<= ACS(x) <= 180°).


ASN (x)

Returns the arc sine of x. (-1.0 <= x <= 1.0; -90°
<= ASN(x) <= 90°).


ATN (x)

Returns the arc tangent of x. (-90° <= ATN(x) <= 90°).


COS (x)

Returns the cosine of x.


SIN (x)

Returns the sine of x.


TAN (x)

Returns the tangent of x.



Returns Ludolph’s constant. (p = 3.1415926…).


All return values are real.

Transcendental Functions


EXP (x)

Returns the x th power of e (e = 2.7182818).


LGT (x)

Returns the base 10 logarithm of x.


LOG (x)

Returns the natural logarithm of x.


All returned values are real.

Boolean Functions


NOT (x)

Returns false (=0 integer) if x is true (<>0), and true (=1 integer) if x is false (=0)(logical negation).


Parameter value should be integer.

Statistical Functions


MIN (x1, x2, ..., xn)

Returns the smallest of an unlimited number of arguments.


MAX (x1, x2, ..., xn)

Returns the largest of an unlimited number of arguments.


RND (x)

Returns a random value between 0.0 and x (x > 0.0) always real.

Bit Functions


BITTEST (x, b)

Returns 1 if the b bit of x is set, 0 otherwise.


BITSET (x, b [, expr])

expr can be 0 or different, the default value is 1.
Sets the b bit of x to 1 or 0 depending on the value of the specified expression, and returns the result.
Parameter value should be integer, returned value is integer.

Special Functions

Special functions (besides global variables) can be used in the script to communicate with the executing program.
They either ask the current state and different preferences settings of the program, or refer to the current environment of the library part.
Request calls can also be used to communicate with GDL extensions.


REQ (parameter_string)

Asks the current state of the program. Its parameter – the question – is a string. The GDL interpreter answers with a numeric value.
If it does not understand the question, the answer is negative.

parameter_string: question string, one of the following:
"GDL_version": version number of the GDL compiler/interpreter. Warning: it is not the same as the version.
"Program": code of the program (e.g., 1: ),
"Serial_number": the serial number of the keyplug,
"Model_size": size of the current 3D data structure in bytes,
"Red_of_material name"
"Green_of_material name"
"Blue_of_material name": Defines the given material’s color components in RGB values between 0 and 1,
"Red_of_pen index"
"Green_of_pen index"
"Blue_of_pen index": Defines the given pen’s color components in RGB values between 0 and 1,
"Pen_of_RGB r g b":
Defines the index of the pen closest to the given color.
The r, g and b constants’ values are between 0 and 1.


REQUEST (question_name, name | index, variable1 [, variable2, ...])

The first parameter represents the question string while the second represents the object of the question (if it exists)
and can be of either string or numeric type (for example, the question can be “Rgb_of_material” and its object the material’s name,
or “Rgb_of_pen” and its object the index of the pen). The other parameters are variable names in which the return values (the answers) are stored.

The return value of the requests is always the number of successfully retrieved values (integer),
while the type of the retrieved values is defined by each request in part.
In the case of a badly formulated question or a nonexistent name, the return value will be 0.

  • REQUEST – default request, with 1 input parameter of string or numeric type
  • REQUEST{2} – 2 input parameters: string or numeric, string type
  • REQUEST{3} – 2 input parameters: string, string or numeric array type
  • REQUEST{4} – 3 input parameters: string or numeric, numeric, string type. Compatibility: introduced in ARCHICAD 21.

ARCHICAD identifies the order and number of the input parameters by either the version of the command, or the exact name (as string constant) of the request option.
Current accepted variations:

For the list of available options see the section called “REQUEST Options”.


IND (MATERIAL, name_string)
IND (FILL, name_string)
IND (LINE_TYPE, name_string)
IND (STYLE, name_string)
IND (TEXTURE, name_string)
IND (PROFILE_ATTR, name_string, index)

This function returns the current index of the material, building material, fill, line type or style, texture or profile attribute.
The main use of the resulting number is to transfer it to a macro that requires the same attribute as the calling macro.

The functions return an attribute index (integer) value.
The result is negative for inline definitions (inside the script or from Master_GDL file)
and positive for global definitions (from the project attributes).

See also the section called “Inline Attribute Definition”.


APPLICATION_QUERY (extension_name, parameter_string, variable1, variable2, ...)

GDL allows a way for the individual applications to provide specific request functions in their context.
These query options aren’t defined in the GDL syntax; consult the GDL developer documentation of the given application for specific options.
See also the section called “Application Query Options”.


LIBRARYGLOBAL (object_name, parameter, value)

Fills value with the current model view option parameter value of the library global object defined by object_name if available.
A library global setting is available if the global object is currently loaded in the library,
or was loaded earlier and its setting was saved in the current model view option combination.
Visible placed objects whose 2d or 3d scripts contain LIBRARYGLOBAL commands are refreshed when the library global object’s parameters change at Model View Options. Parameter and migration scripts should not use LIBRARYGLOBAL values, the current view should not have any effect on other views.

Returns 1 if successful, 0 otherwise.

object_name: name of library global object. Must be a string constant.
Warning: If string variables or parameters are used as object names, then the 2d and 3d view of objects querying
this library global object will not refresh automatically.
parameter: name of requested parameter.
value: filled with the requested parameter value.


success = LIBRARYGLOBAL ("MyGlobalOptions", "detLevel2D", det)
if success > 0 then
    text2 0, 0, det
    text2 0, 0, "Not available"


String Functions


STR (numeric_expression, length, fractions)

This form of the function creates a string from the current value of the numeric expression.
The minimum number for numerical characters in the string is length, while fractions represents the numbers following the floating point.
If the converted value has more than length characters, it is expanded as required.
If it has fewer characters, it is padded on the left (length > 0) or on the right (length < 0).

length >= -100, length <= 100
fractions <= 20, fractions < length



a = 4.5
b = 2.345
TEXT2 0, 2, STR(a, 8, 2)   ! 4.50
TEXT2 0, 1, STR(b, 8, 2)   ! 2.34
TEXT2 0, 0, STR(a*b, 8, 2) ! 10.55


STR (format_string, numeric_expression)

This form is deprecated, use STR{2}.

In this form the format_string can either be a variable or a constant.
If the format is empty, it is interpreted as meters, with an accuracy of three decimals (displaying 0s).
Using extra accuracy flags can give incorrect results.


STR{2} (format_string, numeric_expression [, extra_accuracy_string])

This function creates a formatted string representation of the current value of the numeric expression.
Formatting is specified by format_string which can either be a variable or a string literal.
If the format is empty, the output is formatted as meters, with an accuracy of three decimals (displaying 0s).
If the extra accuracy flags are set in the format_string, the STR{2} function will return the corresponding extra accuracy string in the 3rd parameter.

format_string: “%[0 or more flags][field_width][.precision] conv_spec”
flags: (for m, mm, cm, dm, e, df, di, sqm, sqcm, sqf, sqi, dd, gr, rad, cum, l, cucm, cumm, cuf, cui, cuy, gal):
(none): right justify (default),
-: left justify,
+: explicit plus sign,
(space): in place of a + sign,
'*0': extra accuracy Off (default),
'*1': extra accuracy .5,
'*2': extra accuracy .25,
'*3': extra accuracy .1,
'*4': extra accuracy .01,
'*5': rounding to .5 within displayed decimal range, no returned extra accuracy string, (used for area calculations),
'*6': rounding to .25 within displayed decimal range, no returned extra accuracy string, (used for area calculations),
'*7': Compatibility: introduced in ARCHICAD 20.
fills the fractional part of numeric_expression into the extra_accuracy_string in case of fi or ffi, while the returned expression of the function does not contain the fractional parts,
'#': don’t display 0s (for m, mm, cm, dm, ffi, fdi, fi, df, di, sqm, sqcm, sqf, sqi, dd, fr, rad, cum, l, cucm, cumm, cuf, cui, cuy, gal),
'0': display 0 inches (for ffi, fdi, fi),
'~': hide 0 decimals (effective only if the ‘#’ flag is not specified) (for m, mm, cm, dm, fdi, df, di, sqm, sqcm, sqf, sqi, dd, fr, rad, cum, l, cucm, cumm, cuf, cui, cuy, gal),
do not change decimal separator and digit grouping characters Compatibility: introduced in ARCHICAD 8
(if not specified, these characters will be replaced as set in the current system).
display 0 inches before fractions, effective if the ‘0’ flag is not specified (for ffi, fdi, fi)
j1: display 0 inches before fractions (0 3/4″), effective when value is smaller than 1 foot and not displaying 0 foot (the ‘#’ flag is specified)
j2: display 0 whole inches after feet (1′-0″), effective when value is at least 1 foot
j3: display 0 inches before fractions (1′-0 3/4″), effective when value is at least 1 foot
field_width: unsigned decimal integer, the minimum number of characters to generate.
precision: unsigned decimal integer, the number of fraction digits to generate.
conv_spec: (conversion specifier):
e: exponential format (meter),
m: meters,
mm: millimeters,
cm: centimeters,
dm: decimeters, Compatibility: decimeters introduced in ARCHICAD 22.
ffi: feet & fractional inches,
fdi: feet & decimal inches,
df: decimal feet,
fi: fractional inches,
di: decimal inches,
pt: points,

for areas:

sqm: square meters,
sqcm: square centimeters,
sqmm: square millimeters,
sqf: square feet,
sqi: square inches,

for angles:

dd: decimal degrees,
dms: degrees, minutes, seconds,
gr: grads,
rad: radians,
surv: surveyors unit,

for volumes:

cum: cubic meters,
l: liters,
cucm: cubic centimeters,
cumm: cubic millimeters,
cuf: cubic feet,
cui: cubic inches,
cuy: cubic yards,
gal: gallons.



nr = 0.345678
TEXT2 0, 23, STR ("%m", nr)      !0.346
TEXT2 0, 22, STR ("%#10.2m", nr) !35
TEXT2 0, 21, STR ("%.4cm", nr)   !34.5678
TEXT2 0, 20, STR ("%12.4cm", nr) !  34.5678
TEXT2 0, 19, STR ("%.6mm", nr)   !345.678000
TEXT2 0, 18, STR ("%+15e", nr)   !+3.456780e-01
TEXT2 0, 17, STR ("%ffi", nr)    !1'-2"
TEXT2 0, 16, STR ("%0.16ffi", nr) !1'-1 5/8"
TEXT2 0, 15, STR ("% .3fdi", nr) ! 1'-1.609"
TEXT2 0, 14, STR ("% -10.4df", nr) ! 1.1341'
TEXT2 0, 13, STR ("%0.64fi", nr) !13 39/64"
TEXT2 0, 12, STR ("%+12.4di", nr)!+13.6094"
TEXT2 0, 11, STR ("%#.3sqm", nr) !346
TEXT2 0, 10, STR ("%+sqcm", nr)  !+3,456.78
TEXT2 0,  9, STR ("% .2sqmm", nr)! 345,678.00
TEXT2 0,  8, STR ("%-12sqf", nr) !3.72
TEXT2 0,  7, STR ("%10sqi", nr)  ! 535.80
TEXT2 0,  6, STR ("%.2pt", nr)   !0.35
alpha = 88.657
TEXT2 0,  5, STR ("%+10.3dd", alpha) !+88.657°
TEXT2 0,  4, STR ("%.1dms", alpha)   !88°39'
TEXT2 0,  3, STR ("%.2dms", alpha)   !88°39'25"
TEXT2 0,  2, STR ("%10.4gr", alpha)  ! 98.5078G
TEXT2 0,  1, STR ("%rad", alpha)     !1.55R
TEXT2 0,  0, STR ("%.2surv", alpha)  !N 1°20'35" E

nr  = 0'-0 3/4"
TEXT2 0, -1, STR ("%#[1].16ffi", nr) !0 3/4"
nr = 1'-0"
TEXT2 0, -2, STR ("%[2].16ffi", nr) !1'-0"
nr = 1'-0 3/4"
TEXT2 0, -3, STR ("%[4].16ffi", nr) !1'-0 3/4"

! use system decimal character ',', default
nr = 12.345678
TEXT2 0, -2, STR ("%8.6m", nr) ! 12,345678
! ignore system decimal character ','
TEXT2 0, -2, STR ("%^8.6m", nr) ! 12.345678
nr = 0.34278
TEXT2 0, 0, STR ("%*5 .4m", nr)		!0.3430

! split to integral and fractional parts
extra_accuracy_string = ""
nr  = 1'-0 3/4"

TEXT2 0, -3, STR{2}("%*7.16ffi", nr,  extra_accuracy_string)	!1'-
TEXT2 0, -4, extra_accuracy_string				!3/4"



SPLIT (string, format, variable1 [, variable2, ..., variablen])

Splits the string parameter according to the format in one or more numeric or string parts. The split process stops when the first non-matching part is encountered. Returns the number of successfully read values (integer).

string: the string to be split.
any combination of constant strings, %s, %n and %^n -s.
Parts in the string must fit the constant strings, %s denotes any string value delimited by spaces or tabs, while %n or %^n denotes any numeric value. If the ‘^’ flag is present, current system settings for decimal separator and digit grouping characters are taken into consideration when matching the actual numerical value.
variablei: names of the variables to store the split string parts.



ss = "3 pieces 2x5 beam"
n = SPLIT (ss, "%n pieces %nx%n %s", num, ss1, size1, ss2, size2, name)
IF n = 6 THEN
    PRINT num, ss1, size1, ss2, size2, name ! 3 pieces 2 x 5 beam



STW (string_expression)

Returns the (real) width of the string in millimeters displayed in the current style.
The width in meters, at current scale, is STW (string_expression) / 1000 * GLOB_SCALE.


DEFINE STYLE "own" "Gabriola", 180000 / GLOB_SCALE, 1, 0
string = "abcd"
width = STW (string) / 1000 * GLOB_SCALE
n = REQUEST ("Height_of_style", "own", height)
height = height / 1000 * GLOB_SCALE
TEXT2 0,0, string
RECT2 0,0, width, -height



STRLEN (string_expression)

Returns the (integer) length of the string (the number of characters)


STRSTR (string_expression1, string_expression2[, case_insensitivity])

Returns the (integer) position of the first appearance of the second string in the first string.
If the first string doesn’t contain the second one, the function returns 0.
In case string_expression2 is an empty string, the function returns 1.

0 or not set: Case sensitive
1: Case insensitive


Example 1:

szFormat = ""
n = REQUEST ("Linear_dimension", "", szFormat)
unit = ""
IF STRSTR (szFormat, "m")  > 0 THEN unit = "m"
IF STRSTR (szFormat, "mm") > 0 THEN unit = "mm"
IF STRSTR (szFormat, "cm") > 0 THEN unit = "cm"
IF STRSTR (szFormat, "dm") > 0 THEN unit = "dm"
TEXT2 0, 0, STR (szFormat, a) + " " + unit !1.00 m


Example 2:

STRSTR ("abcdefg", "BCdEf") = 0
STRSTR ("abcdefg", "BCdEf", 0) = 0
STRSTR ("abcdefg", "BCdEf", 1) = 2



STRSUB (string_expression, start_position, characters_number)

Returns a substring of the string parameter that begins at the position given by the start_position parameter and its length is characters_number characters.



string = "Flowers.jpeg"
len = STRLEN (string)
iDotPos = STRSTR (string, ".")
TEXT2 0, -1, STRSUB (string, 1, iDotPos - 1) !Flowers
TEXT2 0, -2, STRSUB (string, len - 4, 5)     !.jpeg



STRTOUPPER (string_expression)

Returns a string converted to uppercase.



_oldString = "flower"
_newString = STRTOUPPER (_oldString)    ! _newString will be "FLOWER"



STRTOLOWER (string_expression)

Returns a string converted to lowercase.


_oldString = "FLOWER"
_newString = STRTOLOWER (_oldString)    ! _newString will be "flower"