Numeric types – Precision

Before ARCHICAD 9, all numeric values were stored internally as floating point values which resulted in imprecise values.
This meant that integer values were – a little – imprecisely stored.
From ARCHICAD 9, integers – and hence GDL parameter types that are best described with integers – are correctly stored internally as integers.

GDL variables still don’t require type definition, the type is determined during the interpretation
from the value to be loaded into the variable.
The output of numeric operators now have a type. You should consult the GDL Manual for this information.

The programmer can safely compare integer types with the equality operator.
In fact, from ARCHICAD 9 warnings are now issued, if a programmer tries
to directly compare floating point values with integer values using the equality operator.
For equality-comparisons of floating-point numbers use a small epsilon value meaning the precision of the comparison.
For equality-comparisons of a floating-point number and an integer use the round_int function.

Below some sample methods of testing for equivalence between different numeric types are described:

iDummy = 1 * 2
if iDummy = 2 then
    ! valid comparison, it is true, these statements will be executed
    ...
endif

dDummy = 1.5 + 0.5
if dDummy = 2 then
    ! you never know if it is true, don't trust such comparisons
    ...
endif

dDummy = 1.1 * 2
if dDummy = 2.2 then
    ! you never know if it is true, don't trust such comparisons
    ...
endif

! EPS = 0.0001 -> in the master script
dDummy = 1.1 * 2
if abs (dDummy - 2.2) < EPS then
    ! valid comparison, it is true, these statements will be executed
    ...
endif

dDummy = 1.5 * 2
if round_int (dDummy) = 3 then
    ! valid comparison, it is true, these statements will be executed
    ...
endif

Decimal separators in functions

By default, most versions of STR function output uses the decimal separator defined by the operating system (“,” “.”, etc.). This makes the result unpredictable in some cases, which may cause problems if the result is the input for some other function (requests, for example), which will only work correctly with a specified “.” separator (in GDL, all numeric types use “.” as separator by default).
To make sure you get the desired decimal separator no-matter-what, use the “^” flag of the STR command in conversions, as explained here.

Trigonometry functions

While GDL scripting, you may need various trigonometry functions.
The following functions are directly available from GDL:
cos, sin, tan, acs, asn, atn.

All other functions can be easily derived as follows.

Secant Sec(X) = 1 / cos(X)
Cosecant Cosec(X) = 1 / sin(X)
Cotangent Cotan(X) = 1 / tan(X)
Inv. Sine Arcsin(X) = atn(X / Sqr(-X * X + 1))
Inv. Cosine Arccos(X) = atn(-X / sqr(-X * X + 1)) + 2 * atn(1)
Inv. Secant Arcsec(X) = atn(X / sqr(X * X - 1)) + sgn((X) -1) * 2*atn(1)
Inv. Cosecant Arccosec(X) = atn(X / sqr(X*X - 1)) + (sgn(X) - 1) * 2*atn(1)
Inv. Cotangent Arccotan(X) = atn(X) + 2 * atn(1)
Hyp. Sine HSin(X) = (exp(X) - exp(-X)) / 2
Hyp. Cosine HCos(X) = (exp(X) + exp(-X)) / 2
Hyp. Tangent HTan(X) = (exp(X) - exp(-X)) / (exp(X) + exp(-X))
Hyp. Secant HSec(X) = 2 / (exp(X) + exp(-X))
Hyp. Cosecant HCosec(X) = 2 / (exp(X) - exp(-X))
Hyp. Cotangent HCotan(X) = (exp(X) + exp(-X)) / (exp(X) - exp(-X))
Inv. Hyp. Sine HArcsin(X) = log(X + sqr(X * X + 1))
Inv. Hyp. Cosine HArccos(X) = log(X + sqr(X * X - 1))
Inv. Hyp. Tangent HArctan(X) = log((1 + X) / (1 - X)) / 2
Inv. Hyp. Secant HArcsec(X) = log((sqr(-X * X + 1) + 1) / X)
Inv. Hyp. Cosecant HArccosec(X) = log((sgn(X) * sqr(X * X + 1) +1) / X)
Inv. Hyp. Cotangent HArccotan(X) = log((X + 1) / (X - 1)) / 2

Note:

Logarithm to base N LogN(X) = log(X) / log(N)

GDL warnings

Like any other programming language, GDL has a syntax and logic to be followed. If there is a mistake in syntax, the programmer gets an error message.
If there is something confusing, or some unexpected thing happens when running the script, a GDL warning is sent out.

You can choose WHERE you want to send these messages in Options/Work Environment/Model Rebuild Options:

• Interrupt with error messages: a dialog pops up at every problem
• Write Report: the message is written in the Report window

You can choose WHAT you want to send out as message: this setting is available in the Library Developer menu, called “Check Library Part Scripts for Warnings”.
When enabled, not only errors, but warnings get reported as well according to the WHERE settings.

You can also choose WHEN you want to see warning messages. This can be set in the Library Developer menu as well, called “Always Send GDL Messages”.
Turning this feature on, every time GDL is executed, the warnings and errors get force-reported anyway. Leaving it off, the warning report contexts stay as usual.

Note, that using some combinations of the above switches can result in difficulties:
for example, having the “Always Send GDL Messages” and the “Interrupt with error messages” enabled together may prevent
the execution of something as “simple” as moving an editable hotspot, popping up dialogs all the time.

Pressing “Check script” in the library part editor, if there is a problem with your script using the current parameter settings,
you will always get a warning or error message popup window.
Using the PRINT command, or the GDL debugger may help a lot locating mistakes hard to find otherwise.

Note that the line numbers in the GDL warnings refer to the script which contains the problem.

Parsing errors must be handled with extra care.
These denote the first line in which the parsing gets impossible
but the actual problems may be some lines before.

Example

The interpreter detects the missing statement first at the
endif and stops there;
though the problem is obviously around line 4 where an
endif is really missing.

if condition1 then
    if condition2 then
        ! do something

    ! do something - BUT WE MISSED AN 'endif'
else
    ! a potentially long code block
endif

Here are some examples of the latest warning messages developed, with some explanation:

Hotspot and Hotline IDs

Purpose of hotspot/hotline/hotarc identification

In ARCHICAD the hotspot/hotline/hotarc identification is introduced to support
associative dimensioning in section.
Via this feature a dimensioning item can refer to any of a GDL object’s hotspots/hotlines.
It will become an important issue when the number of hotspots/hotlines changes
between the object’s different parameterization states.

Problem of old-school hotspots/hotlines

If the programmer doesn’t specify hotspot/hotline/hotarc IDs – or if he sets them to 0 –
ARCHICAD will assign continuously increasing ordinal numbers.
This solution is correct for static objects but causes dimensioning problems
when some hotspots/hotlines appear or hide between parameter set-ups.
Namely, the IDs will be rearranged so they will change,
and the associative dimensioning items – in section – will go astray.

Correct hotspot/hotline/hotarc scripting

For all these reasons you should assign fix IDs to the hotspots/hotlines in your objects.
This can be done by reserving wide intervals for the hotspots/hotlines of individually controllable features.

Let’s take a stair for example.
The bounding hotspots/hotlines may use the [1-100] interval,
the handrails may use the [200-299] interval and the risers the [1000- ) one.
This guarantees that the dimensioning of the handrails won’t be corrupted
if the number of risers changes or even if the bottom connection gets more complex
(using more hotspots/hotlines).

Editable hotspots

Since ARCHICAD 8 release you can use editable hotspots in your library parts.
The feature is described in Chapter 6, Graphical Editing Using Hotspots except for one possibility.

In some cases you may want to display a different parameter
from the edited one. See the example code below:

Editable hotspot example – Shoe / Shoe-rack

We want to have the size of a shoe in meters and in shoe sizes, too.
For that we create two parameters and connect them in the parameter script.
Naturally, the type of the explaining parameter can be different (e.g. text).
We emphasize that the edited parameter is footLength
all the way, footSizeEU – the displayed parameter – must be updated via the parameter script.

2D editing

Parameter script

DIM lengthValues[10]
DIM sizeValues[10]
for i = 1 to 10
    sizeValues[i] = i + 35
    lengthValues[i] = (i + 35) * 0.007
next i

values "footLength" lengthValues
values "footSizeEU" sizeValues

if GLOB_MODPAR_NAME = "footLength" then
    parameters footSizeEU = round_int (footLength / 0.007)
else
    if GLOB_MODPAR_NAME = "footSizeEU" or GLOB_MODPAR_NAME = "" then
        parameters footLength = footSizeEU * 0.007
    endif
endif

2D script

rect2 0, 0, footLength * 0.4, footLength   ! or a more realistic shoe model

hotspot2 0, 0,          1, footLength, 1 + 256, footSizeEU
hotspot2 0, footLength, 2, footLength, 2, footSizeEU
hotspot2 0, -0.1,       3, footLength, 3

GDL execution contexts

ARCHICAD lets the GDL object know about the context it is being displayed or used in.
The next global variables are used for this purpose:

• GLOB_VIEW_TYPE to determine the active view
• GLOB_PREVIEW_MODE to determine the active preview
• GLOB_FEEDBACK_MODE for editing context indication
• GLOB_SEO_TOOL_MODE for solid element operations context indication

For the possible values refer the the section called “General environment information” and the following list:

GLOB_VIEW_TYPE = 2 – 2D, floor plan

The model is displayed in the standard 2D floor plan.
In a 3D script this means that the model is projected to 2D
via the project2D command.
This is the main use of an object – this 2D model must be always correct and efficient.

If GLOB_FEEDBACK_MODE = 1 then
the model is displayed via feedback lines on the 2D floor plan during the hotspot editing of the object.
This model is drawn many times in a single second throughout the user interaction.
This implies that the model should represent the essential parts of the object only.
Note, that texts (generated by text2 command)
are not refreshed in feedback mode – since it would slow down the output.

GLOB_VIEW_TYPE = 3 – 3D view

The 3D model is displayed in the standard 3D model window or
it is the source of photorealistic rendering.
This view should omit internal details of the object, since these cannot be seen anyway.
This is the second most important use of an object – the 3D model must be always correct and efficient.
This target type demands correct outside look.

If GLOB_FEEDBACK_MODE = 1 then
the 3D model is displayed via feedback lines in the 3D model window
during the hotspot editing of the object.
This model is drawn many times in a single second throughout the
user interaction. This implies that the model should represent
the essential and visible parts of the object only.

GLOB_VIEW_TYPE = 4 – section or
GLOB_VIEW_TYPE = 5 – elevation

The 3D model is displayed in a section/elevation window.
For these views, the object should generate internal details
which are unnecessary for every other view type.

If GLOB_FEEDBACK_MODE = 1 then
the 3D model is displayed via feedback lines in a section/elevation window
during the hotspot editing of the object.
This model is drawn many times in a single second throughout the
user interaction. This implies that the model should represent
the essential and visible parts of the object only.

GLOB_VIEW_TYPE = 6 – 3D document

The 3D model is displayed in an axonometric window as a drawing.
This is used for documentation, dimensioning in 3D.

GLOB_VIEW_TYPE = 7 – detail drawing

The model is used in a detailed drawing window.
The model can be more detailed than in other views consequently.
The 2D and 3D models are not distinguished –
that information can be derived from the script type.

GLOB_VIEW_TYPE = 8 – layout

The model is used in a layout window, with its print display.
The model should show its printing look.
The 2D and 3D models are not distinguished –
that information can be derived from the script type.

If GLOB_FEEDBACK_MODE = 1 then
the model is displayed via feedback lines in a layout window
during the hotspot editing of the object.
This model is drawn many times in a single second throughout the
user interaction. This implies that the model should represent
the essential and visible parts of the object only.

GLOB_VIEW_TYPE = 9 – calculation and/or
GLOB_PREVIEW_MODE = 2 – listing

The 3D model is used for surface and volume calculation by the listing engine.
This context is the proper place to do some model alterations for listing.
E.g. you can generate extra bodies to raise the surface to be painted
and the amount of required paint. Use the combination of the 2 globals for the desired result in calculation and listing model generation.

GLOB_PREVIEW_MODE = 1 – settings dialog

The model is displayed in the Object Settings Dialog’s preview box.
The 2D and 3D models are not distinguished –
that information can be derived from the script type.
The object should provide a fast, rough preview of the model
considering the limited size of the preview.

GLOB_SEO_TOOL_MODE = 1 generating as an operator for Solid Element Operations

The generated 3D model is used as a parameter for solid (CSG) operations.
This can be useful, when the object’s space demand is larger than the object itself.
E.g. when you subtract a stair from a slab, you’d expect that the stair cuts a hole
for the walking people, too.
To achieve this, in this context the stair should generate a model containing
that walking space.

Communicating values with ARCHICAD

There are two directions of parameter value flow between ARCHICAD and the library part.
The first direction means that the ARCHICAD informs the library part
about an attribute of its context
(e.g. the drawing scale of the project or the thickness of the wall a window is placed into).
The second direction is when the library part asserts something about itself
which instructs ARCHICAD to change that something in the direct context of the object
(e.g. the depth a wall end cuts in the wall).

Information flow from ARCHICAD

There are 3 channels of information coming from ARCHICAD:
global variables, parameters with predefined names and directly called values.

Global variables

Global variables are filled by ARCHICAD according to the current project settings
and to the placement context of the object. Note, that not all globals are filled in every context and view.

For the complete list of global variables and their relevant restrictions in certain scripts, consult the section called “Global Variables”.

Fix named optional parameters

The newer method of ARCHICAD for providing information is the method of fixed named optional parameters.
If a given library part has a parameter with a name and type matching
any optional parameter, ARCHICAD sets its value according to its function.

Refer the section called “Parameters set by ” in the section called “Fix named optional parameters”
to learn the ARCHICAD defined library part parameters.

Requests and Application Queries

For rarely used, special information, library parts use Request calls or Application Queries in their scripts.
Unlike global variables, these only give a return value when the containing actual scripts runs.
Note, that most requests ans queries should be avoided in parameter script, or master script run as parameter script.
If used in those scripts, the validity of the returned value or the function can not be guaranteed.

Refer the section called “REQUEST Options” and the section called “Application Query Options” to learn more about options, parameter script compatibility and syntax.

Information coming from the library part

ARCHICAD needs certain information to use the library parts correctly. This information depends on the
function and the context, and is stored in the built-in ARCHICAD subtypes as parameters with predefined
name and function. In addition to built-in ARCHICAD subtypes some functions might need fixed named optional parameters.

Consult the fix parameters of built-in subtypes and
the section called “Parameters read by ” in the section called “Fix named optional parameters”
to get a view of the possibilities.

Model View Options, Library Global

The display of library parts in the plan may depend on the current view.

Internal Model View Options

The view’s internal settings are available via GDL global variables (e.g. GLOB_SCALE, GLOB_STRUCTURE_DISPLAY) and
request options (e.g. “window_show_dim”, “door_show_dim”, “floor_plan_option”, “view_rotangle”).

Library Global View Options

From ARCHICAD 13 on, you can define view options from your library.
These options are stored into each view and they are returned accordingly.

The following properties/parameters/options should be stored in view dependent library globals:

• showing/hiding opening lines
• showing/hiding minimal spaces
• pen and other view attributes which shouldn’t be changed individually for the sake of uniformity (e.g. minimal spaces)
• showing/hiding specific accessory elements (e.g. knobs, handles)
• setting 2D symbol types for object groups

Things which should NOT be stored in view dependent library globals:
general values for the whole project, general values for the whole country,
values which may be required to be set individually for objects.

To insert a tab page into the MVO dialog, you have to make a library part
which is derived from the Library Global Settings (GUID: {709CC5CC-6817-4C56-A74B-BED99DDB5FFA}) subtype.
This object must contain the desired global options as parameters and it must have a user interface definition for the tab page.
The width of the UI should be set to 600 pixels to match the existing panels. The height of the UI is freely definable.
It may have a parameter script for connecting parameters or user interface elements.

The LIBRARYGLOBAL command can be used in your placeable elements to query
values of your own library global settings object depending on the current view settings.