Functions

Arithmetical Functions

ABS

ABS (x)

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

CEIL

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

INT (x)

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

FRA

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).

ROUND_INT

ROUND_INT (x)

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

SGN (x)

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

SQR

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

ACS (x)

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

ASN

ASN (x)

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

ATN

ATN (x)

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

COS

COS (x)

Returns the cosine of x.

SIN

SIN (x)

Returns the sine of x.

TAN

TAN (x)

Returns the tangent of x.

PI

PI

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

Note

All return values are real.

Transcendental Functions

EXP

EXP (x)

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

LGT

LGT (x)

Returns the base 10 logarithm of x.

LOG

LOG (x)

Returns the natural logarithm of x.

Note

All returned values are real.

Boolean Functions

NOT

NOT (x)

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

Note

Parameter value should be integer.

Statistical Functions

MIN

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

Returns the smallest of an unlimited number of arguments.

MAX

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

Returns the largest of an unlimited number of arguments.

RND

RND (x)

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

Bit Functions

BITTEST

BITTEST (x, b)

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

BITSET

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

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

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

IND (MATERIAL, name_string)
IND (BUILDING_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

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

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.

Example:

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

 

String Functions

STR

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

 

Example:

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

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}

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).
'[1*j1+2*j2+4*j3]':
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.

 

Example:

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

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.
format:
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.

 

Example:

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
ELSE
    PRINT "ERROR"
ENDIF

 

STW

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.

 

Example:

https://gdl.graphisoft.com/wp-content/uploads/ac19-gdl/ExpFunct_stw.png
DEFINE STYLE "own" "Gabriola", 180000 / GLOB_SCALE, 1, 0
SET STYLE "own"
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

STRLEN (string_expression)

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

STRSTR

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.

case_insensitivity:
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

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.

 

Example:

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

STRTOUPPER (string_expression)

Returns a string converted to uppercase.

 

Example:

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

 

STRTOLOWER

STRTOLOWER (string_expression)

Returns a string converted to lowercase.

Example:

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